openapi: 3.2.0 info: title: Akeneo API REFERENCE Data Architect Agent API version: 1.0.0 description: 'This is the reference documentation for the Akeneo PIM REST API. It provides detailed information about the available endpoints, request and response formats, and authentication methods. For more information, visit the Akeneo PIM documentation.' license: name: Open Software License 3.0 url: http://opensource.org/licenses/OSL-3.0 contact: name: Akeneo Support url: https://www.akeneo.com/support-help-center/ email: contact@akeneo.com servers: - url: '{your-pim-url}' variables: your-pim-url: default: '' description: 'Set the PIM url you want to target ex: https://my-pim.cloud.akeneo.com or https://localhost:8443' tags: - name: Data Architect Agent description: 'The Data Architect Agent endpoints allow you to create modelization suggestions for the data model designer. These suggestions can be used to improve the catalog structure and data quality.' paths: /api/rest/v1/data-model-designer/modelization-suggestion/attribute: post: operationId: post_data_model_designer_modelization_suggestion_attribute x-visibility: public summary: Create a modelization suggestion description: Creates a new modelization suggestion for the Data Architect Agent tags: - Data Architect Agent security: - bearerToken: [] requestBody: description: The modelization suggestion to create required: true content: application/json: schema: type: object required: - source - description properties: source: type: string description: The source of the suggestion example: manual enum: - manual - api - import description: type: string description: The description of the suggested attribute example: Product SKU identifier for tracking inventory code: type: - string - 'null' description: The attribute code (optional) example: sku type: type: - string - 'null' description: The attribute type (optional) example: text additional_comments: type: - string - 'null' description: Additional comments about the suggestion example: This attribute is needed for the new product line example: source: manual description: Product SKU identifier for tracking inventory code: sku type: text additional_comments: This attribute is needed for the new product line responses: '201': description: Modelization suggestion successfully created content: application/json: schema: type: object properties: uuid: type: string format: uuid description: The unique identifier of the created suggestion example: 550e8400-e29b-41d4-a716-446655440000 source: type: string description: The source of the suggestion example: manual enum: - manual - api - import author: type: string description: The author of the suggestion (authenticated user) example: admin created_at: type: string format: date-time description: The creation timestamp example: '2026-02-27T15:30:00+00:00' suggested_attributes: type: array description: List of suggested attributes items: type: object properties: code: type: - string - 'null' description: The attribute code example: sku type: type: - string - 'null' description: The attribute type example: text description: type: - string - 'null' description: The attribute description example: Product SKU identifier example: - code: sku type: text description: Product SKU identifier example: uuid: 550e8400-e29b-41d4-a716-446655440000 source: manual author: admin created_at: '2026-02-27T15:30:00+00:00' suggested_attributes: - code: sku type: text description: Product SKU identifier - code: name type: text description: Product name '400': description: 'This response indicates that the server cannot process the request due to a client error, such as malformed request syntax, invalid request message framing, or deceptive request routing. It is typically used when the server cannot understand the request due to invalid JSON or other client-side issues. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 400 message: Invalid JSON message received '401': description: 'This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 401 message: Full authentication is required to access this resource. '403': description: 'This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 403 message: Access forbidden. You are not allowed to list this entity. '404': description: 'This response indicates that the requested resource could not be found on the server. It can occur when the resource code given in the URI does not correspond to any existing PIM resource. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 404 message: Resource `my_resource_code` does not exist. '415': description: 'This response indicates that the `Content-type` header of the request is not supported by the server. The server expects the `Content-type` header to be `application/json`, and any other value will result in this error. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 415 message: xxx in `Content-type` header is not valid. Only `application/json` is allowed." /api/rest/v1/data-model-designer/modelization-suggestion/{uuid}: get: operationId: get_data_model_designer_modelization_suggestion x-visibility: public summary: Get a modelization suggestion description: Returns the details of a modelization suggestion by its UUID tags: - Data Architect Agent security: - bearerToken: [] parameters: - in: path name: uuid description: 'This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate. It is essential for identifying the specific entity in the API requests. Ensure that the UUID is correctly formatted and corresponds to an existing entity in the system. ' required: true schema: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174000 responses: '200': description: Returns the content of the modelization suggestion in JSON standard format content: application/json: schema: type: object properties: uuid: type: string format: uuid description: The unique identifier of the created suggestion example: 550e8400-e29b-41d4-a716-446655440000 source: type: string description: The source of the suggestion example: manual enum: - manual - api - import author: type: string description: The author of the suggestion (authenticated user) example: admin created_at: type: string format: date-time description: The creation timestamp example: '2026-02-27T15:30:00+00:00' suggested_attributes: type: array description: List of suggested attributes items: type: object properties: code: type: - string - 'null' description: The attribute code example: sku type: type: - string - 'null' description: The attribute type example: text description: type: - string - 'null' description: The attribute description example: Product SKU identifier example: - code: sku type: text description: Product SKU identifier example: uuid: 550e8400-e29b-41d4-a716-446655440000 status: draft source: manual author: admin created_at: '2026-02-27 15:30:00' raw_suggested_attributes: - code: name type: text description: Product name coreai_attributes: null additional_comments: This attribute is needed for the new product line '401': description: 'This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 401 message: Full authentication is required to access this resource. '403': description: 'This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 403 message: Access forbidden. You are not allowed to list this entity. '404': description: 'This response indicates that the requested resource could not be found on the server. It can occur when the resource code given in the URI does not correspond to any existing PIM resource. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 404 message: Resource `my_resource_code` does not exist. /api/rest/v1/data-model-designer/modelization-suggestion/{uuid}/approve: post: operationId: post_data_model_designer_modelization_suggestion_approve x-visibility: public summary: Approve a modelization suggestion description: 'Approves a modelization suggestion and creates the corresponding attributes in the PIM. The suggestion must be in DRAFT status and have CoreAI attributes available. Optional overrides can be provided for the attribute code, type, labels, group, scopable, and localizable.' tags: - Data Architect Agent security: - bearerToken: [] parameters: - in: path name: uuid description: 'This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate. It is essential for identifying the specific entity in the API requests. Ensure that the UUID is correctly formatted and corresponds to an existing entity in the system. ' required: true schema: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174000 requestBody: description: Optional overrides for the attribute being approved required: false content: application/json: schema: type: object description: Optional overrides for the attribute being approved properties: attribute_code: type: string description: Override the attribute code example: product_sku attribute_type: type: string description: Override the attribute type example: pim_catalog_text attribute_labels: type: object description: Override the attribute labels by locale additionalProperties: type: string example: en_US: Product SKU fr_FR: SKU Produit attribute_group: type: string description: Override the attribute group code example: marketing scopable: type: boolean nullable: true description: Override whether the attribute is scopable example: true localizable: type: boolean nullable: true description: Override whether the attribute is localizable example: true example: attribute_code: product_sku attribute_type: pim_catalog_text attribute_labels: en_US: Product SKU fr_FR: SKU Produit attribute_group: marketing scopable: true localizable: true responses: '200': description: Modelization suggestion successfully approved content: application/json: schema: type: object description: Result of approving a modelization suggestion properties: created: type: array description: List of attribute codes that were successfully created items: type: string example: - product_sku - product_name skipped: type: array description: List of attribute codes that were skipped because they already exist items: type: string example: - existing_attribute errors: type: object description: Map of attribute codes to error messages for attributes that failed to create additionalProperties: type: string example: invalid_attr: Attribute type is not valid example: created: - product_sku - product_name skipped: [] errors: {} '400': description: 'This response indicates that the server cannot process the request due to a client error, such as malformed request syntax, invalid request message framing, or deceptive request routing. It is typically used when the server cannot understand the request due to invalid JSON or other client-side issues. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 400 message: Invalid JSON message received '401': description: 'This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 401 message: Full authentication is required to access this resource. '403': description: 'This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 403 message: Access forbidden. You are not allowed to list this entity. '404': description: 'This response indicates that the requested resource could not be found on the server. It can occur when the resource code given in the URI does not correspond to any existing PIM resource. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 404 message: Resource `my_resource_code` does not exist. '422': description: 'This response indicates that the validation of the entity given in the body of the request failed. It occurs when the server understands the request but cannot process it due to validation errors in the provided data. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 422 message: type: string description: Message explaining the error example: Validation failed. errors: type: array description: A list of validation error messages (optional) items: type: object properties: property: type: string description: Name of the invalid property message: type: string description: Human-readable error message attribute: type: - string - 'null' description: Attribute code (if the error is on an attribute) locale: type: - string - 'null' description: Locale code involved in the error, if any scope: type: - string - 'null' description: Channel code involved in the error, if any example: - property: family message: The tshirts family does not exist in your PIM. _links: type: object properties: documentation: type: object properties: href: type: string example: documentation: href: http://api.akeneo.com/api-reference.html example: code: 422 message: Validation failed. errors: - property: family message: The tshirts family does not exist in your PIM. - property: categories message: The "tvs_projectors" category does not exist. - property: associations.SUBSTITUTION.groups message: You should associate existing groups. The "promotion" group does not exist. - property: values message: The "description" attribute requires a channel. attribute: description locale: en_US scope: null - property: values message: The "name" attribute requires a locale. attribute: name locale: null scope: null _links: documentation: href: http://api.akeneo.com/api-reference.html /api/rest/v1/data-model-designer/modelization-suggestion/{uuid}/decline: post: operationId: post_data_model_designer_modelization_suggestion_decline x-visibility: public summary: Decline a modelization suggestion description: 'Declines a modelization suggestion, marking it as rejected. The suggestion must be in DRAFT status.' tags: - Data Architect Agent security: - bearerToken: [] parameters: - in: path name: uuid description: 'This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate. It is essential for identifying the specific entity in the API requests. Ensure that the UUID is correctly formatted and corresponds to an existing entity in the system. ' required: true schema: type: string format: uuid example: 123e4567-e89b-12d3-a456-426614174000 requestBody: description: Optional body to provide a reason for declining the modelization suggestion content: application/json: examples: with_reason: value: reject_reason: The suggested attributes do not match the catalog requirements. without_reason: value: {} schema: type: object properties: reject_reason: type: string nullable: true description: The reason for declining the modelization suggestion example: The suggested attributes do not match the catalog requirements. responses: '204': description: Modelization suggestion successfully declined '400': description: 'This response indicates that the server cannot process the request due to a client error, such as malformed request syntax, invalid request message framing, or deceptive request routing. It is typically used when the server cannot understand the request due to invalid JSON or other client-side issues. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 400 message: Invalid JSON message received '401': description: 'This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 401 message: Full authentication is required to access this resource. '403': description: 'This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 403 message: Access forbidden. You are not allowed to list this entity. '404': description: 'This response indicates that the requested resource could not be found on the server. It can occur when the resource code given in the URI does not correspond to any existing PIM resource. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 404 message: Resource `my_resource_code` does not exist. /api/rest/v1/data-model-designer/modelization-suggestions: get: operationId: get_data_model_designer_modelization_suggestions x-visibility: public summary: Get list of modelization suggestions description: 'Returns a paginated list of modelization suggestions. Users without the manage permission are automatically restricted to their own suggestions.' tags: - Data Architect Agent security: - bearerToken: [] parameters: - in: query name: page description: 'Specify which page of results to retrieve when using pagination. It is useful for navigating through large datasets by breaking them into smaller, manageable pages. See [Pagination](https://api.akeneo.com/documentation/pagination.html) section for more details. ' required: false schema: type: integer default: 1 example: 1 - in: query name: limit description: 'Specify the maximum number of results to return per page. It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets. See [Pagination](https://api.akeneo.com/documentation/pagination.html) section for more details. ' required: false schema: type: integer default: 10 minimum: 1 maximum: 100 example: 100 - in: query name: with_count description: 'Return the count of items in the response. Be careful with that, on a big catalog, it can decrease performance in a significant way. It is useful for understanding the size of the dataset being returned, especially when dealing with large collections. Use it judiciously to avoid performance issues. ' required: false schema: type: boolean default: false example: true - in: query name: codes required: false description: 'Filter suggestions by attribute codes present in their suggested attributes. Accepts a comma-separated list of attribute codes. Returns suggestions that contain at least one of the provided attribute codes. ' schema: type: string example: color,size,weight - in: query name: status required: false description: 'Filter suggestions by status. ' schema: type: string enum: - generating - draft - applied - declined - failed example: draft - in: query name: source required: false description: 'Filter suggestions by their source identifier. ' schema: type: string example: my-system - in: query name: author required: false description: 'Filter suggestions by the author''s username. Only available for users with the manage permission. This parameter is ignored for users without it. ' schema: type: string example: john.doe responses: '200': description: Returns a paginated list of modelization suggestions in HAL format content: application/json: schema: title: Modelization suggestions type: object allOf: - type: object properties: _links: type: object properties: self: type: object properties: href: type: string description: URI of the current page of resources example: https://demo.akeneo.com/api/rest/v1/categories?page=2&limit=5 first: type: object properties: href: type: string description: URI of the first page of resources example: https://demo.akeneo.com/api/rest/v1/categories?page=1&limit=5 previous: type: object properties: href: type: string description: URI of the previous page of resources example: https://demo.akeneo.com/api/rest/v1/categories?page=1&limit=5 next: type: object properties: href: type: string description: URI of the next page of resources example: https://demo.akeneo.com/api/rest/v1/categories?page=3&limit=5 - type: object properties: current_page: type: integer description: Current page number example: 1 items_count: type: integer description: Total number of items (only if `with_count` parameter is set to true) example: 5 _embedded: type: object properties: items: type: array items: allOf: - type: object properties: _links: type: object properties: self: type: object properties: href: type: string description: URI of the resource example: https://demo.akeneo.com/api/rest/v1/data-model-designer/modelization-suggestion/550e8400-e29b-41d4-a716-446655440000 - type: object properties: uuid: type: string format: uuid description: The unique identifier of the created suggestion example: 550e8400-e29b-41d4-a716-446655440000 source: type: string description: The source of the suggestion example: manual enum: - manual - api - import author: type: string description: The author of the suggestion (authenticated user) example: admin created_at: type: string format: date-time description: The creation timestamp example: '2026-02-27T15:30:00+00:00' suggested_attributes: type: array description: List of suggested attributes items: type: object properties: code: type: - string - 'null' description: The attribute code example: sku type: type: - string - 'null' description: The attribute type example: text description: type: - string - 'null' description: The attribute description example: Product SKU identifier example: - code: sku type: text description: Product SKU identifier example: _links: self: href: https://demo.akeneo.com/api/rest/v1/data-model-designer/modelization-suggestions?page=1&limit=10 first: href: https://demo.akeneo.com/api/rest/v1/data-model-designer/modelization-suggestions?page=1&limit=10 next: href: https://demo.akeneo.com/api/rest/v1/data-model-designer/modelization-suggestions?page=2&limit=10 current_page: 1 _embedded: items: - _links: self: href: https://demo.akeneo.com/api/rest/v1/data-model-designer/modelization-suggestion/550e8400-e29b-41d4-a716-446655440000 uuid: 550e8400-e29b-41d4-a716-446655440000 status: draft source: manual author: admin created_at: '2026-02-27 15:30:00' raw_suggested_attributes: - code: sku type: text description: Product SKU identifier coreai_attributes: null additional_comments: null '400': description: 'This response indicates that the server cannot process the request due to a client error, such as malformed request syntax, invalid request message framing, or deceptive request routing. It is typically used when the server cannot understand the request due to invalid JSON or other client-side issues. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 400 message: Invalid JSON message received '401': description: 'This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 401 message: Full authentication is required to access this resource. '403': description: 'This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 403 message: Access forbidden. You are not allowed to list this entity. components: securitySchemes: basicToken: scheme: basic type: http description: 'HTTP Basic authentication using user credentials. [More information here](https://api.akeneo.com/documentation/authentication.html) ' bearerToken: scheme: bearer type: http description: 'Bearer token obtained via the "Password Grant" flow. This token authenticates a user, is valid for one hour, and can be refreshed using a refresh token. [More information here](https://api.akeneo.com/documentation/authentication.html) ' appToken: scheme: bearer type: http description: 'Bearer token for Apps, obtained via the OAuth 2.0 flow. This permanent token allows an application to make requests on behalf of a user. [More information here](https://api.akeneo.com/apps/authentication-and-authorization.html) ' x-provenance: method: harvested publisher: Akeneo source: https://storage.googleapis.com/akecld-prd-pim-saas-shared-openapi-spec/openapi.yaml note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json); stamped by stamp-openapi-provenance.py (roadmap#793)