openapi: 3.2.0 info: title: Akeneo API REFERENCE Reference entity 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: Reference entity description: 'A reference entity is a custom entity that can be used to store additional information about products or product models. It allows you to create your own entities with their own attributes and values, which can be linked to products or product models. Reference entities are useful for managing complex data structures or for integrating with external systems.' paths: /api/rest/v1/reference-entities: get: operationId: get_reference_entities x-visibility: public summary: Get list of reference entities description: 'This endpoint allows you to get a list of reference entities. Reference entities are paginated.' tags: - Reference entity security: - bearerToken: [] parameters: - in: query name: search_after description: 'Cursor when using the `search_after` pagination method type. It is essential for navigating through pages in cursor-based pagination, providing more efficient pagination for large datasets. Should never be set manually, see [Pagination](https://api.akeneo.com/documentation/pagination.html) section for more details. ' required: false schema: type: string default: cursor to the first page example: qaXbcde responses: '200': description: 'Return reference entities paginated. The response is paginated and includes links to navigate through the pages. Only `search_after` pagination is used. ' content: application/json: schema: title: Reference Entities 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: _embedded: type: object properties: items: type: array items: type: object 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/reference-entities/brands image_download: type: object properties: href: type: string description: URI to download the binaries of the reference entity image file example: https://demo.akeneo.com/api/rest/v1/reference-entities-media-files/0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png - type: object required: - code properties: code: type: string description: Reference entity code x-immutable: true example: brands labels: type: object description: Reference entity labels for each locale default: {} patternProperties: ^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$: description: Reference entity label for the locale type: - string - 'null' example: Brands x-validation-rules: The `localeCode` is the code of an existing and activated locale example: en_US: Brands fr_FR: Marques image: type: - string - 'null' description: Code of the reference entity image example: 0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png default: null example: _links: self: href: https://demo.akeneo.com/api/rest/v1/reference-entities first: href: https://demo.akeneo.com/api/rest/v1/reference-entities next: href: https://demo.akeneo.com/api/rest/v1/reference-entities?search_after=colors _embedded: items: - _links: self: href: https://demo.akeneo.com/api/rest/v1/reference-entities/brands image_download: href: https://demo.akeneo.com/api/rest/v1/reference-entities-media-files/0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png code: brands labels: en_US: Brands fr_FR: Marques image: 0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png - _links: self: href: https://demo.akeneo.com/api/rest/v1/reference-entities/designers code: designers labels: en_US: Designers fr_FR: Designers image: null - _links: self: href: https://demo.akeneo.com/api/rest/v1/reference-entities/colors code: colors labels: en_US: Colors fr_FR: Couleurs image: null '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. '406': description: 'This response indicates that the server cannot produce a response matching the list of acceptable values defined in the request''s `Accept` header. It is typically used when the requested resource is not available in the requested format. ' 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: 406 message: xxx in `Accept` header is not valid. Only `application/json` is allowed. /api/rest/v1/reference-entities/{code}: get: operationId: get_reference_entity_by_code x-visibility: public summary: Get a reference entity description: This endpoint allows you to get the information about a given reference entity tags: - Reference entity security: - bearerToken: [] parameters: - in: path name: code 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 code is correctly formatted and corresponds to an existing entity in the system. ' required: true schema: type: string example: my_entity_code responses: '200': description: Returns the content of the reference entity in JSON format content: application/json: schema: type: object allOf: - type: object properties: _links: type: object readOnly: true properties: image_download: type: object properties: href: type: string description: URI to download the binaries of the reference entity image file example: https://demo.akeneo.com/api/rest/v1/reference-entities-media-files/0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png - type: object required: - code properties: code: type: string description: Reference entity code x-immutable: true example: brands labels: type: object description: Reference entity labels for each locale default: {} patternProperties: ^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$: description: Reference entity label for the locale type: - string - 'null' example: Brands x-validation-rules: The `localeCode` is the code of an existing and activated locale example: en_US: Brands fr_FR: Marques image: type: - string - 'null' description: Code of the reference entity image example: 0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png default: null example: _links: image_download: href: https://demo.akeneo.com/api/rest/v1/reference-entities-media-files/0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png code: brands labels: en_US: Brands fr_FR: Marques image: 0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png '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. '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. '406': description: 'This response indicates that the server cannot produce a response matching the list of acceptable values defined in the request''s `Accept` header. It is typically used when the requested resource is not available in the requested format. ' 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: 406 message: xxx in `Accept` header is not valid. Only `application/json` is allowed. patch: operationId: patch_reference_entity_by_code x-visibility: public summary: Update/create a reference entity description: 'This endpoint allows you to update a given reference entity. Note that if the reference entity does not already exist, it creates it.' tags: - Reference entity security: - bearerToken: [] parameters: - in: path name: code 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 code is correctly formatted and corresponds to an existing entity in the system. ' required: true schema: type: string example: my_entity_code requestBody: description: Payload to create or update a reference entity required: true content: application/json: schema: type: object required: - code properties: code: type: string description: Reference entity code x-immutable: true example: brands labels: type: object description: Reference entity labels for each locale default: {} patternProperties: ^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$: description: Reference entity label for the locale type: - string - 'null' example: Brands x-validation-rules: The `localeCode` is the code of an existing and activated locale example: en_US: Brands fr_FR: Marques image: type: - string - 'null' description: Code of the reference entity image example: 0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png default: null example: code: brands labels: en_US: Brands fr_FR: Marques image: 0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png responses: '201': description: 'This response indicates that the entity was successfully created. The server has fulfilled the request and created a new resource. The response includes a `Location` header that contains the URI of the newly created resource. ' headers: Location: description: URI of the created resource schema: type: string '204': description: 'This response indicates that the request was successful and that there is no content to return. It is typically used in response to a successful update operation where the server does not need to return any data to the client. ' headers: Location: description: URI of the updated resource schema: type: string '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. '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." '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 required: - code - message properties: code: type: integer description: HTTP status code example: 422 message: type: string description: Description of the validation error example: The code of the reference entity provided in the URI must be the same as the one provided in the request body. examples: codeMismatch: summary: Code mismatch between URI and request body value: code: 422 message: The code of the reference entity provided in the URI must be the same as the one provided in the request body. imageNotFound: summary: Provided image code does not exist value: code: 422 message: The image "0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png" was not found 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)