{"openapi":"3.0.0","info":{"title":"Afineo Webservices API — projects","description":"Module `projects` of the Afineo API v3 (4 endpoints).\n\nManage project trees within a library: create projects, list them, and retrieve project details. Projects are contextual workspaces where assets can be organized independently from the main repository.\n\nFull specification: https://api.afineo.io/openapi.json","version":"3.0.0","contact":{"name":"Afineo Solutions","url":"https://www.afineo.com"},"x-logo":{"url":"./logo.png","altText":"Afineo - Powerful Data, Powerful People"}},"servers":[{"url":"https://{instance}.afineo.io","description":"Afineo instance","variables":{"instance":{"description":"Your Afineo instance name","default":"client"}}}],"tags":[{"name":"projects","description":"Manage project trees within a library: create projects, list them, and retrieve project details. Projects are contextual workspaces where assets can be organized independently from the main repository."}],"paths":{"/api/v3/projects/create/":{"post":{"tags":["projects"],"summary":"Create new project","description":"## Purpose\n\nCreates a new project under a parent workspace with specified type and configuration.\n\n## Project Types\n\n- `directory_project`: Directory-based project\n- `document_holder`: Document holder for publications\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Project creation response","content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Success Response","properties":{"status_code":{"type":"integer","example":1,"description":"Status code (1 = success)"},"status_message":{"type":"string","example":"","description":"Status message (empty string for success)"},"result":{"type":"object","properties":{"id":{"type":"integer","example":956408,"description":"Node ID of the created project"},"node_id":{"type":"integer","example":956408,"description":"Node ID of the created project"},"asset_id":{"type":"integer","example":24923,"description":"Asset ID of the created project"}},"required":["id","node_id","asset_id"],"description":"Created project information - simplified structure"}},"required":["status_code","status_message","result"]},{"type":"object","title":"Error Response","properties":{"status_code":{"type":"integer","enum":[2,3],"example":2,"description":"Status code (2 = validation error/business logic error, 3 = system error)"},"status_message":{"type":"string","enum":["The parameter \"template_id\" must be a valid integer","There is an issue with the data sent in the parameter \"versions_id\" : one of the items in the array is not a valid integer.","There is an issue with the data sent in the parameter \"start_date\" : the value is invalid, expected ISO 8601 date format (2025-11-06T10:00:00Z or 2025-11-06T10:00:00Z+02:00).","There is an issue with the data sent in the parameter \"end_date\" : the value is invalid, expected ISO 8601 date format (2025-11-06T10:00:00Z or 2025-11-06T10:00:00Z+02:00).","Parent workspace does not exist","Project could not be created"],"example":"The parameter \"template_id\" must be a valid integer","description":"Specific error message describing the validation or business logic failure"},"result":{"type":"array","items":{"type":"object"},"example":[],"description":"Empty array on error"}},"required":["status_code","status_message","result"]}]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"class_id":{"type":"integer","description":"Library ID. Use POST /api/v3/administration/classes/list to get available libraries.","example":4},"workspace_node_id":{"type":"integer","description":"Workspace node ID (project group). Use POST /api/v3/projects/list with class_id to find workspace nodes (entries with project_type=\"workspace\").","example":6726},"label":{"type":"string","description":"Label/name for the new project. Must be unique unless disabled.","example":"Christmas 2025"},"project_type":{"type":"string","description":"Project type: \"directory_project\" (directory-based) or \"document_holder\" (document holder).","enum":["directory_project","document_holder"],"example":"document_holder"},"template_id":{"type":"integer","description":"Project template ID. Optional. Templates are pre-configured by administrators. Omit to create a blank project with default settings.","example":25},"default_version_id":{"type":"integer","description":"Default version ID for the project. Use POST /api/v3/administration/versions/list with class_id to get available versions.","example":1},"versions_id":{"type":"array","description":"List of version IDs available for the project. Use POST /api/v3/administration/versions/list with class_id to get available versions.","example":[1,2,3],"items":{"type":"integer"}},"tree_default_display":{"type":"string","description":"Default tree to display : \"dynamic\" or \"virtual\"","enum":["dynamic","virtual"],"example":"virtual"},"start_date":{"type":"string","description":"Project start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z).","example":"2025-01-01T00:00:00Z"},"end_date":{"type":"string","description":"Project end date in ISO 8601 format (e.g., 2025-12-31T23:59:59Z).","example":"2025-12-31T23:59:59Z"},"start_workflow":{"type":"boolean","description":"If true, automatically starts the project workflow after creation. Requires the project to be created from a template containing workflows (template_id must be set and the template must define workflows). Default: false (workflow must be started manually).","example":true}},"required":["class_id","workspace_node_id","label","project_type"]}}}}}},"/api/v3/projects/full/":{"post":{"tags":["projects"],"summary":"Get all projects with full details","description":"## Purpose\n\nReturns all workspaces and projects for a class with complete configuration (dates, versions, groups, permissions).\n\n## Project Types\n\n- `directory_project`: Directory-based project\n- `document_holder`: Document holder project\n- `publication`: Publication project\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Projects list response","content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Success Response","properties":{"status_code":{"type":"integer","example":1,"description":"Status code (1 = success)"},"status_message":{"type":"string","example":"","description":"Status message"},"result":{"type":"array","items":{"type":"object","properties":{"workspace":{"type":"object","properties":{"id":{"type":"integer","example":1,"description":"Workspace node ID"},"node_id":{"type":"integer","example":1982,"description":"Workspace node ID"},"start_date":{"type":"string","example":"2016-02-17T00:00:00+01:00","description":"Start date"},"end_date":{"type":"string","example":"2016-02-17T00:00:00+01:00","description":"End date"},"label":{"type":"string","example":"Workspace 1","description":"Workspace label"},"class_id":{"type":"integer","example":4,"description":"Class ID"}},"required":["id","node_id","start_date","end_date","label","class_id"],"description":"Workspace information"},"projects":{"type":"object","properties":{"id":{"type":"integer","example":213855,"description":"Project node ID"},"node_id":{"type":"integer","example":213855,"description":"Project node ID"},"class_id":{"type":"integer","example":4,"description":"Associated class ID"},"asset_id":{"type":"integer","example":285279,"description":"Associated asset ID"},"label":{"type":"string","example":"VDM PRINT","description":"Project label/name"},"active":{"type":"boolean","example":true,"description":"Project active status"},"project_type":{"type":"string","example":"publication","description":"Project type"},"project_type_description":{"type":"string","example":"Publication - Brief","description":"Human-readable project type"},"start_date":{"type":"string","example":"2019-03-28T00:00:00+01:00","description":"Project start date (ISO 8601 format)"},"end_date":{"type":"string","example":"2019-04-28T00:00:00Z","description":"Project end date (ISO 8601 format)"},"manager_user_id":{"type":"integer","example":1,"description":"Manager user ID"},"manager_user_label":{"type":"string","example":"user@afineo.com","description":"Manager user label"},"default_version":{"type":"integer","example":1,"description":"Default version ID"},"all_version":{"type":"array","nullable":true,"items":{"type":"integer"},"example":[1],"description":"Available versions for the project"},"display_all_version":{"type":"boolean","example":false,"description":"Whether to display all versions"},"generate_previews_for_publication":{"type":"boolean","example":true,"description":"Whether to generate publication previews"},"default_display":{"type":"string","example":"virtual","description":"Default display mode"},"easycatalog_export_mapping_id":{"type":"integer","example":1782,"description":"EasyCatalog export mapping ID"},"new_version_of_project_id":{"type":"integer","nullable":true,"example":null,"description":"New version of project ID (null if not applicable)"},"groups":{"type":"object","nullable":true,"properties":{"id":{"type":"integer","example":10,"description":"Group ID"},"workflow_id":{"type":"integer","example":0,"description":"Workflow ID"},"status":{"type":"array","items":{"type":"object"},"example":[{"id":1639,"label":"User label 1"},{"id":1640,"label":"User label 2"}],"description":"Status array"},"status_config":{"oneOf":[{"type":"object","additionalProperties":{"type":"boolean"}},{"type":"array","items":{"type":"object"}}],"example":{"option_key":true,"another_option":false},"description":"Status configuration options (object with boolean properties, or empty array when not configured)"}},"description":"Project groups configuration"},"tab_options":{"type":"object","nullable":true,"example":{"without_brief":0},"description":"Tab options configuration"},"lca":{"type":"array","items":{"type":"object"},"example":[],"description":"LCA array"},"icon":{"type":"string","example":"<span style=';padding: 0;padding-bottom: 3px;'><span><i class='fa-solid fa-book img-type' style='font-size: 16px;color:#004196; '></i></span></span>","description":"Project icon HTML"},"path":{"type":"string","example":"0/1978/1982/213855","description":"Project path in hierarchy"}},"required":["id","node_id","class_id","asset_id","label","active","project_type","project_type_description","start_date","end_date","manager_user_id","manager_user_label","default_version","display_all_version","generate_previews_for_publication","default_display","easycatalog_export_mapping_id","icon","path"],"description":"Project information"}}},"description":"List of workspaces and its projects for the specified class"}},"required":["status_code","status_message","result"]},{"type":"object","title":"Error Response","properties":{"status_code":{"type":"integer","example":3,"description":"Status code (3 = error, 0 = class not found)"},"status_message":{"type":"string","example":"Class not found or access denied","description":"Error message"},"result":{"type":"array","items":{"type":"object"},"example":[],"description":"Empty array on error"}},"required":["status_code","status_message","result"]}]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"class_id":{"type":"integer","description":"Library ID. Use POST /api/v3/administration/classes/list to get available libraries.","example":4},"include_inactive":{"type":"boolean","description":"Include inactive projects. By default, inactive projects are excluded.","example":true}},"required":["class_id"]}}}}}},"/api/v3/projects/get/":{"post":{"tags":["projects"],"summary":"Get project details","description":"## Purpose\n\nReturns complete project configuration including type, dates, versions, groups, display settings, and permissions.\n\n## When to Use\n\n- Use after POST /api/v3/projects/list to get full details of a specific project\n- Check `project_type` to determine capabilities: \"directory_project\" (standard) or \"document_holder\" (publication)\n- Check `all_version` and `default_version` for version configuration\n- Check `groups` for workflow step configurations and contributor assignments\n- The `node_id` is used as `project_node_id` in other endpoints (recordAsset, publishing, workflows, etc.)\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Project information response","content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Success Response","properties":{"status_code":{"type":"integer","example":1,"description":"Status code (1 = success)"},"status_message":{"type":"string","example":"","description":"Status message (empty string for success)"},"result":{"type":"object","properties":{"id":{"type":"integer","example":395204,"description":"Project node ID"},"node_id":{"type":"integer","example":395204,"description":"Project node ID"},"class_id":{"type":"integer","example":4,"description":"Associated class ID"},"asset_id":{"type":"integer","example":285279,"description":"Associated asset ID"},"label":{"type":"string","example":"VDM PRINT","description":"Project label/name"},"active":{"type":"boolean","example":true,"description":"Project active status"},"project_type":{"type":"string","example":"publication","description":"Project type"},"project_type_description":{"type":"string","example":"Publication","description":"Human-readable project type"},"start_date":{"type":"string","example":"2019-03-28T00:00:00+01:00","description":"Project start date (ISO 8601 format)"},"end_date":{"type":"string","example":"2019-04-28T00:00:00Z","description":"Project end date (ISO 8601 format)"},"manager_user_id":{"type":"integer","example":1,"description":"Manager user ID"},"manager_user_label":{"type":"string","example":"user@afineo.com","description":"Manager user label"},"default_version":{"type":"integer","example":1,"description":"Default version ID"},"all_version":{"type":"array","nullable":true,"items":{"type":"integer"},"example":[1],"description":"Available versions for the project"},"display_all_version":{"type":"boolean","example":false,"description":"Whether to display all versions"},"generate_previews_for_publication":{"type":"boolean","example":true,"description":"Whether to generate publication previews"},"default_display":{"type":"string","example":"virtual","description":"Default display mode"},"easycatalog_export_mapping_id":{"type":"integer","example":1782,"description":"EasyCatalog export mapping ID"},"new_version_of_project_id":{"type":"integer","nullable":true,"example":null,"description":"New version of project ID (null if not applicable)"},"groups":{"type":"object","nullable":true,"properties":{"id":{"type":"integer","example":10,"description":"Group ID"},"workflow_id":{"type":"integer","example":0,"description":"Workflow ID"},"status":{"type":"array","items":{"type":"object"},"example":[{"id":1639,"label":"User label 1"},{"id":1640,"label":"User label 2"}],"description":"Status array"},"status_config":{"oneOf":[{"type":"object","additionalProperties":{"type":"boolean"}},{"type":"array","items":{"type":"object"}}],"example":{"option_key":true,"another_option":false},"description":"Status configuration options (object with boolean properties, or empty array when not configured)"}},"description":"Project groups configuration"},"tab_options":{"type":"object","nullable":true,"example":{"without_brief":0},"description":"Tab options configuration"},"lca":{"type":"array","items":{"type":"object"},"example":[],"description":"LCA array"},"icon":{"type":"string","example":"<span style=';padding: 0;padding-bottom: 3px;'><span><i class='fa-solid fa-book img-type' style='font-size: 16px;color:#004196; '></i></span></span>","description":"Project icon HTML"},"path":{"type":"string","example":"0/1978/1982/213855","description":"Project path in hierarchy"}},"required":["id","node_id","class_id","asset_id","label","active","project_type","project_type_description","start_date","end_date","manager_user_id","manager_user_label","default_version","display_all_version","generate_previews_for_publication","default_display","easycatalog_export_mapping_id","icon","path"],"description":"Complete project information"}},"required":["status_code","status_message","result"]},{"type":"object","title":"Error Response","properties":{"status_code":{"type":"integer","example":3,"description":"Status code (3 = error, 0 = project not found)"},"status_message":{"type":"string","example":"Project not found or access denied","description":"Error message"},"result":{"type":"array","items":{"type":"object"},"example":[],"description":"Empty array on error"}},"required":["status_code","status_message","result"]}]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Project node ID. Use POST /api/v3/projects/list with class_id to get available projects.","example":54}},"required":["id"]}}}}}},"/api/v3/projects/list/":{"post":{"tags":["projects"],"summary":"List projects (simplified)","description":"## Purpose\n\nReturns simplified project list grouped by workspace for a library.\n\n## Afineo Project Hierarchy\n\n- **Library** (class): Top-level container for assets\n- **Workspace**: Organizational group within a library (e.g., \"Season 2025\", \"Region Europe\")\n- **Project**: Working space within a workspace where assets are managed with specific configurations (versions, workflows, permissions)\n\n## When to Use\n\n- Use to discover projects and their workspace hierarchy for a library\n- Use POST /api/v3/projects/get with a project node_id to get complete project configuration (versions, groups, permissions)\n- The `node_id` returned is used as `project_node_id` in other endpoints (recordAsset, publishing, workflows, etc.)\n\n## Response Structure\n\nResults are grouped as `[{workspace: {...}, projects: {...}}, ...]`. Each workspace contains its child projects.\n","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Projects list response","content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"Success Response","properties":{"status_code":{"type":"integer","example":1,"description":"Status code (1 = success)"},"status_message":{"type":"string","example":"","description":"Status message"},"result":{"type":"array","items":{"type":"object","properties":{"workspace":{"type":"object","properties":{"id":{"type":"integer","example":1,"description":"Workspace node ID"},"node_id":{"type":"integer","example":1982,"description":"Workspace node ID"},"start_date":{"type":"string","example":"2016-02-17T00:00:00+01:00","description":"Start date"},"end_date":{"type":"string","example":"2016-02-17T00:00:00+01:00","description":"End date"},"label":{"type":"string","example":"Workspace 1","description":"Workspace label"},"class_id":{"type":"integer","example":4,"description":"Class ID"}},"required":["id","node_id","start_date","end_date","label","class_id"],"description":"Workspace information"},"projects":{"type":"object","properties":{"id":{"type":"integer","example":213855,"description":"Project node ID"},"node_id":{"type":"integer","example":213855,"description":"Project node ID"},"label":{"type":"string","example":"Christmas 2025","description":"Project label"},"description":{"type":"string","nullable":true,"example":null,"description":"Project description"},"active":{"type":"boolean","example":true,"description":"Whether the project is active"},"project_type":{"type":"string","example":"publication","description":"Project type"},"project_type_description":{"type":"string","example":"Publication","description":"Human-readable project type"},"path":{"type":"string","example":"0/1978/1982/213855","description":"Project path in hierarchy"},"class_id":{"type":"integer","example":4,"description":"Associated class ID"},"start_date":{"type":"string","nullable":true,"example":"2021-07-15T00:00:00+02:00","description":"Project start date"},"end_date":{"type":"string","nullable":true,"example":"2021-08-15T00:00:00+02:00","description":"Project end date"}},"required":["id","node_id","label","active","project_type","project_type_description","path","class_id"],"description":"Project information"}}},"description":"List of workspaces and its projects for the specified class"}},"required":["status_code","status_message","result"]},{"type":"object","title":"Error Response","properties":{"status_code":{"type":"integer","example":3,"description":"Status code (3 = error, 0 = class not found)"},"status_message":{"type":"string","example":"Class not found or access denied","description":"Error message"},"result":{"type":"array","items":{"type":"object"},"example":[],"description":"Empty array on error"}},"required":["status_code","status_message","result"]}]}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"class_id":{"type":"integer","description":"Library ID. Use POST /api/v3/administration/classes/list to get available libraries.","example":4},"include_inactive":{"type":"boolean","description":"Include inactive projects. By default, inactive projects are excluded. The filter will only be applied if the user is an admin or project manager.","example":true}},"required":["class_id"]}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token generated with /api/v3/token/get/"}}}}