openapi: 3.2.0 info: title: Akeneo API REFERENCE Asset 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: Asset description: 'An asset is a flexible object that makes it possible to enrich products with images, videos, documents… An asset must be part of an asset family. That way, it will have its own attributes and lifecycle. Assets can be linked to products and product models, in order to enrich them.' paths: /api/rest/v1/asset-families/{asset_family_code}/assets: get: operationId: get_assets x-visibility: public summary: Get the list of the assets of a given asset family description: 'This endpoint allows you to get a list of assets of a given asset family. Assets are paginated. This endpoint is case sensitive on the asset family code.' tags: - Asset security: - bearerToken: [] parameters: - name: search in: query description: 'Filter assets, for more details see the [Asset filters](https://api.akeneo.com/documentation/filter.html#filter-assets) section. ' required: false schema: type: string examples: getAssetsByAssetCode: summary: Filter the assets by their code value: '{"code":[{"operator":"IN","value":["code1","code2"]}]}' getAssetsByUpdatedDate: summary: Filter the assets by their update date value: '{"updated":[{"operator":">","value":"2018-07-04T10:00:00Z"}]}' getAssetsUpdatedOverPeriod: summary: Filter the assets that were updated over a period of time value: '{"updated":[{"operator":"NOT BETWEEN","value":["2018-07-04T10:00:00Z","2018-08-04T10:00:00Z"]}]}' getAssetsUpdatedSinceXDays: summary: Filter the assets that were updated since X days value: '{"updated":[{"operator":"SINCE LAST N DAYS","value":4}]}' - name: channel in: query description: 'Filter asset values to return scopable asset attributes for the given channel as well as the non localizable/non scopable asset attributes, for more details see the [Filter asset values by channel](https://api.akeneo.com/documentation/filter.html#asset-values-by-channel) section. ' required: false schema: type: string example: ecommerce - name: locales in: query description: 'Filter asset values to return localizable asset attributes for the given locales as well as the non localizable/non scopable asset attributes, for more details see the [Filter asset values by locale](https://api.akeneo.com/documentation/filter.html#asset-values-by-locale) section. ' required: false schema: type: string example: en_US,fr_FR - in: path name: asset_family_code description: 'This path parameter is used to specify the unique identifier of the asset family you want to retrieve or manipulate. It is essential for identifying the specific asset family in the API requests. Ensure that the asset family code is correctly formatted and corresponds to an existing asset family in the system. ' required: true schema: type: string example: packshot - 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 - in: query name: with_asset_auto_tags description: 'Return labels of asset tags generated by auto-tagging in the response. When set to `true`, the response will include human-readable labels for asset tags alongside their codes. If set to `false`, the response will only include tag codes, which can improve performance. See [the `linked_data` format](https://api.akeneo.com/concepts/asset-manager.html#the-linked_data-format) section for more details. ' required: false schema: type: boolean default: false example: true - in: query name: attributes description: 'Comma-separated list of asset attribute codes. Only the values of these attributes are returned. It is useful for limiting the response to specific attributes and reducing its payload size. Attribute codes are case sensitive. An empty or malformed code, or a code that does not belong to the asset family, returns a 422 error. ' required: false schema: type: string example: title,description responses: '200': description: 'Return the assets of the given asset family paginated. The response is paginated and includes links to navigate through the pages. Only `search_after` pagination is used. ' content: application/json: schema: title: Asset 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: 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/asset-families/packshot/assets/sku_54628_picture1 - type: object required: - code properties: code: type: string description: Code of the asset x-immutable: true example: sku_54628_picture1 asset_family_code: type: string description: Code of the asset family x-immutable: true example: packshot values: type: object description: 'Asset attributes values. See the [Focus on the asset values](https://api.akeneo.com/concepts/asset-manager.html#focus-on-the-asset-values) section for more details. ' patternProperties: ^\w+$: type: array items: type: object required: - locale - channel - data properties: channel: type: - string - 'null' description: Channel code of the asset attribute value locale: type: - string - 'null' description: Locale code of the asset attribute value data: oneOf: - type: string - type: array items: type: string - type: boolean - type: 'null' description: 'Asset attribute value. See [the `data` format](https://api.akeneo.com/concepts/asset-manager.html#the-data-format) section for more details. ' linked_data: type: object description: 'Linked data for `media link`, `media file` and `auto tags` attribute values. See [the `linked_data` format](https://api.akeneo.com/concepts/asset-manager.html#the-linked_data-format) section for more details. ' attribute_type: type: string description: The type of the value's attribute. See [type](https://api.akeneo.com/concepts/asset-manager.html#asset-attribute) section for more details. readOnly: true enum: - text - single_option - multiple_options - number - media_file - media_link - boolean - date - record - auto_tagging example: media_file _links: type: object description: 'Related links for the `media file` attribute values. See [the `_links` format](https://api.akeneo.com/concepts/asset-manager.html#the-_links-format) section for more details. ' x-validation-rules: The share link is returned when asset sharing is enabled x-validation-rules: Validation rules detailed in Asset attribute values section example: media_file: - locale: en_US channel: ecommerce data: 0/0/9/d/009d38fe8c97e16f6b48bbf8f6cf8a9564401cc9_allie_jean_model_picture.png linked_data: original_filename: allie_jean_model_picture.png mime_type: image/jpeg size: 16070 extension: jpg updated_at: 2026-04-22T07:39:37+0000 _links: download: href: https://demo.akeneo.com/api/rest/v1/asset-media-files/0/0/9/d/009d38fe8c97e16f6b48bbf8f6cf8a9564401cc9_allie_jean_model_picture.png share_link: href: https://demo.asset.akeneo.com/model_pictures/media_file/allie_jean_model_picture.png description: - locale: en_US channel: ecommerce data: This is a product description main_colors: - locale: en_US channel: ecommerce data: - red - blue created: type: string format: date-time description: Date of creation readOnly: true x-immutable: true example: '2021-05-31T09:23:34+00:00' updated: type: string format: date-time description: Date of the last update readOnly: true example: '2021-05-31T09:23:34+00:00' example: items: - _links: self: href: https://demo.akeneo.com/api/rest/v1/asset-families/packshot/assets/sku_54628_picture1 code: sku_54628_picture1 asset_family_code: packshot values: media_preview: - data: sku_54628_picture1.jpg locale: en_US channel: ecommerce model_wears_size: - data: s locale: en_US channel: ecommerce photographer: - data: ben_levy locale: en_US channel: ecommerce main_colors: - data: - red - purple locale: en_US channel: ecommerce end_of_use_date: - data: 02/03/2021 locale: null channel: null auto_tags: - locale: null channel: null data: - outdoor - fashion linked_data: outdoor: labels: en_US: Outdoor fr_FR: Plein air fashion: labels: en_US: Fashion fr_FR: Mode created: '2021-05-31T09:23:34+00:00' updated: '2021-05-31T09:23:34+00:00' example: _links: self: href: https://demo.akeneo.com/api/rest/v1/asset-families/model_pictures/assets first: href: https://demo.akeneo.com/api/rest/v1/asset-families/model_pictures/assets next: href: https://demo.akeneo.com/api/rest/v1/asset-families/model_pictures/assets?search_after=alice_blouse_model_picture _embedded: items: - _links: self: href: https://demo.akeneo.com/api/rest/v1/asset-families/model_pictures/assets/allie_jean_model_picture code: allie_jean_model_picture asset_family_code: model_pictures values: media_file: - locale: null channel: null data: 0/0/9/d/009d38fe8c97e16f6b48bbf8f6cf8a9564401cc9_allie_jean_model_picture.png linked_data: original_filename: allie_jean_model_picture.png mime_type: image/jpeg size: 16070 extension: jpg updated_at: 2026-04-22T07:39:37+0000 _links: download: href: https://demo.akeneo.com/api/rest/v1/asset-media-files/0/0/9/d/009d38fe8c97e16f6b48bbf8f6cf8a9564401cc9_allie_jean_model_picture.png share_link: href: https://demo.asset.akeneo.com/model_pictures/media_file/allie_jean_model_picture.png media_link: - locale: null channel: null data: allie_jean_model_picture.png linked_data: full_url: https://example.com/allie_jean_model_picture.png prefix: https://example.com/ suffix: null model_is_wearing_size: - locale: null channel: null data: size_27 warning_mention: - data: Photo not retouched locale: en_US channel: null - data: Photo non retouchée locale: fr_FR channel: null auto_tags: - locale: null channel: null data: - jeans - trousers linked_data: jeans: labels: en_US: Jeans fr_FR: Jean trousers: labels: en_US: Trousers fr_FR: Pantalon created: '2021-05-31T09:23:34+00:00' updated: '2021-05-31T09:23:34+00:00' - _links: self: href: https://demo.akeneo.com/api/rest/v1/asset-families/model_pictures/assets/amy_socks_model_picture code: amy_socks_model_picture asset_family_code: model_pictures values: media_file: - locale: null channel: null data: 0/0/9/d/009d38fe8c97e16f6b48bbf8f6cf8a9564401cc9_amy_socks_model_picture.png linked_data: original_filename: amy_socks_model_picture.jpg mime_type: image/jpeg size: 16070 extension: jpg updated_at: 2026-04-22T07:39:37+0000 _links: download: href: https://demo.akeneo.com/api/rest/v1/asset-media-files/0/0/9/d/009d38fe8c97e16f6b48bbf8f6cf8a9564401cc9_amy_socks_model_picture.png share_link: href: https://demo.asset.akeneo.com/model_pictures/media_file/amy_socks_model_picture.jpg media_link: - locale: null channel: null data: amy_socks_model_picture.png linked_data: full_url: https://example.com/amy_socks_model_picture.png prefix: https://example.com/ suffix: null model_is_wearing_size: - locale: null channel: null data: unique_size warning_mention: - data: Photo not retouched locale: en_US channel: null - data: Photo non retouchée locale: fr_FR channel: null auto_tags: - locale: null channel: null data: - socks - fashion linked_data: socks: labels: en_US: Socks fr_FR: Chaussettes fashion: labels: en_US: Fashion fr_FR: Mode created: '2021-05-31T09:23:34+00:00' updated: '2021-05-31T09:23:34+00:00' - _links: self: href: https://demo.akeneo.com/api/rest/v1/asset-families/model_pictures/assets/alice_blouse_model_picture code: alice_blouse_model_picture asset_family_code: model_pictures values: media_file: - locale: null channel: null data: 0/0/9/d/009d38fe8c97e16f6b48bbf8f6cf8a9564401cc9_alice_blouse_model_picture.png linked_data: original_filename: alice_blouse_model_picture.png mime_type: image/jpeg size: 16070 extension: jpg updated_at: 2026-04-22T07:39:37+0000 _links: download: href: https://demo.akeneo.com/api/rest/v1/asset-media-files/0/0/9/d/009d38fe8c97e16f6b48bbf8f6cf8a9564401cc9_alice_blouse_model_picture.png share_link: href: https://demo.asset.akeneo.com/model_pictures/media_file/alice_blouse_model_picture.png media_link: - locale: null channel: null data: alice_blouse_model_picture.png linked_data: full_url: https://example.com/alice_blouse_model_picture.png prefix: https://example.com/ suffix: null model_is_wearing_size: - locale: null channel: null data: small warning_mention: - data: Photo retouched locale: en_US channel: null - data: Photo non retouchée locale: fr_FR channel: null auto_tags: - locale: null channel: null data: - blouse - fashion linked_data: blouse: labels: en_US: Blouse fr_FR: Blouse fashion: labels: en_US: Fashion fr_FR: Mode created: '2021-05-31T09:23:34+00:00' updated: '2021-05-31T09:23:34+00:00' '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. '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 patch: operationId: patch_assets x-visibility: public summary: Update/create several assets description: 'This endpoint allows you to update and/or create several assets of one given asset family at once. Learn more about the Update behavior. Note that if the asset does not already exist for the given asset family, it creates it. This endpoint is case sensitive on the asset family code.' tags: - Asset security: - bearerToken: [] parameters: - in: path name: asset_family_code description: 'This path parameter is used to specify the unique identifier of the asset family you want to retrieve or manipulate. It is essential for identifying the specific asset family in the API requests. Ensure that the asset family code is correctly formatted and corresponds to an existing asset family in the system. ' required: true schema: type: string example: packshot requestBody: description: Body of the request containing the assets to create or update content: application/json: schema: type: array items: type: object required: - code properties: code: type: string description: Code of the asset x-immutable: true example: sku_54628_picture1 asset_family_code: type: string description: Code of the asset family x-immutable: true example: packshot values: type: object description: 'Asset attributes values. See the [Focus on the asset values](https://api.akeneo.com/concepts/asset-manager.html#focus-on-the-asset-values) section for more details. ' patternProperties: ^\w+$: type: array items: type: object required: - locale - channel - data properties: channel: type: - string - 'null' description: Channel code of the asset attribute value locale: type: - string - 'null' description: Locale code of the asset attribute value data: oneOf: - type: string - type: array items: type: string - type: boolean - type: 'null' description: 'Asset attribute value. See [the `data` format](https://api.akeneo.com/concepts/asset-manager.html#the-data-format) section for more details. ' linked_data: type: object description: 'Linked data for `media link`, `media file` and `auto tags` attribute values. See [the `linked_data` format](https://api.akeneo.com/concepts/asset-manager.html#the-linked_data-format) section for more details. ' attribute_type: type: string description: The type of the value's attribute. See [type](https://api.akeneo.com/concepts/asset-manager.html#asset-attribute) section for more details. readOnly: true enum: - text - single_option - multiple_options - number - media_file - media_link - boolean - date - record - auto_tagging example: media_file _links: type: object description: 'Related links for the `media file` attribute values. See [the `_links` format](https://api.akeneo.com/concepts/asset-manager.html#the-_links-format) section for more details. ' x-validation-rules: The share link is returned when asset sharing is enabled x-validation-rules: Validation rules detailed in Asset attribute values section example: media_file: - locale: en_US channel: ecommerce data: 0/0/9/d/009d38fe8c97e16f6b48bbf8f6cf8a9564401cc9_allie_jean_model_picture.png linked_data: original_filename: allie_jean_model_picture.png mime_type: image/jpeg size: 16070 extension: jpg updated_at: 2026-04-22T07:39:37+0000 _links: download: href: https://demo.akeneo.com/api/rest/v1/asset-media-files/0/0/9/d/009d38fe8c97e16f6b48bbf8f6cf8a9564401cc9_allie_jean_model_picture.png share_link: href: https://demo.asset.akeneo.com/model_pictures/media_file/allie_jean_model_picture.png description: - locale: en_US channel: ecommerce data: This is a product description main_colors: - locale: en_US channel: ecommerce data: - red - blue created: type: string format: date-time description: Date of creation readOnly: true x-immutable: true example: '2021-05-31T09:23:34+00:00' updated: type: string format: date-time description: Date of the last update readOnly: true example: '2021-05-31T09:23:34+00:00' example: - code: sku_54628_picture1 status: enabled start_date: '2026-05-10' end_date: null values: media_preview: - data: sku_54628_picture1.jpg channel: null locale: null attribute_type: media_file model_wears_size: - data: s channel: null locale: null attribute_type: single_option photographer: - data: ben_levy channel: null locale: null attribute_type: text main_colors: - data: - red - purple channel: null locale: null attribute_type: multiple_options end_of_use_date: - data: 02/03/2021 channel: null locale: null attribute_type: date auto_tags: - data: - outdoor - fashion channel: null locale: null linked_data: outdoor: labels: en_US: Outdoor fr_FR: Plein air fashion: labels: en_US: Fashion fr_FR: Mode attribute_type: auto_tagging created: '2021-05-31T09:23:34+00:00' updated: '2021-05-31T09:23:34+00:00' - code: sku_54628_picture2 status: enabled start_date: null end_date: '2100-05-11' values: media_preview: - data: sku_54628_picture2.jpg channel: null locale: null attribute_type: media_file model_wears_size: - data: s channel: null locale: null attribute_type: single_option photographer: - data: ben_levy channel: null locale: null attribute_type: text main_colors: - data: - blue - white channel: null locale: null attribute_type: multiple_options end_of_use_date: - data: 02/03/2021 channel: null locale: null attribute_type: date auto_tags: - data: - indoor - fashion channel: null locale: null linked_data: indoor: labels: en_US: Indoor fr_FR: Intérieur fashion: labels: en_US: Fashion fr_FR: Mode attribute_type: auto_tagging created: '2021-05-31T09:23:34+00:00' updated: '2021-05-31T09:23:34+00:00' - code: sku_54628_picture3 status: disabled start_date: '2020-01-01' end_date: '2026-05-10' values: media_preview: - data: sku_54628_picture3.jpg channel: null locale: null attribute_type: media_file model_wears_size: - data: s channel: null locale: null attribute_type: single_option photographer: - data: ben_levy channel: null locale: null attribute_type: text main_colors: - data: - purple channel: null locale: null attribute_type: multiple_options end_of_use_date: - data: 02/03/2021 channel: null locale: null attribute_type: date auto_tags: - data: - outdoor - fashion channel: null locale: null linked_data: outdoor: labels: en_US: Outdoor fr_FR: Plein air fashion: labels: en_US: Fashion fr_FR: Mode attribute_type: auto_tagging created: '2021-05-31T09:23:34+00:00' updated: '2021-05-31T09:23:34+00:00' required: true responses: '200': description: Returns an JSON array in which each object gives you the status of each asset creation or update x-no-entity: true content: application/json: schema: type: array items: type: object properties: code: type: string description: Resource code status_code: type: integer description: 'HTTP status code, see [Client errors](https://api.akeneo.com/documentation/responses.html#client-errors) to understand the meaning of each code ' message: type: string description: Message explaining the error required: - code - status_code example: - code: sku_54628_picture1 status_code: 204 - code: sku_54628_picture2 status_code: 422 message: Property 'group' does not exist. - code: sku_54628_picture3 status_code: 201 '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. '413': description: 'This response indicates that the request entity is larger than the server is willing or able to process. It can occur when the number of resources in a batch request exceeds the maximum allowed limit. ' 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: 413 message: Too many resources to process, 100 is the maximum allowed. '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." '429': description: 'This response indicates that the user has sent too many requests in a given amount of time. It occurs when the rate limit for API requests has been exceeded, and the client should wait before making additional requests. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 429 message: type: string description: Message explaining the error example: You have exceeded the limit of API requests per second. example: code: 429 message: You have exceeded the limit of API requests per second. /api/rest/v1/asset-families/{asset_family_code}/assets/{code}: get: operationId: get_asset_by_code x-visibility: public summary: Get an asset of a given asset family description: 'This endpoint allows you to get the information about a given asset for a given asset family. This endpoint is case sensitive on the asset family code.' tags: - Asset security: - bearerToken: [] parameters: - in: path name: asset_family_code description: 'This path parameter is used to specify the unique identifier of the asset family you want to retrieve or manipulate. It is essential for identifying the specific asset family in the API requests. Ensure that the asset family code is correctly formatted and corresponds to an existing asset family in the system. ' required: true schema: type: string example: packshot - 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 - in: query name: with_asset_auto_tags description: 'Return labels of asset tags generated by auto-tagging in the response. When set to `true`, the response will include human-readable labels for asset tags alongside their codes. If set to `false`, the response will only include tag codes, which can improve performance. See [the `linked_data` format](https://api.akeneo.com/concepts/asset-manager.html#the-linked_data-format) section for more details. ' required: false schema: type: boolean default: false example: true - in: query name: with_usage description: 'Return a usage overview of the asset in the response. When set to `true`, the response includes how many products, product models, reference entity records and categories reference this asset. Only the exact value `true` enables it, any other value is ignored. These counts are not scoped to the category permissions of the caller. Enabling it has a performance cost on every call. See the [asset usage](https://api.akeneo.com/concepts/asset-manager.html#asset-usage) section for more details. ' required: false schema: type: boolean default: false example: true - in: query name: attributes description: 'Comma-separated list of asset attribute codes. Only the values of these attributes are returned. It is useful for limiting the response to specific attributes and reducing its payload size. Attribute codes are case sensitive. An empty or malformed code, or a code that does not belong to the asset family, returns a 422 error. ' required: false schema: type: string example: title,description responses: '200': description: Returns the content of the asset in JSON standard format content: application/json: schema: allOf: - type: object required: - code properties: code: type: string description: Code of the asset x-immutable: true example: sku_54628_picture1 asset_family_code: type: string description: Code of the asset family x-immutable: true example: packshot values: type: object description: 'Asset attributes values. See the [Focus on the asset values](https://api.akeneo.com/concepts/asset-manager.html#focus-on-the-asset-values) section for more details. ' patternProperties: ^\w+$: type: array items: type: object required: - locale - channel - data properties: channel: type: - string - 'null' description: Channel code of the asset attribute value locale: type: - string - 'null' description: Locale code of the asset attribute value data: oneOf: - type: string - type: array items: type: string - type: boolean - type: 'null' description: 'Asset attribute value. See [the `data` format](https://api.akeneo.com/concepts/asset-manager.html#the-data-format) section for more details. ' linked_data: type: object description: 'Linked data for `media link`, `media file` and `auto tags` attribute values. See [the `linked_data` format](https://api.akeneo.com/concepts/asset-manager.html#the-linked_data-format) section for more details. ' attribute_type: type: string description: The type of the value's attribute. See [type](https://api.akeneo.com/concepts/asset-manager.html#asset-attribute) section for more details. readOnly: true enum: - text - single_option - multiple_options - number - media_file - media_link - boolean - date - record - auto_tagging example: media_file _links: type: object description: 'Related links for the `media file` attribute values. See [the `_links` format](https://api.akeneo.com/concepts/asset-manager.html#the-_links-format) section for more details. ' x-validation-rules: The share link is returned when asset sharing is enabled x-validation-rules: Validation rules detailed in Asset attribute values section example: media_file: - locale: en_US channel: ecommerce data: 0/0/9/d/009d38fe8c97e16f6b48bbf8f6cf8a9564401cc9_allie_jean_model_picture.png linked_data: original_filename: allie_jean_model_picture.png mime_type: image/jpeg size: 16070 extension: jpg updated_at: 2026-04-22T07:39:37+0000 _links: download: href: https://demo.akeneo.com/api/rest/v1/asset-media-files/0/0/9/d/009d38fe8c97e16f6b48bbf8f6cf8a9564401cc9_allie_jean_model_picture.png share_link: href: https://demo.asset.akeneo.com/model_pictures/media_file/allie_jean_model_picture.png description: - locale: en_US channel: ecommerce data: This is a product description main_colors: - locale: en_US channel: ecommerce data: - red - blue created: type: string format: date-time description: Date of creation readOnly: true x-immutable: true example: '2021-05-31T09:23:34+00:00' updated: type: string format: date-time description: Date of the last update readOnly: true example: '2021-05-31T09:23:34+00:00' - type: object properties: usage: type: object readOnly: true description: 'Usage overview of the asset, returned only when the `with_usage` query parameter is set to `true`. Each entry gives the number of entities referencing this asset. ' properties: products: type: object properties: total: type: integer description: Number of products referencing this asset example: 12 product_models: type: object properties: total: type: integer description: Number of product models referencing this asset example: 3 reference_entity_records: type: object properties: total: type: integer description: Number of reference entity records referencing this asset example: 0 categories: type: object properties: total: type: integer description: Number of categories referencing this asset example: 1 example: code: sku_54628_picture1 status: enabled start_date: null end_date: null values: media_preview: - locale: null channel: null data: sku_54628_picture1.jpg attribute_type: media_file linked_data: original_filename: sku_54628_picture1.jpg mime_type: image/png size: 16070 extension: png updated_at: 2026-04-22T07:39:37+0000 model_wears_size: - locale: null channel: null data: s attribute_type: single_option photographer: - locale: null channel: null data: ben_levy attribute_type: text main_colors: - locale: null channel: null data: - red - purple attribute_type: multiple_options end_of_use_date: - locale: null channel: null data: 02/03/2021 attribute_type: date auto_tags: - locale: null channel: null data: - outdoor - fashion linked_data: outdoor: labels: en_US: Outdoor fr_FR: Plein air fashion: labels: en_US: Fashion fr_FR: Mode attribute_type: auto_tagging created: '2021-05-31T09:23:34+00:00' updated: '2021-05-31T09:23:34+00:00' '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. '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 patch: operationId: patch_asset_by_code x-visibility: public summary: Update/create an asset description: 'This endpoint allows you to update a given asset of a given asset family. Learn more about the Update behavior. Note that if the asset does not already exist for the given asset family, it creates it. This endpoint is case sensitive on the asset family code.' tags: - Asset security: - bearerToken: [] parameters: - in: path name: asset_family_code description: 'This path parameter is used to specify the unique identifier of the asset family you want to retrieve or manipulate. It is essential for identifying the specific asset family in the API requests. Ensure that the asset family code is correctly formatted and corresponds to an existing asset family in the system. ' required: true schema: type: string example: packshot - 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: Body of the request containing the asset to create or update content: application/json: schema: type: object required: - code properties: code: type: string description: Code of the asset x-immutable: true example: sku_54628_picture1 asset_family_code: type: string description: Code of the asset family x-immutable: true example: packshot values: type: object description: 'Asset attributes values. See the [Focus on the asset values](https://api.akeneo.com/concepts/asset-manager.html#focus-on-the-asset-values) section for more details. ' patternProperties: ^\w+$: type: array items: type: object required: - locale - channel - data properties: channel: type: - string - 'null' description: Channel code of the asset attribute value locale: type: - string - 'null' description: Locale code of the asset attribute value data: oneOf: - type: string - type: array items: type: string - type: boolean - type: 'null' description: 'Asset attribute value. See [the `data` format](https://api.akeneo.com/concepts/asset-manager.html#the-data-format) section for more details. ' linked_data: type: object description: 'Linked data for `media link`, `media file` and `auto tags` attribute values. See [the `linked_data` format](https://api.akeneo.com/concepts/asset-manager.html#the-linked_data-format) section for more details. ' attribute_type: type: string description: The type of the value's attribute. See [type](https://api.akeneo.com/concepts/asset-manager.html#asset-attribute) section for more details. readOnly: true enum: - text - single_option - multiple_options - number - media_file - media_link - boolean - date - record - auto_tagging example: media_file _links: type: object description: 'Related links for the `media file` attribute values. See [the `_links` format](https://api.akeneo.com/concepts/asset-manager.html#the-_links-format) section for more details. ' x-validation-rules: The share link is returned when asset sharing is enabled x-validation-rules: Validation rules detailed in Asset attribute values section example: media_file: - locale: en_US channel: ecommerce data: 0/0/9/d/009d38fe8c97e16f6b48bbf8f6cf8a9564401cc9_allie_jean_model_picture.png linked_data: original_filename: allie_jean_model_picture.png mime_type: image/jpeg size: 16070 extension: jpg updated_at: 2026-04-22T07:39:37+0000 _links: download: href: https://demo.akeneo.com/api/rest/v1/asset-media-files/0/0/9/d/009d38fe8c97e16f6b48bbf8f6cf8a9564401cc9_allie_jean_model_picture.png share_link: href: https://demo.asset.akeneo.com/model_pictures/media_file/allie_jean_model_picture.png description: - locale: en_US channel: ecommerce data: This is a product description main_colors: - locale: en_US channel: ecommerce data: - red - blue created: type: string format: date-time description: Date of creation readOnly: true x-immutable: true example: '2021-05-31T09:23:34+00:00' updated: type: string format: date-time description: Date of the last update readOnly: true example: '2021-05-31T09:23:34+00:00' example: code: sku_54628_picture1 status: enabled start_date: null end_date: null values: media_preview: - locale: null channel: null data: sku_54628_picture1.jpg attribute_type: media_file linked_data: original_filename: sku_54628_picture1.jpg mime_type: image/png size: 16070 extension: png updated_at: 2026-04-22T07:39:37+0000 model_wears_size: - locale: null channel: null data: s attribute_type: single_option photographer: - locale: null channel: null data: ben_levy attribute_type: text main_colors: - locale: null channel: null data: - red - purple attribute_type: multiple_options end_of_use_date: - locale: null channel: null data: 02/03/2021 attribute_type: date auto_tags: - locale: null channel: null data: - outdoor - fashion linked_data: outdoor: labels: en_US: Outdoor fr_FR: Plein air fashion: labels: en_US: Fashion fr_FR: Mode attribute_type: auto_tagging created: '2021-05-31T09:23:34+00:00' updated: '2021-05-31T09:23:34+00:00' required: true 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 '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. '409': description: 'This response indicates a request conflict with the current state of the target resource. It can occur when the same resource is being targeted by concurrent requests. ' 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: 409 message: Resource `my_resource_code` was deleted during the process. '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 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 '429': description: 'This response indicates that the user has sent too many requests in a given amount of time. It occurs when the rate limit for API requests has been exceeded, and the client should wait before making additional requests. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 429 message: type: string description: Message explaining the error example: You have exceeded the limit of API requests per second. example: code: 429 message: You have exceeded the limit of API requests per second. delete: operationId: delete_asset_by_code x-visibility: public summary: Delete an asset description: 'This endpoint allows you to delete a given asset. This endpoint is case sensitive on the asset family code.' tags: - Asset security: - bearerToken: [] parameters: - in: path name: asset_family_code description: 'This path parameter is used to specify the unique identifier of the asset family you want to retrieve or manipulate. It is essential for identifying the specific asset family in the API requests. Ensure that the asset family code is correctly formatted and corresponds to an existing asset family in the system. ' required: true schema: type: string example: packshot - 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: '204': description: 'No content to return. Means that the deletion was successful. ' '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. 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)