openapi: 3.2.0 info: title: Akeneo API REFERENCE Asset attribute 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 attribute description: 'An asset attribute is a piece of information that can be associated with an asset. Asset attributes can be used to store various types of data, such as text, numbers, dates, or media files. They are used to define the characteristics of assets and to provide additional information about them.' paths: /api/rest/v1/asset-families/{asset_family_code}/attributes: get: operationId: get_asset_family_attributes x-visibility: public summary: Get the list of attributes of a given asset family description: This endpoint allows you to get the list of attributes of a given asset family tags: - Asset attribute 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 responses: '200': description: Return the attributes of the given asset family x-no-entity: true content: application/json: schema: type: array items: anyOf: - type: object required: - code - type properties: code: type: string description: Attribute code x-immutable: true example: model_is_wearing_size labels: type: object description: Attribute labels for each locale default: {} patternProperties: ^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$: description: Attribute label for the specified locale type: - string - 'null' example: description x-validation-rules: The `localeCode` is the code of an existing and activated locale example: en_US: description fr_FR: description type: type: string description: 'Attribute type. See [type](https://api.akeneo.com/concepts/asset-manager.html#asset-attribute) section for more details. ' enum: - text - media_link - number - media_file - single_option - multiple_options - boolean - date - record - asset_family_single_link - asset_family_multiple_links - auto_tagging x-immutable: true example: text value_per_locale: type: boolean description: Whether the attribute is localizable, i.e. can have one value by locale default: false x-immutable: true example: true value_per_channel: type: boolean description: Whether the attribute is scopable, i.e. can have one value by channel default: false x-immutable: true example: false is_required_for_completeness: type: boolean description: Whether the attribute should be part of the record's completeness calculation default: false example: false is_read_only: type: boolean description: Whether the attribute should be in read only mode only in the UI, but you can still update it with the API default: false example: false max_characters: type: - integer - 'null' description: Maximum number of characters allowed for the value of the attribute when the attribute type is `text` x-warning: Only for `text` attribute type example: 2 is_textarea: type: boolean description: Whether the UI should display a text area instead of a simple field when the attribute type is `text` default: false x-warning: Only for `text` attribute type example: false is_rich_text_editor: type: boolean description: Whether the UI should display a rich text editor instead of a simple text area when the attribute type is `text` x-validation-rules: Required when the property `is_textarea` is equal to `true` x-warning: Only for `text` attribute type example: false validation_rule: type: - string - 'null' description: Validation rule type used to validate the attribute value when the attribute type is `text` default: none x-warning: Only for `text` attribute type enum: - email - url - regular_expression - none - null example: none validation_regexp: type: - string - 'null' description: Regexp expression used to validate the attribute value when the attribute type is `text` default: null x-validation-rules: Required when the property `validation_rule` is equal to `regular_expression` x-warning: Only for `text` attribute type example: null allowed_extensions: type: array description: Extensions allowed when the attribute type is `media_file` default: [] x-warning: Only for `media_file` attribute type items: type: string example: [] max_file_size: type: - string - 'null' description: Max file size in MB when the attribute type is `media_file` default: null x-warning: Only for `media_file` attribute type example: null decimals_allowed: type: boolean description: 'Whether decimals are allowed when the attribute type is `number` ' default: false x-warning: Only for `number` attribute type example: false min_value: type: - string - 'null' description: Minimum value allowed when the attribute type is `number` default: null x-validation-rules: The minimum value must be lower than the maximum value x-warning: Only for `number` attribute type example: '1' max_value: type: - string - 'null' description: Maximum value allowed when the attribute type is `number` default: null x-validation-rules: The maximum value must be greater than the minimum value x-warning: Only for `number` attribute type example: '100' media_type: type: string description: 'For the `media_link` attribute type, it is the type of the media behind the url, to allow its preview in the PIM. For the `media_file` attribute type, it is the type of the file. ' enum: - image - pdf - youtube - vimeo - other x-warning: Only required for `media_link` and `media_file` attribute types example: image prefix: type: - string - 'null' description: 'Prefix of the `media_link` attribute type. The common url root that prefixes the link to the media. ' default: null x-warning: Only for `media_link` attribute type example: null suffix: type: - string - 'null' description: 'Suffix of the `media_link` attribute type. The common url suffix for the media. ' default: null x-warning: Only for `media_link` attribute type example: ?height=630&width=485 reference_entity: type: - string - 'null' description: Reference entity code for the `record` attribute type (see [Reference entity](https://api.akeneo.com/api-reference.html#Referenceentity)) default: null x-warning: Only for `record` attribute type example: my_reference_entity default_value: description: 'Default value for the attribute, automatically applied when creating a new asset. - For `number` attributes: a string representing the numeric value (e.g. `"42"`) - For `boolean` attributes: `true` or `false` - For `single_option` attributes: the option code (e.g. `"red"`) - For `multiple_options` attributes: an array of option codes (e.g. `["red", "blue"]`) ' default: null x-warning: Only for `number`, `boolean`, `single_option` and `multiple_options` attribute types oneOf: - type: string - type: boolean - type: array items: type: string - type: 'null' example: null asset_family_code: type: - string - 'null' description: Asset family code for the `asset_family_single_link` and `asset_family_multiple_links` attribute types default: null x-warning: Only for `asset_family_single_link` and `asset_family_multiple_links` attribute types example: packshots example: - code: model_is_wearing_size labels: en_US: Model is wearing size fr_FR: Le mannequin porte la taille type: single_option value_per_locale: false value_per_channel: false is_required_for_completeness: true default_value: s - code: media_link labels: en_US: Media link fr_FR: Lien vers le média type: media_link value_per_locale: false value_per_channel: false is_required_for_completeness: true prefix: https://my-dam.com/ suffix: ?height=630&width=485 media_type: image - code: warning_mention labels: en_US: Warning mention fr_FR: Phrase d'avertissement type: text value_per_locale: true value_per_channel: false is_required_for_completeness: false max_characters: 50 is_textarea: false is_rich_text_editor: false validation_rule: none '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/asset-families/{asset_family_code}/attributes/{code}: get: operationId: get_asset_family_attribute_by_code x-visibility: public summary: Get an attribute of a given asset family description: This endpoint allows you to get the information about a given attribute for a given asset family tags: - Asset attribute 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: '200': description: Returns the content of the asset attribute in JSON format content: application/json: schema: type: object required: - code - type properties: code: type: string description: Attribute code x-immutable: true example: model_is_wearing_size labels: type: object description: Attribute labels for each locale default: {} patternProperties: ^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$: description: Attribute label for the specified locale type: - string - 'null' example: description x-validation-rules: The `localeCode` is the code of an existing and activated locale example: en_US: description fr_FR: description type: type: string description: 'Attribute type. See [type](https://api.akeneo.com/concepts/asset-manager.html#asset-attribute) section for more details. ' enum: - text - media_link - number - media_file - single_option - multiple_options - boolean - date - record - asset_family_single_link - asset_family_multiple_links - auto_tagging x-immutable: true example: text value_per_locale: type: boolean description: Whether the attribute is localizable, i.e. can have one value by locale default: false x-immutable: true example: true value_per_channel: type: boolean description: Whether the attribute is scopable, i.e. can have one value by channel default: false x-immutable: true example: false is_required_for_completeness: type: boolean description: Whether the attribute should be part of the record's completeness calculation default: false example: false is_read_only: type: boolean description: Whether the attribute should be in read only mode only in the UI, but you can still update it with the API default: false example: false max_characters: type: - integer - 'null' description: Maximum number of characters allowed for the value of the attribute when the attribute type is `text` x-warning: Only for `text` attribute type example: 2 is_textarea: type: boolean description: Whether the UI should display a text area instead of a simple field when the attribute type is `text` default: false x-warning: Only for `text` attribute type example: false is_rich_text_editor: type: boolean description: Whether the UI should display a rich text editor instead of a simple text area when the attribute type is `text` x-validation-rules: Required when the property `is_textarea` is equal to `true` x-warning: Only for `text` attribute type example: false validation_rule: type: - string - 'null' description: Validation rule type used to validate the attribute value when the attribute type is `text` default: none x-warning: Only for `text` attribute type enum: - email - url - regular_expression - none - null example: none validation_regexp: type: - string - 'null' description: Regexp expression used to validate the attribute value when the attribute type is `text` default: null x-validation-rules: Required when the property `validation_rule` is equal to `regular_expression` x-warning: Only for `text` attribute type example: null allowed_extensions: type: array description: Extensions allowed when the attribute type is `media_file` default: [] x-warning: Only for `media_file` attribute type items: type: string example: [] max_file_size: type: - string - 'null' description: Max file size in MB when the attribute type is `media_file` default: null x-warning: Only for `media_file` attribute type example: null decimals_allowed: type: boolean description: 'Whether decimals are allowed when the attribute type is `number` ' default: false x-warning: Only for `number` attribute type example: false min_value: type: - string - 'null' description: Minimum value allowed when the attribute type is `number` default: null x-validation-rules: The minimum value must be lower than the maximum value x-warning: Only for `number` attribute type example: '1' max_value: type: - string - 'null' description: Maximum value allowed when the attribute type is `number` default: null x-validation-rules: The maximum value must be greater than the minimum value x-warning: Only for `number` attribute type example: '100' media_type: type: string description: 'For the `media_link` attribute type, it is the type of the media behind the url, to allow its preview in the PIM. For the `media_file` attribute type, it is the type of the file. ' enum: - image - pdf - youtube - vimeo - other x-warning: Only required for `media_link` and `media_file` attribute types example: image prefix: type: - string - 'null' description: 'Prefix of the `media_link` attribute type. The common url root that prefixes the link to the media. ' default: null x-warning: Only for `media_link` attribute type example: null suffix: type: - string - 'null' description: 'Suffix of the `media_link` attribute type. The common url suffix for the media. ' default: null x-warning: Only for `media_link` attribute type example: ?height=630&width=485 reference_entity: type: - string - 'null' description: Reference entity code for the `record` attribute type (see [Reference entity](https://api.akeneo.com/api-reference.html#Referenceentity)) default: null x-warning: Only for `record` attribute type example: my_reference_entity default_value: description: 'Default value for the attribute, automatically applied when creating a new asset. - For `number` attributes: a string representing the numeric value (e.g. `"42"`) - For `boolean` attributes: `true` or `false` - For `single_option` attributes: the option code (e.g. `"red"`) - For `multiple_options` attributes: an array of option codes (e.g. `["red", "blue"]`) ' default: null x-warning: Only for `number`, `boolean`, `single_option` and `multiple_options` attribute types oneOf: - type: string - type: boolean - type: array items: type: string - type: 'null' example: null asset_family_code: type: - string - 'null' description: Asset family code for the `asset_family_single_link` and `asset_family_multiple_links` attribute types default: null x-warning: Only for `asset_family_single_link` and `asset_family_multiple_links` attribute types example: packshots example: code: model_is_wearing_size labels: en_US: Model is wearing size fr_FR: Le mannequin porte la taille type: single_option value_per_locale: false value_per_channel: false is_required_for_completeness: true is_read_only: false default_value: s '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_asset_family_attribute_by_code x-visibility: public summary: Update/create an attribute of a given asset family description: 'This endpoint allows you to update a given attribute for a given asset family. Note that if the attribute does not already exist for the given asset family, it creates it.' tags: - Asset attribute 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 attribute to create or update content: application/json: schema: type: object required: - code - type properties: code: type: string description: Attribute code x-immutable: true example: model_is_wearing_size labels: type: object description: Attribute labels for each locale default: {} patternProperties: ^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$: description: Attribute label for the specified locale type: - string - 'null' example: description x-validation-rules: The `localeCode` is the code of an existing and activated locale example: en_US: description fr_FR: description type: type: string description: 'Attribute type. See [type](https://api.akeneo.com/concepts/asset-manager.html#asset-attribute) section for more details. ' enum: - text - media_link - number - media_file - single_option - multiple_options - boolean - date - record - asset_family_single_link - asset_family_multiple_links - auto_tagging x-immutable: true example: text value_per_locale: type: boolean description: Whether the attribute is localizable, i.e. can have one value by locale default: false x-immutable: true example: true value_per_channel: type: boolean description: Whether the attribute is scopable, i.e. can have one value by channel default: false x-immutable: true example: false is_required_for_completeness: type: boolean description: Whether the attribute should be part of the record's completeness calculation default: false example: false is_read_only: type: boolean description: Whether the attribute should be in read only mode only in the UI, but you can still update it with the API default: false example: false max_characters: type: - integer - 'null' description: Maximum number of characters allowed for the value of the attribute when the attribute type is `text` x-warning: Only for `text` attribute type example: 2 is_textarea: type: boolean description: Whether the UI should display a text area instead of a simple field when the attribute type is `text` default: false x-warning: Only for `text` attribute type example: false is_rich_text_editor: type: boolean description: Whether the UI should display a rich text editor instead of a simple text area when the attribute type is `text` x-validation-rules: Required when the property `is_textarea` is equal to `true` x-warning: Only for `text` attribute type example: false validation_rule: type: - string - 'null' description: Validation rule type used to validate the attribute value when the attribute type is `text` default: none x-warning: Only for `text` attribute type enum: - email - url - regular_expression - none - null example: none validation_regexp: type: - string - 'null' description: Regexp expression used to validate the attribute value when the attribute type is `text` default: null x-validation-rules: Required when the property `validation_rule` is equal to `regular_expression` x-warning: Only for `text` attribute type example: null allowed_extensions: type: array description: Extensions allowed when the attribute type is `media_file` default: [] x-warning: Only for `media_file` attribute type items: type: string example: [] max_file_size: type: - string - 'null' description: Max file size in MB when the attribute type is `media_file` default: null x-warning: Only for `media_file` attribute type example: null decimals_allowed: type: boolean description: 'Whether decimals are allowed when the attribute type is `number` ' default: false x-warning: Only for `number` attribute type example: false min_value: type: - string - 'null' description: Minimum value allowed when the attribute type is `number` default: null x-validation-rules: The minimum value must be lower than the maximum value x-warning: Only for `number` attribute type example: '1' max_value: type: - string - 'null' description: Maximum value allowed when the attribute type is `number` default: null x-validation-rules: The maximum value must be greater than the minimum value x-warning: Only for `number` attribute type example: '100' media_type: type: string description: 'For the `media_link` attribute type, it is the type of the media behind the url, to allow its preview in the PIM. For the `media_file` attribute type, it is the type of the file. ' enum: - image - pdf - youtube - vimeo - other x-warning: Only required for `media_link` and `media_file` attribute types example: image prefix: type: - string - 'null' description: 'Prefix of the `media_link` attribute type. The common url root that prefixes the link to the media. ' default: null x-warning: Only for `media_link` attribute type example: null suffix: type: - string - 'null' description: 'Suffix of the `media_link` attribute type. The common url suffix for the media. ' default: null x-warning: Only for `media_link` attribute type example: ?height=630&width=485 reference_entity: type: - string - 'null' description: Reference entity code for the `record` attribute type (see [Reference entity](https://api.akeneo.com/api-reference.html#Referenceentity)) default: null x-warning: Only for `record` attribute type example: my_reference_entity default_value: description: 'Default value for the attribute, automatically applied when creating a new asset. - For `number` attributes: a string representing the numeric value (e.g. `"42"`) - For `boolean` attributes: `true` or `false` - For `single_option` attributes: the option code (e.g. `"red"`) - For `multiple_options` attributes: an array of option codes (e.g. `["red", "blue"]`) ' default: null x-warning: Only for `number`, `boolean`, `single_option` and `multiple_options` attribute types oneOf: - type: string - type: boolean - type: array items: type: string - type: 'null' example: null asset_family_code: type: - string - 'null' description: Asset family code for the `asset_family_single_link` and `asset_family_multiple_links` attribute types default: null x-warning: Only for `asset_family_single_link` and `asset_family_multiple_links` attribute types example: packshots example: code: model_is_wearing_size labels: en_US: Model is wearing size fr_FR: Le mannequin porte la taille type: single_option value_per_locale: false value_per_channel: false is_required_for_completeness: true is_read_only: false default_value: s 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 '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 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 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)