{ "openapi": "3.0.0", "info": { "title": "Afineo Webservices API", "description": "## Definition\n\nThe Afineo API allows you to perform a number of operations on a platform using the REST protocol.\n\nTo perform operations on the API, you need an active account on the platform and its login credentials.\n\nEach account has different permissions, corresponding to authorized operations and accessible data for both reading and writing.\n\nThe required connection information can be obtained from a platform administrator.\n\nThese credentials are not the same as those used to log into the Afineo application.\n\nAll requests and responses to the API are in JSON format.\n\n---\n\n## API v3 Overview\n\nThe Afineo API v3 introduces a complete standardization to improve consistency, readability and compliance with modern API best practices.\n\nThis API version is available starting from version 10.2.0 of the Afineo application.\n\n### Key improvements\n\n- **Naming convention**: Endpoint names switched to kebab-case and snake_case adopted for all parameters\n- **Date format**: Migration to ISO 8601\n- **Data types**: Explicit booleans and appropriate types\n- **Response structure**: Standardized formats\n- **Error handling**: More detailed error messages and uniform structure\n- **Differentiation between repository and projects**: For example, the record creation endpoint `recordAsset/create` is split into `record-asset/create_repository` and `record-asset/create_node`\n\n---\n\n## Authentication\n\n### API v2\n\nThere is only one authentication method: token-based connection.\n\nA token allows authentication for a duration of 60 minutes.\n\nIt is obtained by providing credentials to the \"token\" module with the \"get\" action:\n- **l** (lowercase letter L): user login\n- **p** (lowercase letter P): password\n\nThe response is in JSON format with the following information:\n- **code**: return code (numeric format)\n- **message**: status message (text format)\n- **id**: the token (alphanumeric format)\n\nThe token must be passed with each API call via the **t** variable (lowercase letter T) as a body parameter:\n\n```json\n{\n \"t\": \"021928e078d7b27428267b6bdfa9ed8f1c798d37\",\n ...\n}\n```\n\n### API v3\n\nThe v3 authentication uses a **JWT (JSON Web Token)** passed in the `Authorization` HTTP header:\n\n```\nAuthorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...\n```\n\n#### v2 / v3 Comparison\n\n| Aspect | V2 | V3 |\n|---|---|---|\n| **Method** | Parameter `t` in body/query | `Authorization` header |\n| **Format** | Simple token | JWT (JSON Web Token) |\n| **Location** | Request body | HTTP header |\n| **Security** | Basic | Enhanced (signed JWT) |\n\n---\n\n## Return Code\n\nThe HTTP return code will always be 200.\n\nIt is the return code contained in the JSON response that indicates whether the action succeeded or failed (see \"Error Codes\" below).\n\n---\n\n## Error Codes\n\nAn action will always return a JSON response containing at least a return code. Here is the meaning of each return code:\n\n| Code | Meaning |\n|---|---|\n| 0 | The action does not exist |\n| 1 | Action successful |\n| 2 | Parameter error |\n| 3 | The action returns no result |\n| 4 | Action parameter information |\n| 997 | Unauthorized action |\n| 998 | The token is not valid |\n| 999 | Connection error |", "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": "administration", "description": "Read-only access to platform structure: list available libraries (classes) and versions. Use this to discover the data model foundation (library IDs, names) before querying other modules like attributes or types." }, { "name": "attributes", "description": "Define and manage asset attributes (fields) within a library: create attributes, organize them into tabs and groups, assign them to types, and retrieve JSON schemas for validation. This is the core module for data model configuration." }, { "name": "export", "description": "Export asset data using predefined mappings. Supports repository and project contexts, file-based exports (CSV, XML) via background jobs, and EasyCatalog format. Use processes/get to track export job status and retrieve generated files." }, { "name": "get-asset", "description": "Retrieve asset data by search criteria or by ID. Supports both repository (master data) and project (contextual data) contexts. Use this to read asset information without modifying it." }, { "name": "import", "description": "Import asset data into the platform. Supports auto-mapped imports and JSON/JSONL formats, in both repository and project contexts. Data can be sent inline via the data parameter or as a file upload." }, { "name": "listvalues", "description": "Manage dropdown lists (list values) used by select-type attributes: create lists, add options, and update existing values. These are the predefined option sets that populate dropdown, checkbox and radio attributes." }, { "name": "mappings", "description": "Read-only access to field mapping configurations: list available mappings and retrieve mapping details. Mappings define how data is transformed during import and export operations." }, { "name": "permissions", "description": "Read-only access to access control configuration: list and retrieve user groups, permission profiles, display masks, and asset statuses. Use this to discover permission structures and their IDs for use in other API calls." }, { "name": "preferences", "description": "Manage display preferences per library context: column visibility, sort order, and layout settings. These control how asset lists are presented to users." }, { "name": "processes", "description": "Execute and monitor background processes (ETL, exports, transformations). Launch a process, track its state via polling, retrieve execution logs and download generated files when complete." }, { "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." }, { "name": "publishing", "description": "Manage publication projects for catalog and document generation: create publications, manage pages, place products in blocks, assign themes, and control page layout. This is the complete print/digital publishing workflow." }, { "name": "queues", "description": "Monitor the message queue system: list queues, get queue details, and view queue types. Queues handle asynchronous job processing (imports, exports, transformations) across the platform." }, { "name": "record-asset", "description": "Full asset lifecycle management: create, update, delete, move and copy assets in both repository and project contexts. Also handles file uploads, status changes, type reassignment, and tree operations (move, copy, detach)." }, { "name": "token", "description": "Authentication: obtain a JWT token by providing credentials (login/password), check token validity, or disable active tokens. A valid token is required in the Authorization header for all other API calls." }, { "name": "types", "description": "Manage asset types (categories) within a library: create types, update properties, configure status assignments and set group permissions. Types define the classification and permission structure for assets." }, { "name": "workflows", "description": "Retrieve workflow configurations: list available workflows and get complete workflow definitions including states, transitions and rules. Supports both repository and project contexts." } ], "paths": { "/api/v3/administration/classes/list/": { "post": { "tags": [ "administration" ], "summary": "List all available classes", "description": "## Purpose\n\nReturns all configured data structures (libraries) in the system.\n\n## Use Cases\n\n- Discover available entities before creating or searching assets\n- Get class IDs required by other API endpoints\n- Retrieve class configuration (multilingual, contexts, modules)\n\n## Common Classes\n\nProducts, Media, Categories, Suppliers, Brands - each with its own attributes, types, and business rules.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Classes 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 (empty string on success)" }, "result": { "type": "object", "properties": { "results_total": { "type": "integer", "example": 5, "description": "Total number of classes returned" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 4, "description": "Class ID" }, "label": { "type": "string", "example": "Products", "description": "Class label" }, "description": { "type": "string", "example": "Product management class", "description": "Class description" }, "indexed": { "type": "boolean", "nullable": true, "example": true, "description": "Whether the class is indexed" }, "relation_type": { "type": "string", "nullable": true, "example": "Product Board", "description": "Relation type label" }, "manage_visuel": { "type": "boolean", "nullable": true, "example": true, "description": "Whether visual management is enabled" }, "tree_type": { "type": "string", "nullable": true, "example": "tree", "description": "Tree type" }, "path": { "type": "string", "nullable": true, "example": "tree", "description": "Path type" }, "default_tree": { "type": "string", "nullable": true, "example": "dynamic", "description": "Default tree type" }, "view": { "type": "string", "nullable": true, "example": "grid", "description": "Default view mode" }, "associated_class": { "type": "boolean", "nullable": true, "example": false, "description": "Whether class has advanced links" }, "multilingual": { "type": "boolean", "nullable": true, "example": true, "description": "Whether the class supports multiple languages" }, "enable_contexts": { "type": "boolean", "nullable": true, "example": true, "description": "Whether contexts are enabled for this class" }, "enable_suggestions": { "type": "boolean", "nullable": true, "example": false, "description": "Whether suggestions are enabled" }, "enable_note_management": { "type": "boolean", "nullable": true, "example": true, "description": "Whether note management is enabled (conditional)" }, "synchronization_modification_date_linking_assets": { "type": "boolean", "nullable": true, "example": false, "description": "Whether modification date sync is enabled for linked assets" }, "compare_contexts": { "type": "boolean", "nullable": true, "example": false, "description": "Whether context comparison is enabled" }, "enable_hierarchical_tree": { "type": "boolean", "nullable": true, "example": true, "description": "Whether hierarchical tree is enabled" }, "enable_labels": { "type": "boolean", "nullable": true, "example": false, "description": "Whether labels are enabled" }, "media_transformation": { "type": "boolean", "nullable": true, "example": true, "description": "Whether media transformation is enabled" }, "enable_lock_attribute": { "type": "boolean", "nullable": true, "example": true, "description": "Whether attribute locking is enabled (conditional)" }, "hotfolder": { "type": "boolean", "nullable": true, "example": false, "description": "Whether hotfolder functionality is enabled" }, "modules": { "oneOf": [ { "type": "object", "additionalProperties": { "type": "string" }, "example": { "3": "Workspace", "7": "Process" }, "description": "Available modules for this class" }, { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array when no modules" } ], "nullable": true }, "supertype_default_search": { "type": "array", "nullable": true, "items": { "type": "string" }, "example": [ "7" ], "description": "Default search supertype IDs (conditional)" }, "overload_supertypes": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "supertype_id": { "type": "integer", "description": "Supertype ID" }, "label_custom": { "type": "string", "description": "Custom label for the supertype" } } }, "example": [ { "supertype_id": 7, "label_custom": "Custom Label" } ], "description": "Custom supertype overloads (conditional)" }, "linked_classes": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Linked class ID" }, "label": { "type": "string", "description": "Linked class label" }, "link_table": { "type": "string", "description": "Name of the linking table between the two classes" }, "has_advanced_link": { "type": "boolean", "description": "Whether an advanced link table (crossed data) has been generated for this link" } } }, "example": [ { "id": 2, "label": "Media", "link_table": "products_pictures", "has_advanced_link": false } ], "description": "List of classes linked (attached) to this class" } }, "required": [ "id", "label", "description" ] }, "description": "Array of class objects" } }, "required": [ "results_total", "items" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "enum": [ 3, 997 ], "example": 997, "description": "Status code (997 = insufficient permissions, 3 = no results found)" }, "status_message": { "type": "string", "enum": [ "You don't have the rights to do this action", "No results found" ], "example": "You don't have the rights to do this action", "description": "Error message" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array on error" } }, "required": [ "status_code", "status_message", "result" ] } ] } } } } } } }, "/api/v3/administration/versions/list/": { "post": { "tags": [ "administration" ], "summary": "List available versions", "description": "## Purpose\n\nReturns available language versions (locales) configured in the system.\n\n## Use Cases\n\n- Get version IDs for multi-language operations\n- Discover available locales (language + country + channel)\n- Filter by class or project context\n\n## Filtering\n\n- **No parameters**: All system versions\n- **class_id**: Versions available for a specific class\n- **context + node_id**: Versions available in a specific project node\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Versions 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 (empty string on success)" }, "result": { "type": "object", "properties": { "results_total": { "type": "integer", "example": 5, "description": "Total number of versions returned" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1, "description": "Version ID" }, "label": { "type": "string", "example": "France (canal défaut)", "description": "Version label" }, "active": { "type": "boolean", "example": true, "description": "Whether the version is active" }, "currency": { "type": "string", "example": "EUR", "description": "Currency code" }, "flag": { "type": "string", "example": "fr.png", "description": "Flag filename" }, "channel": { "type": "object", "description": "Channel information", "properties": { "id": { "type": "integer", "example": 1, "description": "Channel ID" }, "label": { "type": "string", "example": "canal défaut", "description": "Channel label" }, "active": { "type": "boolean", "example": true, "description": "Whether the channel is active" }, "color": { "type": "string", "example": "#ffffff", "description": "Channel color" } }, "required": [ "id", "label", "active", "color" ] }, "localisation": { "type": "object", "description": "Localisation information", "properties": { "id": { "type": "integer", "example": 1, "description": "Localisation ID" }, "label": { "type": "string", "example": "France", "description": "Localisation label" }, "active": { "type": "boolean", "example": true, "description": "Whether the localisation is active" } }, "required": [ "id", "label", "active" ] }, "country": { "type": "object", "description": "Country information", "properties": { "id": { "type": "integer", "example": 67, "description": "Country ID" }, "code": { "type": "string", "example": "FR", "description": "Country ISO code" }, "label": { "type": "string", "example": "France", "description": "Country label" } }, "required": [ "id", "code", "label" ] }, "lang": { "type": "object", "description": "Language information", "properties": { "id": { "type": "integer", "example": 34, "description": "Language ID" }, "code": { "type": "string", "example": "fr", "description": "Language ISO code" }, "label": { "type": "string", "example": "French", "description": "Language label" } }, "required": [ "id", "code", "label" ] } }, "required": [ "id", "label", "active", "currency", "flag", "channel", "localisation", "country", "lang" ] }, "description": "Array of version objects with localization and channel information" } }, "required": [ "results_total", "items" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "enum": [ 2, 3 ], "example": 3, "description": "Status code (2 = class or node not found, 3 = no results found)" }, "status_message": { "type": "string", "enum": [ "Class or node not found", "No results found" ], "example": "No results found", "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 }, "context": { "type": "string", "description": "Context of the versions list. Use \"repository\" to list versions by class, or \"node\" for a specific project node **⚠️ Required when:** `class_id` = `107` | `110` | `4` | `2` | `106` | `101`", "enum": [ "repository", "node" ], "example": "repository", "x-conditional-required": { "class_id": [ 107, 110, 4, 2, 106, 101 ] } }, "node_id": { "type": "integer", "description": "Node ID. Use POST /api/v3/projects/list to find projects, then POST /api/v3/projects/get for project details **⚠️ Required when:** `context` = `node`", "example": 1254, "x-conditional-required": { "context": [ "node" ] } } } } } } } } }, "/api/v3/attributes/get/": { "post": { "tags": [ "attributes" ], "summary": "Get attribute configuration", "description": "## Purpose\n\nReturns complete field definition (type, validation rules, list values, display settings, permissions).\n\n## Use Cases\n\n- Understand attribute behavior before data submission\n- Build dynamic forms based on attribute configuration\n- Validate data format requirements\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Attribute 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": "Empty string on success" }, "result": { "type": "object", "description": "Attribute information with common properties at first level and specific properties in configuration", "properties": { "id": { "type": "integer", "example": 231, "description": "Attribute ID" }, "code": { "type": "string", "example": "product_name", "description": "Attribute code" }, "label": { "type": "string", "example": "Product name", "description": "Attribute label" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "tag1", "tag2" ], "description": "Array of tags (can be empty)" }, "class_id": { "type": "integer", "example": 4, "description": "Library ID. Use POST /api/v3/administration/classes/list to get available libraries." }, "description": { "type": "string", "nullable": true, "example": "Product name description", "description": "Attribute description" }, "tab_id": { "type": "integer", "example": 105, "description": "Tab ID. Use POST /api/v3/attributes/tabs/list with class_id to get available tabs." }, "tab_label": { "type": "string", "example": "General", "description": "Tab label" }, "group_id": { "type": "integer", "nullable": true, "example": 81, "description": "Group ID. Use POST /api/v3/attributes/groups/list with class_id to get available groups." }, "group_label": { "type": "string", "nullable": true, "example": "Information", "description": "Group label" }, "data_type": { "type": "string", "example": "short_text", "enum": [ "afs", "asset_link", "boolean", "characteristic", "checkbox", "counter", "data_table", "date", "datetime", "decimal", "dropdown", "dropdown_editable", "dropdown_items", "dropdown_items_editable", "dynamic_afs", "dynamic_link", "ean", "email", "etim", "html", "integer", "long_text", "multi_dropdown", "multi_dropdown_items", "passthrough", "price", "product_table", "radio", "radio_items", "rich_text", "short_text", "splitter", "tiles", "tiles_required", "url" ], "description": "Data type" }, "type": { "type": "string", "enum": [ "simple_value", "advanced_value" ], "example": "advanced_value", "description": "Attribute type (simple_value or advanced_value)" }, "order": { "type": "integer", "example": 5, "description": "Display order" }, "view_asset": { "type": "boolean", "example": true, "description": "Whether attribute is visible on the asset" }, "dependency": { "type": "string", "nullable": true, "example": "{if #153#}1{/if}", "description": "Attribute dependencies (AfineoScript)" }, "scope": { "type": "string", "example": "reference_value", "enum": [ "reference_value", "overloadable_repository_value", "reference_value_directly_editable_locally", "contextual_value", "shared_value_to_project_group" ], "description": "Attribute scope" }, "langs_label": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "Français (fr)": "Nom du produit", "English (en)": "Product name" }, "description": "Label translations by language" }, "configuration": { "type": "object", "description": "Specific configuration based on data_type. Properties vary depending on the attribute type. See JSON schemas in attributes_schema folder for complete property list per data_type.", "additionalProperties": true, "example": { "name": "role_231", "system": false, "class_linked_id": null, "suffix_text": "€", "suffix_list": null, "specifications": null, "alignment": 0, "character_limit": "0-255", "unique": 0, "required": true, "is_crossed_data": false, "default_value": null, "default_value_afs": 0, "ai_completion": 0, "multilingual": true, "multilingual_default_value": 0, "property": 0, "property_label": "standard", "remain_visible_master_asset": null, "editable": true, "indexed": false, "display": false, "help": "Help text", "help_display": "overview", "afs": null, "default_inheritance": false, "inheritable": false, "crossed_attributes": [], "permissions": [], "asset_types": [], "langs_help": [], "langs_default_value": [] } } }, "required": [ "id", "code", "label", "tags", "class_id", "data_type", "type", "order", "view_asset", "scope", "langs_label", "configuration" ] } }, "required": [ "status_code", "status_message", "result" ], "description": "Attribute information" }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = not found)" }, "status_message": { "type": "string", "example": "Attribute \"231\" does not exist", "description": "Error message with attribute ID" }, "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": "Attribute ID. Use POST /api/v3/attributes/list with class_id to get available attribute IDs for a library.", "example": 231 } }, "required": [ "id" ] } } } } } }, "/api/v3/attributes/full/": { "post": { "tags": [ "attributes" ], "summary": "Get all attributes with full configuration", "description": "## Purpose\n\nReturns complete information about all attributes of a class with full configuration.\n\n## Structure\n\nCombines `attributes/list` envelope (`results_total`, `items`) with `attributes/get` detail level (common properties + `configuration` object).\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Full attributes 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": "Empty string on success" }, "result": { "type": "object", "properties": { "results_total": { "type": "integer", "example": 25, "description": "Total number of attributes" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 231, "description": "Attribute ID" }, "code": { "type": "string", "example": "product_name", "description": "Attribute code" }, "label": { "type": "string", "example": "Product name", "description": "Attribute label" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "tag1", "tag2" ], "description": "Array of tags (can be empty)" }, "class_id": { "type": "integer", "example": 4, "description": "Library ID. Use POST /api/v3/administration/classes/list to get available libraries." }, "description": { "type": "string", "nullable": true, "example": "Product name description", "description": "Attribute description" }, "tab_id": { "type": "integer", "example": 105, "description": "Tab ID. Use POST /api/v3/attributes/tabs/list with class_id to get available tabs." }, "tab_label": { "type": "string", "example": "General", "description": "Tab label" }, "group_id": { "type": "integer", "nullable": true, "example": 81, "description": "Group ID. Use POST /api/v3/attributes/groups/list with class_id to get available groups." }, "group_label": { "type": "string", "nullable": true, "example": "Information", "description": "Group label" }, "data_type": { "type": "string", "example": "short_text", "enum": [ "afs", "asset_link", "boolean", "characteristic", "checkbox", "counter", "data_table", "date", "datetime", "decimal", "dropdown", "dropdown_editable", "dropdown_items", "dropdown_items_editable", "dynamic_afs", "dynamic_link", "ean", "email", "etim", "html", "integer", "long_text", "multi_dropdown", "multi_dropdown_items", "passthrough", "price", "product_table", "radio", "radio_items", "rich_text", "short_text", "splitter", "tiles", "tiles_required", "url" ], "description": "Data type" }, "type": { "type": "string", "enum": [ "simple_value", "advanced_value" ], "example": "simple_value", "description": "Attribute type (simple_value or advanced_value)" }, "order": { "type": "integer", "example": 5, "description": "Display order" }, "view_asset": { "type": "boolean", "example": true, "description": "Whether attribute is visible on the asset" }, "dependency": { "type": "string", "nullable": true, "example": "{if #153#}1{/if}", "description": "Attribute dependencies (AfineoScript)" }, "scope": { "type": "string", "example": "reference_value", "enum": [ "reference_value", "overloadable_repository_value", "reference_value_directly_editable_locally", "contextual_value", "shared_value_to_project_group" ], "description": "Attribute scope" }, "langs_label": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "Français (fr)": "Nom du produit", "English (en)": "Product name" }, "description": "Label translations by language" }, "configuration": { "type": "object", "description": "Specific configuration based on data_type. Properties vary depending on the attribute type.", "additionalProperties": true, "example": { "name": "role_231", "system": false, "required": true, "multilingual": true, "editable": true, "indexed": false, "permissions": [], "asset_types": [] } } }, "required": [ "id", "code", "label", "tags", "class_id", "data_type", "type", "order", "view_asset", "scope", "langs_label", "configuration" ] }, "description": "Array of attributes with full configuration" } }, "required": [ "results_total", "items" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = not found)" }, "status_message": { "type": "string", "example": "Class \"4\" does not exist", "description": "Error message with class ID" }, "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 } }, "required": [ "class_id" ] } } } } } }, "/api/v3/attributes/list/": { "post": { "tags": [ "attributes" ], "summary": "List class attributes (simplified)", "description": "## Purpose\n\nReturns essential attribute information (id, code, label, data_type) for a class.\n\n## Pagination\n\nUse `num_page` and `results_per_page` together. Results per page: 10-1000.\n\n## Filtering\n\nFilter by `code`, `label`, `data_type`, `system`, `required`, `multilingual`, `indexed`, `scope`, and more. See params for all options.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Attributes 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": "Empty string on success" }, "result": { "type": "object", "properties": { "results_total": { "type": "integer", "example": 5, "description": "Total number of attributes (before pagination)" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 15, "description": "Attribute ID" }, "code": { "type": "string", "example": "attribute_code", "description": "Attribute code" }, "label": { "type": "string", "example": "My attribute", "description": "Attribute label" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "tag1", "tag2" ], "description": "Array of tags (can be empty)" }, "data_type": { "type": "string", "example": "short_text", "enum": [ "afs", "asset_link", "boolean", "characteristic", "checkbox", "counter", "data_table", "date", "datetime", "decimal", "dropdown", "dropdown_editable", "dropdown_items", "dropdown_items_editable", "dynamic_afs", "dynamic_link", "ean", "email", "etim", "html", "integer", "long_text", "multi_dropdown", "multi_dropdown_items", "passthrough", "price", "product_table", "radio", "radio_items", "rich_text", "short_text", "splitter", "tiles", "tiles_required", "url" ], "description": "Attribute data type (short_text, integer, dropdown_items, etc.)" }, "required": { "type": "integer", "example": 1, "description": "Required attribute (0=no, 1=yes)" }, "multilingual": { "type": "integer", "example": 1, "description": "Multilingual attribute (0=no, 1=yes)" }, "indexed": { "type": "integer", "example": 0, "description": "Indexed attribute (0=no, 1=yes)" }, "tab_label": { "type": "string", "example": "My tab label", "description": "Tab attribute label" }, "group_label": { "type": "string", "nullable": true, "example": "Product Properties", "description": "Attribute group label (null if attribute has no group)" }, "description": { "type": "string", "nullable": true, "example": "A description", "description": "Attribute description text (may be null)" }, "scope": { "type": "string", "example": "reference_value", "enum": [ "reference_value", "overloadable_repository_value", "reference_value_directly_editable_locally", "contextual_value", "shared_value_to_project_group" ], "description": "Attribute scope (reference_value, contextual_value, etc.)" } }, "required": [ "id", "code", "label", "tags", "data_type", "required", "multilingual", "indexed", "tab_label", "scope" ] }, "description": "Array of attributes objects" }, "num_page": { "type": "integer", "nullable": true, "example": 1, "description": "Current page number (only if pagination is used)" }, "nb_pages": { "type": "integer", "nullable": true, "example": 3, "description": "Total number of pages (only if pagination is used)" }, "results_per_page": { "type": "integer", "nullable": true, "example": 50, "description": "Number of results per page (only if pagination is used)" } }, "required": [ "results_total", "items" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = not found)" }, "status_message": { "type": "string", "example": "Class \"4\" does not exist", "description": "Error message with class ID" }, "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 }, "num_page": { "type": "integer", "description": "Page number. Must be used together with results_per_page.", "example": 1 }, "results_per_page": { "type": "integer", "description": "Number of results per page (between 10 and 1000). Must be used together with num_page.", "example": 50 }, "filters": { "type": "object", "description": "Optional filter object with type_id (filter by attribute type) and other criteria.", "example": { "data_type": "date", "system": false, "indexed": true }, "properties": { "code": { "type": "string", "description": "Partial match on attribute code (case-insensitive)", "example": "product" }, "label": { "type": "string", "description": "Partial match on attribute label (case-insensitive)", "example": "price" }, "class_linked_id": { "type": "integer", "description": "Associated library ID. Use POST /api/v3/administration/classes/list to get available libraries.", "example": 22 }, "description": { "type": "string", "description": "Partial match on attribute description", "example": "product" }, "tab_id": { "type": "integer", "description": "Tab ID. Use POST /api/v3/attributes/tabs/list with class_id to get available tabs.", "example": 105 }, "tab_label": { "type": "string", "description": "Tab label", "example": "My tab label" }, "group_id": { "type": "integer", "description": "Attribute group ID. Use POST /api/v3/attributes/groups/list with class_id to get available groups.", "example": 81 }, "group_label": { "type": "string", "description": "Group label", "example": "My group label" }, "name": { "type": "string", "description": "Partial match on attribute internal name (e.g. role_231)", "example": "role_231" }, "system": { "type": "boolean", "description": "Filter by system attribute (true = system-managed only, false = user-created only)", "example": false }, "data_type": { "type": "string", "description": "Attribute data type", "enum": [ "afs", "asset_link", "boolean", "characteristic", "checkbox", "counter", "data_table", "date", "datetime", "decimal", "dropdown", "dropdown_editable", "dropdown_items", "dropdown_items_editable", "dynamic_afs", "dynamic_link", "ean", "email", "etim", "html", "integer", "long_text", "multi_dropdown", "multi_dropdown_items", "passthrough", "price", "product_table", "radio", "radio_items", "rich_text", "short_text", "splitter", "tiles", "tiles_required", "url" ], "example": "short_text" }, "list_values": { "type": "integer", "description": "Values list ID. Use POST /api/v3/listvalues/list with class_id to get available values lists.", "example": 32 }, "list": { "type": "boolean", "description": "Filter by asset bin attribute (true = bin/collection attributes only, false = standard attributes only)", "example": false }, "unique": { "type": "integer", "description": "Unique value(s) (0=none, 1=check, 2=block)", "example": 2 }, "required": { "type": "boolean", "description": "Filter by required attribute (true = required only, false = optional only)", "example": true }, "asset_link_management": { "type": "boolean", "description": "Filter by advanced value attribute (true = advanced_value only, false = simple_value only)", "example": false }, "is_crossed_data": { "type": "boolean", "description": "Filter by advanced link attribute", "example": false }, "multilingual": { "type": "boolean", "description": "Filter by multilingual attribute", "example": false }, "property": { "type": "integer", "description": "Property value(s) (0=Standard, 1=Relevant, 2=Variation)", "example": 0 }, "editable": { "type": "boolean", "description": "Filter by editable attribute (true = editable only, false = read-only only)", "example": true }, "indexed": { "type": "boolean", "description": "Filter by indexed attribute (true = indexed for search, false = not indexed)", "example": false }, "view_asset": { "type": "boolean", "description": "Filter by visibility on asset sheet (true = visible on asset, false = hidden)", "example": true }, "display": { "type": "boolean", "description": "Filter by display in asset list columns (true = shown in list, false = hidden)", "example": false }, "scope": { "type": "string", "description": "Filter by attribute scope (reference_value, overloadable_repository_value, contextual_value, etc.)", "enum": [ "reference_value", "overloadable_repository_value", "reference_value_directly_editable_locally", "contextual_value", "shared_value_to_project_group" ], "example": "contextual_value" }, "default_inheritance": { "type": "boolean", "description": "Filter by default inheritance (true = inherited by child assets by default)", "example": true }, "inheritable": { "type": "boolean", "description": "Filter by inheritable attribute", "example": false }, "usage": { "type": "boolean", "description": "Filter by usage (0=multi-valued, 1=single-valued)", "example": true }, "create_value": { "type": "boolean", "description": "Filter by create value attribute", "example": true }, "search": { "type": "integer", "description": "Search value(s) (0=no, 1=yes in full screen mode, 2=yes in drop-down mode)", "example": 2 } } } }, "required": [ "class_id" ] } } } } } }, "/api/v3/attributes/types/": { "post": { "tags": [ "attributes" ], "summary": "Get attribute type assignments", "description": "## Purpose\n\nReturns asset type assignments for an attribute.\n\n## Response Details\n\nEach assignment includes:\n- `type_id`, `type_label`: Asset type identification\n- `supertype_id`, `supertype_label`: Parent supertype\n- `editability`: default, editable, or not_editable\n- `hide_interface`: visibility in UI\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Attribute type assignments 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": "Empty string on success" }, "result": { "type": "object", "properties": { "results_total": { "type": "integer", "example": 5, "description": "Total number of asset types assigned to this attribute" }, "items": { "type": "array", "items": { "type": "object", "properties": { "type_id": { "type": "integer", "example": 407, "description": "Asset type ID" }, "type_label": { "type": "string", "nullable": true, "example": "Product", "description": "Asset type label" }, "supertype_id": { "type": "integer", "nullable": true, "example": 1, "description": "Supertype ID" }, "supertype_label": { "type": "string", "nullable": true, "example": "Record", "description": "Supertype label" }, "editability": { "type": "string", "enum": [ "default", "editable", "not_editable" ], "example": "editable", "description": "Editability setting for this attribute on this type" }, "hide_interface": { "type": "boolean", "example": false, "description": "Whether the attribute is hidden in the interface for this type" } }, "required": [ "type_id", "type_label", "supertype_id", "supertype_label", "editability", "hide_interface" ] }, "description": "Array of type assignments for this attribute" } }, "required": [ "results_total", "items" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = attribute not found)" }, "status_message": { "type": "string", "example": "Attribute \"231\" does not exist", "description": "Error message" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array on error" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Not Found Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = no assignments found)" }, "status_message": { "type": "string", "example": "No type assignments found for attribute \"231\"", "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": "Attribute ID. Use POST /api/v3/attributes/list with class_id to get available attribute IDs for a library.", "example": 231 } }, "required": [ "id" ] } } } } } }, "/api/v3/attributes/masks/": { "post": { "tags": [ "attributes" ], "summary": "Get attribute mask permissions", "description": "## Purpose\n\nReturns display mask assignments and permissions for an attribute.\n\n## Response Details\n\nEach assignment includes:\n- `mask_id`, `mask_label`: Display mask identification\n- `hidden`: attribute visibility for this mask\n- `read`, `write`: permission flags\n- `locally_editable`: reference value editability in assetShare\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Attribute mask permissions 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": "Empty string on success" }, "result": { "type": "object", "properties": { "results_total": { "type": "integer", "example": 5, "description": "Total number of display masks assigned to this attribute" }, "items": { "type": "array", "items": { "type": "object", "properties": { "mask_id": { "type": "integer", "example": 1557, "description": "Display mask ID" }, "mask_label": { "type": "string", "example": "Standard", "description": "Display mask label" }, "hidden": { "type": "boolean", "example": false, "description": "Whether attribute is hidden for this mask (no LCA entry exists)" }, "read": { "type": "boolean", "example": true, "description": "Read permission for this attribute with this mask" }, "write": { "type": "boolean", "example": true, "description": "Write permission for this attribute with this mask" }, "locally_editable": { "type": "boolean", "example": false, "description": "Whether reference value is directly editable locally (assetShare)" } }, "required": [ "mask_id", "mask_label", "hidden", "read", "write", "locally_editable" ] }, "description": "Array of mask permissions for this attribute" } }, "required": [ "results_total", "items" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = attribute not found)" }, "status_message": { "type": "string", "example": "Attribute \"231\" does not exist", "description": "Error message" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array on error" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Not Found Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = no permissions found)" }, "status_message": { "type": "string", "example": "No mask permissions found for attribute \"231\"", "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": "Attribute ID. Use POST /api/v3/attributes/list with class_id to get available attribute IDs for a library.", "example": 231 } }, "required": [ "id" ] } } } } } }, "/api/v3/attributes/tabs/create/": { "post": { "tags": [ "attributes" ], "summary": "Create a new attribute tab", "description": "## Purpose\n\nCreates a new display tab in a library. Tabs organize attributes into logical sections in the asset editing interface.\n\n## Required Parameters\n\n- `class_id`: Library where the tab will be created\n- `label`: Display name for the tab\n\n## Idempotent Behavior\n\nIf a tab with the same label already exists in the library, the endpoint returns the existing tab with `created: false` instead of creating a duplicate.\n\n## Modeling Hierarchy\n\nLibrary → **Tab** → Group → Attributes\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Tab 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": "Tab created successfully", "description": "Success message" }, "result": { "type": "object", "properties": { "id": { "type": "integer", "example": 45, "description": "Tab ID" }, "class_id": { "type": "integer", "example": 4, "description": "Library ID" }, "label": { "type": "string", "example": "Technical information", "description": "Tab label" }, "order": { "type": "integer", "example": 3, "description": "Display order" }, "created": { "type": "boolean", "example": true, "description": "true if newly created, false if already existed" } }, "required": [ "id", "class_id", "label", "order", "created" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = validation error)" }, "status_message": { "type": "string", "example": "Label cannot be empty", "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 }, "label": { "type": "string", "description": "Tab label (display name). Common examples: Identification, Commercial, Technical, Logistics, Marketing.", "example": "Technical information" } }, "required": [ "class_id", "label" ] } } } } } }, "/api/v3/attributes/tabs/update/": { "post": { "tags": [ "attributes" ], "summary": "Update an existing attribute tab", "description": "## Purpose\n\nUpdates properties of an existing display tab. Only provided fields are modified — omitted fields remain unchanged.\n\n## What can be updated\n\n- `label`: Display name\n\n## What cannot be updated\n\n- `class_id` (immutable — the tab belongs to a specific library)\n\n## Modeling Hierarchy\n\nLibrary → **Tab** → Group → Attributes\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Tab update 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": "Tab updated successfully", "description": "Status message" }, "result": { "type": "object", "properties": { "id": { "type": "integer", "example": 45, "description": "Tab ID" }, "class_id": { "type": "integer", "example": 4, "description": "Library ID" }, "label": { "type": "string", "example": "Technical information", "description": "Tab label" }, "updated_fields": { "type": "array", "items": { "type": "string" }, "example": [ "label" ], "description": "List of fields that were actually modified" } }, "required": [ "id", "class_id", "label", "updated_fields" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "enum": [ 2, 997 ], "example": 2, "description": "Status code (2 = validation error, 997 = insufficient permissions)" }, "status_message": { "type": "string", "example": "Tab not found", "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": "Tab ID to update. Use POST /api/v3/attributes/tabs/list with class_id to get available tabs.", "example": 45 }, "label": { "type": "string", "description": "New tab label (display name)", "example": "Technical information" } }, "required": [ "id" ] } } } } } }, "/api/v3/attributes/groups/create/": { "post": { "tags": [ "attributes" ], "summary": "Create a new attribute group", "description": "## Purpose\n\nCreates a new attribute group within a tab. Groups organize attributes by theme within a tab.\n\n## Required Parameters\n\n- `class_id`: Library where the group will be created\n- `tab_id`: Parent tab ID (must belong to the specified library)\n- `label`: Display name for the group\n\n## Idempotent Behavior\n\nIf a group with the same label already exists in the same tab, the endpoint returns the existing group with `created: false` instead of creating a duplicate.\n\n## Modeling Hierarchy\n\nLibrary → Tab → **Group** → Attributes\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Group 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": "Group created successfully", "description": "Success message" }, "result": { "type": "object", "properties": { "id": { "type": "integer", "example": 78, "description": "Group ID" }, "class_id": { "type": "integer", "example": 4, "description": "Library ID" }, "tab_id": { "type": "integer", "example": 45, "description": "Parent tab ID" }, "label": { "type": "string", "example": "Dimensions", "description": "Group label" }, "order": { "type": "integer", "example": 3, "description": "Display order within tab" }, "created": { "type": "boolean", "example": true, "description": "true if newly created, false if already existed" } }, "required": [ "id", "class_id", "tab_id", "label", "order", "created" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = validation error)" }, "status_message": { "type": "string", "example": "Tab does not belong to specified library", "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 }, "tab_id": { "type": "integer", "description": "Parent tab ID. Must belong to the specified library. Use POST /api/v3/attributes/tabs/list with class_id to get available tabs.", "example": 45 }, "label": { "type": "string", "description": "Group label (display name). Common examples: Dimensions, Pricing, Identification, Properties.", "example": "Dimensions" } }, "required": [ "class_id", "tab_id", "label" ] } } } } } }, "/api/v3/attributes/groups/update/": { "post": { "tags": [ "attributes" ], "summary": "Update an existing attribute group", "description": "## Purpose\n\nUpdates properties of an existing attribute group. Only provided fields are modified — omitted fields remain unchanged.\n\n## What can be updated\n\n- `label`: Display name\n\n## What cannot be updated\n\n- `tab_id` (immutable — the group belongs to a specific tab)\n\n## Important\n\nIf no updatable field is provided, the endpoint returns success with an empty `updated_fields` list.\n\n## Modeling Hierarchy\n\nLibrary → Tab → **Group** → Attributes\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Group update 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": "Group updated successfully", "description": "Status message" }, "result": { "type": "object", "properties": { "id": { "type": "integer", "example": 78, "description": "Group ID" }, "tab_id": { "type": "integer", "example": 45, "description": "Parent tab ID" }, "label": { "type": "string", "example": "Dimensions", "description": "Group label" }, "updated_fields": { "type": "array", "items": { "type": "string" }, "example": [ "label" ], "description": "List of fields that were actually modified" } }, "required": [ "id", "tab_id", "label", "updated_fields" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "enum": [ 2, 997 ], "example": 2, "description": "Status code (2 = validation error, 997 = insufficient permissions)" }, "status_message": { "type": "string", "example": "Group not found", "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": "Group ID to update. Use POST /api/v3/attributes/groups/list with class_id and tab_id to get available groups.", "example": 78 }, "label": { "type": "string", "description": "New group label (display name). Common examples: Dimensions, Pricing, Identification, Properties. Maximum 255 characters. Empty strings are not allowed.", "example": "Dimensions" } }, "required": [ "id" ] } } } } } }, "/api/v3/attributes/tabs/list/": { "post": { "tags": [ "attributes" ], "summary": "List attribute tabs", "description": "## Purpose\n\nReturns attribute tabs (form sections) for a library. Tabs organize attributes into logical groups in the asset editing interface.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Tabs 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": "Empty string on success" }, "result": { "type": "object", "properties": { "results_total": { "type": "integer", "example": 5, "description": "Total number of tabs" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 105, "description": "Tab ID" }, "label": { "type": "string", "example": "General", "description": "Tab label" }, "order": { "type": "integer", "example": 1, "description": "Display order" }, "visible": { "type": "boolean", "example": true, "description": "Whether the tab is visible" }, "description": { "type": "string", "nullable": true, "example": null, "description": "Tab description or help text (may be null)" } }, "required": [ "id", "label", "order", "visible" ] }, "description": "Array of tabs" } }, "required": [ "results_total", "items" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = no tabs found)" }, "status_message": { "type": "string", "example": "No tabs found", "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_hidden": { "type": "boolean", "description": "Include hidden tabs. By default, only visible tabs are returned.", "example": false } }, "required": [ "class_id" ] } } } } } }, "/api/v3/attributes/groups/list/": { "post": { "tags": [ "attributes" ], "summary": "List attribute groups", "description": "## Purpose\n\nReturns attribute groups within tabs for a library. Groups organize attributes within tabs.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Groups 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": "Empty string on success" }, "result": { "type": "object", "properties": { "results_total": { "type": "integer", "example": 5, "description": "Total number of groups" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 81, "description": "Group ID" }, "label": { "type": "string", "example": "Product Properties", "description": "Group label" }, "tab_id": { "type": "integer", "example": 105, "description": "Parent tab ID" }, "tab_label": { "type": "string", "example": "General", "description": "Parent tab label" }, "order": { "type": "integer", "example": 3, "description": "Display order within tab" }, "description": { "type": "string", "nullable": true, "example": null, "description": "Attribute group description or help text (may be null)" } }, "required": [ "id", "label", "tab_id", "tab_label", "order" ] }, "description": "Array of groups" } }, "required": [ "results_total", "items" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = no groups found)" }, "status_message": { "type": "string", "example": "No groups found", "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 }, "tab_id": { "type": "integer", "description": "Filter by tab. Use POST /api/v3/attributes/tabs/list with class_id to get available tabs.", "example": 105 } }, "required": [ "class_id" ] } } } } } }, "/api/v3/attributes/schema/": { "post": { "tags": [ "attributes" ], "summary": "Get attribute schema by data type", "description": "## Purpose\n\nReturns the JSON schema defining all available properties for a specific attribute data type.\n\n## Response Structure\n\nThe schema returns all properties at root level (flat structure).\n\n**Important**: When calling the create endpoint, common properties (`class_id`, `tab_id`, `data_type`, `label`, `code`, `group_id`, `description`) go at root level, while all other properties from the schema should be placed inside the `configuration` object.\n\n**Note**: JSON Schema standard keys are converted to snake_case in the response (`allOf` -> `all_of`, `maxLength` -> `max_length`, `additionalProperties` -> `additional_properties`).\n\n## Use Cases\n\n- Discover required and optional fields before calling POST /api/v3/attributes/create/\n- Understand validation rules, default values, and enum constraints for each property\n\n## Workflow\n\n1. Call this endpoint with the desired data_type\n2. Receive the flat JSON schema listing all available properties with types, defaults, and validation rules\n3. When preparing your create request: put common fields at root level, put all type-specific fields inside `configuration: {...}`\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Schema 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": "Empty string on success" }, "result": { "type": "object", "description": "JSON Schema object defining the attribute properties", "properties": { "$schema": { "type": "string", "example": "http://json-schema.org/draft-07/schema#" }, "title": { "type": "string", "example": "Schéma de l'attribut Afineo : texte court" }, "description": { "type": "string", "example": "Schéma décrivant toutes les options possibles pour un attribut de nature : short_text" }, "type": { "type": "string", "example": "object" }, "properties": { "type": "object", "description": "Property definitions with types, descriptions, and validation rules", "additionalProperties": true }, "allOf": { "type": "array", "description": "Conditional validation rules based on property values", "items": { "type": "object" } } } } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = invalid data_type)" }, "status_message": { "type": "string", "example": "Schema not found for data_type \"invalid_type\"", "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": { "data_type": { "type": "string", "description": "The attribute data type to get the creation schema for. Returns all available properties (common + configuration object) with types, descriptions, default values, and validation rules. Use this before calling POST /api/v3/attributes/create/ to understand required and optional fields for the chosen type.", "enum": [ "afs", "asset_link", "boolean", "checkbox", "counter", "data_table", "date", "datetime", "decimal", "dropdown_items", "dropdown_items_editable", "dynamic_afs", "dynamic_link", "ean", "email", "html", "integer", "long_text", "multi_dropdown_items", "passthrough", "price", "product_table", "radio_items", "rich_text", "short_text", "splitter", "url" ], "example": "short_text" } }, "required": [ "data_type" ] } } } } } }, "/api/v3/attributes/create/": { "post": { "tags": [ "attributes" ], "summary": "Create a new attribute", "description": "## Purpose\n\nCreates a new attribute with validation against the JSON schema for the specified data_type.\n\n## Workflow\n\n1. First call POST /api/v3/attributes/schema/ with your desired data_type to get the schema\n2. Prepare your attribute data according to the schema requirements\n3. Call this endpoint with common properties at root level and type-specific properties in `configuration`\n\n## Parameter Structure\n\nParameters are organized in two levels:\n- **Root level**: Common properties required for all data types\n- **configuration**: Object containing type-specific properties (varies by data_type)\n\n## Required Fields (all data types)\n\n- `class_id`: Library ID where the attribute will be created\n- `tab_id`: Tab ID where the attribute will be placed\n- `data_type`: The attribute data type (determines available configuration properties)\n- `label`: Display label for the attribute\n- `code`: Unique code/identifier (must start with a letter, globally unique across all libraries)\n\n## Type-Specific Requirements (in configuration)\n\nSome data types require additional fields in the configuration object:\n- `asset_link`, `dynamic_link`: requires `class_linked_id` (target library ID, use POST /api/v3/administration/classes/list to get available IDs)\n- `dynamic_link`: also requires `dynamic_afs` (AfineoScript for dynamic search)\n- `dropdown_items`, `dropdown_items_editable`, `multi_dropdown_items`, `radio_items`, `checkbox_items`: requires `list_values` (values list ID, must belong to same class_id - get IDs via POST /api/v3/listvalues/list)\n- `afs`: requires `afs` (AfineoScript formula, e.g. `{ref:product_name} - {ref:brand}`)\n- `counter`: accepts `counter_start` (integer, starting value, default 0), `counter_afs` (string, AfineoScript for counter format), `counter_nbcharacters` (integer, zero-padding character count)\n- See schema endpoint for complete requirements per data_type\n\n## Type-Specific Restrictions\n\nSome data types have restrictions on configuration properties:\n- `splitter`: indexed and editable are forbidden (visual separator only)\n- `counter`: editable is forbidden (auto-incremented)\n- `multi_dropdown_items`: multilingual is forbidden (managed at list level)\n- `passthrough`: required, unique, indexed, default_value, character_limit are forbidden (display-only)\n- `inheritable` and `default_inheritance` are mutually exclusive (cannot both be true)\n- `ai_completion` is only available for short_text, long_text, and rich_text\n- `create_value` and `display_assets` are only available for asset_link and dynamic_link\n- `asset_multiple` requires `display_assets` to be 2\n- `remain_visible_master_asset` requires `property` to be 2\n- `multilingual_default_value` requires `multilingual` to be 1\n- When `default_value_afs` is 1, `afs` (AfineoScript formula) is required\n\n## Crossed Data Attributes\n\nSet `is_crossed_data: true` in configuration to create a crossed data attribute.\n\n**Requirements**:\n- The library must support crossed data\n- Forbidden data_types: afs, dynamic_afs, splitter, etim, characteristic\n\n**Forbidden properties** (automatically disabled when is_crossed_data is true):\nrequired, unique, default_value, default_value_afs, multilingual, property, inheritable, default_inheritance, alignment, character_limit, help, ai_completion, create_value, search, search_context, dependency, dynamic_afs, display_assets, usage, counter_start, counter_afs.\n\n## Example Call\n\n```json\n{\n \"class_id\": 4,\n \"tab_id\": 105,\n \"data_type\": \"short_text\",\n \"label\": \"Product Name\",\n \"code\": \"product_name\",\n \"configuration\": {\n \"required\": 1,\n \"multilingual\": 1,\n \"unique\": 1,\n \"character_limit\": \"0-255\"\n }\n}\n```\n\n## Example: Create a dropdown_items attribute\n\n```json\n{\n \"class_id\": 4,\n \"tab_id\": 105,\n \"data_type\": \"dropdown_items\",\n \"label\": \"Color\",\n \"code\": \"product_color\",\n \"configuration\": {\n \"list_values\": 12,\n \"required\": 1\n }\n}\n```\n\n## Common Errors\n\n- `Class ID \"X\" is invalid` - the specified class_id does not exist or is not active\n- `class_linked_id is required for data type \"X\"` - asset_link and dynamic_link types require a target library\n- `Tab not found: X` - the specified tab_id does not exist\n- `Tab X does not belong to class Y` - tab_id must belong to the specified class_id\n- `Group not found: X` - the specified group_id does not exist\n- `Group X does not belong to tab Y` - group_id must belong to the specified tab_id\n- `Values list not found: X` - the specified list_values does not exist\n- `Values list X does not belong to class Y` - list_values in configuration must belong to the same class_id\n- `Target class (class_linked_id) not found: X` - the specified class_linked_id does not exist\n- `Attribute code already exists: X` - code must be globally unique across all libraries\n- `Invalid code format` - code must match ^[a-zA-Z][a-zA-Z0-9_]*$\n- `Label exceeds maximum length of 255 characters` - label must be <= 255 chars\n- `Description exceeds maximum length of 500 characters` - description must be <= 500 chars\n- `Help exceeds maximum length of 1000 characters` - help (in configuration) must be <= 1000 chars\n- `Library X does not accept crossed data attributes` - library must support crossed data\n- `Data type X is not compatible with crossed data attributes` - some types are forbidden for crossed data\n- `\"X\" is not allowed for crossed data attributes` - property X is forbidden when is_crossed_data is true\n- `\"list_values\" is required for data type \"X\"` - dropdown_items, dropdown_items_editable, multi_dropdown_items, radio_items, checkbox_items need list_values\n- `\"afs\" is required for data type \"afs\"` - afs type needs the afs formula\n- `\"dynamic_afs\" is required for data type \"dynamic_link\"` - dynamic_link type needs the dynamic_afs script\n- `\"X\" is not available for data type \"Y\"` - property X is not allowed for the specified data_type\n- `Invalid \"character_limit\" format` - must be in \"min-max\" format (e.g., \"0-255\")\n- `Invalid \"character_limit\": minimum cannot be greater than maximum` - min value must be <= max value\n- `\"ai_completion\" is only available for short_text, long_text, and rich_text` - type restriction\n- `\"create_value\" is only available for asset_link and dynamic_link` - type restriction\n- `\"display_assets\" is only available for asset_link and dynamic_link` - type restriction\n- `\"asset_multiple\" requires \"display_assets\" to be 2` - dependency constraint\n- `\"remain_visible_master_asset\" requires \"property\" to be 2` - dependency constraint\n- `\"multilingual_default_value\" requires \"multilingual\" to be 1` - dependency constraint\n- `When \"default_value_afs\" is 1, \"afs\" is required` - dependency constraint\n- `scope_id X is not available for simple value types` - scope restriction for certain data types\n- `counter_start must be >= 0` - counter starting value must be non-negative\n- `counter_nbcharacters must be >= 0` - counter zero-padding must be non-negative\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Create attribute 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": "Attribute created successfully", "description": "Success message" }, "result": { "type": "object", "properties": { "id": { "type": "integer", "example": 456, "description": "ID of the created attribute" }, "code": { "type": "string", "example": "product_name", "description": "Attribute code" }, "label": { "type": "string", "example": "Product Name", "description": "Attribute label" }, "data_type": { "type": "string", "example": "short_text", "description": "Attribute data type" }, "class_id": { "type": "integer", "example": 4, "description": "Library ID" }, "tab_id": { "type": "integer", "example": 105, "description": "Tab ID" }, "field_name": { "type": "string", "nullable": true, "example": "role_456", "description": "Database field name (for simple_value types)" }, "is_crossed_data": { "type": "boolean", "nullable": true, "example": true, "description": "Present and true only when the attribute was created as crossed data" } }, "required": [ "id", "code", "label", "data_type", "class_id", "tab_id" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Validation Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = validation error)" }, "status_message": { "type": "string", "example": "Validation failed: class_linked_id is required for data_type asset_link", "description": "Validation error message" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array on error" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = creation error)" }, "status_message": { "type": "string", "example": "Error creating attribute: Attribute code already exists", "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 where the attribute will be created. Use POST /api/v3/administration/classes/list to get available libraries.", "example": 4 }, "tab_id": { "type": "integer", "description": "Tab ID where the attribute will be placed. Must belong to the specified class_id (validated server-side). Use POST /api/v3/attributes/tabs/list with class_id to get available tabs for that library.", "example": 105 }, "data_type": { "type": "string", "description": "The attribute data type. Determines available configuration properties. Common types: short_text (free text), dropdown_items (select from list), integer, decimal, boolean, date, asset_link (link to another library), rich_text (HTML content). After choosing a type, call POST /api/v3/attributes/schema/ with this data_type to get required configuration properties.", "enum": [ "afs", "asset_link", "boolean", "checkbox", "counter", "data_table", "date", "datetime", "decimal", "dropdown_items", "dropdown_items_editable", "dynamic_afs", "dynamic_link", "ean", "email", "html", "integer", "long_text", "multi_dropdown_items", "passthrough", "price", "product_table", "radio_items", "rich_text", "short_text", "splitter", "url" ], "example": "short_text" }, "label": { "type": "string", "description": "Display label for the attribute. Shown in forms and listings. Maximum 255 characters.", "example": "Product Name" }, "code": { "type": "string", "description": "Unique code/identifier for the attribute (XML code). Must start with a letter and contain only alphanumeric characters and underscores (regex: ^[a-zA-Z][a-zA-Z0-9_]*$). Must be globally unique across all libraries. Example: product_name, ean_code.", "example": "product_name" }, "group_id": { "type": "integer", "description": "Group ID within the tab. Must belong to the specified tab_id (validated server-side). Use POST /api/v3/attributes/groups/list with class_id and optionally tab_id to get available groups. Omit to place the attribute outside any group.", "example": 81 }, "description": { "type": "string", "description": "Description of the attribute. Provides context for users filling the form. Maximum 500 characters.", "example": "The main product name displayed to customers" }, "configuration": { "type": "object", "description": "Type-specific configuration properties. Available properties depend on the data_type. Key properties by type: dropdown_items/dropdown_items_editable/multi_dropdown_items/radio_items/checkbox_items require list_values (must belong to same class_id, get IDs via POST /api/v3/listvalues/list); asset_link/dynamic_link require class_linked_id (target library ID); dynamic_link also requires dynamic_afs; afs requires afs (formula). Use POST /api/v3/attributes/schema/ to get the complete schema for a specific data_type.", "example": { "required": 1, "multilingual": 1, "unique": 1, "character_limit": "0-255" } } }, "required": [ "class_id", "tab_id", "data_type", "label", "code" ] } } } } } }, "/api/v3/attributes/batch-create/": { "post": { "tags": [ "attributes" ], "summary": "Create multiple attributes in batch", "description": "## Purpose\n\nCreates multiple attributes in a single call with cache revalidation only at the end, improving performance for bulk operations.\n\n## Workflow\n\n1. Call POST /api/v3/attributes/tabs/list and POST /api/v3/attributes/groups/list to get available tabs and groups\n2. Call POST /api/v3/attributes/schema/ for each data_type you plan to use\n3. Prepare your attributes array (optionally with `types` and `masks` per attribute)\n4. Call this endpoint\n\n## Behavior\n\n- All attributes are created in the same library (`class_id` at root level)\n- Each attribute is validated independently (same rules as POST /api/v3/attributes/create/)\n- If an attribute fails validation, it is skipped and reported in `errors` — other attributes are still created\n- Cache is revalidated only once after all attributes are created, which is significantly faster for large batches\n- If `types` is provided, type assignments are applied after creation using the same sync logic as POST /api/v3/attributes/assign-types/. Since the attribute is new, this is purely additive (no prior state to remove)\n- If `masks` is provided, mask permissions are applied after creation using the same sync logic as POST /api/v3/attributes/assign-masks/. Since the attribute is new, this is purely additive\n- Invalid entries inside `types` or `masks` (unknown ID/label, missing required fields) do NOT abort the attribute creation — the attribute is still created and per-entry errors are reported in `created[i].types.errors` / `created[i].masks.errors`\n\n## Status Codes\n\n- `1`: All attributes created successfully\n- `2`: Partial success — some attributes created, some failed (check `errors` array)\n- `3`: All attributes failed (creation failures only — `status_code` does not reflect `types`/`masks` assignment errors; always check `created[i].types.errors` / `created[i].masks.errors` for partial assignment failures)\n\n## When to use inline `types`/`masks` vs separate endpoints\n\n- **Use inline** when creating attributes that already need to be assigned to specific record types or masks — saves N×2 roundtrips per attribute compared to calling `assign-types`/`assign-masks` separately\n- **Use separate endpoints** (`POST /api/v3/attributes/assign-types/`, `POST /api/v3/attributes/assign-masks/`) when updating assignments on an existing attribute, or when the final assignment state is not known at creation time\n\n## Example Call\n\n```json\n{\n \"class_id\": 4,\n \"attributes\": [\n {\n \"tab_id\": 105,\n \"data_type\": \"short_text\",\n \"label\": \"Product Name\",\n \"code\": \"product_name\",\n \"configuration\": {\n \"required\": 1,\n \"multilingual\": 1\n },\n \"types\": [\n {\"type\": 12},\n {\"type\": 15, \"editability\": \"read_only\"}\n ],\n \"masks\": [\n {\"mask\": 1, \"permission\": \"write\"},\n {\"mask\": 2, \"permission\": \"read\"}\n ]\n },\n {\n \"tab_id\": 105,\n \"data_type\": \"integer\",\n \"label\": \"Weight\",\n \"code\": \"product_weight\",\n \"configuration\": {\n \"indexed\": 1\n }\n },\n {\n \"tab_id\": 106,\n \"data_type\": \"dropdown_items\",\n \"label\": \"Color\",\n \"code\": \"product_color\",\n \"configuration\": {\n \"list_values\": 12\n }\n }\n ]\n}\n```\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Batch create response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status_code": { "type": "integer", "example": 1, "description": "Status code (1 = all success, 2 = partial success, 3 = all failed)" }, "status_message": { "type": "string", "example": "3 attribute(s) created successfully", "description": "Summary message" }, "result": { "type": "object", "properties": { "created": { "type": "array", "description": "Array of successfully created attributes", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Created attribute ID" }, "code": { "type": "string", "description": "Attribute code" }, "label": { "type": "string", "description": "Attribute label" }, "data_type": { "type": "string", "description": "Attribute data type" }, "class_id": { "type": "integer", "description": "Library ID" }, "tab_id": { "type": "integer", "description": "Tab ID" }, "field_name": { "type": "string", "nullable": true, "description": "Database field name" }, "types": { "type": "object", "nullable": true, "description": "Present only if `types` was provided in the request. Absent otherwise.", "properties": { "attribute_id": { "type": "integer", "description": "Attribute ID" }, "types": { "type": "array", "description": "Per-type action results", "items": { "type": "object", "properties": { "type_id": { "type": "integer" }, "action": { "type": "string", "enum": [ "added", "unchanged" ] }, "editability": { "type": "string" }, "hidden": { "type": "boolean" } } } }, "total_added": { "type": "integer" }, "total_updated": { "type": "integer" }, "total_removed": { "type": "integer" }, "cache_refreshed": { "type": "boolean" }, "errors": { "type": "array", "description": "Per-entry errors (invalid type IDs/labels, missing fields). Attribute creation is NOT aborted by these errors.", "items": { "type": "string" } } } }, "masks": { "type": "object", "nullable": true, "description": "Present only if `masks` was provided in the request. Absent otherwise.", "properties": { "attribute_id": { "type": "integer", "description": "Attribute ID" }, "masks": { "type": "array", "description": "Per-mask action results", "items": { "type": "object", "properties": { "mask_id": { "type": "integer" }, "action": { "type": "string", "enum": [ "added", "updated", "removed", "unchanged" ] }, "permission": { "type": "string" }, "locally_editable": { "type": "boolean" } } } }, "total_added": { "type": "integer" }, "total_updated": { "type": "integer" }, "total_removed": { "type": "integer" }, "cache_refreshed": { "type": "boolean" }, "errors": { "type": "array", "description": "Per-entry errors (invalid mask IDs/labels, missing fields). Attribute creation is NOT aborted by these errors.", "items": { "type": "string" } } } } } } }, "errors": { "type": "array", "description": "Array of failed attributes with error details", "items": { "type": "object", "properties": { "index": { "type": "integer", "description": "Index in the original attributes array" }, "code": { "type": "string", "nullable": true, "description": "Attribute code (if provided)" }, "label": { "type": "string", "nullable": true, "description": "Attribute label (if provided)" }, "error": { "type": "string", "description": "Error message" } } } }, "total_requested": { "type": "integer", "description": "Total number of attributes requested" }, "total_created": { "type": "integer", "description": "Number of successfully created attributes" }, "total_errors": { "type": "integer", "description": "Number of failed attributes" } } } }, "required": [ "status_code", "status_message", "result" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "class_id": { "type": "integer", "description": "Library ID where all attributes will be created. Use POST /api/v3/administration/classes/list to get available libraries.", "example": 4 }, "attributes": { "type": "array", "description": "Array of attribute objects to create. Each object has the same structure as POST /api/v3/attributes/create/ parameters (except class_id which is defined at root level). (Array of objects - see example for structure)", "example": [ { "tab_id": 105, "data_type": "short_text", "label": "Product Name", "code": "product_name", "configuration": { "required": 1, "multilingual": 1 }, "types": [ { "type": 12 }, { "type": 15, "editability": "read_only" } ], "masks": [ { "mask": 1, "permission": "write" }, { "mask": 2, "permission": "read" } ] }, { "tab_id": 105, "data_type": "integer", "label": "Weight", "code": "product_weight" } ], "items": { "type": "object", "properties": { "tab_id": { "type": "integer", "description": "Tab ID where the attribute will be placed. Must belong to the specified class_id (validated server-side). Use POST /api/v3/attributes/tabs/list with class_id to get available tabs.", "example": 105 }, "data_type": { "type": "string", "description": "The attribute data type. Determines available configuration properties. Common types: short_text, dropdown_items, integer, decimal, boolean, date, asset_link, rich_text. Call POST /api/v3/attributes/schema/ to get the schema for a specific data_type.", "enum": [ "afs", "asset_link", "boolean", "checkbox", "counter", "data_table", "date", "datetime", "decimal", "dropdown_items", "dropdown_items_editable", "dynamic_afs", "dynamic_link", "ean", "email", "html", "integer", "long_text", "multi_dropdown_items", "passthrough", "price", "product_table", "radio_items", "rich_text", "short_text", "splitter", "url" ], "example": "short_text" }, "label": { "type": "string", "description": "Display label for the attribute. Maximum 255 characters.", "example": "Product Name" }, "code": { "type": "string", "description": "Unique code/identifier (XML code). Must start with a letter, contain only alphanumeric characters and underscores. Must be globally unique across all libraries.", "example": "product_name" }, "group_id": { "type": "integer", "description": "Group ID within the tab. Must belong to the specified tab_id. Omit to place the attribute outside any group.", "example": 81 }, "description": { "type": "string", "description": "Description of the attribute. Maximum 500 characters.", "example": "The main product name displayed to customers" }, "configuration": { "type": "object", "description": "Type-specific configuration properties. Available properties depend on the data_type. Key properties by type: dropdown_items/multi_dropdown_items/radio_items/checkbox_items require list_values; asset_link/dynamic_link require class_linked_id; afs requires afs (formula). Use POST /api/v3/attributes/schema/ for the complete schema per data_type.", "example": { "required": 1, "multilingual": 1, "character_limit": "0-255" } }, "types": { "type": "array", "description": "Optional. Record type assignments to apply after attribute creation. Each entry requires a `type` field (integer ID or string label from POST /api/v3/types/list). The `type` field accepts either an integer ID or a string label.", "items": { "type": "object", "properties": { "type": { "description": "Type ID (integer) or type label (string). Use POST /api/v3/types/list to get available types.", "example": 12 }, "editability": { "type": "string", "enum": [ "default", "read_only", "editable" ], "description": "Editability override for this type. Omit for library default." }, "hidden": { "type": "boolean", "description": "Set to true to hide this attribute in this type." } }, "required": [ "type" ] }, "example": [ { "type": 12 }, { "type": 15, "editability": "read_only", "hidden": false } ] }, "masks": { "type": "array", "description": "Optional. Display mask permission assignments to apply after attribute creation. Since the attribute is new, this is purely additive (same sync logic as POST /api/v3/attributes/assign-masks/ but no prior state to remove). Each entry requires a `mask` field (integer ID or string label) and a `permission` field.", "items": { "type": "object", "properties": { "mask": { "description": "Mask ID (integer) or mask label (string).", "example": 1 }, "permission": { "type": "string", "enum": [ "hidden", "read", "write" ], "description": "Permission level: \"hidden\" = not visible, \"read\" = read-only, \"write\" = editable." }, "locally_editable": { "type": "boolean", "description": "Only applicable when permission is \"write\". Allows editing of locally-inherited values." } }, "required": [ "mask", "permission" ] }, "example": [ { "mask": 1, "permission": "write" }, { "mask": 2, "permission": "read" } ] } }, "required": [ "tab_id", "data_type", "label", "code" ] } } }, "required": [ "class_id", "attributes" ] } } } } } }, "/api/v3/attributes/update/": { "post": { "tags": [ "attributes" ], "summary": "Update an existing attribute", "description": "## Purpose\n\nUpdates an existing attribute's properties. Only send the properties you want to change.\n\n## Immutable Fields (cannot be changed)\n\n- `code`: The unique identifier cannot be renamed\n- `data_type`: The data type cannot be changed after creation\n- `class_id`: The attribute cannot be moved to a different library\n\n## Workflow\n\n1. First call POST /api/v3/attributes/get/ with the parameter `id` to see current values\n2. Prepare only the properties you want to change\n3. Call this endpoint with parameter `id` and the changed properties\n\n## Parameter Structure\n\nParameters are organized in two levels:\n- **Root level**: `id` (required) + common properties (label, tab_id, group_id, description)\n- **configuration**: Object containing type-specific properties to update (same properties as create, all optional)\n\n## What Can Be Updated\n\n### Root Level Properties\n- `label`: Change the display label\n- `tab_id`: Move attribute to a different tab (must belong to same library)\n- `group_id`: Move attribute to a different group (must belong to the target tab). Set to 0 to remove from group.\n- `description`: Change the description\n\n### Configuration Properties (type-specific)\nAll configuration properties available for the attribute's data_type can be updated:\n- `required`, `multilingual`, `unique`, `indexed`, `editable`, `view_asset`\n- `character_limit`, `default_value`, `help`, `help_display`\n- `inheritable`, `default_inheritance`, `property`, `scope_id`\n- `ai_completion`, `ai_completion_config`\n- `list_values` (for dropdown_items types), `class_linked_id` (for link types)\n- And all other type-specific properties (see POST /api/v3/attributes/schema/)\n\n## Restrictions\n\n- System attributes (`system = true`) cannot be updated\n- Crossed data attributes have the same property restrictions as during creation\n- `inheritable` and `default_inheritance` remain mutually exclusive\n- Type-specific restrictions still apply (see create endpoint documentation)\n\n## Example: Update label and make required\n\n```json\n{\n \"id\": 456,\n \"label\": \"New Product Name\",\n \"configuration\": {\n \"required\": 1\n }\n}\n```\n\n## Example: Move attribute to different tab and group\n\n```json\n{\n \"id\": 456,\n \"tab_id\": 110,\n \"group_id\": 85\n}\n```\n\n## Common Errors\n\n- `Attribute not found: X` - the specified id does not exist\n- `System attributes cannot be updated` - attribute has system flag\n- `Tab not found: X` - the specified tab_id does not exist\n- `Tab X does not belong to class Y` - tab must belong to the attribute's library\n- `Group not found: X` - the specified group_id does not exist\n- `Group X does not belong to tab Y` - group must belong to the target tab\n- `Values list not found: X` - the specified list_values does not exist\n- `Values list X does not belong to class Y` - list must belong to the attribute's library\n- All validation errors from create also apply (type restrictions, dependency constraints, etc.)\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Update attribute 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": "Attribute updated successfully", "description": "Success message" }, "result": { "type": "object", "description": "Full attribute data after update (same format as GET endpoint)", "properties": { "id": { "type": "integer", "example": 456, "description": "Attribute ID" }, "code": { "type": "string", "example": "product_name", "description": "Attribute code" }, "label": { "type": "string", "example": "New Product Name", "description": "Updated attribute label" }, "data_type": { "type": "string", "example": "short_text", "description": "Attribute data type" }, "class_id": { "type": "integer", "example": 4, "description": "Library ID" }, "configuration": { "type": "object", "description": "Full type-specific configuration after update" } } } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Validation Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = validation error)" }, "status_message": { "type": "string", "example": "Attribute not found: 999", "description": "Validation error message" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array on error" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = update error)" }, "status_message": { "type": "string", "example": "Error updating attribute: ...", "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": "ID of the attribute to update. Use POST /api/v3/attributes/list/ or POST /api/v3/attributes/get/ to find attribute IDs.", "example": 456 }, "label": { "type": "string", "description": "New display label for the attribute. Maximum 255 characters.", "example": "New Product Name" }, "tab_id": { "type": "integer", "description": "Move attribute to this tab. Must belong to the same library as the attribute. Use POST /api/v3/attributes/tabs/list/ with class_id to get available tabs.", "example": 110 }, "group_id": { "type": "integer", "description": "Move attribute to this group. Must belong to the target tab (current or new tab_id). Set to 0 to remove from any group. Use POST /api/v3/attributes/groups/list/ with class_id and tab_id to get available groups.", "example": 85 }, "description": { "type": "string", "description": "New description for the attribute. Maximum 500 characters.", "example": "Updated product description field" }, "configuration": { "type": "object", "description": "Type-specific configuration properties to update. Only include properties you want to change. Available properties depend on the attribute's data_type. Use POST /api/v3/attributes/schema/ to see available properties for a data_type.", "example": { "required": 1, "multilingual": 1, "character_limit": "0-255" } } }, "required": [ "id" ] } } } } } }, "/api/v3/attributes/assign-types/": { "post": { "tags": [ "attributes" ], "summary": "Sync type assignments for an attribute (add, update, remove)", "description": "## Purpose\n\nSynchronizes which record types an attribute is assigned to, along with per-type display options. Send the **complete desired state** for this attribute: the endpoint computes a diff and applies additions, updates, and removals automatically.\n\n## Library Context\n\nThe library (class_id) is automatically derived from the attribute — no class_id parameter is required.\n\n## Sync Behavior\n\n- Type in the list but NOT currently assigned → **added**\n- Type currently assigned but NOT in the list → **removed**\n- Type in both → **updated** if options differ, **unchanged** if identical\n\nSending `assignments: []` removes the attribute from **all** types. Use with care.\n\n## Per-type options\n\nEach assignment entry supports two optional display options:\n\n**`editability`** — controls editability of the attribute value for this type:\n- `\"default\"` (default) — inherits the attribute's global editability setting\n- `\"read_only\"` — value is always read-only for this type, regardless of the global setting\n- `\"editable\"` — value is always editable for this type, regardless of the global setting\n\nOmitting `editability` is equivalent to `\"default\"`.\n\n**`hidden`** — hides the attribute in the interface for this type:\n- `false` (default) — attribute is visible\n- `true` — attribute is hidden in the interface for this type\n\nOmitting `hidden` is equivalent to `false`.\n\n## Partial Failures\n\nInvalid entries (unknown type ID or label, missing fields) do NOT fail the whole request — valid entries are still applied and `status_code` remains 1. All failures are reported in `result.errors`.\n\n## Accepts IDs or Labels\n\n`type`: integer (type ID) or string (type label, case-insensitive, use POST /api/v3/types/list with class_id to discover).\n\n## Related Endpoints\n\n- `attributes/types` — read current type assignments for an attribute\n- `types/assign-attributes` — inverse: given one type, sync all its attributes\n- `types/list` — list available types with their IDs and labels (requires class_id)\n\n## Complete workflow\n\n1. `attributes/tabs/create` - Create tab\n2. `attributes/groups/create` - Create group in tab\n3. `attributes/create` or `attributes/batch-create` - Create attribute(s)\n4. `attributes/assign-types` - Sync type assignments (you are here)\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Sync result response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Success Response", "properties": { "status_code": { "type": "integer", "example": 1, "description": "Always 1 for this endpoint, even when some entries failed (partial failures are reported in result.errors, not via status_code)" }, "status_message": { "type": "string", "example": "2 added, 1 updated, 1 removed", "description": "Summary of changes (e.g. \"2 added, 1 updated, 1 removed\"). Suffix \"(N error(s))\" is appended when result.errors is non-empty. \"No changes\" when nothing changed." }, "result": { "type": "object", "properties": { "attribute_id": { "type": "integer", "example": 456, "description": "Attribute ID" }, "types": { "type": "array", "description": "Per-type action details. Only covers types that were in the request or currently assigned — not all types in the system.", "items": { "type": "object", "properties": { "type_id": { "type": "integer", "example": 12, "description": "Resolved type ID" }, "action": { "type": "string", "enum": [ "added", "updated", "unchanged", "removed" ], "example": "added", "description": "Operation applied to this type assignment" }, "editability": { "type": "string", "enum": [ "default", "read_only", "editable" ], "example": "default", "description": "Reflects the value sent in the request (not the stored value). Absent when action is \"removed\"." }, "hidden": { "type": "boolean", "example": false, "description": "Reflects the value sent in the request (not the stored value). Absent when action is \"removed\"." } } } }, "total_added": { "type": "integer", "example": 2 }, "total_updated": { "type": "integer", "example": 1 }, "total_removed": { "type": "integer", "example": 1 }, "cache_refreshed": { "type": "boolean", "example": true }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Per-entry errors that did not block execution. Valid entries are still applied.", "example": [ "Type not found: inexistant" ] } } } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code 2 when attribute not found" }, "status_message": { "type": "string", "example": "Attribute \"999\" does not exist", "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": "Attribute ID. Use POST /api/v3/attributes/list with class_id to get available attribute IDs.", "example": 456 }, "assignments": { "type": "array", "description": "Complete desired type state for this attribute. Each entry must have \"type\" (integer ID or string label). Optional: \"editability\" (\"default\", \"read_only\", \"editable\") and \"hidden\" (boolean). WARNING: this is a SYNC operation — types not in this list will be REMOVED. (Array of objects - see example for structure)", "example": [ { "type": "PROJECTEURS", "editability": "editable", "hidden": false }, { "type": 12, "editability": "default", "hidden": true } ], "items": { "type": "object", "properties": { "type": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Type ID (integer) or type label (string, case-insensitive). Use POST /api/v3/types/list with class_id to discover.", "example": "PROJECTEURS" }, "editability": { "type": "string", "description": "Editability override for this type. Defaults to \"default\" (inherits global setting).", "enum": [ "default", "read_only", "editable" ], "example": "editable" }, "hidden": { "type": "boolean", "description": "Hide attribute in interface for this type. Defaults to false.", "example": false } }, "required": [ "type" ], "title": "Item" } } }, "required": [ "id", "assignments" ] } } } } } }, "/api/v3/attributes/assign-masks/": { "post": { "tags": [ "attributes" ], "summary": "Sync display mask permissions for an attribute (add, update, remove)", "description": "## Purpose\n\nSynchronizes display mask permissions for a single attribute. Send the **complete desired state** for all masks: the endpoint computes a diff and applies additions, updates, and removals automatically.\n\n## Library Context\n\nThe library (class_id) is automatically derived from the attribute — no class_id parameter is required.\n\n## Sync Behavior\n\n- Mask in request AND in DB → **updated** if permissions differ, **unchanged** if identical\n- Mask in request but NOT in DB → **added** (unless `permission: \"hidden\"`, which is a no-op)\n- Mask in DB but NOT in request → **removed**\n- Mask 10 (full display mask) is always ignored and cannot be modified\n\n## Partial Failures\n\nInvalid entries (unknown mask ID or label, missing fields, protected mask 10) do NOT fail the whole request — valid entries are still applied and `status_code` remains 1. All failures are reported in `result.errors`.\n\n## Permission Values\n\n- `\"hidden\"` — attribute is not visible in this mask (no entry in DB)\n- `\"read\"` — attribute is visible, read-only\n- `\"write\"` — attribute is visible and editable\n\n## locally_editable\n\nOnly applies when `permission: \"write\"`. When `true`, the attribute reference value can be edited locally in assetShare. Ignored for `hidden` and `read` (always stored as false).\n\n## Accepts IDs or Labels\n\n- `mask`: mask ID (integer or numeric string, e.g. `1024` or `\"1024\"`) or mask label (string, case-insensitive). Use `POST /api/v3/attributes/masks/` with the attribute id to discover currently assigned masks. To assign a mask not yet present on this attribute, use `POST /api/v3/permissions/masks/list/` to list all available masks with their IDs and labels.\n\n## Empty assignments\n\nSending `assignments: []` removes **all** mask permissions for this attribute (except mask 10, which is always protected). This is a destructive operation — use with care.\n\n## Related Endpoints\n\n- `attributes/masks` — read current mask permissions for an attribute\n- `permissions/masks/assign-attributes` — inverse: given one mask, sync all attributes of a library in that mask\n- `permissions/masks/list` — list all available display masks with IDs and labels\n- `attributes/assign-types` — sync type assignments for attributes in a library\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Sync result response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Success Response", "properties": { "status_code": { "type": "integer", "example": 1, "description": "Always 1 for this endpoint, even when some entries failed (partial failures are reported in result.errors, not via status_code)" }, "status_message": { "type": "string", "example": "2 added, 1 updated, 1 removed", "description": "Summary of changes (e.g. \"2 added, 1 updated, 1 removed\"). Suffix \"(N error(s))\" is appended when result.errors is non-empty. \"No changes\" when nothing changed." }, "result": { "type": "object", "properties": { "attribute_id": { "type": "integer", "example": 231, "description": "Attribute ID" }, "masks": { "type": "array", "description": "Per-mask action details. Only covers masks that were in the request or in DB — not the full list of all masks in the system.", "items": { "type": "object", "properties": { "mask_id": { "type": "integer", "example": 3 }, "action": { "type": "string", "enum": [ "added", "updated", "unchanged", "removed" ], "example": "added" }, "permission": { "type": "string", "enum": [ "read", "write" ], "description": "Absent when action is \"removed\". Always false for locally_editable when permission is \"read\".", "example": "write" }, "locally_editable": { "type": "boolean", "description": "Absent when action is \"removed\". Always false when permission is \"read\".", "example": true } } } }, "total_added": { "type": "integer", "example": 2 }, "total_updated": { "type": "integer", "example": 1 }, "total_removed": { "type": "integer", "example": 1 }, "cache_refreshed": { "type": "boolean", "example": true }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Per-entry errors that did not block execution. Valid entries are still applied.", "example": [ "Mask not found: Masque inexistant", "Mask 10 (full display mask) cannot be modified" ] } } } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = error)" }, "status_message": { "type": "string", "example": "Attribute \"999\" does not exist", "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": "Attribute ID. Use POST /api/v3/attributes/list with class_id to get available attribute IDs.", "example": 231 }, "assignments": { "type": "array", "description": "Complete desired mask state for this attribute. Each entry must have \"mask\" (integer ID or string label — use POST /api/v3/attributes/masks/ with the attribute id to get currently assigned mask IDs and labels) and \"permission\" (\"hidden\", \"read\", or \"write\"). Optionally include \"locally_editable\" (boolean, only effective with \"write\"). WARNING: this is a SYNC operation — masks in DB but not in this list will be REMOVED. Mask ID 10 (full display mask) is always protected — any entry targeting mask 10 will be ignored and reported in \"errors\". (Array of objects - see example for structure)", "items": { "type": "object", "properties": { "mask": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Mask ID (integer or numeric string, e.g. 1024 or \"1024\") or mask label (string, case-insensitive, e.g. \"Masque commercial\"). Use POST /api/v3/attributes/masks/ with the attribute id to get currently assigned masks.", "example": 1024 }, "permission": { "type": "string", "description": "Desired permission level for this attribute in the mask.", "enum": [ "hidden", "read", "write" ], "example": "write" }, "locally_editable": { "type": "boolean", "description": "Only effective when permission is \"write\". Defaults to false.", "example": true } }, "required": [ "mask", "permission" ], "title": "Item" } } }, "required": [ "id", "assignments" ] } } } } } }, "/api/v3/export/get-file/": { "post": { "tags": [ "export" ], "summary": "Get export file by queue ID", "description": "## Purpose\n\nReturns file information (name, size, URL) for a completed export using the queue_id.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Export file", "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": "object", "properties": { "file": { "type": "string", "example": "export_20250901_120000.csv", "description": "File name" }, "extension": { "type": "string", "example": "csv", "description": "File extension" }, "size": { "type": "integer", "example": 10000, "description": "File size (in bytes)" }, "file_url": { "type": "string", "example": "https://my-afineo.com/gallery/global/dl/files/export_20250901_120000.csv", "description": "File url" } }, "required": [ "file", "extension", "size", "file_url" ], "description": "Generated file information" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (2 = Parameters error, 3 = No file found / Export is running / ...)" }, "status_message": { "type": "string", "example": "No file found", "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": { "queue_id": { "type": "integer", "description": "Queue ID returned by export/jobs-by-mapping endpoints. Use this to retrieve the generated export file after async processing completes. Workflow: 1) Call jobs-by-mapping → get queue_id, 2) Poll queues/get until status=\"finished\", 3) Call this endpoint to download.", "example": 50 } }, "required": [ "queue_id" ] } } } } } }, "/api/v3/export/by-mapping/repository/": { "post": { "tags": [ "export" ], "summary": "Export repository data by mapping", "description": "## Purpose\n\nExports repository assets to JSON using a preconfigured mapping with pagination and filters.\n\n## Format Options\n\n- `simple`: Standard attribute format (default)\n- `composed`: Recursive JSON structure\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON export 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": "object", "properties": { "results_total": { "type": "integer", "example": 15, "description": "Total number of items" }, "items": { "type": "array", "items": { "type": "object" }, "description": "Export data" }, "num_page": { "type": "integer", "nullable": true, "example": 1, "description": "Current page number" }, "nb_pages": { "type": "integer", "nullable": true, "example": 15, "description": "Total number of pages" }, "results_per_page": { "type": "integer", "nullable": true, "example": 100, "description": "Number of results per page" } }, "required": [ "results_total", "items" ], "description": "Export result" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = Export result not valid / Export error / ...)" }, "status_message": { "type": "string", "example": "Export result not valid", "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 }, "parent_id": { "type": "integer", "description": "Parent asset ID in repository. Use POST /api/v3/get-asset/by-search/repository to find assets. Set to 0 for repository root.", "example": 4350 }, "mapping_id": { "type": "integer", "description": "Mapping ID. Use POST /api/v3/mappings/list/ with class_id to discover available mappings for a given class.", "example": 23 }, "num_page": { "type": "integer", "description": "Page number for pagination. Must be used together with results_per_page.", "example": 3 }, "results_per_page": { "type": "integer", "description": "Number of results per page (between 10 and 1000). Must always be provided together with \"num_page\".", "example": 50 }, "version_id": { "type": "integer", "description": "Version ID. Use POST /api/v3/administration/versions/list with class_id to get available versions.", "example": 1 }, "exclude_inherited_values": { "type": "boolean", "description": "If it is true, only the direct values of the asset are exported (excludes values that have not been filled directly in the asset : values inherited from a parent, or from the repository in the case of a contextual asset, or calculated values)", "example": true }, "research": { "type": "array", "description": "Array of attribute filters. Each filter has attribute_id, operator, value, and optional link. IMPORTANT: When using \"research\", \"filters.types_id\" or \"filters.supertypes_id\" must also be provided. (Array of objects - see example for structure)", "example": [ { "attribute_id": 1234, "operator": "contains", "value": "Prefix_" }, { "link": "or", "attribute_id": 2465, "operator": "contains", "value": "Prefix_" } ], "items": { "type": "object", "properties": { "attribute_id": { "type": "integer", "description": "Attribute ID. Use POST /api/v3/attributes/list with class_id to get available attributes.", "example": 231 }, "operator": { "type": "string", "description": "Search operator: equal/notequal (exact match), contains/notcontains (partial), startby/endby (prefix/suffix), isnull/isnotnull (empty check), greater/atleast/lesser/nomore (numeric), between (range).", "enum": [ "equal", "notequal", "contains", "notcontains", "startby", "endby", "notstartby", "notendby", "isnull", "isnotnull", "greater", "atleast", "lesser", "nomore", "between", "isinlist", "isnotinlist" ], "example": "between" }, "value": { "type": "string", "description": "Value (only if operator is not \"isnull\" and \"isnotnull\") **⚠️ Required when:** `operator` = `equal` | `notequal` | `contains` | `notcontains` | `startby` | `endby` | `notstartby` | `notendby` | `greater` | `atleast` | `lesser` | `nomore` | `between` | `isinlist` | `isnotinlist`", "example": "12345", "x-conditional-required": { "operator": [ "equal", "notequal", "contains", "notcontains", "startby", "endby", "notstartby", "notendby", "greater", "atleast", "lesser", "nomore", "between", "isinlist", "isnotinlist" ] } }, "value2": { "type": "string", "description": "Second value for range search. Required only when operator is \"between\" **⚠️ Required when:** `operator` = `between`", "example": "12346", "x-conditional-required": { "operator": [ "between" ] } }, "link": { "type": "string", "description": "Logical link between filters: \"and\" (all conditions must match) or \"or\" (any condition matches). Default: \"and\".", "enum": [ "and", "or" ], "example": "and" } }, "required": [ "attribute_id", "operator" ], "title": "Item" } }, "filters": { "type": "object", "description": "Filter object with types_id, supertypes_id, status_id, creausers, users, workflow_step_id, date filters. IMPORTANT: When using \"research\" or \"filters\", at least \"types_id\" or \"supertypes_id\" must be provided.", "example": { "supertypes_id": [ 2 ], "types_id": [ 257, 258 ], "time": "2024-12-17T10:30:00Z", "workflow_step_id": 10 }, "properties": { "types_id": { "type": "array", "description": "List of asset type IDs. Required when using \"research\" or \"filters\" (unless supertypes_id is provided). Use POST /api/v3/types/list with class_id to get available types.", "example": [ 257, 258 ], "items": { "type": "integer" } }, "supertypes_id": { "type": "array", "description": "List of supertype IDs (parent category of asset types). All child types of these supertypes will be included. Required when using \"research\" or \"filters\" (unless types_id is provided). Can be combined with types_id. Available supertypes: 1 (Groupe de fiches), 2 (Fiche), 3 (Dossier), 4 (Page), 5 (Publication), 6 (Workspace), 7 (Article), 8 (Variation de produit)", "example": [ 1, 2 ], "items": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] } }, "status_id": { "type": "array", "description": "List of asset status IDs. Use POST /api/v3/permissions/statuses/list with class_id to get available statuses.", "example": [ 1287, 1288 ], "items": { "type": "integer" } }, "creausers": { "type": "array", "description": "List of user IDs who created assets. Use POST /api/v3/permissions/groups/list to get user groups.", "example": [ 1485, 1535 ], "items": { "type": "integer" } }, "users": { "type": "array", "description": "List of user IDs who last modified assets. Use POST /api/v3/permissions/groups/list to get user groups.", "example": [ 1485, 1535 ], "items": { "type": "integer" } }, "workflow_step_id": { "type": "integer", "description": "Workflow step ID. Use POST /api/v3/workflows/list/repository/ with class_id to get workflows and their steps.", "example": 10 }, "creatime": { "type": "string", "description": "Minimum creation date of the asset (ISO 8601 format). Used to filter assets created from this date.", "example": "2024-12-17T10:30:00Z" }, "creatimeend": { "type": "string", "description": "Maximum creation date of the asset (ISO 8601 format). Used to filter assets created up to this date.", "example": "2024-12-17T23:59:59Z" }, "time": { "type": "string", "description": "Minimum update date of the asset (ISO 8601 format). Used to filter assets updated from this date.", "example": "2024-12-17T10:30:00Z" }, "timeend": { "type": "string", "description": "Maximum update date of the asset (ISO 8601 format). Used to filter assets updated up to this date.", "example": "2024-12-17T23:59:59Z" }, "search_find": { "type": "string", "description": "Quick search text. Searches across indexed attributes for matching content.", "example": "My product label" }, "split_find": { "type": "string", "description": "Fast search mode: \"all_words\" (all words must be present), \"each_word\" (any word matches), \"exact_expression\" (exact phrase match).", "enum": [ "all_words", "each_word", "exact_expression" ], "example": "each_word" } } }, "format": { "type": "string", "description": "JSON format: \"simple\" (flat attribute list) or \"composed\" (recursive structure). Default: simple.", "enum": [ "simple", "composed" ], "example": "composed" } }, "required": [ "class_id", "mapping_id", "num_page", "results_per_page" ] } } } } } }, "/api/v3/export/by-mapping/node/": { "post": { "tags": [ "export" ], "summary": "Export project node data by mapping", "description": "## Purpose\n\nExports project-contextualized assets to JSON using a mapping with pagination and filters.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON export 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": "object", "properties": { "results_total": { "type": "integer", "example": 15, "description": "Total number of items" }, "items": { "type": "array", "items": { "type": "object" }, "description": "Export data" }, "num_page": { "type": "integer", "nullable": true, "example": 1, "description": "Current page number" }, "nb_pages": { "type": "integer", "nullable": true, "example": 15, "description": "Total number of pages" }, "results_per_page": { "type": "integer", "nullable": true, "example": 100, "description": "Number of results per page" } }, "required": [ "results_total", "items" ], "description": "Export result" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = Export result not valid / Export error / ...)" }, "status_message": { "type": "string", "example": "Export result not valid", "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 }, "parent_id": { "type": "integer", "description": "Parent node ID in project. Use POST /api/v3/get-asset/by-search/node to find project nodes.", "example": 4350 }, "mapping_id": { "type": "integer", "description": "Mapping ID. Use POST /api/v3/mappings/list/ with class_id to discover available mappings for a given class.", "example": 23 }, "num_page": { "type": "integer", "description": "Page number for pagination. Must be used together with results_per_page.", "example": 3 }, "results_per_page": { "type": "integer", "description": "Number of results per page (between 10 and 1000). Must always be provided together with \"num_page\".", "example": 50 }, "version_id": { "type": "integer", "description": "Version ID. Use POST /api/v3/administration/versions/list with class_id to get available versions.", "example": 1 }, "exclude_inherited_values": { "type": "boolean", "description": "If it is true, only the direct values of the asset are exported (excludes values that have not been filled directly in the asset : values inherited from a parent, or from the repository in the case of a contextual asset, or calculated values)", "example": true }, "research": { "type": "array", "description": "Array of attribute filters. Each filter has attribute_id, operator, value, and optional link. IMPORTANT: When using \"research\", \"filters.types_id\" or \"filters.supertypes_id\" must also be provided. (Array of objects - see example for structure)", "example": [ { "attribute_id": 1234, "operator": "contains", "value": "Prefix_" }, { "link": "or", "attribute_id": 2465, "operator": "contains", "value": "Prefix_" } ], "items": { "type": "object", "properties": { "attribute_id": { "type": "integer", "description": "Attribute ID. Use POST /api/v3/attributes/list with class_id to get available attributes.", "example": 231 }, "operator": { "type": "string", "description": "Search operator: equal/notequal (exact match), contains/notcontains (partial), startby/endby (prefix/suffix), isnull/isnotnull (empty check), greater/atleast/lesser/nomore (numeric), between (range).", "enum": [ "equal", "notequal", "contains", "notcontains", "startby", "endby", "notstartby", "notendby", "isnull", "isnotnull", "greater", "atleast", "lesser", "nomore", "between", "isinlist", "isnotinlist" ], "example": "between" }, "value": { "type": "string", "description": "Value (only if operator is not \"isnull\" and \"isnotnull\") **⚠️ Required when:** `operator` = `equal` | `notequal` | `contains` | `notcontains` | `startby` | `endby` | `notstartby` | `notendby` | `greater` | `atleast` | `lesser` | `nomore` | `between` | `isinlist` | `isnotinlist`", "example": "12345", "x-conditional-required": { "operator": [ "equal", "notequal", "contains", "notcontains", "startby", "endby", "notstartby", "notendby", "greater", "atleast", "lesser", "nomore", "between", "isinlist", "isnotinlist" ] } }, "value2": { "type": "string", "description": "Second value for range search. Required only when operator is \"between\" **⚠️ Required when:** `operator` = `between`", "example": "12346", "x-conditional-required": { "operator": [ "between" ] } }, "link": { "type": "string", "description": "Logical link between filters: \"and\" (all conditions must match) or \"or\" (any condition matches). Default: \"and\".", "enum": [ "and", "or" ], "example": "and" } }, "required": [ "attribute_id", "operator" ], "title": "Item" } }, "filters": { "type": "object", "description": "Filter object with types_id, supertypes_id, status_id, creausers, users, workflow_step_id, date filters. IMPORTANT: When using \"research\" or \"filters\", at least \"types_id\" or \"supertypes_id\" must be provided.", "example": { "supertypes_id": [ 2 ], "types_id": [ 257, 258 ], "time": "2024-12-17T10:30:00Z", "workflow_step_id": 10 }, "properties": { "types_id": { "type": "array", "description": "List of asset type IDs. Required when using \"research\" or \"filters\" (unless supertypes_id is provided). Use POST /api/v3/types/list with class_id to get available types.", "example": [ 257, 258 ], "items": { "type": "integer" } }, "supertypes_id": { "type": "array", "description": "List of supertype IDs (parent category of asset types). All child types of these supertypes will be included. Required when using \"research\" or \"filters\" (unless types_id is provided). Can be combined with types_id. Available supertypes: 1 (Groupe de fiches), 2 (Fiche), 3 (Dossier), 4 (Page), 5 (Publication), 6 (Workspace), 7 (Article), 8 (Variation de produit)", "example": [ 1, 2 ], "items": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] } }, "status_id": { "type": "array", "description": "List of asset status IDs. Use POST /api/v3/permissions/statuses/list with class_id to get available statuses.", "example": [ 1287, 1288 ], "items": { "type": "integer" } }, "creausers": { "type": "array", "description": "List of user IDs who created assets. Use POST /api/v3/permissions/groups/list to get user groups.", "example": [ 1485, 1535 ], "items": { "type": "integer" } }, "users": { "type": "array", "description": "List of user IDs who last modified assets. Use POST /api/v3/permissions/groups/list to get user groups.", "example": [ 1485, 1535 ], "items": { "type": "integer" } }, "workflow_step_id": { "type": "integer", "description": "Workflow step ID. Use POST /api/v3/workflows/list/node/ with project_node_id and class_id to get workflows and their steps.", "example": 10 }, "creatime": { "type": "string", "description": "Minimum creation date of the asset (ISO 8601 format). Used to filter assets created from this date", "example": "2024-12-17T10:30:00Z" }, "creatimeend": { "type": "string", "description": "Maximum creation date of the asset (ISO 8601 format). Used to filter assets created up to this date", "example": "2024-12-17T23:59:59Z" }, "time": { "type": "string", "description": "Minimum update date of the asset (ISO 8601 format). Used to filter assets updated from this date", "example": "2024-12-17T10:30:00+02:00" }, "timeend": { "type": "string", "description": "Maximum update date of the asset (ISO 8601 format). Used to filter assets updated up to this date", "example": "2024-12-17T23:59:59+02:00" }, "search_find": { "type": "string", "description": "Quick search text. Searches across indexed attributes for matching content.", "example": "My product label" }, "split_find": { "type": "string", "description": "Fast search mode: \"all_words\" (all words must be present), \"each_word\" (any word matches), \"exact_expression\" (exact phrase match).", "enum": [ "all_words", "each_word", "exact_expression" ], "example": "each_word" }, "alias": { "type": "string", "description": "Alias filter: \"only_aliases\" (return only alias nodes), \"except_aliases\" (exclude alias nodes). Default: include all.", "enum": [ "only_aliases", "except_aliases" ], "example": "only_aliases" } } }, "format": { "type": "string", "description": "JSON format: \"simple\" (flat attribute list) or \"composed\" (recursive structure). Default: simple.", "enum": [ "simple", "composed" ], "example": "composed" } }, "required": [ "class_id", "parent_id", "mapping_id", "num_page", "results_per_page" ] } } } } } }, "/api/v3/export/jobs-by-mapping/repository/": { "post": { "tags": [ "export" ], "summary": "Async export repository to file", "description": "## Purpose\n\nGenerates file export from repository (CSV/XLS/XLSX/TXT/XML/JSON). Returns queue_id for async processing.\n\n## Workflow\n\nUse `export/get-file` with queue_id to download completed file.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "File export 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": "object", "properties": { "queue_id": { "type": "integer", "example": 47593, "description": "Queue ID for async file retrieval via export/get-file" } }, "required": [ "queue_id" ], "description": "Queue information" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = error)" }, "status_message": { "type": "string", "example": "Export error", "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 }, "parent_id": { "type": "integer", "description": "Parent asset ID in repository. Use POST /api/v3/get-asset/by-search/repository to find assets. Set to 0 for repository root.", "example": 4350 }, "mapping_id": { "type": "integer", "description": "Mapping ID. Use POST /api/v3/mappings/list/ with class_id to discover available mappings for a given class.", "example": 23 }, "version_id": { "type": "integer", "description": "Version ID. Use POST /api/v3/administration/versions/list with class_id to get available versions.", "example": 1 }, "exclude_inherited_values": { "type": "boolean", "description": "If it is true, only the direct values of the asset are exported (excludes values that have not been filled directly in the asset : values inherited from a parent, or from the repository in the case of a contextual asset, or calculated values)", "example": true }, "research": { "type": "array", "description": "Array of attribute filters. Each filter has attribute_id, operator, value, and optional link. IMPORTANT: When using \"research\", \"filters.types_id\" or \"filters.supertypes_id\" must also be provided. (Array of objects - see example for structure)", "example": [ { "attribute_id": 1234, "operator": "contains", "value": "Prefix_" }, { "link": "or", "attribute_id": 2465, "operator": "contains", "value": "Prefix_" } ], "items": { "type": "object", "properties": { "attribute_id": { "type": "integer", "description": "Attribute ID. Use POST /api/v3/attributes/list with class_id to get available attributes.", "example": 231 }, "operator": { "type": "string", "description": "Search operator: equal/notequal (exact match), contains/notcontains (partial), startby/endby (prefix/suffix), isnull/isnotnull (empty check), greater/atleast/lesser/nomore (numeric), between (range).", "enum": [ "equal", "notequal", "contains", "notcontains", "startby", "endby", "notstartby", "notendby", "isnull", "isnotnull", "greater", "atleast", "lesser", "nomore", "between", "isinlist", "isnotinlist" ], "example": "between" }, "value": { "type": "string", "description": "Value (only if operator is not \"isnull\" and \"isnotnull\") **⚠️ Required when:** `operator` = `equal` | `notequal` | `contains` | `notcontains` | `startby` | `endby` | `notstartby` | `notendby` | `greater` | `atleast` | `lesser` | `nomore` | `between` | `isinlist` | `isnotinlist`", "example": "12345", "x-conditional-required": { "operator": [ "equal", "notequal", "contains", "notcontains", "startby", "endby", "notstartby", "notendby", "greater", "atleast", "lesser", "nomore", "between", "isinlist", "isnotinlist" ] } }, "value2": { "type": "string", "description": "Second value for range search. Required only when operator is \"between\" **⚠️ Required when:** `operator` = `between`", "example": "12346", "x-conditional-required": { "operator": [ "between" ] } }, "link": { "type": "string", "description": "Logical link between filters: \"and\" (all conditions must match) or \"or\" (any condition matches). Default: \"and\".", "enum": [ "and", "or" ], "example": "and" } }, "required": [ "attribute_id", "operator" ], "title": "Item" } }, "filters": { "type": "object", "description": "Filter object with types_id, supertypes_id, status_id, creausers, users, workflow_step_id, date filters. IMPORTANT: When using \"research\" or \"filters\", at least \"types_id\" or \"supertypes_id\" must be provided.", "example": { "supertypes_id": [ 2 ], "types_id": [ 257, 258 ], "time": "2024-12-17T10:30:00Z", "workflow_step_id": 10 }, "properties": { "types_id": { "type": "array", "description": "List of asset type IDs. Required when using \"research\" or \"filters\" (unless supertypes_id is provided). Use POST /api/v3/types/list with class_id to get available types.", "example": [ 257, 258 ], "items": { "type": "integer" } }, "supertypes_id": { "type": "array", "description": "List of supertype IDs (parent category of asset types). All child types of these supertypes will be included. Required when using \"research\" or \"filters\" (unless types_id is provided). Can be combined with types_id. Available supertypes: 1 (Groupe de fiches), 2 (Fiche), 3 (Dossier), 4 (Page), 5 (Publication), 6 (Workspace), 7 (Article), 8 (Variation de produit)", "example": [ 1, 2 ], "items": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] } }, "status_id": { "type": "array", "description": "List of asset status IDs. Use POST /api/v3/permissions/statuses/list with class_id to get available statuses.", "example": [ 1287, 1288 ], "items": { "type": "integer" } }, "creausers": { "type": "array", "description": "List of user IDs who created assets. Use POST /api/v3/permissions/groups/list to get user groups.", "example": [ 1485, 1535 ], "items": { "type": "integer" } }, "users": { "type": "array", "description": "List of user IDs who last modified assets. Use POST /api/v3/permissions/groups/list to get user groups.", "example": [ 1485, 1535 ], "items": { "type": "integer" } }, "workflow_step_id": { "type": "integer", "description": "Workflow step ID. Use POST /api/v3/workflows/list/repository/ with class_id to get workflows and their steps.", "example": 10 }, "creatime": { "type": "string", "description": "Minimum creation date of the asset (ISO 8601 format). Used to filter assets created from this date", "example": "2024-12-17T10:30:00Z" }, "creatimeend": { "type": "string", "description": "Maximum creation date of the asset (ISO 8601 format). Used to filter assets created up to this date", "example": "2024-12-17T23:59:59Z" }, "time": { "type": "string", "description": "Minimum update date of the asset (ISO 8601 format). Used to filter assets updated from this date", "example": "2024-12-17T10:30:00+02:00" }, "timeend": { "type": "string", "description": "Maximum update date of the asset (ISO 8601 format). Used to filter assets updated up to this date", "example": "2024-12-17T23:59:59+02:00" }, "search_find": { "type": "string", "description": "Quick search text. Searches across indexed attributes for matching content.", "example": "My product label" }, "split_find": { "type": "string", "description": "Fast search mode: \"all_words\" (all words must be present), \"each_word\" (any word matches), \"exact_expression\" (exact phrase match).", "enum": [ "all_words", "each_word", "exact_expression" ], "example": "each_word" } } }, "format": { "type": "string", "description": "Export file format: \"csv\", \"xlsx\", \"xml\", \"json\". Default: csv.", "enum": [ "csv", "xls", "xlsx", "txt", "xml", "json", "json_composed" ], "example": "xlsx" } }, "required": [ "class_id", "mapping_id" ] } } } } } }, "/api/v3/export/jobs-by-mapping/node/": { "post": { "tags": [ "export" ], "summary": "Async export project node to file", "description": "## Purpose\n\nGenerates file export from project-contextualized data (CSV/XLS/XLSX/TXT/XML/JSON). Returns queue_id for async processing.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "File export 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": "object", "properties": { "queue_id": { "type": "integer", "example": 47593, "description": "Queue ID for async file retrieval via export/get-file" } }, "required": [ "queue_id" ], "description": "Queue information" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = error)" }, "status_message": { "type": "string", "example": "Export error", "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 }, "parent_id": { "type": "integer", "description": "Parent node ID in project. Use POST /api/v3/get-asset/by-search/node to find project nodes.", "example": 4350 }, "mapping_id": { "type": "integer", "description": "Mapping ID. Use POST /api/v3/mappings/list/ with class_id to discover available mappings for a given class.", "example": 23 }, "version_id": { "type": "integer", "description": "Version ID. Use POST /api/v3/administration/versions/list with class_id to get available versions.", "example": 1 }, "exclude_inherited_values": { "type": "boolean", "description": "If it is true, only the direct values of the asset are exported (excludes values that have not been filled directly in the asset : values inherited from a parent, or from the repository in the case of a contextual asset, or calculated values)", "example": true }, "research": { "type": "array", "description": "Array of attribute filters. Each filter has attribute_id, operator, value, and optional link. IMPORTANT: When using \"research\", \"filters.types_id\" or \"filters.supertypes_id\" must also be provided. (Array of objects - see example for structure)", "example": [ { "attribute_id": 1234, "operator": "contains", "value": "Prefix_" }, { "link": "or", "attribute_id": 2465, "operator": "contains", "value": "Prefix_" } ], "items": { "type": "object", "properties": { "attribute_id": { "type": "integer", "description": "Attribute ID. Use POST /api/v3/attributes/list with class_id to get available attributes.", "example": 231 }, "operator": { "type": "string", "description": "Search operator: equal/notequal (exact match), contains/notcontains (partial), startby/endby (prefix/suffix), isnull/isnotnull (empty check), greater/atleast/lesser/nomore (numeric), between (range).", "enum": [ "equal", "notequal", "contains", "notcontains", "startby", "endby", "notstartby", "notendby", "isnull", "isnotnull", "greater", "atleast", "lesser", "nomore", "between", "isinlist", "isnotinlist" ], "example": "between" }, "value": { "type": "string", "description": "Value (only if operator is not \"isnull\" and \"isnotnull\") **⚠️ Required when:** `operator` = `equal` | `notequal` | `contains` | `notcontains` | `startby` | `endby` | `notstartby` | `notendby` | `greater` | `atleast` | `lesser` | `nomore` | `between` | `isinlist` | `isnotinlist`", "example": "12345", "x-conditional-required": { "operator": [ "equal", "notequal", "contains", "notcontains", "startby", "endby", "notstartby", "notendby", "greater", "atleast", "lesser", "nomore", "between", "isinlist", "isnotinlist" ] } }, "value2": { "type": "string", "description": "Second value for range search. Required only when operator is \"between\" **⚠️ Required when:** `operator` = `between`", "example": "12346", "x-conditional-required": { "operator": [ "between" ] } }, "link": { "type": "string", "description": "Logical link between filters: \"and\" (all conditions must match) or \"or\" (any condition matches). Default: \"and\".", "enum": [ "and", "or" ], "example": "and" } }, "required": [ "attribute_id", "operator" ], "title": "Item" } }, "filters": { "type": "object", "description": "Filter object with types_id, supertypes_id, status_id, creausers, users, workflow_step_id, date filters. IMPORTANT: When using \"research\" or \"filters\", at least \"types_id\" or \"supertypes_id\" must be provided.", "example": { "supertypes_id": [ 2 ], "types_id": [ 257, 258 ], "time": "2024-12-17T10:30:00Z", "workflow_step_id": 10 }, "properties": { "types_id": { "type": "array", "description": "List of asset type IDs. Required when using \"research\" or \"filters\" (unless supertypes_id is provided). Use POST /api/v3/types/list with class_id to get available types.", "example": [ 257, 258 ], "items": { "type": "integer" } }, "supertypes_id": { "type": "array", "description": "List of supertype IDs (parent category of asset types). All child types of these supertypes will be included. Required when using \"research\" or \"filters\" (unless types_id is provided). Can be combined with types_id. Available supertypes: 1 (Groupe de fiches), 2 (Fiche), 3 (Dossier), 4 (Page), 5 (Publication), 6 (Workspace), 7 (Article), 8 (Variation de produit)", "example": [ 1, 2 ], "items": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ] } }, "status_id": { "type": "array", "description": "List of asset status IDs. Use POST /api/v3/permissions/statuses/list with class_id to get available statuses.", "example": [ 1287, 1288 ], "items": { "type": "integer" } }, "creausers": { "type": "array", "description": "List of user IDs who created assets. Use POST /api/v3/permissions/groups/list to get user groups.", "example": [ 1485, 1535 ], "items": { "type": "integer" } }, "users": { "type": "array", "description": "List of user IDs who last modified assets. Use POST /api/v3/permissions/groups/list to get user groups.", "example": [ 1485, 1535 ], "items": { "type": "integer" } }, "workflow_step_id": { "type": "integer", "description": "Workflow step ID. Use POST /api/v3/workflows/list/node/ with project_node_id and class_id to get workflows and their steps.", "example": 10 }, "creatime": { "type": "string", "description": "Minimum creation date of the asset (ISO 8601 format). Used to filter assets created from this date", "example": "2024-12-17T10:30:00Z" }, "creatimeend": { "type": "string", "description": "Maximum creation date of the asset (ISO 8601 format). Used to filter assets created up to this date", "example": "2024-12-17T23:59:59Z" }, "time": { "type": "string", "description": "Minimum update date of the asset (ISO 8601 format). Used to filter assets updated from this date", "example": "2024-12-17T10:30:00+02:00" }, "timeend": { "type": "string", "description": "Maximum update date of the asset (ISO 8601 format). Used to filter assets updated up to this date", "example": "2024-12-17T23:59:59+02:00" }, "search_find": { "type": "string", "description": "Quick search text. Searches across indexed attributes for matching content.", "example": "My product label" }, "split_find": { "type": "string", "description": "Fast search mode: \"all_words\" (all words must be present), \"each_word\" (any word matches), \"exact_expression\" (exact phrase match).", "enum": [ "all_words", "each_word", "exact_expression" ], "example": "each_word" }, "alias": { "type": "string", "description": "Alias filter: \"only_aliases\" (return only alias nodes), \"except_aliases\" (exclude alias nodes). Default: include all.", "enum": [ "only_aliases", "except_aliases" ], "example": "only_aliases" } } }, "format": { "type": "string", "description": "Export file format: \"csv\", \"xlsx\", \"xml\", \"json\". Default: csv.", "enum": [ "csv", "xls", "xlsx", "txt", "xml", "json", "json_composed" ], "example": "xlsx" } }, "required": [ "class_id", "parent_id", "mapping_id" ] } } } } } }, "/api/v3/export/easycatalog/": { "post": { "tags": [ "export" ], "summary": "Export for EasyCatalog InDesign", "description": "## Description\n\nGenerates InDesign-compatible export for EasyCatalog plugin. Returns formatted data for print catalog production. Supports column mapping discovery, first result preview, and thematiques listing.\n\n## Parameters\n\n| Parameter Name | Description |\n|---------------------------|--------------------------------------------|\n| class_id | Class ID |\n| node_id | Node ID |\n| action | Action : export (classic export), columns_mapping (list of mapping columns), first_result (first export result) or get_themes (list of thematiques for the project) |\n| mapping_id (optional) | Mapping ID |\n| version_id (optional) | Version ID |\n| page_start (optional) | Start page number |\n| page_end (optional) | End page number |\n| thematique_id (optional) | Thematique ID (mutually exclusive with page_start/page_end) |\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Export 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": "object", "properties": { "results_total": { "type": "integer", "example": 15, "description": "Number of items" }, "items": { "type": "array", "items": { "type": "object" }, "example": [ { "Id Fiche": "651165", "Id Node": "884168", "Désignation produit": "Product 1" }, { "Id Fiche": "651166", "Id Node": "884172", "Désignation produit": "Product 2" } ] } }, "required": [ "results_total", "items" ], "description": "Generated content" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (997 = You cannot access this project, 2 = Node does not exist or has been deleted / Project not found / ...)" }, "status_message": { "type": "string", "example": "Project not found", "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 }, "node_id": { "type": "integer", "description": "Publication project node ID. Use POST /api/v3/publishing/list with class_id to find publication projects and get their node_id.", "example": 4350 }, "action": { "type": "string", "description": "Depending on the filled action, the result will be different : \"export\" (classic export), \"columns_mapping\" (list of mapping columns), \"first_result\" (first export result), \"get_themes\" (list of thematiques for the project)", "enum": [ "export", "columns_mapping", "first_result", "get_themes" ], "example": "export" }, "mapping_id": { "type": "integer", "description": "Mapping ID. Use POST /api/v3/mappings/list/ with class_id to discover available mappings for a given class.", "example": 23 }, "version_id": { "type": "integer", "description": "Version ID. Use POST /api/v3/administration/versions/list with class_id to get available versions.", "example": 1 }, "page_start": { "type": "integer", "description": "Start page number to filter export. Can be used alone (single page) or with page_end (interval). Mutually exclusive with thematique_id.", "example": 1 }, "page_end": { "type": "integer", "description": "End page number to filter export. Must be used with page_start. Mutually exclusive with thematique_id.", "example": 10 }, "thematique_id": { "type": "integer", "description": "Thematique (group) ID to filter export by pages belonging to this thematique. Mutually exclusive with page_start/page_end. Use action \"get_themes\" to retrieve available thematiques.", "example": 10 } }, "required": [ "class_id", "node_id", "action" ] } } } } } }, "/api/v3/get-asset/by-search/repository/": { "post": { "tags": [ "get-asset" ], "summary": "Search repository assets by filters", "description": "## Purpose\n\nReturns repository assets matching filters with pagination and custom attribute selection.\n\n## Attribute Selection\n\nUse either `attribute_list` (max 10 IDs) OR `mapping_id` for attribute output configuration.\n\n## Format Options\n\n- `simple`: Standard attribute list\n- `composed`: JSON with recursive structure\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Asset list by search", "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": "object", "properties": { "results_total": { "type": "integer", "example": 15, "description": "Number of items" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "141560", "description": "Asset ID" }, "parent_id": { "type": "string", "nullable": true, "example": "466175", "description": "Parent asset ID" }, "version_id": { "type": "integer", "example": 1, "description": "Version ID" }, "path": { "type": "string", "example": "0/1978/141560", "description": "Asset path" }, "supertype_id": { "type": "integer", "example": 7, "description": "Supertype ID" }, "supertype_label": { "type": "string", "nullable": true, "example": "Products", "description": "Supertype label" }, "type_id": { "type": "string", "example": "291", "description": "Type ID" }, "type_label": { "type": "string", "example": "HOUSSES", "description": "Type label" }, "workflow_item_id": { "type": "integer", "nullable": true, "example": null, "description": "Workflow item ID" }, "workflow_item_label": { "type": "string", "nullable": true, "example": null, "description": "Workflow item label (step/action)" }, "creation_date": { "type": "string", "example": "2018-09-12T00:00:00+02:00", "description": "Creation date (ISO 8601)" }, "modification_date": { "type": "string", "example": "2025-07-30T00:00:00+02:00", "description": "Modification date (ISO 8601)" }, "status_id": { "type": "string", "example": "1115", "description": "Status ID" }, "status_label": { "type": "string", "nullable": true, "example": "Validated", "description": "Status label" }, "data": { "type": "object", "additionalProperties": true, "example": { "2017": "AAF22DSQ22DQS2", "2018": "2804-AAF22DSQ22DQS2" }, "description": "Asset data with attribute values" } }, "required": [ "id", "type_id", "type_label", "creation_date", "modification_date", "status_id", "data" ] }, "description": "List of assets" }, "num_page": { "type": "integer", "nullable": true, "example": 1, "description": "Page number" }, "nb_pages": { "type": "integer", "nullable": true, "example": 15, "description": "Number of pages" }, "results_per_page": { "type": "integer", "nullable": true, "example": 100, "description": "Number of results per page" } }, "required": [ "results_total", "items" ], "description": "Result list" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = Parameter error)" }, "status_message": { "type": "string", "example": "The parameter \"num_page\" must be a valid integer", "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 }, "parent_id": { "type": "integer", "description": "Parent ID of the reference tree in which to search. Set to \"0\" if you want to search in all the repository", "example": 4350 }, "num_page": { "type": "integer", "description": "Page number for pagination. Use with results_per_page parameter.", "example": 3 }, "results_per_page": { "type": "integer", "description": "Number of results per page (between 10 and 1000). Must always be provided together with \"num_page\".", "example": 50 }, "version_id": { "type": "integer", "description": "Version ID. Use POST /api/v3/administration/versions/list with class_id to get available versions.", "example": 1 }, "exclude_inherited_values": { "type": "boolean", "description": "If it is true, only the direct values of the asset are exported (excludes values that have not been filled directly in the asset : values inherited from a parent, or from the repository in the case of a contextual asset, or calculated values)", "example": true }, "attribute_list": { "type": "array", "description": "If specified, the result will contain for each asset only the list of specified attributes (10 maximum). You must use either the \"attribute_list\" parameter or the \"mapping_id\" parameter.", "example": [ 231, "Selling price", "type_sales_price" ], "items": { "type": "integer" } }, "mapping_id": { "type": "integer", "description": "Mapping ID. If specified, the result will contain for each asset only the list of attributes used in the mapping. You must use either the \"attribute_list\" parameter or the \"mapping_id\" parameter. Use POST /api/v3/mappings/list/ with class_id to discover available mappings.", "example": 23 }, "research": { "type": "array", "description": "Array of attribute filters. Each filter has attribute_id, operator, value, and optional link. (Array of objects - see example for structure)", "example": [ { "attribute_id": 1234, "operator": "contains", "value": "Prefix_" }, { "link": "or", "attribute_id": 2465, "operator": "contains", "value": "Prefix_" } ], "items": { "type": "object", "properties": { "attribute_id": { "type": "integer", "description": "Attribute ID. Use POST /api/v3/attributes/list with class_id to get available attributes.", "example": 231 }, "operator": { "type": "string", "description": "Search operator: equal/notequal (exact match), contains/notcontains (partial), startby/endby (prefix/suffix), isnull/isnotnull (empty check), greater/atleast/lesser/nomore (numeric comparison), between (range with value2), isinlist/isnotinlist (multiple values).", "enum": [ "equal", "notequal", "contains", "notcontains", "startby", "endby", "notstartby", "notendby", "isnull", "isnotnull", "greater", "atleast", "lesser", "nomore", "between", "isinlist", "isnotinlist" ], "example": "between" }, "value": { "type": "string", "description": "Value (only if operator is not \"isnull\" and \"isnotnull\") **⚠️ Required when:** `operator` = `equal` | `notequal` | `contains` | `notcontains` | `startby` | `endby` | `notstartby` | `notendby` | `greater` | `atleast` | `lesser` | `nomore` | `between` | `isinlist` | `isnotinlist`", "example": "12345", "x-conditional-required": { "operator": [ "equal", "notequal", "contains", "notcontains", "startby", "endby", "notstartby", "notendby", "greater", "atleast", "lesser", "nomore", "between", "isinlist", "isnotinlist" ] } }, "value2": { "type": "string", "description": "Second value for range search. Required only when operator is \"between\" **⚠️ Required when:** `operator` = `between`", "example": "12346", "x-conditional-required": { "operator": [ "between" ] } }, "link": { "type": "string", "description": "Logical link between filters: \"and\" (all conditions must match) or \"or\" (any condition matches). Default: \"and\".", "enum": [ "and", "or" ], "example": "and" } }, "required": [ "attribute_id", "operator" ], "title": "Item" } }, "filters": { "type": "object", "description": "Filter object with types_id, status_id, creausers, users, workflow_step_id, date filters.", "example": { "types_id": [ 257, 258 ], "time": "2024-12-17T10:30:00Z", "workflow_step_id": 10 }, "properties": { "types_id": { "type": "array", "description": "List of asset type IDs. Use POST /api/v3/types/list with class_id to get available types.", "example": [ 257, 258 ], "items": { "type": "integer" } }, "status_id": { "type": "array", "description": "List of asset status IDs. Use POST /api/v3/permissions/statuses/list with class_id to get available statuses.", "example": [ 1287, 1288 ], "items": { "type": "integer" } }, "creausers": { "type": "array", "description": "List of user IDs who created assets. Use POST /api/v3/permissions/groups/list to get user groups.", "example": [ 1485, 1535 ], "items": { "type": "integer" } }, "users": { "type": "array", "description": "List of user IDs who last modified assets. Use POST /api/v3/permissions/groups/list to get user groups.", "example": [ 1485, 1535 ], "items": { "type": "integer" } }, "workflow_step_id": { "type": "integer", "description": "Workflow step ID. Use POST /api/v3/workflows/list/repository/ with class_id to get workflows and their steps.", "example": 10 }, "creatime": { "type": "string", "description": "Minimum creation date of the asset (ISO 8601 format). Used to filter assets created from this date.", "example": "2024-12-17T10:30:00Z" }, "creatimeend": { "type": "string", "description": "Maximum creation date of the asset (ISO 8601 format). Used to filter assets created up to this date.", "example": "2024-12-17T23:59:59Z" }, "time": { "type": "string", "description": "Minimum update date of the asset (ISO 8601 format). Used to filter assets updated from this date.", "example": "2024-12-17T10:30:00Z" }, "timeend": { "type": "string", "description": "Maximum update date of the asset (ISO 8601 format). Used to filter assets updated up to this date.", "example": "2024-12-17T23:59:59Z" }, "search_find": { "type": "string", "description": "Quick search text. Searches across indexed attributes for matching content.", "example": "My product label" }, "split_find": { "type": "string", "description": "Fast search mode: \"all_words\" (all words must be present), \"each_word\" (any word matches), \"exact_expression\" (exact phrase match).", "enum": [ "all_words", "each_word", "exact_expression" ], "example": "each_word" } } }, "format": { "type": "string", "description": "Specifies the format of the returned asset data. Use \"simple\" for standard attribute list format, or \"composed\" for JSON Composed format with recursive data structure and enhanced formatting.", "enum": [ "simple", "composed" ], "example": "simple" } }, "required": [ "class_id", "parent_id", "num_page", "results_per_page" ] } } } } } }, "/api/v3/get-asset/by-search/node/": { "post": { "tags": [ "get-asset" ], "summary": "Search project node assets by filters", "description": "## Purpose\n\nReturns project-contextualized assets matching filters with pagination and custom attribute selection.\n\n## Context\n\nSearches within a specific project node tree (catalog, publication) instead of repository.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Asset list by search", "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": "object", "properties": { "results_total": { "type": "integer", "example": 15, "description": "Number of items" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "141560", "description": "Node ID" }, "parent_id": { "type": "string", "nullable": true, "example": "466175", "description": "Parent node ID" }, "version_id": { "type": "integer", "example": 1, "description": "Version ID" }, "path": { "type": "string", "example": "0/1978/141560", "description": "Node path" }, "supertype_id": { "type": "integer", "example": 7, "description": "Supertype ID" }, "supertype_label": { "type": "string", "nullable": true, "example": "Products", "description": "Supertype label" }, "type_id": { "type": "string", "example": "291", "description": "Type ID" }, "type_label": { "type": "string", "example": "HOUSSES", "description": "Type label" }, "workflow_item_id": { "type": "integer", "nullable": true, "example": null, "description": "Workflow item ID" }, "workflow_item_label": { "type": "string", "nullable": true, "example": null, "description": "Workflow item label (step/action)" }, "creation_date": { "type": "string", "example": "2018-09-12T00:00:00+02:00", "description": "Creation date (ISO 8601)" }, "modification_date": { "type": "string", "example": "2025-07-30T00:00:00+02:00", "description": "Modification date (ISO 8601)" }, "status_id": { "type": "string", "example": "1115", "description": "Status ID" }, "status_label": { "type": "string", "nullable": true, "example": "Validated", "description": "Status label" }, "data": { "type": "object", "additionalProperties": true, "example": { "2017": "AAF22DSQ22DQS2", "2018": "2804-AAF22DSQ22DQS2" }, "description": "Asset data with attribute values" } }, "required": [ "id", "type_id", "type_label", "creation_date", "modification_date", "status_id", "data" ] }, "description": "List of nodes" }, "num_page": { "type": "integer", "nullable": true, "example": 1, "description": "Page number" }, "nb_pages": { "type": "integer", "nullable": true, "example": 15, "description": "Number of pages" }, "results_per_page": { "type": "integer", "nullable": true, "example": 100, "description": "Number of results per page" } }, "required": [ "results_total", "items" ], "description": "Result list" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = Parameter error)" }, "status_message": { "type": "string", "example": "The parameter \"num_page\" must be a valid integer", "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 }, "parent_id": { "type": "integer", "description": "Parent node ID in project. Use POST /api/v3/get-asset/by-search/node to find project nodes.", "example": 4350 }, "num_page": { "type": "integer", "description": "Page number for pagination. Use with results_per_page parameter.", "example": 3 }, "results_per_page": { "type": "integer", "description": "Number of results per page (between 10 and 1000). Must always be provided together with \"num_page\".", "example": 50 }, "version_id": { "type": "integer", "description": "Version ID. Use POST /api/v3/administration/versions/list with class_id to get available versions.", "example": 1 }, "exclude_inherited_values": { "type": "boolean", "description": "If it is true, only the direct values of the asset are exported (excludes values that have not been filled directly in the asset : values inherited from a parent, or from the repository in the case of a contextual asset, or calculated values)", "example": true }, "attribute_list": { "type": "array", "description": "If specified, the result will contain for each asset only the list of specified attributes (10 maximum). You must use either the \"attribute_list\" parameter or the \"mapping_id\" parameter.", "example": [ 231, "Selling price", "type_sales_price" ], "items": { "type": "integer" } }, "mapping_id": { "type": "integer", "description": "Mapping ID. If specified, the result will contain for each asset only the list of attributes used in the mapping. You must use either the \"attribute_list\" parameter or the \"mapping_id\" parameter. Use POST /api/v3/mappings/list/ with class_id to discover available mappings.", "example": 23 }, "research": { "type": "array", "description": "Array of attribute filters. Each filter has attribute_id, operator, value, and optional link. (Array of objects - see example for structure)", "example": [ { "attribute_id": 1234, "operator": "contains", "value": "Prefix_" }, { "link": "or", "attribute_id": 2465, "operator": "contains", "value": "Prefix_" } ], "items": { "type": "object", "properties": { "attribute_id": { "type": "integer", "description": "Attribute ID. Use POST /api/v3/attributes/list with class_id to get available attributes.", "example": 231 }, "operator": { "type": "string", "description": "Search operator: equal/notequal (exact match), contains/notcontains (partial), startby/endby (prefix/suffix), isnull/isnotnull (empty check), greater/atleast/lesser/nomore (numeric comparison), between (range with value2), isinlist/isnotinlist (multiple values).", "enum": [ "equal", "notequal", "contains", "notcontains", "startby", "endby", "notstartby", "notendby", "isnull", "isnotnull", "greater", "atleast", "lesser", "nomore", "between", "isinlist", "isnotinlist" ], "example": "between" }, "value": { "type": "string", "description": "Value (only if operator is not \"isnull\" and \"isnotnull\") **⚠️ Required when:** `operator` = `equal` | `notequal` | `contains` | `notcontains` | `startby` | `endby` | `notstartby` | `notendby` | `greater` | `atleast` | `lesser` | `nomore` | `between` | `isinlist` | `isnotinlist`", "example": "12345", "x-conditional-required": { "operator": [ "equal", "notequal", "contains", "notcontains", "startby", "endby", "notstartby", "notendby", "greater", "atleast", "lesser", "nomore", "between", "isinlist", "isnotinlist" ] } }, "value2": { "type": "string", "description": "Second value for range search. Required only when operator is \"between\" **⚠️ Required when:** `operator` = `between`", "example": "12346", "x-conditional-required": { "operator": [ "between" ] } }, "link": { "type": "string", "description": "Logical link between filters: \"and\" (all conditions must match) or \"or\" (any condition matches). Default: \"and\".", "enum": [ "and", "or" ], "example": "and" } }, "required": [ "attribute_id", "operator" ], "title": "Item" } }, "filters": { "type": "object", "description": "Filter object with types_id, status_id, creausers, users, workflow_step_id, date filters.", "example": { "types_id": [ 257, 258 ], "time": "2024-12-17T10:30:00Z", "workflow_step_id": 10 }, "properties": { "types_id": { "type": "array", "description": "List of asset type IDs. Use POST /api/v3/types/list with class_id to get available types.", "example": [ 257, 258 ], "items": { "type": "integer" } }, "status_id": { "type": "array", "description": "List of asset status IDs. Use POST /api/v3/permissions/statuses/list with class_id to get available statuses.", "example": [ 1287, 1288 ], "items": { "type": "integer" } }, "creausers": { "type": "array", "description": "List of user IDs who created assets. Use POST /api/v3/permissions/groups/list to get user groups.", "example": [ 1485, 1535 ], "items": { "type": "integer" } }, "users": { "type": "array", "description": "List of user IDs who last modified assets. Use POST /api/v3/permissions/groups/list to get user groups.", "example": [ 1485, 1535 ], "items": { "type": "integer" } }, "workflow_step_id": { "type": "integer", "description": "Workflow step ID. Use POST /api/v3/workflows/list/node/ with project_node_id and class_id to get workflows and their steps.", "example": 10 }, "creatime": { "type": "string", "description": "Minimum creation date of the asset (ISO 8601 format). Used to filter assets created from this date.", "example": "2024-12-17T10:30:00Z" }, "creatimeend": { "type": "string", "description": "Maximum creation date of the asset (ISO 8601 format). Used to filter assets created up to this date.", "example": "2024-12-17T23:59:59Z" }, "time": { "type": "string", "description": "Minimum update date of the asset (ISO 8601 format). Used to filter assets updated from this date.", "example": "2024-12-17T10:30:00Z" }, "timeend": { "type": "string", "description": "Maximum update date of the asset (ISO 8601 format). Used to filter assets updated up to this date.", "example": "2024-12-17T23:59:59Z" }, "search_find": { "type": "string", "description": "Quick search text. Searches across indexed attributes for matching content.", "example": "My product label" }, "split_find": { "type": "string", "description": "Fast search mode: \"all_words\" (all words must be present), \"each_word\" (any word matches), \"exact_expression\" (exact phrase match).", "enum": [ "all_words", "each_word", "exact_expression" ], "example": "each_word" }, "alias": { "type": "string", "description": "Alias filter: \"only_aliases\" (return only alias nodes), \"except_aliases\" (exclude alias nodes). Default: include all.", "enum": [ "only_aliases", "except_aliases" ], "example": "except_aliases" } } }, "format": { "type": "string", "description": "Specifies the format of the returned asset data. Use \"simple\" for standard attribute list format, or \"composed\" for JSON Composed format with recursive data structure and enhanced formatting.", "enum": [ "simple", "composed" ], "example": "simple" } }, "required": [ "class_id", "parent_id", "num_page", "results_per_page" ] } } } } } }, "/api/v3/get-asset/by-id/repository/": { "post": { "tags": [ "get-asset" ], "summary": "Get repository asset by ID", "description": "## Purpose\n\nReturns complete repository asset with all attribute values (master data without project overrides).\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Asset data", "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": "object", "properties": { "id": { "type": "string", "example": "141560", "description": "Asset ID" }, "parent_id": { "type": "string", "nullable": true, "example": "466175", "description": "Parent asset ID" }, "version_id": { "type": "integer", "example": 1, "description": "Version ID" }, "path": { "type": "string", "example": "0/1978/141560", "description": "Asset path" }, "supertype_id": { "type": "integer", "example": 7, "description": "Supertype ID" }, "supertype_label": { "type": "string", "nullable": true, "example": "Products", "description": "Supertype label" }, "type_id": { "type": "string", "example": "291", "description": "Type ID" }, "type_label": { "type": "string", "example": "HOUSSES", "description": "Type label" }, "workflow_item_id": { "type": "integer", "nullable": true, "example": null, "description": "Workflow item ID" }, "workflow_item_label": { "type": "string", "nullable": true, "example": "Pending validation", "description": "Workflow item label (step/action)" }, "creation_date": { "type": "string", "example": "2018-09-12T00:00:00+02:00", "description": "Creation date (ISO 8601)" }, "modification_date": { "type": "string", "example": "2025-07-30T00:00:00+02:00", "description": "Modification date (ISO 8601)" }, "status_id": { "type": "string", "example": "1115", "description": "Status ID" }, "status_label": { "type": "string", "nullable": true, "example": "Validated", "description": "Status label" }, "media": { "type": "string", "nullable": true, "example": "/path/to/image.jpg", "description": "Asset thumbnail image path (null if no image)" }, "data": { "type": "object", "additionalProperties": true, "example": { "2017": "AAF22DSQ22DQS2", "2018": "2804-AAF22DSQ22DQS2" }, "description": "Asset data with attribute values" } }, "required": [ "id", "type_id", "type_label", "creation_date", "modification_date", "status_id", "media", "data" ], "description": "Asset object" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = Parameter error)" }, "status_message": { "type": "string", "example": "Asset does not exist or has been deleted", "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": "Asset ID. Use POST /api/v3/get-asset/by-search/repository to find assets and get their IDs.", "example": 50 }, "class_id": { "type": "integer", "description": "Library ID. Use POST /api/v3/administration/classes/list to get available libraries.", "example": 4 }, "version_id": { "type": "integer", "description": "Version ID. Use POST /api/v3/administration/versions/list with class_id to get available versions.", "example": 1 } }, "required": [ "id", "class_id" ] } } } } } }, "/api/v3/get-asset/by-id/node/": { "post": { "tags": [ "get-asset" ], "summary": "Get project node asset by ID", "description": "## Purpose\n\nReturns project-contextualized asset with all attribute values (includes project-specific overrides).\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Asset data", "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": "object", "properties": { "id": { "type": "string", "example": "5756", "description": "Node ID" }, "parent_id": { "type": "string", "nullable": true, "example": "466175", "description": "Parent node ID" }, "version_id": { "type": "integer", "example": 1, "description": "Version ID" }, "path": { "type": "string", "example": "0/1978/5756", "description": "Node path" }, "supertype_id": { "type": "integer", "example": 7, "description": "Supertype ID" }, "supertype_label": { "type": "string", "nullable": true, "example": "Products", "description": "Supertype label" }, "type_id": { "type": "string", "example": "291", "description": "Type ID" }, "type_label": { "type": "string", "example": "HOUSSES", "description": "Type label" }, "workflow_item_id": { "type": "integer", "nullable": true, "example": null, "description": "Workflow item ID" }, "workflow_item_label": { "type": "string", "nullable": true, "example": "Pending validation", "description": "Workflow item label (step/action)" }, "creation_date": { "type": "string", "example": "2018-09-12T00:00:00+02:00", "description": "Creation date (ISO 8601)" }, "modification_date": { "type": "string", "example": "2025-07-30T00:00:00+02:00", "description": "Modification date (ISO 8601)" }, "status_id": { "type": "string", "example": "1115", "description": "Status ID" }, "status_label": { "type": "string", "nullable": true, "example": "Validated", "description": "Status label" }, "media": { "type": "string", "nullable": true, "example": "/path/to/image.jpg", "description": "Asset thumbnail image path (null if no image)" }, "data": { "type": "object", "additionalProperties": true, "example": { "2017": "AAF22DSQ22DQS2", "2018": "2804-AAF22DSQ22DQS2" }, "description": "Asset data with attribute values" } }, "required": [ "id", "type_id", "type_label", "creation_date", "modification_date", "status_id", "media", "data" ], "description": "Asset object" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = Parameter error)" }, "status_message": { "type": "string", "example": "Asset does not exist or has been deleted", "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": "Node ID. Use POST /api/v3/get-asset/by-search/node to find nodes and get their IDs.", "example": 5756 }, "class_id": { "type": "integer", "description": "Library ID. Use POST /api/v3/administration/classes/list to get available libraries.", "example": 4 }, "version_id": { "type": "integer", "description": "Version ID. Use POST /api/v3/administration/versions/list with class_id to get available versions.", "example": 1 } }, "required": [ "id", "class_id" ] } } } } } }, "/api/v3/import/auto/repository/": { "post": { "tags": [ "import" ], "summary": "Auto-mapped import in repository", "description": "## Purpose\n\nImports data from CSV or Excel files into the repository using automatic attribute mapping based on column headers.\n\n## Content-Type\n\nThis endpoint requires `multipart/form-data` content type.\n\n## Supported File Formats\n\nFile type is automatically detected from file extension:\n- **CSV**: Text-based comma/semicolon separated values\n- **XLSX**: Excel 2007+ format (Office Open XML)\n\n## Example with curl\n\n```bash\ncurl -X POST \"https://your-domain/api/v3/import/auto/repository/\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -F \"class_id=4\" \\\n -F \"file=@/path/to/data.csv\" \\\n -F \"separator=;\" \\\n -F \"mode=create_or_update\"\n```\n\n## Auto-Mapping Rules\n\nThe system automatically maps columns to attributes using these rules:\n1. **By uname**: Column header matches attribute uname exactly\n2. **By label**: Column header matches attribute label exactly\n\n## Header Conventions\n\n| Suffix | Meaning | Example |\n|--------|---------|---------|\n| `*` | Key column (used to identify existing assets) | `reference*` |\n| `!` | Associated data (linked entity) | `category!` |\n| `[suffix]` | Cross-reference data | `price[EUR]` |\n\n## Update Modes (Repository)\n\n- `create_only`: Only create new assets, skip existing ones\n- `update_only`: Only update existing assets, skip new ones\n- `create_or_update`: Create new assets or update existing ones (default)\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Import 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": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Import success status" }, "mapping": { "type": "object", "properties": { "resolved": { "type": "array", "items": { "type": "object", "properties": { "column": { "type": "integer", "example": 1, "description": "Column index (1-based)" }, "header": { "type": "string", "example": "reference*", "description": "Original column header from file" }, "attribute_id": { "type": "integer", "nullable": true, "example": 145, "description": "Matched attribute ID. Null if mapped to a system field." }, "system_field": { "type": "string", "nullable": true, "example": "[ID_FICHE]", "description": "System field identifier (e.g., [ID_FICHE], [ID_NODE], [ID_TYPE], [STATUT]). Only present for system field mappings." }, "is_key": { "type": "boolean", "example": true, "description": "Whether this column is marked as a key column (header ends with *)" } } }, "description": "Columns successfully mapped to attributes or system fields" }, "unresolved": { "type": "array", "items": { "type": "object", "properties": { "column": { "type": "integer", "example": 3, "description": "Column index (1-based)" }, "header": { "type": "string", "example": "unknown_column", "description": "Column header that could not be matched to any attribute" } } }, "description": "Columns that could not be mapped (no matching uname or label found in the class)" } }, "description": "Mapping information" }, "stats": { "type": "object", "properties": { "total_rows": { "type": "integer", "example": 1500, "description": "Total number of data rows processed" }, "created": { "type": "integer", "example": 1200, "description": "Number of assets created" }, "updated": { "type": "integer", "example": 300, "description": "Number of assets updated" }, "excluded": { "type": "integer", "example": 0, "description": "Number of rows excluded (no key value)" }, "errors": { "type": "integer", "example": 0, "description": "Number of rows with errors" } }, "required": [ "total_rows", "created", "updated", "excluded", "errors" ], "description": "Import statistics" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "integer", "description": "Row number" }, "message": { "type": "string", "description": "Error message" } } }, "description": "List of row-level errors" }, "history_id": { "type": "integer", "example": 12345, "description": "ID of the import action in the history log. Can be used to track or reference this import operation." } }, "required": [ "success", "mapping", "stats", "errors" ], "description": "Import result" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = Parameters error, 3 = Import error)" }, "status_message": { "type": "string", "example": "Invalid file format", "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 identifier (e.g., 4=Products). Use POST /api/v3/administration/classes/list to retrieve available libraries.", "example": 4 }, "parent_id": { "type": "integer", "description": "Parent asset ID in repository. Use POST /api/v3/get-asset/by-search/repository to find assets. Set to 0 for repository root.", "example": 0 }, "file": { "type": "string", "format": "binary", "description": "The file to import. Must be sent as multipart/form-data with a filename including a valid extension (e.g. products.csv). Supported formats: CSV, XLSX. Sending the file as raw binary without a filename will result in an error.", "example": "products.csv" }, "mode": { "type": "string", "description": "Import mode: \"create_only\" (new assets only), \"update_only\" (existing assets only), \"create_or_update\" (both).", "enum": [ "create_only", "update_only", "create_or_update" ], "example": "create_or_update" }, "separator": { "type": "string", "description": "CSV column separator (default: \";\"). Only used for CSV files", "example": ";" }, "header_row": { "type": "integer", "description": "Row number containing column headers (default: 1)", "example": 1 }, "data_start_row": { "type": "integer", "description": "Row number where data starts (default: 2)", "example": 2 }, "type_id": { "type": "integer", "description": "Asset type ID for created assets. Use POST /api/v3/types/list with class_id to get available types.", "example": 257 }, "version_id": { "type": "integer", "description": "Version ID for multilingual imports. Use POST /api/v3/administration/versions/list with class_id to get available versions.", "example": 1 } }, "required": [ "class_id", "mode" ] } } } } } }, "/api/v3/import/auto/node/": { "post": { "tags": [ "import" ], "summary": "Auto-mapped import in node (project context)", "description": "## Purpose\n\nImports data from CSV or Excel files into a specific node/project context using automatic attribute mapping based on column headers.\n\n## Content-Type\n\nThis endpoint requires `multipart/form-data` content type.\n\n## Supported File Formats\n\nFile type is automatically detected from file extension:\n- **CSV**: Text-based comma/semicolon separated values\n- **XLSX**: Excel 2007+ format (Office Open XML)\n\n## Example with curl\n\n```bash\ncurl -X POST \"https://your-domain/api/v3/import/auto/node/\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -F \"class_id=4\" \\\n -F \"parent_id=12345\" \\\n -F \"file=@/path/to/data.csv\" \\\n -F \"separator=;\" \\\n -F \"mode=create_in_context\"\n```\n\n## Auto-Mapping Rules\n\nThe system automatically maps columns to attributes using these rules:\n1. **By uname**: Column header matches attribute uname exactly\n2. **By label**: Column header matches attribute label exactly\n\n## Header Conventions\n\n| Suffix | Meaning | Example |\n|--------|---------|---------|\n| `*` | Key column (used to identify existing assets) | `reference*` |\n| `!` | Associated data (linked entity) | `category!` |\n| `[suffix]` | Cross-reference data | `price[EUR]` |\n\n## Update Modes (Node/Project)\n\n- `create_in_context`: Create assets in the specified node context (default)\n- `update_in_context`: Update existing assets in the context\n- `classify_only`: Only classify assets (no data modification)\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Import 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": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Import success status" }, "mapping": { "type": "object", "properties": { "resolved": { "type": "array", "items": { "type": "object", "properties": { "column": { "type": "integer", "example": 1, "description": "Column index (1-based)" }, "header": { "type": "string", "example": "reference*", "description": "Original column header from file" }, "attribute_id": { "type": "integer", "nullable": true, "example": 145, "description": "Matched attribute ID. Null if mapped to a system field." }, "system_field": { "type": "string", "nullable": true, "example": "[ID_FICHE]", "description": "System field identifier (e.g., [ID_FICHE], [ID_NODE], [ID_TYPE], [STATUT]). Only present for system field mappings." }, "is_key": { "type": "boolean", "example": true, "description": "Whether this column is marked as a key column (header ends with *)" } } }, "description": "Columns successfully mapped to attributes or system fields" }, "unresolved": { "type": "array", "items": { "type": "object", "properties": { "column": { "type": "integer", "example": 3, "description": "Column index (1-based)" }, "header": { "type": "string", "example": "unknown_column", "description": "Column header that could not be matched to any attribute" } } }, "description": "Columns that could not be mapped (no matching uname or label found in the class)" } }, "description": "Mapping information" }, "stats": { "type": "object", "properties": { "total_rows": { "type": "integer", "example": 1500, "description": "Total number of data rows processed" }, "created": { "type": "integer", "example": 1200, "description": "Number of assets created" }, "updated": { "type": "integer", "example": 300, "description": "Number of assets updated" }, "excluded": { "type": "integer", "example": 0, "description": "Number of rows excluded (no key value)" }, "errors": { "type": "integer", "example": 0, "description": "Number of rows with errors" } }, "required": [ "total_rows", "created", "updated", "excluded", "errors" ], "description": "Import statistics" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "integer", "description": "Row number" }, "message": { "type": "string", "description": "Error message" } } }, "description": "List of row-level errors" }, "history_id": { "type": "integer", "example": 12345, "description": "ID of the import action in the history log. Can be used to track or reference this import operation." } }, "required": [ "success", "mapping", "stats", "errors" ], "description": "Import result" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = Parameters error, 3 = Import error)" }, "status_message": { "type": "string", "example": "Invalid file format", "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 identifier (e.g., 4=Products). Use POST /api/v3/administration/classes/list to retrieve available libraries.", "example": 4 }, "parent_id": { "type": "integer", "description": "Parent node ID in project. Use POST /api/v3/get-asset/by-search/node to find project nodes.", "example": 12345 }, "file": { "type": "string", "format": "binary", "description": "The file to import. Must be sent as multipart/form-data with a filename including a valid extension (e.g. products.csv). Supported formats: CSV, XLSX. Sending the file as raw binary without a filename will result in an error.", "example": "products.csv" }, "mode": { "type": "string", "description": "Import mode: \"create_in_context\" (create nodes in project), \"update_in_context\" (update existing nodes), \"classify_only\" (classify without modification).", "enum": [ "create_in_context", "update_in_context", "classify_only" ], "example": "create_in_context" }, "separator": { "type": "string", "description": "CSV column separator (default: \";\"). Only used for CSV files", "example": ";" }, "header_row": { "type": "integer", "description": "Row number containing column headers (default: 1)", "example": 1 }, "data_start_row": { "type": "integer", "description": "Row number where data starts (default: 2)", "example": 2 }, "type_id": { "type": "integer", "description": "Asset type ID for created assets. Use POST /api/v3/types/list with class_id to get available types.", "example": 257 }, "version_id": { "type": "integer", "description": "Version ID for multilingual imports. Use POST /api/v3/administration/versions/list with class_id to get available versions.", "example": 1 } }, "required": [ "class_id", "parent_id", "mode" ] } } } } } }, "/api/v3/import/json/repository/": { "post": { "tags": [ "import" ], "summary": "Import JSON/JSONL data in repository", "description": "## Purpose\n\nImports data from JSON or JSONL format into the repository. Supports two input modes:\n1. **Inline data**: Pass JSON data directly via the `data` parameter\n2. **File upload**: Upload a JSON/JSONL file via multipart/form-data\n\n## Content-Type\n\n- For inline data: `application/json`\n- For file upload: `multipart/form-data`\n\n## JSON Schema\n\n### Line Structure (JSONL format)\n\nEach line represents one asset to import:\n\n```jsonl\n{\"key\": {...}, \"type_id\": 257, \"fields\": [...]}\n```\n\n### Asset Identification (`key`)\n\n```jsonl\n// By direct asset_id\n{\"key\": {\"id\": 5845}, \"fields\": [...]}\n\n// By key attribute (code/uname)\n{\"key\": {\"attr\": \"reference\", \"value\": \"ABC123\"}, \"fields\": [...]}\n\n// By key attribute (numeric id)\n{\"key\": {\"attr\": 231, \"value\": \"ABC123\"}, \"fields\": [...]}\n```\n\n### Attribute Resolution (`id` and `attr`)\n\nThe `attr` parameter resolves attributes in this order:\n1. **Numeric ID**: Direct attribute ID (e.g., `231`)\n2. **Uname**: Attribute uname/code (e.g., `\"designationlibelle\"`)\n3. **Label**: Attribute label (e.g., `\"Designation\"`)\n\nUse POST /api/v3/attributes/list to retrieve attribute IDs and unames.\n\n### Attribute Fields (`fields`)\n\n```jsonl\n// Simple attribute by ID\n{\"id\": 231, \"value\": \"Product A\"}\n\n// With language version\n{\"id\": 658, \"value\": \"Red leather\", \"version\": 1}\n\n// By attribute code/uname instead of ID\n{\"attr\": \"designationlabel\", \"value\": \"Text\", \"version\": 2}\n\n// Multiple values (sync required)\n{\"id\": 724, \"value\": [\"Red\", \"Black\"], \"sync\": true}\n\n// Associated data with search key\n{\"id\": 800, \"value\": [\"SKU1\", \"SKU2\"], \"keyassoc\": 231, \"sync\": true}\n```\n\n### Complete JSONL Example\n\n```jsonl\n{\"key\": {\"attr\": \"reference\", \"value\": \"ABC123\"}, \"type_id\": 257, \"fields\": [{\"id\": 231, \"value\": \"3-seater sofa\"}, {\"id\": 658, \"value\": \"Red leather\", \"version\": 1}, {\"id\": 658, \"value\": \"Cuir rouge\", \"version\": 2}, {\"id\": 724, \"value\": [\"Red\", \"Black\"], \"sync\": true}]}\n{\"key\": {\"attr\": \"reference\", \"value\": \"DEF456\"}, \"type_id\": 257, \"fields\": [{\"id\": 231, \"value\": \"Coffee table\"}, {\"id\": 800, \"value\": [\"ABC123\"], \"keyassoc\": 231, \"sync\": false}]}\n```\n\n### Field Parameters\n\n| Parameter | Required | Description |\n|-----------|----------|-------------|\n| `id` or `attr` | Yes | Attribute numeric ID, code/uname, or label |\n| `value` | Yes | Value (string, number, or array for multiples) |\n| `version` | No | Language version ID (default version if absent) |\n| `sync` | **Required if array** | `true` = replace all, `false` = append |\n| `keyassoc` | No | Key attribute ID for associated data |\n\n## Important Notes\n\n- **`type_id` is required when creating assets** (modes `create_only` and `create_or_update`). Without it, rows will fail with an error. It can be set globally via the `type_id` parameter or per line via the `type_id` field in each JSON object.\n\n## Examples with curl\n\n### Mode 1: Inline JSON (data parameter)\n\n```bash\ncurl -X POST \"https://your-domain/api/v3/import/json/repository/\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"class_id\": 4,\n \"mode\": \"create_or_update\",\n \"type_id\": 257,\n \"data\": [\n {\"key\": {\"attr\": \"reference\", \"value\": \"ABC\"}, \"fields\": [{\"id\": 231, \"value\": \"Product A\"}]},\n {\"key\": {\"attr\": \"reference\", \"value\": \"DEF\"}, \"fields\": [{\"id\": 231, \"value\": \"Product B\"}]}\n ]\n }'\n```\n\n### Mode 2: File upload\n\n```bash\ncurl -X POST \"https://your-domain/api/v3/import/json/repository/\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -F \"class_id=4\" \\\n -F \"mode=create_or_update\" \\\n -F \"file=@/path/to/data.jsonl\"\n```\n\n## Update Modes (Repository)\n\n- `create_only`: Only create new assets, skip existing ones\n- `update_only`: Only update existing assets, skip new ones\n- `create_or_update`: Create new assets or update existing ones (default)\n\n## Common Errors\n\n| Error Code | Message | Cause | Solution |\n|------------|---------|-------|----------|\n| 2 | \"No data provided\" | Neither `data` nor `file` parameter | Provide exactly one of `data` or `file` |\n| 2 | \"Cannot use both data and file\" | Both parameters provided | Use only one input mode |\n| 2 | \"Invalid file format\" | File is not .json or .jsonl | Use JSON or JSONL file extension |\n| 2 | \"Parameter data must be an array\" | `data` is not a JSON array | Ensure `data` is an array of objects |\n| 3 | \"JSON parse error on line X\" | Malformed JSON in file | Fix JSON syntax at specified line |\n| 3 | \"Import error\" | Processing failed | Check attribute IDs and data format |\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON Import 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": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Import success status" }, "stats": { "type": "object", "properties": { "total_rows": { "type": "integer", "example": 2, "description": "Total number of data rows processed" }, "created": { "type": "integer", "example": 1, "description": "Number of assets created" }, "updated": { "type": "integer", "example": 1, "description": "Number of assets updated" }, "excluded": { "type": "integer", "example": 0, "description": "Number of rows excluded (no key value)" }, "errors": { "type": "integer", "example": 0, "description": "Number of rows with errors" } }, "required": [ "total_rows", "created", "updated", "excluded", "errors" ], "description": "Import statistics" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "integer", "example": 3, "description": "Row number where error occurred" }, "message": { "type": "string", "example": "Invalid attribute ID: 999", "description": "Error message describing the issue" } } }, "example": [ { "row": 3, "message": "Invalid attribute ID: 999" } ], "description": "List of row-level errors encountered during import" }, "history_id": { "type": "integer", "example": 12345, "description": "ID of the import action in the history log" } }, "required": [ "success", "stats", "errors" ], "description": "Import result" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = Parameters error, 3 = Import error)" }, "status_message": { "type": "string", "example": "No data provided. Use either \"data\" parameter (JSON body) or \"file\" parameter (multipart upload)", "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 identifier (e.g., 4=Products). Use POST /api/v3/administration/classes/list to retrieve available libraries.", "example": 4 }, "parent_id": { "type": "integer", "description": "Parent asset ID in repository. Use POST /api/v3/get-asset/by-search/repository to find assets. Set to 0 for repository root (default).", "example": 0 }, "mode": { "type": "string", "description": "Import mode: \"create_only\" (new assets only), \"update_only\" (existing assets only), \"create_or_update\" (both).", "enum": [ "create_only", "update_only", "create_or_update" ], "example": "create_or_update" }, "data": { "type": "array", "description": "**MUTUALLY EXCLUSIVE with `file`** - Array of JSON objects to import (inline mode). Each object must contain `key` (asset identification), optionally `type_id`, and `fields` array. Exactly one of `data` or `file` must be provided.", "example": "[{\"key\": {\"attr\": \"reference\", \"value\": \"ABC123\"}, \"type_id\": 257, \"fields\": [{\"id\": 231, \"value\": \"Product A\"}]}]", "items": { "type": "string" } }, "file": { "type": "string", "format": "binary", "description": "**MUTUALLY EXCLUSIVE with `data`** - JSON (.json) or JSONL (.jsonl) file to import. Must be sent as multipart/form-data with a filename including a valid extension (e.g. products.jsonl). Sending the file as raw binary without a filename will result in an error. Exactly one of `data` or `file` must be provided.", "example": "products.jsonl" }, "type_id": { "type": "integer", "description": "Asset type ID for created assets. **Required when creating assets** (without it, creation will fail). Can be overridden per line with type_id field. Use POST /api/v3/types/list with class_id to get available types.", "example": 257 }, "version_id": { "type": "integer", "description": "Default version ID for multilingual imports (can be overridden per field with version). Use POST /api/v3/administration/versions/list with class_id to get available versions.", "example": 1 } }, "required": [ "class_id", "mode" ] } } } } } }, "/api/v3/import/json/node/": { "post": { "tags": [ "import" ], "summary": "Import JSON/JSONL data in node (project context)", "description": "## Purpose\n\nImports data from JSON or JSONL format into a specific node/project context. Supports two input modes:\n1. **Inline data**: Pass JSON data directly via the `data` parameter\n2. **File upload**: Upload a JSON/JSONL file via multipart/form-data\n\n## Content-Type\n\n- For inline data: `application/json`\n- For file upload: `multipart/form-data`\n\n## JSON Schema\n\n### Line Structure (JSONL format)\n\nEach line represents one asset to import:\n\n```jsonl\n{\"key\": {...}, \"type_id\": 257, \"fields\": [...]}\n```\n\n### Asset Identification (`key`)\n\n```jsonl\n// By direct asset_id\n{\"key\": {\"id\": 5845}, \"fields\": [...]}\n\n// By key attribute (code/uname)\n{\"key\": {\"attr\": \"reference\", \"value\": \"ABC123\"}, \"fields\": [...]}\n\n// By key attribute (numeric id)\n{\"key\": {\"attr\": 231, \"value\": \"ABC123\"}, \"fields\": [...]}\n```\n\n### Attribute Resolution (`id` and `attr`)\n\nThe `attr` parameter resolves attributes in this order:\n1. **Numeric ID**: Direct attribute ID (e.g., `231`)\n2. **Uname**: Attribute uname/code (e.g., `\"designationlibelle\"`)\n3. **Label**: Attribute label (e.g., `\"Designation\"`)\n\nUse POST /api/v3/attributes/list to retrieve attribute IDs and unames.\n\n### Attribute Fields (`fields`)\n\n```jsonl\n// Simple attribute by ID\n{\"id\": 231, \"value\": \"Product A\"}\n\n// With language version\n{\"id\": 658, \"value\": \"Red leather\", \"version\": 1}\n\n// By attribute code/uname instead of ID\n{\"attr\": \"designationlabel\", \"value\": \"Text\", \"version\": 2}\n\n// Multiple values (sync required)\n{\"id\": 724, \"value\": [\"Red\", \"Black\"], \"sync\": true}\n\n// Associated data with search key\n{\"id\": 800, \"value\": [\"SKU1\", \"SKU2\"], \"keyassoc\": 231, \"sync\": true}\n```\n\n### Field Parameters\n\n| Parameter | Required | Description |\n|-----------|----------|-------------|\n| `id` or `attr` | Yes | Attribute numeric ID, code/uname, or label |\n| `value` | Yes | Value (string, number, or array for multiples) |\n| `version` | No | Language version ID (default version if absent) |\n| `sync` | **Required if array** | `true` = replace all, `false` = append |\n| `keyassoc` | No | Key attribute ID for associated data |\n\n## Important Notes\n\n- **`type_id` is required when creating assets** (modes `create_in_context`). Without it, rows will fail with an error. It can be set globally via the `type_id` parameter or per line via the `type_id` field in each JSON object.\n\n## Examples with curl\n\n### Mode 1: Inline JSON (data parameter)\n\n```bash\ncurl -X POST \"https://your-domain/api/v3/import/json/node/\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"class_id\": 4,\n \"parent_id\": 12345,\n \"mode\": \"create_in_context\",\n \"type_id\": 257,\n \"data\": [\n {\"key\": {\"attr\": \"reference\", \"value\": \"ABC\"}, \"fields\": [{\"id\": 231, \"value\": \"Product A\"}]},\n {\"key\": {\"attr\": \"reference\", \"value\": \"DEF\"}, \"fields\": [{\"id\": 231, \"value\": \"Product B\"}]}\n ]\n }'\n```\n\n### Mode 2: File upload\n\n```bash\ncurl -X POST \"https://your-domain/api/v3/import/json/node/\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -F \"class_id=4\" \\\n -F \"parent_id=12345\" \\\n -F \"mode=create_in_context\" \\\n -F \"file=@/path/to/data.jsonl\"\n```\n\n## Update Modes (Node/Project)\n\n- `create_in_context`: Create assets in the specified node context (default)\n- `update_in_context`: Update existing assets in the context\n- `classify_only`: Only classify assets (no data modification)\n\n## Common Errors\n\n| Error Code | Message | Cause | Solution |\n|------------|---------|-------|----------|\n| 2 | \"No data provided\" | Neither `data` nor `file` parameter | Provide exactly one of `data` or `file` |\n| 2 | \"Cannot use both data and file\" | Both parameters provided | Use only one input mode |\n| 2 | \"Parent node does not exist\" | Invalid parent_id | Use valid node ID from project |\n| 2 | \"Invalid file format\" | File is not .json or .jsonl | Use JSON or JSONL file extension |\n| 3 | \"JSON parse error on line X\" | Malformed JSON in file | Fix JSON syntax at specified line |\n| 3 | \"Not allowed operation\" | No permission on project | Check user project permissions |\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "JSON Import 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": "object", "properties": { "success": { "type": "boolean", "example": true, "description": "Import success status" }, "stats": { "type": "object", "properties": { "total_rows": { "type": "integer", "example": 2, "description": "Total number of data rows processed" }, "created": { "type": "integer", "example": 1, "description": "Number of assets created" }, "updated": { "type": "integer", "example": 1, "description": "Number of assets updated" }, "excluded": { "type": "integer", "example": 0, "description": "Number of rows excluded (no key value)" }, "errors": { "type": "integer", "example": 0, "description": "Number of rows with errors" } }, "required": [ "total_rows", "created", "updated", "excluded", "errors" ], "description": "Import statistics" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "integer", "example": 3, "description": "Row number where error occurred" }, "message": { "type": "string", "example": "Invalid attribute ID: 999", "description": "Error message describing the issue" } } }, "example": [ { "row": 3, "message": "Invalid attribute ID: 999" } ], "description": "List of row-level errors encountered during import" }, "history_id": { "type": "integer", "example": 12345, "description": "ID of the import action in the history log" } }, "required": [ "success", "stats", "errors" ], "description": "Import result" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = Parameters error, 3 = Import error)" }, "status_message": { "type": "string", "example": "No data provided. Use either \"data\" parameter (JSON body) or \"file\" parameter (multipart upload)", "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 identifier (e.g., 4=Products). Use POST /api/v3/administration/classes/list to retrieve available libraries.", "example": 4 }, "parent_id": { "type": "integer", "description": "Parent node ID in project. Use POST /api/v3/get-asset/by-search/node to find project nodes.", "example": 12345 }, "mode": { "type": "string", "description": "Import mode: \"create_in_context\" (create nodes in project), \"update_in_context\" (update existing nodes), \"classify_only\" (classify without modification).", "enum": [ "create_in_context", "update_in_context", "classify_only" ], "example": "create_in_context" }, "data": { "type": "array", "description": "**MUTUALLY EXCLUSIVE with `file`** - Array of JSON objects to import (inline mode). Each object must contain `key` (asset identification), optionally `type_id`, and `fields` array. Exactly one of `data` or `file` must be provided.", "example": "[{\"key\": {\"attr\": \"reference\", \"value\": \"ABC123\"}, \"type_id\": 257, \"fields\": [{\"id\": 231, \"value\": \"Product A\"}]}]", "items": { "type": "string" } }, "file": { "type": "string", "format": "binary", "description": "**MUTUALLY EXCLUSIVE with `data`** - JSON (.json) or JSONL (.jsonl) file to import. Must be sent as multipart/form-data with a filename including a valid extension (e.g. products.jsonl). Sending the file as raw binary without a filename will result in an error. Exactly one of `data` or `file` must be provided.", "example": "products.jsonl" }, "type_id": { "type": "integer", "description": "Asset type ID for created assets. **Required when creating assets** (without it, creation will fail). Can be overridden per line with type_id field. Use POST /api/v3/types/list with class_id to get available types.", "example": 257 }, "version_id": { "type": "integer", "description": "Default version ID for multilingual imports (can be overridden per field with version). Use POST /api/v3/administration/versions/list with class_id to get available versions.", "example": 1 } }, "required": [ "class_id", "parent_id", "mode" ] } } } } } }, "/api/v3/listvalues/full/": { "post": { "tags": [ "listvalues" ], "summary": "Get list values for dropdowns", "description": "## Purpose\n\nReturns all dropdown options configured for a class with full details (options, linked attributes, versions).\n\n## Use Cases\n\n- Populate select fields with available choices\n- Validate user input against allowed values\n- Build dynamic forms based on list configuration\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "List values 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": "object", "properties": { "results_total": { "type": "integer", "example": 2, "description": "Total number of list values found" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 45, "description": "List value ID" }, "class_id": { "type": "integer", "example": 4, "description": "Class ID" }, "code": { "type": "string", "example": "code_list", "description": "List value code" }, "label": { "type": "string", "example": "Colors", "description": "List value label" }, "linked_attributes": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "125": "Color attribute", "126": "Main color" }, "description": "Map of attribute IDs to labels that use this list value" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "tag1", "tag2" ], "description": "Array of tags (can be empty)" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1001, "description": "Option ID" }, "value_code": { "type": "string", "example": "RED", "description": "Option value code" }, "order": { "type": "integer", "example": 1, "description": "Display order" }, "afs": { "type": "string", "example": "#123#", "description": "AFS value" }, "versions": { "type": "array", "items": { "type": "object" }, "example": { "1": { "data_value": "No", "real_value": "No" }, "2": { "data_value": "No", "real_value": "No" } }, "description": "Associated versions" }, "asset_types": { "type": "array", "items": { "type": "string" }, "example": [ "all" ], "description": "Associated asset types (can be 'all' or specific type labels)" } }, "required": [ "id", "value_code", "order", "afs", "versions", "asset_types" ] }, "description": "Array of options" } }, "required": [ "id", "class_id", "code", "label", "tags", "linked_attributes", "options" ] }, "description": "Array of list values" } }, "required": [ "results_total", "items" ], "description": "List values with total count" } }, "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 } }, "required": [ "class_id" ] } } } } } }, "/api/v3/listvalues/list/": { "post": { "tags": [ "listvalues" ], "summary": "List dropdown configurations", "description": "## Purpose\n\nReturns simplified list values for a class (id, code, label, tags only).\n\n## Comparison\n\nUse `listvalues/full` for complete details including options and linked attributes.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "List values 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": "object", "properties": { "results_total": { "type": "integer", "example": 2, "description": "Total number of list values found" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 45, "description": "List value ID" }, "class_id": { "type": "integer", "example": 4, "description": "Class ID" }, "code": { "type": "string", "example": "code_list", "description": "List value code" }, "label": { "type": "string", "example": "Colors", "description": "List value label" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "tag1", "tag2" ], "description": "Array of tags (can be empty)" } }, "required": [ "id", "class_id", "code", "label", "tags" ] }, "description": "Array of list values" } }, "required": [ "results_total", "items" ], "description": "List values with total count" } }, "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 } }, "required": [ "class_id" ] } } } } } }, "/api/v3/listvalues/get/": { "post": { "tags": [ "listvalues" ], "summary": "Get list value details", "description": "## Purpose\n\nReturns complete information for a single list value including all options, linked attributes, and version data.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "List value 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" }, "result": { "type": "object", "properties": { "id": { "type": "integer", "example": 45, "description": "List value ID" }, "class_id": { "type": "integer", "example": 4, "description": "Class ID" }, "code": { "type": "string", "example": "code_list", "description": "List value code" }, "label": { "type": "string", "example": "Colors", "description": "List value label" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "tag1", "tag2" ], "description": "Array of tags (can be empty)" }, "linked_attributes": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "125": "Color attribute", "126": "Main color" }, "description": "Map of attribute IDs to labels that use this list value" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1001, "description": "Option ID" }, "value_code": { "type": "string", "example": "RED", "description": "Option value code" }, "order": { "type": "integer", "example": 1, "description": "Display order" }, "afs": { "type": "string", "example": "#123#", "description": "AFS value" }, "versions": { "type": "array", "items": { "type": "object" }, "example": { "1": { "data_value": "No", "real_value": "No" }, "2": { "data_value": "No", "real_value": "No" } }, "description": "Associated versions" }, "asset_types": { "type": "array", "items": { "type": "string" }, "example": [ "all" ], "description": "Associated asset types (can be 'all' or specific type labels)" } }, "required": [ "id", "value_code", "order", "afs", "versions", "asset_types" ] }, "description": "Array of options" } }, "required": [ "id", "class_id", "code", "label", "tags", "linked_attributes", "options" ], "description": "List value information" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = not found)" }, "status_message": { "type": "string", "example": "List value \"20\" does not exist", "description": "Error message with list value ID" }, "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": "List value ID. Use POST /api/v3/listvalues/list with class_id to get available list values.", "example": 20 } }, "required": [ "id" ] } } } } } }, "/api/v3/listvalues/create/": { "post": { "tags": [ "listvalues" ], "summary": "Create a new dropdown list", "description": "## Purpose\n\nCreates a new dropdown list (list value) in a library, optionally with initial options (values).\n\n## Idempotent Behavior\n\nIf a list with the same label already exists in the library, returns the existing list with `created: false` and adds any new values provided.\n\n## Use Cases\n\n- Create dropdown lists for product attributes (colors, sizes, categories)\n- Pre-populate lists with initial values and translations\n- Automate list creation during platform setup\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Create list value 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": "List created successfully", "description": "Status message" }, "result": { "type": "object", "properties": { "id": { "type": "integer", "example": 127, "description": "List value ID" }, "class_id": { "type": "integer", "example": 4, "description": "Library ID" }, "label": { "type": "string", "example": "Colors", "description": "List label" }, "created": { "type": "boolean", "example": true, "description": "true if newly created, false if already existed" }, "values_added": { "type": "integer", "example": 3, "description": "Number of option values added" } }, "required": [ "id", "class_id", "label", "created", "values_added" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = validation error)" }, "status_message": { "type": "string", "example": "Label cannot be empty", "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 }, "label": { "type": "string", "description": "Name of the dropdown list. Must be unique within the library for creation (idempotent if duplicate).", "example": "Colors" }, "values": { "type": "array", "description": "Array of option objects to add to the list. Empty labels are ignored. (Array of objects - see example for structure)", "example": [ { "label": "Rouge", "code": "RED", "translations": { "2": "Red", "3": "Rojo" }, "type_ids": [ 100, 102 ], "afs": "#123#" }, { "label": "Bleu", "code": "BLU" } ], "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Display label in the default language.", "example": "Rouge" }, "code": { "type": "string", "description": "Option code. Auto-generated as \"id_\" if omitted.", "example": "RED" }, "translations": { "type": "object", "description": "Translated labels by version_id. Keys are version IDs (as strings), values are translated labels. Use POST /api/v3/listvalues/full to see available version IDs.", "additionalProperties": { "type": "string" }, "example": { "2": "Red", "3": "Rojo" } }, "type_ids": { "type": "array", "items": { "type": "integer" }, "description": "Asset type IDs to restrict this option to. If omitted, option is available for all types. Use POST /api/v3/types/list to get available type IDs.", "example": [ 100, 102 ] }, "afs": { "type": "string", "description": "AFS condition using Smarty/hashtag syntax (e.g. \"#123#\", \"{if #153#}1{/if}\"). Syntax is validated before creation.", "example": "#123#" } }, "required": [ "label" ] } } }, "required": [ "class_id", "label" ] } } } } } }, "/api/v3/listvalues/update/": { "post": { "tags": [ "listvalues" ], "summary": "Update a dropdown list with full options synchronization", "description": "## Purpose\n\nUpdates an existing dropdown list: its label and/or its options. When `values` is provided, the endpoint performs a **full synchronization** of the list options.\n\n## What can be updated\n\n- `label`: Display name of the list\n- `values`: Complete list of options (exhaustive synchronization)\n\n## What cannot be updated\n\n- `class_id` (immutable — the list belongs to a specific library)\n\n## Recommended workflow\n\n1. Call `POST /api/v3/listvalues/get` with the list ID to retrieve all existing options and their IDs\n2. Modify the returned options array as needed (add, remove, or edit entries)\n3. Send the modified array as the `values` parameter to this endpoint\n\nThis read-modify-write pattern ensures you don't accidentally delete existing options by sending a partial list.\n\n## Options synchronization (`values` parameter)\n\nWhen `values` is provided, it must contain the **complete and exhaustive** list of options for this dropdown. The endpoint compares the provided options with the existing ones in database and performs:\n\n### 1. Matching logic (by priority)\n- **By `id`**: if an option has an `id` field, it is matched to the existing option with that `id_asset`\n- **By `code`**: if no `id` but a `code` is provided, it is matched to the existing option with that `code_valeur`\n- **No match**: the option is treated as new and will be created\n\n### 2. ADD — Options present in `values` but not in database\n- Creates the option element (asset) in the list\n- Sets translations for each provided `version_id`\n- Creates type associations if `type_ids` is provided\n\n### 3. UPDATE — Options matched between `values` and database\nFor each matched option, only fields that actually differ are updated:\n- `label` (translations): compared per version_id, only changed versions are written\n- `code`: updated if different from current `code_valeur`\n- `afs`: updated if different from current `asset_afs` (syntax validated before update)\n- `type_ids`: diff computed with `array_diff()` — types to add and types to remove are processed separately\n\n### 4. DELETE — Options in database but NOT in `values`\n**⚠️ DESTRUCTIVE**: options present in the database but absent from the `values` array will be **permanently deleted**. This includes:\n- The option element (asset) itself (soft-delete: `deleted=1`)\n- All type associations for this option (`links_element_list_values_type` rows)\n- All references in library link tables (`links_XXX_list_values`)\n\n### 5. No `values` parameter\nIf `values` is omitted, only the `label` is updated (if provided). Existing options are left untouched.\n\n## Important\n\n- If neither `label` nor `values` is provided, the endpoint returns success with empty sync counts.\n- All option validations (translations version_ids, type_ids, AFS syntax) are performed **before any write operation**. If any validation fails, the entire update is aborted.\n\n## Common Errors\n\n| status_code | Cause | Example message |\n|-------------|-------|-----------------|\n| 2 | Invalid or non-existent id | \"List not found with id 99999\" |\n| 2 | Empty label after trim | \"Label cannot be empty\" |\n| 2 | Invalid version_id in translations | \"Invalid version_id \\\"99\\\" in values[0].translations\" |\n| 2 | Invalid type_id | \"Invalid type_id \\\"999\\\" in values[0].type_ids\" |\n| 2 | AFS syntax error | \"AFS syntax error in values[0].afs: ...\" |\n| 997 | User is not sadmin | \"Not allowed operation\" |\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "List update 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": "List updated successfully", "description": "Status message" }, "result": { "type": "object", "properties": { "id": { "type": "integer", "example": 127, "description": "List ID" }, "class_id": { "type": "integer", "example": 4, "description": "Library ID" }, "label": { "type": "string", "example": "Colors", "description": "Current list label (after update)" }, "updated_fields": { "type": "array", "items": { "type": "string" }, "example": [ "label" ], "description": "List-level fields that were actually modified" }, "options_added": { "type": "integer", "example": 1, "description": "Number of new options created" }, "options_updated": { "type": "integer", "example": 2, "description": "Number of existing options modified" }, "options_deleted": { "type": "integer", "example": 1, "description": "Number of options permanently removed from the list" } }, "required": [ "id", "class_id", "label", "updated_fields", "options_added", "options_updated", "options_deleted" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "enum": [ 2, 997 ], "example": 2, "description": "Status code (2 = validation error, 997 = insufficient permissions)" }, "status_message": { "type": "string", "example": "List not found", "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": "List value ID to update. Use POST /api/v3/listvalues/list with class_id to get available lists and their IDs.", "example": 127 }, "label": { "type": "string", "description": "New list label (display name). Maximum 255 characters. Empty strings are not allowed.", "example": "Colors" }, "values": { "type": "array", "description": "Complete and exhaustive array of options for this list. This triggers a full synchronization: options not in this array will be DELETED from the database. Omit this parameter entirely to leave existing options untouched. (Array of objects - see example for structure)", "example": [ { "id": 456, "label": "Rouge", "code": "RED", "translations": { "2": "Red", "3": "Rojo" }, "type_ids": [ 100, 102 ] }, { "label": "Vert", "code": "GRN", "translations": { "2": "Green" } } ], "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Existing option ID (id_asset). If provided, the option is matched by ID for update. Use POST /api/v3/listvalues/get to retrieve existing option IDs.", "example": 456 }, "label": { "type": "string", "description": "Display label in the default language.", "example": "Rouge" }, "code": { "type": "string", "description": "Option code. Used as matching key if no `id` is provided. Auto-generated as \"id_\" if omitted on new options.", "example": "RED" }, "translations": { "type": "object", "description": "Translated labels by version_id. Keys are version IDs (as strings), values are translated labels. Use POST /api/v3/listvalues/full to see available version IDs.", "additionalProperties": { "type": "string" }, "example": { "2": "Red", "3": "Rojo" } }, "type_ids": { "type": "array", "items": { "type": "integer" }, "description": "Asset type IDs to restrict this option to. If omitted on new options, option is available for all types. On update: if provided, types are synchronized (missing types added, extra types removed). If omitted entirely on an existing option, its current type restrictions are left unchanged.", "example": [ 100, 102 ] }, "afs": { "type": "string", "description": "AFS condition using Smarty/hashtag syntax (e.g. \"#123#\", \"{if #153#}1{/if}\"). Syntax is validated before update.", "example": "#123#" } }, "required": [ "label" ] } } }, "required": [ "id" ] } } } } } }, "/api/v3/listvalues/add-option/": { "post": { "tags": [ "listvalues" ], "summary": "Add option to list value", "description": "## Purpose\n\nAdds a new option (choice) to an existing dropdown list.\n\n## Use Cases\n\n- Extend available choices for a dropdown field\n- Add new values to existing list configurations\n- Automate list value population via API\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Add option 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": "Option added successfully", "description": "Status message" }, "result": { "type": "object", "properties": { "list_id": { "type": "integer", "example": 50, "description": "ID of the list value" }, "option_id": { "type": "integer", "example": 205, "description": "ID of the newly created option" }, "label": { "type": "string", "example": "Nouvelle Couleur", "description": "Display label for the new list option. Must be unique within the list" }, "code": { "type": "string", "example": "NEW_COLOR", "description": "Code of the new option" } }, "required": [ "list_id", "option_id", "label", "code" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = list not found, 3 = error)" }, "status_message": { "type": "string", "example": "List value \"50\" does not exist", "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": { "list_id": { "type": "integer", "description": "List value ID. Use POST /api/v3/listvalues/list with class_id to get available list values.", "example": 50 }, "value": { "type": "string", "description": "Display label for the new list option. Must be unique within the list", "example": "Nouvelle Couleur" }, "code": { "type": "string", "description": "Optional code for the option (auto-generated if not provided)", "example": "NEW_COLOR" } }, "required": [ "list_id", "value" ] } } } } } }, "/api/v3/mappings/full/": { "post": { "tags": [ "mappings" ], "summary": "Get all mappings for a class", "description": "## Purpose\n\nReturns all mappings for a class grouped by type (export, import, asset_view, search_view, dynamic_grouped_view).\n\n## Response Details\n\nEach mapping includes metadata (creation/modification dates, users, permissions) and full configuration data.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Mappings 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": "Empty string on success" }, "result": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "export", "description": "Mapping type" }, "results_total": { "type": "integer", "example": 5, "description": "Total number of mappings returned for this mapping type" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1415, "description": "ID" }, "code": { "type": "string", "example": "export_products_csv", "description": "Mapping code" }, "label": { "type": "string", "example": "My Mapping", "description": "Label" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "tag1", "tag2" ], "description": "Array of tags (can be empty)" }, "class_id": { "type": "integer", "example": 4, "description": "Class ID" }, "permissions": { "type": "string", "example": "Group 1 | Group 2", "description": "Permissions" }, "creation_date": { "type": "string", "nullable": true, "example": "2016-02-17T00:00:00+01:00", "description": "Creation date (ISO 8601 format)" }, "creation_user": { "type": "string", "nullable": true, "example": "creation_user@company.com", "description": "Creation user" }, "modification_date": { "type": "string", "nullable": true, "example": "2018-02-17T00:00:00+01:00", "description": "Modification date (ISO 8601 format)" }, "modification_user": { "type": "string", "nullable": true, "example": "modification_user@company.com", "description": "Modification user" }, "last_use_date": { "type": "string", "nullable": true, "example": "2019-02-17T00:00:00+01:00", "description": "Last use date (ISO 8601 format)" }, "last_use_user": { "type": "string", "nullable": true, "example": "last_use_user@company.com", "description": "Last use user" }, "hash": { "type": "string", "example": "a84ef1b35017a6ce27eaca962d291124afaf005dc301656ef9b7492e29cc3d4d", "description": "Hash" }, "data": { "type": "object", "nullable": true, "description": "Data", "additionalProperties": true } }, "required": [ "id", "code", "label", "tags", "class_id", "hash" ], "description": "Mapping information" } } }, "required": [ "type", "items" ], "description": "List of mappings for the mapping type" } } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 997, "description": "Status code (997 = action not allowed)" }, "status_message": { "type": "string", "example": "You don't have the rights to do this action", "description": "Error message because no rights" }, "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 } }, "required": [ "class_id" ] } } } } } }, "/api/v3/mappings/list/": { "post": { "tags": [ "mappings" ], "summary": "List mappings by class and type", "description": "## Purpose\n\nReturns simplified mapping list for a specific class and type.\n\n## Mapping Types\n\n- `export`: Data export configurations\n- `import`: Data import configurations\n- `asset_view`: Asset display views\n- `search_view`: Search result views\n- `dynamic_grouped_view`: Grouped display views\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Mappings 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": "Empty string on success" }, "result": { "type": "object", "properties": { "results_total": { "type": "integer", "example": 2, "description": "Total number of mappings found" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1415, "description": "Mapping ID" }, "code": { "type": "string", "example": "export_products_csv", "description": "Mapping code" }, "label": { "type": "string", "example": "My Mapping", "description": "Mapping label" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "tag1", "tag2" ], "description": "Array of tags (can be empty)" }, "class_id": { "type": "integer", "example": 4, "description": "Class ID" }, "type": { "type": "string", "example": "export", "description": "Mapping type" } }, "required": [ "id", "code", "label", "tags", "class_id", "type" ] }, "description": "Array of mapping objects" } }, "required": [ "results_total", "items" ], "description": "Mappings with total count" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 997, "description": "Status code (997 = action not allowed)" }, "status_message": { "type": "string", "example": "You don't have the rights to do this action", "description": "Error message because no rights" }, "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 }, "type": { "type": "string", "description": "Mapping type: \"export\" (data export), \"import\" (data import), \"asset_view\" (asset display), \"search_view\" (search results), \"dynamic_grouped_view\" (grouped display).", "enum": [ "asset_view", "dynamic_grouped_view", "export", "import", "search_view" ], "example": "export" } }, "required": [ "class_id", "type" ] } } } } } }, "/api/v3/mappings/get/": { "post": { "tags": [ "mappings" ], "summary": "Get mapping details", "description": "## Purpose\n\nReturns complete mapping configuration including metadata, permissions, and full data structure.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Mapping 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": "Empty string on success" }, "result": { "type": "object", "properties": { "id": { "type": "integer", "example": 1415, "description": "ID" }, "code": { "type": "string", "example": "export_products_csv", "description": "Mapping code" }, "label": { "type": "string", "example": "My Mapping", "description": "Label" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "tag1", "tag2" ], "description": "Array of tags (can be empty)" }, "class_id": { "type": "integer", "example": 4, "description": "Class ID" }, "type": { "type": "string", "example": "export", "description": "Mapping type" }, "permissions": { "type": "string", "example": "Group 1 | Group 2", "description": "Permissions" }, "creation_date": { "type": "string", "nullable": true, "example": "2016-02-17T00:00:00+01:00", "description": "Creation date (ISO 8601 format)" }, "creation_user": { "type": "string", "nullable": true, "example": "creation_user@company.com", "description": "Creation user" }, "modification_date": { "type": "string", "nullable": true, "example": "2018-02-17T00:00:00+01:00", "description": "Modification date (ISO 8601 format)" }, "modification_user": { "type": "string", "nullable": true, "example": "modification_user@company.com", "description": "Modification user" }, "last_use_date": { "type": "string", "nullable": true, "example": "2019-02-17T00:00:00+01:00", "description": "Last use date (ISO 8601 format)" }, "last_use_user": { "type": "string", "nullable": true, "example": "last_use_user@company.com", "description": "Last use user" }, "hash": { "type": "string", "example": "a84ef1b35017a6ce27eaca962d291124afaf005dc301656ef9b7492e29cc3d4d", "description": "Hash" }, "data": { "type": "object", "nullable": true, "description": "Data", "additionalProperties": true } }, "required": [ "id", "code", "label", "tags", "class_id", "type", "hash" ], "description": "Mapping information" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 997, "description": "Status code (997 = action not allowed)" }, "status_message": { "type": "string", "example": "You don't have the rights to do this action", "description": "Error message because no rights" }, "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": "Mapping ID. Use POST /api/v3/mappings/list with class_id to get available mappings.", "example": 140 } }, "required": [ "id" ] } } } } } }, "/api/v3/permissions/groups/list/": { "post": { "tags": [ "permissions" ], "summary": "List user groups (simplified)", "description": "## Purpose\n\nReturns simplified user group list (id, label) for dropdowns and selectors.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Simplified user groups 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": "Empty string on success" }, "result": { "type": "object", "properties": { "results_total": { "type": "integer", "example": 5, "description": "Total number of user groups returned" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 15, "description": "Group ID" }, "label": { "type": "string", "example": "My group", "description": "Group label" } }, "required": [ "id", "label" ] }, "description": "Array of simplified user groups objects" } }, "required": [ "results_total", "items" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 997, "description": "Status code (997 = action not allowed)" }, "status_message": { "type": "string", "example": "You don't have the rights to do this action", "description": "Error message because no rights" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array on error" } }, "required": [ "status_code", "status_message", "result" ] } ] } } } } } } }, "/api/v3/permissions/groups/full/": { "post": { "tags": [ "permissions" ], "summary": "Get full user group permissions", "description": "## Purpose\n\nReturns complete permissions configuration for all user groups (profiles, statuses, languages, display masks, overloads).\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Full user group permissions 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": "Empty string on success" }, "result": { "type": "object", "properties": { "results_total": { "type": "integer", "example": 5, "description": "Total number of user groups returned" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 15, "description": "Group ID" }, "label": { "type": "string", "example": "My group", "description": "Group label" }, "parent_id": { "type": "integer", "example": 1511, "description": "Parent group ID" }, "parent_label": { "type": "string", "example": "My group parent", "description": "Parent group label" }, "configuration": { "type": "object", "properties": { "langs": { "type": "object", "additionalProperties": true, "example": { "all_versions": true }, "description": "Multilingual" }, "default_display_mask": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true, "example": { "1025": "A mask" }, "description": "Default display mask" }, "profiles": { "type": "object", "properties": { "asset": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true, "example": { "25": "Full rights" }, "description": "Asset profile" }, "general": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true, "example": { "28": "Full rights" }, "description": "General profile" }, "project": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true, "example": { "35": "Full rights" }, "description": "Project profile" } } }, "status": { "type": "array", "items": { "type": "object", "properties": { "class_id": { "type": "integer", "example": 2, "description": "Class ID" }, "class_label": { "type": "string", "example": "DAM", "description": "Class label" }, "items": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "1093": "Active", "1096": "Inactive", "1114": "Archive" }, "description": "Status list by id (key = ID, value = label)" } }, "required": [ "class_id", "class_label", "items" ] }, "description": "Status list" }, "overload_by_status": { "type": "array", "items": { "type": "object", "properties": { "class_id": { "type": "integer", "example": 2, "description": "Class ID" }, "class_label": { "type": "string", "example": "DAM", "description": "Class label" }, "items": { "type": "object", "properties": { "status_id": { "type": "integer", "example": 1111, "description": "Status id" }, "status_label": { "type": "string", "example": "Proposed", "description": "Status label" }, "profile_asset": { "oneOf": [ { "type": "array", "items": { "type": "string" }, "example": [ "Default" ] }, { "type": "object", "additionalProperties": { "type": "string" }, "example": { "53": "Profile test" } } ], "description": "Asset profile" }, "mask": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "1064": "Full display mask" }, "description": "Display mask" } }, "required": [ "status_id", "status_label" ] } }, "required": [ "class_id", "class_label", "items" ] }, "description": "Overloaded by status" } }, "required": [ "langs", "default_display_mask", "profiles", "status", "overload_by_status" ], "description": "Group configuration (langs, default display mask, profiles, statuses and overload by status)" }, "users": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "2187": "login@company.com" }, "description": "Users in group" } }, "required": [ "id", "label", "parent_id", "parent_label", "configuration", "users" ] }, "description": "Array of user groups objects" } }, "required": [ "results_total", "items" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 997, "description": "Status code (997 = action not allowed)" }, "status_message": { "type": "string", "example": "You don't have the rights to do this action", "description": "Error message because no rights" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array on error" } }, "required": [ "status_code", "status_message", "result" ] } ] } } } } } } }, "/api/v3/permissions/groups/get/": { "post": { "tags": [ "permissions" ], "summary": "Get user group details", "description": "## Purpose\n\nReturns complete configuration for a specific user group by ID.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "User group 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": "Empty string on success" }, "result": { "type": "object", "properties": { "id": { "type": "integer", "example": 15, "description": "Group ID" }, "label": { "type": "string", "example": "My group", "description": "Group label" }, "parent_id": { "type": "integer", "example": 1511, "description": "Parent group ID" }, "parent_label": { "type": "string", "example": "My group parent", "description": "Parent group label" }, "configuration": { "type": "object", "properties": { "langs": { "type": "object", "additionalProperties": true, "example": { "all_versions": true }, "description": "Multilingual" }, "default_display_mask": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true, "example": { "1025": "A mask" }, "description": "Default display mask" }, "profiles": { "type": "object", "properties": { "asset": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true, "example": { "25": "Full rights" }, "description": "Asset profile" }, "general": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true, "example": { "28": "Full rights" }, "description": "General profile" }, "project": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true, "example": { "35": "Full rights" }, "description": "Project profile" } } }, "status": { "type": "array", "items": { "type": "object", "properties": { "class_id": { "type": "integer", "example": 2, "description": "Class ID" }, "class_label": { "type": "string", "example": "DAM", "description": "Class label" }, "items": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "1093": "Active", "1096": "Inactive", "1114": "Archive" }, "description": "Status list by id (key = ID, value = label)" } }, "required": [ "class_id", "class_label", "items" ] }, "description": "Status list" }, "overload_by_status": { "type": "array", "items": { "type": "object", "properties": { "class_id": { "type": "integer", "example": 2, "description": "Class ID" }, "class_label": { "type": "string", "example": "DAM", "description": "Class label" }, "items": { "type": "object", "properties": { "status_id": { "type": "integer", "example": 1111, "description": "Status id" }, "status_label": { "type": "string", "example": "Proposed", "description": "Status label" }, "profile_asset": { "oneOf": [ { "type": "array", "items": { "type": "string" }, "example": [ "Default" ] }, { "type": "object", "additionalProperties": { "type": "string" }, "example": { "53": "Profile test" } } ], "description": "Asset profile" }, "mask": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "1064": "Full display mask" }, "description": "Display mask" } }, "required": [ "status_id", "status_label" ] } }, "required": [ "class_id", "class_label", "items" ] }, "description": "Overloaded by status" } }, "required": [ "langs", "default_display_mask", "profiles", "status", "overload_by_status" ], "description": "Group configuration (langs, default display mask, profiles, statuses and overload by status)" }, "users": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "2187": "login@company.com" }, "description": "Users in group" } }, "required": [ "id", "label", "parent_id", "parent_label", "configuration", "users" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = not found, 997 = action not allowed)" }, "status_message": { "type": "string", "example": "Group not found", "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": "Group ID. Use POST /api/v3/permissions/groups/list to get available user groups.", "example": 15 } }, "required": [ "id" ] } } } } } }, "/api/v3/permissions/statuses/list/": { "post": { "tags": [ "permissions" ], "summary": "List statuses (simplified)", "description": "## Purpose\n\nReturns simplified status list (id, label, class) for a specific class.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Simplified statuses 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": "Empty string on success" }, "result": { "type": "object", "properties": { "results_total": { "type": "integer", "example": 5, "description": "Total number of statuses for this class" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1093, "description": "Status ID" }, "label": { "type": "string", "example": "Active", "description": "Status label" }, "class_id": { "type": "integer", "example": 2, "description": "Class ID" }, "class_label": { "type": "string", "example": "DAM", "description": "Class label" } }, "required": [ "id", "label", "class_id", "class_label" ] } } }, "required": [ "results_total", "items" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = not found, 997 = action not allowed)" }, "status_message": { "type": "string", "example": "No statuses found for this class", "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 identifier (e.g., 4=Products). Use POST /api/v3/administration/classes/list to retrieve available libraries.", "example": 2 } }, "required": [ "class_id" ] } } } } } }, "/api/v3/permissions/statuses/full/": { "post": { "tags": [ "permissions" ], "summary": "Get all statuses with details", "description": "## Purpose\n\nReturns workflow statuses for a class with full details (default flag, color configuration).\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Statuses 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": "Empty string on success" }, "result": { "type": "object", "properties": { "results_total": { "type": "integer", "example": 5, "description": "Total number of statuses for this class" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1093, "description": "Status ID" }, "label": { "type": "string", "example": "Active", "description": "Status label" }, "class_id": { "type": "integer", "example": 2, "description": "Class ID" }, "class_label": { "type": "string", "example": "DAM", "description": "Class label" }, "default": { "type": "boolean", "example": true, "description": "Whether this is the default status (only for one status by class)" }, "color": { "type": "string", "nullable": true, "example": "#00FF00", "description": "Status color" } }, "required": [ "id", "label", "class_id", "class_label", "default", "color" ] } } }, "required": [ "results_total", "items" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = not found, 997 = action not allowed)" }, "status_message": { "type": "string", "example": "No statuses found for this class", "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 identifier (e.g., 4=Products). Use POST /api/v3/administration/classes/list to retrieve available libraries.", "example": 2 } }, "required": [ "class_id" ] } } } } } }, "/api/v3/permissions/statuses/get/": { "post": { "tags": [ "permissions" ], "summary": "Get status details", "description": "## Purpose\n\nReturns complete status configuration by ID (label, class, default flag, color).\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Status 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": "Empty string on success" }, "result": { "type": "object", "properties": { "id": { "type": "integer", "example": 1093, "description": "Status ID" }, "label": { "type": "string", "example": "Active", "description": "Status label" }, "class_id": { "type": "integer", "example": 2, "description": "Class ID" }, "class_label": { "type": "string", "example": "DAM", "description": "Class label" }, "default": { "type": "boolean", "example": true, "description": "Whether this is the default status" }, "color": { "type": "string", "nullable": true, "example": "#00FF00", "description": "Status color" } }, "required": [ "id", "label", "class_id", "class_label", "default" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = not found, 997 = action not allowed)" }, "status_message": { "type": "string", "example": "Status not found", "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": "Status ID. Use POST /api/v3/permissions/statuses/list to get available statuses.", "example": 1093 } }, "required": [ "id" ] } } } } } }, "/api/v3/permissions/profiles/list/": { "post": { "tags": [ "permissions" ], "summary": "List profiles (simplified)", "description": "## Purpose\n\nReturns simplified profile list (id, label, type) grouped by profile type (general, project, asset).\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Simplified profiles 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": "Empty string on success" }, "result": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "general", "description": "Profile type: general, project or asset" }, "results_total": { "type": "integer", "example": 5, "description": "Total number of profiles for this type" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1415, "description": "Profile ID" }, "label": { "type": "string", "example": "My profile", "description": "Profile label" } }, "required": [ "id", "label" ] } } }, "required": [ "type", "results_total", "items" ] } } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 997, "description": "Status code (997 = action not allowed)" }, "status_message": { "type": "string", "example": "You don't have the rights to do this action", "description": "Error message because no rights" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array on error" } }, "required": [ "status_code", "status_message", "result" ] } ] } } } } } } }, "/api/v3/permissions/profiles/full/": { "post": { "tags": [ "permissions" ], "summary": "Get full profile permissions", "description": "## Purpose\n\nReturns all profiles with complete permissions configuration (module access, universes, mount points, statuses).\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Profile permissions 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": "Empty string on success" }, "result": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "general", "description": "Profile type label : general, project or asset" }, "results_total": { "type": "integer", "example": 5, "description": "Total number of profiles returned for this profile type" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1415, "description": "Profile ID" }, "label": { "type": "string", "example": "My profile", "description": "Profile label" }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string", "example": "Access to modules", "description": "Group name" }, "items": { "type": "object", "additionalProperties": true, "example": { "Workflow": true, "FrontCatalog": false }, "description": "Dynamic keys : permission name => value (true or false)" } }, "required": [ "group", "items" ] }, "description": "Permissions" }, "managed_universe": { "type": "object", "additionalProperties": true, "nullable": true, "example": { "5": 5 }, "description": "Universe list" }, "user_mount_points": { "type": "object", "additionalProperties": true, "nullable": true, "example": { "5": 5 }, "description": "User mount points" }, "other_statuses_available": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true, "example": { "1093": "Active", "1096": "Inactive" }, "description": "Statuses to manage" }, "assignable_labels": { "type": "object", "additionalProperties": true, "nullable": true, "example": { "11": 11, "22": 22 }, "description": "Labels to manage" } }, "required": [ "id", "label", "permissions" ], "description": "Profile information" } } }, "required": [ "type", "results_total", "items" ], "description": "List of profiles for the profile type" } } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 997, "description": "Status code (997 = action not allowed)" }, "status_message": { "type": "string", "example": "You don't have the rights to do this action", "description": "Error message because no rights" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array on error" } }, "required": [ "status_code", "status_message", "result" ] } ] } } } } } } }, "/api/v3/permissions/profiles/get/": { "post": { "tags": [ "permissions" ], "summary": "Get profile details", "description": "## Purpose\n\nReturns complete permissions configuration for a specific profile by ID.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Profile 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": "Empty string on success" }, "result": { "type": "object", "properties": { "id": { "type": "integer", "example": 1415, "description": "Profile ID" }, "label": { "type": "string", "example": "My profile", "description": "Profile label" }, "type": { "type": "string", "example": "general", "description": "Profile type: general, project or asset" }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "group": { "type": "string", "example": "Access to modules", "description": "Group name" }, "items": { "type": "object", "additionalProperties": true, "example": { "Workflow": true, "FrontCatalog": false }, "description": "Dynamic keys : permission name => value (true or false)" } }, "required": [ "group", "items" ] }, "description": "Permissions" }, "managed_universe": { "type": "object", "additionalProperties": true, "nullable": true, "example": { "5": 5 }, "description": "Universe list" }, "user_mount_points": { "type": "object", "additionalProperties": true, "nullable": true, "example": { "5": 5 }, "description": "User mount points" }, "other_statuses_available": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true, "example": { "1093": "Active", "1096": "Inactive" }, "description": "Statuses to manage" }, "assignable_labels": { "type": "object", "additionalProperties": true, "nullable": true, "example": { "11": 11, "22": 22 }, "description": "Labels to manage" } }, "required": [ "id", "label", "type", "permissions" ], "description": "Profile information" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = not found, 997 = action not allowed)" }, "status_message": { "type": "string", "example": "Profile not found", "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": "Profile ID. Use POST /api/v3/permissions/profiles/list to get available profiles.", "example": 1415 } }, "required": [ "id" ] } } } } } }, "/api/v3/permissions/masks/list/": { "post": { "tags": [ "permissions" ], "summary": "List display masks (simplified)", "description": "## Purpose\n\nReturns simplified display mask list (id, label) for dropdowns and selectors.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Simplified display masks 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": "Empty string on success" }, "result": { "type": "object", "properties": { "results_total": { "type": "integer", "example": 10, "description": "Total number of display masks returned" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1025, "description": "Mask ID" }, "label": { "type": "string", "example": "Standard mask", "description": "Mask label" } }, "required": [ "id", "label" ] } } }, "required": [ "results_total", "items" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 997, "description": "Status code (997 = action not allowed)" }, "status_message": { "type": "string", "example": "You don't have the rights to do this action", "description": "Error message because no rights" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array on error" } }, "required": [ "status_code", "status_message", "result" ] } ] } } } } } } }, "/api/v3/permissions/masks/full/": { "post": { "tags": [ "permissions" ], "summary": "Get all display masks with details", "description": "## Purpose\n\nReturns all display masks for a class with attribute-level read/write/hidden permissions.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Display masks 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": "Empty string on success" }, "result": { "type": "object", "properties": { "results_total": { "type": "integer", "example": 10, "description": "Total number of display masks returned" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1025, "description": "Mask ID" }, "label": { "type": "string", "example": "Standard mask", "description": "Mask label" }, "class_id": { "type": "integer", "example": 2, "description": "Class ID" }, "class_label": { "type": "string", "example": "DAM", "description": "Class label" }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 123, "description": "Attribute ID" }, "label": { "type": "string", "example": "Product name", "description": "Attribute label" }, "hidden": { "type": "boolean", "example": false, "description": "Whether attribute is hidden" }, "read": { "type": "boolean", "example": true, "description": "Whether attribute is readable" }, "write": { "type": "boolean", "example": true, "description": "Whether attribute is writable" }, "locally_editable": { "type": "boolean", "example": false, "description": "Whether attribute is locally editable (asset share)" } }, "required": [ "id", "label", "hidden", "read", "write", "locally_editable" ] }, "description": "Attributes configuration for the class" } }, "required": [ "id", "label", "class_id", "class_label", "attributes" ] } } }, "required": [ "results_total", "items" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 997, "description": "Status code (997 = action not allowed)" }, "status_message": { "type": "string", "example": "You don't have the rights to do this action", "description": "Error message because no rights" }, "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 identifier (e.g., 4=Products). Use POST /api/v3/administration/classes/list to retrieve available libraries.", "example": 2 } }, "required": [ "class_id" ] } } } } } }, "/api/v3/permissions/masks/get/": { "post": { "tags": [ "permissions" ], "summary": "Get display mask details", "description": "## Purpose\n\nReturns complete mask configuration with attribute-level permissions (read/write/hidden) for a specific class.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Display mask 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": "Empty string on success" }, "result": { "type": "object", "properties": { "id": { "type": "integer", "example": 1025, "description": "Mask ID" }, "label": { "type": "string", "example": "Standard mask", "description": "Mask label" }, "class_id": { "type": "integer", "example": 2, "description": "Class ID" }, "class_label": { "type": "string", "example": "DAM", "description": "Class label" }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 123, "description": "Attribute ID" }, "label": { "type": "string", "example": "Product name", "description": "Attribute label" }, "hidden": { "type": "boolean", "example": false, "description": "Whether attribute is hidden" }, "read": { "type": "boolean", "example": true, "description": "Whether attribute is readable" }, "write": { "type": "boolean", "example": true, "description": "Whether attribute is writable" }, "locally_editable": { "type": "boolean", "example": false, "description": "Whether attribute is locally editable (asset share)" } }, "required": [ "id", "label", "hidden", "read", "write", "locally_editable" ] }, "description": "Attributes configuration for the class" } }, "required": [ "id", "label", "class_id", "class_label", "attributes" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = not found, 997 = action not allowed)" }, "status_message": { "type": "string", "example": "Mask not found", "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": "Mask ID. Use POST /api/v3/permissions/masks/list to get available display masks.", "example": 1025 }, "class_id": { "type": "integer", "description": "Library identifier (e.g., 4=Products). Use POST /api/v3/administration/classes/list to retrieve available libraries.", "example": 2 } }, "required": [ "id", "class_id" ] } } } } } }, "/api/v3/permissions/masks/assign-attributes/": { "post": { "tags": [ "permissions" ], "summary": "Sync attribute permissions for a display mask, scoped to a library (add, update, remove)", "description": "## Purpose\n\nSynchronizes which attributes are visible/editable in a display mask, **scoped to a single library**. Send the **complete desired state** for all attributes of that library in the mask: the endpoint computes a diff and applies additions, updates, and removals automatically.\n\n## Inverse of attributes/assign-masks\n\n- `attributes/assign-masks` — given **one attribute**, sync all its masks\n- `permissions/masks/assign-attributes` — given **one mask**, sync all attributes of a library in that mask\n\n## Library Scope\n\nThe `class_id` parameter scopes the sync to a specific library. Only attributes belonging to that library are considered:\n- Attributes in the request → processed (added/updated/hidden)\n- Attributes of the library currently in the mask but NOT in the request → **removed**\n- Attributes from other libraries in the same mask → **untouched**\n\n## Sync Behavior\n\n- Attribute in request AND in mask → **updated** if permissions differ, **unchanged** if identical\n- Attribute in request but NOT in mask → **added** (unless `permission: \"hidden\"`, which is a no-op)\n- Attribute of this library in mask but NOT in request → **removed**\n- Mask 10 (full display mask) is always rejected with `status_code: 2`\n\n## Partial Failures\n\nInvalid entries (unknown attribute ID or code, missing fields) do NOT fail the whole request — valid entries are still applied and `status_code` remains 1. All failures are reported in `result.errors`.\n\n## Permission Values\n\n- `\"hidden\"` — attribute not visible in this mask (no DB entry)\n- `\"read\"` — attribute visible, read-only\n- `\"write\"` — attribute visible and editable\n\n## locally_editable\n\nOnly applies when `permission: \"write\"`. When `true`, the reference value can be edited locally in assetShare. Ignored for `hidden` and `read` (always stored as false).\n\n## Accepts IDs or Codes\n\n- `id` (mask): integer mask ID only. Use `POST /api/v3/permissions/masks/list/` to list available masks with their IDs and labels.\n- `attribute`: attribute ID (integer or numeric string, e.g. 231) or attribute code (string, case-insensitive). Use `POST /api/v3/attributes/list` with class_id to get available attribute IDs and codes.\n\n## Related Endpoints\n\n- `attributes/assign-masks` — inverse: sync masks for a single attribute\n- `permissions/masks/list` — list available display masks with IDs and labels\n- `permissions/masks/get` — read current attribute permissions for a mask in a library\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Sync result response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Success Response", "properties": { "status_code": { "type": "integer", "example": 1, "description": "Always 1 for this endpoint, even when some entries failed (partial failures are reported in result.errors, not via status_code)" }, "status_message": { "type": "string", "example": "2 added, 1 updated, 1 removed", "description": "Summary of changes. Suffix \"(N error(s))\" is appended when result.errors is non-empty. \"No changes\" when nothing changed." }, "result": { "type": "object", "properties": { "mask_id": { "type": "integer", "example": 3, "description": "Resolved mask ID" }, "class_id": { "type": "integer", "example": 4, "description": "Library ID used for scoping" }, "attributes": { "type": "array", "description": "Per-attribute action details. Covers attributes in the request and attributes removed by sync.", "items": { "type": "object", "properties": { "attribute_id": { "type": "integer", "example": 231 }, "action": { "type": "string", "enum": [ "added", "updated", "unchanged", "removed" ], "example": "added" }, "permission": { "type": "string", "enum": [ "read", "write" ], "description": "Absent when action is \"removed\". Always false for locally_editable when permission is \"read\".", "example": "write" }, "locally_editable": { "type": "boolean", "description": "Absent when action is \"removed\". Always false when permission is \"read\".", "example": true } } } }, "total_added": { "type": "integer", "example": 2 }, "total_updated": { "type": "integer", "example": 1 }, "total_removed": { "type": "integer", "example": 1 }, "cache_refreshed": { "type": "boolean", "example": true }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Per-entry errors that did not block execution. Valid entries are still applied.", "example": [ "Attribute not found in class 4: code_inexistant" ] } } } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code 2 when mask not found, mask 10 targeted, or class_id invalid" }, "status_message": { "type": "string", "example": "Mask 10 (full display mask) cannot be modified", "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": "Mask ID. Mask 10 is always rejected. Use POST /api/v3/permissions/masks/list/ to get available mask IDs.", "example": 1027 }, "class_id": { "type": "integer", "description": "Library ID. Scopes the sync — only attributes of this library are considered. Attributes from other libraries in the same mask are left untouched. Use POST /api/v3/administration/classes/list to get available library IDs.", "example": 4 }, "assignments": { "type": "array", "description": "Complete desired attribute state for this mask, scoped to the library. Each entry must have \"attribute\" (integer ID or string code — use POST /api/v3/attributes/list with class_id to discover) and \"permission\" (\"hidden\", \"read\", or \"write\"). Optionally include \"locally_editable\" (boolean, only effective with \"write\"). WARNING: this is a SYNC operation — attributes of this library currently in the mask but absent from this list will be REMOVED. Send an empty array [] to remove all attributes of this library from the mask. (Array of objects - see example for structure)", "items": { "type": "object", "properties": { "attribute": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Attribute ID (integer or numeric string, e.g. 231 or \"231\") or attribute code (string, case-insensitive). Use POST /api/v3/attributes/list with class_id to discover available attributes.", "example": 231 }, "permission": { "type": "string", "description": "Desired permission level for this attribute in the mask.", "enum": [ "hidden", "read", "write" ], "example": "write" }, "locally_editable": { "type": "boolean", "description": "Only effective when permission is \"write\". Defaults to false.", "example": true } }, "required": [ "attribute", "permission" ], "title": "Item" } } }, "required": [ "id", "class_id", "assignments" ] } } } } } }, "/api/v3/preferences/full/": { "post": { "tags": [ "preferences" ], "summary": "Get all preferences with details", "description": "## Purpose\n\nReturns all user preferences for a class with complete configuration (context, type/node assignments, attributes).\n\n## Contexts\n\n- `general`: Global preferences\n- `type`: Per asset-type preferences\n- `node`: Per node preferences\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Preference 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": { "id": { "type": "integer", "example": 1, "description": "Preference ID" }, "code": { "type": "string", "example": "my_preference_code", "description": "Preference code" }, "label": { "type": "string", "example": "Display in list", "description": "Preference label" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "tag1", "tag2" ], "description": "Array of tags (can be empty)" }, "context": { "type": "array", "items": { "type": "string", "enum": [ "general", "type", "node" ] }, "example": [ "general", "type" ], "description": "Array of applicable contexts. Possible values: general, type, node" }, "results_total": { "type": "integer", "example": 2, "description": "Total number of items for this preference" }, "items": { "type": "array", "items": { "type": "object", "properties": { "type_id": { "type": "integer", "example": 5, "description": "Asset type ID (0 for global)" }, "type_label": { "type": "string", "example": "Product", "description": "Asset type label (empty for global)" }, "node_id": { "type": "integer", "example": 0, "description": "Node ID (0 for global)" }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 125, "description": "Attribute ID" }, "label": { "type": "string", "example": "Name", "description": "Attribute label" }, "order": { "type": "integer", "example": 1, "description": "Display order" } }, "required": [ "id", "label", "order" ] }, "description": "Array of attributes for this type/node combination" } }, "required": [ "type_id", "type_label", "node_id", "attributes" ] }, "description": "Array of preference configurations by type and node" } }, "required": [ "id", "code", "label", "tags", "context", "results_total", "items" ] }, "description": "Array of preferences with their configurations" } }, "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 } }, "required": [ "class_id" ] } } } } } }, "/api/v3/preferences/list/": { "post": { "tags": [ "preferences" ], "summary": "List preferences (simplified)", "description": "## Purpose\n\nReturns simplified preference list (id, code, label, tags, context) without attribute details.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Preference 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": { "id": { "type": "integer", "example": 1, "description": "Preference ID" }, "code": { "type": "string", "example": "my_preference_code", "description": "Preference code" }, "label": { "type": "string", "example": "Display in list", "description": "Preference label" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "tag1", "tag2" ], "description": "Array of tags (can be empty)" }, "context": { "type": "array", "items": { "type": "string", "enum": [ "general", "type", "node" ] }, "example": [ "general", "type" ], "description": "Array of applicable contexts. Possible values: general, type, node" } }, "required": [ "id", "code", "label", "tags", "context" ] }, "description": "Array of preferences with id and label" } }, "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 } }, "required": [ "class_id" ] } } } } } }, "/api/v3/preferences/get/": { "post": { "tags": [ "preferences" ], "summary": "Get preference by context", "description": "## Purpose\n\nReturns preference configuration for a specific context (general, type, or node).\n\n## Context Usage\n\n- `general`: No context_id needed\n- `type`: Provide type_id as context_id\n- `node`: Provide node_id as context_id\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Preference details 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": "object", "properties": { "id": { "type": "integer", "example": 1, "description": "Preference ID" }, "code": { "type": "string", "example": "my_preference_code", "description": "Preference code" }, "label": { "type": "string", "example": "Display in list", "description": "Preference label" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "tag1", "tag2" ], "description": "Array of tags (can be empty)" }, "context": { "type": "array", "items": { "type": "string", "enum": [ "general", "type", "node" ] }, "example": [ "general", "type" ], "description": "Array of applicable contexts. Possible values: general, type, node" }, "type_id": { "type": "integer", "example": 5, "description": "Asset type ID (0 for global)" }, "type_label": { "type": "string", "example": "Product", "description": "Asset type label (empty for global)" }, "node_id": { "type": "integer", "example": 0, "description": "Node ID (0 for global)" }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 125, "description": "Attribute ID" }, "label": { "type": "string", "example": "Name", "description": "Attribute label" }, "order": { "type": "integer", "example": 1, "description": "Display order" } }, "required": [ "id", "label", "order" ] }, "description": "Array of attributes" } }, "required": [ "id", "code", "label", "tags", "context", "type_id", "type_label", "node_id", "attributes" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = error)" }, "status_message": { "type": "string", "example": "Preference not found", "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 }, "id": { "type": "integer", "description": "Preference ID. Use POST /api/v3/preferences/list to get available preferences.", "example": 1 }, "context": { "type": "string", "description": "Context filter: \"general\" (global), \"type\" (per asset-type), or \"node\" (per node).", "enum": [ "general", "type", "node" ], "example": "type" }, "context_id": { "type": "integer", "description": "Context-dependent ID. If context=\"type\": provide type_id (use POST /api/v3/types/list with class_id to get type IDs). If context=\"node\": provide project node_id (use POST /api/v3/projects/list with class_id to get project node IDs). Not required if context=\"general\".", "example": 5 } }, "required": [ "class_id", "id", "context" ] } } } } } }, "/api/v3/preferences/update/": { "post": { "tags": [ "preferences" ], "summary": "Update preference attributes", "description": "## Purpose\n\nUpdates the list of attributes assigned to a preference for a given context (general, type, or node).\n\n## Behavior\n\nThis is a **complete replacement** operation: the provided `attribute_ids` array replaces all existing attributes for the specified preference and context. To remove all attributes, pass an empty array.\n\n## Context Usage\n\n- `general`: Updates global preference (no context_id needed, type_id=0, node_id=0)\n- `type`: Updates preference for a specific asset type (provide context_id = type_id)\n- `node`: Updates preference for a specific tree node (provide context_id = node_id)\n\n## Important\n\n- The preference must support the requested context (check its `application` code via preferences/get or preferences/list)\n- Attribute IDs must be valid role IDs from the library. Use POST /api/v3/attributes/list to get available attributes.\n- Order of attributes is preserved as provided in the array.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Preference update 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": "Preference updated successfully", "description": "Status message" }, "result": { "type": "object", "properties": { "id": { "type": "integer", "example": 1, "description": "Preference ID" }, "context": { "type": "string", "example": "general", "description": "Context that was updated" }, "context_id": { "type": "integer", "example": 0, "description": "Context ID (0 for general)" }, "attributes_count": { "type": "integer", "example": 3, "description": "Number of attributes assigned" } }, "required": [ "id", "context", "context_id", "attributes_count" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = validation error, 3 = not found)" }, "status_message": { "type": "string", "example": "Preference not found", "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 }, "id": { "type": "integer", "description": "Preference ID to update. Use POST /api/v3/preferences/list to get available preferences.", "example": 1 }, "context": { "type": "string", "description": "Context level: \"general\" (library-wide), \"type\" (per asset-type), or \"node\" (per tree node).", "enum": [ "general", "type", "node" ], "example": "general" }, "context_id": { "type": "integer", "description": "Context-dependent ID. Required when context=\"type\" (provide type_id, use POST /api/v3/types/list) or context=\"node\" (provide node_id, use POST /api/v3/projects/list). Defaults to 0 when omitted (general context).", "example": 5 }, "attribute_ids": { "type": "array", "description": "Array of attribute/role IDs to assign to this preference. Replaces all existing attributes. Pass empty array [] to clear. Use POST /api/v3/attributes/list to get available attribute IDs.", "example": [ 101, 102, 103 ], "items": { "type": "integer" } } }, "required": [ "class_id", "id", "context", "attribute_ids" ] } } } } } }, "/api/v3/processes/execute/": { "post": { "tags": [ "processes" ], "summary": "Execute automated process", "description": "## Purpose\n\nLaunches an automation and returns identification key for progress tracking.\n\n## Use Cases\n\n- Execute exports, imports, workflows\n- Trigger scheduled tasks\n- Run bulk operations\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Process execution 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": "object", "properties": { "identification_key": { "type": "string", "example": "89141ccc93665f1463c845ccc7d57559", "description": "Unique identification key for tracking the process execution" } }, "required": [ "identification_key" ], "description": "Process execution details" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = error, 0 = process not found)" }, "status_message": { "type": "string", "example": "Process not found or execution failed", "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": "Process ID. Use POST /api/v3/processes/list with class_id to get available processes.", "example": 125 }, "class_id": { "type": "integer", "description": "Library ID. Use POST /api/v3/administration/classes/list to get available libraries.", "example": 54 }, "current_node": { "type": "integer", "description": "Specify the current node to be used by actions that are configured with a \"current node\" option. Use POST /api/v3/get-asset/by-search/node to find project nodes, or POST /api/v3/publishing/list to find publication project nodes. Affected actions include: \"Change the status\", \"Export\", \"Exporting deleted records\", \"Import\", \"Multiple actions and rules\", and \"Publish to EasyCatalog\".", "example": 11450 }, "variables": { "type": "object", "description": "Process variables as key-value pairs. Variable names are defined in the process configuration. Use POST /api/v3/processes/get with process id to see available variables.", "example": { "OUTPUT_FORMAT": "csv", "EXPORT_PATH": "/exports/daily" } } }, "required": [ "id", "class_id" ] } } } } } }, "/api/v3/processes/get/": { "post": { "tags": [ "processes" ], "summary": "Get process configuration", "description": "## Purpose\n\nReturns complete process definition including actions, parameters, triggers, availability settings, and which processes call this one.\n\n## When to Use\n\n- Use after POST /api/v3/processes/list to get full details of a specific process before executing it\n- Check `variables` to know which runtime parameters the process accepts (pass them to `execute`)\n- Check `actions` to understand what the process will do (export, import, status change, etc.)\n- Check `applicable_to_*` fields to verify if the process can be applied to specific users/types/statuses\n- Check `trigger_type` to know if the process is manual or workflow-triggered\n- Check `used_by` to find which other processes call this one (reverse dependency)\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Process 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" }, "result": { "type": "object", "properties": { "id": { "type": "integer", "example": 686, "description": "Process ID" }, "code": { "type": "string", "example": "export_products_xml", "description": "Process code" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "export", "products" ], "description": "Array of tags (can be empty)" }, "class_id": { "type": "integer", "example": 4, "description": "Class ID" }, "label": { "type": "string", "example": "My process", "description": "Process label" }, "active": { "type": "boolean", "nullable": true, "example": true, "description": "Whether the process is active" }, "description": { "type": "string", "example": "Description of the process", "description": "Process description" }, "user_description": { "type": "string", "example": "User description of the process", "description": "Process user description" }, "order": { "type": "integer", "nullable": true, "example": 1, "description": "Display order" }, "parent_group_id": { "type": "integer", "example": 26, "description": "Process parent group ID" }, "parent_group_label": { "type": "string", "example": "Label of parent group 26", "description": "Process parent group label" }, "applicable_to_users": { "oneOf": [ { "type": "array", "items": { "type": "string" }, "example": [ "all" ] }, { "type": "object", "additionalProperties": { "type": "string" }, "example": { "1555": "Admin test", "1645": "Product Manager" } } ], "nullable": true, "description": "Permissions to apply the process to users. Can be 'all', 'admin', or a map of user IDs to labels" }, "applicable_to_asset_types": { "oneOf": [ { "type": "array", "items": { "type": "string" }, "example": [ "all" ] }, { "type": "object", "additionalProperties": { "type": "string" }, "example": { "195": "Article" } } ], "nullable": true, "description": "Permissions to apply the process to asset types. Can be 'all' or a map of type IDs to labels" }, "applicable_to_asset_status": { "oneOf": [ { "type": "array", "items": { "type": "string" }, "example": [ "all" ] }, { "type": "object", "additionalProperties": { "type": "string" }, "example": { "1111": "Proposed" } } ], "nullable": true, "description": "Permissions to apply the process to asset status. Can be 'all' or a map of status IDs to labels" }, "variables": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" }, "example": { "MY_VARIABLE": "test" }, "description": "Process variables" }, "trigger_type": { "type": "string", "enum": [ "manual", "workflow" ], "example": "manual", "description": "How the process can be triggered: \"manual\" (by user action) or \"workflow\" (automatically on workflow step change)" }, "availability": { "type": "object", "properties": { "in_actions_panel": { "type": "boolean", "example": true, "description": "Available in the global \"Actions\" interface listing all manual processes" }, "on_asset": { "type": "boolean", "example": false, "description": "Available from an asset detail view (executable directly on a fiche)" } }, "description": "Where the process is available in the UI (only relevant for manual processes)" }, "is_scheduled": { "type": "boolean", "example": false, "description": "Whether this process is scheduled (added to a scheduler for automated execution at specific times)" }, "image": { "type": "string", "nullable": true, "example": "/design/default/processus/processus.png", "description": "Image path" }, "image_http": { "type": "string", "nullable": true, "example": "https://my-afineo.com/design/default/processus/processus.png", "description": "Image URL" }, "actions": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 54, "description": "Process action ID" }, "process_linked_id": { "type": "integer", "example": 687, "description": "Process linked ID" }, "label": { "type": "string", "example": "Export", "description": "Action label" }, "label_custom": { "type": "string", "example": "Export custom", "description": "Action label custom" }, "form": { "type": "string", "example": "export_configuration", "description": "Action form" }, "type": { "type": "string", "example": "action", "description": "Action type functional : action or process" }, "type_action": { "type": "string", "example": "action", "description": "Action type technical : Export a configuration, Import, etc." }, "order": { "type": "integer", "example": 1, "description": "Display order" }, "parameters": { "oneOf": [ { "type": "array", "items": { "type": "object" } }, { "type": "object" } ], "example": { "label_action": "", "description_action": "", "mapping_id": "1173" }, "description": "Action parameters" }, "mapping_id": { "oneOf": [ { "type": "string", "example": "1234" }, { "type": "integer", "example": 1234 } ], "description": "Mapping ID : empty string if no value" }, "image": { "type": "string", "nullable": true, "example": "/UPLOADS/processus/actions/image.png", "description": "Image path" }, "image_http": { "type": "string", "nullable": true, "example": "https://my-afineo.com/gallery/global/UPLOADS/processus/actions/image.png", "description": "Image URL" } }, "required": [ "id", "process_linked_id", "label", "label_custom", "form", "type", "type_action", "order", "parameters", "mapping_id" ] }, "description": "List of actions for the process" }, "schedulers": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" }, "example": { "15": "Scheduler label" }, "description": "Map of scheduler IDs to labels" }, "used_by": { "type": "array", "items": { "type": "object", "properties": { "process_id": { "type": "integer", "example": 45, "description": "ID of the calling process" }, "label": { "type": "string", "example": "Import Global", "description": "Label of the calling process" }, "class_id": { "type": "integer", "example": 4, "description": "Class ID of the calling process" }, "call_type": { "type": "string", "enum": [ "sub_process", "others_processus_action" ], "example": "sub_process", "description": "How this process is called: \"sub_process\" (direct sub-process via regle_lie) or \"others_processus_action\" (cross-library call)" } }, "required": [ "process_id", "label", "class_id", "call_type" ] }, "description": "List of processes that call this process (reverse lookup). Empty array if no callers found." } }, "required": [ "id", "code", "tags", "class_id", "label", "description", "user_description", "parent_group_id", "parent_group_label" ], "description": "Process 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 = process not found)" }, "status_message": { "type": "string", "example": "Process 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": "Process ID. Use POST /api/v3/processes/list with class_id to get available processes.", "example": 125 } }, "required": [ "id" ] } } } } } }, "/api/v3/processes/get-logs/": { "post": { "tags": [ "processes" ], "summary": "Get process execution logs", "description": "## Purpose\n\nReturns execution history with status details for troubleshooting and auditing.\n\n## Date Filtering\n\nUse either `one_day` OR `start_date` + `end_date` together.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Process logs 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": "object", "properties": { "raw_data": { "type": "boolean", "example": false, "description": "Raw data flag" }, "items": { "type": "array", "items": { "type": "object", "properties": { "process_id": { "type": "integer", "example": 686, "description": "Process ID" }, "process_label": { "type": "string", "example": "My process", "description": "Process label" }, "user_id": { "type": "integer", "example": 1687, "description": "User ID execution process" }, "process_start_date": { "type": "string", "example": "2025-08-29T09:55:52+02:00", "description": "Process start date (ISO 8601 format)" }, "process_end_date": { "type": "string", "example": "2025-08-29T09:55:55+02:00", "description": "Process end date (ISO 8601 format)" }, "state": { "type": "string", "nullable": true, "example": "Completed", "description": "Process state" }, "actions": { "type": "array", "items": { "type": "object", "properties": { "action_id": { "type": "string", "example": "---", "description": "Action ID" }, "action_label": { "type": "string", "example": "Export a configuration", "description": "Action label" }, "action_start_date": { "type": "string", "example": "2025-08-29T09:55:52+02:00", "description": "Action start date (ISO 8601 format)" }, "action_end_date": { "type": "string", "example": "2025-08-29T09:55:55+02:00", "description": "Action end date (ISO 8601 format)" }, "action_details": { "type": "string", "example": "Executing rule: XML export", "description": "Action details" } }, "required": [ "action_id", "action_label", "action_start_date", "action_end_date", "action_details" ], "description": "Action information" } } }, "required": [ "process_id", "process_label", "user_id", "process_start_date", "process_end_date", "state", "actions" ], "description": "Process logs item" } } }, "required": [ "raw_data", "items" ], "description": "Process logs data" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = error, 2 = parameters configuration error, 0 = process not found)" }, "status_message": { "type": "string", "example": "The parameter \"start_date\" must be anterior to the parameter \"end_date\"", "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": "Process ID. Use POST /api/v3/processes/list with class_id to get available processes.", "example": 125 }, "start_date": { "type": "string", "description": "Start date (ISO 8601 format). The \"start_date\" and \"end_date\" parameters are to be used together.", "example": "2025-10-25T08:10:00Z" }, "end_date": { "type": "string", "description": "End date (ISO 8601 format). The \"start_date\" and \"end_date\" parameters are to be used together.", "example": "2025-10-26T10:52:00Z" }, "one_day": { "type": "string", "description": "Date of a given day (Format YYYY-MM-DD). You must either use the \"one_day\" parameter or use the \"start_date\" and \"end_date\" parameters.", "example": "2025-07-10" }, "response_type": { "type": "string", "description": "Response format : \"html\", \"plainText\", \"xml\", \"json\"", "enum": [ "html", "plainText", "xml", "json" ], "example": "json" } }, "required": [ "id" ] } } } } } }, "/api/v3/processes/get-instance-state/": { "post": { "tags": [ "processes" ], "summary": "Check process execution status", "description": "## Purpose\n\nReturns real-time execution state and available files using identification_key from execute endpoint.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Process instance state 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": "No files to return", "description": "Status message" }, "result": { "type": "object", "properties": { "start_date": { "type": "string", "example": "2025-08-29T09:55:52+02:00", "description": "Process execution start date (ISO 8601 format)" }, "end_date": { "type": "string", "example": "2025-08-29T09:55:55+02:00", "description": "Process execution end date (ISO 8601 format)" }, "state": { "type": "string", "nullable": true, "example": "Finished", "description": "Process execution state" }, "notification": { "type": "string", "nullable": true, "example": "", "description": "Notification message if error" }, "completed": { "type": "boolean", "example": true, "description": "Whether the process execution is completed" }, "available_files": { "type": "array", "items": { "type": "string" }, "example": [ "myfile.csv" ], "description": "List of available files" }, "unavailable_files": { "type": "array", "items": { "type": "string" }, "example": [ "myfile2.csv" ], "description": "List of unavailable files" } }, "required": [ "start_date", "end_date", "completed", "available_files", "unavailable_files" ], "description": "Process instance state 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 = process not found)" }, "status_message": { "type": "string", "example": "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": { "identification_key": { "type": "string", "description": "Identification key (returned by endpoint \"execute\")", "example": "89141ccc93665f1463c845ccc7d57559" } }, "required": [ "identification_key" ] } } } } } }, "/api/v3/processes/get-file/": { "post": { "tags": [ "processes" ], "summary": "Download process-generated file", "description": "## Purpose\n\nDownloads file generated by a completed process using identification_key and file_key.\n\n## Workflow\n\n1. Call `execute` to get identification_key\n2. Call `get-instance-state` to get available_files list\n3. Call this endpoint to download each file\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Process file content 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": "object", "properties": { "raw_data": { "type": "boolean", "example": false, "description": "Raw data flag" }, "items": { "type": "string", "example": "...", "description": "File content" } }, "required": [ "raw_data", "items" ], "description": "Generated file content" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = error, 0 = file not found)" }, "status_message": { "type": "string", "example": "No files to return", "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": { "identification_key": { "type": "string", "description": "Identification key (returned by endpoint \"execute\")", "example": "89141ccc93665f1463c845ccc7d57559" }, "file_key": { "type": "string", "description": "File key returned in the 'available_files' array of POST /api/v3/processes/get-instance-state response. Each file generated by the process has a unique key.", "example": "Global_SOLO_EXPORT" } }, "required": [ "identification_key", "file_key" ] } } } } } }, "/api/v3/processes/full/": { "post": { "tags": [ "processes" ], "summary": "List processes (full details)", "description": "## Purpose\n\nReturns all processes for a class with complete configuration (actions, permissions, triggers, schedulers, callers).\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Process list 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" }, "result": { "type": "object", "properties": { "results_total": { "type": "integer", "example": 2, "description": "Total number of processes found" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 686, "description": "Process ID" }, "code": { "type": "string", "example": "my_process_code", "description": "Process code" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "tag1", "tag2" ], "description": "Array of tags (can be empty)" }, "class_id": { "type": "integer", "example": 4, "description": "Class ID" }, "label": { "type": "string", "example": "My process", "description": "Process label" }, "active": { "type": "boolean", "example": true, "description": "Whether the process is active" }, "description": { "type": "string", "example": "Description of the process", "description": "Process description" }, "user_description": { "type": "string", "example": "User description of the process", "description": "Process user description" }, "order": { "type": "integer", "example": 1, "description": "Display order" }, "parent_group_id": { "type": "integer", "example": 26, "description": "Process parent group ID" }, "parent_group_label": { "type": "string", "example": "Label of parent group 26", "description": "Process parent group label" }, "applicable_to_users": { "oneOf": [ { "type": "array", "items": { "type": "string" }, "example": [ "all" ] }, { "type": "object", "additionalProperties": { "type": "string" }, "example": { "1555": "Admin test", "1645": "Product Manager" } } ], "description": "Permissions to apply the process to users. Can be 'all', 'admin', or a map of user IDs to labels" }, "applicable_to_asset_types": { "oneOf": [ { "type": "array", "items": { "type": "string" }, "example": [ "all" ] }, { "type": "object", "additionalProperties": { "type": "string" }, "example": { "195": "Article" } } ], "description": "Permissions to apply the process to asset types. Can be 'all' or a map of type IDs to labels" }, "applicable_to_asset_status": { "oneOf": [ { "type": "array", "items": { "type": "string" }, "example": [ "all" ] }, { "type": "object", "additionalProperties": { "type": "string" }, "example": { "1111": "Proposed" } } ], "description": "Permissions to apply the process to asset status. Can be 'all' or a map of status IDs to labels" }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "MY_VARIABLE": "test" }, "description": "Process variables" }, "trigger_type": { "type": "string", "enum": [ "manual", "workflow" ], "example": "manual", "description": "How the process can be triggered: \"manual\" (by user action) or \"workflow\" (automatically on workflow step change)" }, "availability": { "type": "object", "properties": { "in_actions_panel": { "type": "boolean", "example": true, "description": "Available in the global \"Actions\" interface listing all manual processes" }, "on_asset": { "type": "boolean", "example": false, "description": "Available from an asset detail view (executable directly on a fiche)" } }, "description": "Where the process is available in the UI (only relevant for manual processes)" }, "is_scheduled": { "type": "boolean", "example": false, "description": "Whether this process is scheduled (added to a scheduler for automated execution at specific times)" }, "image": { "type": "string", "example": "/design/default/processus/processus.png", "description": "Image path" }, "image_http": { "type": "string", "example": "https://my-afineo.com/design/default/processus/processus.png", "description": "Image URL" }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 54, "description": "Process action ID" }, "process_linked_id": { "type": "integer", "example": 687, "description": "Process linked ID" }, "label": { "type": "string", "example": "Export", "description": "Action label" }, "label_custom": { "type": "string", "example": "Export custom", "description": "Action label custom" }, "form": { "type": "string", "example": "export_configuration", "description": "Action form" }, "type": { "type": "string", "example": "action", "description": "Action type functional : action or process" }, "type_action": { "type": "string", "example": "action", "description": "Action type technical : Export a configuration, Import, etc." }, "order": { "type": "integer", "example": 1, "description": "Display order" }, "parameters": { "oneOf": [ { "type": "array", "items": { "type": "object" } }, { "type": "object" } ], "example": { "label_action": "", "description_action": "", "mapping_id": "1173" }, "description": "Action parameters" }, "mapping_id": { "oneOf": [ { "type": "string", "example": "1234" }, { "type": "integer", "example": 1234 } ], "description": "Mapping ID : empty string if no value" }, "image": { "type": "string", "nullable": true, "example": "/UPLOADS/processus/actions/image.png", "description": "Image path" }, "image_http": { "type": "string", "nullable": true, "example": "https://my-afineo.com/gallery/global/UPLOADS/processus/actions/image.png", "description": "Image URL" } }, "required": [ "id", "process_linked_id", "label", "label_custom", "form", "type", "type_action", "order", "parameters", "mapping_id" ] }, "description": "List of actions for the process" }, "schedulers": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "15": "Scheduler label" }, "description": "Map of scheduler IDs to labels" }, "used_by": { "type": "array", "items": { "type": "object", "properties": { "process_id": { "type": "integer", "example": 45, "description": "ID of the calling process" }, "label": { "type": "string", "example": "Import Global", "description": "Label of the calling process" }, "class_id": { "type": "integer", "example": 4, "description": "Class ID of the calling process" }, "call_type": { "type": "string", "enum": [ "sub_process", "others_processus_action" ], "example": "sub_process", "description": "How this process is called: \"sub_process\" (direct sub-process via regle_lie) or \"others_processus_action\" (cross-library call)" } }, "required": [ "process_id", "label", "class_id", "call_type" ] }, "description": "List of processes that call this process (reverse lookup). Empty array if no callers found." } }, "required": [ "id", "code", "tags", "class_id", "label", "active", "description", "user_description", "order", "parent_group_id", "parent_group_label", "applicable_to_users", "applicable_to_asset_types", "applicable_to_asset_status", "variables", "trigger_type", "availability", "is_scheduled", "image", "image_http", "actions", "schedulers", "used_by" ] }, "description": "Array of processes" } }, "required": [ "results_total", "items" ], "description": "Process list with total count" } }, "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", "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 } }, "required": [ "class_id" ] } } } } } }, "/api/v3/processes/list/": { "post": { "tags": [ "processes" ], "summary": "List processes (simplified)", "description": "## Purpose\n\nReturns simplified process list for a library (id, code, label, tags, trigger type, availability, scheduling status).\n\n## What is a Process?\n\nA process is an automated workflow that executes one or more actions sequentially (exports, imports, status changes, bulk operations, etc.). Processes are configured per library and can be triggered manually by a user or automatically via workflow step changes.\n\n## When to Use\n\n- Use `list` to discover available processes and their IDs for a library\n- Use POST /api/v3/processes/get with a process ID to get complete configuration (actions, variables, permissions)\n- Use POST /api/v3/processes/execute with a process ID and class_id to run a process\n\n## Key Fields\n\n- `trigger_type`: \"manual\" (user-triggered from UI) or \"workflow\" (auto-triggered on workflow step change)\n- `is_scheduled`: true if the process is attached to a scheduler for timed execution\n- `availability`: where the process appears in the UI (actions panel and/or asset detail view)\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Process list 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" }, "result": { "type": "object", "properties": { "results_total": { "type": "integer", "example": 2, "description": "Total number of processes found" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 686, "description": "Process ID" }, "code": { "type": "string", "example": "my_process_code", "description": "Process code" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "tag1", "tag2" ], "description": "Array of tags (can be empty)" }, "class_id": { "type": "integer", "example": 4, "description": "Class ID" }, "label": { "type": "string", "example": "My process", "description": "Process label" }, "active": { "type": "boolean", "nullable": true, "example": true, "description": "Whether the process is active" }, "description": { "type": "string", "example": "Description of the process", "description": "Process description" }, "user_description": { "type": "string", "example": "User description of the process", "description": "Process user description" }, "parent_group_id": { "type": "integer", "example": 26, "description": "Process parent group ID" }, "parent_group_label": { "type": "string", "example": "Label of parent group 26", "description": "Process parent group label" }, "trigger_type": { "type": "string", "enum": [ "manual", "workflow" ], "example": "workflow", "description": "How the process can be triggered: \"manual\" (by user action) or \"workflow\" (automatically on workflow step change)" }, "availability": { "type": "object", "properties": { "in_actions_panel": { "type": "boolean", "example": false, "description": "Available in the global \"Actions\" interface listing all manual processes" }, "on_asset": { "type": "boolean", "example": false, "description": "Available from an asset detail view (executable directly on a fiche)" } }, "description": "Where the process is available in the UI (only relevant for manual processes)" }, "is_scheduled": { "type": "boolean", "example": true, "description": "Whether this process is scheduled (added to a scheduler for automated execution at specific times)" } }, "required": [ "id", "code", "tags", "class_id", "label", "description", "user_description", "parent_group_id", "parent_group_label", "trigger_type", "availability", "is_scheduled" ] }, "description": "Array of processes" } }, "required": [ "results_total", "items" ], "description": "Process list with total count" } }, "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", "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 } }, "required": [ "class_id" ] } } } } } }, "/api/v3/processes/schedulers/": { "post": { "tags": [ "processes" ], "summary": "List scheduled processes", "description": "## Purpose\n\nReturns schedulers with next execution dates and recurrence configuration for a library.\n\n## What is a Scheduler?\n\nA scheduler is a timed automation that executes one or more processes at configured intervals. Schedulers can run at fixed times (e.g., daily at 10:00) or at intervals within a time range (e.g., every hour from 06:00 to 20:00). They can also monitor watch folders for file changes.\n\n## When to Use\n\n- Use to discover scheduled automations for a library\n- Use to check next execution dates, recurrence patterns, and active/disabled status\n- Each scheduler contains a `processes` array listing which processes it will execute\n- Use POST /api/v3/processes/execute with a process ID from the scheduler to manually trigger it\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Scheduler list 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" }, "result": { "type": "object", "properties": { "results_total": { "type": "integer", "example": 1, "description": "Total number of schedulers found" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 15, "description": "Scheduler ID" }, "label": { "type": "string", "example": "My Scheduler", "description": "Scheduler label" }, "class_id": { "type": "integer", "example": 4, "description": "Class ID" }, "active": { "type": "boolean", "example": true, "description": "Whether the scheduler is active" }, "description": { "type": "string", "nullable": true, "example": "Description of the scheduler", "description": "Scheduler description" }, "next_date": { "type": "string", "nullable": true, "example": "2025-11-06T13:00:00+01:00", "description": "Next execution date (ISO 8601 format)" }, "parameters": { "type": "object", "properties": { "schedule": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "specific_date", "recurrence" ], "example": "recurrence", "description": "Schedule type : specific_date for one-time execution, recurrence for recurring execution" }, "date": { "type": "string", "nullable": true, "example": "2025-11-01", "description": "Specific date (only for type=specific_date), format YYYY-MM-DD" }, "time": { "type": "string", "nullable": true, "example": "10:00", "description": "Specific time (only for type=specific_date), format HH:MM" }, "days_summary": { "type": "string", "example": "Weekdays (Monday to Friday)", "description": "Human-readable summary of active days (only for type=recurrence)" }, "active_days": { "type": "array", "items": { "type": "string", "enum": [ "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday" ] }, "example": [ "Monday", "Tuesday", "Wednesday", "Thursday", "Friday" ], "description": "List of active days (only for type=recurrence)" }, "frequency": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "fixed_time", "interval_between_time_range" ], "example": "interval_between_time_range", "description": "Frequency mode: fixed_time for execution at specific time, interval_between_time_range for recurring execution within a time range" }, "time": { "type": "string", "nullable": true, "example": "10:00", "description": "Fixed execution time (only for mode=fixed_time), format HH:MM" }, "interval": { "type": "integer", "nullable": true, "example": 1, "description": "Interval value (only for mode=interval_between_time_range)" }, "unit": { "type": "string", "nullable": true, "enum": [ "hours", "minutes" ], "example": "hours", "description": "Interval unit (only for mode=interval_between_time_range)" }, "from_time": { "type": "string", "nullable": true, "example": "06:00", "description": "Start time of the time range (only for mode=interval_between_time_range), format HH:MM" }, "to_time": { "type": "string", "nullable": true, "example": "20:00", "description": "End time of the time range (only for mode=interval_between_time_range), format HH:MM" } }, "description": "Frequency configuration (only for type=recurrence)" }, "cron_expression": { "type": "string", "example": "0 6-20/1 * * 1,2,3,4,5", "description": "Standard cron expression (minute hour day month weekday)" }, "description": { "type": "string", "example": "Weekdays (Monday to Friday), every 1 hour between 06:00 and 20:00", "description": "Human-readable description of the complete schedule" } }, "required": [ "type", "cron_expression" ], "description": "Schedule configuration" }, "run_as_user": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 1687, "description": "User ID that will run the scheduler" }, "label": { "type": "string", "example": "John Doe", "description": "User label" } }, "description": "User that will execute the scheduler (null if default user)" }, "alert_users": { "type": "array", "nullable": true, "items": { "type": "string" }, "example": [ "user@company.com", "user2@company.com" ], "description": "List of email addresses to alert (null if no alerts configured)" }, "watch_folder": { "type": "object", "nullable": true, "properties": { "path": { "type": "string", "example": "/ftp/Datas/afineo/produits/*.csv", "description": "Path to monitor for file changes" } }, "description": "Folder monitoring configuration (null if not enabled)" } }, "required": [ "schedule", "run_as_user", "alert_users", "watch_folder" ], "description": "Scheduler parameters with schedule configuration" }, "disabled_by_error": { "type": "boolean", "example": false, "description": "Whether the scheduler is disabled by error" }, "processes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 686, "description": "Process ID" }, "code": { "type": "string", "example": "my_process_code", "description": "Process code" }, "label": { "type": "string", "example": "My process", "description": "Process label" }, "node_id": { "type": "integer", "example": 123, "description": "Node ID" }, "parameters": { "type": "object", "example": { "variable1": "value1" }, "description": "Process parameters (overload label and description)" }, "image": { "type": "string", "example": "/design/default/processus/processus.png", "description": "Image path" } }, "required": [ "id", "code", "label", "node_id", "parameters", "image" ] }, "description": "List of processes associated with this scheduler" } }, "required": [ "id", "label", "class_id", "active", "description", "next_date", "parameters", "disabled_by_error", "processes" ] }, "description": "Array of schedulers" } }, "required": [ "results_total", "items" ], "description": "Scheduler list with total count" } }, "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", "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 } }, "required": [ "class_id" ] } } } } } }, "/api/v3/processes/connections/": { "post": { "tags": [ "processes" ], "summary": "List external connections", "description": "## Purpose\n\nReturns configured external connections (integrations) available for use in process actions.\n\n## What is a Connection?\n\nA connection is a configured link to an external system (FTP server, SFTP, HTTP API, database, ERP, etc.). Connections are created by administrators and referenced by process actions that need to interact with external systems (e.g., export files to FTP, import data from an API, sync with an ERP).\n\n## When to Use\n\n- Use to discover available external connections and their configuration\n- Connection IDs are referenced in process action parameters (visible via POST /api/v3/processes/get)\n- No parameters required - returns all configured connections across all libraries\n\n## Connection Types\n\nCommon types: `ftp`, `sftp`, `http`, `database`, `erp`. The `configuration` object structure varies by type (host, port, credentials, path, etc.).\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Connection list 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" }, "result": { "type": "object", "properties": { "results_total": { "type": "integer", "example": 2, "description": "Total number of connections found" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1, "description": "Connection ID" }, "label": { "type": "string", "example": "My FTP Connection", "description": "Connection label" }, "type": { "type": "string", "example": "ftp", "description": "Connection type (ftp, sftp, http, etc.)" }, "configuration": { "type": "object", "additionalProperties": true, "example": { "host": "ftp.example.com", "port": "21", "username": "user", "password": "******", "path": "/uploads" }, "description": "Connection configuration (structure depends on connection type)" } }, "required": [ "id", "label", "type", "configuration" ] }, "description": "Array of connections" } }, "required": [ "results_total", "items" ], "description": "Connection list with total count" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = error)" }, "status_message": { "type": "string", "example": "Access denied", "description": "Error message" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array on error" } }, "required": [ "status_code", "status_message", "result" ] } ] } } } } } } }, "/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": "", "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/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" ] } } } } } }, "/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" } }, "required": [ "class_id", "workspace_node_id", "label", "project_type" ] } } } } } }, "/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": "", "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/publishing/list/": { "post": { "tags": [ "publishing" ], "summary": "List publication projects", "description": "## Purpose\n\nReturns publication projects grouped by workspace.\n\n## When to Use\n\n- Use this endpoint first to discover available publication projects and their node_id values\n- The returned node_id is used as project_node_id in all other publishing endpoints\n- The returned workspace_id values can be used as workspace_node_id when creating new projects with POST /api/v3/publishing/create\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Publications 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": "object", "properties": { "results_total": { "type": "integer", "example": 5, "description": "Total number of publications" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 213855, "description": "Publication node ID" }, "node_id": { "type": "integer", "example": 213855, "description": "Publication node ID" }, "label": { "type": "string", "example": "Christmas Catalog 2025", "description": "Publication label" }, "workspace_id": { "type": "integer", "example": 1982, "description": "Parent workspace node ID" }, "workspace_label": { "type": "string", "example": "Catalogs 2025", "description": "Parent workspace label" }, "description": { "type": "string", "nullable": true, "example": null, "description": "Publication description" }, "active": { "type": "boolean", "example": true, "description": "Whether the publication is active" }, "project_type": { "type": "string", "example": "publication", "description": "Project type (always \"publication\" or \"catalog_with_pagination\")" }, "project_type_description": { "type": "string", "example": "Publication - Brief", "description": "Human-readable project type" }, "path": { "type": "string", "example": "0/1978/1982/213855", "description": "Publication path in hierarchy" }, "class_id": { "type": "integer", "example": 4, "description": "Associated library ID" }, "start_date": { "type": "string", "nullable": true, "example": "2025-01-01T00:00:00+01:00", "description": "Publication start date" }, "end_date": { "type": "string", "nullable": true, "example": "2025-12-31T23:59:59+01:00", "description": "Publication end date" } }, "required": [ "id", "node_id", "label", "workspace_id", "workspace_label", "active", "project_type", "project_type_description", "path", "class_id" ] }, "description": "List of publications" } }, "required": [ "results_total", "items" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = error)" }, "status_message": { "type": "string", "example": "No publications found", "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 publications. By default, inactive publications are excluded.", "example": false } }, "required": [ "class_id" ] } } } } } }, "/api/v3/publishing/add-themes-to-pages/": { "post": { "tags": [ "publishing" ], "summary": "Associate themes to pages", "description": "## Purpose\n\nAssigns thematic categories to publication pages. Use for organizing print catalog content by themes (seasonal, product families, promotional sections).\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Publication themes addition 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": "OK - but 4 unauthorized pages (2, 3)", "description": "Status message" }, "result": { "type": "object", "properties": { "nb_pages_modified": { "type": "integer", "example": 1, "description": "Number of pages that were modified" }, "themes_not_exist": { "type": "array", "nullable": true, "items": { "type": "string" }, "example": [ "Music", "Board games" ], "description": "List of themes that do not exist (optional)" }, "pages_not_exist": { "type": "array", "nullable": true, "items": { "type": "integer" }, "example": [ 2, 3 ], "description": "List of page numbers that do not exist (optional)" }, "pages_unauthorized": { "type": "array", "nullable": true, "items": { "type": "integer" }, "example": [ 2, 3 ], "description": "List of page numbers that are not allowed (optional)" } }, "required": [ "nb_pages_modified" ], "description": "Theme addition result with statistics" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = error, 0 = validation failed)" }, "status_message": { "type": "string", "example": "Project not found or invalid parameters", "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 }, "project_node_id": { "type": "integer", "description": "Publication project node ID. Use POST /api/v3/publishing/list with class_id to get available publication projects.", "example": 556 }, "pages": { "type": "array", "description": "List of pages with theme names. A page can contain multiple themes. Format : array(array(\"page_num\" => 1, \"themes\" => array(theme_name_1, theme_name_2)), ...) (Array of objects - see example for structure)", "example": [ { "page_num": 4, "themes": [ "Music" ] }, { "page_num": 6, "themes": [ "Music", "Board games" ] } ], "items": { "type": "object", "properties": { "page_num": { "type": "integer", "description": "Page number (1-based index). First page is 1" }, "themes": { "type": "array", "description": "List of theme names. Themes are configured at publication level", "items": { "type": "string" } } }, "required": [ "page_num", "themes" ], "title": "Item" } } }, "required": [ "class_id", "project_node_id", "pages" ] } } } } } }, "/api/v3/publishing/add-theme-to-page/": { "post": { "tags": [ "publishing" ], "summary": "Associate a single theme to a single page", "description": "## Purpose\n\nAssigns a single theme to a specific publication page. Simplified alternative to add-themes-to-pages for single operations.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Single theme to page association 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": "Theme associated successfully", "description": "Status message" }, "result": { "type": "object", "properties": { "page_num": { "type": "integer", "example": 4, "description": "Page number where the theme was added" }, "theme": { "type": "string", "example": "Music", "description": "Theme name that was associated" } }, "required": [ "page_num", "theme" ], "description": "Theme association result" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = validation error, 3 = system error)" }, "status_message": { "type": "string", "enum": [ "Page does not exist", "Theme does not exist", "Theme is already associated to this page", "Not authorized to modify this page" ], "example": "Page does not exist", "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 }, "project_node_id": { "type": "integer", "description": "Publication project node ID. Use POST /api/v3/publishing/list with class_id to get available publication projects.", "example": 556 }, "page_num": { "type": "integer", "description": "Page number (1-based). Use POST /api/v3/publishing/pages to list available pages.", "example": 4 }, "theme": { "type": "string", "description": "Theme name to associate. Themes are configured at publication level.", "example": "Music" } }, "required": [ "class_id", "project_node_id", "page_num", "theme" ] } } } } } }, "/api/v3/publishing/add-block-to-page/": { "post": { "tags": [ "publishing" ], "summary": "Add a single content block to a page", "description": "## Purpose\n\nAdds a single content block to a specific publication page. Simplified alternative to add-blocks-to-pages for single block operations.\n\n## Important\n\n`product_block` type creates a block with a template and optional form data, but does NOT assign a product. To assign a product to a block, use POST /api/v3/publishing/place-product-in-page/.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Single block addition 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": "Block created successfully", "description": "Status message" }, "result": { "type": "object", "properties": { "block_id": { "type": "integer", "example": 12345, "description": "ID of the created block" }, "page_num": { "type": "integer", "example": 1, "description": "Page number where the block was added" } }, "required": [ "block_id", "page_num" ], "description": "Created block information" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = validation error, 3 = system error)" }, "status_message": { "type": "string", "enum": [ "Page does not exist", "Block already exists at this position", "Not authorized to modify this page", "Block could not be created" ], "example": "Page does not exist", "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 }, "project_node_id": { "type": "integer", "description": "Publication project node ID. Use POST /api/v3/publishing/list with class_id to get available publication projects.", "example": 556 }, "page_num": { "type": "integer", "description": "Page number (1-based). Use POST /api/v3/publishing/pages to list available pages.", "example": 1 }, "block": { "type": "object", "description": "Block information object with type, position, dimensions. product_block creates a block with template/form but no product — use place-product-in-page to assign a product afterwards.", "example": { "type": "product_block", "x_position": 10, "y_position": 20, "width": 60, "height": 40, "asset_template_id": 22, "rank": 3, "form_datas": { "123": "Cuisine", "456": "Promo", "789": "P1" } }, "properties": { "type": { "type": "string", "description": "Block type. product_block creates a block with a template and optional form data (no product assignment — use place-product-in-page for that). Other types: empty_block, text_block, image_block, or notepad types.", "enum": [ "product_block", "empty_block", "text_block", "image_block", "image_note", "square_note", "text_note", "attention_pin_note", "question_pin_note", "information_pin_note", "simple_note" ] }, "x_position": { "type": "integer", "description": "Block X position in mm from the left edge of the page" }, "y_position": { "type": "integer", "description": "Block Y position in mm from the top edge of the page" }, "width": { "type": "integer", "description": "Block width in mm. Must be a positive value" }, "height": { "type": "integer", "description": "Block height in mm. Must be a positive value" }, "rank": { "type": "integer", "description": "Block z-index position for layering. Higher values display on top of lower values. Default: 0." }, "html_content": { "type": "string", "description": "HTML content (required for text_block and notepad types) **⚠️ Required when:** `type` = `text_block` | `image_note` | `square_note` | `text_note` | `attention_pin_note` | `question_pin_note` | `information_pin_note` | `simple_note`", "x-conditional-required": { "type": [ "text_block", "image_note", "square_note", "text_note", "attention_pin_note", "question_pin_note", "information_pin_note", "simple_note" ] } }, "asset_template_id": { "type": "integer", "description": "Product template ID for rendering (applicable to product_block type). If omitted, uses the publication default, then the library default. There is no dedicated API endpoint to list templates; inspect existing blocks via POST /api/v3/publishing/page-details (profil_id and profil_label fields)." }, "section_id": { "type": "integer", "description": "Section ID for text categorization (applicable to text_block type). Sections are configured at library administration level. There is no API endpoint to list sections; contact your administrator." }, "form_datas": { "type": "object", "description": "Form data as {attribute_id: \"value\"} pairs (applicable to product_block type). All values must be strings. Use POST /api/v3/attributes/list with class_id to get available attribute IDs." } }, "required": [ "type", "x_position", "y_position", "width", "height" ] } }, "required": [ "class_id", "project_node_id", "page_num", "block" ] } } } } } }, "/api/v3/publishing/add-blocks-to-pages/": { "post": { "tags": [ "publishing" ], "summary": "Add content blocks to pages", "description": "## Purpose\n\nDefines page layout by adding content blocks to publication pages. Configure block positioning and content for print catalog production.\n\n## Important\n\n`product_block` type creates a block with a template and optional form data, but does NOT assign a product. To assign a product to a block, use POST /api/v3/publishing/place-product-in-page/ or POST /api/v3/publishing/place-products-in-pages/.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Publication blocks addition 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": "OK - but 2 existing blocks", "description": "Status message (empty string for success)" }, "result": { "type": "object", "properties": { "nb_pages_modified": { "type": "integer", "example": 1, "description": "Number of pages that were modified" }, "nb_blocks_created": { "type": "integer", "example": 3, "description": "Number of new blocks created" }, "nb_blocks_updated": { "type": "integer", "example": 1, "description": "Number of existing blocks updated via attribute_key UPSERT" }, "created_blocks": { "type": "array", "nullable": true, "items": { "type": "integer" }, "example": [ 12345, 12346 ], "description": "List of created block IDs (only present if blocks were created). Use these IDs with place-product-in-page block_id parameter." }, "updated_blocks": { "type": "array", "nullable": true, "items": { "type": "integer" }, "example": [ 456 ], "description": "List of updated block IDs (only present if blocks were updated via UPSERT)" }, "pages_not_exist": { "type": "array", "nullable": true, "items": { "type": "integer" }, "example": [ 2, 3 ], "description": "List of page numbers that do not exist (optional)" }, "existing_blocks": { "type": "array", "nullable": true, "items": { "type": "object" }, "example": [], "description": "List of blocks that already exist at the same position (optional)" }, "pages_unauthorized": { "type": "array", "nullable": true, "items": { "type": "integer" }, "example": [ 4 ], "description": "List of page numbers where user is not authorized (optional)" } }, "required": [ "nb_pages_modified", "nb_blocks_created", "nb_blocks_updated" ], "description": "Block addition result with statistics" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = error, 0 = validation failed)" }, "status_message": { "type": "string", "example": "Invalid block type or missing required parameters", "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 }, "project_node_id": { "type": "integer", "description": "Publication project node ID. Use POST /api/v3/publishing/list with class_id to get available publication projects.", "example": 556 }, "pages": { "type": "array", "description": "List of pages with blocks. A page can contain multiple blocks. Each block requires: \"type\" (use enum values: empty_block, text_block, image_block, or notepad types), \"x_position\", \"y_position\", \"width\", \"height\". Additional fields by type: text_block supports \"html_content\" and \"section_id\"; notepad types support \"html_content\". For product blocks, use POST /api/v3/publishing/place-product-in-page/ or place-products-in-pages/ instead. (Array of objects - see example for structure)", "example": [ { "page_num": 1, "blocks": [ { "type": "empty_block", "x_position": 10, "y_position": 20, "width": 60, "height": 40, "rank": 2 }, { "type": "text_block", "x_position": 16, "y_position": 178, "width": 60, "height": 40, "html_content": "Advertising block", "section_id": 10 }, { "type": "product_block", "x_position": 10, "y_position": 80, "width": 60, "height": 40, "asset_template_id": 22, "rank": 3, "form_datas": { "123": "Cuisine", "456": "Promo", "789": "P1" } } ] } ], "items": { "type": "object", "properties": { "page_num": { "type": "integer", "description": "Page number (1-based index). First page is 1" }, "blocks": { "type": "array", "description": "List of blocks on the page with their properties and positions. (Array of objects - see example for structure)", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Block type. product_block creates a block with a template and optional form data (no product assignment — use place-product-in-page for that). Other types: empty_block, text_block, image_block, or notepad types.", "enum": [ "product_block", "empty_block", "text_block", "image_block", "image_note", "square_note", "text_note", "attention_pin_note", "question_pin_note", "information_pin_note", "simple_note" ] }, "x_position": { "type": "integer", "description": "Block X position in mm from the left edge of the page" }, "y_position": { "type": "integer", "description": "Block Y position in mm from the top edge of the page" }, "width": { "type": "integer", "description": "Block width in mm. Must be a positive value" }, "height": { "type": "integer", "description": "Block height in mm. Must be a positive value" }, "rank": { "type": "integer", "description": "Block z-index position for layering. Higher values display on top of lower values. Default: 0." }, "html_content": { "type": "string", "description": "HTML content (required for text_block and notepad types) **⚠️ Required when:** `type` = `text_block` | `image_note` | `square_note` | `text_note` | `attention_pin_note` | `question_pin_note` | `information_pin_note` | `simple_note`", "x-conditional-required": { "type": [ "text_block", "image_note", "square_note", "text_note", "attention_pin_note", "question_pin_note", "information_pin_note", "simple_note" ] } }, "asset_template_id": { "type": "integer", "description": "Product template ID for rendering (applicable to product_block type). If omitted, uses the publication default, then the library default. There is no dedicated API endpoint to list templates; inspect existing blocks via POST /api/v3/publishing/page-details (profil_id and profil_label fields)." }, "section_id": { "type": "integer", "description": "Section ID for text categorization (applicable to text_block type). Sections are configured at library administration level. There is no API endpoint to list sections; contact your administrator." }, "attribute_key": { "type": "integer", "description": "Attribute ID used as lookup key for UPSERT mode. If a block already exists in the project with this attribute value (from form_datas), it will be updated instead of creating a new one. The attribute must be indexed. Use POST /api/v3/attributes/list with class_id to get attribute IDs." }, "form_datas": { "type": "object", "description": "Form data as {attribute_id: \"value\"} pairs. All values must be strings, even for numeric attributes. Use POST /api/v3/attributes/list with class_id to get available attribute IDs." } }, "required": [ "type", "x_position", "y_position", "width", "height" ], "title": "Item" } } }, "required": [ "page_num", "blocks" ], "title": "Item" } } }, "required": [ "class_id", "project_node_id", "pages" ] } } } } } }, "/api/v3/publishing/get-block-form-by-attribute/": { "post": { "tags": [ "publishing" ], "summary": "Get forms in a project by attribute value", "description": "## Purpose\n\nRetrieves all forms in a publication project matching a specific attribute value. Useful for finding forms based on their content.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Forms search 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": "object", "properties": { "results_total": { "type": "integer", "example": 2, "description": "Total number of forms found" }, "items": { "type": "array", "items": { "type": "object", "properties": { "form_id": { "type": "integer", "example": 12345, "description": "Form asset ID" }, "block": { "type": "object", "properties": { "id": { "type": "integer", "example": 456, "description": "Block ID" }, "type": { "type": "string", "example": "product_block", "description": "Block type: product_block, empty_block, text_block, image_block, or notepad types (image_note, etc.)" }, "x_position": { "type": "integer", "example": 10, "description": "Block X position in mm from the left edge of the page" }, "y_position": { "type": "integer", "example": 20, "description": "Block Y position in mm from the top edge of the page" }, "width": { "type": "integer", "example": 60, "description": "Block width in mm. Must be a positive value" }, "height": { "type": "integer", "example": 40, "description": "Block height in mm. Must be a positive value" }, "node_id": { "type": "integer", "example": 789, "description": "Product node ID" }, "asset_template_id": { "type": "integer", "example": 22, "description": "Asset template ID" } }, "description": "Block information" }, "page": { "type": "object", "properties": { "page_num": { "type": "integer", "example": 1, "description": "Page number" }, "node_id": { "type": "integer", "example": 555, "description": "Page node ID" } }, "description": "Page information" } }, "required": [ "form_id", "block", "page" ] }, "description": "List of forms found" } }, "required": [ "results_total", "items" ], "description": "Search results" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = validation error, 3 = system error)" }, "status_message": { "type": "string", "enum": [ "Project not found", "No form type configured", "Attribute not found", "Attribute is not indexed", "No forms found" ], "example": "No forms found", "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 }, "project_node_id": { "type": "integer", "description": "Publication project node ID. Use POST /api/v3/publishing/list with class_id to get available publication projects.", "example": 556 }, "attribute_id": { "type": "integer", "description": "Attribute ID to search on (must be indexed). Use POST /api/v3/attributes/list with class_id to get attributes.", "example": 730 }, "value": { "type": "string", "description": "Value to search for in the specified attribute.", "example": "REF-12345" } }, "required": [ "class_id", "project_node_id", "attribute_id", "value" ] } } } } } }, "/api/v3/publishing/update-block-to-page/": { "post": { "tags": [ "publishing" ], "summary": "Update a content block on a page", "description": "## Purpose\n\nUpdates an existing content block on a publication page. Modify position, dimensions, content, or associated data. Only provided properties are updated.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Block update 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": "Block updated successfully", "description": "Status message" }, "result": { "type": "object", "properties": { "block_id": { "type": "integer", "example": 12345, "description": "ID of the updated block" }, "page_num": { "type": "integer", "example": 1, "description": "Page number where the block was updated" }, "messages": { "type": "array", "items": { "type": "string" }, "example": [ "Updated block", "Updated form data" ], "description": "List of operations performed" } }, "required": [ "block_id", "page_num" ], "description": "Updated block information" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = validation error, 3 = system error)" }, "status_message": { "type": "string", "enum": [ "Page does not exist", "Block not found", "Not authorized to update the block", "Project not found", "Block could not be updated" ], "example": "Block not found", "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 }, "project_node_id": { "type": "integer", "description": "Publication project node ID. Use POST /api/v3/publishing/list with class_id to get available publication projects.", "example": 556 }, "page_num": { "type": "integer", "description": "Page number (1-based). Use POST /api/v3/publishing/pages to list available pages.", "example": 1 }, "block_id": { "type": "integer", "description": "Block ID to update. Use POST /api/v3/publishing/page-details with project_node_id and page_num to get block IDs.", "example": 12345 }, "block": { "type": "object", "description": "Block information to update. All properties are optional - only provided properties will be updated.", "example": { "x_position": 15, "y_position": 25, "width": 70, "height": 50 }, "properties": { "type": { "type": "string", "description": "Block type: product_block, empty_block, text_block, image_block, or notepad types (image_note, etc.)", "enum": [ "product_block", "empty_block", "text_block", "image_block", "image_note", "square_note", "text_note", "attention_pin_note", "question_pin_note", "information_pin_note", "simple_note" ] }, "x_position": { "type": "integer", "description": "Block X position in mm from the left edge of the page" }, "y_position": { "type": "integer", "description": "Block Y position in mm from the top edge of the page" }, "width": { "type": "integer", "description": "Block width in mm. Must be a positive value" }, "height": { "type": "integer", "description": "Block height in mm. Must be a positive value" }, "node_id": { "type": "integer", "description": "Product node ID for product_block. Use POST /api/v3/get-asset/by-search/node to find products" }, "asset_template_id": { "type": "integer", "description": "Product template ID for rendering. If omitted, uses the publication default, then the library default. There is no dedicated API endpoint to list templates; inspect existing blocks via POST /api/v3/publishing/page-details (profil_id and profil_label fields)." }, "rank": { "type": "integer", "description": "Block position for product placement (for product_block and empty_block)" }, "html_content": { "type": "string", "description": "HTML content (for text_block and notepad types)" }, "section_id": { "type": "integer", "description": "Section ID for text categorization (applicable to text_block type). Sections are configured at library administration level. There is no API endpoint to list sections; contact your administrator." }, "form_datas": { "type": "object", "description": "Form data as key-value pairs where key is attribute_id and value is the content (for product_block)" } } } }, "required": [ "class_id", "project_node_id", "page_num", "block_id", "block" ] } } } } } }, "/api/v3/publishing/delete-block-to-page/": { "post": { "tags": [ "publishing" ], "summary": "Remove a content block from a page", "description": "## Purpose\n\nDeletes a content block from a publication page. Also removes any associated form data.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Block deletion 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": "Block deleted successfully", "description": "Status message" }, "result": { "type": "object", "properties": { "block_id": { "type": "integer", "example": 12345, "description": "ID of the deleted block" } }, "required": [ "block_id" ], "description": "Deleted block information" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = validation error, 3 = system error)" }, "status_message": { "type": "string", "enum": [ "Block not found", "No form data in block", "Not authorized to delete the block" ], "example": "Block not found", "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": { "block_id": { "type": "integer", "description": "Block ID to delete. Use POST /api/v3/publishing/page-details with project_node_id and page_num to get block IDs.", "example": 12345 } }, "required": [ "block_id" ] } } } } } }, "/api/v3/publishing/delete-theme-to-page/": { "post": { "tags": [ "publishing" ], "summary": "Remove a theme from a page", "description": "## Purpose\n\nRemoves a theme from a specific publication page. Reverse operation of add-theme-to-page.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Theme removal from page 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": "Theme removed successfully", "description": "Status message" }, "result": { "type": "object", "properties": { "page_num": { "type": "integer", "example": 4, "description": "Page number from which the theme was removed" }, "theme": { "type": "string", "example": "Music", "description": "Theme name that was removed" } }, "required": [ "page_num", "theme" ], "description": "Theme removal result" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = validation error, 3 = system error)" }, "status_message": { "type": "string", "enum": [ "Page does not exist", "Theme does not exist", "Theme is not associated to this page", "Not authorized to modify this page" ], "example": "Page does not exist", "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 }, "project_node_id": { "type": "integer", "description": "Publication project node ID. Use POST /api/v3/publishing/list with class_id to get available publication projects.", "example": 556 }, "page_num": { "type": "integer", "description": "Page number (1-based). Use POST /api/v3/publishing/pages to list available pages.", "example": 4 }, "theme": { "type": "string", "description": "Theme name to remove. Use POST /api/v3/publishing/page-details with project_node_id and page_num to see current page themes.", "example": "Music" } }, "required": [ "class_id", "project_node_id", "page_num", "theme" ] } } } } } }, "/api/v3/publishing/create/": { "post": { "tags": [ "publishing" ], "summary": "Create new project", "description": "## Purpose\n\nCreates a new publication or catalog project within a project group. Configure project type, page dimensions, and initial settings.\n\n## Project Types\n\n- `publication`: Print publication with page layout and blocks\n- `catalog_with_pagination`: Digital catalog with pagination support\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).", "There is an issue with the data sent in the parameter \"themes_configuration\" : each key must be a valid string and not empty.", "There is an issue with the data sent in the parameter \"themes_configuration\" : each value must be a valid string and not empty and must match a hexadecimal code (with or without #).", "Parent workspace does not exist", "Project could not be created", "Publication 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/publishing/list with class_id to find workspace nodes.", "example": 6726 }, "label": { "type": "string", "description": "Label/name for the new publication project.", "example": "Christmas 2025" }, "project_type": { "type": "string", "description": "Project type: \"publication\" (paginated document with layout) or \"catalog_with_pagination\" (catalog with automatic pagination).", "enum": [ "publication", "catalog_with_pagination" ], "example": "publication" }, "template_id": { "type": "integer", "description": "Project template ID (optional). Creates a blank project if omitted. There is currently no API endpoint to list project templates. You can inspect existing projects via POST /api/v3/publishing/list as reference.", "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 for the project. Use POST /api/v3/administration/versions/list to get 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" }, "page_width": { "type": "integer", "description": "Page width in mm for publication layout **⚠️ Required when:** `project_type` = `publication`", "example": 210, "x-conditional-required": { "project_type": [ "publication" ] } }, "page_height": { "type": "integer", "description": "Page height in mm for publication layout **⚠️ Required when:** `project_type` = `publication`", "example": 297, "x-conditional-required": { "project_type": [ "publication" ] } }, "page_margin": { "type": "array", "description": "Page margin information (for publication) (Array of objects - see example for structure)", "example": { "top": 5, "left": 5, "right": 5, "bottom": 5 }, "items": { "type": "object", "properties": { "top": { "type": "integer", "description": "Top page margin in millimeters. Default value: 0" }, "left": { "type": "integer", "description": "Left page margin in millimeters. Default value: 0" }, "right": { "type": "integer", "description": "Right page margin in millimeters. Default value: 0" }, "bottom": { "type": "integer", "description": "Bottom page margin in millimeters. Default value: 0" } }, "title": "Item" } }, "number_of_pages": { "type": "integer", "description": "Number of pages to create (for publication)", "example": 10 }, "easycatalog_export_mapping_id": { "type": "integer", "description": "Export mapping ID for EasyCatalog. Use POST /api/v3/mappings/list with type=\"export\" to get mappings.", "example": 251 }, "page_start_number": { "type": "integer", "description": "Starting page numbering (for publication)", "example": 1 }, "themes_configuration": { "type": "object", "description": "List of theme configurations for publication layout organization. Color values accept hexadecimal codes with or without # prefix (e.g. \"4169e1\" or \"#4169e1\").", "example": { "Music": "4169e1", "Board games": "#228b22" } }, "attribute_list": { "type": "array", "description": "List of attributes to update on the project asset. List of properties to apply : \"attribute_id\", \"value\" (Array of objects - see example for structure)", "example": [ { "attribute_id": 231, "value": "Christmas 2025 Edition" }, { "attribute_id": 658, "value": "1234" } ], "items": { "type": "object", "properties": { "attribute_id": { "type": "integer", "description": "Attribute ID. Use POST /api/v3/attributes/list with class_id to get available attributes." }, "value": { "type": "string", "description": "Value to set. Format depends on attribute type (text, date, list)" } }, "required": [ "attribute_id", "value" ], "title": "Item" } } }, "required": [ "class_id", "workspace_node_id", "label", "project_type" ] } } } } } }, "/api/v3/publishing/update-status/node/": { "post": { "tags": [ "publishing" ], "summary": "Update page status in publication project", "description": "## Purpose\n\nUpdates the access control status (LCA) of a publication page by page number. This endpoint operates in the project/node context (not repository).\n\n## Note on URL\n\nThe `/node/` suffix indicates this operates in a project context (as opposed to repository). This is consistent with other Afineo endpoints that distinguish between `/node/` (project-specific) and `/repository/` (master data).\n\n## When to Use\n\n- Use to change the validation status of a specific page in a publication project\n- The `page_num` refers to the publication page number (1-based), not the internal node ID\n- Use POST /api/v3/publishing/pages with class_id and project_node_id to get available page numbers\n- Use POST /api/v3/permissions/statuses/list to get available status IDs\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Update status by page 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": "Status updated", "description": "Status message" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = error)" }, "status_message": { "type": "string", "enum": [ "Page does not exist", "Asset does not exist or has been deleted", "The status of the asset is already the same as the one you want to set", "You don't have the rights to update the status of this asset" ], "example": "Page does not exist", "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": { "page_num": { "type": "integer", "description": "Page number (1-based). Use POST /api/v3/publishing/pages to list available pages.", "example": 1 }, "class_id": { "type": "integer", "description": "Library ID. Use POST /api/v3/administration/classes/list to get available libraries.", "example": 4 }, "project_node_id": { "type": "integer", "description": "Publication project node ID. Use POST /api/v3/publishing/list with class_id to get available publication projects.", "example": 556 }, "status_id": { "type": "integer", "description": "Status ID. Use POST /api/v3/permissions/statuses/list to get available statuses.", "example": 102 } }, "required": [ "page_num", "class_id", "project_node_id", "status_id" ] } } } } } }, "/api/v3/publishing/add-product-to-page/": { "post": { "tags": [ "publishing" ], "summary": "Add a product to a publication page tree", "description": "## Purpose\n\nAdds a product from the repository to a publication page tree. The product becomes a child of the page, making it available for block placement via place-product-in-page.\n\n## When to use\n\nUse this endpoint to populate a page with products before placing them in blocks. This is the first step in the product placement workflow.\n\n## When NOT to use\n\n- To place a product in a block (with coordinates or block_id) → use POST /api/v3/publishing/place-product-in-page/\n- If the product is already in the page tree → this endpoint will return the existing node_id without duplicating\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Product addition 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": "Product added to page successfully", "description": "Status message" }, "result": { "type": "object", "properties": { "node_id": { "type": "integer", "example": 12345, "description": "Node ID of the product in the page tree. Use this value as node_id in place-product-in-page." }, "page_num": { "type": "integer", "example": 1, "description": "Page number" }, "already_in_page": { "type": "boolean", "example": false, "description": "Whether the product was already present in the page tree (true) or newly added (false)" } }, "required": [ "node_id", "page_num", "already_in_page" ], "description": "Product addition result" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = validation error)" }, "status_message": { "type": "string", "enum": [ "Publication not found", "Page does not exist", "Product asset not found", "Could not add product to page tree" ], "example": "Product asset not found", "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 }, "project_node_id": { "type": "integer", "description": "Publication project node ID. Use POST /api/v3/publishing/list with class_id to get available publication projects.", "example": 556 }, "page_num": { "type": "integer", "description": "Page number (1-based). Use POST /api/v3/publishing/pages to list available pages.", "example": 1 }, "asset_id": { "type": "integer", "description": "Product asset ID from the repository (unique database identifier). Use POST /api/v3/get-asset/by-search/ to find product asset IDs.", "example": 638116 } }, "required": [ "class_id", "project_node_id", "page_num", "asset_id" ] } } } } } }, "/api/v3/publishing/add-products-to-pages/": { "post": { "tags": [ "publishing" ], "summary": "Add products to publication pages (batch)", "description": "## Purpose\n\nBatch endpoint for adding products from the repository to multiple publication pages. Each product becomes a child of its target page.\n\n## When to use\n\nUse this endpoint to populate multiple pages with products in a single call. More efficient than calling add-product-to-page repeatedly.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Batch product addition 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 for full success)" }, "result": { "type": "object", "properties": { "nb_pages_modified": { "type": "integer", "example": 2, "description": "Number of pages that received products" }, "nb_products_added": { "type": "integer", "example": 5, "description": "Number of products added" }, "products": { "type": "array", "items": { "type": "object", "properties": { "node_id": { "type": "integer", "example": 12345, "description": "Node ID of the product in the page tree" }, "page_num": { "type": "integer", "example": 1, "description": "Page number where the product was added" }, "already_in_page": { "type": "boolean", "example": false, "description": "Whether the product was already in the page (true) or newly added (false)" } } }, "description": "List of added products with node IDs" }, "errors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "page_num": { "type": "integer", "description": "Page number where the error occurred" }, "asset_id": { "type": "integer", "description": "Asset ID that caused the error" }, "message": { "type": "string", "description": "Error message" } } }, "description": "List of errors for individual products (optional, present on partial success)" } }, "required": [ "nb_pages_modified", "nb_products_added", "products" ], "description": "Batch addition result" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = validation error)" }, "status_message": { "type": "string", "example": "The parameter \"pages\" must be not empty", "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 }, "project_node_id": { "type": "integer", "description": "Publication project node ID. Use POST /api/v3/publishing/list with class_id to get available publication projects.", "example": 556 }, "pages": { "type": "array", "description": "List of pages with products to add. Each entry requires a page_num (1-based) and an asset_ids array of product asset IDs from the repository. (Array of objects - see example for structure)", "example": [ { "page_num": 1, "asset_ids": [ 638116, 638117, 638118 ] }, { "page_num": 2, "asset_ids": [ 638200, 638201 ] } ], "items": { "type": "object", "properties": { "page_num": { "type": "integer", "description": "Page number (1-based index). First page is 1" }, "asset_ids": { "type": "array", "description": "List of product asset IDs to add to this page. Use POST /api/v3/get-asset/by-search/ to find asset IDs.", "items": { "type": "integer" } } }, "required": [ "page_num", "asset_ids" ], "title": "Item" } } }, "required": [ "class_id", "project_node_id", "pages" ] } } } } } }, "/api/v3/publishing/place-product-in-page/": { "post": { "tags": [ "publishing" ], "summary": "Place a product on a publication page", "description": "## Purpose\n\nIntelligent endpoint for placing a product on a publication page. Handles the full workflow: adding the product from the repository to the page tree if needed, then creating a new product block or assigning the product to an existing block.\n\n## When to use\n\nUse this endpoint when you need to place a product on a publication page. It replaces the former `add-product-block` endpoint with added capabilities:\n- Place a product already present in the page tree (via `node_id`)\n- Place a product from the repository (via `asset_id`) — will be added to the page tree automatically\n- Create a new block OR assign to an existing block (via `block_id`)\n\n## Parameter rules\n\n- Provide either `node_id` OR `asset_id` (mutually exclusive, one is required)\n- If `block_id` is not provided, `x_position`, `y_position`, `width`, `height` are required to create a new block\n- If `block_id` is provided, the product will be assigned to the existing block\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Product placement 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": "Product placed in page successfully", "description": "Status message" }, "result": { "type": "object", "properties": { "node_id": { "type": "integer", "example": 12345, "description": "Node ID of the product in the page tree" }, "block_id": { "type": "integer", "example": 6789, "description": "ID of the block (created or existing)" }, "page_num": { "type": "integer", "example": 1, "description": "Page number" }, "added_from_repository": { "type": "boolean", "example": true, "description": "Whether the product was added from the repository (true) or was already in the page (false)" } }, "required": [ "node_id", "block_id", "page_num", "added_from_repository" ], "description": "Product placement result" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = validation error, 3 = system error)" }, "status_message": { "type": "string", "enum": [ "You must provide either node_id or asset_id (not both)", "Publication not found", "Page does not exist", "Product not found in page", "Product asset not found", "Could not add product to page tree", "Parameters x_position, y_position, width, height are required when block_id is not provided", "Not authorized to modify this page", "Block could not be created" ], "example": "You must provide either node_id or asset_id (not both)", "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 }, "project_node_id": { "type": "integer", "description": "Publication project node ID. Use POST /api/v3/publishing/list with class_id to get available publication projects.", "example": 556 }, "page_num": { "type": "integer", "description": "Page number (1-based). Use POST /api/v3/publishing/pages to list available pages.", "example": 1 }, "node_id": { "type": "integer", "description": "Product node ID already present as a child of the page. Mutually exclusive with asset_id — provide one or the other. Use POST /api/v3/publishing/page-details/ with project_node_id and page_num to list products already in the page (see blocks[].node_id).", "example": 12345 }, "asset_id": { "type": "integer", "description": "Product asset ID from the repository (unique database identifier). If the product is not already in the page tree, it will be added automatically. Mutually exclusive with node_id. Use POST /api/v3/get-asset/by-search/ to find product asset IDs.", "example": 638116 }, "block_id": { "type": "integer", "description": "ID of an existing block (empty_block or product_block) to assign the product to. If omitted, a new block is created using x_position, y_position, width, height parameters. Use POST /api/v3/publishing/page-details/ to list existing blocks and their IDs (see blocks[].id).", "example": 789 }, "asset_template_id": { "type": "integer", "description": "Product template ID for rendering. If omitted, uses the default template configured on the publication project; if none, falls back to the library default template. There is no dedicated API endpoint to list templates; inspect existing blocks via POST /api/v3/publishing/page-details (profil_id and profil_label fields).", "example": 22 }, "x_position": { "type": "integer", "description": "X position in mm from the left edge of the page. Must be a positive value. Required if block_id is not provided.", "example": 10 }, "y_position": { "type": "integer", "description": "Y position in mm from the top edge of the page. Must be a positive value. Required if block_id is not provided.", "example": 20 }, "width": { "type": "integer", "description": "Block width in mm. Must be a positive value. Required if block_id is not provided.", "example": 60 }, "height": { "type": "integer", "description": "Block height in mm. Must be a positive value. Required if block_id is not provided.", "example": 40 }, "rank": { "type": "integer", "description": "Block placement order (z-index). Higher values display on top of lower values. Default: 0.", "example": 3 }, "form_datas": { "type": "object", "description": "Form data as {attribute_id: \"value\"} pairs. All values must be strings, even for numeric attributes. Use POST /api/v3/attributes/list with class_id to get available attribute IDs.", "example": { "123": "Cuisine", "456": "Promo" } } }, "required": [ "class_id", "project_node_id", "page_num" ] } } } } } }, "/api/v3/publishing/place-products-in-pages/": { "post": { "tags": [ "publishing" ], "summary": "Place products on publication pages (batch)", "description": "## Purpose\n\nBatch endpoint for placing multiple products on multiple publication pages. Each product follows the same workflow as place-product-in-page: adding from repository if needed, then creating or assigning blocks.\n\n## When to use\n\nUse this endpoint when you need to place multiple products across one or more pages in a single call. More efficient than calling place-product-in-page repeatedly.\n\n## Parameter rules (per product)\n\n- Provide either `node_id` OR `asset_id` (mutually exclusive, one is required)\n- If `block_id` is not provided, `x_position`, `y_position`, `width`, `height` are required to create a new block\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Batch product placement 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 for full success, details on partial success)" }, "result": { "type": "object", "properties": { "nb_pages_modified": { "type": "integer", "example": 1, "description": "Number of pages that were modified" }, "nb_products_placed": { "type": "integer", "example": 3, "description": "Number of products successfully placed" }, "products": { "type": "array", "items": { "type": "object", "properties": { "node_id": { "type": "integer", "example": 12345, "description": "Node ID of the product in the page tree" }, "block_id": { "type": "integer", "example": 6789, "description": "ID of the block (created or existing)" }, "page_num": { "type": "integer", "example": 1, "description": "Page number where the product was placed" }, "added_from_repository": { "type": "boolean", "example": true, "description": "Whether the product was added from the repository (true) or was already in the page (false)" } } }, "description": "List of placed products with details" }, "errors": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "page_num": { "type": "integer", "description": "Page number where the error occurred" }, "message": { "type": "string", "description": "Error message" } } }, "description": "List of errors encountered during processing (optional, present on partial success)" } }, "required": [ "nb_pages_modified", "nb_products_placed", "products" ], "description": "Batch placement result" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = validation error)" }, "status_message": { "type": "string", "example": "The parameter \"pages\" must be not empty", "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 }, "project_node_id": { "type": "integer", "description": "Publication project node ID. Use POST /api/v3/publishing/list with class_id to get available publication projects.", "example": 556 }, "pages": { "type": "array", "description": "List of pages with products to place. Each page contains a page_num and a list of products. (Array of objects - see example for structure)", "example": [ { "page_num": 1, "products": [ { "asset_id": 638116, "x_position": 10, "y_position": 20, "width": 60, "height": 40, "asset_template_id": 22 }, { "node_id": 12345, "block_id": 789 } ] } ], "items": { "type": "object", "properties": { "page_num": { "type": "integer", "description": "Page number (1-based index). First page is 1" }, "products": { "type": "array", "description": "List of products to place on this page. (Array of objects - see example for structure)", "items": { "type": "object", "properties": { "node_id": { "type": "integer", "description": "Product node ID already present as a child of the page. Mutually exclusive with asset_id — provide one or the other. Use POST /api/v3/publishing/page-details/ to list products in the page (see blocks[].node_id).", "example": 12345 }, "asset_id": { "type": "integer", "description": "Product asset ID from the repository (unique database identifier). If the product is not already in the page tree, it will be added automatically. Mutually exclusive with node_id. Use POST /api/v3/get-asset/by-search/ to find product asset IDs.", "example": 638116 }, "block_id": { "type": "integer", "description": "ID of an existing block (empty_block or product_block) to assign the product to. If omitted, a new block is created using x_position, y_position, width, height parameters. Use POST /api/v3/publishing/page-details/ to list existing blocks and their IDs (see blocks[].id).", "example": 789 }, "asset_template_id": { "type": "integer", "description": "Product template ID for rendering. If omitted, uses the default template configured on the publication project; if none, falls back to the library default template. There is no dedicated API endpoint to list templates; inspect existing blocks via POST /api/v3/publishing/page-details (profil_id and profil_label fields).", "example": 22 }, "x_position": { "type": "integer", "description": "X position in mm from the left edge of the page. Must be a positive value. Required if block_id is not provided." }, "y_position": { "type": "integer", "description": "Y position in mm from the top edge of the page. Must be a positive value. Required if block_id is not provided." }, "width": { "type": "integer", "description": "Block width in mm. Must be a positive value. Required if block_id is not provided." }, "height": { "type": "integer", "description": "Block height in mm. Must be a positive value. Required if block_id is not provided." }, "rank": { "type": "integer", "description": "Block placement order (z-index). Higher values display on top of lower values. Default: 0." }, "form_datas": { "type": "object", "description": "Form data as {attribute_id: \"value\"} pairs. All values must be strings, even for numeric attributes. Use POST /api/v3/attributes/list with class_id to get available attribute IDs." } }, "title": "Item" } } }, "required": [ "page_num", "products" ], "title": "Item" } } }, "required": [ "class_id", "project_node_id", "pages" ] } } } } } }, "/api/v3/publishing/add-empty-block/": { "post": { "tags": [ "publishing" ], "summary": "Add an empty block to a page", "description": "## Purpose\n\nCreates an empty placeholder block on a publication page. Empty blocks reserve space for future product placement.\n\n## When to use\n\nUse this endpoint to create placeholder blocks that will later receive products via place-product-in-page.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Empty block 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": "Block created successfully", "description": "Status message" }, "result": { "type": "object", "properties": { "block_id": { "type": "integer", "example": 12345, "description": "ID of the created block" }, "page_num": { "type": "integer", "example": 1, "description": "Page number where the block was added" } }, "required": [ "block_id", "page_num" ], "description": "Created block information" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = validation error, 3 = system error)" }, "status_message": { "type": "string", "enum": [ "Page does not exist", "Block already exists at this position", "Not authorized to modify this page", "Block could not be created" ], "example": "Page does not exist", "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 }, "project_node_id": { "type": "integer", "description": "Publication project node ID. Use POST /api/v3/publishing/list with class_id to get available publication projects.", "example": 556 }, "page_num": { "type": "integer", "description": "Page number (1-based). Use POST /api/v3/publishing/pages to list available pages.", "example": 1 }, "x_position": { "type": "integer", "description": "X position in mm from the left edge of the page.", "example": 10 }, "y_position": { "type": "integer", "description": "Y position in mm from the top edge of the page.", "example": 20 }, "width": { "type": "integer", "description": "Block width in mm. Must be a positive value.", "example": 80 }, "height": { "type": "integer", "description": "Block height in mm. Must be a positive value.", "example": 100 }, "rank": { "type": "integer", "description": "Block placement order (z-index). Higher values display on top. Default: 0.", "example": 0 } }, "required": [ "class_id", "project_node_id", "page_num", "x_position", "y_position", "width", "height" ] } } } } } }, "/api/v3/publishing/add-text-block/": { "post": { "tags": [ "publishing" ], "summary": "Add a text block to a page", "description": "## Purpose\n\nCreates a text block with HTML content on a publication page. Text blocks display formatted content independently of products.\n\n## When to use\n\nUse this endpoint for adding titles, descriptions, promotional text, or any standalone HTML content to a page.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Text block 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": "Block created successfully", "description": "Status message" }, "result": { "type": "object", "properties": { "block_id": { "type": "integer", "example": 12345, "description": "ID of the created block" }, "page_num": { "type": "integer", "example": 1, "description": "Page number where the block was added" } }, "required": [ "block_id", "page_num" ], "description": "Created block information" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = validation error, 3 = system error)" }, "status_message": { "type": "string", "enum": [ "Page does not exist", "Block already exists at this position", "Not authorized to modify this page", "Block could not be created" ], "example": "Page does not exist", "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 }, "project_node_id": { "type": "integer", "description": "Publication project node ID. Use POST /api/v3/publishing/list with class_id to get available publication projects.", "example": 556 }, "page_num": { "type": "integer", "description": "Page number (1-based). Use POST /api/v3/publishing/pages to list available pages.", "example": 1 }, "x_position": { "type": "integer", "description": "X position in mm from the left edge of the page.", "example": 10 }, "y_position": { "type": "integer", "description": "Y position in mm from the top edge of the page.", "example": 20 }, "width": { "type": "integer", "description": "Block width in mm. Must be a positive value.", "example": 80 }, "height": { "type": "integer", "description": "Block height in mm. Must be a positive value.", "example": 30 }, "html_content": { "type": "string", "description": "HTML content for the text block. Supports basic formatting tags.", "example": "

Section Title

Description text

" }, "section_id": { "type": "integer", "description": "Section ID for text block categorization. Sections are configured at library administration level. There is no API endpoint to list sections; contact your administrator.", "example": 10 } }, "required": [ "class_id", "project_node_id", "page_num", "x_position", "y_position", "width", "height", "html_content" ] } } } } } }, "/api/v3/publishing/add-notepad/": { "post": { "tags": [ "publishing" ], "summary": "Add a notepad to a page", "description": "## Purpose\n\nCreates a notepad element on a publication page. Notepads are annotation elements for collaboration (pins, simple notes).\n\n## Notepad Types\n\n- `attention_pin_note`: Orange pin marker for attention items\n- `question_pin_note`: Blue pin marker for questions\n- `information_pin_note`: Green pin marker for information\n- `simple_note`: Full-page simple note (positions ignored)\n\n## Position Requirements\n\nFor all pin types, x_position, y_position, width, and height are required.\nFor `simple_note` type, these parameters are ignored as simple notes are page-level annotations.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Notepad 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": "Notepad created successfully", "description": "Status message" }, "result": { "type": "object", "properties": { "block_id": { "type": "integer", "example": 12345, "description": "ID of the created notepad block" }, "page_num": { "type": "integer", "example": 1, "description": "Page number where the notepad was added" }, "notepad_type": { "type": "string", "example": "attention_pin", "description": "Type of notepad created" } }, "required": [ "block_id", "page_num", "notepad_type" ], "description": "Created notepad information" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = validation error, 3 = system error)" }, "status_message": { "type": "string", "enum": [ "Page does not exist", "Not authorized to modify this page", "Notepad could not be created", "Parameter 'x_position' is required for notepad type 'attention_pin'" ], "example": "Page does not exist", "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 }, "project_node_id": { "type": "integer", "description": "Publication project node ID. Use POST /api/v3/publishing/list with class_id to get available publication projects.", "example": 556 }, "page_num": { "type": "integer", "description": "Page number (1-based). Use POST /api/v3/publishing/pages to list available pages.", "example": 1 }, "notepad_type": { "type": "string", "description": "Notepad type. For \"simple_note\", positions are ignored.", "enum": [ "attention_pin_note", "question_pin_note", "information_pin_note", "simple_note" ], "example": "attention_pin_note" }, "html_content": { "type": "string", "description": "HTML content for the notepad block. Supports basic formatting tags.", "example": "

Please review this section

" }, "x_position": { "type": "integer", "description": "X position in mm (required except for simple_note type)", "example": 50 }, "y_position": { "type": "integer", "description": "Y position in mm (required except for simple_note type)", "example": 100 }, "width": { "type": "integer", "description": "Width in mm (required except for simple_note type)", "example": 8 }, "height": { "type": "integer", "description": "Height in mm (required except for simple_note type)", "example": 8 } }, "required": [ "class_id", "project_node_id", "page_num", "notepad_type", "html_content" ] } } } } } }, "/api/v3/publishing/unassign-product-from-block/": { "post": { "tags": [ "publishing" ], "summary": "Remove a product from a block", "description": "## Purpose\n\nRemoves the product assignment from a product block, converting it back to an empty block. Associated form data is preserved.\n\n## When to use\n\nUse this endpoint to:\n- Clear a product block without deleting it\n- Convert a product block back to a placeholder\n- Prepare a block for a different product assignment\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Product unassignment 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": "Product unassigned from block successfully", "description": "Status message" }, "result": { "type": "object", "properties": { "block_id": { "type": "integer", "example": 12345, "description": "Block ID" }, "previous_type": { "type": "string", "example": "product_block", "description": "Previous block type before unassignment" }, "new_type": { "type": "string", "example": "empty_block", "description": "New block type after unassignment" }, "previous_node_id": { "type": "integer", "example": 5678, "description": "Previously assigned product node ID" } }, "required": [ "block_id", "previous_type", "new_type" ], "description": "Unassignment result" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = validation error, 3 = system error)" }, "status_message": { "type": "string", "enum": [ "Block not found", "Block is not a product block", "Block has no product assigned", "Not authorized to modify this block" ], "example": "Block not found", "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 }, "project_node_id": { "type": "integer", "description": "Publication project node ID. Use POST /api/v3/publishing/list with class_id to get available publication projects.", "example": 556 }, "block_id": { "type": "integer", "description": "Block ID to unassign product from. Use POST /api/v3/publishing/page-details with project_node_id and page_num to get block IDs.", "example": 12345 } }, "required": [ "class_id", "project_node_id", "block_id" ] } } } } } }, "/api/v3/publishing/details/": { "post": { "tags": [ "publishing" ], "summary": "Get publication details", "description": "## Purpose\n\nReturns complete details of a publication including dimensions, page count, display mode, and associated themes.\n\n## When to use\n\nUse this endpoint to:\n- Get an overview of a publication before working with its pages\n- Retrieve publication metadata (dimensions, page count)\n- List all themes configured for a publication\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Publication details response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status_code": { "type": "integer", "example": 1 }, "status_message": { "type": "string", "example": "Success" }, "result": { "type": "object", "properties": { "id": { "type": "integer", "description": "Publication ID" }, "node_id": { "type": "integer", "description": "Publication node ID" }, "label": { "type": "string", "description": "Publication name" }, "project_type": { "type": "string", "enum": [ "publication", "catalog_with_pagination" ], "description": "Project type" }, "nb_pages": { "type": "integer", "description": "Total number of pages" }, "page_width": { "type": "integer", "description": "Page width in mm" }, "page_height": { "type": "integer", "description": "Page height in mm" }, "display_mode": { "type": "string", "enum": [ "single", "double" ], "description": "Page display mode: single (one page at a time) or double (two-page spread)" }, "created_at": { "type": "string", "description": "Creation date" }, "themes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "label": { "type": "string" }, "color": { "type": "string" } } } } } } } } } } } }, "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 }, "project_node_id": { "type": "integer", "description": "Publication project node ID. Use POST /api/v3/publishing/list with class_id to get available publication projects.", "example": 556 } }, "required": [ "class_id", "project_node_id" ] } } } } } }, "/api/v3/publishing/pages/": { "post": { "tags": [ "publishing" ], "summary": "Get publication pages list", "description": "## Purpose\n\nReturns a paginated list of pages in a publication with their status and block count.\n\n## When to use\n\nUse this endpoint to:\n- List all pages of a publication\n- Get page status and block counts\n- Navigate through a publication structure\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Pages list response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status_code": { "type": "integer", "example": 1 }, "status_message": { "type": "string", "example": "Success" }, "result": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total number of pages" }, "page": { "type": "integer", "description": "Current pagination page" }, "limit": { "type": "integer", "description": "Results per page" }, "pages": { "type": "array", "items": { "type": "object", "properties": { "page_number": { "type": "integer" }, "node_id": { "type": "integer" }, "asset_id": { "type": "integer" }, "status_id": { "type": "integer" }, "status_label": { "type": "string" }, "blocks_count": { "type": "integer" }, "themes": { "type": "array", "items": { "type": "object" } } } } } } } } } } } } }, "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 }, "project_node_id": { "type": "integer", "description": "Publication project node ID. Use POST /api/v3/publishing/list with class_id to get available publication projects.", "example": 556 }, "page": { "type": "integer", "description": "Pagination page number for API results (NOT the publication page number). Default: 1. Use together with the \"limit\" parameter to paginate through the list of publication pages.", "example": 1 }, "limit": { "type": "integer", "description": "Results per page (default: 20, max: 100)", "example": 20 }, "include_themes": { "type": "boolean", "description": "Include themes for each page (default: false)", "example": false } }, "required": [ "class_id", "project_node_id" ] } } } } } }, "/api/v3/publishing/page-details/": { "post": { "tags": [ "publishing" ], "summary": "Get page details with blocks", "description": "## Purpose\n\nReturns complete details of a publication page including themes and all blocks with their positions, content, and metadata.\n\n## When to use\n\nUse this endpoint to:\n- Get all blocks on a specific page with their complete details\n- View block positions and dimensions for layout analysis\n- See which products are assigned to blocks with their templates and forms\n- Access form data values for product blocks\n- Track modification history (user, date, version)\n- Retrieve HTML content for text blocks and notes\n- Identify note hierarchies (parent-child relationships for replies)\n- Get page themes and status\n\n## Block type specificity\n\nDifferent block types return different fields:\n- **product_block**: includes node_id, template_id, template_label, form_id, form_datas\n- **text_block**: includes html_content\n- **note types**: includes html_content and parent_id (if reply to another note)\n- **empty_block**: basic positioning fields only\n\nOnly relevant fields are returned for each block type (no null values for unsupported fields).\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Page details response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status_code": { "type": "integer", "example": 1 }, "status_message": { "type": "string", "example": "Success" }, "result": { "type": "object", "properties": { "page_number": { "type": "integer" }, "node_id": { "type": "integer" }, "asset_id": { "type": "integer" }, "status_id": { "type": "integer" }, "status_label": { "type": "string" }, "themes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "label": { "type": "string" }, "color": { "type": "string" } } } }, "blocks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier of the block in the publication page" }, "type": { "type": "string", "description": "Block type: product_block (contains product), empty_block (placeholder), text_block (HTML content), or note types (annotations with possible replies)" }, "x_position": { "type": "integer", "description": "Horizontal position of the block on the page in millimeters from the left edge" }, "y_position": { "type": "integer", "description": "Vertical position of the block on the page in millimeters from the top edge" }, "width": { "type": "integer", "description": "Width of the block in millimeters" }, "height": { "type": "integer", "description": "Height of the block in millimeters" }, "user_id": { "type": "integer", "description": "ID of the user who last modified the block. Use POST /api/v3/assets/read/ with class_id=99 to get user details." }, "user_label": { "type": "string", "description": "Display name of the user who last modified the block" }, "modification_date": { "type": "string", "description": "Last modification date in ISO 8601 format (YYYY-MM-DD HH:MM:SS)" }, "history_id": { "type": "integer", "description": "Version ID in the block history, used for tracking changes and rollback operations" }, "node_id": { "type": "integer", "description": "Product node ID (only for product_block type). Use POST /api/v3/repository/node-content/ to get product details." }, "template_id": { "type": "integer", "description": "Product template/gabarit ID (only for product_block type). Use POST /api/v3/templates/list/ to get available templates." }, "template_label": { "type": "string", "description": "Product template/gabarit display name (only for product_block type with template assigned)" }, "form_id": { "type": "integer", "description": "Form instance ID containing attribute values (only for product_block type with form assigned)" }, "form_datas": { "type": "object", "description": "Form attribute values as key-value pairs where keys are attribute IDs and values are their content (only for product_block type with form assigned). Use POST /api/v3/attributes/list to get attribute definitions." }, "html_content": { "type": "string", "description": "HTML content of the block (only for text_block type and note types)" }, "parent_id": { "type": "integer", "description": "ID of the parent note block if this is a reply to another note (only for note types with parent)" } } } } } } } } } } } }, "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 }, "project_node_id": { "type": "integer", "description": "Publication project node ID. Use POST /api/v3/publishing/list with class_id to get available publication projects.", "example": 556 }, "page_num": { "type": "integer", "description": "Page number (1-based). Use POST /api/v3/publishing/pages to list available pages.", "example": 1 } }, "required": [ "class_id", "project_node_id", "page_num" ] } } } } } }, "/api/v3/queues/list/": { "post": { "tags": [ "queues" ], "summary": "List queue items", "description": "## Purpose\n\nReturns background job queue with execution status and optional filtering by status, type, and date range.\n\n## Use Cases\n\n- Monitor exports, imports, processes, and bulk operations\n- Track job progress and completion\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Queue items 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": "object", "properties": { "results_total": { "type": "integer", "example": 15, "description": "Number of items" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 12345, "description": "Queue ID" }, "user_id": { "type": "integer", "example": 1, "description": "User who initiated the queue" }, "type": { "type": "string", "example": "export", "description": "Queue type (export, importattrs, etc.)" }, "type_description": { "type": "string", "example": "Export", "description": "Queue type label (Import, Export, Importing Attributes, etc.)" }, "status": { "type": "string", "example": "in_progress", "enum": [ "pending", "in_progress", "finished", "being_killed", "killed", "canceled", "queue_connection_error", "fatal_error_out_of_process", "machine_error", "fatal_error_in_process", "temporary_duplicate_prevention" ], "description": "Queue status" }, "class_id": { "type": "integer", "nullable": true, "description": "Class ID (if queue executed by a process)", "example": 4 }, "process_id": { "type": "integer", "nullable": true, "example": 12345, "description": "Process ID (if queue executed by a process)" }, "project_node_id": { "type": "integer", "nullable": true, "description": "Project Node ID", "example": 556 }, "creation_date": { "type": "string", "example": "2024-12-07T14:29:45+00:00", "description": "Creation date and time (ISO 8601 format)" }, "start_date": { "type": "string", "example": "2024-12-07T14:30:45+00:00", "description": "Start date and time (ISO 8601 format)" }, "end_date": { "type": "string", "nullable": true, "example": "2024-12-07T15:30:45+00:00", "description": "End date and time (ISO 8601 format) : null if not finished" }, "attempts_count": { "type": "integer", "example": 1, "description": "Number of attempts" }, "result": { "type": "object", "nullable": true, "properties": { "totalResults": { "type": "integer", "example": 50, "description": "Total results" }, "nb": { "type": "integer", "example": 49, "description": "Number of items processed" } }, "description": "Results information" }, "notification_sent": { "type": "integer", "nullable": true, "example": 1, "description": "Notification sent" }, "file_info": { "type": "object", "nullable": true, "properties": { "file": { "type": "string", "example": "export_20250901_120000.csv", "description": "Generated filename" }, "extension": { "type": "string", "example": "csv", "description": "File extension" }, "size": { "type": "integer", "example": 10000, "description": "File size in bytes" }, "file_url": { "type": "string", "example": "https://my-afineo.com/gallery/global/dl/files/export_20250901_120000.csv", "description": "Direct download URL for the file" } }, "description": "File information (only present for finished queues that generated a file)" } }, "required": [ "id", "user_id", "type", "type_description", "status", "creation_date", "start_date", "end_date", "attempts_count" ], "description": "Queue information" } } }, "required": [ "results_total", "items" ], "description": "Queue list" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = error, 0 = validation failed)" }, "status_message": { "type": "string", "example": "Invalid parameters 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": { "status": { "type": "array", "description": "Filter by queue statuses: \"pending\" (waiting), \"in_progress\" (running), \"finished\" (completed), \"killed\" (stopped), \"canceled\" (cancelled by user), or error states.", "example": [ "pending", "in_progress" ], "items": { "type": "string", "enum": [ "pending", "in_progress", "finished", "being_killed", "killed", "canceled", "queue_connection_error", "fatal_error_out_of_process", "machine_error", "fatal_error_in_process", "temporary_duplicate_prevention" ] } }, "type": { "type": "string", "description": "Filter by queue type. Use POST /api/v3/queues/types to get all available types. Common values: \"Import\", \"Export\", \"DeleteFiche\", \"DeleteNode\", \"Process\", \"PublishEasyCatalog\".", "example": "Process" }, "start_date": { "type": "object", "description": "Start date of the element. Can be bounded using \"min\" and \"max\"", "example": { "min": "2025-09-20T14:00:00Z", "max": "2025-09-21T18:00:00Z" }, "properties": { "min": { "type": "string", "description": "Minimum start date (ISO 8601 format)", "example": "2025-09-20T14:00:00Z" }, "max": { "type": "string", "description": "Maximum start date (ISO 8601 format)", "example": "2025-09-21T18:00:00Z" } } }, "end_date": { "type": "object", "description": "End date of the element. Can be bounded using \"min\" and \"max\"", "example": { "min": "2025-11-14T08:30:00Z" }, "properties": { "min": { "type": "string", "description": "Minimum end date (ISO 8601 format)", "example": "2025-11-20T14:00:00Z" }, "max": { "type": "string", "description": "Maximum end date (ISO 8601 format)", "example": "2025-11-21T18:00:00Z" } } } } } } } } } }, "/api/v3/queues/get/": { "post": { "tags": [ "queues" ], "summary": "Get queue details", "description": "## Purpose\n\nReturns detailed queue information by ID including file download URL for finished jobs.\n\n## Permissions\n\n- Admin users: Access any queue\n- Regular users: Own queues only\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Queue details 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": "object", "properties": { "id": { "type": "integer", "example": 12345, "description": "Queue ID" }, "user_id": { "type": "integer", "example": 1, "description": "User who initiated the queue" }, "type_id": { "type": "string", "example": "export", "description": "Queue type" }, "type_label": { "type": "string", "example": "Export", "description": "Queue type label" }, "status_id": { "type": "integer", "example": 3, "description": "Queue status (1=pending, 2=in progress, 3=finished, etc.)" }, "status_label": { "type": "string", "example": "Finished", "description": "Human-readable status label" }, "creation_date": { "type": "string", "example": "2024-12-07T14:29:45+00:00", "description": "Creation date (ISO 8601)" }, "start_date": { "type": "string", "example": "2024-12-07T14:30:45+00:00", "description": "Start date (ISO 8601)" }, "end_date": { "type": "string", "nullable": true, "example": "2024-12-07T15:30:45+00:00", "description": "End date (ISO 8601)" }, "file_info": { "type": "object", "nullable": true, "properties": { "file": { "type": "string", "example": "export_20250901_120000.csv", "description": "Filename" }, "extension": { "type": "string", "example": "csv", "description": "File extension" }, "size": { "type": "integer", "example": 10000, "description": "File size in bytes" }, "file_url": { "type": "string", "example": "https://my-afineo.com/gallery/global/dl/files/export_20250901_120000.csv", "description": "Direct download URL" } }, "description": "File information (only for finished queues with generated files)" } }, "description": "Queue details" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = not found, 2 = validation error)" }, "status_message": { "type": "string", "example": "Queue 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": "Queue ID. Use POST /api/v3/queues/list to get available queues.", "example": 12345 } }, "required": [ "id" ] } } } } } }, "/api/v3/queues/types/": { "post": { "tags": [ "queues" ], "summary": "List queue types", "description": "## Purpose\n\nReturns available background job categories (Import, Export, Process, Delete) for filtering queue lists.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Queue types 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": "object", "properties": { "results_total": { "type": "integer", "example": 15, "description": "Number of items" }, "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "example": "importattr", "description": "Queue type" }, "description": { "type": "string", "example": "Importing attributes", "description": "Detailed description of the queue type" } }, "required": [ "type", "description" ], "description": "Queue type information" } } }, "required": [ "results_total", "items" ], "description": "List of available queue types", "example": { "results_total": 51, "items": [ { "type": "Import", "description": "Data import" }, { "type": "Export", "description": "Data export" }, { "type": "Process", "description": "Process execution" } ] } } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = error)" }, "status_message": { "type": "string", "example": "Access denied or system error", "description": "Error message" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array on error" } }, "required": [ "status_code", "status_message", "result" ] } ] } } } } } } }, "/api/v3/record-asset/create/repository/": { "post": { "tags": [ "record-asset" ], "summary": "Create asset in repository", "description": "## Purpose\n\nCreates a new master data record in repository with initial attribute values.\n\n## Attribute Lists\n\n- `attribute_list_simple`: Simple attributes (text, number, date, single dropdown)\n- `attribute_list_multiple`: Multiple attributes (associated data, dynamic, multiple dropdown)\n\n## Additional Information\n\n### Parameter \"attribute_list_simple\"\n\n#### Updating a simple dropdown list attribute\n\nTo update a **simple** dropdown list attribute, you need to send the element.\nIt is possible to insert either the identifier, the code, or the label — all three options are valid.\n\n```json\n{\"attribute_id\":1113,\"value\":\"1234\"}\n{\"attribute_id\":1113,\"value\":\"OPTION_CODE_4\"}\n{\"attribute_id\":1113,\"value\":\"Option label 2\"}\n```\n\n#### For other attribute types\n\nFor attributes with specific formatting (example: a price), it is possible to send a decimal number separated by either a comma or a dot — both will work.\nFor date attributes, the possible formats are as follows :\n- timestamp\n- ISO 8601 format : 2023-09-14T15:04:00.000Z\n- English format separated by \"-\" (with or without time) : 2017-12-13 or 2017-12-13 15:05:13\n- French format separated by \"-\" or \"/\" (with or without time) : 13-12-2017 or 13/12/2017 or 13-12-2017 15:05:13 or 13/12/2017 15:05:13\n- Timezone format with or without Greenwich time : 2017:12:13 10:15:59+02:00 or 2017:12:13 10:15:59\n\n### Parameter \"attribute_list_multiple\"\n\n#### Updating a associated data attribute\n\nTo update a related data attribute, you need to send an array containing one or more assets id :\n\n```json\n{\"attribute_id\":1113,\"value\":[1111]}\n{\"attribute_id\":1113,\"value\":[2222, 3333, 4444]}\n```\n\nIf you want to add one or more associated assets using the value of an attribute instead of the asset id (as in an import), this is possible using the \"key\" option :\n\n```json\n{\"attribute_id\":1113,\"key\":1284,\"value\":[\"asset\"]}\n{\"attribute_id\":1113,\"key\":1284,\"value\":[\"asset 1\", \"asset 2\"]}\n```\n\n#### Updating a multiple dropdown list attribute\nTo update a multiple dropdown list attribute, you also need to send an array containing one or more elements.\nIt is possible to insert either the identifier, the code, or the label — all three options are valid.\n\n```json\n{\"attribute_id\":1113,\"value\":[\"Option\"]}\n{\"attribute_id\":1113,\"value\":[1234, \"OPTION_CODE_4\", \"Option label 2\"]}\n```\n\n**Note :** If the code or the label of the desired option (for both simple and multiple dropdown lists) is an integer and corresponds to the identifier of another option in the same list, that option will be taken into account.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Asset creation repository 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": "object", "properties": { "asset_id": { "type": "integer", "example": 43178, "description": "Asset ID" }, "node_id": { "type": "integer", "example": 0, "description": "Node ID" }, "asset_id_duplicate": { "type": "integer", "nullable": true, "example": 45177, "description": "Asset ID for duplication" } }, "required": [ "asset_id", "node_id" ], "description": "Return information about the created asset" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = error)" }, "status_message": { "type": "string", "example": "The value for the parameter \"type_id\" (456) is invalid", "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 }, "type_id": { "type": "integer", "description": "Asset type ID. Use POST /api/v3/types/list with class_id to get available types.", "example": 89 }, "parent_id": { "type": "integer", "description": "Parent node ID in the repository tree. Set to 0 to create the asset at the root of the repository. Use POST /api/v3/get-asset/by-search/repository with class_id and parent_id=0 to browse the repository tree and find existing parent nodes.", "example": 4350 }, "version_id": { "type": "integer", "description": "Version ID. Use POST /api/v3/administration/versions/list with class_id to get available versions.", "example": 1 }, "attribute_list_simple": { "type": "array", "description": "List of attributes to be filled in, only simple attributes. List of properties to apply : \"attribute_id\", \"value\", \"suffix_value\" (optional) (Array of objects - see example for structure)", "example": [ { "attribute_id": 231, "value": "3-seater leather sofa" }, { "attribute_id": 658, "value": "1234" }, { "attribute_id": 659, "value": "100", "suffix_value": "EUR" } ], "items": { "type": "object", "properties": { "attribute_id": { "type": "integer", "description": "Attribute ID. Use POST /api/v3/attributes/list with class_id to get available attributes." }, "value": { "type": "string", "description": "Value to set. Format depends on attribute type (text, date, list option ID/code/label)." }, "suffix_value": { "type": "string", "description": "Suffix value for attributes with dropdown suffix (input, select-items, price). Accepts ID, code, or label." } }, "required": [ "attribute_id", "value" ], "title": "Item" } }, "attribute_list_multiple": { "type": "array", "description": "List of attributes to be filled in, only multiple attributes (associated data, dynamic attribute, multiple drop-down list). List of properties to apply : \"attribute_id\", \"value\", \"key\" (optional) (Array of objects - see example for structure)", "example": [ { "attribute_id": 724, "value": [ "Accessory A" ] }, { "attribute_id": 660, "value": [ "Label 1" ], "key": 2749 }, { "attribute_id": 659, "value": [ 1234, 2345, 4567 ] }, { "attribute_id": 660, "value": [ "Label 1", "Label 2", "Label 3" ], "key": 2749 } ], "items": { "type": "object", "properties": { "attribute_id": { "type": "integer", "description": "Attribute ID. Use POST /api/v3/attributes/list with class_id to get available attributes." }, "value": { "type": "array", "description": "Value to set. Format depends on attribute type (text, date, list option ID/code/label).", "items": { "type": "string" } }, "key": { "type": "integer", "description": "With this property, you can add one or more associated assets using the value of an attribute and not with the asset ID (as with import) - only for associated data attribute" } }, "required": [ "attribute_id", "value" ], "title": "Item" } } }, "required": [ "class_id", "type_id", "parent_id" ] } } } } } }, "/api/v3/record-asset/create/node/": { "post": { "tags": [ "record-asset" ], "summary": "Create node in project", "description": "## Purpose\n\nCreates a new contextualized node directly in project (not linked to repository).\n\n## Additional Information\n\n### Parameter \"attribute_list_simple\"\n\n#### Updating a simple dropdown list attribute\n\nTo update a **simple** dropdown list attribute, you need to send the element.\nIt is possible to insert either the identifier, the code, or the label — all three options are valid.\n\n```json\n{\"attribute_id\":1113,\"value\":\"1234\"}\n{\"attribute_id\":1113,\"value\":\"OPTION_CODE_4\"}\n{\"attribute_id\":1113,\"value\":\"Option label 2\"}\n```\n\n#### For other attribute types\n\nFor attributes with specific formatting (example: a price), it is possible to send a decimal number separated by either a comma or a dot — both will work.\nFor date attributes, the possible formats are as follows :\n- timestamp\n- ISO 8601 format : 2023-09-14T15:04:00.000Z\n- English format separated by \"-\" (with or without time) : 2017-12-13 or 2017-12-13 15:05:13\n- French format separated by \"-\" or \"/\" (with or without time) : 13-12-2017 or 13/12/2017 or 13-12-2017 15:05:13 or 13/12/2017 15:05:13\n- Timezone format with or without Greenwich time : 2017:12:13 10:15:59+02:00 or 2017:12:13 10:15:59\n\n### Parameter \"attribute_list_multiple\"\n\n#### Updating a associated data attribute\n\nTo update a related data attribute, you need to send an array containing one or more assets id :\n\n```json\n{\"attribute_id\":1113,\"value\":[1111]}\n{\"attribute_id\":1113,\"value\":[2222, 3333, 4444]}\n```\n\nIf you want to add one or more associated assets using the value of an attribute instead of the asset id (as in an import), this is possible using the \"key\" option :\n\n```json\n{\"attribute_id\":1113,\"key\":1284,\"value\":[\"asset\"]}\n{\"attribute_id\":1113,\"key\":1284,\"value\":[\"asset 1\", \"asset 2\"]}\n```\n\n#### Updating a multiple dropdown list attribute\nTo update a multiple dropdown list attribute, you also need to send an array containing one or more elements.\nIt is possible to insert either the identifier, the code, or the label — all three options are valid.\n\n```json\n{\"attribute_id\":1113,\"value\":[\"Option\"]}\n{\"attribute_id\":1113,\"value\":[1234, \"OPTION_CODE_4\", \"Option label 2\"]}\n```\n\n**Note :** If the code or the label of the desired option (for both simple and multiple dropdown lists) is an integer and corresponds to the identifier of another option in the same list, that option will be taken into account.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Asset creation node 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": "object", "properties": { "asset_id": { "type": "integer", "example": 0, "description": "Asset ID" }, "node_id": { "type": "integer", "example": 49324, "description": "Node ID" }, "asset_id_duplicate": { "type": "integer", "nullable": true, "example": 45177, "description": "Asset ID for duplication" } }, "required": [ "asset_id", "node_id" ], "description": "Return information about the created asset" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = error)" }, "status_message": { "type": "string", "example": "The value for the parameter \"type_id\" (456) is invalid", "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 }, "type_id": { "type": "integer", "description": "Asset type ID. Use POST /api/v3/types/list with class_id to get available types.", "example": 89 }, "parent_id": { "type": "integer", "description": "Parent node ID in the project tree. Set to 0 to create the asset at the root of the project. Use POST /api/v3/get-asset/by-search/node with class_id and project_node_id to browse the project tree and find existing parent nodes.", "example": 4350 }, "version_id": { "type": "integer", "description": "Version ID. Use POST /api/v3/administration/versions/list with class_id to get available versions.", "example": 1 }, "attribute_list_simple": { "type": "array", "description": "List of attributes to be filled in, only simple attributes. List of properties to apply : \"attribute_id\", \"value\", \"suffix_value\" (optional) (Array of objects - see example for structure)", "example": [ { "attribute_id": 231, "value": "3-seater leather sofa" }, { "attribute_id": 658, "value": "1234" }, { "attribute_id": 659, "value": "100", "suffix_value": "EUR" } ], "items": { "type": "object", "properties": { "attribute_id": { "type": "integer", "description": "Attribute ID. Use POST /api/v3/attributes/list with class_id to get available attributes." }, "value": { "type": "string", "description": "Value to set. Format depends on attribute type (text, date, list option ID/code/label)." }, "suffix_value": { "type": "string", "description": "Suffix value for attributes with dropdown suffix (input, select-items, price). Accepts ID, code, or label." } }, "required": [ "attribute_id", "value" ], "title": "Item" } }, "attribute_list_multiple": { "type": "array", "description": "List of attributes to be filled in, only multiple attributes (associated data, dynamic attribute, multiple drop-down list). List of properties to apply : \"attribute_id\", \"value\", \"key\" (optional) (Array of objects - see example for structure)", "example": [ { "attribute_id": 724, "value": [ "Accessory A" ] }, { "attribute_id": 660, "value": [ "Label 1" ], "key": 2749 }, { "attribute_id": 659, "value": [ 1234, 2345, 4567 ] }, { "attribute_id": 660, "value": [ "Label 1", "Label 2", "Label 3" ], "key": 2749 } ], "items": { "type": "object", "properties": { "attribute_id": { "type": "integer", "description": "Attribute ID. Use POST /api/v3/attributes/list with class_id to get available attributes." }, "value": { "type": "array", "description": "Value to set. Format depends on attribute type (text, date, list option ID/code/label).", "items": { "type": "string" } }, "key": { "type": "integer", "description": "With this property, you can add one or more associated assets using the value of an attribute and not with the asset ID (as with import) - only for associated data attribute" } }, "required": [ "attribute_id", "value" ], "title": "Item" } } }, "required": [ "class_id", "type_id", "parent_id" ] } } } } } }, "/api/v3/record-asset/available-attributes-creation/": { "post": { "tags": [ "record-asset" ], "summary": "Get available attributes for creation", "description": "## Purpose\n\nReturns list of available attributes for a specific type to help build dynamic creation forms.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Attribute 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": "string" }, "description": "Attribute list for creation (key = attribute ID, value = attribute label)" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (2 = error, 3 = no result)" }, "status_message": { "type": "string", "example": "No results found", "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": { "type_id": { "type": "integer", "description": "Asset type ID. Use POST /api/v3/types/list with class_id to get available types.", "example": 89 } }, "required": [ "type_id" ] } } } } } }, "/api/v3/record-asset/update-status/repository/": { "post": { "tags": [ "record-asset" ], "summary": "Update repository asset status", "description": "## Purpose\n\nUpdates workflow status (LCA) of a repository asset. Changes propagate to all projects unless overridden.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Update status repository 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": "Status updated", "description": "Status message" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = error)" }, "status_message": { "type": "string", "example": "You don't have the rights to update the status of this asset", "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": "Asset ID. Use POST /api/v3/get-asset/by-search/repository to find assets and get their IDs.", "example": 5684 }, "class_id": { "type": "integer", "description": "Library ID. Use POST /api/v3/administration/classes/list to get available libraries.", "example": 4 }, "status_id": { "type": "integer", "description": "Status ID. Use POST /api/v3/permissions/statuses/list to get available statuses.", "example": 102 } }, "required": [ "id", "class_id", "status_id" ] } } } } } }, "/api/v3/record-asset/update-status/node/": { "post": { "tags": [ "record-asset" ], "summary": "Update project node status", "description": "## Purpose\n\nUpdates workflow status (LCA) of a project node. Optionally propagate to repository asset.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Update status node 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": "Status updated", "description": "Status message" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = error)" }, "status_message": { "type": "string", "example": "The status of the asset is already the same as the one you want to set", "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": "Node ID. Use POST /api/v3/get-asset/by-search/node to find nodes and get their IDs.", "example": 5684 }, "class_id": { "type": "integer", "description": "Library ID. Use POST /api/v3/administration/classes/list to get available libraries.", "example": 4 }, "status_id": { "type": "integer", "description": "Status ID. Use POST /api/v3/permissions/statuses/list to get available statuses.", "example": 102 }, "force_propagation_asset": { "type": "boolean", "description": "If set to true, the status will be propagated to the repository asset", "example": true } }, "required": [ "id", "class_id", "status_id" ] } } } } } }, "/api/v3/record-asset/update-type/": { "post": { "tags": [ "record-asset" ], "summary": "Change asset type", "description": "## Purpose\n\nReclassifies asset to a different type within the same class.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Update type 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": "Asset type updated", "description": "Status message" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = error)" }, "status_message": { "type": "string", "example": "You don't have the rights to update the type of this asset", "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": "Asset ID. Use POST /api/v3/get-asset/by-search/repository to find assets and get their IDs.", "example": 5684 }, "class_id": { "type": "integer", "description": "Library ID. Use POST /api/v3/administration/classes/list to get available libraries.", "example": 4 }, "type_id": { "type": "integer", "description": "Asset type ID. Use POST /api/v3/types/list with class_id to get available types.", "example": 89 } }, "required": [ "id", "class_id", "type_id" ] } } } } } }, "/api/v3/record-asset/upload-file/repository/": { "post": { "tags": [ "record-asset" ], "summary": "Upload file to repository asset", "description": "## Purpose\n\nAttaches a physical file to a repository asset. File becomes available for all projects.\n\n## Content-Type\n\n**Important**: The request must be sent as `multipart/form-data`. The `file` field must include a `filename` with a valid extension (e.g. `filename=\"image.jpg\"`). The file extension is used to validate the file type against the allowed extensions configured for your application. Sending the file as raw binary without a filename will result in a \"This type of file is not allowed\" error.\n\n## Example with curl\n\n```bash\ncurl -X POST \"https://{instance}.afineo.io/api/v3/record-asset/upload-file_repository/\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n --form 'id=\"5684\"' \\\n --form 'class_id=\"4\"' \\\n --form 'file=@\"/path/to/image.jpg\"'\n```\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Upload file repository 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": "Creation done", "description": "Status message" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (2 = error, 3 = no action done)" }, "status_message": { "type": "string", "example": "No action done", "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": "Asset ID. Use POST /api/v3/get-asset/by-search/repository to find assets and get their IDs.", "example": 5684 }, "class_id": { "type": "integer", "description": "Library ID. Use POST /api/v3/administration/classes/list to get available libraries.", "example": 4 }, "file": { "type": "string", "format": "binary", "description": "The file to upload. Must be sent as multipart/form-data with a filename including a valid extension (e.g. image.jpg). The extension is checked against the allowed file types configured for your application.", "example": "image.jpg" } }, "required": [ "id", "class_id" ] } } } } } }, "/api/v3/record-asset/upload-file/node/": { "post": { "tags": [ "record-asset" ], "summary": "Upload file to project node", "description": "## Purpose\n\nAttaches a physical file to a project-specific node. File exists only in this project context.\n\n## Content-Type\n\n**Important**: The request must be sent as `multipart/form-data`. The `file` field must include a `filename` with a valid extension (e.g. `filename=\"image.jpg\"`). The file extension is used to validate the file type against the allowed extensions configured for your application. Sending the file as raw binary without a filename will result in a \"This type of file is not allowed\" error.\n\n## Example with curl\n\n```bash\ncurl -X POST \"https://{instance}.afineo.io/api/v3/record-asset/upload-file_node/\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n --form 'id=\"5684\"' \\\n --form 'class_id=\"4\"' \\\n --form 'file=@\"/path/to/image.jpg\"'\n```\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Upload file node 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": "Update done", "description": "Status message" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = error, 3 = no action done)" }, "status_message": { "type": "string", "example": "This type of file is not allowed", "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": "Node ID. Use POST /api/v3/get-asset/by-search/node to find nodes and get their IDs.", "example": 5684 }, "class_id": { "type": "integer", "description": "Library ID. Use POST /api/v3/administration/classes/list to get available libraries.", "example": 4 }, "file": { "type": "string", "format": "binary", "description": "The file to upload. Must be sent as multipart/form-data with a filename including a valid extension (e.g. image.jpg). The extension is checked against the allowed file types configured for your application.", "example": "image.jpg" } }, "required": [ "id", "class_id" ] } } } } } }, "/api/v3/record-asset/add-asset-to-project/": { "post": { "tags": [ "record-asset" ], "summary": "Add repository asset to project", "description": "## Purpose\n\nCreates a contextualized node from a repository asset in a project. Returns created node_id.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Add asset to project 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": "object", "properties": { "node_id": { "type": "integer", "example": 4576, "description": "Node ID" } }, "required": [ "node_id" ], "description": "Created node ID" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = error, 3 = Aborted because this asset already exists in this node)" }, "status_message": { "type": "string", "example": "Asset does not exist or has been deleted", "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 }, "asset_id": { "type": "integer", "description": "Asset ID. Use POST /api/v3/get-asset/by-search/repository to find assets.", "example": 5684 }, "parent_node_id": { "type": "integer", "description": "Parent node ID. Use POST /api/v3/get-asset/by-search/node to find project nodes.", "example": 69852 }, "status_id": { "type": "integer", "description": "Status ID. Use POST /api/v3/permissions/statuses/list to get available statuses.", "example": 102 } }, "required": [ "class_id", "asset_id", "parent_node_id" ] } } } } } }, "/api/v3/record-asset/move-node-in-project/": { "post": { "tags": [ "record-asset" ], "summary": "Move node in project", "description": "## Purpose\n\nMoves a node (and children) to a new parent location within the project.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Move node in project 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": "object", "properties": { "node_id": { "type": "integer", "example": 4577, "description": "Node ID" } }, "required": [ "node_id" ], "description": "Created node ID" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = error)" }, "status_message": { "type": "string", "example": "Node does not exist or has been deleted", "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 }, "node_id": { "type": "integer", "description": "Node ID. Use POST /api/v3/get-asset/by-search/node to find project nodes.", "example": 56845 }, "parent_node_id": { "type": "integer", "description": "Parent node ID. Use POST /api/v3/get-asset/by-search/node to find project nodes.", "example": 69852 } }, "required": [ "class_id", "node_id", "parent_node_id" ] } } } } } }, "/api/v3/record-asset/copy-node-in-project/": { "post": { "tags": [ "record-asset" ], "summary": "Copy node in project", "description": "## Purpose\n\nDuplicates a node (and children) to a new location within the project. Returns new node_id.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Copy node in project 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": "object", "properties": { "node_id": { "type": "integer", "example": 4578, "description": "Node ID" } }, "required": [ "node_id" ], "description": "Created node ID" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = error, 3 = Aborted because this asset already exists in this node)" }, "status_message": { "type": "string", "example": "Parent node does not exist or has been deleted", "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 }, "node_id": { "type": "integer", "description": "Node ID. Use POST /api/v3/get-asset/by-search/node to find project nodes.", "example": 56845 }, "parent_node_id": { "type": "integer", "description": "Parent node ID. Use POST /api/v3/get-asset/by-search/node to find project nodes.", "example": 69852 } }, "required": [ "class_id", "node_id", "parent_node_id" ] } } } } } }, "/api/v3/record-asset/move-asset-in-repository/": { "post": { "tags": [ "record-asset" ], "summary": "Move an asset to a different parent in the repository hierarchy", "description": "## Purpose\n\nMoves an asset (and its children) to a new parent location within the repository hierarchy.\n\nUse `parent_id = 0` to move the asset to the root of the repository.\n\n## Requirements\n\n- **Permission**: The user must have the `cut/move` permission (LCA) on the source asset.\n- **Same library**: The `parent_id` must belong to the same `class_id` as the `asset_id`.\n\n## Common Errors\n\n| Error | Cause | Solution |\n|-------|-------|----------|\n| `Asset does not exist or has been deleted` | `asset_id` is invalid or deleted | Verify with POST /api/v3/get-asset/by-search/repository/ |\n| `Parent asset does not exist or has been deleted` | `parent_id` is invalid or deleted (when > 0) | Verify with POST /api/v3/get-asset/by-search/repository/ |\n| `Cannot move an asset into itself` | `asset_id` == `parent_id` | Use a different `parent_id` |\n| `Cannot move an asset into one of its own children` | `parent_id` is a descendant of `asset_id` | Choose a parent that is not a child of the moved asset |\n| `Operation not allowed` | Insufficient LCA permissions | Check user permissions on the source asset |\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Move asset in repository 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": "object", "properties": { "asset_id": { "type": "integer", "example": 1234, "description": "Asset ID" } }, "required": [ "asset_id" ], "description": "The ID of the asset that was successfully moved" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = error)" }, "status_message": { "type": "string", "example": "Asset does not exist or has been deleted", "description": "Error message. Possible values: \"Asset does not exist or has been deleted\", \"Parent asset does not exist or has been deleted\", \"Cannot move an asset into itself\", \"Cannot move an asset into one of its own children\", \"Operation not allowed\"" }, "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 }, "asset_id": { "type": "integer", "description": "Asset ID to move. Use POST /api/v3/get-asset/by-search/repository to find repository assets.", "example": 1234 }, "parent_id": { "type": "integer", "description": "Destination parent asset ID within the same library. Must belong to the same class_id as asset_id. Use 0 to move to the root of the repository. Use POST /api/v3/get-asset/by-search/repository/ to find valid parent assets.", "example": 5678 } }, "required": [ "class_id", "asset_id", "parent_id" ] } } } } } }, "/api/v3/record-asset/destroy/repository/": { "post": { "tags": [ "record-asset" ], "summary": "Delete repository asset permanently", "description": "## Purpose\n\nIRREVERSIBLY removes asset and children from repository. Prefer `detach` for reversible removal.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Destroy repository 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": "Asset and all child assets have been deleted", "description": "Status message" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = error)" }, "status_message": { "type": "string", "example": "Impossible to destroy this asset because it is classified", "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": "Asset ID. Use POST /api/v3/get-asset/by-search/repository to find assets and get their IDs.", "example": 5845 }, "class_id": { "type": "integer", "description": "Library ID. Use POST /api/v3/administration/classes/list to get available libraries.", "example": 4 } }, "required": [ "id", "class_id" ] } } } } } }, "/api/v3/record-asset/detach/repository/": { "post": { "tags": [ "record-asset" ], "summary": "Detach asset from repository tree", "description": "## Purpose\n\nMoves asset and children to Unclassified folder (reversible). Asset remains accessible for reclassification.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Detach repository 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": "Asset and all child assets have been detached", "description": "Status message" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = error)" }, "status_message": { "type": "string", "example": "You don't have the rights to detach child assets from the asset", "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": "Asset ID. Use POST /api/v3/get-asset/by-search/repository to find assets and get their IDs.", "example": 5845 }, "class_id": { "type": "integer", "description": "Library ID. Use POST /api/v3/administration/classes/list to get available libraries.", "example": 4 } }, "required": [ "id", "class_id" ] } } } } } }, "/api/v3/record-asset/destroy/node/": { "post": { "tags": [ "record-asset" ], "summary": "Delete node and repository asset", "description": "## Purpose\n\nIRREVERSIBLY removes both project node AND repository master data with all children. Cascading deletion affects all projects.\n\n⚠️ Extremely destructive - prefer `detach` for reversible removal.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Destroy node 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": "Node and all child nodes have been deleted", "description": "Status message" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = error)" }, "status_message": { "type": "string", "example": "Impossible to destroy this node because it is classified elsewhere", "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": "Node ID. Use POST /api/v3/get-asset/by-search/node to find nodes and get their IDs.", "example": 58450 }, "class_id": { "type": "integer", "description": "Library ID. Use POST /api/v3/administration/classes/list to get available libraries.", "example": 4 } }, "required": [ "id", "class_id" ] } } } } } }, "/api/v3/record-asset/detach/node/": { "post": { "tags": [ "record-asset" ], "summary": "Detach node from project", "description": "## Purpose\n\nRemoves node and children from project tree without affecting repository. Reversible operation - repository asset remains intact and can be re-added.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Detach node 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": "Node and all child nodes have been detached", "description": "Status message" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = error)" }, "status_message": { "type": "string", "example": "You don't have the rights to detach child assets from the node", "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": "Node ID. Use POST /api/v3/get-asset/by-search/node to find nodes and get their IDs.", "example": 58450 }, "class_id": { "type": "integer", "description": "Library ID. Use POST /api/v3/administration/classes/list to get available libraries.", "example": 4 } }, "required": [ "id", "class_id" ] } } } } } }, "/api/v3/record-asset/update-datas/repository/": { "post": { "tags": [ "record-asset" ], "summary": "Update repository asset attributes", "description": "## Purpose\n\nUpdates attribute values (simple and multiple types) of an existing asset in the **repository** (master data). Changes propagate to all projects where the asset is used, unless a local override exists.\n\n## When to Use\n\n- Use `/repository/` to update master data (affects all projects). Use `/node/` variant to update project-specific overrides without affecting master data.\n- Use POST /api/v3/attributes/list with class_id to discover available attributes and their types (simple vs multiple)\n- Use POST /api/v3/get-asset/by-search/repository to find asset IDs to update\n\n## Requirements\n\n- **Asset existence**: Asset ID must exist and not be deleted\n- **Library context**: Valid class_id must be provided\n\n⚠️ Repository updates propagate to all projects unless local overrides exist.\n\n---\n\n## Simple Attributes (`attribute_list_simple`)\n\nFor: Text, number, date, simple dropdown list, and other single-value attributes.\n\n| Property | Required | Description |\n|----------|----------|-------------|\n| `attribute_id` | ✅ | Attribute identifier |\n| `value` | ✅ | Value to set (empty string to clear) |\n| `version_id` | ❌ | Target language version (default if not specified) |\n\n### Simple Dropdown Lists\n\nPass element identifier, code, or label. All three formats are accepted.\n\n```json\n{\"attribute_id\":1113,\"value\":\"1234\"}\n{\"attribute_id\":1113,\"value\":\"OPTION_CODE_4\"}\n{\"attribute_id\":1113,\"value\":\"Red color\"}\n```\n\n### Date Formats\n\nSupported formats:\n- Timestamp: `1694704440`\n- ISO 8601: `2023-09-14T15:04:00.000Z`\n- English (YYYY-MM-DD): `2017-12-13` or `2017-12-13 15:05:13`\n- European (DD-MM-YYYY or DD/MM/YYYY): `13-12-2017` or `13/12/2017 15:05:13`\n- Timezone format: `2017:12:13 10:15:59+02:00`\n\n### Numeric Attributes\n\nDecimal separator: comma or dot accepted (e.g., `12.99` or `12,99`).\n\n### Clearing Values\n\nSet `value` to empty string to clear attribute value:\n\n```json\n{\"attribute_id\":1113,\"value\":\"\"}\n```\n\n---\n\n## Multiple Attributes (`attribute_list_multiple`)\n\nFor: Associated data, dynamic attributes, and multiple dropdown lists.\n\n| Property | Required | Description |\n|----------|----------|-------------|\n| `attribute_id` | ✅ | Attribute identifier |\n| `value` | ✅ | Array of values (empty array to clear all) |\n| `synchronization` | ✅ | `false` = add mode, `true` = sync mode |\n| `key` | ❌ | Attribute ID to use as lookup key (associated data only) |\n| `version_id` | ❌ | Target language version (default if not specified) |\n\n### Associated Data\n\nPass array of asset IDs:\n\n```json\n{\"attribute_id\":724,\"value\":[1111],\"synchronization\":false}\n{\"attribute_id\":724,\"value\":[2222, 3333, 4444],\"synchronization\":true}\n```\n\n**Synchronization modes**:\n- `false` (Add mode): Appends values without removing existing ones\n- `true` (Sync mode): Removes values not in array, adds missing ones, preserves matching ones\n\n**Using attribute values as keys** (import-style lookup):\n\n```json\n{\"attribute_id\":724,\"key\":1284,\"value\":[\"SKU-12345\"],\"synchronization\":true}\n{\"attribute_id\":724,\"key\":1284,\"value\":[\"Product A\", \"Product B\"],\"synchronization\":false}\n```\n\n### Multiple Dropdown Lists\n\nPass array of identifiers, codes, or labels:\n\n```json\n{\"attribute_id\":1113,\"value\":[\"Red\"],\"synchronization\":true}\n{\"attribute_id\":1113,\"value\":[1234, \"OPTION_CODE_4\", \"Blue color\"],\"synchronization\":false}\n```\n\n⚠️ If a code or label is numeric and matches another option ID, the ID match takes precedence.\n\n---\n\n## Example\n\n```json\n{\n \"id\": 5845,\n \"class_id\": 4,\n \"attribute_list_simple\": [\n {\"attribute_id\": 231, \"value\": \"3-seater sofa\"},\n {\"attribute_id\": 1234, \"value\": \"\"},\n {\"attribute_id\": 658, \"value\": \"Red leather\", \"version_id\": 2},\n {\"attribute_id\": 658, \"value\": \"Cuir rouge\", \"version_id\": 1}\n ],\n \"attribute_list_multiple\": [\n {\"attribute_id\": 724, \"value\": [\"Red\", \"Black\"], \"synchronization\": true},\n {\"attribute_id\": 660, \"value\": [\"Chair legs\"], \"synchronization\": false, \"key\": 2749},\n {\"attribute_id\": 659, \"value\": [1234, 2345], \"synchronization\": false, \"version_id\": 2}\n ]\n}\n```\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Asset data update 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": "Asset data updated", "description": "Status message" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = parameter error)" }, "status_message": { "type": "string", "example": "Asset does not exist or has been deleted", "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": "Asset ID. Use POST /api/v3/get-asset/by-search/repository to find assets and get their IDs.", "example": 5845 }, "class_id": { "type": "integer", "description": "Library ID. Use POST /api/v3/administration/classes/list to get available libraries.", "example": 4 }, "attribute_list_simple": { "type": "array", "description": "Simple attributes (text, number, date, single dropdown). Pass same attribute_id multiple times with different version_id to update multiple languages. (Array of objects - see example for structure)", "example": [ { "attribute_id": 231, "value": "3-seater sofa" }, { "attribute_id": 1234, "value": "" }, { "attribute_id": 658, "value": "Red leather", "version_id": 2 }, { "attribute_id": 658, "value": "Cuir rouge", "version_id": 1 }, { "attribute_id": 658, "value": "Cuero rojo", "version_id": 3 }, { "attribute_id": 659, "value": "100", "suffix_value": "EUR" } ], "items": { "type": "object", "properties": { "attribute_id": { "type": "integer", "description": "Attribute ID. Use POST /api/v3/attributes/list with class_id to get available attributes." }, "value": { "type": "string", "description": "Value to set. Format depends on attribute type. Empty string clears the value." }, "version_id": { "type": "integer", "description": "Version ID for multilingual data. Use POST /api/v3/administration/versions/list." }, "suffix_value": { "type": "string", "description": "Suffix value for attributes with dropdown suffix (input, select-items, price). Accepts ID, code, or label." } }, "required": [ "attribute_id", "value" ], "title": "Item" } }, "attribute_list_multiple": { "type": "array", "description": "Multiple attributes (associated data, multiple dropdown). Pass same attribute_id multiple times with different version_id to update multiple languages. (Array of objects - see example for structure)", "example": [ { "attribute_id": 724, "value": [ "Red", "Black" ], "synchronization": true }, { "attribute_id": 660, "value": [ "Chair legs" ], "synchronization": false, "key": 2749 }, { "attribute_id": 659, "value": [ 1234, 2345, 4567 ], "synchronization": false, "version_id": 2 } ], "items": { "type": "object", "properties": { "attribute_id": { "type": "integer", "description": "Attribute ID. Use POST /api/v3/attributes/list with class_id to get available attributes." }, "value": { "type": "array", "description": "Array of values (empty array to clear all)", "items": { "type": "string" } }, "synchronization": { "type": "boolean", "description": "false = add mode, true = sync mode (remove unlisted, add missing)" }, "key": { "type": "integer", "description": "Attribute ID to use as lookup key (associated data only)" }, "version_id": { "type": "integer", "description": "Version ID. Use POST /api/v3/administration/versions/list with class_id. Default if omitted" } }, "required": [ "attribute_id", "value", "synchronization" ], "title": "Item" } } }, "required": [ "id", "class_id" ] } } } } } }, "/api/v3/record-asset/update-datas/node/": { "post": { "tags": [ "record-asset" ], "summary": "Update project node attributes", "description": "## Purpose\n\nUpdates project-specific attribute values (simple and multiple types) for an existing node. Creates contextualized overrides without affecting repository master data. Use for catalog or publication-specific adaptations.\n\n## When to Use\n\n- Use `/node/` to update project-specific overrides (does not affect master data). Use `/repository/` variant to update master data that propagates to all projects.\n- Use POST /api/v3/attributes/list with class_id to discover available attributes and their types (simple vs multiple)\n- Use POST /api/v3/get-asset/by-search/node with class_id and parent_id to find node IDs to update\n\n## Requirements\n\n- **Node existence**: Node ID must exist and not be deleted\n- **Library context**: Valid class_id must be provided\n\n⚠️ Project node updates do not affect repository master data.\n\n---\n\n## Simple Attributes (`attribute_list_simple`)\n\nFor: Text, number, date, simple dropdown list, and other single-value attributes.\n\n| Property | Required | Description |\n|----------|----------|-------------|\n| `attribute_id` | ✅ | Attribute identifier |\n| `value` | ✅ | Value to set (empty string to clear) |\n| `version_id` | ❌ | Target language version (default if not specified) |\n\n### Simple Dropdown Lists\n\nPass element identifier, code, or label. All three formats are accepted.\n\n```json\n{\"attribute_id\":1113,\"value\":\"1234\"}\n{\"attribute_id\":1113,\"value\":\"OPTION_CODE_4\"}\n{\"attribute_id\":1113,\"value\":\"Red color\"}\n```\n\n### Date Formats\n\nSupported formats:\n- Timestamp: `1694704440`\n- ISO 8601: `2023-09-14T15:04:00.000Z`\n- English (YYYY-MM-DD): `2017-12-13` or `2017-12-13 15:05:13`\n- European (DD-MM-YYYY or DD/MM/YYYY): `13-12-2017` or `13/12/2017 15:05:13`\n- Timezone format: `2017:12:13 10:15:59+02:00`\n\n### Numeric Attributes\n\nDecimal separator: comma or dot accepted (e.g., `12.99` or `12,99`).\n\n### Clearing Values\n\nSet `value` to empty string to clear attribute value:\n\n```json\n{\"attribute_id\":1113,\"value\":\"\"}\n```\n\n---\n\n## Multiple Attributes (`attribute_list_multiple`)\n\nFor: Associated data, dynamic attributes, and multiple dropdown lists.\n\n| Property | Required | Description |\n|----------|----------|-------------|\n| `attribute_id` | ✅ | Attribute identifier |\n| `value` | ✅ | Array of values (empty array to clear all) |\n| `synchronization` | ✅ | `false` = add mode, `true` = sync mode |\n| `key` | ❌ | Attribute ID to use as lookup key (associated data only) |\n| `version_id` | ❌ | Target language version (default if not specified) |\n\n### Associated Data\n\nPass array of asset IDs:\n\n```json\n{\"attribute_id\":724,\"value\":[1111],\"synchronization\":false}\n{\"attribute_id\":724,\"value\":[2222, 3333, 4444],\"synchronization\":true}\n```\n\n**Synchronization modes**:\n- `false` (Add mode): Appends values without removing existing ones\n- `true` (Sync mode): Removes values not in array, adds missing ones, preserves matching ones\n\n**Using attribute values as keys** (import-style lookup):\n\n```json\n{\"attribute_id\":724,\"key\":1284,\"value\":[\"SKU-12345\"],\"synchronization\":true}\n{\"attribute_id\":724,\"key\":1284,\"value\":[\"Product A\", \"Product B\"],\"synchronization\":false}\n```\n\n### Multiple Dropdown Lists\n\nPass array of identifiers, codes, or labels:\n\n```json\n{\"attribute_id\":1113,\"value\":[\"Red\"],\"synchronization\":true}\n{\"attribute_id\":1113,\"value\":[1234, \"OPTION_CODE_4\", \"Blue color\"],\"synchronization\":false}\n```\n\n⚠️ If a code or label is numeric and matches another option ID, the ID match takes precedence.\n\n---\n\n## Example\n\n```json\n{\n \"id\": 58450,\n \"class_id\": 4,\n \"attribute_list_simple\": [\n {\"attribute_id\": 231, \"value\": \"3-seater sofa\"},\n {\"attribute_id\": 1234, \"value\": \"\"},\n {\"attribute_id\": 658, \"value\": \"Red leather\", \"version_id\": 2},\n {\"attribute_id\": 658, \"value\": \"Cuir rouge\", \"version_id\": 1}\n ],\n \"attribute_list_multiple\": [\n {\"attribute_id\": 724, \"value\": [\"Red\", \"Black\"], \"synchronization\": true},\n {\"attribute_id\": 660, \"value\": [\"Chair legs\"], \"synchronization\": false, \"key\": 2749},\n {\"attribute_id\": 659, \"value\": [1234, 2345], \"synchronization\": false, \"version_id\": 2}\n ]\n}\n```\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Update datas asset node 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": "Asset data updated", "description": "Status message" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = error)" }, "status_message": { "type": "string", "example": "Node does not exist or has been deleted", "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": "Node ID. Use POST /api/v3/get-asset/by-search/node to find nodes and get their IDs.", "example": 58450 }, "class_id": { "type": "integer", "description": "Library ID. Use POST /api/v3/administration/classes/list to get available libraries.", "example": 4 }, "attribute_list_simple": { "type": "array", "description": "Simple attributes (text, number, date, single dropdown). Pass same attribute_id multiple times with different version_id to update multiple languages. (Array of objects - see example for structure)", "example": [ { "attribute_id": 231, "value": "3-seater sofa" }, { "attribute_id": 1234, "value": "" }, { "attribute_id": 658, "value": "Red leather", "version_id": 2 }, { "attribute_id": 658, "value": "Cuir rouge", "version_id": 1 }, { "attribute_id": 658, "value": "Cuero rojo", "version_id": 3 }, { "attribute_id": 659, "value": "100", "suffix_value": "EUR" } ], "items": { "type": "object", "properties": { "attribute_id": { "type": "integer", "description": "Attribute ID. Use POST /api/v3/attributes/list with class_id to get available attributes." }, "value": { "type": "string", "description": "Value to set. Format depends on attribute type. Empty string clears the value." }, "version_id": { "type": "integer", "description": "Version ID for multilingual data. Use POST /api/v3/administration/versions/list." }, "suffix_value": { "type": "string", "description": "Suffix value for attributes with dropdown suffix (input, select-items, price). Accepts ID, code, or label." } }, "required": [ "attribute_id", "value" ], "title": "Item" } }, "attribute_list_multiple": { "type": "array", "description": "Multiple attributes (associated data, multiple dropdown). Pass same attribute_id multiple times with different version_id to update multiple languages. (Array of objects - see example for structure)", "example": [ { "attribute_id": 724, "value": [ "Red", "Black" ], "synchronization": true }, { "attribute_id": 660, "value": [ "Chair legs" ], "synchronization": false, "key": 2749 }, { "attribute_id": 659, "value": [ 1234, 2345, 4567 ], "synchronization": false, "version_id": 2 } ], "items": { "type": "object", "properties": { "attribute_id": { "type": "integer", "description": "Attribute ID. Use POST /api/v3/attributes/list with class_id to get available attributes." }, "value": { "type": "array", "description": "Array of values (empty array to clear all)", "items": { "type": "string" } }, "synchronization": { "type": "boolean", "description": "false = add mode, true = sync mode (remove unlisted, add missing)" }, "key": { "type": "integer", "description": "Attribute ID to use as lookup key (associated data only)" }, "version_id": { "type": "integer", "description": "Version ID. Use POST /api/v3/administration/versions/list with class_id. Default if omitted" } }, "required": [ "attribute_id", "value", "synchronization" ], "title": "Item" } } }, "required": [ "id", "class_id" ] } } } } } }, "/api/v3/record-asset/repoint/node/": { "post": { "tags": [ "record-asset" ], "summary": "Repoint a node to a different asset", "description": "## Purpose\n\nRepoints a node (project position) to a different asset (master record). Useful to correct import mistakes.\n\n## Preserved Data\n\n- Node identity (publications, history, statuses, workflows)\n- All contextual data associated with the node\n- Alias positions (automatically updated)\n\n## Links Processing\n\n- **Non-workspace attributes**: Links updated to point to new asset\n- **Workspace attributes** (scope=5): Links deleted (workspace data not transferred)\n\n## Constraints\n\n- **Duplicate prevention**: Blocked if sibling node already references target asset\n- **Cascade to aliases**: All alias positions automatically updated\n- **Workspace data**: Cleanup processed if no other nodes reference old asset\n- **Indexation**: Automatic reindexation triggered\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Node repoint 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 or warning" }, "result": { "type": "object", "properties": { "node_id": { "type": "integer", "example": 12345, "description": "Node ID that was repointed" }, "old_asset_id": { "type": "integer", "example": 54321, "description": "Previous asset ID" }, "new_asset_id": { "type": "integer", "example": 67890, "description": "New asset ID" }, "aliases_updated": { "type": "integer", "example": 2, "description": "Number of alias positions updated" }, "links_updated": { "type": "integer", "example": 15, "description": "Number of non-workspace links updated" }, "workspace_links_deleted": { "type": "integer", "example": 3, "description": "Number of workspace links deleted" }, "workspace_id": { "type": "integer", "example": 789, "description": "Workspace ID" } }, "required": [ "node_id", "old_asset_id", "new_asset_id", "aliases_updated", "links_updated", "workspace_links_deleted", "workspace_id" ], "description": "Details of the repoint operation" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = parameter error, 3 = processing error)" }, "status_message": { "type": "string", "example": "Node does not exist or has been deleted", "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": { "node_id": { "type": "integer", "description": "Node ID (position in project) to repoint. Use POST /api/v3/get-asset/by-search/node to find nodes.", "example": 12345 }, "asset_id": { "type": "integer", "description": "Target asset ID (referential). Use POST /api/v3/get-asset/by-search/repository to find assets.", "example": 67890 }, "class_id": { "type": "integer", "description": "Library ID. Use POST /api/v3/administration/classes/list to get available libraries.", "example": 4 } }, "required": [ "node_id", "asset_id", "class_id" ] } } } } } }, "/api/v3/token/get/": { "post": { "tags": [ "token" ], "summary": "Get JWT authentication token", "description": "## Purpose\n\nGenerates a JWT token for API authentication. Use login credentials to obtain a bearer token for subsequent API calls.\n\n## Constraints\n\n- Token lifetime: 1 hour\n- Maximum active tokens per account: 10\n- Tokens auto-expire after 1 hour\n\n## Usage\n\nInclude the token in subsequent requests:\n\n```\nAuthorization: Bearer \n```\n", "security": [], "responses": { "200": { "description": "Token generation 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": "JWT token generated successfully", "description": "Status message" }, "result": { "type": "object", "properties": { "jwt_token": { "type": "string", "example": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...", "description": "JWT token to use in Authorization header" }, "token_type": { "type": "string", "example": "Bearer", "description": "Token type for Authorization header" }, "expires_at": { "type": "string", "example": "2024-12-07T15:30:45+00:00", "description": "Token expiration date and time (ISO 8601 format)" }, "issued_at": { "type": "string", "example": "2024-12-07T14:30:45+00:00", "description": "Token creation date and time (ISO 8601 format)" }, "internal_token": { "type": "string", "example": "abc123def456...", "description": "Internal token for compatibility (deprecated)" } }, "required": [ "jwt_token", "token_type", "expires_at", "issued_at", "internal_token" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = error, 0 = authentication failed)" }, "status_message": { "type": "string", "example": "Invalid login or password", "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": { "l": { "type": "string", "description": "User login (username). Account must have API access permissions.", "example": "mylogin" }, "p": { "type": "string", "description": "User password. Use a service account for API integrations.", "example": "mypassword" }, "HTTP_REFERER": { "type": "string", "description": "Internal referer for authentication (delayedExecutor, API_REST, etc.)", "example": "API_REST-b47f1ad6b862bcff9b680f5cfa78a979" } }, "required": [ "l", "p" ] } } } } } }, "/api/v3/token/disable/": { "post": { "tags": [ "token" ], "summary": "Disable all active tokens", "description": "## Purpose\n\nInvalidates all active JWT tokens for the account.\n\n## Use Cases\n\n- Force re-authentication for all sessions\n- Reset sessions after security concerns\n- Clear tokens when limit (10) reached\n\n⚠️ All existing tokens will be immediately invalidated.\n", "security": [], "responses": { "200": { "description": "Token disabling 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": "5 tokens disabled", "description": "Number of tokens that were disabled" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array on success" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = error, 0 = authentication failed)" }, "status_message": { "type": "string", "example": "Invalid login or password", "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": { "l": { "type": "string", "description": "User login (username). Account must have API access permissions.", "example": "mylogin" }, "p": { "type": "string", "description": "User password. Use a service account for API integrations.", "example": "mypassword" } }, "required": [ "l", "p" ] } } } } } }, "/api/v3/token/info/": { "post": { "tags": [ "token" ], "summary": "Get current token information", "description": "## Purpose\n\nReturns metadata about the current JWT token (validity, issue date, expiration).\n\n## Use Cases\n\n- Verify authentication state\n- Check remaining token lifetime\n- Determine if token refresh is needed\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Token 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": "The JWT token is valid", "description": "Token validation message" }, "result": { "type": "object", "properties": { "token_type": { "type": "string", "example": "JWT", "description": "Type of the token" }, "user_id": { "type": "integer", "example": 1687, "description": "User ID associated with the token" }, "created_at": { "type": "string", "example": "2024-12-07T14:30:45+00:00", "description": "Token creation date and time (ISO 8601 format)" }, "expires_at": { "type": "string", "example": "2024-12-07T15:30:45+00:00", "description": "Token expiration date and time (ISO 8601 format)" }, "issued_at": { "type": "string", "example": "2024-12-07T14:30:45+00:00", "description": "Token issuance date and time (ISO 8601 format)" }, "not_before": { "type": "string", "nullable": true, "example": "2024-12-07T14:30:45+00:00", "description": "Token not valid before this date and time (ISO 8601 format)" }, "internal_token": { "type": "string", "example": "abc123def456...", "description": "Internal token identifier" } }, "required": [ "token_type", "user_id", "created_at", "expires_at", "issued_at", "internal_token" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = error)" }, "status_message": { "type": "string", "example": "Bearer token missing in Authorization header", "description": "Error message" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array on error" } }, "required": [ "status_code", "status_message", "result" ] } ] } } } } } } }, "/api/v3/types/full/": { "post": { "tags": [ "types" ], "summary": "Get all types with full details", "description": "## Purpose\n\nReturns all asset types for a class with complete configuration including permissions, statuses, and display settings.\n\n## Filtering\n\nUse `supertype_id` to filter by category (Record, Folder, Page, etc.).\n\n## Comparison\n\nUse `types/list` for simplified output (id, code, label, active status only).\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Asset type 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": "object", "properties": { "results_total": { "type": "integer", "example": 5, "description": "Total number of asset types returned" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 15, "description": "Type ID" }, "class_id": { "type": "integer", "example": 4, "description": "Associated class ID" }, "code": { "type": "string", "example": "my_type_code", "description": "Type code" }, "label": { "type": "string", "example": "Product category", "description": "Type label" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "tag1", "tag2" ], "description": "Array of tags (can be empty)" }, "manage_file": { "type": "boolean", "nullable": true, "example": true, "description": "Whether the type can load a preview file" }, "supertype_id": { "type": "integer", "nullable": true, "example": 1, "description": "Supertype ID" }, "supertype_label": { "type": "string", "nullable": true, "example": "Record", "description": "Supertype label" }, "active": { "type": "boolean", "example": true, "description": "Whether the type is active" }, "indexed": { "type": "boolean", "nullable": true, "example": true, "description": "Whether the type is indexed" }, "order": { "type": "integer", "nullable": true, "example": 1, "description": "Display order" }, "help": { "type": "string", "nullable": true, "example": "Help text for this type", "description": "Help text" }, "creation_status": { "type": "integer", "nullable": true, "example": 1149, "description": "Status at creation" }, "project_status": { "type": "integer", "nullable": true, "example": 1148, "description": "Status when adding project" }, "bundle_option": { "type": "integer", "nullable": true, "example": 3, "description": "Association type : linked asset or not" }, "display_link_tab": { "type": "boolean", "nullable": true, "example": true, "description": "Displaying \"links\" tab in the asset" }, "display_related_assets": { "type": "boolean", "nullable": true, "example": false, "description": "Displaying related assets" }, "font_awesome_code": { "type": "object", "nullable": true, "properties": { "code": { "type": "string", "nullable": true, "example": "fa-solid fa-file", "description": "Font-Awesome code" }, "color": { "type": "string", "nullable": true, "example": "#FF5722", "description": "Type color in hexadecimal" } }, "description": "Font-Awesome code" }, "not_logged": { "type": "boolean", "nullable": true, "example": true, "description": "Not logged" }, "not_exportable": { "type": "boolean", "nullable": true, "example": true, "description": "Not exportable" }, "dynamic_search": { "type": "integer", "nullable": true, "example": 0, "description": "Dynamic search" }, "image": { "type": "string", "nullable": true, "example": "", "description": "Image" }, "permissions": { "type": "object", "nullable": true, "additionalProperties": { "type": "object", "properties": { "label": { "type": "string", "example": "Group 1", "description": "User group label" }, "create": { "type": "boolean", "example": false, "description": "Create permission" }, "edit": { "type": "boolean", "example": false, "description": "Edit permission" }, "view": { "type": "boolean", "example": true, "description": "View permission" } }, "required": [ "label", "create", "edit", "view" ] }, "example": { "1557": { "label": "Afineo", "create": false, "edit": false, "view": true } }, "description": "Permissions by user group ID. Each key is a user group ID, and the value contains permissions (create, edit, view)" }, "available_statuses": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" }, "example": { "1149": "Archived", "1150": "Active" }, "description": "Available statuses for this type. Each key is a status ID, and the value is the status label" } }, "required": [ "id", "class_id", "code", "label", "tags", "supertype_id", "supertype_label", "active" ] }, "description": "Array of asset types objects" } }, "required": [ "results_total", "items" ] } }, "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 }, "supertype_id": { "type": "integer", "description": "Supertype ID : Groupe de fiches,Fiche,Dossier,Page,Publication,Workspace,Article,Variation de produit", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ], "example": "Groupe de fiches" } }, "required": [ "class_id" ] } } } } } }, "/api/v3/types/list/": { "post": { "tags": [ "types" ], "summary": "List types by class", "description": "## Purpose\n\nReturns simplified asset type list for a class (id, code, label, supertype, active status).\n\n## Filtering\n\nUse `supertype_id` to filter by category (Record, Folder, Page, etc.).\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Asset type 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": "object", "properties": { "results_total": { "type": "integer", "example": 5, "description": "Total number of asset types returned" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 15, "description": "Type ID" }, "class_id": { "type": "integer", "example": 4, "description": "Associated class ID" }, "code": { "type": "string", "example": "my_type_code", "description": "Type code" }, "label": { "type": "string", "example": "Product category", "description": "Type label" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "tag1", "tag2" ], "description": "Array of tags (can be empty)" }, "supertype_id": { "type": "integer", "nullable": true, "example": 1, "description": "Supertype ID" }, "supertype_label": { "type": "string", "nullable": true, "example": "Record", "description": "Supertype label" }, "active": { "type": "boolean", "example": true, "description": "Whether the type is active" } }, "required": [ "id", "class_id", "code", "label", "tags", "supertype_id", "supertype_label", "active" ] }, "description": "Array of asset types objects" } }, "required": [ "results_total", "items" ] } }, "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 }, "supertype_id": { "type": "integer", "description": "Supertype ID : Groupe de fiches,Fiche,Dossier,Page,Publication,Workspace,Article,Variation de produit", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ], "example": "Groupe de fiches" } }, "required": [ "class_id" ] } } } } } }, "/api/v3/types/get/": { "post": { "tags": [ "types" ], "summary": "Get asset type details", "description": "## Purpose\n\nReturns complete asset type configuration including permissions, statuses, display settings, and file management options.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Asset type 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" }, "result": { "type": "object", "properties": { "id": { "type": "integer", "example": 15, "description": "Type ID" }, "class_id": { "type": "integer", "example": 4, "description": "Associated class ID" }, "code": { "type": "string", "example": "my_type_code", "description": "Type code" }, "label": { "type": "string", "example": "Product category", "description": "Type label" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "tag1", "tag2" ], "description": "Array of tags (can be empty)" }, "manage_file": { "type": "boolean", "nullable": true, "example": true, "description": "Whether the type can load a preview file" }, "supertype_id": { "type": "integer", "nullable": true, "example": 1, "description": "Supertype ID" }, "supertype_label": { "type": "string", "nullable": true, "example": "Record", "description": "Supertype label" }, "active": { "type": "boolean", "example": true, "description": "Whether the type is active" }, "indexed": { "type": "boolean", "nullable": true, "example": true, "description": "Whether the type is indexed" }, "order": { "type": "integer", "nullable": true, "example": 1, "description": "Display order" }, "help": { "type": "string", "nullable": true, "example": "Help text for this type", "description": "Help text" }, "creation_status": { "type": "integer", "nullable": true, "example": 1149, "description": "Status at creation" }, "project_status": { "type": "integer", "nullable": true, "example": 1148, "description": "Status when adding project" }, "bundle_option": { "type": "integer", "nullable": true, "example": 3, "description": "Association type : linked asset or not" }, "display_link_tab": { "type": "boolean", "nullable": true, "example": true, "description": "Displaying \"links\" tab in the asset" }, "display_related_assets": { "type": "boolean", "nullable": true, "example": false, "description": "Displaying related assets" }, "font_awesome_code": { "type": "object", "nullable": true, "properties": { "code": { "type": "string", "nullable": true, "example": "fa-solid fa-file", "description": "Font-Awesome code" }, "color": { "type": "string", "nullable": true, "example": "#FF5722", "description": "Type color in hexadecimal" } }, "description": "Font-Awesome code" }, "not_logged": { "type": "boolean", "nullable": true, "example": true, "description": "Not logged" }, "not_exportable": { "type": "boolean", "nullable": true, "example": true, "description": "Not exportable" }, "dynamic_search": { "type": "integer", "nullable": true, "example": 0, "description": "Dynamic search" }, "image": { "type": "string", "nullable": true, "example": "", "description": "Image" }, "permissions": { "type": "object", "nullable": true, "additionalProperties": { "type": "object", "properties": { "label": { "type": "string", "example": "Group 1", "description": "User group label" }, "create": { "type": "boolean", "example": false, "description": "Create permission" }, "edit": { "type": "boolean", "example": false, "description": "Edit permission" }, "view": { "type": "boolean", "example": true, "description": "View permission" } }, "required": [ "label", "create", "edit", "view" ] }, "example": { "1557": { "label": "Afineo", "create": false, "edit": false, "view": true } }, "description": "Permissions by user group ID. Each key is a user group ID, and the value contains permissions (create, edit, view)" }, "available_statuses": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" }, "example": { "1149": "Archived", "1150": "Active" }, "description": "Available statuses for this type. Each key is a status ID, and the value is the status label" } }, "required": [ "id", "class_id", "code", "label", "tags", "supertype_id", "supertype_label", "active" ], "description": "Asset type 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 = 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": { "id": { "type": "integer", "description": "Asset type ID. Use POST /api/v3/types/list with class_id to get available asset types.", "example": 407 } }, "required": [ "id" ] } } } } } }, "/api/v3/types/statuses/": { "post": { "tags": [ "types" ], "summary": "Get type status assignments", "description": "## Purpose\n\nReturns available workflow statuses for an asset type (includes inherited statuses from supertype).\n\n## Requirement\n\nRequires extension: `ASSIGNMENT_STATUS_TYPES`. This extension must be enabled at the platform level by an administrator. If not enabled, the endpoint will return status_code=2 with message \"Extension not available\".\n\n## Handling Unavailability\n\nIf you receive status_code=2, the extension is not enabled and this endpoint cannot be used. Fall back to POST /api/v3/permissions/statuses/list to get statuses without type-level filtering.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Status assignments 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": "Empty string on success" }, "result": { "type": "object", "properties": { "results_total": { "type": "integer", "example": 3, "description": "Total number of statuses available for this type" }, "items": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "1149": "Archived", "1150": "Active" }, "description": "Available statuses for the type (includes inherited from supertype). Key is status ID, value is status label" } }, "required": [ "results_total", "items" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Extension Required Error", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = extension required or type not found)" }, "status_message": { "type": "string", "example": "This endpoint requires the ASSIGNMENT_STATUS_TYPES extension to be enabled", "description": "Error message about required extension or type not found" }, "result": { "type": "array", "items": { "type": "object" }, "example": [], "description": "Empty array on error" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Not Found Error", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = not found)" }, "status_message": { "type": "string", "example": "No status assignments found for asset type \"407\"", "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": "Asset type ID. Use POST /api/v3/types/list with class_id to get available asset types.", "example": 407 } }, "required": [ "id" ] } } } } } }, "/api/v3/types/update/": { "post": { "tags": [ "types" ], "summary": "Update an existing type in a library", "description": "## Purpose\n\nUpdates properties of an existing asset type (category). Only provided fields are modified — omitted fields remain unchanged.\n\n## What can be updated\n\n- Label, help text, icon, color\n- Active status, indexed, logging, exportability\n- File management, display options, bundle, dynamic search\n- Default statuses (creation, project)\n- Parent type, display order\n\n## What cannot be updated\n\n- `class_id` (immutable — the type belongs to a specific library)\n- `supertype_id` (immutable — changing supertype would break type hierarchy)\n\n## Important\n\nThe `id` parameter refers to the type ID, not the class ID. Use POST /api/v3/types/list with class_id to discover type IDs.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Type update 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": "Type updated successfully", "description": "Status message" }, "result": { "type": "object", "properties": { "id": { "type": "integer", "example": 42, "description": "Type ID" }, "class_id": { "type": "integer", "example": 4, "description": "Library ID" }, "label": { "type": "string", "example": "Product", "description": "Type label" }, "updated_fields": { "type": "array", "items": { "type": "string" }, "example": [ "label", "help", "icon" ], "description": "List of fields that were actually modified" } }, "required": [ "id", "class_id", "label", "updated_fields" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "enum": [ 2, 997 ], "example": 2, "description": "Status code (2 = validation error, 997 = insufficient permissions)" }, "status_message": { "type": "string", "example": "Type not found", "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": "Type ID to update. Use POST /api/v3/types/list with class_id to get available types.", "example": 42 }, "label": { "type": "string", "description": "New type label (display name)", "example": "Product" }, "help": { "type": "string", "description": "Type description/help text", "example": "Product type for catalog items" }, "icon": { "type": "string", "description": "FontAwesome icon class", "example": "fa-solid fa-box" }, "color": { "type": "string", "description": "Hex color code for the type icon", "example": "#FF5733" }, "active": { "type": "boolean", "description": "Whether the type is active", "example": true }, "indexed": { "type": "boolean", "description": "Whether the type is indexed for search", "example": true }, "not_logged": { "type": "boolean", "description": "Disable logging for records of this type", "example": false }, "not_exportable": { "type": "boolean", "description": "Prevent export of records of this type", "example": false }, "manage_file": { "type": "boolean", "description": "Enable file management for this type", "example": false }, "display_link_tab": { "type": "boolean", "description": "Display link tab in the type view", "example": false }, "bundle_option": { "type": "integer", "description": "Bundle association option: 1=simple bundle, 2=variant bundle, 3=kit bundle. Leave empty or omit if not applicable", "example": 1 }, "display_related_assets": { "type": "integer", "description": "Related assets display mode: 1=display related assets tab. Leave empty or omit if not applicable", "example": 1 }, "dynamic_search": { "type": "integer", "description": "Smart folder / dynamic search setting. Only applied when supertype is Folder (supertype_id=3). Silently ignored for other supertypes. 0=disabled, 1=enabled", "example": 0 }, "creation_status": { "type": "integer", "description": "Default status ID assigned when creating a new record of this type. Use POST /api/v3/types/statuses with the type ID to get available statuses", "example": 1 }, "project_status": { "type": "integer", "description": "Default status ID assigned when creating a new project of this type. Use POST /api/v3/types/statuses with the type ID to get available statuses", "example": 1 }, "parent_id": { "type": "integer", "description": "Parent type ID for nesting this type under another. Use POST /api/v3/types/list with class_id to get existing types. Must belong to the same library. Set to 0 to remove parent", "example": 15 }, "order": { "type": "integer", "description": "Display order position. Lower values appear first", "example": 1 } }, "required": [ "id" ] } } } } } }, "/api/v3/types/update-permissions/": { "post": { "tags": [ "types" ], "summary": "Update group permissions for a type", "description": "## Purpose\n\nManages group (LCA) permissions on an asset type. Controls which groups can create, edit, or view assets of this type. Type IDs are unique across all libraries.\n\n## Modes\n\n- **synchronize**: Replaces ALL permissions for the type. Groups not listed are removed. Use this to set the complete permission state.\n- **update**: Adds or modifies only the listed groups. Existing groups not mentioned are left unchanged. Recommended for incremental changes.\n- **delete**: Removes permissions for the listed groups. The `create`, `edit`, `view` fields are ignored in this mode.\n\n## Permission Hierarchy\n\nPermissions follow a logical hierarchy enforced server-side:\n- `create: true` automatically enables `edit` and `view`\n- `edit: true` automatically enables `view`\n- `view: false` automatically disables `create` and `edit`\n\n## Discovery Chain\n\n1. Get libraries: `POST /api/v3/administration/classes/list`\n2. Get types for a library: `POST /api/v3/types/list` with `class_id`\n3. Get available groups: `POST /api/v3/permissions/groups/list`\n4. Read current permissions: `POST /api/v3/types/get` with `id`\n\n## Common Errors\n\n| Error | Cause | Solution |\n|-------|-------|----------|\n| Type not found with id X | Invalid type ID | Use `POST /api/v3/types/list` with `class_id` to get valid IDs |\n| Group ID X does not exist | Invalid group_id | Use `POST /api/v3/permissions/groups/list` to get valid group IDs |\n| Cannot manage permissions on a duplicates handler type | Type is reserved for duplicates management | Choose a different type |\n| Not allowed operation | User lacks admin permission or `lca_manage_type_fiche` right | Requires admin-level API token |\n\n## Example Requests\n\n### Update specific groups\n```json\n{\"id\": 42, \"mode\": \"update\", \"permissions\": [{\"group_id\": 5, \"create\": true, \"edit\": true, \"view\": true}]}\n```\n\n### Synchronize all permissions (replaces everything)\n```json\n{\"id\": 42, \"mode\": \"synchronize\", \"permissions\": [{\"group_id\": 5, \"create\": true, \"edit\": true, \"view\": true}, {\"group_id\": 8, \"create\": false, \"edit\": true, \"view\": true}]}\n```\n\n### Delete group permissions\n```json\n{\"id\": 42, \"mode\": \"delete\", \"permissions\": [{\"group_id\": 8}]}\n```\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Returns the complete permission state after the operation, including all groups with their create/edit/view flags", "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": "Permissions updated successfully", "description": "Status message" }, "result": { "type": "object", "properties": { "id": { "type": "integer", "example": 42, "description": "Asset type ID" }, "mode": { "type": "string", "example": "update", "description": "Operation mode used" }, "affected_groups": { "type": "integer", "example": 2, "description": "Number of groups affected by the operation" }, "permissions": { "type": "array", "description": "Complete permission state after the operation", "items": { "type": "object", "properties": { "group_id": { "type": "integer", "description": "Permission group (LCA) ID" }, "label": { "type": "string", "description": "Group display name" }, "create": { "type": "boolean", "description": "Can create assets of this type" }, "edit": { "type": "boolean", "description": "Can edit assets of this type" }, "view": { "type": "boolean", "description": "Can view assets of this type" } } } } }, "required": [ "id", "mode", "affected_groups", "permissions" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = error)" }, "status_message": { "type": "string", "example": "Type not found", "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": "Asset type ID. First get a class_id from POST /api/v3/administration/classes/list, then use POST /api/v3/types/list with that class_id to discover type IDs.", "example": 42 }, "mode": { "type": "string", "description": "Operation mode. \"synchronize\": replaces ALL permissions (groups not listed are removed). \"update\": adds or modifies only listed groups (others unchanged). \"delete\": removes listed groups (create/edit/view fields ignored). Recommendation: use \"update\" for incremental changes, \"synchronize\" for full state management.", "enum": [ "synchronize", "update", "delete" ], "example": "update" }, "permissions": { "type": "array", "description": "Array of permission objects defining group-level access. In \"update\"/\"synchronize\" modes, each object requires group_id + create/edit/view booleans. In \"delete\" mode, only group_id is needed (other fields are ignored). (Array of objects - see example for structure)", "example": [ { "group_id": 5, "create": true, "edit": true, "view": true }, { "group_id": 8, "create": false, "edit": true, "view": true } ], "items": { "type": "object", "properties": { "group_id": { "type": "integer", "description": "Permission group (LCA) ID. Use POST /api/v3/permissions/groups/list to get available groups and their IDs." }, "create": { "type": "boolean", "description": "Can create assets of this type. Default: false. Ignored in delete mode." }, "edit": { "type": "boolean", "description": "Can edit assets of this type. Default: false. Ignored in delete mode." }, "view": { "type": "boolean", "description": "Can view assets of this type. Default: false. Ignored in delete mode." } }, "required": [ "group_id" ] } } }, "required": [ "id", "mode", "permissions" ] } } } } } }, "/api/v3/types/create/": { "post": { "tags": [ "types" ], "summary": "Create a new type in a library", "description": "## Purpose\n\nCreates a new asset type (category) in a library with full configuration. If a type with the same label already exists for the given supertype, it returns the existing type without creating a duplicate.\n\n## Required Parameters\n\n- `class_id`: Library where the type will be created\n- `label`: Display name for the type\n- `supertype_id`: Category of type\n\n## Optional Parameters\n\nAll other parameters are optional and allow full type configuration at creation time: icon, color, help text, visibility, export, logging, file management, etc.\n\n## Idempotent Behavior\n\nIf a type with the same label already exists in the same library and supertype, the endpoint returns the existing type with `created: false` instead of creating a duplicate. Optional parameters are NOT applied to existing types.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Type 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": "Type created successfully", "description": "Status message" }, "result": { "type": "object", "properties": { "id": { "type": "integer", "example": 42, "description": "Type ID" }, "class_id": { "type": "integer", "example": 4, "description": "Library ID" }, "label": { "type": "string", "example": "Product", "description": "Type label" }, "supertype_id": { "type": "integer", "example": 2, "description": "Supertype ID" }, "created": { "type": "boolean", "example": true, "description": "True if newly created, false if already existed" } }, "required": [ "id", "class_id", "label", "supertype_id", "created" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code (2 = error)" }, "status_message": { "type": "string", "example": "Type creation failed", "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 }, "label": { "type": "string", "description": "Type label (display name)", "example": "Product" }, "supertype_id": { "type": "integer", "description": "Supertype ID : 1=Groupe de fiches, 2=Fiche, 3=Dossier, 4=Page, 5=Publication, 6=Workspace, 7=Article, 8=Variation de produit", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8 ], "example": 2 }, "help": { "type": "string", "description": "Type description/help text", "example": "Product type for catalog items" }, "icon": { "type": "string", "description": "FontAwesome icon class. Overrides the supertype default icon", "example": "fa-solid fa-box" }, "color": { "type": "string", "description": "Hex color code for the type icon. Overrides the supertype default color", "example": "#FF5733" }, "active": { "type": "boolean", "description": "Whether the type is active. Default: true", "example": true }, "indexed": { "type": "boolean", "description": "Whether the type is indexed for search. Default: true", "example": true }, "not_logged": { "type": "boolean", "description": "Disable logging for records of this type. Default: false", "example": false }, "not_exportable": { "type": "boolean", "description": "Prevent export of records of this type. Default: false", "example": false }, "manage_file": { "type": "boolean", "description": "Enable file management for this type. Default: false", "example": false }, "display_link_tab": { "type": "boolean", "description": "Display link tab in the type view. Default: false", "example": false }, "bundle_option": { "type": "integer", "description": "Bundle association option: 1=simple bundle, 2=variant bundle, 3=kit bundle. Leave empty or omit if not applicable", "example": 1 }, "display_related_assets": { "type": "integer", "description": "Related assets display mode: 1=display related assets tab. Leave empty or omit if not applicable", "example": 1 }, "dynamic_search": { "type": "integer", "description": "Smart folder / dynamic search setting. Only applied when supertype_id=3 (Folder). Silently ignored for other supertypes. 0=disabled, 1=enabled", "example": 0 }, "creation_status": { "type": "integer", "description": "Default status ID assigned when creating a new record of this type. Use POST /api/v3/types/statuses with the type ID to get available statuses. Statuses are inherited from the supertype", "example": 1 }, "project_status": { "type": "integer", "description": "Default status ID assigned when creating a new project of this type. Use POST /api/v3/types/statuses with the type ID to get available statuses. Statuses are inherited from the supertype", "example": 1 }, "parent_id": { "type": "integer", "description": "Parent type ID for nesting this type under another. Use POST /api/v3/types/list with class_id to get existing types. Must belong to the same library", "example": 15 }, "order": { "type": "integer", "description": "Display order position. Lower values appear first", "example": 1 } }, "required": [ "class_id", "label", "supertype_id" ] } } } } } }, "/api/v3/types/assign-attributes/": { "post": { "tags": [ "types" ], "summary": "Sync attribute assignments for a type (add, update, remove)", "description": "## Purpose\n\nSynchronizes which attributes are assigned to a record type, along with per-attribute display options. Send the **complete desired state** for this type: the endpoint computes a diff and applies additions, updates, and removals automatically.\n\n## Library Context\n\nThe library (class_id) is automatically derived from the type — no class_id parameter is required. To discover the class_id of a type, call `POST /api/v3/types/get` with the type `id` — the response includes `class_id`.\n\n## Sync Behavior\n\n- Attribute in the list but NOT currently assigned → **added**\n- Attribute currently assigned but NOT in the list → **removed**\n- Attribute in both → **updated** if options differ, **unchanged** if identical\n\nSending `assignments: []` removes **all** attributes from the type. Use with care.\n\n## Per-attribute options\n\nEach assignment entry supports two optional display options:\n\n**`editability`** — controls editability of the attribute value for this type:\n- `\"default\"` (default) — inherits the attribute's global editability setting\n- `\"read_only\"` — value is always read-only for this type, regardless of the global setting\n- `\"editable\"` — value is always editable for this type, regardless of the global setting\n\nOmitting `editability` is equivalent to `\"default\"`.\n\n**`hidden`** — hides the attribute in the interface for this type:\n- `false` (default) — attribute is visible\n- `true` — attribute is hidden in the interface for this type\n\nOmitting `hidden` is equivalent to `false`.\n\n## Partial Failures\n\nInvalid entries (unknown attribute ID or code, missing fields) do NOT fail the whole request — valid entries are still applied and `status_code` remains 1. All failures are reported in `result.errors`.\n\n## Accepts IDs or Codes\n\n`attribute`: integer (attribute ID) or string (attribute code, case-insensitive). To list available attributes for a type's library, call `POST /api/v3/attributes/list` with the `class_id` returned by `POST /api/v3/types/get`.\n\n## Related Endpoints\n\n- `attributes/assign-types` — inverse: given one attribute, sync all its types\n- `attributes/list` — list available attributes (requires class_id; use `types/get` to retrieve it)\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Sync result response", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Success Response", "properties": { "status_code": { "type": "integer", "example": 1, "description": "Always 1 for this endpoint, even when some entries failed (partial failures are reported in result.errors, not via status_code)" }, "status_message": { "type": "string", "example": "3 added, 1 updated, 1 removed", "description": "Summary of changes (e.g. \"3 added, 1 updated, 1 removed\"). Suffix \"(N error(s))\" is appended when result.errors is non-empty. \"No changes\" when nothing changed." }, "result": { "type": "object", "properties": { "type_id": { "type": "integer", "example": 12, "description": "Type ID" }, "attributes": { "type": "array", "description": "Per-attribute action details. Only covers attributes that were in the request or currently assigned — not all attributes in the library.", "items": { "type": "object", "properties": { "attribute_id": { "type": "integer", "example": 456, "description": "Resolved attribute ID" }, "action": { "type": "string", "enum": [ "added", "updated", "unchanged", "removed" ], "example": "added", "description": "Operation applied to this attribute assignment" }, "editability": { "type": "string", "enum": [ "default", "read_only", "editable" ], "example": "default", "description": "Reflects the value sent in the request (not the stored value). Absent when action is \"removed\"." }, "hidden": { "type": "boolean", "example": false, "description": "Reflects the value sent in the request (not the stored value). Absent when action is \"removed\"." } } } }, "total_added": { "type": "integer", "example": 3 }, "total_updated": { "type": "integer", "example": 1 }, "total_removed": { "type": "integer", "example": 1 }, "cache_refreshed": { "type": "boolean", "example": true }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Per-entry errors that did not block execution. Valid entries are still applied.", "example": [ "Attribute not found: code_inexistant" ] } } } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 2, "description": "Status code 2 when type not found" }, "status_message": { "type": "string", "example": "Type \"999\" does not exist", "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": "Type ID. Use POST /api/v3/types/list with class_id to get available type IDs.", "example": 12 }, "assignments": { "type": "array", "description": "Complete desired attribute state for this type. Each entry must have \"attribute\" (integer ID or string code). Optional: \"editability\" (\"default\", \"read_only\", \"editable\") and \"hidden\" (boolean). WARNING: this is a SYNC operation — attributes not in this list will be REMOVED. (Array of objects - see example for structure)", "example": [ { "attribute": "datedecreation", "editability": "editable", "hidden": false }, { "attribute": 456, "editability": "default", "hidden": true } ], "items": { "type": "object", "properties": { "attribute": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Attribute ID (integer) or attribute code (string, case-insensitive). Use POST /api/v3/attributes/list with class_id to discover.", "example": "datedecreation" }, "editability": { "type": "string", "description": "Editability for this attribute on this type. Defaults to \"default\" (inherits global setting).", "enum": [ "default", "read_only", "editable" ], "example": "editable" }, "hidden": { "type": "boolean", "description": "Hide attribute in interface for this type. Defaults to false.", "example": false } }, "required": [ "attribute" ], "title": "Item" } } }, "required": [ "id", "assignments" ] } } } } } }, "/api/v3/workflows/list/node/": { "post": { "tags": [ "workflows" ], "summary": "List workflows by project node", "description": "## Purpose\n\nReturns simplified workflow list for a specific project node (id, code, label, types).\n\n## Node vs Repository Context\n\n- **Node** (`/node/`): Workflows configured for a specific project. Use when working within a project context (e.g., managing assets in a publication project).\n- **Repository** (`/repository/`): Workflows configured at the master repository level (root, no project). Use POST /api/v3/workflows/list/repository/ instead.\n\n## When to Use\n\n- Use to discover available workflows for a project before changing asset workflow status\n- The workflow `id` returned is used in POST /api/v3/recordAsset/update-status/node/\n- Use POST /api/v3/workflows/get with a workflow ID to see complete step configuration (step groups, actions, contributors)\n\n## Filtering\n\nUse `filters.type_id` to filter by asset type. If a workflow has no explicit types, it matches via supertype fallback.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Workflow 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": "object", "properties": { "results_total": { "type": "integer", "example": 2, "description": "Total number of workflows returned" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 15, "description": "Workflow ID" }, "code": { "type": "string", "example": "", "description": "Workflow code" }, "label": { "type": "string", "example": "Workflow validation", "description": "Workflow label" }, "class_id": { "type": "integer", "example": 4, "description": "Class ID" }, "project_node_id": { "type": "integer", "example": 1234, "description": "Project node ID" }, "project_label": { "type": "string", "example": "My Project", "description": "Project label" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "validation", "review" ], "description": "Array of tags (can be empty)" }, "supertype": { "type": "object", "properties": { "id": { "type": "integer", "example": 3, "description": "Supertype ID" }, "label": { "type": "string", "example": "Products", "description": "Supertype label" } }, "required": [ "id", "label" ], "description": "Supertype information" }, "types": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 42, "description": "Type ID" }, "label": { "type": "string", "example": "Product", "description": "Type label" } }, "required": [ "id", "label" ] }, "description": "Array of asset types associated with this workflow" } }, "required": [ "id", "code", "label", "class_id", "project_node_id", "project_label", "tags", "supertype", "types" ] }, "description": "Array of workflow objects" } }, "required": [ "results_total", "items" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = error, 0 = 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": { "project_node_id": { "type": "integer", "description": "Project node ID. Use POST /api/v3/projects/list with class_id to get available projects.", "example": 1234 }, "class_id": { "type": "integer", "description": "Library ID. Use POST /api/v3/administration/classes/list to get available libraries.", "example": 4 }, "filters": { "type": "object", "description": "Optional filters object. Currently supports filtering by type_id only.", "example": { "type_id": 42 }, "properties": { "type_id": { "type": "integer", "description": "Filter workflows by type ID. Use POST /api/v3/types/list with class_id to get valid type IDs. Returns workflows that have this type in their types array, or if types is empty, have a supertype matching the type's supertype.", "example": 42 } } } }, "required": [ "project_node_id", "class_id" ] } } } } } }, "/api/v3/workflows/list/repository/": { "post": { "tags": [ "workflows" ], "summary": "List workflows for repository", "description": "## Purpose\n\nReturns simplified workflow list for the master repository (automatically retrieved by class_id).\n\n## Node vs Repository Context\n\n- **Repository** (`/repository/`): Workflows configured at the master repository level (root project, project_node_id=0). These apply to all assets at the library level, outside of any specific project context.\n- **Node** (`/node/`): Workflows for a specific project. Use POST /api/v3/workflows/list/node/ with project_node_id instead.\n\n## When to Use\n\n- Use to discover available workflows for master data (repository context)\n- The workflow `id` returned is used in POST /api/v3/recordAsset/update-status/repository/\n- Use POST /api/v3/workflows/get with a workflow ID to see complete step configuration\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Workflow 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": "object", "properties": { "results_total": { "type": "integer", "example": 2, "description": "Total number of workflows returned" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 15, "description": "Workflow ID" }, "code": { "type": "string", "example": "", "description": "Workflow code" }, "label": { "type": "string", "example": "Workflow validation", "description": "Workflow label" }, "class_id": { "type": "integer", "example": 4, "description": "Class ID" }, "project_node_id": { "type": "integer", "example": 0, "description": "Project node ID (0 for repository project)" }, "project_label": { "type": "string", "example": "Repository Project", "description": "Project label" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "validation", "review" ], "description": "Array of tags (can be empty)" }, "supertype": { "type": "object", "properties": { "id": { "type": "integer", "example": 3, "description": "Supertype ID" }, "label": { "type": "string", "example": "Products", "description": "Supertype label" } }, "required": [ "id", "label" ], "description": "Supertype information" }, "types": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 42, "description": "Type ID" }, "label": { "type": "string", "example": "Product", "description": "Type label" } }, "required": [ "id", "label" ] }, "description": "Array of asset types associated with this workflow" } }, "required": [ "id", "code", "label", "class_id", "project_node_id", "project_label", "tags", "supertype", "types" ] }, "description": "Array of workflow objects" } }, "required": [ "results_total", "items" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = error, 0 = not found)" }, "status_message": { "type": "string", "example": "Repository 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": { "class_id": { "type": "integer", "description": "Library ID. Use POST /api/v3/administration/classes/list to get available libraries.", "example": 4 }, "filters": { "type": "object", "description": "Optional filters object. Currently supports filtering by type_id only.", "example": { "type_id": 42 }, "properties": { "type_id": { "type": "integer", "description": "Filter workflows by type ID. Use POST /api/v3/types/list with class_id to get valid type IDs. Returns workflows that have this type in their types array, or if types is empty, have a supertype matching the type's supertype.", "example": 42 } } } }, "required": [ "class_id" ] } } } } } }, "/api/v3/workflows/get/": { "post": { "tags": [ "workflows" ], "summary": "Get workflow details", "description": "## Purpose\n\nReturns complete workflow configuration including step groups hierarchy, steps with their actions, contributors, completeness rules, and notification settings.\n\n## When to Use\n\n- Use after POST /api/v3/workflows/list/repository/ or POST /api/v3/workflows/list/node/ to get full details of a workflow\n- Check `configuration.step_groups[].steps[]` to understand the workflow progression\n- Check each step's `actions` to see available transitions (validate, reject, submit)\n- Check `contributors` per step to see which user groups can act\n- Check `completeness` to understand automatic transitions based on data completeness\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Workflow 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" }, "result": { "type": "object", "properties": { "id": { "type": "integer", "example": 15, "description": "Workflow ID" }, "code": { "type": "string", "example": "", "description": "Workflow code" }, "label": { "type": "string", "example": "Workflow validation", "description": "Workflow label" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "validation", "review" ], "description": "Array of tags (can be empty)" }, "class_id": { "type": "integer", "example": 4, "description": "Associated class ID" }, "project_node_id": { "type": "integer", "example": 1234, "description": "Project node ID (0 for repository project)" }, "project_label": { "type": "string", "example": "My Project", "description": "Project label" }, "started": { "type": "boolean", "example": true, "description": "Whether the workflow is started" }, "filters": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "attribute_id": { "type": "integer", "example": 123, "description": "Attribute ID. Use POST /api/v3/attributes/list with class_id to get available attributes." }, "attribute_label": { "type": "string", "example": "Status", "description": "Attribute label" }, "value": { "type": "string", "example": "active", "description": "Filter value" } } }, "description": "Workflow filters (array of filter objects or null)" }, "supertype": { "type": "object", "properties": { "id": { "type": "integer", "example": 3, "description": "Supertype ID" }, "label": { "type": "string", "example": "Products", "description": "Supertype label" } }, "required": [ "id", "label" ], "description": "Supertype information" }, "types": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 42, "description": "Type ID" }, "label": { "type": "string", "example": "Product", "description": "Type label" } }, "required": [ "id", "label" ] }, "description": "Array of asset types associated with this workflow" }, "configuration": { "type": "object", "properties": { "step_groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1, "description": "Step group ID" }, "label": { "type": "string", "example": "Validation", "description": "Step group label" }, "order": { "type": "integer", "example": 1, "description": "Display order" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 101, "description": "Step ID" }, "label": { "type": "string", "example": "Draft", "description": "Step label" }, "order": { "type": "integer", "example": 1, "description": "Display order" }, "color": { "type": "string", "nullable": true, "example": "#28a745", "description": "Step color" }, "start": { "type": "boolean", "example": false, "description": "Whether this is a start step" }, "notification": { "type": "object", "nullable": true, "properties": { "mail_template_id": { "type": "integer", "example": 5, "description": "Mail template ID" }, "mail_template_label": { "type": "string", "example": "Validation notification", "description": "Mail template label" } }, "description": "Notification configuration (null if not configured)" }, "delay_days": { "type": "integer", "nullable": true, "example": 7, "description": "Delay in days for the step" }, "contributors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 5, "description": "Contributor group ID" }, "label": { "type": "string", "example": "Validation Group", "description": "Contributor group label" } }, "required": [ "id", "label" ] }, "description": "Array of contributors for this step" }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 201, "description": "Action ID" }, "label": { "type": "string", "example": "Validate", "description": "Action label" }, "goto_step": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 102, "description": "Destination step ID" }, "label": { "type": "string", "example": "Validated", "description": "Destination step label" } }, "required": [ "id", "label" ], "description": "Destination step (null if no destination)" }, "mode": { "type": "string", "enum": [ "send_the_brief", "submit", "reject", "validate" ], "example": "validate", "description": "Action mode (send_the_brief, submit, reject or validate)" }, "display_if_completeness": { "type": "boolean", "example": false, "description": "Display button only if all completeness attributes are filled" } }, "required": [ "id", "label", "mode", "display_if_completeness" ] }, "description": "Array of actions for this step" }, "completeness": { "type": "object", "nullable": true, "properties": { "attributes": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" }, "example": { "123": "Attribute Label", "456": "Other Attribute" }, "description": "Map of attribute IDs to their labels" }, "automate_goto_step": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 102, "description": "Automatic transition step ID when complete" }, "label": { "type": "string", "example": "Validate", "description": "Automatic transition step label when complete" } }, "required": [ "id", "label" ], "description": "Automatic step transition when completeness is reached" } }, "description": "Completeness configuration (null if not configured)" }, "hotfolder": { "type": "object", "nullable": true, "properties": { "action_on_update": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 201, "description": "Action ID to execute on update" }, "label": { "type": "string", "example": "Validate", "description": "Action label" } }, "required": [ "id", "label" ], "description": "Action to execute when hotfolder is updated (null for no automatic step change)" }, "create_version": { "type": "boolean", "example": true, "description": "Whether to create a version on update" } }, "description": "Hotfolder configuration (null if not configured or not active)" }, "status_piloting_view": { "type": "object", "properties": { "status": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "example": "1234", "description": "Status id" }, "label": { "type": "string", "nullable": true, "example": "Admin Status", "description": "Status label" } }, "required": [ "id" ], "description": "Status configuration (null if not configured)" }, "default_view": { "type": "string", "nullable": true, "enum": [ "default", "completeness", "list" ], "example": "completeness", "description": "Default view mode (default, completeness, or list)" }, "children_piloting": { "type": "object", "nullable": true, "oneOf": [ { "type": "object", "title": "Workflow Type", "properties": { "type": { "type": "string", "enum": [ "workflow" ], "example": "workflow", "description": "Children piloting type" }, "items": { "type": "array", "items": { "type": "object", "properties": { "workflow": { "type": "object", "properties": { "id": { "type": "integer", "example": 15, "description": "Target workflow ID" }, "label": { "type": "string", "nullable": true, "example": "Child Workflow", "description": "Target workflow label" } }, "required": [ "id" ] }, "step": { "type": "object", "properties": { "id": { "type": "integer", "example": 101, "description": "Target step ID" }, "label": { "type": "string", "nullable": true, "example": "Draft", "description": "Target step label" } }, "required": [ "id" ] } }, "required": [ "workflow", "step" ] }, "description": "Array of workflow step configurations" } }, "required": [ "type", "items" ] }, { "type": "object", "title": "Status Type", "properties": { "type": { "type": "string", "enum": [ "status" ], "example": "status", "description": "Children piloting type" }, "items": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "object", "properties": { "id": { "type": "integer", "example": 123, "description": "Status ID" }, "label": { "type": "string", "nullable": true, "example": "Active", "description": "Status label" } }, "required": [ "id" ] }, "supertypes": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 3, "description": "Supertype ID" }, "label": { "type": "string", "nullable": true, "example": "Products", "description": "Supertype label" } }, "required": [ "id" ] }, "description": "Array of supertypes (null if not configured)" }, "types": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 42, "description": "Type ID" }, "label": { "type": "string", "nullable": true, "example": "Product", "description": "Type label" } }, "required": [ "id" ] }, "description": "Array of types (null if not configured)" } }, "required": [ "status" ] }, "description": "Array of status configurations" } }, "required": [ "type", "items" ] } ], "description": "Children piloting configuration (null if not configured)" } }, "description": "Status, piloting and view configuration" }, "reminder": { "type": "object", "nullable": true, "properties": { "days_before": { "type": "integer", "example": 7, "description": "Days before deadline to send notification" }, "recurrence_days": { "type": "integer", "nullable": true, "example": 1, "description": "Recurrence interval in days for notifications" } }, "description": "Reminder configuration (null if not configured)" } }, "required": [ "id", "label", "order", "start", "contributors", "actions", "status_piloting_view" ] }, "description": "Array of steps in this group" } }, "required": [ "id", "label", "order", "steps" ] }, "description": "Array of step groups containing steps with their nested data" } }, "required": [ "step_groups" ], "description": "Workflow configuration containing step groups hierarchy" } }, "required": [ "id", "code", "label", "class_id", "project_node_id", "project_label", "tags", "supertype", "types", "started", "configuration" ], "description": "Complete workflow information with hierarchical structure" } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = error, 0 = not found)" }, "status_message": { "type": "string", "example": "Workflow 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": "Workflow ID. Use POST /api/v3/workflows/list/repository/ (for master data) or POST /api/v3/workflows/list/node/ (for project context) to get available workflows.", "example": 15 } }, "required": [ "id" ] } } } } } }, "/api/v3/workflows/full/node/": { "post": { "tags": [ "workflows" ], "summary": "Get full workflows for project node", "description": "## Purpose\n\nReturns all workflows for a project node with complete configuration details.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Workflow list with complete 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" }, "result": { "type": "object", "properties": { "results_total": { "type": "integer", "example": 2, "description": "Total number of workflows returned" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 15, "description": "Workflow ID" }, "code": { "type": "string", "example": "", "description": "Workflow code" }, "label": { "type": "string", "example": "Workflow validation", "description": "Workflow label" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "validation", "review" ], "description": "Array of tags (can be empty)" }, "class_id": { "type": "integer", "example": 4, "description": "Associated class ID" }, "project_node_id": { "type": "integer", "example": 1234, "description": "Project node ID (0 for repository project)" }, "project_label": { "type": "string", "example": "My Project", "description": "Project label" }, "started": { "type": "boolean", "example": true, "description": "Whether the workflow is started" }, "filters": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "attribute_id": { "type": "integer", "example": 123, "description": "Attribute ID. Use POST /api/v3/attributes/list with class_id to get available attributes." }, "attribute_label": { "type": "string", "example": "Status", "description": "Attribute label" }, "value": { "type": "string", "example": "active", "description": "Filter value" } } }, "description": "Workflow filters (array of filter objects or null)" }, "supertype": { "type": "object", "properties": { "id": { "type": "integer", "example": 3, "description": "Supertype ID" }, "label": { "type": "string", "example": "Products", "description": "Supertype label" } }, "required": [ "id", "label" ], "description": "Supertype information" }, "types": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 42, "description": "Type ID" }, "label": { "type": "string", "example": "Product", "description": "Type label" } }, "required": [ "id", "label" ] }, "description": "Array of asset types associated with this workflow" }, "configuration": { "type": "object", "properties": { "step_groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1, "description": "Step group ID" }, "label": { "type": "string", "example": "Validation", "description": "Step group label" }, "order": { "type": "integer", "example": 1, "description": "Display order" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 101, "description": "Step ID" }, "label": { "type": "string", "example": "Draft", "description": "Step label" }, "order": { "type": "integer", "example": 1, "description": "Display order" }, "color": { "type": "string", "nullable": true, "example": "#28a745", "description": "Step color" }, "start": { "type": "boolean", "example": false, "description": "Whether this is a start step" }, "notification": { "type": "object", "nullable": true, "properties": { "mail_template_id": { "type": "integer", "example": 5, "description": "Mail template ID" }, "mail_template_label": { "type": "string", "example": "Validation notification", "description": "Mail template label" } }, "description": "Notification configuration (null if not configured)" }, "delay_days": { "type": "integer", "nullable": true, "example": 7, "description": "Delay in days for the step" }, "contributors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 5, "description": "Contributor group ID" }, "label": { "type": "string", "example": "Validation Group", "description": "Contributor group label" } }, "required": [ "id", "label" ] }, "description": "Array of contributors for this step" }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 201, "description": "Action ID" }, "label": { "type": "string", "example": "Validate", "description": "Action label" }, "goto_step": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 102, "description": "Destination step ID" }, "label": { "type": "string", "example": "Validated", "description": "Destination step label" } }, "required": [ "id", "label" ], "description": "Destination step (null if no destination)" }, "mode": { "type": "string", "enum": [ "send_the_brief", "submit", "reject", "validate" ], "example": "validate", "description": "Action mode (send_the_brief, submit, reject or validate)" }, "display_if_completeness": { "type": "boolean", "example": false, "description": "Display button only if all completeness attributes are filled" } }, "required": [ "id", "label", "mode", "display_if_completeness" ] }, "description": "Array of actions for this step" }, "completeness": { "type": "object", "nullable": true, "properties": { "attributes": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" }, "example": { "123": "Attribute Label", "456": "Other Attribute" }, "description": "Map of attribute IDs to their labels" }, "automate_goto_step": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 102, "description": "Automatic transition step ID when complete" }, "label": { "type": "string", "example": "Validate", "description": "Automatic transition step label when complete" } }, "required": [ "id", "label" ], "description": "Automatic step transition when completeness is reached" } }, "description": "Completeness configuration (null if not configured)" }, "hotfolder": { "type": "object", "nullable": true, "properties": { "action_on_update": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 201, "description": "Action ID to execute on update" }, "label": { "type": "string", "example": "Validate", "description": "Action label" } }, "required": [ "id", "label" ], "description": "Action to execute when hotfolder is updated (null for no automatic step change)" }, "create_version": { "type": "boolean", "example": true, "description": "Whether to create a version on update" } }, "description": "Hotfolder configuration (null if not configured or not active)" }, "status_piloting_view": { "type": "object", "properties": { "status": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "example": "1234", "description": "Status id" }, "label": { "type": "string", "nullable": true, "example": "Admin Status", "description": "Status label" } }, "required": [ "id" ], "description": "Status configuration (null if not configured)" }, "default_view": { "type": "string", "nullable": true, "enum": [ "default", "completeness", "list" ], "example": "completeness", "description": "Default view mode (default, completeness, or list)" }, "children_piloting": { "type": "object", "nullable": true, "oneOf": [ { "type": "object", "title": "Workflow Type", "properties": { "type": { "type": "string", "enum": [ "workflow" ], "example": "workflow", "description": "Children piloting type" }, "items": { "type": "array", "items": { "type": "object", "properties": { "workflow": { "type": "object", "properties": { "id": { "type": "integer", "example": 15, "description": "Target workflow ID" }, "label": { "type": "string", "nullable": true, "example": "Child Workflow", "description": "Target workflow label" } }, "required": [ "id" ] }, "step": { "type": "object", "properties": { "id": { "type": "integer", "example": 101, "description": "Target step ID" }, "label": { "type": "string", "nullable": true, "example": "Draft", "description": "Target step label" } }, "required": [ "id" ] } }, "required": [ "workflow", "step" ] }, "description": "Array of workflow step configurations" } }, "required": [ "type", "items" ] }, { "type": "object", "title": "Status Type", "properties": { "type": { "type": "string", "enum": [ "status" ], "example": "status", "description": "Children piloting type" }, "items": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "object", "properties": { "id": { "type": "integer", "example": 123, "description": "Status ID" }, "label": { "type": "string", "nullable": true, "example": "Active", "description": "Status label" } }, "required": [ "id" ] }, "supertypes": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 3, "description": "Supertype ID" }, "label": { "type": "string", "nullable": true, "example": "Products", "description": "Supertype label" } }, "required": [ "id" ] }, "description": "Array of supertypes (null if not configured)" }, "types": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 42, "description": "Type ID" }, "label": { "type": "string", "nullable": true, "example": "Product", "description": "Type label" } }, "required": [ "id" ] }, "description": "Array of types (null if not configured)" } }, "required": [ "status" ] }, "description": "Array of status configurations" } }, "required": [ "type", "items" ] } ], "description": "Children piloting configuration (null if not configured)" } }, "description": "Status, piloting and view configuration" }, "reminder": { "type": "object", "nullable": true, "properties": { "days_before": { "type": "integer", "example": 7, "description": "Days before deadline to send notification" }, "recurrence_days": { "type": "integer", "nullable": true, "example": 1, "description": "Recurrence interval in days for notifications" } }, "description": "Reminder configuration (null if not configured)" } }, "required": [ "id", "label", "order", "start", "contributors", "actions", "status_piloting_view" ] }, "description": "Array of steps in this group" } }, "required": [ "id", "label", "order", "steps" ] }, "description": "Array of step groups containing steps with their nested data" } }, "required": [ "step_groups" ], "description": "Workflow configuration containing step groups hierarchy" } }, "required": [ "id", "code", "label", "class_id", "project_node_id", "project_label", "tags", "supertype", "types", "started", "configuration" ], "description": "Complete workflow information with hierarchical structure" }, "description": "Array of workflow objects with complete information" } }, "required": [ "results_total", "items" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = error, 0 = 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": { "project_node_id": { "type": "integer", "description": "Project node ID. Use POST /api/v3/projects/list with class_id to get available projects.", "example": 1234 }, "class_id": { "type": "integer", "description": "Library ID. Use POST /api/v3/administration/classes/list to get available libraries.", "example": 4 }, "filters": { "type": "object", "description": "Optional filters object. Currently supports filtering by type_id only.", "example": { "type_id": 42 }, "properties": { "type_id": { "type": "integer", "description": "Filter workflows by type ID. Use POST /api/v3/types/list with class_id to get valid type IDs. Returns workflows that have this type in their types array, or if types is empty, have a supertype matching the type's supertype.", "example": 42 } } } }, "required": [ "project_node_id", "class_id" ] } } } } } }, "/api/v3/workflows/full/repository/": { "post": { "tags": [ "workflows" ], "summary": "Get full workflows for repository", "description": "## Purpose\n\nReturns all workflows for the repository project with complete configuration details.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Workflow list with complete 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" }, "result": { "type": "object", "properties": { "results_total": { "type": "integer", "example": 2, "description": "Total number of workflows returned" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 15, "description": "Workflow ID" }, "code": { "type": "string", "example": "", "description": "Workflow code" }, "label": { "type": "string", "example": "Workflow validation", "description": "Workflow label" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "validation", "review" ], "description": "Array of tags (can be empty)" }, "class_id": { "type": "integer", "example": 4, "description": "Associated class ID" }, "project_node_id": { "type": "integer", "example": 1234, "description": "Project node ID (0 for repository project)" }, "project_label": { "type": "string", "example": "My Project", "description": "Project label" }, "started": { "type": "boolean", "example": true, "description": "Whether the workflow is started" }, "filters": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "attribute_id": { "type": "integer", "example": 123, "description": "Attribute ID. Use POST /api/v3/attributes/list with class_id to get available attributes." }, "attribute_label": { "type": "string", "example": "Status", "description": "Attribute label" }, "value": { "type": "string", "example": "active", "description": "Filter value" } } }, "description": "Workflow filters (array of filter objects or null)" }, "supertype": { "type": "object", "properties": { "id": { "type": "integer", "example": 3, "description": "Supertype ID" }, "label": { "type": "string", "example": "Products", "description": "Supertype label" } }, "required": [ "id", "label" ], "description": "Supertype information" }, "types": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 42, "description": "Type ID" }, "label": { "type": "string", "example": "Product", "description": "Type label" } }, "required": [ "id", "label" ] }, "description": "Array of asset types associated with this workflow" }, "configuration": { "type": "object", "properties": { "step_groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1, "description": "Step group ID" }, "label": { "type": "string", "example": "Validation", "description": "Step group label" }, "order": { "type": "integer", "example": 1, "description": "Display order" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 101, "description": "Step ID" }, "label": { "type": "string", "example": "Draft", "description": "Step label" }, "order": { "type": "integer", "example": 1, "description": "Display order" }, "color": { "type": "string", "nullable": true, "example": "#28a745", "description": "Step color" }, "start": { "type": "boolean", "example": false, "description": "Whether this is a start step" }, "notification": { "type": "object", "nullable": true, "properties": { "mail_template_id": { "type": "integer", "example": 5, "description": "Mail template ID" }, "mail_template_label": { "type": "string", "example": "Validation notification", "description": "Mail template label" } }, "description": "Notification configuration (null if not configured)" }, "delay_days": { "type": "integer", "nullable": true, "example": 7, "description": "Delay in days for the step" }, "contributors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 5, "description": "Contributor group ID" }, "label": { "type": "string", "example": "Validation Group", "description": "Contributor group label" } }, "required": [ "id", "label" ] }, "description": "Array of contributors for this step" }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 201, "description": "Action ID" }, "label": { "type": "string", "example": "Validate", "description": "Action label" }, "goto_step": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 102, "description": "Destination step ID" }, "label": { "type": "string", "example": "Validated", "description": "Destination step label" } }, "required": [ "id", "label" ], "description": "Destination step (null if no destination)" }, "mode": { "type": "string", "enum": [ "send_the_brief", "submit", "reject", "validate" ], "example": "validate", "description": "Action mode (send_the_brief, submit, reject or validate)" }, "display_if_completeness": { "type": "boolean", "example": false, "description": "Display button only if all completeness attributes are filled" } }, "required": [ "id", "label", "mode", "display_if_completeness" ] }, "description": "Array of actions for this step" }, "completeness": { "type": "object", "nullable": true, "properties": { "attributes": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" }, "example": { "123": "Attribute Label", "456": "Other Attribute" }, "description": "Map of attribute IDs to their labels" }, "automate_goto_step": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 102, "description": "Automatic transition step ID when complete" }, "label": { "type": "string", "example": "Validate", "description": "Automatic transition step label when complete" } }, "required": [ "id", "label" ], "description": "Automatic step transition when completeness is reached" } }, "description": "Completeness configuration (null if not configured)" }, "hotfolder": { "type": "object", "nullable": true, "properties": { "action_on_update": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer", "example": 201, "description": "Action ID to execute on update" }, "label": { "type": "string", "example": "Validate", "description": "Action label" } }, "required": [ "id", "label" ], "description": "Action to execute when hotfolder is updated (null for no automatic step change)" }, "create_version": { "type": "boolean", "example": true, "description": "Whether to create a version on update" } }, "description": "Hotfolder configuration (null if not configured or not active)" }, "status_piloting_view": { "type": "object", "properties": { "status": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "example": "1234", "description": "Status id" }, "label": { "type": "string", "nullable": true, "example": "Admin Status", "description": "Status label" } }, "required": [ "id" ], "description": "Status configuration (null if not configured)" }, "default_view": { "type": "string", "nullable": true, "enum": [ "default", "completeness", "list" ], "example": "completeness", "description": "Default view mode (default, completeness, or list)" }, "children_piloting": { "type": "object", "nullable": true, "oneOf": [ { "type": "object", "title": "Workflow Type", "properties": { "type": { "type": "string", "enum": [ "workflow" ], "example": "workflow", "description": "Children piloting type" }, "items": { "type": "array", "items": { "type": "object", "properties": { "workflow": { "type": "object", "properties": { "id": { "type": "integer", "example": 15, "description": "Target workflow ID" }, "label": { "type": "string", "nullable": true, "example": "Child Workflow", "description": "Target workflow label" } }, "required": [ "id" ] }, "step": { "type": "object", "properties": { "id": { "type": "integer", "example": 101, "description": "Target step ID" }, "label": { "type": "string", "nullable": true, "example": "Draft", "description": "Target step label" } }, "required": [ "id" ] } }, "required": [ "workflow", "step" ] }, "description": "Array of workflow step configurations" } }, "required": [ "type", "items" ] }, { "type": "object", "title": "Status Type", "properties": { "type": { "type": "string", "enum": [ "status" ], "example": "status", "description": "Children piloting type" }, "items": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "object", "properties": { "id": { "type": "integer", "example": 123, "description": "Status ID" }, "label": { "type": "string", "nullable": true, "example": "Active", "description": "Status label" } }, "required": [ "id" ] }, "supertypes": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 3, "description": "Supertype ID" }, "label": { "type": "string", "nullable": true, "example": "Products", "description": "Supertype label" } }, "required": [ "id" ] }, "description": "Array of supertypes (null if not configured)" }, "types": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 42, "description": "Type ID" }, "label": { "type": "string", "nullable": true, "example": "Product", "description": "Type label" } }, "required": [ "id" ] }, "description": "Array of types (null if not configured)" } }, "required": [ "status" ] }, "description": "Array of status configurations" } }, "required": [ "type", "items" ] } ], "description": "Children piloting configuration (null if not configured)" } }, "description": "Status, piloting and view configuration" }, "reminder": { "type": "object", "nullable": true, "properties": { "days_before": { "type": "integer", "example": 7, "description": "Days before deadline to send notification" }, "recurrence_days": { "type": "integer", "nullable": true, "example": 1, "description": "Recurrence interval in days for notifications" } }, "description": "Reminder configuration (null if not configured)" } }, "required": [ "id", "label", "order", "start", "contributors", "actions", "status_piloting_view" ] }, "description": "Array of steps in this group" } }, "required": [ "id", "label", "order", "steps" ] }, "description": "Array of step groups containing steps with their nested data" } }, "required": [ "step_groups" ], "description": "Workflow configuration containing step groups hierarchy" } }, "required": [ "id", "code", "label", "class_id", "project_node_id", "project_label", "tags", "supertype", "types", "started", "configuration" ], "description": "Complete workflow information with hierarchical structure" }, "description": "Array of workflow objects with complete information" } }, "required": [ "results_total", "items" ] } }, "required": [ "status_code", "status_message", "result" ] }, { "type": "object", "title": "Error Response", "properties": { "status_code": { "type": "integer", "example": 3, "description": "Status code (3 = error, 0 = not found)" }, "status_message": { "type": "string", "example": "Repository 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": { "class_id": { "type": "integer", "description": "Library ID. Use POST /api/v3/administration/classes/list to get available libraries.", "example": 4 }, "filters": { "type": "object", "description": "Optional filters object. Currently supports filtering by type_id only.", "example": { "type_id": 42 }, "properties": { "type_id": { "type": "integer", "description": "Filter workflows by type ID. Use POST /api/v3/types/list with class_id to get valid type IDs. Returns workflows that have this type in their types array, or if types is empty, have a supertype matching the type's supertype.", "example": 42 } } } }, "required": [ "class_id" ] } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT token generated with /api/v3/token/get/" } } } }