REST API reference
Complete reference on how to handle Akeneo PIM resources
Products
Product [uuid]
This API provides two endpoints for interacting with products:
- Product (UUID): We strongly recommend using this endpoint for its reliability and flexibility. UUIDs, or Universally Unique Identifiers, are guaranteed to be unique and never change, even if other product identifiers like SKUs are modified. This ensures consistent product identification regardless of future changes. Additionally, UUIDs allow interaction with products that lack a traditional identifier.
- Product (Identifier): This endpoint is useful when you already have a product identifier within your systems. This identifier, which could be a SKU or internal code, can be used to directly interact with the corresponding product in our API. This simplifies integration for workflows that rely on existing product identification methods.
Get list of products
This endpoint allows you to get a list of products. Products are paginated and they can be filtered. Permissions based on your user groups are applied to the set of products you request.
REQUEST
get /api/rest/v1/products-uuid
Path parameters
Ø
Query parameters
search
(string)
• Filter products, for more details see the Filters section
scope
(string)
• Filter product values to return scopable attributes for the given channel as well as the non localizable/non scopable attributes.
It is useful for retrieving product information specific to a particular sales channel, which is essential for channel-specific applications.
For more details see the Filter product values via channel section.
locales
(string)
• Filter product values to return localizable attributes for the given locales as well as the non localizable/non scopable attributes.
It is useful for retrieving product information in specific languages, which is essential for multi-locale applications.
For more details see the Filter product values via locale section.
attributes
(string)
• Filter product values to only return those concerning the given attributes.
It is useful for limiting the response to specific attributes, reducing payload size and improving performance.
For more details see the Filter product values via attributes section.
pagination_type
(string,
page
by default)
• Specify which pagination method to use for navigating through large datasets.
It is useful for choosing between different pagination strategies based on your specific use case and performance requirements.
See Pagination section for more details.
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
search_after
(string,
cursor to the first page
by default)
• 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 section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
search_scope
(string)
• Filter scopes based on specific criteria.
If you need to filter on several attributes on the same scope, you can use this parameter, to avoid repeating yourself for each attribute.
For more details see the Filters section.
search_locale
(string)
• Filter locales based on specific criteria.
If you need to filter on several attributes on the same locale, you can use this parameter, to avoid repeating yourself for each attribute.
For more details see the Filters section.
convert_measurements
(boolean)
• Convert values of measurement attributes to the unit configured in the channel provided by the scope parameter.
When set to true, the response will include measurement values converted to the channel's configured units.
This is useful for displaying measurement values in the appropriate units for different channels or regions.
If set to false, the response will return measurement values in their original units, which can improve performance.
Therefore, this parameter requires the scope parameter to be provided.
with_count
(boolean)
• Return the count of items in the response.
Be careful with that, on a big catalog, it can decrease performance in a significant way.
It is useful for understanding the size of the dataset being returned, especially when dealing with large collections.
Use it judiciously to avoid performance issues.
with_attribute_options
(boolean)
• Return labels of attribute options in the response.
When set to true, the response will include human-readable labels for attribute options alongside their codes.
This is useful for displaying human-readable labels instead of just option codes, which improves the user experience in frontend applications.
If set to false, the response will only include option codes, which can improve performance.
See the linked_data format section for more details.
with_asset_share_links
(boolean)
• Return asset collection share link URLs in the response.
When set to true, the response will include direct URLs to asset collections for sharing purposes.
This is useful for accessing direct links to asset collections, which can be used for sharing or external integrations.
If set to false, the response will not include share links, which can improve performance.
See the linked_data format for more details.
with_quality_scores
(boolean)
• Return product quality scores in the response.
When set to true, the response will include quality score information for each product.
This is useful for assessing and monitoring product data quality, which is essential for maintaining high data standards and improving product information.
If set to false, the response will not include quality scores, which can improve performance.
with_completenesses
(boolean)
• Return product completenesses information in the response.
When set to true, the response will include detailed completeness information for each product.
This is useful for understanding the data quality and completeness of products, which is essential for product management and quality assurance.
If set to false, the response will not include completeness information, which can improve performance.
with_root_parent
(boolean)
• Return the root parent product model code of a variant in the response.
When set to true, the response will include the root parent product model code for each variant product.
This is useful for understanding the hierarchical relationship between product variants and their parent models, which is essential for product catalog navigation.
If set to false, the response will not include parent model information, which can improve performance.
with_workflow_execution_statuses
(boolean)
•
Return an array of workflow_execution_statuses directly associated with the requested entity (product or product model) in the response. Statuses are level-specific and are not inherited from parent models. For a complete overview of a variant product, you must query the variant itself and its parent model(s) in separate requests. Each workflow object contains:
- The overall execution status (e.g., in_progress, completed).
- A list of all associated tasks.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns products paginated. The response is paginated and includes links to navigate through the pages.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
items_count
(integer)
• Total number of items (only if with_count parameter is set to true)
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
uuid (string)
• Product UUID
identifier (string)
• Product identifier, i.e. the value of the only pim_catalog_identifier attribute
enabled (boolean)
• Whether the product is enabled
family (string,null)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories (array [string])
• Codes of the categories in which the product is classified
• Codes of the categories in which the product is classified
groups (array [string])
• Codes of the groups to which the product belong.
Each string of the array is equal to an existing group code.
• Codes of the groups to which the product belong.
Each string of the array is equal to an existing group code.
parent (string,null)
• Code of the parent product model when the product is a variant
root_parent (string)
• Code of the root parent product model when the product is a variant
(only available when the with_root_parent is set to true).
values (object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations (object)
: {
{^\w+$} (object)
: {
groups
(array [string]) • Array of groups codes with which the product is in relation
products
(array [string]) • Array of product identifiers with which the product is in relation
product_models
(array [string]) • Array of product model codes with which the product is in relation
}
}
quantified_associations (object)
: {
{^\w+$} (object)
: {
products
(array [object]) • Array of objects containing product uuids and quantities with which the product is in relation
product_models
(array [object]) • Array of objects containing product model codes and quantities with which the product is in relation
}
}
created (string)
• Date of creation
updated (string)
• Date of the last update
metadata (object)
: {
workflow_status (string)
• Status of the product regarding the user permissions
}
quality_scores (array [object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
completenesses (array [object])
: [
{
scope (string) • Channel code for which the completenesses score is calculated
locale (string) • Channel code for which the completenesses score is calculated
data (integer) • Completenesses score value for the given channel/locale combination
}
]
workflow_execution_statuses (array [object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array [object]) • Tasks associated with the workflow execution
}
]
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products-uuid?page=3&with_count=true&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true&with_workflow_execution_statuses=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/products-uuid?page=1&with_count=true&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true&with_workflow_execution_statuses=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/products-uuid?page=2&with_count=true&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true&with_workflow_execution_statuses=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/products-uuid?page=4&with_count=true&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true&with_workflow_execution_statuses=true"
}
},
"current_page": 3,
"items_count": 3,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products/top"
}
},
"uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"root_parent": "null",
"values": {
"sku": [
{
"data": "top",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_identifier"
}
],
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"size": [
{
"data": "m",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"collection": [
{
"data": [
"winter_2016"
],
"locale": null,
"scope": null,
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
},
"attribute_type": "pim_catalog_multiselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"quantity": 2
},
{
"uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
],
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
]
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products/cap"
}
},
"uuid": "aec6780b-c813-4bd7-8e24-1a8574471576",
"family": "caps",
"groups": [],
"parent": null,
"root_parent": "null",
"categories": [
"summer_collection"
],
"enabled": true,
"values": {
"sku": [
{
"data": "cap",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_identifier"
}
],
"name": [
{
"data": "Cap",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Casquette",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"data": [
{
"amount": "20",
"currency": "EUR"
},
{
"amount": "20",
"currency": "USD"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:0",
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 20
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 30
},
{
"scope": "tablet",
"locale": "en_US",
"data": 55
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 70
}
],
"workflow_execution_statuses": []
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products/sweat"
}
},
"uuid": "93f14b03-5ed3-4f23-87c6-ae3806041b6a",
"family": null,
"groups": [],
"parent": null,
"root_parent": "null",
"categories": [
"winter_collection"
],
"enabled": true,
"values": {
"sku": [
{
"data": "sweat",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_identifier"
}
]
},
"created": "2016-06-23T11:24:44+02:00",
"updated": "2016-06-23T11:24:44+02:00",
"associations": {},
"quantified_associations": {},
"quality_scores": [],
"completenesses": [],
"workflow_execution_statuses": []
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Create a new product
This endpoint allows you to create a new product. Permissions based on your user groups are applied to the product you try to create. If no uuid is provided, the PIM will generate one for you.
REQUEST
post /api/rest/v1/products-uuid
Path parameters
Ø
Query parameters
create_missing_options
(string)
• When present in the query string (regardless of value), automatically creates missing attribute options during product/product model creation or update.
This only works for simple select and multi select attributes that have the enable_option_creation_during_import property set to true (configurable via the Attribute API).
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
uuid
(string)
• Product UUID
enabled
(boolean,
true by default)
• Whether the product is enabled
family
(string,null,
null only in the case of a non variant product by default)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories
(array[string],
[] by default)
• Codes of the categories in which the product is classified
groups
(array[string],
[] by default)
• Codes of the groups to which the product belong
parent
(string,null,
null by default)
• Code of the parent product model when the product is a variant
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array)
• Array of groups codes with which the product is in relation
products
(array)
• Array of product identifiers with which the product is in relation
product_models
(array)
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array)
• Array of objects containing product uuids and quantities with which the product is in relation
product_models
(array)
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
}
Example
{
"uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"values": {
"sku": [
{
"data": "top",
"locale": null,
"scope": null
}
],
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"locale": null,
"scope": null
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"data": "m",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"data": [
"winter_2016"
],
"locale": null,
"scope": null,
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
}
}
]
},
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"quantity": 2
},
{
"uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
}
}RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Update/create several products
This endpoint allows you to update and/or create several products at once. Learn more about Update behavior. Note that if no product exists for the given uuid, it creates it. Permissions based on your user groups are applied to the products you try to update. It may result in the creation of drafts if you only have edit rights through the product's categories.
REQUEST
patch /api/rest/v1/products-uuid
Path parameters
Ø
Query parameters
create_missing_options
(string)
• When present in the query string (regardless of value), automatically creates missing attribute options during product/product model creation or update.
This only works for simple select and multi select attributes that have the enable_option_creation_during_import property set to true (configurable via the Attribute API).
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is a product in JSON standard format. Modifications to existing products can be specified using additional keys such as `add_categories` and `remove_categories`.
{
uuid
(string)
• Product UUID
identifier
(string)
• Product identifier, i.e. the value of the only pim_catalog_identifier attribute
enabled
(boolean,
true by default)
• Whether the product is enabled
family
(string,null,
null only in the case of a non variant product by default)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories
(array[string],
[] by default)
• Codes of the categories in which the product is classified
add_categories
(array[string],
[] by default)
• Codes of the categories to add to the product.
Existing categories will be preserved.
remove_categories
(array[string],
[] by default)
• Codes of the categories to remove from the product.
Other categories will be preserved.d
groups
(array[string],
[] by default)
• Codes of the groups to which the product belong
parent
(string,null,
null by default)
• Code of the parent product model when the product is a variant
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array)
• Array of groups codes with which the product is in relation
products
(array)
• Array of product identifiers with which the product is in relation
product_models
(array)
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array)
• Array of objects containing product uuids and quantities with which the product is in relation
product_models
(array)
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product regarding the user permissions
}
quality_scores
(array[object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
completenesses
(array[object])
: [
{
scope (string) • Channel code for which the completenesses score is calculated
locale (string) • Channel code for which the completenesses score is calculated
data (integer) • Completenesses score value for the given channel/locale combination
}
]
workflow_execution_statuses
(array[object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array[object]) • Tasks associated with the workflow execution
}
]
}
Example
{"uuid":"fc24e6c3-933c-4a93-8a81-e5c703d134d5","values":{"description":[{"scope":"ecommerce","locale":"en_US","data":"My amazing cap"}]}}
{"uuid":"573dd613-0c7f-4143-83d5-63cc5e535966","values":{"sku":[{"data":"updated_sku","locale":null,"scope":null}]}, "group":["promotion"]}
{"uuid":"25566245-55c3-42ce-86d9-8610ac459fa8","values":{"sku":[{"data":"new_product","locale":null,"scope":null}]},"family":"clothes"}
RESPONSES
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
{
line
(integer)
• Line number
uuid
(string)
• Product uuid
status_code
(integer)
• HTTP status code, see Client errors to understand the meaning of each code
message
(string)
• Message explaining the error
}
Example
{"line":1,"uuid":"fc24e6c3-933c-4a93-8a81-e5c703d134d5","status_code":204}
{"line":2,"uuid":"573dd613-0c7f-4143-83d5-63cc5e535966","status_code":422,"message":"Property \"group\" does not exist."}
{"line":3,"uuid":"25566245-55c3-42ce-86d9-8610ac459fa8","status_code":201}
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Search list of products
This endpoint allows you to search for products that match the filters provided in the request body. Products are paginated and can be filtered by scope, locales, attributes, and other criteria. User-group-based permissions are applied to the products you request.
Important limitations
- The maximum number of attributes in the request body is 800.
- The maximum number of search criteria is 20.
- The maximum number of items in an array (e.g., values for filters like
INorNOT IN) is 800.
REQUEST
post /api/rest/v1/products-uuid/search
Path parameters
Ø
Query parameters
pagination_type
(string,
page
by default)
• Specify which pagination method to use for navigating through large datasets.
It is useful for choosing between different pagination strategies based on your specific use case and performance requirements.
See Pagination section for more details.
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
search_after
(string,
cursor to the first page
by default)
• 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 section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
with_count
(boolean)
• Return the count of items in the response.
Be careful with that, on a big catalog, it can decrease performance in a significant way.
It is useful for understanding the size of the dataset being returned, especially when dealing with large collections.
Use it judiciously to avoid performance issues.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
search
(string)
• Stringified JSON to filter products,
for more details see the Filters section.
scope
(string)
• Filter product values to return scopable attributes for the given channel as well as the non localizable/non scopable attributes,
for more details see the Filter product values via channel section.
locales
(string)
• Filter product values to return localizable attributes for the given locales as well as the non localizable/non scopable attributes,
for more details see the Filter product values via locale section.
attributes
(string)
• Filter product values to only return those concerning the given attributes,
for more details see the Filter product values via attributes section.
convert_measurements
(boolean)
• Convert values of measurement attributes to the unit configured in the channel provided by the parameter "scope".
Therefore, this parameter requires the scope parameter to be provided.
with_attribute_options
(boolean)
• Return labels of attribute options in the response.
See the linked_data format section for more details.
with_asset_share_links
(boolean)
• Whether to return asset collection share link URLs in the response.
See the linked_data format for more details.
with_quality_scores__products
(boolean)
• Return product quality scores in the response
with_completenesses
(boolean)
• Return product completenesses in the response
with_workflow_execution_statuses
(boolean)
• Return an array of workflow_execution_statuses in the response
}
Example
{
"scope": "ecommerce",
"locales": "en_US",
"search": "{\"completeness\":[{\"operator\": \"=\",\"value\": 100,\"scope\":\"ecommerce\"}]}",
"attributes": "description, name",
"with_attribute_options": false,
"with_asset_share_links": true,
"with_quality_scores__products": true,
"with_completenesses": true
}RESPONSES
Returns products paginated. The response is paginated and includes links to navigate through the pages.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
items_count
(integer)
• Total number of items (only if with_count parameter is set to true)
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
uuid (string)
• Product UUID
identifier (string)
• Product identifier, i.e. the value of the only pim_catalog_identifier attribute
enabled (boolean)
• Whether the product is enabled
family (string,null)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories (array [string])
• Codes of the categories in which the product is classified
• Codes of the categories in which the product is classified
groups (array [string])
• Codes of the groups to which the product belong.
Each string of the array is equal to an existing group code.
• Codes of the groups to which the product belong.
Each string of the array is equal to an existing group code.
parent (string,null)
• Code of the parent product model when the product is a variant
root_parent (string)
• Code of the root parent product model when the product is a variant
(only available when the with_root_parent is set to true).
values (object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations (object)
: {
{^\w+$} (object)
: {
groups
(array [string]) • Array of groups codes with which the product is in relation
products
(array [string]) • Array of product identifiers with which the product is in relation
product_models
(array [string]) • Array of product model codes with which the product is in relation
}
}
quantified_associations (object)
: {
{^\w+$} (object)
: {
products
(array [object]) • Array of objects containing product uuids and quantities with which the product is in relation
product_models
(array [object]) • Array of objects containing product model codes and quantities with which the product is in relation
}
}
created (string)
• Date of creation
updated (string)
• Date of the last update
metadata (object)
: {
workflow_status (string)
• Status of the product regarding the user permissions
}
quality_scores (array [object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
completenesses (array [object])
: [
{
scope (string) • Channel code for which the completenesses score is calculated
locale (string) • Channel code for which the completenesses score is calculated
data (integer) • Completenesses score value for the given channel/locale combination
}
]
workflow_execution_statuses (array [object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array [object]) • Tasks associated with the workflow execution
}
]
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products-uuid?page=3&with_count=true&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true&with_workflow_execution_statuses=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/products-uuid?page=1&with_count=true&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true&with_workflow_execution_statuses=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/products-uuid?page=2&with_count=true&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true&with_workflow_execution_statuses=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/products-uuid?page=4&with_count=true&limit=3&with_quality_scores=true&with_completenesses=true&with_attribute_options=true&with_workflow_execution_statuses=true"
}
},
"current_page": 3,
"items_count": 3,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products/top"
}
},
"uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"root_parent": "null",
"values": {
"sku": [
{
"data": "top",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_identifier"
}
],
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"size": [
{
"data": "m",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"collection": [
{
"data": [
"winter_2016"
],
"locale": null,
"scope": null,
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
},
"attribute_type": "pim_catalog_multiselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"quantity": 2
},
{
"uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
],
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
]
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products/cap"
}
},
"uuid": "aec6780b-c813-4bd7-8e24-1a8574471576",
"family": "caps",
"groups": [],
"parent": null,
"root_parent": "null",
"categories": [
"summer_collection"
],
"enabled": true,
"values": {
"sku": [
{
"data": "cap",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_identifier"
}
],
"name": [
{
"data": "Cap",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Casquette",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"data": [
{
"amount": "20",
"currency": "EUR"
},
{
"amount": "20",
"currency": "USD"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:0",
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 20
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 30
},
{
"scope": "tablet",
"locale": "en_US",
"data": 55
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 70
}
],
"workflow_execution_statuses": []
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products/sweat"
}
},
"uuid": "93f14b03-5ed3-4f23-87c6-ae3806041b6a",
"family": null,
"groups": [],
"parent": null,
"root_parent": "null",
"categories": [
"winter_collection"
],
"enabled": true,
"values": {
"sku": [
{
"data": "sweat",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_identifier"
}
]
},
"created": "2016-06-23T11:24:44+02:00",
"updated": "2016-06-23T11:24:44+02:00",
"associations": {},
"quantified_associations": {},
"quality_scores": [],
"completenesses": [],
"workflow_execution_statuses": []
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Get a product
This endpoint allows you to get the information about a given product. Permissions based on your user groups are applied to the product you request.
REQUEST
get /api/rest/v1/products-uuid/{uuid}
Path parameters
uuid
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the UUID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
with_attribute_options
(boolean)
• Return labels of attribute options in the response.
When set to true, the response will include human-readable labels for attribute options alongside their codes.
This is useful for displaying human-readable labels instead of just option codes, which improves the user experience in frontend applications.
If set to false, the response will only include option codes, which can improve performance.
See the linked_data format section for more details.
with_asset_share_links
(boolean)
• Return asset collection share link URLs in the response.
When set to true, the response will include direct URLs to asset collections for sharing purposes.
This is useful for accessing direct links to asset collections, which can be used for sharing or external integrations.
If set to false, the response will not include share links, which can improve performance.
See the linked_data format for more details.
with_quality_scores
(boolean)
• Return product quality scores in the response.
When set to true, the response will include quality score information for each product.
This is useful for assessing and monitoring product data quality, which is essential for maintaining high data standards and improving product information.
If set to false, the response will not include quality scores, which can improve performance.
with_completenesses
(boolean)
• Return product completenesses information in the response.
When set to true, the response will include detailed completeness information for each product.
This is useful for understanding the data quality and completeness of products, which is essential for product management and quality assurance.
If set to false, the response will not include completeness information, which can improve performance.
with_root_parent
(boolean)
• Return the root parent product model code of a variant in the response.
When set to true, the response will include the root parent product model code for each variant product.
This is useful for understanding the hierarchical relationship between product variants and their parent models, which is essential for product catalog navigation.
If set to false, the response will not include parent model information, which can improve performance.
with_workflow_execution_statuses
(boolean)
•
Return an array of workflow_execution_statuses directly associated with the requested entity (product or product model) in the response. Statuses are level-specific and are not inherited from parent models. For a complete overview of a variant product, you must query the variant itself and its parent model(s) in separate requests. Each workflow object contains:
- The overall execution status (e.g., in_progress, completed).
- A list of all associated tasks.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the product in JSON standard format
Body Format application/json
{
uuid
(string)
• Product UUID
identifier
(string)
• Product identifier, i.e. the value of the only pim_catalog_identifier attribute
enabled
(boolean)
• Whether the product is enabled
family
(string,null)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories
(array [string])
• Codes of the categories in which the product is classified
groups
(array [string])
• Codes of the groups to which the product belong.
Each string of the array is equal to an existing group code.
parent
(string,null)
• Code of the parent product model when the product is a variant
root_parent
(string)
• Code of the root parent product model when the product is a variant
(only available when the with_root_parent is set to true).
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array[string])
• Array of groups codes with which the product is in relation
products
(array[string])
• Array of product identifiers with which the product is in relation
product_models
(array[string])
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array[object])
• Array of objects containing product uuids and quantities with which the product is in relation
product_models
(array[object])
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product regarding the user permissions
}
quality_scores
(array [object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
completenesses
(array [object])
: [
{
scope (string) • Channel code for which the completenesses score is calculated
locale (string) • Channel code for which the completenesses score is calculated
data (integer) • Completenesses score value for the given channel/locale combination
}
]
workflow_execution_statuses
(array [object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array) • Tasks associated with the workflow execution
}
]
}
Example
{
"uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"root_parent": "null",
"values": {
"sku": [
{
"data": "top",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_identifier"
}
],
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"size": [
{
"data": "m",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"collection": [
{
"data": [
"winter_2016"
],
"locale": null,
"scope": null,
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
},
"attribute_type": "pim_catalog_multiselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"quantity": 2
},
{
"uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
],
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
]
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Update/create a product
This endpoint allows you to update a given product. Learn more about Update behavior. Note that if no product exists for the given uuid, it creates it. In the Enterprise Edition, permissions based on your user groups are applied to the product you try to update. It may result in the creation of a draft if you only have edit rights through the product's categories.
REQUEST
patch /api/rest/v1/products-uuid/{uuid}
Path parameters
uuid
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the UUID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
create_missing_options
(string)
• When present in the query string (regardless of value), automatically creates missing attribute options during product/product model creation or update.
This only works for simple select and multi select attributes that have the enable_option_creation_during_import property set to true (configurable via the Attribute API).
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
uuid
(string)
• Product UUID
identifier
(string)
• Product identifier, i.e. the value of the only pim_catalog_identifier attribute
enabled
(boolean,
true by default)
• Whether the product is enabled
family
(string,null,
null only in the case of a non variant product by default)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories
(array[string],
[] by default)
• Codes of the categories in which the product is classified
add_categories
(array[string],
[] by default)
• Codes of the categories to add to the product.
Existing categories will be preserved.
remove_categories
(array[string],
[] by default)
• Codes of the categories to remove from the product.
Other categories will be preserved.d
groups
(array[string],
[] by default)
• Codes of the groups to which the product belong
parent
(string,null,
null by default)
• Code of the parent product model when the product is a variant
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array)
• Array of groups codes with which the product is in relation
products
(array)
• Array of product identifiers with which the product is in relation
product_models
(array)
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array)
• Array of objects containing product uuids and quantities with which the product is in relation
product_models
(array)
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product regarding the user permissions
}
quality_scores
(array[object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
completenesses
(array[object])
: [
{
scope (string) • Channel code for which the completenesses score is calculated
locale (string) • Channel code for which the completenesses score is calculated
data (integer) • Completenesses score value for the given channel/locale combination
}
]
workflow_execution_statuses
(array[object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array[object]) • Tasks associated with the workflow execution
}
]
}
Example
{
"uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"root_parent": "null",
"values": {
"sku": [
{
"data": "top",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_identifier"
}
],
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"size": [
{
"data": "m",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"collection": [
{
"data": [
"winter_2016"
],
"locale": null,
"scope": null,
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
},
"attribute_type": "pim_catalog_multiselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"quantity": 2
},
{
"uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
],
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
]
}RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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 • URI of the updated resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Delete a product
This endpoint allows you to delete a given product. Permissions based on your user groups are applied to the product you try to delete.
REQUEST
delete /api/rest/v1/products-uuid/{uuid}
Path parameters
uuid
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the UUID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
No content to return. Means that the deletion was successful.
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Submit a draft for approval
This endpoint allows you to submit a draft for approval
REQUEST
post /api/rest/v1/products-uuid/{uuid}/proposal
Path parameters
uuid
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the UUID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Get a draft
This endpoint allows you to get the information about a given draft
REQUEST
get /api/rest/v1/products-uuid/{uuid}/draft
Path parameters
uuid
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the UUID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the product in JSON standard format
Body Format application/json
{
uuid
(string)
• Product UUID
identifier
(string)
• Product identifier, i.e. the value of the only pim_catalog_identifier attribute
enabled
(boolean)
• Whether the product is enabled
family
(string,null)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories
(array [string])
• Codes of the categories in which the product is classified
groups
(array [string])
• Codes of the groups to which the product belong.
Each string of the array is equal to an existing group code.
parent
(string,null)
• Code of the parent product model when the product is a variant
root_parent
(string)
• Code of the root parent product model when the product is a variant
(only available when the with_root_parent is set to true).
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array[string])
• Array of groups codes with which the product is in relation
products
(array[string])
• Array of product identifiers with which the product is in relation
product_models
(array[string])
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array[object])
• Array of objects containing product uuids and quantities with which the product is in relation
product_models
(array[object])
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product regarding the user permissions
}
quality_scores
(array [object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
completenesses
(array [object])
: [
{
scope (string) • Channel code for which the completenesses score is calculated
locale (string) • Channel code for which the completenesses score is calculated
data (integer) • Completenesses score value for the given channel/locale combination
}
]
workflow_execution_statuses
(array [object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array) • Tasks associated with the workflow execution
}
]
}
Example
{
"uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"parent": null,
"root_parent": "null",
"values": {
"sku": [
{
"data": "top",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_identifier"
}
],
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"size": [
{
"data": "m",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"collection": [
{
"data": [
"winter_2016"
],
"locale": null,
"scope": null,
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
},
"attribute_type": "pim_catalog_multiselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"quantity": 2
},
{
"uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
],
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
]
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Product [identifier]
This API provides two endpoints for interacting with products:
- Product (UUID): We strongly recommend using this endpoint for its reliability and flexibility. UUIDs, or Universally Unique Identifiers, are guaranteed to be unique and never change, even if other product identifiers like SKUs are modified. This ensures consistent product identification regardless of future changes. Additionally, UUIDs allow interaction with products that lack a traditional identifier.
- Product (Identifier): This endpoint is useful when you already have a product identifier within your systems. This identifier, which could be a SKU or internal code, can be used to directly interact with the corresponding product in our API. This simplifies integration for workflows that rely on existing product identification methods.
Get list of products
This endpoint allows you to get a list of products. Products are paginated and they can be filtered. Permissions based on your user groups are applied to the set of products you request.
REQUEST
get /api/rest/v1/products
Path parameters
Ø
Query parameters
search
(string)
• Filter products,
for more details see the Filters section.
scope
(string)
• Filter product values to return scopable attributes for the given channel as well as the non localizable/non scopable attributes.
It is useful for retrieving product information specific to a particular sales channel, which is essential for channel-specific applications.
For more details see the Filter product values via channel section.
locales
(string)
• Filter product values to return localizable attributes for the given locales as well as the non localizable/non scopable attributes.
It is useful for retrieving product information in specific languages, which is essential for multi-locale applications.
For more details see the Filter product values via locale section.
attributes
(string)
• Filter product values to only return those concerning the given attributes.
It is useful for limiting the response to specific attributes, reducing payload size and improving performance.
For more details see the Filter product values via attributes section.
pagination_type
(string,
page
by default)
• Specify which pagination method to use for navigating through large datasets.
It is useful for choosing between different pagination strategies based on your specific use case and performance requirements.
See Pagination section for more details.
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
search_after
(string,
cursor to the first page
by default)
• 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 section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
search_scope
(string)
• Filter scopes based on specific criteria.
If you need to filter on several attributes on the same scope, you can use this parameter, to avoid repeating yourself for each attribute.
For more details see the Filters section.
search_locale
(string)
• Filter locales based on specific criteria.
If you need to filter on several attributes on the same locale, you can use this parameter, to avoid repeating yourself for each attribute.
For more details see the Filters section.
convert_measurements
(boolean)
• Convert values of measurement attributes to the unit configured in the channel provided by the scope parameter.
When set to true, the response will include measurement values converted to the channel's configured units.
This is useful for displaying measurement values in the appropriate units for different channels or regions.
If set to false, the response will return measurement values in their original units, which can improve performance.
Therefore, this parameter requires the scope parameter to be provided.
with_count
(boolean)
• Return the count of items in the response.
Be careful with that, on a big catalog, it can decrease performance in a significant way.
It is useful for understanding the size of the dataset being returned, especially when dealing with large collections.
Use it judiciously to avoid performance issues.
with_attribute_options
(boolean)
• Return labels of attribute options in the response.
When set to true, the response will include human-readable labels for attribute options alongside their codes.
This is useful for displaying human-readable labels instead of just option codes, which improves the user experience in frontend applications.
If set to false, the response will only include option codes, which can improve performance.
See the linked_data format section for more details.
with_asset_share_links
(boolean)
• Return asset collection share link URLs in the response.
When set to true, the response will include direct URLs to asset collections for sharing purposes.
This is useful for accessing direct links to asset collections, which can be used for sharing or external integrations.
If set to false, the response will not include share links, which can improve performance.
See the linked_data format for more details.
with_quality_scores
(boolean)
• Return product quality scores in the response.
When set to true, the response will include quality score information for each product.
This is useful for assessing and monitoring product data quality, which is essential for maintaining high data standards and improving product information.
If set to false, the response will not include quality scores, which can improve performance.
with_completenesses
(boolean)
• Return product completenesses information in the response.
When set to true, the response will include detailed completeness information for each product.
This is useful for understanding the data quality and completeness of products, which is essential for product management and quality assurance.
If set to false, the response will not include completeness information, which can improve performance.
with_workflow_execution_statuses
(boolean)
•
Return an array of workflow_execution_statuses directly associated with the requested entity (product or product model) in the response. Statuses are level-specific and are not inherited from parent models. For a complete overview of a variant product, you must query the variant itself and its parent model(s) in separate requests. Each workflow object contains:
- The overall execution status (e.g., in_progress, completed).
- A list of all associated tasks.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns products paginated. The response is paginated and includes links to navigate through the pages.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
items_count
(integer)
• Total number of items (only if with_count parameter is set to true)
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
uuid (string)
• Product UUID
identifier (string)
• Product identifier, i.e. the value of the only pim_catalog_identifier attribute
enabled (boolean)
• Whether the product is enabled
family (string,null)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories (array [string])
• Codes of the categories in which the product is classified.
• Codes of the categories in which the product is classified.
groups (array [string])
• Codes of the groups to which the product belong.
Each string of the array is equal to an existing group code.
• Codes of the groups to which the product belong.
Each string of the array is equal to an existing group code.
parent (string,null)
• Code of the parent product model when the product is a variant
values (object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations (object)
: {
{^\w+$} (object)
: {
groups
(array [string]) • Array of groups codes with which the product is in relation
products
(array [string]) • Array of product identifiers with which the product is in relation
product_models
(array [string]) • Array of product model codes with which the product is in relation
}
}
quantified_associations (object)
: {
{^\w+$} (object)
: {
products
(array [object]) • Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array [object]) • Array of objects containing product model codes and quantities with which the product is in relation
}
}
created (string)
• Date of creation
updated (string)
• Date of the last update
metadata (object)
: {
workflow_status (string)
• Status of the product regarding the user permissions
}
quality_scores (array [object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
completenesses (array [object])
: [
{
scope (string) • Channel code for which the completenesses score is calculated
locale (string) • Channel code for which the completenesses score is calculated
data (integer) • Completenesses score value for the given channel/locale combination
}
]
workflow_execution_statuses (array [object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array [object]) • Tasks associated with the workflow execution
}
]
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=3&limit=3&with_count=true&with_quality_scores=true&with_completenesses=true&with_attribute_options=true&with_workflow_execution_statuses=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=1&limit=3&with_count=true&with_quality_scores=true&with_completenesses=true&with_attribute_options=true&with_workflow_execution_statuses=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=2&limit=3&with_count=true&with_quality_scores=true&with_completenesses=true&with_attribute_options=true&with_workflow_execution_statuses=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/products?page=4&limit=3&with_count=true&with_quality_scores=true&with_completenesses=true&with_attribute_options=true&with_workflow_execution_statuses=true"
}
},
"current_page": 3,
"items_count": 3,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products/top"
}
},
"uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"identifier": "top",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"size": [
{
"data": "m",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"collection": [
{
"data": [
"winter_2016"
],
"locale": null,
"scope": null,
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
},
"attribute_type": "pim_catalog_multiselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
},
{
"identifier": "shoes",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
],
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
]
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products/cap"
}
},
"uuid": "aec6780b-c813-4bd7-8e24-1a8574471576",
"identifier": "cap",
"family": "caps",
"groups": [],
"parent": null,
"categories": [
"summer_collection"
],
"enabled": true,
"values": {
"name": [
{
"data": "Cap",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Casquette",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Cap unisex",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Casquette unisexe",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"data": [
{
"amount": "20",
"currency": "EUR"
},
{
"amount": "20",
"currency": "USD"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:0",
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 20
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 30
},
{
"scope": "tablet",
"locale": "en_US",
"data": 55
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 70
}
],
"workflow_execution_statuses": []
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/products/sweat"
}
},
"uuid": "93f14b03-5ed3-4f23-87c6-ae3806041b6a",
"identifier": "sweat",
"family": null,
"groups": [],
"parent": null,
"categories": [
"winter_collection"
],
"enabled": true,
"values": {},
"created": "2016-06-23T11:24:44+02:00",
"updated": "2016-06-23T11:24:44+02:00",
"associations": {},
"quantified_associations": {},
"quality_scores": [],
"completenesses": [],
"workflow_execution_statuses": []
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Create a new product
This endpoint allows you to create a new product. Permissions based on your user groups are applied to the product you try to create.
REQUEST
post /api/rest/v1/products
Path parameters
Ø
Query parameters
create_missing_options
(string)
• When present in the query string (regardless of value), automatically creates missing attribute options during product/product model creation or update.
This only works for simple select and multi select attributes that have the enable_option_creation_during_import property set to true (configurable via the Attribute API).
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
uuid
(string)
• Product UUID
identifier
(string)
• Product identifier, i.e. the value of the only pim_catalog_identifier attribute
enabled
(boolean,
true by default)
• Whether the product is enabled
groups
(array[string],
[] by default)
• Codes of the groups to which the product belong
family
(string,null,
null only in the case of a non variant product. by default)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family
categories
(array[string],
[] by default)
• Codes of the categories in which the product is classified
parent
(string,null,
null by default)
• Code of the parent product model when the product is a variant
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array)
• Array of groups codes with which the product is in relation
products
(array)
• Array of product identifiers with which the product is in relation
product_models
(array)
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array)
• Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array)
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
}
Example
{
"identifier": "top",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"locale": null,
"scope": null
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"data": "m",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"data": [
"winter_2016"
],
"locale": null,
"scope": null,
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
},
{
"identifier": "shoes",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
]
}RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Update/create several products
This endpoint allows you to update and/or create several products at once. Learn more about Update behavior. Note that if no product exists for the given identifier, it creates it. Permissions based on your user groups are applied to the products you try to update. It may result in the creation of drafts if you only have edit rights through the product's categories.
REQUEST
patch /api/rest/v1/products
Path parameters
Ø
Query parameters
create_missing_options
(string)
• When present in the query string (regardless of value), automatically creates missing attribute options during product/product model creation or update.
This only works for simple select and multi select attributes that have the enable_option_creation_during_import property set to true (configurable via the Attribute API).
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is a product model in JSON standard format. Modifications to existing product models can be specified using additional keys such as `add_categories` and `remove_categories`.
{
uuid
(string)
• Product UUID
identifier
(string)
• Product identifier, i.e. the value of the only pim_catalog_identifier attribute
enabled
(boolean,
true by default)
• Whether the product is enabled
groups
(array[string],
[] by default)
• Codes of the groups to which the product belong
family
(string,null,
null only in the case of a non variant product by default)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories
(array[string],
[] by default)
• Codes of the categories in which the product is classified
add_categories
(array[string],
[] by default)
• Codes of the categories to add to the product.
Existing categories will be preserved
remove_categories
(array[string],
[] by default)
• Codes of the categories to remove from the product.
Other categories will be preserved.
parent
(string,null,
null by default)
• Code of the parent product model when the product is a variant
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array)
• Array of groups codes with which the product is in relation
products
(array)
• Array of product identifiers with which the product is in relation
product_models
(array)
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array)
• Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array)
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product regarding the user permissions
}
quality_scores
(array[object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
completenesses
(array[object])
: [
{
scope (string) • Channel code for which the completenesses score is calculated
locale (string) • Channel code for which the completenesses score is calculated
data (integer) • Completenesses score value for the given channel/locale combination
}
]
workflow_execution_statuses
(array[object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array[object]) • Tasks associated with the workflow execution
}
]
}
Example
{"line":1,"identifier":"cap","status_code":204}
{"line":2,"identifier":"mug","status_code":422,"message":"Property \"group\" does not exist."}
{"line":3,"identifier":"tshirt","status_code":201}
RESPONSES
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
{
line
(integer)
• Line number
identifier
(string)
• Product identifier
status_code
(integer)
• HTTP status code, see Client errors to understand the meaning of each code
message
(string)
• Message explaining the error
}
Example
{"line":1,"identifier":"cap","status_code":204}
{"line":2,"identifier":"mug","status_code":422,"message":"Property \"group\" does not exist."}
{"line":3,"identifier":"tshirt","status_code":201}
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Get a product
This endpoint allows you to get the information about a given product. Permissions based on your user groups are applied to the product you request.
REQUEST
get /api/rest/v1/products/{code}
Path parameters
code
(string)
• 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.
Query parameters
with_attribute_options
(boolean)
• Return labels of attribute options in the response.
When set to true, the response will include human-readable labels for attribute options alongside their codes.
This is useful for displaying human-readable labels instead of just option codes, which improves the user experience in frontend applications.
If set to false, the response will only include option codes, which can improve performance.
See the linked_data format section for more details.
with_asset_share_links
(boolean)
• Return asset collection share link URLs in the response.
When set to true, the response will include direct URLs to asset collections for sharing purposes.
This is useful for accessing direct links to asset collections, which can be used for sharing or external integrations.
If set to false, the response will not include share links, which can improve performance.
See the linked_data format for more details.
with_quality_scores
(boolean)
• Return product quality scores in the response.
When set to true, the response will include quality score information for each product.
This is useful for assessing and monitoring product data quality, which is essential for maintaining high data standards and improving product information.
If set to false, the response will not include quality scores, which can improve performance.
with_completenesses
(boolean)
• Return product completenesses information in the response.
When set to true, the response will include detailed completeness information for each product.
This is useful for understanding the data quality and completeness of products, which is essential for product management and quality assurance.
If set to false, the response will not include completeness information, which can improve performance.
with_workflow_execution_statuses
(boolean)
•
Return an array of workflow_execution_statuses directly associated with the requested entity (product or product model) in the response. Statuses are level-specific and are not inherited from parent models. For a complete overview of a variant product, you must query the variant itself and its parent model(s) in separate requests. Each workflow object contains:
- The overall execution status (e.g., in_progress, completed).
- A list of all associated tasks.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the product in JSON standard format
Body Format application/json
{
uuid
(string)
• Product UUID
identifier
(string)
• Product identifier, i.e. the value of the only pim_catalog_identifier attribute
enabled
(boolean)
• Whether the product is enabled
family
(string,null)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories
(array [string])
• Codes of the categories in which the product is classified.
groups
(array [string])
• Codes of the groups to which the product belong.
Each string of the array is equal to an existing group code.
parent
(string,null)
• Code of the parent product model when the product is a variant
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array[string])
• Array of groups codes with which the product is in relation
products
(array[string])
• Array of product identifiers with which the product is in relation
product_models
(array[string])
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array[object])
• Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array[object])
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product regarding the user permissions
}
quality_scores
(array [object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
completenesses
(array [object])
: [
{
scope (string) • Channel code for which the completenesses score is calculated
locale (string) • Channel code for which the completenesses score is calculated
data (integer) • Completenesses score value for the given channel/locale combination
}
]
workflow_execution_statuses
(array [object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array) • Tasks associated with the workflow execution
}
]
}
Example
{
"uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"identifier": "top",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"size": [
{
"data": "m",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"collection": [
{
"data": [
"winter_2016"
],
"locale": null,
"scope": null,
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
},
"attribute_type": "pim_catalog_multiselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
},
{
"identifier": "shoes",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
],
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
]
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Update/create a product
This endpoint allows you to update a given product. Learn more about Update behavior. Note that if no product exists for the given identifier, it creates it. In the Enterprise Edition, since the v2.0, permissions based on your user groups are applied to the product you try to update. It may result in the creation of a draft if you only have edit rights through the product's categories.
REQUEST
patch /api/rest/v1/products/{code}
Path parameters
code
(string)
• 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.
Query parameters
create_missing_options
(string)
• When present in the query string (regardless of value), automatically creates missing attribute options during product/product model creation or update.
This only works for simple select and multi select attributes that have the enable_option_creation_during_import property set to true (configurable via the Attribute API).
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
uuid
(string)
• Product UUID
identifier
(string)
• Product identifier, i.e. the value of the only pim_catalog_identifier attribute
enabled
(boolean,
true by default)
• Whether the product is enabled
groups
(array[string],
[] by default)
• Codes of the groups to which the product belong
family
(string,null,
null only in the case of a non variant product by default)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories
(array[string],
[] by default)
• Codes of the categories in which the product is classified
add_categories
(array[string],
[] by default)
• Codes of the categories to add to the product.
Existing categories will be preserved
remove_categories
(array[string],
[] by default)
• Codes of the categories to remove from the product.
Other categories will be preserved.
parent
(string,null,
null by default)
• Code of the parent product model when the product is a variant
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array)
• Array of groups codes with which the product is in relation
products
(array)
• Array of product identifiers with which the product is in relation
product_models
(array)
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array)
• Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array)
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product regarding the user permissions
}
quality_scores
(array[object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
completenesses
(array[object])
: [
{
scope (string) • Channel code for which the completenesses score is calculated
locale (string) • Channel code for which the completenesses score is calculated
data (integer) • Completenesses score value for the given channel/locale combination
}
]
workflow_execution_statuses
(array[object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array[object]) • Tasks associated with the workflow execution
}
]
}
Example
{
"uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"identifier": "top",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"size": [
{
"data": "m",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"collection": [
{
"data": [
"winter_2016"
],
"locale": null,
"scope": null,
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
},
"attribute_type": "pim_catalog_multiselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
},
{
"identifier": "shoes",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
],
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
]
}RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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 • URI of the updated resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Delete a product
This endpoint allows you to delete a given product. Permissions based on your user groups are applied to the product you try to delete.
REQUEST
delete /api/rest/v1/products/{code}
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
No content to return. Means that the deletion was successful.
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Submit a draft for approval
This endpoint allows you to submit a draft for approval.
REQUEST
post /api/rest/v1/products/{code}/proposal
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Get a draft
This endpoint allows you to get the information about a given draft.
REQUEST
get /api/rest/v1/products/{code}/draft
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the product in JSON standard format
Body Format application/json
{
uuid
(string)
• Product UUID
identifier
(string)
• Product identifier, i.e. the value of the only pim_catalog_identifier attribute
enabled
(boolean)
• Whether the product is enabled
family
(string,null)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories
(array [string])
• Codes of the categories in which the product is classified.
groups
(array [string])
• Codes of the groups to which the product belong.
Each string of the array is equal to an existing group code.
parent
(string,null)
• Code of the parent product model when the product is a variant
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array[string])
• Array of groups codes with which the product is in relation
products
(array[string])
• Array of product identifiers with which the product is in relation
product_models
(array[string])
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array[object])
• Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array[object])
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product regarding the user permissions
}
quality_scores
(array [object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
completenesses
(array [object])
: [
{
scope (string) • Channel code for which the completenesses score is calculated
locale (string) • Channel code for which the completenesses score is calculated
data (integer) • Completenesses score value for the given channel/locale combination
}
]
workflow_execution_statuses
(array [object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array) • Tasks associated with the workflow execution
}
]
}
Example
{
"uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"identifier": "top",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"values": {
"name": [
{
"data": "Top",
"locale": "en_US",
"scope": null,
"attribute_type": "pim_catalog_text"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce",
"attribute_type": "pim_catalog_textarea"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet",
"attribute_type": "pim_catalog_textarea"
}
],
"price": [
{
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"color": [
{
"data": "black",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"size": [
{
"data": "m",
"locale": null,
"scope": null,
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
},
"attribute_type": "pim_catalog_simpleselect"
}
],
"collection": [
{
"data": [
"winter_2016"
],
"locale": null,
"scope": null,
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
},
"attribute_type": "pim_catalog_multiselect"
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
},
{
"identifier": "shoes",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
],
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
]
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Product model
Get list of product models
This endpoint allows you to get a list of product models. Product models are paginated. Permissions based on your user groups are applied to the set of products you request.
REQUEST
get /api/rest/v1/product-models
Path parameters
Ø
Query parameters
search
(string)
• Filter product models,
for more details see the Filters.
scope
(string)
• Filter product values to return scopable attributes for the given channel as well as the non localizable/non scopable attributes.
It is useful for retrieving product information specific to a particular sales channel, which is essential for channel-specific applications.
For more details see the Filter product values via channel section.
locales
(string)
• Filter product values to return localizable attributes for the given locales as well as the non localizable/non scopable attributes.
It is useful for retrieving product information in specific languages, which is essential for multi-locale applications.
For more details see the Filter product values via locale section.
attributes
(string)
• Filter product values to only return those concerning the given attributes.
It is useful for limiting the response to specific attributes, reducing payload size and improving performance.
For more details see the Filter product values via attributes section.
pagination_type
(string,
page
by default)
• Specify which pagination method to use for navigating through large datasets.
It is useful for choosing between different pagination strategies based on your specific use case and performance requirements.
See Pagination section for more details.
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
search_after
(string,
cursor to the first page
by default)
• 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 section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
search_scope
(string)
• Filter scopes based on specific criteria.
If you need to filter on several attributes on the same scope, you can use this parameter, to avoid repeating yourself for each attribute.
For more details see the Filters section.
search_locale
(string)
• Filter locales based on specific criteria.
If you need to filter on several attributes on the same locale, you can use this parameter, to avoid repeating yourself for each attribute.
For more details see the Filters section.
convert_measurements
(boolean)
• Convert values of measurement attributes to the unit configured in the channel provided by the scope parameter.
When set to true, the response will include measurement values converted to the channel's configured units.
This is useful for displaying measurement values in the appropriate units for different channels or regions.
If set to false, the response will return measurement values in their original units, which can improve performance.
Therefore, this parameter requires the scope parameter to be provided.
with_count
(boolean)
• Return the count of items in the response.
Be careful with that, on a big catalog, it can decrease performance in a significant way.
It is useful for understanding the size of the dataset being returned, especially when dealing with large collections.
Use it judiciously to avoid performance issues.
with_workflow_execution_statuses
(boolean)
•
Return an array of workflow_execution_statuses directly associated with the requested entity (product or product model) in the response. Statuses are level-specific and are not inherited from parent models. For a complete overview of a variant product, you must query the variant itself and its parent model(s) in separate requests. Each workflow object contains:
- The overall execution status (e.g., in_progress, completed).
- A list of all associated tasks.
with_attribute_options
(boolean)
• Return labels of attribute options in the response.
See the linked_data format section for more details.
with_asset_share_links
(boolean)
• Return asset collection share link URLs in the response.
When set to true, the response will include direct URLs to asset collections for sharing purposes.
This is useful for accessing direct links to asset collections, which can be used for sharing or external integrations.
If set to false, the response will not include share links, which can improve performance.
See the linked_data format for more details.
with_quality_scores
(boolean)
• Return product model quality scores in the response.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return product models paginated. The response is paginated and includes links to navigate through the pages.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
items_count
(integer)
• Total number of items (only if with_count parameter is set to true)
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
code (string)
• Product model code
family (string,null)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
family_variant (string)
• Family variant code from which the product model inherits its attributes and variant attributes
parent (string,null)
• Code of the parent product model when the product is a variant
categories (array [string])
• Codes of the categories in which the product is classified
• Codes of the categories in which the product is classified
values (object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations (object)
: {
{^\w+$} (object)
: {
groups
(array [string]) • Array of groups codes with which the product is in relation
products
(array [string]) • Array of product identifiers with which the product is in relation
product_models
(array [string]) • Array of product model codes with which the product is in relation
}
}
quantified_associations (object)
: {
{^\w+$} (object)
: {
products
(array [object]) • Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array [object]) • Array of objects containing product model codes and quantities with which the product is in relation
}
}
created (string)
• Date of creation
updated (string)
• Date of the last update
metadata (object)
: {
workflow_status (string)
• Status of the product regarding the user permissions
}
quality_scores (array [object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
workflow_execution_statuses (array [object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array [object]) • Tasks associated with the workflow execution
}
]
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product-models?page=2&with_count=true&limit=3&with_quality_scores=true&with_workflow_execution_statuses=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/product-models?page=1&with_count=true&limit=3&with_quality_scores=true&with_workflow_execution_statuses=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/product-models?page=1&with_count=true&limit=3&with_quality_scores=true&with_workflow_execution_statuses=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/product-models?page=3&with_count=true&limit=3&with_quality_scores=true&with_workflow_execution_statuses=true"
}
},
"current_page": 1,
"items_count": 3,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product-models/amarisshoe"
}
},
"code": "amarisshoe",
"family": "shoes",
"family_variant": "shoes_VariantA1",
"categories": [
"clothing",
"shoes"
],
"values": {
"price": [
{
"data": [
{
"amount": "50.00",
"currency": "EUR"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "I like shoes!",
"attribute_type": "pim_catalog_textarea"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglasses"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
},
{
"identifier": "shoes",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
],
"created": "2017-10-04T18:04:10+02:00",
"updated": "2017-10-04T18:04:10+02:00"
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product-models/Abiloitshirt"
}
},
"code": "Abiloitshirt",
"family": "clothing",
"family_variant": "clothing_VariantA1",
"categories": [
"clothing",
"tshirt"
],
"values": {
"price": [
{
"data": [
{
"amount": "50.00",
"currency": "EUR"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "I like tshirt!",
"attribute_type": "pim_catalog_textarea"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglasses"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "cap",
"quantity": 2
}
],
"product_models": []
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"workflow_execution_statuses": [],
"created": "2017-10-04T18:04:10+02:00",
"updated": "2017-10-04T18:04:10+02:00"
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/product-models/Astertrousers"
}
},
"code": "Astertrousers",
"family": "clothing",
"family_variant": "clothing_VariantA1",
"categories": [
"clothing",
"trousers"
],
"values": {
"price": [
{
"data": [
{
"amount": "50.00",
"currency": "EUR"
}
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_price_collection"
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "I like trousers!",
"attribute_type": "pim_catalog_textarea"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglasses"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {},
"workflow_execution_statuses": [],
"created": "2017-10-04T18:04:10+02:00",
"updated": "2017-10-04T18:04:10+02:00"
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Create a new product model
This endpoint allows you to create a new product model. Permissions based on your user groups are applied to the product model you try to create.
REQUEST
post /api/rest/v1/product-models
Path parameters
Ø
Query parameters
create_missing_options
(string)
• When present in the query string (regardless of value), automatically creates missing attribute options during product/product model creation or update.
This only works for simple select and multi select attributes that have the enable_option_creation_during_import property set to true (configurable via the Attribute API).
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string)
• Product model code. Required for POST (create) operations.
Optional for PATCH (update) operations as it can be inferred from the URL.
family
(string)
• Family code from which the product model inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
family_variant
(string)
• Family variant code from which the product model inherits its attributes and variant attributes.
Required for root product models (without parent).
Optional for sub-product models (with parent), as it can be inferred from the parent.
parent
(string,null,
null by default)
• Code of the parent product model
categories
(array[string],
[] by default)
• Codes of the categories in which the product model is categorized
values
(object)
• Product model attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array)
• Array of groups codes with which the product is in relation
products
(array)
• Array of product identifiers with which the product is in relation
product_models
(array)
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array)
• Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array)
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
}
Example
{
"code": "model-biker-jacket-leather",
"family": "clothing",
"family_variant": "clothing_material_size",
"parent": "model-biker-jacket",
"categories": [
"summer_collection"
],
"values": {
"color": [
{
"data": "antique_white",
"locale": null,
"scope": null
}
],
"material": [
{
"data": "leather",
"locale": null,
"scope": null
}
],
"variation_name": [
{
"locale": "en_US",
"data": "Biker jacket leather",
"scope": null
}
],
"name": [
{
"locale": "en_US",
"data": "Biker jacket",
"scope": null
}
],
"collection": [
{
"data": [
"summer_2017"
],
"locale": null,
"scope": null
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "Biker jacket"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "top",
"quantity": 2
},
{
"identifier": "cap",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
}
}RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Update/create several product models
This endpoint allows you to update and/or create several product models at once. Learn more about Update behavior. Note that if no product models exists for the given code, it creates it. Permissions based on your user groups are applied to the product models you try to update. It may result in the creation of drafts if you only have edit rights through the product model's categories.
REQUEST
patch /api/rest/v1/product-models
Path parameters
Ø
Query parameters
create_missing_options
(string)
• When present in the query string (regardless of value), automatically creates missing attribute options during product/product model creation or update.
This only works for simple select and multi select attributes that have the enable_option_creation_during_import property set to true (configurable via the Attribute API).
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is a product model in JSON standard format. Modifications to existing product models can be specified using additional keys such as `add_categories` and `remove_categories`.
{
code
(string)
• Product model code. Required for POST (create) operations.
Optional for PATCH (update) operations as it can be inferred from the URL.
family
(string)
• Family code from which the product model inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
family_variant
(string)
• Family variant code from which the product model inherits its attributes and variant attributes.
Required for root product models (without parent).
Optional for sub-product models (with parent), as it can be inferred from the parent.
parent
(string,null,
null by default)
• Code of the parent product model
categories
(array[string],
[] by default)
• Codes of the categories in which the product model is categorized
add_categories
(array[string],
[] by default)
• Codes of the categories to add to the product model.
Existing categories will be preserved.
remove_categories
(array[string],
[] by default)
• Codes of the categories to remove from the product model.
Other categories will be preserved.
values
(object)
• Product model attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array)
• Array of groups codes with which the product is in relation
products
(array)
• Array of product identifiers with which the product is in relation
product_models
(array)
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array)
• Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array)
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product model regarding the user permissions
}
quality_scores
(array[object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
workflow_execution_statuses
(array[object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array[object]) • Tasks associated with the workflow execution
}
]
}
Example
{"code": "sub_sweat_option_a", "parent": "sweat", "values": {"a_simple_select": [{"locale": null, "scope": null, "data": "optionA"}]}}
{"code": "sub_sweat_option_b", "parent": "sweat", "values": {"a_simple_select": [{"locale": null, "scope": null, "data": "optionA"}]}}
{"code":"tshirt", "parent": "root_tshirt", "family_variant":"clothesvariant","values":{"description":[{"scope":"ecommerce","locale":"en_US","data":"My amazing tshirt"}]}}
RESPONSES
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
{
line
(integer)
• Line number
code
(string)
• Resource code
status_code
(integer)
• HTTP status code, see Client errors to understand the meaning of each code
message
(string)
• Message explaining the error
}
Example
{"line":1,"code":"sub_sweat_option_a","status_code":204}
{"line":2,"code":"sub_sweat_option_b","status_code":422,"message":"Validation failed.","errors":[{"property":"attribute","message":"Cannot set value \"Option A\" for the attribute axis \"a_simple_select\", as another sibling entity already has this value"}]}
{"line":3,"code":"tshirt","status_code":201}
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}Get a product model
This endpoint allows you to get the information about a given product model. Permissions based on your user groups are applied to the product model you request.
REQUEST
get /api/rest/v1/product-models/{code}
Path parameters
code
(string)
• 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.
Query parameters
with_asset_share_links
(boolean)
• Return asset collection share link URLs in the response.
When set to true, the response will include direct URLs to asset collections for sharing purposes.
This is useful for accessing direct links to asset collections, which can be used for sharing or external integrations.
If set to false, the response will not include share links, which can improve performance.
See the linked_data format for more details.
with_quality_scores
(boolean)
• Return product quality scores in the response.
When set to true, the response will include quality score information for each product.
This is useful for assessing and monitoring product data quality, which is essential for maintaining high data standards and improving product information.
If set to false, the response will not include quality scores, which can improve performance.
with_workflow_execution_statuses
(boolean)
•
Return an array of workflow_execution_statuses directly associated with the requested entity (product or product model) in the response. Statuses are level-specific and are not inherited from parent models. For a complete overview of a variant product, you must query the variant itself and its parent model(s) in separate requests. Each workflow object contains:
- The overall execution status (e.g., in_progress, completed).
- A list of all associated tasks.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the product model in JSON standard format
Body Format application/json
{
code
(string)
• Product model code
family
(string,null)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
family_variant
(string)
• Family variant code from which the product model inherits its attributes and variant attributes
parent
(string,null)
• Code of the parent product model when the product is a variant
categories
(array [string])
• Codes of the categories in which the product is classified
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array[string])
• Array of groups codes with which the product is in relation
products
(array[string])
• Array of product identifiers with which the product is in relation
product_models
(array[string])
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array[object])
• Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array[object])
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product regarding the user permissions
}
quality_scores
(array [object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
workflow_execution_statuses
(array [object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array) • Tasks associated with the workflow execution
}
]
}
Example
{
"code": "model-biker-jacket-leather",
"family": "clothing",
"family_variant": "clothing_material_size",
"parent": "model-biker-jacket",
"categories": [
"summer_collection"
],
"values": {
"color": [
{
"data": "antique_white",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_simpleselect"
}
],
"material": [
{
"data": "leather",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"variation_name": [
{
"locale": "en_US",
"data": "Biker jacket leather",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"name": [
{
"locale": "en_US",
"data": "Biker jacket",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"collection": [
{
"data": [
"summer_2017"
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_multiselect"
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "Biker jacket",
"attribute_type": "pim_catalog_textarea"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "top",
"quantity": 2
},
{
"identifier": "cap",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
],
"created": "2017-10-02T15:03:55+02:00",
"updated": "2017-10-02T15:03:55+02:00"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Update/create a product model
This endpoint allows you to update a given product model. Learn more about Update behavior. Note that if no product model exists for the given code, it creates it. Permissions based on your user groups are applied to the product model you try to update. It may result in the creation of a draft if you only have edit rights through the product model's categories.
REQUEST
patch /api/rest/v1/product-models/{code}
Path parameters
code
(string)
• 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.
Query parameters
create_missing_options
(string)
• When present in the query string (regardless of value), automatically creates missing attribute options during product/product model creation or update.
This only works for simple select and multi select attributes that have the enable_option_creation_during_import property set to true (configurable via the Attribute API).
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string)
• Product model code. Required for POST (create) operations.
Optional for PATCH (update) operations as it can be inferred from the URL.
family
(string)
• Family code from which the product model inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
family_variant
(string)
• Family variant code from which the product model inherits its attributes and variant attributes.
Required for root product models (without parent).
Optional for sub-product models (with parent), as it can be inferred from the parent.
parent
(string,null,
null by default)
• Code of the parent product model
categories
(array[string],
[] by default)
• Codes of the categories in which the product model is categorized
add_categories
(array[string],
[] by default)
• Codes of the categories to add to the product model.
Existing categories will be preserved.
remove_categories
(array[string],
[] by default)
• Codes of the categories to remove from the product model.
Other categories will be preserved.
values
(object)
• Product model attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array)
• Array of groups codes with which the product is in relation
products
(array)
• Array of product identifiers with which the product is in relation
product_models
(array)
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array)
• Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array)
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product model regarding the user permissions
}
quality_scores
(array[object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
workflow_execution_statuses
(array[object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array[object]) • Tasks associated with the workflow execution
}
]
}
Example
{
"code": "model-biker-jacket-leather",
"family": "clothing",
"family_variant": "clothing_material_size",
"parent": "model-biker-jacket",
"categories": [
"summer_collection"
],
"values": {
"color": [
{
"data": "antique_white",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_simpleselect"
}
],
"material": [
{
"data": "leather",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"variation_name": [
{
"locale": "en_US",
"data": "Biker jacket leather",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"name": [
{
"locale": "en_US",
"data": "Biker jacket",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"collection": [
{
"data": [
"summer_2017"
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_multiselect"
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "Biker jacket",
"attribute_type": "pim_catalog_textarea"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "top",
"quantity": 2
},
{
"identifier": "cap",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
],
"created": "2017-10-02T15:03:55+02:00",
"updated": "2017-10-02T15:03:55+02:00"
}RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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 • URI of the updated resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Delete a product model
This endpoint allows you to delete a given product model. All its children, product models and variant products, will be also deleted. Permissions based on your connection user group are applied to the product model you try to delete.
REQUEST
delete /api/rest/v1/product-models/{code}
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
No content to return. Means that the deletion was successful.
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Submit a draft for approval
This endpoint allows you to submit a product model draft for approval
REQUEST
post /api/rest/v1/product-models/{code}/proposal
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Get a draft
This endpoint allows you to get the information about a given product model draft
REQUEST
get /api/rest/v1/product-models/{code}/draft
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the product model in JSON standard format
Body Format application/json
{
code
(string)
• Product model code
family
(string,null)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
family_variant
(string)
• Family variant code from which the product model inherits its attributes and variant attributes
parent
(string,null)
• Code of the parent product model when the product is a variant
categories
(array [string])
• Codes of the categories in which the product is classified
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array[string])
• Array of groups codes with which the product is in relation
products
(array[string])
• Array of product identifiers with which the product is in relation
product_models
(array[string])
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array[object])
• Array of objects containing product identifiers and quantities with which the product is in relation
product_models
(array[object])
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product regarding the user permissions
}
quality_scores
(array [object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
workflow_execution_statuses
(array [object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array) • Tasks associated with the workflow execution
}
]
}
Example
{
"code": "model-biker-jacket-leather",
"family": "clothing",
"family_variant": "clothing_material_size",
"parent": "model-biker-jacket",
"categories": [
"summer_collection"
],
"values": {
"color": [
{
"data": "antique_white",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_simpleselect"
}
],
"material": [
{
"data": "leather",
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"variation_name": [
{
"locale": "en_US",
"data": "Biker jacket leather",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"name": [
{
"locale": "en_US",
"data": "Biker jacket",
"scope": null,
"attribute_type": "pim_catalog_text"
}
],
"collection": [
{
"data": [
"summer_2017"
],
"locale": null,
"scope": null,
"attribute_type": "pim_catalog_multiselect"
}
],
"description": [
{
"locale": "en_US",
"scope": "ecommerce",
"data": "Biker jacket",
"attribute_type": "pim_catalog_textarea"
}
]
},
"associations": {
"PACK": {
"products": [
"sunglass"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"identifier": "top",
"quantity": 2
},
{
"identifier": "cap",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
},
{
"uuid": "59169984-6d6c-4fa7-b925-68b8e9d31ddb",
"status": "completed",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": "2024-02-22T17:31:00Z",
"workflow": {
"uuid": "b69ee158-a421-4680-bec0-a71bc73b8e31",
"code": "compliance_workflow",
"labels": {}
},
"tasks": []
}
],
"created": "2017-10-02T15:03:55+02:00",
"updated": "2017-10-02T15:03:55+02:00"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Product media file
Get a list of product media files
This endpoint allows you to get a list of media files that are used as attribute values in products or product models
REQUEST
get /api/rest/v1/media-files
Path parameters
Ø
Query parameters
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
with_count
(boolean)
• Return the count of items in the response.
Be careful with that, on a big catalog, it can decrease performance in a significant way.
It is useful for understanding the size of the dataset being returned, especially when dealing with large collections.
Use it judiciously to avoid performance issues.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return media files paginated. The response is paginated and includes links to navigate through the pages.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
items_count
(integer)
• Total number of items (only if with_count parameter is set to true)
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the media file
}
}
_links (object)
: {
download (object)
: {
href
(string) • URI to download the binaries of the media file
}
}
code (string)
• Media file code
original_filename (string)
• Original filename of the media file
mime_type (string)
• Mime type of the media file
size (integer)
• Size of the media file
extension (string)
• Extension of the media file
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files?page=2&limit=4&with_count=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files?page=1&limit=4&with_count=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files?page=1&limit=4&with_count=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files?page=2&limit=4&with_count=true"
}
},
"current_page": 2,
"items_count": 10,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg/download"
}
},
"code": "7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg",
"original_filename": "10806799-1356.jpg",
"mime_type": "image/jpeg",
"size": 16070,
"extension": "jpg"
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/d/0/3/2/d032a92d994df3ef67ee6746b7b7a795c2964e7c_10734346_1480.jpg"
},
"download": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/d/0/3/2/d032a92d994df3ef67ee6746b7b7a795c2964e7c_10734346_1480.jpg/download"
}
},
"code": "d/0/3/2/d032a92d994df3ef67ee6746b7b7a795c2964e7c_10734346_1480.jpg",
"original_filename": "10734346-1480.jpg",
"mime_type": "image/jpeg",
"size": 16454,
"extension": "jpg"
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/5/1/d/8/51d81dc778ba1501a8f998f3ab5797569f3b9e25_12431976_8797.jpg"
},
"download": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/5/1/d/8/51d81dc778ba1501a8f998f3ab5797569f3b9e25_12431976_8797.jpg/download"
}
},
"code": "5/1/d/8/51d81dc778ba1501a8f998f3ab5797569f3b9e25_12431976_8797.jpg",
"original_filename": "12431976-8797.jpg",
"mime_type": "image/jpeg",
"size": 19725,
"extension": "jpg"
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/0/c/b/0/0cb0c0e115dedba676f8d1ad8343e6207ab54c7b_107406_9841.jpg"
},
"download": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/0/c/b/0/0cb0c0e115dedba676f8d1ad8343e6207ab54c7b_107406_9841.jpg/download"
}
},
"code": "0/c/b/0/0cb0c0e115dedba676f8d1ad8343e6207ab54c7b_107406_9841.jpg",
"original_filename": "107406-9841.jpg",
"mime_type": "image/jpeg",
"size": 17639,
"extension": "jpg"
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Create a new product media file
This endpoint allows you to create a new media file and associate it to an attribute value of a given product or product model
REQUEST
post /api/rest/v1/media-files
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Given as form-data
product
(string,null)
• The product to which the media file will be associated.
It is a JSON string that follows this format
'{"identifier":"product_identifier", "attribute":"attribute_code", "scope":"channel_code","locale":"locale_code"}'.
You have to either use this field or the product_model field, but not both at the same time.
RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Get a product media file
This endpoint allows you to get the information about a given media file that is used as an attribute value of a product or a product model.
REQUEST
get /api/rest/v1/media-files/{code}
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the media file in JSON standard format
Body Format application/json
{
_links
(object)
: {
download
(object)
: {
href
(string)
• URI to download the binaries of the media file
}
}
code
(string)
• Media file code
original_filename
(string)
• Original filename of the media file
mime_type
(string)
• Mime type of the media file
size
(integer)
• Size of the media file
extension
(string)
• Extension of the media file
}
Example
{
"_links": {
"download": {
"href": "https://demo.akeneo.com/api/rest/v1/media-files/7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg/download"
}
},
"code": "7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg",
"original_filename": "10806799-1356.jpg",
"mime_type": "image/jpeg",
"size": 16070,
"extension": "jpg"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Download a product media file
This endpoint allows you to download a given media file that is used as an attribute value of a product or a product model
REQUEST
get /api/rest/v1/media-files/{code}/download
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Body
Ø
RESPONSES
Returns the binary of the media file
Body Format Mime-type of the media file
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.
Body Format Mime-type of the media file
This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format Mime-type of the media file
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.
Body Format Mime-type of the media file
Jobs
Jobs
Launch export job by code
This endpoint allows you to launch an export job by code
REQUEST
post /api/rest/v1/jobs/export/{code}
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
is_dry_run
(boolean)
• Whether to run the export in dry-run mode
}
Example
RESPONSES
Returns the execution ID for the launched job
Body Format application/json
{
job_execution_id
(integer)
• The ID of the job execution that was launched
}
Example
{
"job_execution_id": 12345
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Launch import job by code
This endpoint allows you to launch an import job by code
REQUEST
post /api/rest/v1/jobs/import/{code}
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
import_mode
(string)
• Change the import mode for this job by overriding the profile value.
Available values are: create_only, update_only and create_or_update.
is_dry_run
(boolean)
• Whether to run the import in dry-run mode
}
Example
RESPONSES
Returns the execution ID for the launched job
Body Format application/json
{
job_execution_id
(integer)
• The ID of the job execution that was launched
}
Example
{
"job_execution_id": 12345
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Catalog structure
Family
Get list of families
This endpoint allows you to get a list of families. Families are paginated and sorted by code.
REQUEST
get /api/rest/v1/families
Path parameters
Ø
Query parameters
search
(string)
• The search query parameter allows you to filter families based on specific criteria.
For more details see the Filters section.
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
with_count
(boolean)
• Return the count of items in the response.
Be careful with that, on a big catalog, it can decrease performance in a significant way.
It is useful for understanding the size of the dataset being returned, especially when dealing with large collections.
Use it judiciously to avoid performance issues.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return family variants paginated. The response is paginated and includes links to navigate through the pages.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
items_count
(integer)
• Total number of items (only if with_count parameter is set to true)
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
code (string)
• Family code
attribute_as_label (string)
• Attribute code used as label
attribute_as_image (string,null)
• Attribute code used as the main picture in the user interface
attributes (array [string])
• Attribute codes that compose the family
• Attribute codes that compose the family
attribute_requirements (object)
• Attribute codes of the family that are required for the completeness calculation for each channel
labels (object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$} (string,null)
• Family label for the specified locale
}
parent (string,null)
• The parent family code. If the family has no parent, this field is null
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/families?page=2&limit=2&with_count=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/families?page=1&limit=2&with_count=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/families?page=1&limit=2&with_count=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/families?page=3&limit=2&with_count=true"
}
},
"current_page": 2,
"items_count": 10,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/families/tshirt"
}
},
"code": "tshirt",
"attributes": [
"sku",
"name",
"description",
"price",
"size",
"color",
"picture"
],
"attribute_as_label": "name",
"attribute_as_image": "picture",
"attribute_requirements": {
"ecommerce": [
"sku",
"name",
"description",
"price",
"size",
"color"
],
"tablet": [
"sku",
"name",
"description",
"price"
]
},
"labels": {
"en_US": "Tshirt",
"fr_FR": "Tshirt"
},
"parent": null
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/families/caps"
}
},
"code": "caps",
"attributes": [
"sku",
"name",
"description",
"price",
"color",
"picture"
],
"attribute_as_label": "name",
"attribute_as_image": "picture",
"attribute_requirements": {
"ecommerce": [
"sku",
"name",
"description",
"price",
"color"
],
"tablet": [
"sku",
"name",
"description",
"price"
]
},
"labels": {
"en_US": "Caps",
"fr_FR": "Casquettes"
},
"parent": "accessories"
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Create a new family
This endpoint allows you to create a new family
REQUEST
post /api/rest/v1/families
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-Type
• This header indicates the media type of the resource being sent to the server.
It is used to specify the format of the request body, allowing the server to correctly interpret the data being sent.
Equal to 'application/json' or 'application/x-www-form-urlencoded', no other value allowed.
Body
Follow the standard format of the entity
{
attribute_as_label
(string)
• Attribute code used as label
attribute_as_image
(string,null)
• Attribute code used as the main picture in the user interface
attributes
(array[string])
• Attribute codes that compose the family. Each string in the array must be an existing attribute code
attribute_requirements
(object)
• Attribute codes of the family that are required for the completeness calculation for each channel
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Family label for the specified locale.
}
parent
(string,null)
• The code of the parent family. If not provided, the family is a root family
}
Example
{
"code": "caps",
"attributes": [
"sku",
"name",
"description",
"price",
"color",
"picture",
"material"
],
"attribute_as_label": "name",
"attribute_as_image": "picture,",
"attribute_requirements": {
"ecommerce": [
"sku",
"name",
"description",
"price",
"color"
],
"tablet": [
"sku",
"name",
"description",
"price"
]
},
"labels": {
"en_US": "Caps",
"fr_FR": "Casquettes"
},
"parent": null
}RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the data provided does not meet the required format or constraints defined by the API, and includes a link to the documentation for reference.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Property \\\"labels\\\" expects an array as data, \\\"NULL\\\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Update/create several families
This endpoint allows you to update and/or create several families at once
REQUEST
patch /api/rest/v1/families
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is a family in JSON standard format
{
attribute_as_label
(string)
• Attribute code used as label
attribute_as_image
(string,null)
• Attribute code used as the main picture in the user interface
attributes
(array[string])
• Attribute codes that compose the family. Each string in the array must be an existing attribute code
attribute_requirements
(object)
• Attribute codes of the family that are required for the completeness calculation for each channel
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Family label for the specified locale.
}
parent
(string,null)
• The code of the parent family. If not provided, the family is a root family
}
Example
{ "code": "tshirt","attribute_as_label": "description","attributes": [ "description","size" ] }
{ "code": "cap","attribute_as_label": "descripion" }
{ "code": "mug","attributes": [ "description","short_description" ] }
RESPONSES
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
{
line
(integer)
• Line number
code
(string)
• Resource code
status_code
(integer)
• HTTP status code, see Client errors to understand the meaning of each code
message
(string)
• Message explaining the error
}
Example
{"line":1,"code":"camcorders","status_code":201}
{"line":2,"code":"cap","status_code":422,"message":"Attribute \"descripion\" does not exist."}
{"line":3,"code":"clothes","status_code":204}
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}Get a family
This endpoint allows you to get the information about a given family
REQUEST
get /api/rest/v1/families/{code}
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the family in JSON standard format
Body Format application/json
{
code
(string)
• Family code
attribute_as_label
(string)
• Attribute code used as label
attribute_as_image
(string,null)
• Attribute code used as the main picture in the user interface
attributes
(array [string])
• Attribute codes that compose the family
attribute_requirements
(object)
• Attribute codes of the family that are required for the completeness calculation for each channel
labels
(object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Family label for the specified locale
}
parent
(string,null)
• The parent family code. If the family has no parent, this field is null
}
Example
{
"code": "caps",
"attributes": [
"sku",
"name",
"description",
"price",
"color",
"picture",
"material"
],
"attribute_as_label": "name",
"attribute_as_image": "picture,",
"attribute_requirements": {
"ecommerce": [
"sku",
"name",
"description",
"price",
"color"
],
"tablet": [
"sku",
"name",
"description",
"price"
]
},
"labels": {
"en_US": "Caps",
"fr_FR": "Casquettes"
},
"parent": null
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Update/create a family
This endpoint allows you to update a given family. Know more about Update behavior. Note that if no family exists for the given code, it creates it.
REQUEST
patch /api/rest/v1/families/{code}
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-Type
• This header indicates the media type of the resource being sent to the server.
It is used to specify the format of the request body, allowing the server to correctly interpret the data being sent.
Equal to 'application/json' or 'application/x-www-form-urlencoded', no other value allowed.
Body
Follow the standard format of the entity
{
attribute_as_label
(string)
• Attribute code used as label
attribute_as_image
(string,null)
• Attribute code used as the main picture in the user interface
attributes
(array[string])
• Attribute codes that compose the family. Each string in the array must be an existing attribute code
attribute_requirements
(object)
• Attribute codes of the family that are required for the completeness calculation for each channel
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Family label for the specified locale.
}
parent
(string,null)
• The code of the parent family. If not provided, the family is a root family
}
Example
{
"code": "caps",
"attributes": [
"sku",
"name",
"description",
"price",
"color",
"picture",
"material"
],
"attribute_as_label": "name",
"attribute_as_image": "picture,",
"attribute_requirements": {
"ecommerce": [
"sku",
"name",
"description",
"price",
"color"
],
"tablet": [
"sku",
"name",
"description",
"price"
]
},
"labels": {
"en_US": "Caps",
"fr_FR": "Casquettes"
},
"parent": null
}RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
Successfully patched, response with empty body
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the data provided does not meet the required format or constraints defined by the API, and includes a link to the documentation for reference.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Property \\\"labels\\\" expects an array as data, \\\"NULL\\\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Family variant
Get list of family variants
This endpoint allows you to get a list of family variants. Family variants are paginated and sorted by code.
REQUEST
get /api/rest/v1/families/{family_code}/variants
Path parameters
family_code
(string)
• This path parameter is used to specify the unique identifier of the family you want to retrieve or manipulate.
It is essential for identifying the specific family in the API requests.
Ensure that the family code is correctly formatted and corresponds to an existing family in the system.
Query parameters
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
with_count
(boolean)
• Return the count of items in the response.
Be careful with that, on a big catalog, it can decrease performance in a significant way.
It is useful for understanding the size of the dataset being returned, especially when dealing with large collections.
Use it judiciously to avoid performance issues.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return family variants paginated. The response is paginated and includes links to navigate through the pages.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
items_count
(integer)
• Total number of items (only if with_count parameter is set to true)
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
code (string)
• Family variant code
common_attributes (array [string])
• Codes of attributes that are common to all variants (not specific to any enrichment level)
• Codes of attributes that are common to all variants (not specific to any enrichment level)
variant_attribute_sets (array [object])
: [
{
level (integer) • Enrichment level
axes (array [string]) • Codes of attributes used as variant axes
attributes (array [string]) • Codes of attributes bind to this enrichment level
}
]
labels (object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$} (string,null)
• Family variant label for the specified locale
}
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/families/familyA/variants?page=2&limit=10&with_count=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/families/familyA/variants?page=1&limit=10&with_count=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/families/familyA/variants?page=1&limit=10&with_count=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/families/familyA/variants?page=3&limit=10&with_count=true"
}
},
"current_page": 1,
"items_count": 10,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/families/familyA/variants/shoesVariant"
}
},
"code": "shoesVariant",
"labels": {
"en_US": "Shoes variant",
"fr_FR": "Variante de chaussures"
},
"common_attributes": [
"name",
"description",
"image"
],
"variant_attribute_sets": [
{
"level": 1,
"axes": [
"color"
],
"attributes": [
"color",
"material"
]
},
{
"level": 2,
"axes": [
"size"
],
"attributes": [
"sku",
"size"
]
}
]
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Create a new family variant
This endpoint allows you to create a family variant
REQUEST
post /api/rest/v1/families/{family_code}/variants
Path parameters
family_code
(string)
• This path parameter is used to specify the unique identifier of the family you want to retrieve or manipulate.
It is essential for identifying the specific family in the API requests.
Ensure that the family code is correctly formatted and corresponds to an existing family in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string)
• Family variant code
variant_attribute_sets
(array[object])
: [
{
level (integer) • Enrichment level
axes (array[string]) • Codes of attributes used as variant axes
attributes (array[string]) • Codes of attributes bind to this enrichment level
}
]
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Family variant label for the specified locale
}
}
Example
{
"code": "shoesVariant",
"labels": {
"en_US": "Shoes variant",
"fr_FR": "Variante de chaussures"
},
"variant_attribute_sets": [
{
"level": 1,
"attributes": [
"color",
"material"
],
"axes": [
"color"
]
},
{
"level": 2,
"attributes": [
"sku",
"size"
],
"axes": [
"size"
]
}
]
}RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Update/create several family variants
This endpoint allows you to update and/or create several family variants at once
REQUEST
patch /api/rest/v1/families/{family_code}/variants
Path parameters
family_code
(string)
• This path parameter is used to specify the unique identifier of the family you want to retrieve or manipulate.
It is essential for identifying the specific family in the API requests.
Ensure that the family code is correctly formatted and corresponds to an existing family in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is a family in JSON standard format
{
code
(string)
• Family variant code
variant_attribute_sets
(array[object])
: [
{
level (integer) • Enrichment level
axes (array[string]) • Codes of attributes used as variant axes
attributes (array[string]) • Codes of attributes bind to this enrichment level
}
]
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Family variant label for the specified locale
}
}
Example
{"code": "shoes_by_size", "variant_attribute_sets": [{"level": 1, "axes": ["size"], "attributes": ["color"]}]}
{"code": "shoes_by_color","labels": {"en_US": "Shoes by color"}}
{"code": "shoes_without_axes", "variant_attribute_sets": [{"level": 1, "axes": [], "attributes": ["color"]}]}
RESPONSES
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
{
line
(integer)
• Line number
code
(string)
• Resource code
status_code
(integer)
• HTTP status code, see Client errors to understand the meaning of each code
message
(string)
• Message explaining the error
}
Example
{"line":1,"code":"shoes_by_size","status_code":201}
{"line":2,"code":"shoes_by_color","status_code":204}
{"line":3,"code":"mug","status_code":422, "message":"There should be at least one attribute defined as axis for the attribute set for level \"1\""}
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}Get a family variant
This endpoint allows you to get the information about a given family variant
REQUEST
get /api/rest/v1/families/{family_code}/variants/{code}
Path parameters
family_code
(string)
• This path parameter is used to specify the unique identifier of the family you want to retrieve or manipulate.
It is essential for identifying the specific family in the API requests.
Ensure that the family code is correctly formatted and corresponds to an existing family in the system.
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the family variant in JSON standard format
Body Format application/json
{
code
(string)
• Family variant code
common_attributes
(array [string])
• Codes of attributes that are common to all variants (not specific to any enrichment level)
variant_attribute_sets
(array [object])
: [
{
level (integer) • Enrichment level
axes (array) • Codes of attributes used as variant axes
attributes (array) • Codes of attributes bind to this enrichment level
}
]
labels
(object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Family variant label for the specified locale
}
}
Example
{
"code": "shoesVariant",
"labels": {
"en_US": "Shoes variant",
"fr_FR": "Variante de chaussures"
},
"common_attributes": [
"name",
"description"
],
"variant_attribute_sets": [
{
"level": 1,
"attributes": [
"color",
"material"
],
"axes": [
"color"
]
},
{
"level": 2,
"attributes": [
"sku",
"size"
],
"axes": [
"size"
]
}
]
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Update/create a family variant
This endpoint allows you to update a given family variant. Know more about Update behavior. Note that if no family variant exists for the given code, it creates it.
REQUEST
patch /api/rest/v1/families/{family_code}/variants/{code}
Path parameters
family_code
(string)
• This path parameter is used to specify the unique identifier of the family you want to retrieve or manipulate.
It is essential for identifying the specific family in the API requests.
Ensure that the family code is correctly formatted and corresponds to an existing family in the system.
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string)
• Family variant code
variant_attribute_sets
(array[object])
: [
{
level (integer) • Enrichment level
axes (array[string]) • Codes of attributes used as variant axes
attributes (array[string]) • Codes of attributes bind to this enrichment level
}
]
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Family variant label for the specified locale
}
}
Example
{
"code": "shoesVariant",
"labels": {
"en_US": "Shoes variant",
"fr_FR": "Variante de chaussures"
},
"variant_attribute_sets": [
{
"level": 1,
"attributes": [
"color",
"material"
],
"axes": [
"color"
]
},
{
"level": 2,
"attributes": [
"sku",
"size"
],
"axes": [
"size"
]
}
]
}RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
Successfully patched, response with empty body
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Attribute
Get list of attributes
This endpoint allows you to get a list of attributes. Attributes are paginated and sorted by code.
REQUEST
get /api/rest/v1/attributes
Path parameters
Ø
Query parameters
search
(string)
• Filter attributes,
for more details see the Filters section.
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
with_count
(boolean)
• Return the count of items in the response.
Be careful with that, on a big catalog, it can decrease performance in a significant way.
It is useful for understanding the size of the dataset being returned, especially when dealing with large collections.
Use it judiciously to avoid performance issues.
with_table_select_options
(boolean)
• Return the options of 'select' column types (of a table attribute) in the response.
When set to true, the response will include all available options for select-type columns in table attributes.
This is useful for retrieving all available options for select-type columns in table attributes, which is essential for form rendering and data validation.
If set to false, the response will not include select options, which can improve performance.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return attributes paginated. The response is paginated and includes links to navigate through the pages.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
items_count
(integer)
• Total number of items (only if with_count parameter is set to true)
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
code (string)
• Attribute code
type (string)
• Attribute type.
See type section for more details.
labels (object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$} (string,null)
• Attribute label for the specified locale
}
group (string)
• Attribute group
group_labels (object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$} (string,null)
• Group label for the specified locale
}
sort_order (integer)
• Order of the attribute in its group
localizable (boolean)
• Whether the attribute is localizable, i.e. can have one value by locale
scopable (boolean)
• Whether the attribute is scopable, i.e. can have one value by channel
available_locales (array [string])
• To make the attribute locale specfic, specify here for which locales it is specific
• To make the attribute locale specfic, specify here for which locales it is specific
unique (boolean)
• Whether two values for the attribute cannot be the same
useable_as_grid_filter (boolean)
• Whether the attribute can be used as a filter for the product grid in the PIM user interface
max_characters (integer,null)
• Number maximum of characters allowed for the value of the attribute when the attribute type is pim_catalog_text, pim_catalog_textarea or pim_catalog_identifier
validation_rule (string,null)
• Validation rule type used to validate any attribute value when the attribute type is pim_catalog_text or pim_catalog_identifier
validation_regexp (string,null)
• Regexp expression used to validate any attribute value when the attribute type is pim_catalog_text or pim_catalog_identifier
wysiwyg_enabled (boolean,null)
• Whether the WYSIWYG interface is shown when the attribute type is pim_catalog_textarea
number_min (string,null)
• Minimum integer value allowed when the attribute type is pim_catalog_metric, pim_catalog_price or pim_catalog_number
number_max (string,null)
• Maximum integer value allowed when the attribute type is pim_catalog_metric, pim_catalog_price or pim_catalog_number
decimals_allowed (boolean,null)
• Whether decimals are allowed when the attribute type is pim_catalog_metric, pim_catalog_price or pim_catalog_number
negative_allowed (boolean,null)
• Whether negative values are allowed when the attribute type is pim_catalog_metric or pim_catalog_number
metric_family (string,null)
• Metric family when the attribute type is pim_catalog_metric
default_metric_unit (string,null)
• Default metric unit when the attribute type is pim_catalog_metric
date_min (string,null)
• Minimum date allowed when the attribute type is pim_catalog_date
date_max (string,null)
• Maximum date allowed when the attribute type is pim_catalog_date
allowed_extensions (array [string])
• Extensions allowed when the attribute type is pim_catalog_file or pim_catalog_image
• Extensions allowed when the attribute type is pim_catalog_file or pim_catalog_image
max_file_size (string,null)
• Max file size in MB when the attribute type is pim_catalog_file or pim_catalog_image
reference_data_name (string,null)
• Reference entity code when the attribute type is akeneo_reference_entity or akeneo_reference_entity_collection
OR Asset family code when the attribute type is pim_catalog_asset_collection
default_value (boolean)
• Default value for a Yes/No attribute, applied when creating a new product or product model
table_configuration (array [object])
: [
{
code (string) • Column code
data_type (string) • Column data type
validations (object) • User defined validation constraints on the cell content
labels (object) • Column labels for each locale
is_required_for_completeness (boolean) • Defines if the column should be entirely filled for the attribute to be considered complete
}
]
is_main_identifier (boolean)
• Is this attribute main identifier when attribute type is pim_catalog_identifier
is_mandatory (boolean)
• This attribute must be enriched from the moment a product is created.
It will be mandatory across all families.
decimal_places_strategy (string,null)
• Defines the decimal places strategy.
Available options are round, forbid and trim.
decimal_places (number,null)
• Defines the number of decimal places when decimal places strategy is round or forbid
enable_option_creation_during_import (boolean,null)
• Whether new attribute options can be created automatically during product or product model import (CSV, XLSX),
when the attribute type is pim_catalog_simpleselect or pim_catalog_multiselect
max_items_count (number,null)
• Maximum number of items allowed in an asset collection when the attribute type is pim_catalog_asset_collection
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes?page=3&limit=3&with_count=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes?page=1&limit=3&with_count=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes?page=2&limit=3&with_count=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes?page=4&limit=3&with_count=true"
}
},
"current_page": 3,
"items_count": 10,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/sku"
}
},
"code": "sku",
"type": "pim_catalog_identifier",
"group": "other",
"unique": true,
"useable_as_grid_filter": true,
"allowed_extensions": [],
"metric_family": null,
"default_metric_unit": null,
"reference_data_name": null,
"available_locales": [],
"max_characters": null,
"validation_rule": null,
"validation_regexp": null,
"wysiwyg_enabled": false,
"number_min": null,
"number_max": null,
"decimals_allowed": false,
"negative_allowed": false,
"date_min": null,
"date_max": null,
"max_file_size": null,
"minimum_input_length": null,
"sort_order": 1,
"localizable": false,
"scopable": false,
"labels": {
"en_US": "Identifier",
"fr_FR": "Identifiant"
},
"guidelines": {},
"auto_option_sorting": null,
"default_value": null,
"is_mandatory": false,
"decimal_places": null,
"decimal_places_strategy": null,
"is_read_only": null,
"enable_option_creation_during_import": false,
"max_items_count": null,
"group_labels": {
"en_US": "Other",
"fr_FR": "Autre"
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/release_date"
}
},
"code": "release_date",
"type": "pim_catalog_date",
"group": "marketing",
"unique": false,
"useable_as_grid_filter": true,
"allowed_extensions": [],
"metric_family": null,
"default_metric_unit": null,
"reference_data_name": null,
"available_locales": [],
"max_characters": null,
"validation_rule": null,
"validation_regexp": null,
"wysiwyg_enabled": false,
"number_min": null,
"number_max": null,
"decimals_allowed": false,
"negative_allowed": false,
"date_min": "2017-06-28T08:00:00",
"date_max": "2017-08-08T22:00:00",
"max_file_size": null,
"minimum_input_length": null,
"sort_order": 1,
"localizable": false,
"scopable": false,
"labels": {
"en_US": "Sale date",
"fr_FR": "Date des soldes"
},
"guidelines": {},
"auto_option_sorting": null,
"default_value": null,
"is_mandatory": false,
"decimal_places": null,
"decimal_places_strategy": null,
"is_read_only": null,
"enable_option_creation_during_import": false,
"max_items_count": null,
"group_labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
}
},
{
"_links": {
"self": {
"href": "http://demo.akeneo.com/api/rest/v1/attributes/food_composition"
}
},
"code": "food_composition",
"type": "pim_catalog_table",
"group": "product",
"unique": false,
"useable_as_grid_filter": false,
"allowed_extensions": [],
"metric_family": null,
"default_metric_unit": null,
"reference_data_name": null,
"available_locales": [],
"max_characters": null,
"validation_rule": null,
"validation_regexp": null,
"wysiwyg_enabled": null,
"number_min": null,
"number_max": null,
"decimals_allowed": null,
"negative_allowed": null,
"date_min": null,
"date_max": null,
"max_file_size": null,
"minimum_input_length": null,
"sort_order": 0,
"localizable": false,
"scopable": false,
"labels": {
"en_US": "Composition",
"fr_FR": "Composition"
},
"guidelines": {},
"auto_option_sorting": null,
"default_value": null,
"is_mandatory": false,
"decimal_places": null,
"decimal_places_strategy": null,
"is_read_only": null,
"enable_option_creation_during_import": false,
"max_items_count": null,
"table_configuration": [
{
"code": "ingredient",
"data_type": "select",
"labels": {
"en_US": "Ingredient",
"fr_FR": "Ingrédient"
},
"validations": {},
"is_required_for_completeness": true
},
{
"code": "percentage",
"data_type": "number",
"labels": {
"en_US": "%",
"fr_FR": "%"
},
"validations": {
"max": 100,
"min": 0,
"decimals_allowed": true
},
"is_required_for_completeness": true
},
{
"code": "allergen",
"data_type": "boolean",
"labels": {
"en_US": "Allergen",
"fr_FR": "Allergène"
},
"validations": {},
"is_required_for_completeness": false
}
],
"group_labels": {
"en_US": "Product",
"fr_FR": "Produit"
}
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Create a new attribute
This endpoint allows you to create a new attribute.
REQUEST
post /api/rest/v1/attributes
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string)
• Attribute code
type
(string)
• Attribute type.
See type section for more details.
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Attribute label for the specified locale
}
group
(string)
• Attribute group
group_labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Group label for the specified locale
}
sort_order
(integer,
0 by default)
• Order of the attribute in its group
localizable
(boolean,
false by default)
• Whether the attribute is localizable, i.e. can have one value by locale
scopable
(boolean,
false by default)
• Whether the attribute is scopable, i.e. can have one value by channel
available_locales
(array[string])
• To make the attribute locale specfic, specify here for which locales it is specific
unique
(boolean)
• Whether two values for the attribute cannot be the same
useable_as_grid_filter
(boolean)
• Whether the attribute can be used as a filter for the product grid in the PIM user interface
max_characters
(integer,null)
• Number maximum of characters allowed for the value of the attribute when the attribute type is pim_catalog_text, pim_catalog_textarea or pim_catalog_identifier
validation_rule
(string,null)
• Validation rule type used to validate any attribute value when the attribute type is pim_catalog_text or pim_catalog_identifier
validation_regexp
(string,null)
• Regexp expression used to validate any attribute value when the attribute type is pim_catalog_text or pim_catalog_identifier
wysiwyg_enabled
(boolean,null)
• Whether the WYSIWYG interface is shown when the attribute type is pim_catalog_textarea
number_min
(string,null)
• Minimum integer value allowed when the attribute type is pim_catalog_metric, pim_catalog_price or pim_catalog_number
number_max
(string,null)
• Maximum integer value allowed when the attribute type is pim_catalog_metric, pim_catalog_price or pim_catalog_number
decimals_allowed
(boolean,null)
• Whether decimals are allowed when the attribute type is pim_catalog_metric, pim_catalog_price or pim_catalog_number
negative_allowed
(boolean,null)
• Whether negative values are allowed when the attribute type is pim_catalog_metric or pim_catalog_number
metric_family
(string,null)
• Metric family when the attribute type is pim_catalog_metric
default_metric_unit
(string,null)
• Default metric unit when the attribute type is pim_catalog_metric
date_min
(string,null)
• Minimum date allowed when the attribute type is pim_catalog_date
date_max
(string,null)
• Maximum date allowed when the attribute type is pim_catalog_date
allowed_extensions
(array[string])
• Extensions allowed when the attribute type is pim_catalog_file or pim_catalog_image
max_file_size
(string,null)
• Max file size in MB when the attribute type is pim_catalog_file or pim_catalog_image
reference_data_name
(string,null)
• Reference entity code when the attribute type is akeneo_reference_entity or akeneo_reference_entity_collection
OR Asset family code when the attribute type is pim_catalog_asset_collection
default_value
(boolean)
• Default value for a Yes/No attribute, applied when creating a new product or product model
table_configuration
(array[object])
: [
{
code (string) • Column code
data_type (string) • Column data type
validations (object) • User defined validation constraints on the cell content
labels (object) • Column labels for each locale
is_required_for_completeness (boolean) • Defines if the column should be entirely filled for the attribute to be considered complete
}
]
is_main_identifier
(boolean)
• Is this attribute main identifier when attribute type is pim_catalog_identifier
is_mandatory
(boolean)
• This attribute must be enriched from the moment a product is created.
It will be mandatory across all families.
decimal_places_strategy
(string,null)
• Defines the decimal places strategy.
Available options are round, forbid and trim.
decimal_places
(number,null)
• Defines the number of decimal places when decimal places strategy is round or forbid
enable_option_creation_during_import
(boolean,null)
• Whether new attribute options can be created automatically during product or product model import (CSV, XLSX),
when the attribute type is pim_catalog_simpleselect or pim_catalog_multiselect
max_items_count
(number,null)
• Maximum number of items allowed in an asset collection when the attribute type is pim_catalog_asset_collection
}
Example
{
"code": "release_date",
"type": "pim_catalog_date",
"group": "marketing",
"group_labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
},
"unique": false,
"useable_as_grid_filter": true,
"allowed_extensions": [],
"metric_family": null,
"default_metric_unit": null,
"reference_data_name": null,
"available_locales": [],
"max_characters": null,
"validation_rule": null,
"validation_regexp": null,
"wysiwyg_enabled": null,
"number_min": null,
"number_max": null,
"decimals_allowed": null,
"negative_allowed": null,
"date_min": "2017-06-28T08:00:00",
"date_max": "2017-08-08T22:00:00",
"max_file_size": null,
"minimum_input_length": null,
"sort_order": 1,
"localizable": false,
"scopable": false,
"default_value": null,
"labels": {
"en_US": "Sale date",
"fr_FR": "Date des soldes"
},
"is_mandatory": false,
"decimal_places_strategy": null,
"decimal_places": null,
"enable_option_creation_during_import": false,
"max_items_count": null
}RESPONSES
Successfully created attribute, returns empty body
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Update/create several attributes
This endpoint allows you to update and/or create several attributes at once
REQUEST
patch /api/rest/v1/attributes
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is an attribute in JSON standard format
{
code
(string)
• Attribute code
type
(string)
• Attribute type.
See type section for more details.
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Attribute label for the specified locale
}
group
(string)
• Attribute group
group_labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Group label for the specified locale
}
sort_order
(integer,
0 by default)
• Order of the attribute in its group
localizable
(boolean,
false by default)
• Whether the attribute is localizable, i.e. can have one value by locale
scopable
(boolean,
false by default)
• Whether the attribute is scopable, i.e. can have one value by channel
available_locales
(array[string])
• To make the attribute locale specfic, specify here for which locales it is specific
unique
(boolean)
• Whether two values for the attribute cannot be the same
useable_as_grid_filter
(boolean)
• Whether the attribute can be used as a filter for the product grid in the PIM user interface
max_characters
(integer,null)
• Number maximum of characters allowed for the value of the attribute when the attribute type is pim_catalog_text, pim_catalog_textarea or pim_catalog_identifier
validation_rule
(string,null)
• Validation rule type used to validate any attribute value when the attribute type is pim_catalog_text or pim_catalog_identifier
validation_regexp
(string,null)
• Regexp expression used to validate any attribute value when the attribute type is pim_catalog_text or pim_catalog_identifier
wysiwyg_enabled
(boolean,null)
• Whether the WYSIWYG interface is shown when the attribute type is pim_catalog_textarea
number_min
(string,null)
• Minimum integer value allowed when the attribute type is pim_catalog_metric, pim_catalog_price or pim_catalog_number
number_max
(string,null)
• Maximum integer value allowed when the attribute type is pim_catalog_metric, pim_catalog_price or pim_catalog_number
decimals_allowed
(boolean,null)
• Whether decimals are allowed when the attribute type is pim_catalog_metric, pim_catalog_price or pim_catalog_number
negative_allowed
(boolean,null)
• Whether negative values are allowed when the attribute type is pim_catalog_metric or pim_catalog_number
metric_family
(string,null)
• Metric family when the attribute type is pim_catalog_metric
default_metric_unit
(string,null)
• Default metric unit when the attribute type is pim_catalog_metric
date_min
(string,null)
• Minimum date allowed when the attribute type is pim_catalog_date
date_max
(string,null)
• Maximum date allowed when the attribute type is pim_catalog_date
allowed_extensions
(array[string])
• Extensions allowed when the attribute type is pim_catalog_file or pim_catalog_image
max_file_size
(string,null)
• Max file size in MB when the attribute type is pim_catalog_file or pim_catalog_image
reference_data_name
(string,null)
• Reference entity code when the attribute type is akeneo_reference_entity or akeneo_reference_entity_collection
OR Asset family code when the attribute type is pim_catalog_asset_collection
default_value
(boolean)
• Default value for a Yes/No attribute, applied when creating a new product or product model
table_configuration
(array[object])
: [
{
code (string) • Column code
data_type (string) • Column data type
validations (object) • User defined validation constraints on the cell content
labels (object) • Column labels for each locale
is_required_for_completeness (boolean) • Defines if the column should be entirely filled for the attribute to be considered complete
}
]
is_main_identifier
(boolean)
• Is this attribute main identifier when attribute type is pim_catalog_identifier
is_mandatory
(boolean)
• This attribute must be enriched from the moment a product is created.
It will be mandatory across all families.
decimal_places_strategy
(string,null)
• Defines the decimal places strategy.
Available options are round, forbid and trim.
decimal_places
(number,null)
• Defines the number of decimal places when decimal places strategy is round or forbid
enable_option_creation_during_import
(boolean,null)
• Whether new attribute options can be created automatically during product or product model import (CSV, XLSX),
when the attribute type is pim_catalog_simpleselect or pim_catalog_multiselect
max_items_count
(number,null)
• Maximum number of items allowed in an asset collection when the attribute type is pim_catalog_asset_collection
}
Example
{"code":"description","useable_as_grid_filter":true}
{"code":"short_description","group":"marketig"}
{"code":"release_date","date_min":"2017-06-28T08:00:00"}
RESPONSES
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
{
line
(integer)
• Line number
code
(string)
• Resource code
status_code
(integer)
• HTTP status code, see Client errors to understand the meaning of each code
message
(string)
• Message explaining the error
}
Example
{"line":1,"code":"description","status_code":201}
{"line":2,"code":"short_description","status_code":422,"message":"Group \"marketig\" does not exist."}
{"line":3,"code":"release_date","status_code":204}
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}Get an attribute
This endpoint allows you to get the information about a given attribute
REQUEST
get /api/rest/v1/attributes/{code}
Path parameters
code
(string)
• 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.
Query parameters
with_table_select_options
(boolean)
• Return the options of 'select' column types (of a table attribute) in the response.
When set to true, the response will include all available options for select-type columns in table attributes.
This is useful for retrieving all available options for select-type columns in table attributes, which is essential for form rendering and data validation.
If set to false, the response will not include select options, which can improve performance.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the attribute in JSON standard format
Body Format application/json
{
code
(string)
• Attribute code
type
(string)
• Attribute type.
See type section for more details.
labels
(object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Attribute label for the specified locale
}
group
(string)
• Attribute group
group_labels
(object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Group label for the specified locale
}
sort_order
(integer)
• Order of the attribute in its group
localizable
(boolean)
• Whether the attribute is localizable, i.e. can have one value by locale
scopable
(boolean)
• Whether the attribute is scopable, i.e. can have one value by channel
available_locales
(array [string])
• To make the attribute locale specfic, specify here for which locales it is specific
unique
(boolean)
• Whether two values for the attribute cannot be the same
useable_as_grid_filter
(boolean)
• Whether the attribute can be used as a filter for the product grid in the PIM user interface
max_characters
(integer,null)
• Number maximum of characters allowed for the value of the attribute when the attribute type is pim_catalog_text, pim_catalog_textarea or pim_catalog_identifier
validation_rule
(string,null)
• Validation rule type used to validate any attribute value when the attribute type is pim_catalog_text or pim_catalog_identifier
validation_regexp
(string,null)
• Regexp expression used to validate any attribute value when the attribute type is pim_catalog_text or pim_catalog_identifier
wysiwyg_enabled
(boolean,null)
• Whether the WYSIWYG interface is shown when the attribute type is pim_catalog_textarea
number_min
(string,null)
• Minimum integer value allowed when the attribute type is pim_catalog_metric, pim_catalog_price or pim_catalog_number
number_max
(string,null)
• Maximum integer value allowed when the attribute type is pim_catalog_metric, pim_catalog_price or pim_catalog_number
decimals_allowed
(boolean,null)
• Whether decimals are allowed when the attribute type is pim_catalog_metric, pim_catalog_price or pim_catalog_number
negative_allowed
(boolean,null)
• Whether negative values are allowed when the attribute type is pim_catalog_metric or pim_catalog_number
metric_family
(string,null)
• Metric family when the attribute type is pim_catalog_metric
default_metric_unit
(string,null)
• Default metric unit when the attribute type is pim_catalog_metric
date_min
(string,null)
• Minimum date allowed when the attribute type is pim_catalog_date
date_max
(string,null)
• Maximum date allowed when the attribute type is pim_catalog_date
allowed_extensions
(array [string])
• Extensions allowed when the attribute type is pim_catalog_file or pim_catalog_image
max_file_size
(string,null)
• Max file size in MB when the attribute type is pim_catalog_file or pim_catalog_image
reference_data_name
(string,null)
• Reference entity code when the attribute type is akeneo_reference_entity or akeneo_reference_entity_collection
OR Asset family code when the attribute type is pim_catalog_asset_collection
default_value
(boolean)
• Default value for a Yes/No attribute, applied when creating a new product or product model
table_configuration
(array [object])
: [
{
code (string) • Column code
data_type (string) • Column data type
validations (object) • User defined validation constraints on the cell content
labels (object) • Column labels for each locale
is_required_for_completeness (boolean) • Defines if the column should be entirely filled for the attribute to be considered complete
}
]
is_main_identifier
(boolean)
• Is this attribute main identifier when attribute type is pim_catalog_identifier
is_mandatory
(boolean)
• This attribute must be enriched from the moment a product is created.
It will be mandatory across all families.
decimal_places_strategy
(string,null)
• Defines the decimal places strategy.
Available options are round, forbid and trim.
decimal_places
(number,null)
• Defines the number of decimal places when decimal places strategy is round or forbid
enable_option_creation_during_import
(boolean,null)
• Whether new attribute options can be created automatically during product or product model import (CSV, XLSX),
when the attribute type is pim_catalog_simpleselect or pim_catalog_multiselect
max_items_count
(number,null)
• Maximum number of items allowed in an asset collection when the attribute type is pim_catalog_asset_collection
}
Example
{
"code": "release_date",
"type": "pim_catalog_date",
"group": "marketing",
"group_labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
},
"unique": false,
"useable_as_grid_filter": true,
"allowed_extensions": [],
"metric_family": null,
"default_metric_unit": null,
"reference_data_name": null,
"available_locales": [],
"max_characters": null,
"validation_rule": null,
"validation_regexp": null,
"wysiwyg_enabled": null,
"number_min": null,
"number_max": null,
"decimals_allowed": null,
"negative_allowed": null,
"date_min": "2017-06-28T08:00:00",
"date_max": "2017-08-08T22:00:00",
"max_file_size": null,
"minimum_input_length": null,
"sort_order": 1,
"localizable": false,
"scopable": false,
"default_value": null,
"labels": {
"en_US": "Sale date",
"fr_FR": "Date des soldes"
},
"is_mandatory": false,
"decimal_places_strategy": null,
"decimal_places": null,
"enable_option_creation_during_import": false,
"max_items_count": null
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Update/create an attribute
This endpoint allows you to update a given attribute. Know more about Update behavior. Note that if no attribute exists for the given code, it creates it.
REQUEST
patch /api/rest/v1/attributes/{code}
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string)
• Attribute code
type
(string)
• Attribute type.
See type section for more details.
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Attribute label for the specified locale
}
group
(string)
• Attribute group
group_labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Group label for the specified locale
}
sort_order
(integer,
0 by default)
• Order of the attribute in its group
localizable
(boolean,
false by default)
• Whether the attribute is localizable, i.e. can have one value by locale
scopable
(boolean,
false by default)
• Whether the attribute is scopable, i.e. can have one value by channel
available_locales
(array[string])
• To make the attribute locale specfic, specify here for which locales it is specific
unique
(boolean)
• Whether two values for the attribute cannot be the same
useable_as_grid_filter
(boolean)
• Whether the attribute can be used as a filter for the product grid in the PIM user interface
max_characters
(integer,null)
• Number maximum of characters allowed for the value of the attribute when the attribute type is pim_catalog_text, pim_catalog_textarea or pim_catalog_identifier
validation_rule
(string,null)
• Validation rule type used to validate any attribute value when the attribute type is pim_catalog_text or pim_catalog_identifier
validation_regexp
(string,null)
• Regexp expression used to validate any attribute value when the attribute type is pim_catalog_text or pim_catalog_identifier
wysiwyg_enabled
(boolean,null)
• Whether the WYSIWYG interface is shown when the attribute type is pim_catalog_textarea
number_min
(string,null)
• Minimum integer value allowed when the attribute type is pim_catalog_metric, pim_catalog_price or pim_catalog_number
number_max
(string,null)
• Maximum integer value allowed when the attribute type is pim_catalog_metric, pim_catalog_price or pim_catalog_number
decimals_allowed
(boolean,null)
• Whether decimals are allowed when the attribute type is pim_catalog_metric, pim_catalog_price or pim_catalog_number
negative_allowed
(boolean,null)
• Whether negative values are allowed when the attribute type is pim_catalog_metric or pim_catalog_number
metric_family
(string,null)
• Metric family when the attribute type is pim_catalog_metric
default_metric_unit
(string,null)
• Default metric unit when the attribute type is pim_catalog_metric
date_min
(string,null)
• Minimum date allowed when the attribute type is pim_catalog_date
date_max
(string,null)
• Maximum date allowed when the attribute type is pim_catalog_date
allowed_extensions
(array[string])
• Extensions allowed when the attribute type is pim_catalog_file or pim_catalog_image
max_file_size
(string,null)
• Max file size in MB when the attribute type is pim_catalog_file or pim_catalog_image
reference_data_name
(string,null)
• Reference entity code when the attribute type is akeneo_reference_entity or akeneo_reference_entity_collection
OR Asset family code when the attribute type is pim_catalog_asset_collection
default_value
(boolean)
• Default value for a Yes/No attribute, applied when creating a new product or product model
table_configuration
(array[object])
: [
{
code (string) • Column code
data_type (string) • Column data type
validations (object) • User defined validation constraints on the cell content
labels (object) • Column labels for each locale
is_required_for_completeness (boolean) • Defines if the column should be entirely filled for the attribute to be considered complete
}
]
is_main_identifier
(boolean)
• Is this attribute main identifier when attribute type is pim_catalog_identifier
is_mandatory
(boolean)
• This attribute must be enriched from the moment a product is created.
It will be mandatory across all families.
decimal_places_strategy
(string,null)
• Defines the decimal places strategy.
Available options are round, forbid and trim.
decimal_places
(number,null)
• Defines the number of decimal places when decimal places strategy is round or forbid
enable_option_creation_during_import
(boolean,null)
• Whether new attribute options can be created automatically during product or product model import (CSV, XLSX),
when the attribute type is pim_catalog_simpleselect or pim_catalog_multiselect
max_items_count
(number,null)
• Maximum number of items allowed in an asset collection when the attribute type is pim_catalog_asset_collection
}
Example
{
"code": "release_date",
"type": "pim_catalog_date",
"group": "marketing",
"group_labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
},
"unique": false,
"useable_as_grid_filter": true,
"allowed_extensions": [],
"metric_family": null,
"default_metric_unit": null,
"reference_data_name": null,
"available_locales": [],
"max_characters": null,
"validation_rule": null,
"validation_regexp": null,
"wysiwyg_enabled": null,
"number_min": null,
"number_max": null,
"decimals_allowed": null,
"negative_allowed": null,
"date_min": "2017-06-28T08:00:00",
"date_max": "2017-08-08T22:00:00",
"max_file_size": null,
"minimum_input_length": null,
"sort_order": 1,
"localizable": false,
"scopable": false,
"default_value": null,
"labels": {
"en_US": "Sale date",
"fr_FR": "Date des soldes"
},
"is_mandatory": false,
"decimal_places_strategy": null,
"decimal_places": null,
"enable_option_creation_during_import": false,
"max_items_count": null
}RESPONSES
Successfully created or updated, empty response body
Body Format application/json
Ø
Successfully patched, response with empty body
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Attribute option
Get list of attribute options
This endpoint allows you to get a list of attribute options. Attribute options are paginated and sorted by code.
REQUEST
get /api/rest/v1/attributes/{attribute_code}/options
Path parameters
attribute_code
(string)
• This path parameter is used to specify the unique identifier of the attribute you want to retrieve or manipulate.
It is essential for identifying the specific attribute in the API requests.
Ensure that the attribute code is correctly formatted and corresponds to an existing attribute in the system.
Query parameters
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
with_count
(boolean)
• Return the count of items in the response.
Be careful with that, on a big catalog, it can decrease performance in a significant way.
It is useful for understanding the size of the dataset being returned, especially when dealing with large collections.
Use it judiciously to avoid performance issues.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return attribute options paginated. The response is paginated and includes links to navigate through the pages.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
items_count
(integer)
• Total number of items (only if with_count parameter is set to true)
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
code (string)
• Code of option
attribute (string)
• Code of attribute related to the attribute option
sort_order (integer)
• Order of attribute option
labels (object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$} (string,null)
• Attribute option label for the specified locale
}
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options?page=3&limit=3&with_count=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options?page=1&limit=3&with_count=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options?page=2&limit=3&with_count=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options?page=4&limit=3&with_count=true"
}
},
"current_page": 3,
"items_count": 10,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options/red"
}
},
"code": "red",
"attribute": "a_simple_select",
"sort_order": 1,
"labels": {
"en_US": "Red",
"fr_FR": "Rouge"
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options/black"
}
},
"code": "black",
"attribute": "a_simple_select",
"sort_order": 2,
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options/purple"
}
},
"code": "purple",
"attribute": "a_simple_select",
"sort_order": 3,
"labels": {
"en_US": "Purple",
"fr_FR": "Violet"
}
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Create a new attribute option
This endpoint allows you to create a new attribute option
REQUEST
post /api/rest/v1/attributes/{attribute_code}/options
Path parameters
attribute_code
(string)
• This path parameter is used to specify the unique identifier of the attribute you want to retrieve or manipulate.
It is essential for identifying the specific attribute in the API requests.
Ensure that the attribute code is correctly formatted and corresponds to an existing attribute in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
Example
{
"code": "black",
"attribute": "a_simple_select",
"sort_order": 2,
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Update/create several attribute options
This endpoint allows you to update and/or create several attribute options at once
REQUEST
patch /api/rest/v1/attributes/{attribute_code}/options
Path parameters
attribute_code
(string)
• This path parameter is used to specify the unique identifier of the attribute you want to retrieve or manipulate.
It is essential for identifying the specific attribute in the API requests.
Ensure that the attribute code is correctly formatted and corresponds to an existing attribute in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is an attribute option in JSON standard format
Example
{"code":"black","attribute":"a_simple_select","labels":{"en_US":"Black","fr_FR":"Noir"}}
{"code":"red","label":{"en_US": "Red","fr_FR": "Rouge"}}
{"code":"yellow","labels":{"en_US": "Yellow","fr_FR": "Jaune"}}
RESPONSES
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
{
line
(integer)
• Line number
code
(string)
• Resource code
status_code
(integer)
• HTTP status code, see Client errors to understand the meaning of each code
message
(string)
• Message explaining the error
}
Example
{"line":1,"code":"black","status_code":201}
{"line":2,"code":"red","status_code":422,"message":"Property \"label\" does not exist. Check the API format documentation."}
{"line":3,"code":"yellow","status_code":204}
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 429,
"message": "You have exceeded the limit of API requests per second."
}Get an attribute option
This endpoint allows you to get the information about a given attribute option
REQUEST
get /api/rest/v1/attributes/{attribute_code}/options/{code}
Path parameters
attribute_code
(string)
• This path parameter is used to specify the unique identifier of the attribute you want to retrieve or manipulate.
It is essential for identifying the specific attribute in the API requests.
Ensure that the attribute code is correctly formatted and corresponds to an existing attribute in the system.
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the attribute option in JSON standard format
Body Format application/json
{
code
(string)
• Code of option
attribute
(string)
• Code of attribute related to the attribute option
sort_order
(integer)
• Order of attribute option
labels
(object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Attribute option label for the specified locale
}
}
Example
{
"code": "black",
"attribute": "a_simple_select",
"sort_order": 2,
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Update/create an attribute option
This endpoint allows you to update a given attribute option. Know more about Update behavior. Note that if no attribute option exists for the given code, it creates it. Please note that this endpoint applies a rate limit of 3 concurrent API requests per second.
REQUEST
patch /api/rest/v1/attributes/{attribute_code}/options/{code}
Path parameters
attribute_code
(string)
• This path parameter is used to specify the unique identifier of the attribute you want to retrieve or manipulate.
It is essential for identifying the specific attribute in the API requests.
Ensure that the attribute code is correctly formatted and corresponds to an existing attribute in the system.
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
Example
{
"code": "black",
"attribute": "a_simple_select",
"sort_order": 2,
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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 • URI of the updated resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 429,
"message": "You have exceeded the limit of API requests per second."
}Attribute group
Get list of attribute groups
This endpoint allows you to get a list of attribute groups. Attribute groups are paginated and sorted by code.
REQUEST
get /api/rest/v1/attribute-groups
Path parameters
Ø
Query parameters
search
(string)
• Filter attribute groups,
for more details see the Filters section.
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
with_count
(boolean)
• Return the count of items in the response.
Be careful with that, on a big catalog, it can decrease performance in a significant way.
It is useful for understanding the size of the dataset being returned, especially when dealing with large collections.
Use it judiciously to avoid performance issues.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return attribute groups paginated. The response is paginated and includes links to navigate through the pages.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
items_count
(integer)
• Total number of items (only if with_count parameter is set to true)
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
code (string)
• Attribute group code
sort_order (integer)
• Attribute group order among other attribute groups
attributes (array [string])
• Attribute codes that compose the attribute group
• Attribute codes that compose the attribute group
labels (object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$} (string,null)
• Attribute group label for the locale
}
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attribute-groups?page=3&limit=2&with_count=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/attribute-groups?page=1&limit=2&with_count=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/attribute-groups?page=2&limit=2&with_count=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/attribute-groups?page=4&limit=2&with_count=true"
}
},
"current_page": 3,
"items_count": 10,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attribute-groups/marketing"
}
},
"code": "marketing",
"sort_order": 4,
"attributes": [
"sku",
"name",
"description",
"response_time",
"release_date",
"price"
],
"labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/attribute-groups/technical"
}
},
"code": "technical",
"sort_order": 5,
"attributes": [
"weight",
"maximum_scan_size",
"color_scanning",
"power_requirements",
"maximum_print_size",
"sensor_type",
"total_megapixels",
"optical_zoom",
"camera_type"
],
"labels": {
"en_US": "Technical",
"fr_FR": "Technique"
}
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Create a new attribute group
This endpoint allows you to create a new attribute group.
REQUEST
post /api/rest/v1/attribute-groups
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string)
• Attribute group code
sort_order
(integer,
0 by default)
• Attribute group order among other attribute groups
attributes
(array[string],
[] by default)
• Attribute codes that compose the attribute group
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Attribute group label for the locale
}
}
Example
{
"code": "marketing",
"sort_order": 4,
"attributes": [
"sku",
"name",
"description",
"response_time",
"release_date",
"price"
],
"labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
}
}RESPONSES
successfully created, response with empty body
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Update/create several attribute groups
This endpoint allows you to update and/or create several attribute groups at once
REQUEST
patch /api/rest/v1/attribute-groups
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is an attribute group in JSON standard format
{
code
(string)
• Attribute group code
sort_order
(integer,
0 by default)
• Attribute group order among other attribute groups
attributes
(array[string],
[] by default)
• Attribute codes that compose the attribute group
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Attribute group label for the locale
}
}
Example
{"code":"technical","labels":{"en_US": "Technical", "fr_FR": "Technique"}}
{"code":"marketing","type":"bar"}
{"code":"design","sort_order":7}
RESPONSES
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
{
line
(integer)
• Line number
code
(string)
• Resource code
status_code
(integer)
• HTTP status code, see Client errors to understand the meaning of each code
message
(string)
• Message explaining the error
}
Example
{"line":1,"code":"technical","status_code":201}
{"line":2,"code":"marketing","status_code":422,"message":"Property \"type\" does not exist. Check the standard format documentation.","_links":{"documentation":{"href":"http:\/\/api.akeneo.com\/api-reference.html#patch_attribute_groups__code_"}}}
{"line":3,"code":"design","status_code":204}
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}Get an attribute group
This endpoint allows you to get the information about a given attribute group
REQUEST
get /api/rest/v1/attribute-groups/{code}
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the attribute group in JSON standard format
Body Format application/json
{
code
(string)
• Attribute group code
sort_order
(integer)
• Attribute group order among other attribute groups
attributes
(array [string])
• Attribute codes that compose the attribute group
labels
(object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Attribute group label for the locale
}
}
Example
{
"code": "marketing",
"sort_order": 4,
"attributes": [
"sku",
"name",
"description",
"response_time",
"release_date",
"price"
],
"labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Update/create an attribute group
This endpoint allows you to update a given attribute group. Know more about Update behavior. Note that if no attribute group exists for the given code, it creates it.
REQUEST
patch /api/rest/v1/attribute-groups/{code}
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string)
• Attribute group code
sort_order
(integer,
0 by default)
• Attribute group order among other attribute groups
attributes
(array[string],
[] by default)
• Attribute codes that compose the attribute group
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Attribute group label for the locale
}
}
Example
{
"code": "marketing",
"sort_order": 4,
"attributes": [
"sku",
"name",
"description",
"response_time",
"release_date",
"price"
],
"labels": {
"en_US": "Marketing",
"fr_FR": "Marketing"
}
}RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
Successfully patched, response with empty body
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Association type
Get a list of association types
This endpoint allows you to get a list of association types. Association types are paginated and sorted by code.
REQUEST
get /api/rest/v1/association-types
Path parameters
Ø
Query parameters
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
with_count
(boolean)
• Return the count of items in the response.
Be careful with that, on a big catalog, it can decrease performance in a significant way.
It is useful for understanding the size of the dataset being returned, especially when dealing with large collections.
Use it judiciously to avoid performance issues.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return association types paginated. The response is paginated and includes links to navigate through the pages.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
items_count
(integer)
• Total number of items (only if with_count parameter is set to true)
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
code (string)
• Association type code
labels (object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$} (string,null)
• Association type label for the locale
}
is_quantified (boolean)
• When true, the association is a quantified association
is_two_way (boolean)
• When true, the association is a bidirectional association
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/association-types?page=2&limit=3&with_count=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/association-types?page=1&limit=3&with_count=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/association-types?page=1&limit=3&with_count=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/association-types?page=3&limit=3&with_count=true"
}
},
"current_page": 2,
"items_count": 10,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/association-types/X_SELL"
}
},
"code": "X_SELL",
"labels": {
"en_US": "Cross sell",
"fr_FR": "Vente croisée"
},
"is_quantified": false,
"is_two_way": false
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/association-types/UPSELL"
}
},
"code": "UPSELL",
"labels": {
"en_US": "Upsell",
"fr_FR": "Vente incitative"
},
"is_quantified": false,
"is_two_way": false
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/association-types/SUBSTITUTION"
}
},
"code": "SUBSTITUTION",
"labels": {
"en_US": "Substitution",
"fr_FR": "Remplacement"
},
"is_quantified": false,
"is_two_way": false
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Create a new association type
This endpoint allows you to create a new association type
REQUEST
post /api/rest/v1/association-types
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string)
• Association type code
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Association type label for the locale
}
is_quantified
(boolean,
false by default)
• When true, the association is a quantified association
is_two_way
(boolean,
false by default)
• When true, the association is a bidirectional association
}
Example
{
"code": "upsell",
"labels": {
"en_US": "Upsell",
"fr_FR": "Vente incitative"
},
"is_quantified": false,
"is_two_way": false
}RESPONSES
Successfully created association type, empty response body
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Update/create several association types
This endpoint allows you to update and/or create several association types at once
REQUEST
patch /api/rest/v1/association-types
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is an association type in JSON standard format
{
code
(string)
• Association type code
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Association type label for the locale
}
is_quantified
(boolean,
false by default)
• When true, the association is a quantified association
is_two_way
(boolean,
false by default)
• When true, the association is a bidirectional association
}
Example
{"code":"new_sell"}
{"code":"substitution", "type":"bar"}
{"code":"x_cross_sell", "is_two_way": true, "is_quantified": false}
RESPONSES
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
{
line
(integer)
• Line number
code
(string)
• Resource code
status_code
(integer)
• HTTP status code, see Client errors to understand the meaning of each code
message
(string)
• Message explaining the error
}
Example
{"line":1,"code":"new_sell","status_code":201}
{"line":2,"code":"substitution","status_code":422,"message":"Property \"type\" does not exist. Check the standard format documentation.","_links":{"documentation":{"href":"https:\/\/api.akeneo.com\/api-reference.html#patch_association_types__code_"}}}
{"line":3,"code":"x_cross_sell","status_code":204}
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}Get an association type
This endpoint allows you to get the information about a given association type
REQUEST
get /api/rest/v1/association-types/{code}
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the association type in JSON standard format
Body Format application/json
{
code
(string)
• Association type code
labels
(object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Association type label for the locale
}
is_quantified
(boolean)
• When true, the association is a quantified association
is_two_way
(boolean)
• When true, the association is a bidirectional association
}
Example
{
"code": "upsell",
"labels": {
"en_US": "Upsell",
"fr_FR": "Vente incitative"
},
"is_quantified": false,
"is_two_way": false
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Update/create an association type
This endpoint allows you to update a given association type. Know more about Update behavior. Note that if no association type exists for the given code, it creates it.
REQUEST
patch /api/rest/v1/association-types/{code}
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string)
• Association type code
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Association type label for the locale
}
is_quantified
(boolean,
false by default)
• When true, the association is a quantified association
is_two_way
(boolean,
false by default)
• When true, the association is a bidirectional association
}
Example
{
"code": "upsell",
"labels": {
"en_US": "Upsell",
"fr_FR": "Vente incitative"
},
"is_quantified": false,
"is_two_way": false
}RESPONSES
Successfully created association type, empty response body
Body Format application/json
Ø
Successfully updated association type, empty response body
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Category
Get the list of categories
This endpoint allows you to get a list of categories. Categories are paginated and sorted by root/left.
You can filter the categories by using the search query parameter, which supports searching by category code or label.
The response includes the category's code, parent code, labels, values, and channel requirements.
You can also specify the with_position query parameter to include the position of the category in its level.
The with_enriched_attributes query parameter allows you to include enriched attributes.
REQUEST
get /api/rest/v1/categories
Path parameters
Ø
Query parameters
search
(string)
• The search query parameter allows you to filter categories based on specific criteria.
For more details see the Filters section.
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
with_count
(boolean)
• Return the count of items in the response.
Be careful with that, on a big catalog, it can decrease performance in a significant way.
It is useful for understanding the size of the dataset being returned, especially when dealing with large collections.
Use it judiciously to avoid performance issues.
with_position
(boolean)
• Return information about the category's position within its category tree.
When set to true, the response will include the position of the category in its level, which can be useful for understanding the hierarchy and order of categories.
If set to false, the response will not include this information, which can improve performance.
with_enriched_attributes
(boolean)
• Return the attribute values of the category.
When set to true, the response will include the values of all attributes associated with the category.
This is useful for retrieving detailed information about the category's attributes, such as their values and configurations.
If set to false, the response will not include attribute values, which can improve performance
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return categories paginated. The response is paginated and includes links to navigate through the pages.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
items_count
(integer)
• Total number of items (only if with_count parameter is set to true)
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
code (string)
• Category code
parent (string,null)
• Category code of the parent's category
updated (string)
• Date of the last update
position (integer)
• Position of the category in its level, start from 1 (only available when query parameter with_position is set to true)
labels (object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$} (string,null)
• Category label for the specified locale
}
channel_requirements (array [string])
• List of Channel codes on which the category is required for products completeness.
Only category trees can be required, not child categories.
• List of Channel codes on which the category is required for products completeness.
Only category trees can be required, not child categories.
values (object)
: {
{attributeCode|attributeUuid|channel|locale} (object)
: {
type
(string) • The attribute type
locale
(string,null) • Locale code of the attribute value
channel
(string,null) • Channel code of the attribute value
attribute_code
(string) • The attribute code with its uuid (attributeCode|attributeUuid)
data
(string) • Attribute value
}
}
validations (object)
: {
max_categories_per_product (integer)
• Set maximum number of categories per product
only_leaves (boolean)
• Restrict categorization to the lowest level
is_mandatory (boolean)
• Set category as mandatory for every product
}
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/categories?page=2&limit=5&with_count=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/categories?page=1&limit=5&with_count=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/categories?page=1&limit=5&with_count=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/categories?page=3&limit=5&with_count=true"
}
},
"current_page": 2,
"items_count": 10,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/categories/winter_collection"
}
},
"code": "winter_collection",
"parent": null,
"updated": "2021-05-21T11:32:00+02:00",
"position": 1,
"labels": {
"en_US": "Winter collection",
"fr_FR": "Collection hiver",
"de_DE": "Winter-Kollektion"
},
"values": {
"description|96b88bf4-c2b7-4b64-a1f9-5d4876c02c26|ecommerce|en_US": {
"data": "<p>Winter collection description</p>\\n",
"type": "textarea",
"channel": "ecommerce",
"locale": "en_US",
"attribute_code": "description|96b88bf4-c2b7-4b64-a1f9-5d4876c02c26"
},
"image_1|871b8686-79b5-415c-9c6f-a38f8732dfb7|ecommerce|en_US": {
"data": {
"size": 1401359,
"extension": "jpg",
"file_path": "2/d/c/7/2dc791671d726e7438219d5dc7fd51a53d6bf2bb_IMG_7860.jpg",
"mime_type": "image/jpeg",
"original_filename": "IMG_7860.jpg"
},
"type": "image",
"channel": "ecommerce",
"locale": "en_US",
"attribute_code": "image_1|871b8686-79b5-415c-9c6f-a38f8732dfb7"
}
},
"channel_requirements": [
"ecommerce",
"mobile"
]
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/categories/woman"
}
},
"code": "woman",
"parent": "winter_collection",
"updated": "2021-04-21T10:41:02+02:00",
"position": 1,
"labels": {
"en_US": "Woman",
"fr_FR": "Femme",
"de_DE": "Damen"
},
"values": {},
"channel_requirements": [
"ecommerce",
"mobile"
]
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/categories/man"
}
},
"code": "man",
"parent": "winter_collection",
"updated": "2021-03-02T12:59:59+02:00",
"position": 2,
"labels": {
"en_US": "Man",
"fr_FR": "Homme",
"de_DE": "Herren"
},
"values": {},
"channel_requirements": []
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/categories/kids"
}
},
"code": "kids",
"parent": "winter_collection",
"updated": "2021-01-03T12:40:00+02:00",
"position": 3,
"labels": {
"en_US": "kids",
"fr_FR": "Enfant",
"de_DE": "Kinder"
},
"values": {},
"channel_requirements": []
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/categories/summer_collection"
}
},
"code": "summer_collection",
"parent": null,
"updated": "2021-04-04T09:42:00+02:00",
"position": 1,
"labels": {
"en_US": "Summer collection",
"fr_FR": "Collection été",
"de_DE": "Sommer-Kollektion"
},
"values": {},
"channel_requirements": [
"print"
]
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Create a new category
This endpoint allows you to create a new category. You can specify the category's code, parent category, labels, values, validations, and channel requirements. The request body should be in JSON format and include the necessary fields for the category.
REQUEST
post /api/rest/v1/categories
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
parent
(string,null)
• Category code of the parent's category
updated
(string)
• Date of the last update
position
(integer)
• Position of the category in its level, start from 1 (only available when query parameter with_position is set to true)
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Category label for the specified locale
}
channel_requirements
(array[string],
[] by default)
• List of Channel codes on which the category is required for products completeness.
Only category trees can be required, not child categories.
values
(array[object],
[] by default)
: [
{
locale (string,null) • Locale code of the attribute value
channel (string,null) • Channel code of the attribute value
attribute_code (string) • The attribute code with its uuid (attributeCode|attributeUuid)
data (string) • Attribute value.
It should be a string for Text and Text Area attributes,
a boolean for Yes/No attribute
and for Image attribute use the create category media file endpoint.
It can also be null to remove the value.
}
]
validations
(object,
[] by default)
: {
max_categories_per_product
(integer)
• Set maximum number of categories per product
only_leaves
(boolean)
• Restrict categorization to the lowest level
is_mandatory
(boolean)
• Set category as mandatory for every product
}
}
Example
{
"code": "winter_collection",
"parent": null,
"labels": {
"en_US": "Winter collection",
"fr_FR": "Collection hiver"
},
"values": [
{
"data": "<p>Winter collection description</p>",
"channel": "ecommerce",
"locale": "en_US",
"attribute_code": "a_text_area_attribute"
},
{
"data": true,
"channel": "ecommerce",
"locale": "en_US",
"attribute_code": "a_boolean_attribute"
}
],
"validations": {
"max_categories_per_product": 42,
"only_leaves": false,
"is_mandatory": true
},
"channel_requirements": [
"ecommerce",
"mobile"
]
}RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the data provided does not meet the required format or constraints defined by the API, and includes a link to the documentation for reference.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Property \\\"labels\\\" expects an array as data, \\\"NULL\\\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Create or update several categories
This endpoint allows you to update and/or create several categories at once.
REQUEST
patch /api/rest/v1/categories
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is a category in JSON standard format
{
parent
(string,null)
• Category code of the parent's category
updated
(string)
• Date of the last update
position
(integer)
• Position of the category in its level, start from 1 (only available when query parameter with_position is set to true)
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Category label for the specified locale
}
channel_requirements
(array[string],
[] by default)
• List of Channel codes on which the category is required for products completeness.
Only category trees can be required, not child categories.
values
(array[object],
[] by default)
: [
{
locale (string,null) • Locale code of the attribute value
channel (string,null) • Channel code of the attribute value
attribute_code (string) • The attribute code with its uuid (attributeCode|attributeUuid)
data (string) • Attribute value.
It should be a string for Text and Text Area attributes,
a boolean for Yes/No attribute
and for Image attribute use the create category media file endpoint.
It can also be null to remove the value.
}
]
validations
(object,
[] by default)
: {
max_categories_per_product
(integer)
• Set maximum number of categories per product
only_leaves
(boolean)
• Restrict categorization to the lowest level
is_mandatory
(boolean)
• Set category as mandatory for every product
}
}
Example
{"code":"spring_collection","parent":null}
{"code":"woman","parent":"spring_collectionn"}
{"code":"man","parent":"spring_collection"}
RESPONSES
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
{
line
(integer)
• Line number
code
(string)
• Resource code
status_code
(integer)
• HTTP status code, see Client errors to understand the meaning of each code
message
(string)
• Message explaining the error
}
Example
{"line":1,"code":"spring_collection","status_code":201}
{"line":2,"code":"woman","status_code":422,"message":"Category \"spring_collectionn\" does not exist."}
{"line":3,"code":"man","status_code":204}
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}Get a category
This endpoint allows you to retrieve a category by its code. The response includes the category's details such as its labels, values, and channel requirements.
You can also specify the with_position query parameter to include the position of the category in its level.
The with_enriched_attributes query parameter allows you to include enriched attributes.
REQUEST
get /api/rest/v1/categories/{code}
Path parameters
code
(string)
• 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.
Query parameters
with_position
(boolean)
• Return information about the category's position within its category tree.
When set to true, the response will include the position of the category in its level, which can be useful for understanding the hierarchy and order of categories.
If set to false, the response will not include this information, which can improve performance.
with_enriched_attributes
(boolean)
• Return the attribute values of the category.
When set to true, the response will include the values of all attributes associated with the category.
This is useful for retrieving detailed information about the category's attributes, such as their values and configurations.
If set to false, the response will not include attribute values, which can improve performance
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
This endpoint allows you to retrieve a category by its code.
The response includes the category's details such as its labels, values, and channel requirements.
You can also specify the with_position query parameter to include the position of the category in its level.
Body Format application/json
{
code
(string)
• Category code
parent
(string,null)
• Category code of the parent's category
updated
(string)
• Date of the last update
position
(integer)
• Position of the category in its level, start from 1 (only available when query parameter with_position is set to true)
labels
(object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Category label for the specified locale
}
channel_requirements
(array [string])
• List of Channel codes on which the category is required for products completeness.
Only category trees can be required, not child categories.
values
(object)
: {
{attributeCode|attributeUuid|channel|locale}
(object)
: {
type
(string)
• The attribute type
locale
(string,null)
• Locale code of the attribute value
channel
(string,null)
• Channel code of the attribute value
attribute_code
(string)
• The attribute code with its uuid (attributeCode|attributeUuid)
data
(string)
• Attribute value
}
}
validations
(object)
: {
max_categories_per_product
(integer)
• Set maximum number of categories per product
only_leaves
(boolean)
• Restrict categorization to the lowest level
is_mandatory
(boolean)
• Set category as mandatory for every product
}
}
Example
{
"code": "winter_collection",
"parent": null,
"updated": "2021-05-22T12:48:00+02:00",
"position": 1,
"labels": {
"en_US": "Winter collection",
"fr_FR": "Collection hiver"
},
"values": {
"description|96b88bf4-c2b7-4b64-a1f9-5d4876c02c26|ecommerce|en_US": {
"data": "<p>Winter collection description</p>",
"type": "textarea",
"channel": "ecommerce",
"locale": "en_US",
"attribute_code": "description|96b88bf4-c2b7-4b64-a1f9-5d4876c02c26"
},
"image_1|871b8686-79b5-415c-9c6f-a38f8732dfb7|ecommerce|en_US": {
"data": {
"size": 1401359,
"extension": "jpg",
"file_path": "2/d/c/7/2dc791671d726e7438219d5dc7fd51a53d6bf2bb_IMG_7860.jpg",
"mime_type": "image/jpeg",
"original_filename": "IMG_7860.jpg"
},
"type": "image",
"channel": "ecommerce",
"locale": "en_US",
"attribute_code": "image_1|871b8686-79b5-415c-9c6f-a38f8732dfb7"
}
},
"channel_requirements": [
"ecommerce",
"mobile"
]
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Create or update a category
This endpoint allows you to update a given category. Note that if no category exists for the given code, it creates it. You can specify the category's code, parent category, labels, values, validations, and channel requirements. The request body should be in JSON format and include the necessary fields for the category.
REQUEST
patch /api/rest/v1/categories/{code}
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
parent
(string,null)
• Category code of the parent's category
updated
(string)
• Date of the last update
position
(integer)
• Position of the category in its level, start from 1 (only available when query parameter with_position is set to true)
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Category label for the specified locale
}
channel_requirements
(array[string],
[] by default)
• List of Channel codes on which the category is required for products completeness.
Only category trees can be required, not child categories.
values
(array[object],
[] by default)
: [
{
locale (string,null) • Locale code of the attribute value
channel (string,null) • Channel code of the attribute value
attribute_code (string) • The attribute code with its uuid (attributeCode|attributeUuid)
data (string) • Attribute value.
It should be a string for Text and Text Area attributes,
a boolean for Yes/No attribute
and for Image attribute use the create category media file endpoint.
It can also be null to remove the value.
}
]
validations
(object,
[] by default)
: {
max_categories_per_product
(integer)
• Set maximum number of categories per product
only_leaves
(boolean)
• Restrict categorization to the lowest level
is_mandatory
(boolean)
• Set category as mandatory for every product
}
}
Example
{
"code": "winter_collection",
"parent": null,
"labels": {
"en_US": "Winter collection",
"fr_FR": "Collection hiver"
},
"values": [
{
"data": "<p>Winter collection description</p>",
"channel": "ecommerce",
"locale": "en_US",
"attribute_code": "a_text_area_attribute"
},
{
"data": true,
"channel": "ecommerce",
"locale": "en_US",
"attribute_code": "a_boolean_attribute"
}
],
"validations": {
"max_categories_per_product": 42,
"only_leaves": false,
"is_mandatory": true
},
"channel_requirements": [
"ecommerce",
"mobile"
]
}RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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 • URI of the updated resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the data provided does not meet the required format or constraints defined by the API, and includes a link to the documentation for reference.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Property \\\"labels\\\" expects an array as data, \\\"NULL\\\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Create a category media file
This endpoint allows you to create a new media file and associate it to anattribute value of a given enriched category. It is used to upload media files that are linked to categories, such as images or documents. The request body should include the category information and the binary file data.
REQUEST
post /api/rest/v1/category-media-files
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Given as form-data
category
(string)
• The category to which the media file will be associated.
It is a JSON string that follows this format:
'{"code":"category code", "attribute_code":"attribute code", "channel":"channel code or null", "locale":"locale code or null"}'.
file
(string / binary)
• The media file to be uploaded.
It should be provided as a binary file.
Ensure that the file format is supported by the system.
RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the data provided does not meet the required format or constraints defined by the API, and includes a link to the documentation for reference.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Property \\\"labels\\\" expects an array as data, \\\"NULL\\\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Download a category media file
This endpoint allows you to download a given media file that is used as an attribute value of a enriched category. The media file is identified by its path, which is provided in the request.
REQUEST
get /api/rest/v1/category-media-files/{file_path}/download
Path parameters
file_path
(string)
• This path parameter is used to specify the unique identifier of the media file you want to download.
It is essential for identifying the specific media file in the API requests.
Ensure that the file path is correctly formatted and corresponds to an existing media file in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Body
Ø
RESPONSES
Returns the binary of the media file
Body Format Mime-type of the media file
Ø
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.
Body Format Mime-type of the media file
This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format Mime-type of the media file
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.
Body Format Mime-type of the media file
Target market settings
Channel
Get a list of channels
This endpoint allows you to get a list of channels. Channels are paginated and sorted by code.
REQUEST
get /api/rest/v1/channels
Path parameters
Ø
Query parameters
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
with_count
(boolean)
• Return the count of items in the response.
Be careful with that, on a big catalog, it can decrease performance in a significant way.
It is useful for understanding the size of the dataset being returned, especially when dealing with large collections.
Use it judiciously to avoid performance issues.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return channels paginated. The response is paginated and includes links to navigate through the pages.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
items_count
(integer)
• Total number of items (only if with_count parameter is set to true)
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
code (string)
• Channel code
locales (array [string])
• Codes of activated locales for the channel
• Codes of activated locales for the channel
currencies (array [string])
• Codes of activated currencies for the channel
• Codes of activated currencies for the channel
category_tree (string)
• Code of the category tree linked to the channel
conversion_units (object)
: {
attributeCode (string)
• Conversion unit code used to convert the values of the attribute attributeCode when exporting via the channel
}
labels (object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$} (string,null)
• Channel label for the specified locale
}
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/channels?page=2&limit=3&with_count=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/channels?page=1&limit=3&with_count=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/channels?page=1&limit=3&with_count=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/channels?page=3&limit=3&with_count=true"
}
},
"current_page": 1,
"items_count": 10,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/channels/ecommerce"
}
},
"code": "ecommerce",
"currencies": [
"USD",
"EUR"
],
"locales": [
"en_US",
"fr_FR",
"de_DE"
],
"category_tree": "master",
"conversion_units": {
"a_metric": "KILOWATT",
"a_metric_negative": "CELSIUS",
"a_metric_to_not_convert": null
},
"labels": {
"en_US": "Ecommerce",
"fr_FR": "E-commerce",
"de_DE": "E-commerce"
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/channels/mobile"
}
},
"code": "mobile",
"currencies": [
"USD",
"EUR"
],
"locales": [
"en_US",
"fr_FR",
"de_DE"
],
"category_tree": "master",
"conversion_units": {
"a_metric": "KILOWATT",
"a_metric_negative": "CELSIUS",
"a_metric_to_not_convert": null
},
"labels": {
"en_US": "Mobile",
"fr_FR": "Mobile",
"de_DE": "Mobile"
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/channels/print"
}
},
"code": "print",
"currencies": [
"USD",
"EUR"
],
"locales": [
"en_US",
"fr_FR",
"de_DE"
],
"category_tree": "master",
"conversion_units": {},
"labels": {
"en_US": "Print",
"fr_FR": "Print",
"de_DE": "Print"
}
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Create a new channel
This endpoint allows you to create a new channel.
REQUEST
post /api/rest/v1/channels
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
locales
(array[string])
• Codes of activated locales for the channel
currencies
(array[string])
• Codes of activated currencies for the channel
category_tree
(string)
• Code of the category tree linked to the channel
conversion_units
(object)
: {
attributeCode
(string)
• Conversion unit code used to convert the values of the attribute attributeCode when exporting via the channel
}
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Channel label for the specified locale
}
}
Example
{
"code": "ecommerce",
"currencies": [
"USD",
"EUR"
],
"locales": [
"de_DE",
"en_US",
"fr_FR"
],
"category_tree": "master",
"conversion_units": {
"weight": "KILOGRAM"
},
"labels": {
"en_US": "Ecommerce",
"de_DE": "Ecommerce",
"fr_FR": "Ecommerce"
}
}RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the data provided does not meet the required format or constraints defined by the API, and includes a link to the documentation for reference.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Property \\\"labels\\\" expects an array as data, \\\"NULL\\\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Update/create several channels
This endpoint allows you to update and/or create several channels at once.
REQUEST
patch /api/rest/v1/channels
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/vnd.akeneo.collection+json', no other value allowed
Body
Contains several lines, each line is a channel in JSON standard format
{
locales
(array[string])
• Codes of activated locales for the channel
currencies
(array[string])
• Codes of activated currencies for the channel
category_tree
(string)
• Code of the category tree linked to the channel
conversion_units
(object)
: {
attributeCode
(string)
• Conversion unit code used to convert the values of the attribute attributeCode when exporting via the channel
}
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Channel label for the specified locale
}
}
Example
{"code":"ecommerce_fr", "category_tree": "master", "currencies":["EUR"], "locales": ["fr_FR"], "labels":{"fr_FR": "Ecommerce Fr"}}
{"code":"ecommerce_ch", "type":"bar"}
{"code":"tablet", "labels":{"en_US": "Tablet", "fr_FR": "Tablette"}}
RESPONSES
Returns a plain text response whose lines are JSON containing the status of each update or creation
Body Format application/json
{
line
(integer)
• Line number
code
(string)
• Resource code
status_code
(integer)
• HTTP status code, see Client errors to understand the meaning of each code
message
(string)
• Message explaining the error
}
Example
{"line":1,"code":"ecommerce_fr","status_code":201}
{"line":2,"code":"ecommerce_ch","status_code":422,"message":"Property \"type\" does not exist. Check the standard format documentation.","_links":{"documentation":{"href":"https:\/\/api.akeneo.com\/api-reference.html#patch_channels__code_"}}}
{"line":3,"code":"tablet","status_code":204}
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}Get a channel
This endpoint allows you to get the information about a given channel
REQUEST
get /api/rest/v1/channels/{code}
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the channel in JSON standard format
Body Format application/json
{
code
(string)
• Channel code
locales
(array [string])
• Codes of activated locales for the channel
currencies
(array [string])
• Codes of activated currencies for the channel
category_tree
(string)
• Code of the category tree linked to the channel
conversion_units
(object)
: {
attributeCode
(string)
• Conversion unit code used to convert the values of the attribute attributeCode when exporting via the channel
}
labels
(object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Channel label for the specified locale
}
}
Example
{
"code": "ecommerce",
"currencies": [
"USD",
"EUR"
],
"locales": [
"de_DE",
"en_US",
"fr_FR"
],
"category_tree": "master",
"conversion_units": {
"weight": "KILOGRAM"
},
"labels": {
"en_US": "Ecommerce",
"de_DE": "Ecommerce",
"fr_FR": "Ecommerce"
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Update/create a channel
This endpoint allows you to update a given channel. Know more about Update behavior. Note that if no channel exists for the given code, it creates it.
REQUEST
patch /api/rest/v1/channels/{code}
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
locales
(array[string])
• Codes of activated locales for the channel
currencies
(array[string])
• Codes of activated currencies for the channel
category_tree
(string)
• Code of the category tree linked to the channel
conversion_units
(object)
: {
attributeCode
(string)
• Conversion unit code used to convert the values of the attribute attributeCode when exporting via the channel
}
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Channel label for the specified locale
}
}
Example
{
"code": "ecommerce",
"currencies": [
"USD",
"EUR"
],
"locales": [
"de_DE",
"en_US",
"fr_FR"
],
"category_tree": "master",
"conversion_units": {
"weight": "KILOGRAM"
},
"labels": {
"en_US": "Ecommerce",
"de_DE": "Ecommerce",
"fr_FR": "Ecommerce"
}
}RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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 • URI of the updated resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Locale
Get a list of locales
This endpoint allows you to retrieve a list of locales available in the
system. Locales are paginated and can be filtered using the search query
parameter. The response includes the locale code and whether it is enabled.
You can also specify pagination parameters such as page, limit, and with_count.
REQUEST
get /api/rest/v1/locales
Path parameters
Ø
Query parameters
search
(string)
• The search query parameter allows you to filter locales based on specific criteria.
For more details see the Filters section.
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
with_count
(boolean)
• Return the count of items in the response.
Be careful with that, on a big catalog, it can decrease performance in a significant way.
It is useful for understanding the size of the dataset being returned, especially when dealing with large collections.
Use it judiciously to avoid performance issues.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return locales paginated. The response is paginated and includes links to navigate through the pages.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
items_count
(integer)
• Total number of items (only if with_count parameter is set to true)
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
code (string)
• Locale code
enabled (boolean)
• Whether the locale is enabled
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/locales?page=2&limit=5&with_count=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/locales?page=1&limit=5&with_count=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/locales?page=1&limit=5&with_count=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/locales?page=3&limit=5&with_count=true"
}
},
"current_page": 2,
"items_count": 10,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/locales/en_US"
}
},
"code": "en_US",
"enabled": true
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/locales/fr_FR"
}
},
"code": "fr_FR",
"enabled": true
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/locales/de_DE"
}
},
"code": "de_DE",
"enabled": true
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/locales/af_ZA"
}
},
"code": "af_ZA",
"enabled": false
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Get a locale
This endpoint allows you to get the information about a given locale. You can retrieve details such as the locale code and whether it is enabled. The response will be in JSON format.
REQUEST
get /api/rest/v1/locales/{code}
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Get the details of a specific locale by its code. The response will include whether the locale is enabled or not. The response will be in JSON format
Body Format application/json
{
code
(string)
• Locale code
enabled
(boolean)
• Whether the locale is enabled
}
Example
{
"code": "en_US",
"enabled": true
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Currency
Get a list of currencies
This endpoint allows you to retrieve a list of currencies available in the system. Currencies are paginated and can be filtered using the search query parameter. The response includes the currency code, whether it is enabled, and its label. You can also specify pagination parameters such as page, limit, and with_count.
REQUEST
get /api/rest/v1/currencies
Path parameters
Ø
Query parameters
search
(string)
• The search query parameter allows you to filter currencies based on specific criteria.
For more details see the Filters section.
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
with_count
(boolean)
• Return the count of items in the response.
Be careful with that, on a big catalog, it can decrease performance in a significant way.
It is useful for understanding the size of the dataset being returned, especially when dealing with large collections.
Use it judiciously to avoid performance issues.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return currencies paginated. The response is paginated and includes links to navigate through the pages.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
items_count
(integer)
• Total number of items (only if with_count parameter is set to true)
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
code (string)
• Currency code
enabled (boolean)
• Whether the currency is enabled
label (string)
• Currency label
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/currencies?page=1&limit=3&with_count=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/currencies?page=2&limit=3&with_count=true"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/currencies?page=1&limit=3&with_count=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/currencies?page=3&limit=3&with_count=true"
}
},
"current_page": 1,
"items_count": 10,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/currencies/ADP"
}
},
"code": "ADP",
"enabled": true,
"label": "ADP (Andorran Peseta)"
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/currencies/AED"
}
},
"code": "AED",
"enabled": true,
"label": "AED (United Arab Emirates Dirham)"
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/currencies/AFA"
}
},
"code": "AFA",
"enabled": false,
"label": "AFA (Afghan Afghani (1927–2002))"
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Get a currency
This endpoint allows you to get the information about a given currency. You can retrieve details such as the currency code, whether it is enabled, and its label. The response will be in JSON format.
REQUEST
get /api/rest/v1/currencies/{code}
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the currency in JSON standard format
Body Format application/json
{
code
(string)
• Currency code
enabled
(boolean)
• Whether the currency is enabled
label
(string)
• Currency label
}
Example
{
"code": "EUR",
"enabled": true,
"label": "EUR (Euro)"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Measurement family
Get list of measurement families
This endpoint allows you to get a list of measurement families
REQUEST
get /api/rest/v1/measurement-families
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
A list of measurement families
Body Format application/json
[
{
code
(string)
• Measurement family code
labels
(object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$} (string,null)
• Measurement family label for the specified locale
}
standard_unit_code
(string)
• Unit code used as the standard unit for this measurement family
units
(object)
• Measurement units for this family with their conversion operations.
More details here
}
]
Example
[
{
"code": "AREA",
"labels": {
"en_US": "Area",
"fr_FR": "Surface"
},
"standard_unit_code": "SQUARE_METER",
"units": {
"SQUARE_MILLIMETER": {
"code": "SQUARE_MILLIMETER",
"labels": {
"en_US": "Square millimeter",
"fr_FR": "Millimètre carré"
},
"convert_from_standard": [
{
"operator": "mul",
"value": "0.000001"
}
],
"symbol": "mm²"
},
"SQUARE_CENTIMETER": {
"code": "SQUARE_CENTIMETER",
"labels": {
"en_US": "Square centimeter",
"fr_FR": "Centimètre carré"
},
"convert_from_standard": [
{
"operator": "mul",
"value": "0.0001"
}
],
"symbol": "cm²"
},
"SQUARE_METER": {
"code": "SQUARE_METER",
"labels": {
"en_US": "Square meter",
"fr_FR": "Mètre carré"
},
"convert_from_standard": [
{
"operator": "mul",
"value": "1"
}
],
"symbol": "m²"
}
}
}
]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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Update/create several measurement families
This endpoint allows you to update and/or create several measurement families at once
REQUEST
patch /api/rest/v1/measurement-families
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
[
code (string)
• Measurement family code
labels (object{{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$} : string,null},
[]
by default)
• Measurement family labels for each locale
standard_unit_code (string)
• Unit code used as the standard unit for this measurement family
units (object)
• Measurement units for this family with their conversion operations.
More details here
]
}
Example
[
{
"code": "AREA",
"labels": {
"en_US": "Area",
"fr_FR": "Surface"
},
"standard_unit_code": "SQUARE_METER",
"units": {
"SQUARE_MILLIMETER": {
"code": "SQUARE_MILLIMETER",
"labels": {
"en_US": "Square millimeter",
"fr_FR": "Millimètre carré"
},
"convert_from_standard": [
{
"operator": "mul",
"value": "0.000001"
}
],
"symbol": "mm²"
},
"SQUARE_CENTIMETER": {
"code": "SQUARE_CENTIMETER",
"labels": {
"en_US": "Square centimeter",
"fr_FR": "Centimètre carré"
},
"convert_from_standard": [
{
"operator": "mul",
"value": "0.0001"
}
],
"symbol": "cm²"
},
"SQUARE_METER": {
"code": "SQUARE_METER",
"labels": {
"en_US": "Square meter",
"fr_FR": "Mètre carré"
},
"convert_from_standard": [
{
"operator": "mul",
"value": "1"
}
],
"symbol": "m²"
}
}
}
]RESPONSES
OK. Returns a JSON array containing the status of each update or creation
Body Format application/json
[
{
code
(string)
• Resource code
status_code
(integer)
• HTTP status code. See the documentation for client errors to understand the meaning of each code
message
(string)
• Message explaining the error, if any
errors
(array [object])
: [
{
property (string) •
message (string) •
}
]
}
]
Example
[
{
"code": "Angle",
"status_code": 201
},
{
"code": "Force",
"status_code": 204
},
{
"code": "Area",
"status_code": 422,
"message": "The measurement family has data that does not comply with the business rules.",
"errors": [
{
"property": "standard_unit_code",
"message": "The standard unit code of the \"Angle\" measurement family cannot be changed"
}
]
}
]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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}Reference entities
Reference entity
Get list of reference entities
This endpoint allows you to get a list of reference entities. Reference entities are paginated.
REQUEST
get /api/rest/v1/reference-entities
Path parameters
Ø
Query parameters
search_after
(string,
cursor to the first page
by default)
• 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 section for more details.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return reference entities paginated.
The response is paginated and includes links to navigate through the pages.
Only search_after pagination is used.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
image_download (object)
: {
href
(string) • URI to download the binaries of the reference entity image file
}
}
code (string)
• Reference entity code
labels (object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$} (string,null)
• Reference entity label for the locale
}
image (string,null)
• Code of the reference entity image
}
]
}
}
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
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Get a reference entity
This endpoint allows you to get the information about a given reference entity
REQUEST
get /api/rest/v1/reference-entities/{code}
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the reference entity in JSON format
Body Format application/json
{
_links
(object)
: {
image_download (object)
: {
href (string) • URI to download the binaries of the reference entity image file
}
}
code
(string)
• Reference entity code
labels
(object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$} (string,null)
• Reference entity label for the locale
}
image
(string,null)
• Code of the reference entity image
}
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"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Update/create a reference entity
This endpoint allows you to update a given reference entity. Note that if the reference entity does not already exist, it creates it.
REQUEST
patch /api/rest/v1/reference-entities/{code}
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
Example
{
"code": "brands",
"labels": {
"en_US": "Brands",
"fr_FR": "Marques"
},
"image": "0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png"
}RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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 • URI of the updated resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Description of the validation error
}
Example
{
"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."
}Reference entity attribute
Get the list of attributes of a given reference entity
This endpoint allows you to get the list of attributes of a given reference entity
REQUEST
get /api/rest/v1/reference-entities/{reference_entity_code}/attributes
Path parameters
reference_entity_code
(string)
• This path parameter is used to specify the unique identifier of the reference entity you want to retrieve or manipulate.
It is essential for identifying the specific reference entity in the API requests.
Ensure that the reference entity code is correctly formatted and corresponds to an existing reference entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return the attributes of the given reference entity
Body Format application/json
[
{
code
(string)
• Attribute code
labels
(object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$} (string,null)
• Attribute label for the specified locale
}
type
(string)
• Attribute type.
See type section for more details.
value_per_locale
(boolean)
• Whether the attribute is localizable, i.e. can have one value by locale
value_per_channel
(boolean)
• Whether the attribute is scopable, i.e. can have one value by channel
is_required_for_completeness
(boolean)
• Whether the attribute should be part of the record's completeness calculation
max_characters
(integer,null)
• Maximum number of characters allowed for the value of the attribute when the attribute type is text
is_textarea
(boolean)
• Whether the UI should display a text area instead of a simple field when the attribute type is text
is_rich_text_editor
(boolean)
• Whether the UI should display a rich text editor instead of a simple text area when the attribute type is text
validation_rule
(string,null)
• Validation rule type used to validate the attribute value when the attribute type is text
validation_regexp
(string,null)
• Regexp expression used to validate the attribute value when the attribute type is text
allowed_extensions
(array [string])
• Extensions allowed when the attribute type is image
max_file_size
(string,null)
• Max file size in MB when the attribute type is image
reference_entity_code
(string,null)
• Code of the linked reference entity when the attribute type is reference_entity_single_link or reference_entity_multiple_links
asset_family_identifier
(string,null)
• Code of the linked asset family when the attribute type is asset_collection
decimals_allowed
(boolean)
• Whether decimals are allowed when the attribute type is number
min_value
(string,null)
• Minimum value allowed when the attribute type is number
max_value
(string,null)
• Maximum value allowed when the attribute type is number
}
]
Example
[
{
"code": "description",
"labels": {
"en_US": "Description",
"fr_FR": "Description"
},
"type": "text",
"value_per_locale": true,
"value_per_channel": false,
"is_required_for_completeness": true,
"max_characters": null,
"is_textarea": true,
"is_rich_text_editor": true,
"validation_rule": "none",
"validation_regexp": null
},
{
"code": "country",
"labels": {
"en_US": "Country",
"fr_FR": "Pays"
},
"type": "text",
"value_per_locale": false,
"value_per_channel": false,
"is_required_for_completeness": false
},
{
"code": "creation_year",
"labels": {
"en_US": "Creation year",
"fr_FR": "Année de création"
},
"type": "number",
"value_per_locale": false,
"value_per_channel": false,
"is_required_for_completeness": false,
"decimals_allowed": false,
"min_value": "1800",
"max_value": "2100"
},
{
"code": "collection_overview",
"labels": {
"en_US": "Collection overview",
"fr_FR": "Aperçu de la collection"
},
"type": "image",
"value_per_locale": true,
"value_per_channel": false,
"is_required_for_completeness": true,
"allowed_extensions": [
"png"
],
"max_file_size": "1000"
}
]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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Get an attribute of a given reference entity
This endpoint allows you to get the information about a given attribute for a given reference entity
REQUEST
get /api/rest/v1/reference-entities/{reference_entity_code}/attributes/{code}
Path parameters
reference_entity_code
(string)
• This path parameter is used to specify the unique identifier of the reference entity you want to retrieve or manipulate.
It is essential for identifying the specific reference entity in the API requests.
Ensure that the reference entity code is correctly formatted and corresponds to an existing reference entity in the system.
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the reference entity attribute in JSON format
Body Format application/json
{
code
(string)
• Attribute code
labels
(object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Attribute label for the specified locale
}
type
(string)
• Attribute type.
See type section for more details.
value_per_locale
(boolean)
• Whether the attribute is localizable, i.e. can have one value by locale
value_per_channel
(boolean)
• Whether the attribute is scopable, i.e. can have one value by channel
is_required_for_completeness
(boolean)
• Whether the attribute should be part of the record's completeness calculation
max_characters
(integer,null)
• Maximum number of characters allowed for the value of the attribute when the attribute type is text
is_textarea
(boolean)
• Whether the UI should display a text area instead of a simple field when the attribute type is text
is_rich_text_editor
(boolean)
• Whether the UI should display a rich text editor instead of a simple text area when the attribute type is text
validation_rule
(string,null)
• Validation rule type used to validate the attribute value when the attribute type is text
validation_regexp
(string,null)
• Regexp expression used to validate the attribute value when the attribute type is text
allowed_extensions
(array [string])
• Extensions allowed when the attribute type is image
max_file_size
(string,null)
• Max file size in MB when the attribute type is image
reference_entity_code
(string,null)
• Code of the linked reference entity when the attribute type is reference_entity_single_link or reference_entity_multiple_links
asset_family_identifier
(string,null)
• Code of the linked asset family when the attribute type is asset_collection
decimals_allowed
(boolean)
• Whether decimals are allowed when the attribute type is number
min_value
(string,null)
• Minimum value allowed when the attribute type is number
max_value
(string,null)
• Maximum value allowed when the attribute type is number
}
Example
{
"code": "description",
"labels": {
"en_US": "Description",
"fr_FR": "Description"
},
"type": "text",
"value_per_locale": true,
"value_per_channel": false,
"is_required_for_completeness": true,
"is_textarea": true,
"is_rich_text_editor": true,
"validation_rule": "none"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Update/create an attribute of a given reference entity
This endpoint allows you to update a given attribute for a given reference entity. Note that if the attribute does not already exist for the given reference entity, it creates it.
REQUEST
patch /api/rest/v1/reference-entities/{reference_entity_code}/attributes/{code}
Path parameters
reference_entity_code
(string)
• This path parameter is used to specify the unique identifier of the reference entity you want to retrieve or manipulate.
It is essential for identifying the specific reference entity in the API requests.
Ensure that the reference entity code is correctly formatted and corresponds to an existing reference entity in the system.
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string)
• Attribute code
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Attribute label for the specified locale
}
type
(string)
• Attribute type.
See type section for more details.
value_per_locale
(boolean,
false by default)
• Whether the attribute is localizable, i.e. can have one value by locale
value_per_channel
(boolean,
false by default)
• Whether the attribute is scopable, i.e. can have one value by channel
is_required_for_completeness
(boolean,
false by default)
• Whether the attribute should be part of the record's completeness calculation
max_characters
(integer,null)
• Maximum number of characters allowed for the value of the attribute when the attribute type is text
is_textarea
(boolean,
false by default)
• Whether the UI should display a text area instead of a simple field when the attribute type is text
is_rich_text_editor
(boolean,
false by default)
• Whether the UI should display a rich text editor instead of a simple text area when the attribute type is text
validation_rule
(string,
none by default)
• Validation rule type used to validate the attribute value when the attribute type is text
validation_regexp
(string,null)
• Regexp expression used to validate the attribute value when the attribute type is text
allowed_extensions
(array[string],
[] by default)
• Extensions allowed when the attribute type is image
max_file_size
(string,null)
• Max file size in MB when the attribute type is image
decimals_allowed
(boolean,
false by default)
• Whether decimals are allowed when the attribute type is number
min_value
(string,null)
• Minimum value allowed when the attribute type is number
max_value
(string,null)
• Maximum value allowed when the attribute type is number
}
Example
{
"code": "description",
"labels": {
"en_US": "Description",
"fr_FR": "Description"
},
"type": "text",
"value_per_locale": true,
"value_per_channel": false,
"is_required_for_completeness": true,
"is_textarea": true,
"is_rich_text_editor": true,
"validation_rule": "none"
}RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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 • URI of the updated resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Reference entity attribute option
Get a list of attribute options of a given attribute for a given reference entity
This endpoint allows you to get a list of attribute options for a given reference entity
REQUEST
get /api/rest/v1/reference-entities/{reference_entity_code}/attributes/{attribute_code}/options
Path parameters
reference_entity_code
(string)
• This path parameter is used to specify the unique identifier of the reference entity you want to retrieve or manipulate.
It is essential for identifying the specific reference entity in the API requests.
Ensure that the reference entity code is correctly formatted and corresponds to an existing reference entity in the system.
attribute_code
(string)
• This path parameter is used to specify the unique identifier of the attribute you want to retrieve or manipulate.
It is essential for identifying the specific attribute in the API requests.
Ensure that the attribute code is correctly formatted and corresponds to an existing attribute in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return the options of the given attributes of the given reference entity
Body Format application/json
[
{
code
(string)
• Attribute's option code
labels
(object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$} (string,null)
• Attribute label for the specified locale
}
}
]
Example
[
{
"code": "woodland_retreat",
"labels": {
"en_US": "Woodland Retreat",
"fr_FR": "Retraite dans les Bois"
}
},
{
"code": "new_nordic",
"labels": {
"en_US": "New Nordic",
"fr_FR": "Renouveau Scandinave"
}
},
{
"code": "global_nomad",
"labels": {
"en_US": "Global Nomad",
"fr_FR": "Nomade du Monde"
}
}
]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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}The attribute does not support options
Body Format application/json
{
code
(integer)
•
message
(string)
•
}
Example
{
"code": 404,
"message": "Attribute \"description\" does not support options."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Get an attribute option for a given attribute of a given reference entity
This endpoint allows you to get the information about a given attribute option
REQUEST
get /api/rest/v1/reference-entities/{reference_entity_code}/attributes/{attribute_code}/options/{code}
Path parameters
reference_entity_code
(string)
• This path parameter is used to specify the unique identifier of the reference entity you want to retrieve or manipulate.
It is essential for identifying the specific reference entity in the API requests.
Ensure that the reference entity code is correctly formatted and corresponds to an existing reference entity in the system.
attribute_code
(string)
• This path parameter is used to specify the unique identifier of the attribute you want to retrieve or manipulate.
It is essential for identifying the specific attribute in the API requests.
Ensure that the attribute code is correctly formatted and corresponds to an existing attribute in the system.
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the reference entity attribute option in JSON format
Body Format application/json
{
code
(string)
• Attribute's option code
labels
(object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Attribute label for the specified locale
}
}
Example
{
"code": "global_nomad",
"labels": {
"en_US": "Global Nomad",
"fr_FR": "Nomade du Monde"
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Update/create a reference entity attribute option
This endpoint allows you to update a given option for a given attribute and a given reference entity. Learn more about Update behavior. Note that if the option does not already exist for the given attribute of the given reference entity, it creates it.
REQUEST
patch /api/rest/v1/reference-entities/{reference_entity_code}/attributes/{attribute_code}/options/{code}
Path parameters
reference_entity_code
(string)
• This path parameter is used to specify the unique identifier of the reference entity you want to retrieve or manipulate.
It is essential for identifying the specific reference entity in the API requests.
Ensure that the reference entity code is correctly formatted and corresponds to an existing reference entity in the system.
attribute_code
(string)
• This path parameter is used to specify the unique identifier of the attribute you want to retrieve or manipulate.
It is essential for identifying the specific attribute in the API requests.
Ensure that the attribute code is correctly formatted and corresponds to an existing attribute in the system.
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
Example
{
"code": "global_nomad",
"labels": {
"en_US": "Global Nomad",
"fr_FR": "Nomade du Monde"
}
}RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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 • URI of the updated resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the data provided does not meet the required format or constraints defined by the API, and includes a link to the documentation for reference.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Property \\\"labels\\\" expects an array as data, \\\"NULL\\\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}Reference entity record
Get the list of the records of a reference entity
This endpoint allows you to get a list of records of a given reference entity. Records are paginated and can be filtered.
REQUEST
get /api/rest/v1/reference-entities/{reference_entity_code}/records
Path parameters
reference_entity_code
(string)
• This path parameter is used to specify the unique identifier of the reference entity you want to retrieve or manipulate.
It is essential for identifying the specific reference entity in the API requests.
Ensure that the reference entity code is correctly formatted and corresponds to an existing reference entity in the system.
Query parameters
search
(string)
• Filter records of the reference entity,
for more details see the Filters
channel
(string)
• Filter record values to return scopable record attributes for the given channel as well as the non localizable/non scopable record attributes,
for more details see the Filter record values by channel section.
locales
(string)
• Filter record values to return localizable record attributes for the given locales as well as the non localizable/non scopable record attributes,
for more details see the Filter record values by locale section.
search_after
(string,
cursor to the first page
by default)
• 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 section for more details.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return the records of the given reference entity paginated.
The response is paginated and includes links to navigate through the pages.
Only search_after pagination is use.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
_embedded
(object)
: {
items (array)
: [
{
code (string)
• Code of the record
values (object)
• Record attribute values
created (string,null)
•
updated (string,null)
•
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/reference-entities/brands/records"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/reference-entities/brands/records"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/reference-entities/brands/records?search_after=ligneroset"
}
},
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/reference-entities/brands/records/kartell"
}
},
"code": "kartell",
"values": {
"label": [
{
"locale": "en_US",
"channel": null,
"data": "Kartell"
}
],
"image": [
{
"locale": null,
"channel": null,
"data": "0/c/b/0/0cb0c0e115dedba676f8d1ad8343ec207ab54c7b_image.jpg"
}
],
"description": [
{
"locale": "en_US",
"channel": null,
"data": "The contemporary Italian furniture brand"
},
{
"locale": "fr_FR",
"channel": null,
"data": "L'éditeur de meubles comtemporain italien"
}
],
"country": [
{
"locale": null,
"channel": null,
"data": "italy"
}
]
},
"created": "2021-01-01T01:23:34+00:00",
"updated": "2021-02-03T23:45:59+00:00"
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/reference-entities/brands/records/usm"
}
},
"code": "usm",
"values": {
"label": [
{
"locale": "en_US",
"channel": null,
"data": "USM"
}
],
"image": [
{
"locale": null,
"channel": null,
"data": "9/c/g/1/0cb0c0e115dedba76f8d1ad8343ec897abc43bv4_image.jpg"
}
],
"description": [
{
"locale": "en_US",
"channel": null,
"data": "Modular furniture from Switzerland for your home and office"
},
{
"locale": "fr_FR",
"channel": null,
"data": "L'éditeur de meubles modulaires suisse pour votre intérieur et pour les entreprises"
}
],
"country": [
{
"locale": null,
"channel": null,
"data": "switzerland"
}
]
},
"created": "2021-01-01T01:23:34+00:00",
"updated": "2021-02-03T23:45:59+00:00"
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/reference-entities/brands/records/ligneroset"
}
},
"code": "ligneroset",
"values": {
"label": [
{
"locale": "en_US",
"channel": null,
"data": "Ligne Roset"
}
],
"image": [
{
"locale": null,
"channel": null,
"data": "4/b/0/1/0cb0c0e115dedde78b8d1ad8343ec980cd5daa54_image.jpg"
}
],
"description": [
{
"locale": "en_US",
"channel": null,
"data": "Very well known French brand of modern and luxury furniture"
},
{
"locale": "fr_FR",
"channel": null,
"data": "La marque renommée des meubles de luxe à la française"
}
],
"country": [
{
"locale": null,
"channel": null,
"data": "france"
}
]
},
"created": "2021-01-01T01:23:34+00:00",
"updated": "2021-02-03T23:45:59+00:00"
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Update/create several reference entity records
This endpoint allows you to update and/or create several records of a reference entity. Learn more about Update behavior. If a record with the specified code does not already exist, it will be created.
REQUEST
patch /api/rest/v1/reference-entities/{reference_entity_code}/records
Path parameters
reference_entity_code
(string)
• This path parameter is used to specify the unique identifier of the reference entity you want to retrieve or manipulate.
It is essential for identifying the specific reference entity in the API requests.
Ensure that the reference entity code is correctly formatted and corresponds to an existing reference entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
Example
[
{
"code": "kartell",
"values": {
"label": [
{
"locale": "en_US",
"channel": null,
"data": "Kartell"
}
],
"image": [
{
"locale": null,
"channel": null,
"data": "0/c/b/0/0cb0c0e115dedba676f8d1ad8343ec207ab54c7b_image.jpg"
}
],
"description": [
{
"locale": "en_US",
"channel": null,
"data": "Kartell, the Italian furniture company that sells modern and remarkable pieces of furnitures."
},
{
"locale": "fr_FR",
"channel": null,
"data": "Kartell, l'éditeur de meuble italien spécialisé dans la signature de belle pièces au design contemporain."
}
],
"country": [
{
"locale": null,
"channel": null,
"data": "italy"
}
],
"collection_overview": [
{
"locale": null,
"channel": null,
"data": "5/1/d/8/51d81dc778ba1501a8f998f3ab5797569f3b9e25_img.png"
}
],
"creation_year": [
{
"locale": null,
"channel": null,
"data": "1949"
}
]
}
},
{
"code": "ligneroset",
"values": {
"label": [
{
"locale": "en_US",
"channel": null,
"data": "Ligne Roset"
}
],
"description": [
{
"locale": "en_US",
"channel": null,
"data": "Very well known French brand of modern and luxury furniture"
},
{
"locale": "fr_FR",
"channel": null,
"data": "La marque renommée des meubles de luxe à la française"
}
],
"country": [
{
"locale": null,
"channel": null,
"data": "france"
}
],
"creation_year": [
{
"locale": null,
"channel": null,
"data": "1860"
}
]
}
},
{
"code": "usm",
"values": {
"label": [
{
"locale": "en_US",
"channel": null,
"data": "USM"
}
],
"description": [
{
"locale": "en_US",
"channel": null,
"data": "Modular furniture from Switzerland for your home and office"
},
{
"locale": "fr_FR",
"channel": null,
"data": "L'éditeur de meubles modulaires suisse pour votre intérieur et pour les entreprises"
}
],
"country": [
{
"locale": null,
"channel": null,
"data": "switzerland"
}
],
"creation_year": [
{
"locale": null,
"channel": null,
"data": "1885"
}
]
}
}
]RESPONSES
Returns an JSON array in which each object gives you the status of each record creation or update
Body Format application/json
[
{
code
(string)
•
status_code
(integer)
•
message
(string)
•
errors
(array [object])
: [
{
property (string) •
message (string) •
}
]
}
]
Example
[
{
"code": "a_new_brand",
"status_code": 201
},
{
"code": "existing_brand_successfully_updated",
"status_code": 204
},
{
"code": "brand_with_a_wrong_payload_resulting_in_an_error",
"status_code": 422,
"message": "The record has an invalid format.",
"errors": [
{
"property": "values.label[0]",
"message": "Additional object properties are not allowed: typo"
}
]
}
]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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}Get a record of a given reference entity
Retrieve a specific record of a reference entity
REQUEST
get /api/rest/v1/reference-entities/{reference_entity_code}/records/{code}
Path parameters
reference_entity_code
(string)
• This path parameter is used to specify the unique identifier of the reference entity you want to retrieve or manipulate.
It is essential for identifying the specific reference entity in the API requests.
Ensure that the reference entity code is correctly formatted and corresponds to an existing reference entity in the system.
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Record retrieved successfully
Body Format application/json
{
code
(string)
• Code of the record
values
(object)
• Record attribute values
created
(string,null)
•
updated
(string,null)
•
}
Example
{
"code": "kartell",
"values": {
"label": [
{
"locale": "en_US",
"channel": null,
"data": "Kartell"
}
],
"image": [
{
"locale": null,
"channel": null,
"data": "0/c/b/0/0cb0c0e115dedba676f8d1ad8343ec207ab54c7b_image.jpg"
}
],
"description": [
{
"locale": "en_US",
"channel": null,
"data": "Kartell, the Italian furniture company that sells modern and remarkable pieces of furniture."
},
{
"locale": "fr_FR",
"channel": null,
"data": "Kartell, l'éditeur de meuble italien spécialisé dans la signature de belles pièces au design contemporain."
}
],
"country": [
{
"locale": null,
"channel": null,
"data": "italy"
}
],
"collection_overview": [
{
"locale": null,
"channel": null,
"data": "5/1/d/8/51d81dc778ba1501a8f998f3ab5797569f3b9e25_img.png"
}
],
"creation_year": [
{
"locale": null,
"channel": null,
"data": "1949"
}
]
},
"created": "2021-01-01T01:23:34+00:00",
"updated": "2021-02-03T23:45:59+00:00"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Update or create a record of a given reference entity
This endpoint allows you to update a given record of a given reference entity. Learn more about Update behavior. Note that if the record does not already exist for the given reference entity, it creates it.
REQUEST
patch /api/rest/v1/reference-entities/{reference_entity_code}/records/{code}
Path parameters
reference_entity_code
(string)
• This path parameter is used to specify the unique identifier of the reference entity you want to retrieve or manipulate.
It is essential for identifying the specific reference entity in the API requests.
Ensure that the reference entity code is correctly formatted and corresponds to an existing reference entity in the system.
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
Example
{
"code": "kartell",
"values": {
"label": [
{
"locale": "en_US",
"channel": null,
"data": "Kartell"
}
],
"image": [
{
"locale": null,
"channel": null,
"data": "0/c/b/0/0cb0c0e115dedba676f8d1ad8343ec207ab54c7b_image.jpg"
}
],
"description": [
{
"locale": "en_US",
"channel": null,
"data": "Kartell, the Italian furniture company that sells modern and remarkable pieces of furniture."
},
{
"locale": "fr_FR",
"channel": null,
"data": "Kartell, l'éditeur de meuble italien spécialisé dans la signature de belles pièces au design contemporain."
}
],
"country": [
{
"locale": null,
"channel": null,
"data": "italy"
}
],
"collection_overview": [
{
"locale": null,
"channel": null,
"data": "5/1/d/8/51d81dc778ba1501a8f998f3ab5797569f3b9e25_img.png"
}
],
"creation_year": [
{
"locale": null,
"channel": null,
"data": "1949"
}
]
}
}RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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 • URI of the updated resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Reference entity media file
Create a new media file for a reference entity or a record
This endpoint allows you to create a new media file and associate it to the image of a reference entity, or to the main image or to an attribute value of a record
REQUEST
post /api/rest/v1/reference-entities-media-files
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
RESPONSES
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 • URI of the created resource
asset-media-file-code • Code of the created asset media file
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}Unprocessable entity. The file is invalid or missing.
Body Format application/json
{
code
(integer)
•
message
(string)
•
}
Example
{
"code": 422,
"message": "Property \"file\" is required."
}Download the media file associated to a reference entity or a record
This endpoint allows you to download a given media file that is associated with a reference entity or a record
REQUEST
get /api/rest/v1/reference-entities-media-files/{code}
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Body
Ø
RESPONSES
Returns the binary of the media file
Body Format Mime-type of the media file
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.
Body Format Mime-type of the media file
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.
Body Format Mime-type of the media file
Asset Manager
Asset family
Get list of asset families
This endpoint allows you to get a list of asset families. Asset families are paginated.
REQUEST
get /api/rest/v1/asset-families
Path parameters
Ø
Query parameters
search_after
(string,
cursor to the first page
by default)
• 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 section for more details.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return asset families paginated.
The response is paginated and includes links to navigate through the pages.
Only search_after pagination is used.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
code (string)
• Asset family code
labels (object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$} (string,null)
• Asset family label for the specified locale
}
attribute_as_main_media (string,null)
• Attribute code that is used as the main media of the asset family
naming_convention (object)
: {
source (object)
• The string on which the naming convention should be applied.
More details here.
pattern (string)
• The regular expression that should be applied on the source.
More details here.
abort_asset_creation_on_error (boolean)
• Whether the asset should be created if the naming convention failed to apply.
More details here.
}
product_link_rules (array [object])
: [
{
product_selections (array [object]) • The product selection to which the assets of the asset family to be automatically linked.
More details here.
assign_assets_to (array [object]) • The product value in which your assets will be assigned.
More details here.
}
]
transformations (array [object])
: [
{
label (string) • The name of the transformation
filename_suffix (string) • The suffix that will be appended to the source filename to generate the target filename.
More details here.
filename_prefix (string) • The prefix that will be prepended to the source filename to generate the target filename.
More details here.
source (object) • The attribute value in which is stored the media file you want to use as the source file for your transformation.
More details here.
target (object) • The attribute value in which the PIM will generate the new transformed file, aka the target file.
More details here.
operations (array [object]) • The transformations that should be applied to your source file to generate the target file.
More details here.
}
]
sharing_enabled (boolean)
• Share links are available/unavailable for media file attributes of all the assets in this family
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/asset-families"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/asset-families"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/asset-families?search_after=user_guides"
}
},
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/asset-families/packshots"
}
},
"code": "packshots",
"labels": {
"en_US": "Packshots",
"fr_FR": "Plans produit"
},
"naming_convention": {
"source": {
"property": "code",
"channel": null,
"locale": null
},
"pattern": "/(?P<product_ref>.*)\\.jpg/",
"abort_asset_creation_on_error": true
},
"product_link_rules": [
{
"product_selections": [
{
"field": "sku",
"operator": "=",
"value": "{{product_ref}}"
}
],
"assign_assets_to": [
{
"attribute": "{{my_product_attribute}}",
"mode": "add"
}
]
}
],
"transformations": [
{
"label": "My transformation",
"filename_suffix": "_thumbnailBW",
"source": {
"attribute": "main_image",
"channel": null,
"locale": null
},
"target": {
"attribute": "thumbnail",
"channel": null,
"locale": null
},
"operations": [
{
"type": "thumbnail",
"parameters": {
"width": 150,
"height": 150
}
},
{
"type": "colorspace",
"parameters": {
"colorspace": "grey"
}
}
]
}
],
"sharing_enabled": false
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/asset-families/videos"
}
},
"code": "videos",
"labels": {
"en_US": "Videos",
"fr_FR": "Vidéos"
},
"product_link_rules": [
{
"product_selections": [
{
"field": "categories",
"operator": "IN",
"value": "{{category}}"
}
],
"assign_assets_to": [
{
"attribute": "presentation_video",
"locale": "{{locale}}",
"mode": "replace"
}
]
}
],
"sharing_enabled": true
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/asset-families/user_guides"
}
},
"code": "user_guides",
"labels": {
"en_US": "User guides",
"fr_FR": "Guides utilisateur"
},
"product_link_rules": [
{
"product_selections": [
{
"field": "sku",
"operator": "=",
"value": "{{product_ref}}"
}
],
"assign_assets_to": [
{
"attribute": "user_instructions",
"locale": "{{locale}}",
"mode": "replace"
}
]
}
],
"sharing_enabled": false
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Get an asset family
This endpoint allows you to get the information about a given asset family
REQUEST
get /api/rest/v1/asset-families/{code}
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the asset family in JSON format
Body Format application/json
{
code
(string)
• Asset family code
labels
(object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Asset family label for the specified locale
}
attribute_as_main_media
(string,null)
• Attribute code that is used as the main media of the asset family
naming_convention
(object)
: {
source
(object)
• The string on which the naming convention should be applied.
More details here.
pattern
(string)
• The regular expression that should be applied on the source.
More details here.
abort_asset_creation_on_error
(boolean)
• Whether the asset should be created if the naming convention failed to apply.
More details here.
}
product_link_rules
(array [object])
: [
{
product_selections (array) • The product selection to which the assets of the asset family to be automatically linked.
More details here.
assign_assets_to (array) • The product value in which your assets will be assigned.
More details here.
}
]
transformations
(array [object])
: [
{
label (string) • The name of the transformation
filename_suffix (string) • The suffix that will be appended to the source filename to generate the target filename.
More details here.
filename_prefix (string) • The prefix that will be prepended to the source filename to generate the target filename.
More details here.
source (object) • The attribute value in which is stored the media file you want to use as the source file for your transformation.
More details here.
target (object) • The attribute value in which the PIM will generate the new transformed file, aka the target file.
More details here.
operations (array) • The transformations that should be applied to your source file to generate the target file.
More details here.
}
]
sharing_enabled
(boolean)
• Share links are available/unavailable for media file attributes of all the assets in this family
}
Example
{
"code": "model_pictures",
"labels": {
"en_US": "Model pictures",
"fr_FR": "Photographies en pied"
},
"attribute_as_main_media": "main_image",
"naming_convention": {
"source": {
"property": "code"
},
"pattern": "/(?P<product_ref>.*)-.*/",
"abort_asset_creation_on_error": true
},
"product_link_rules": [
{
"product_selections": [
{
"field": "sku",
"operator": "EQUALS",
"value": "{{product_ref}}"
}
],
"assign_assets_to": [
{
"attribute": "model_pictures",
"mode": "replace"
}
]
}
],
"transformations": [
{
"label": "Thumbnail plus black and white transformation",
"filename_suffix": "_thumbnailBW",
"source": {
"attribute": "main_image",
"channel": "ecommerce",
"locale": "en_US"
},
"target": {
"attribute": "thumbnail",
"channel": "ecommerce",
"locale": "en_US"
},
"operations": [
{
"type": "thumbnail",
"parameters": {
"width": 150,
"height": 150
}
},
{
"type": "colorspace",
"parameters": {
"colorspace": "grey"
}
}
]
}
],
"sharing_enabled": true
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Update/create an asset family
This endpoint allows you to update a given asset family. Note that if the asset family does not already exist, it creates it.
REQUEST
patch /api/rest/v1/asset-families/{code}
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string)
• Asset family code
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Asset family label for the specified locale
}
attribute_as_main_media
(string,null,
First media file or media link attribute that was created by default)
• Attribute code that is used as the main media of the asset family
naming_convention
(object,
[] by default)
: {
source
(object)
• The string on which the naming convention should be applied.
More details here.
pattern
(string)
• The regular expression that should be applied on the source.
More details here.
abort_asset_creation_on_error
(boolean)
• Whether the asset should be created if the naming convention failed to apply.
More details here.
}
product_link_rules
(array[object],
[] by default)
: [
{
product_selections (array[object]) • The product selection to which the assets of the asset family to be automatically linked.
More details here.
assign_assets_to (array[object]) • The product value in which your assets will be assigned.
More details here.
}
]
transformations
(array[object],
[] by default)
: [
{
label (string) • The name of the transformation
filename_suffix (string) • The suffix that will be appended to the source filename to generate the target filename.
More details here.
filename_prefix (string) • The prefix that will be prepended to the source filename to generate the target filename.
More details here.
source (object) • The attribute value in which is stored the media file you want to use as the source file for your transformation.
More details here.
target (object) • The attribute value in which the PIM will generate the new transformed file, aka the target file.
More details here.
operations (array[object]) • The transformations that should be applied to your source file to generate the target file.
More details here.
}
]
sharing_enabled
(boolean)
• Share links are available/unavailable for media file attributes of all the assets in this family
}
Example
{
"code": "model_pictures",
"labels": {
"en_US": "Model pictures",
"fr_FR": "Photographies en pied"
},
"attribute_as_main_media": "main_image",
"naming_convention": {
"source": {
"property": "code"
},
"pattern": "/(?P<product_ref>.*)-.*/",
"abort_asset_creation_on_error": true
},
"product_link_rules": [
{
"product_selections": [
{
"field": "sku",
"operator": "EQUALS",
"value": "{{product_ref}}"
}
],
"assign_assets_to": [
{
"attribute": "model_pictures",
"mode": "replace"
}
]
}
],
"transformations": [
{
"label": "Thumbnail plus black and white transformation",
"filename_suffix": "_thumbnailBW",
"source": {
"attribute": "main_image",
"channel": "ecommerce",
"locale": "en_US"
},
"target": {
"attribute": "thumbnail",
"channel": "ecommerce",
"locale": "en_US"
},
"operations": [
{
"type": "thumbnail",
"parameters": {
"width": 150,
"height": 150
}
},
{
"type": "colorspace",
"parameters": {
"colorspace": "grey"
}
}
]
}
],
"sharing_enabled": true
}RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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 • URI of the updated resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Asset attribute
Get the list of attributes of a given asset family
This endpoint allows you to get the list of attributes of a given asset family
REQUEST
get /api/rest/v1/asset-families/{asset_family_code}/attributes
Path parameters
asset_family_code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return the attributes of the given asset family
Body Format application/json
[
{
code
(string)
• Attribute code
labels
(object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$} (string,null)
• Attribute label for the specified locale
}
type
(string)
• Attribute type.
See type section for more details.
value_per_locale
(boolean)
• Whether the attribute is localizable, i.e. can have one value by locale
value_per_channel
(boolean)
• Whether the attribute is scopable, i.e. can have one value by channel
is_required_for_completeness
(boolean)
• Whether the attribute should be part of the record's completeness calculation
is_read_only
(boolean)
• Whether the attribute should be in read only mode only in the UI, but you can still update it with the API
max_characters
(integer,null)
• Maximum number of characters allowed for the value of the attribute when the attribute type is text
is_textarea
(boolean)
• Whether the UI should display a text area instead of a simple field when the attribute type is text
is_rich_text_editor
(boolean)
• Whether the UI should display a rich text editor instead of a simple text area when the attribute type is text
validation_rule
(string,null)
• Validation rule type used to validate the attribute value when the attribute type is text
validation_regexp
(string,null)
• Regexp expression used to validate the attribute value when the attribute type is text
allowed_extensions
(array [string])
• Extensions allowed when the attribute type is media_file
max_file_size
(string,null)
• Max file size in MB when the attribute type is media_file
decimals_allowed
(boolean)
• Whether decimals are allowed when the attribute type is
number
min_value
(string,null)
• Minimum value allowed when the attribute type is number
max_value
(string,null)
• Maximum value allowed when the attribute type is number
media_type
(string)
• 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.
prefix
(string,null)
• Prefix of the media_link attribute type.
The common url root that prefixes the link to the media.
suffix
(string,null)
• Suffix of the media_link attribute type.
The common url suffix for the media.
reference_entity
(string,null)
• Reference entity code for the record attribute type (see Reference entity)
asset_family_code
(string,null)
• Asset family code for the asset_family_single_link and asset_family_multiple_links attribute types
}
]
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
},
{
"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"
}
]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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Get an attribute of a given asset family
This endpoint allows you to get the information about a given attribute for a given asset family
REQUEST
get /api/rest/v1/asset-families/{asset_family_code}/attributes/{code}
Path parameters
asset_family_code
(string)
• 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.
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the asset attribute in JSON format
Body Format application/json
{
code
(string)
• Attribute code
labels
(object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Attribute label for the specified locale
}
type
(string)
• Attribute type.
See type section for more details.
value_per_locale
(boolean)
• Whether the attribute is localizable, i.e. can have one value by locale
value_per_channel
(boolean)
• Whether the attribute is scopable, i.e. can have one value by channel
is_required_for_completeness
(boolean)
• Whether the attribute should be part of the record's completeness calculation
is_read_only
(boolean)
• Whether the attribute should be in read only mode only in the UI, but you can still update it with the API
max_characters
(integer,null)
• Maximum number of characters allowed for the value of the attribute when the attribute type is text
is_textarea
(boolean)
• Whether the UI should display a text area instead of a simple field when the attribute type is text
is_rich_text_editor
(boolean)
• Whether the UI should display a rich text editor instead of a simple text area when the attribute type is text
validation_rule
(string,null)
• Validation rule type used to validate the attribute value when the attribute type is text
validation_regexp
(string,null)
• Regexp expression used to validate the attribute value when the attribute type is text
allowed_extensions
(array [string])
• Extensions allowed when the attribute type is media_file
max_file_size
(string,null)
• Max file size in MB when the attribute type is media_file
decimals_allowed
(boolean)
• Whether decimals are allowed when the attribute type is
number
min_value
(string,null)
• Minimum value allowed when the attribute type is number
max_value
(string,null)
• Maximum value allowed when the attribute type is number
media_type
(string)
• 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.
prefix
(string,null)
• Prefix of the media_link attribute type.
The common url root that prefixes the link to the media.
suffix
(string,null)
• Suffix of the media_link attribute type.
The common url suffix for the media.
reference_entity
(string,null)
• Reference entity code for the record attribute type (see Reference entity)
asset_family_code
(string,null)
• Asset family code for the asset_family_single_link and asset_family_multiple_links attribute types
}
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
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Update/create an attribute of a given asset family
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.
REQUEST
patch /api/rest/v1/asset-families/{asset_family_code}/attributes/{code}
Path parameters
asset_family_code
(string)
• 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.
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string)
• Attribute code
labels
(object,
[] by default)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Attribute label for the specified locale
}
type
(string)
• Attribute type.
See type section for more details.
value_per_locale
(boolean,
false by default)
• Whether the attribute is localizable, i.e. can have one value by locale
value_per_channel
(boolean,
false by default)
• Whether the attribute is scopable, i.e. can have one value by channel
is_required_for_completeness
(boolean,
false by default)
• Whether the attribute should be part of the record's completeness calculation
is_read_only
(boolean,
false by default)
• Whether the attribute should be in read only mode only in the UI, but you can still update it with the API
max_characters
(integer,null)
• Maximum number of characters allowed for the value of the attribute when the attribute type is text
is_textarea
(boolean,
false by default)
• Whether the UI should display a text area instead of a simple field when the attribute type is text
is_rich_text_editor
(boolean)
• Whether the UI should display a rich text editor instead of a simple text area when the attribute type is text
validation_rule
(string,null,
none by default)
• Validation rule type used to validate the attribute value when the attribute type is text
validation_regexp
(string,null,
null by default)
• Regexp expression used to validate the attribute value when the attribute type is text
allowed_extensions
(array[string],
[] by default)
• Extensions allowed when the attribute type is media_file
max_file_size
(string,null,
null by default)
• Max file size in MB when the attribute type is media_file
decimals_allowed
(boolean,
false by default)
• Whether decimals are allowed when the attribute type is
number
min_value
(string,null,
null by default)
• Minimum value allowed when the attribute type is number
max_value
(string,null,
null by default)
• Maximum value allowed when the attribute type is number
media_type
(string)
• 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.
prefix
(string,null,
null by default)
• Prefix of the media_link attribute type.
The common url root that prefixes the link to the media.
suffix
(string,null,
null by default)
• Suffix of the media_link attribute type.
The common url suffix for the media.
reference_entity
(string,null,
null by default)
• Reference entity code for the record attribute type (see Reference entity)
asset_family_code
(string,null,
null by default)
• Asset family code for the asset_family_single_link and asset_family_multiple_links attribute types
}
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
}RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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 • URI of the updated resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Asset attribute option
Get a list of attribute options of a given attribute for a given asset family
This endpoint allows you to get a list of attribute options for a given asset family
REQUEST
get /api/rest/v1/asset-families/{asset_family_code}/attributes/{attribute_code}/options
Path parameters
asset_family_code
(string)
• 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.
attribute_code
(string)
• This path parameter is used to specify the unique identifier of the attribute you want to retrieve or manipulate.
It is essential for identifying the specific attribute in the API requests.
Ensure that the attribute code is correctly formatted and corresponds to an existing attribute in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return the options of the given attribute of the given asset family
Body Format application/json
[
{
code
(string)
• Attribute's option code
labels
(object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$} (string,null)
• Attribute label for the specified locale.
}
}
]
Example
[
{
"code": "unique_size",
"labels": {
"en_US": "Unique size",
"fr_FR": "Taille unique"
}
},
{
"code": "size_27",
"labels": {
"en_US": "Size 27",
"fr_FR": "Taille 36"
}
},
{
"code": "small",
"labels": {
"en_US": "S",
"fr_FR": "S"
}
}
]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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Get an attribute option for a given attribute of a given asset family
This endpoint allows you to get the information about a given asset attribute option
REQUEST
get /api/rest/v1/asset-families/{asset_family_code}/attributes/{attribute_code}/options/{code}
Path parameters
asset_family_code
(string)
• 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.
attribute_code
(string)
• This path parameter is used to specify the unique identifier of the attribute you want to retrieve or manipulate.
It is essential for identifying the specific attribute in the API requests.
Ensure that the attribute code is correctly formatted and corresponds to an existing attribute in the system.
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the asset attribute option in JSON format
Body Format application/json
{
code
(string)
• Attribute's option code
labels
(object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Attribute label for the specified locale.
}
}
Example
{
"code": "small",
"labels": {
"en_US": "S",
"fr_FR": "S"
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Update/create an asset attribute option for a given asset family
This endpoint allows you to update a given option for a given attribute and a given asset family. Learn more about the Update behavior. Note that if the option does not already exist for the given attribute of the given asset family, it creates it.
REQUEST
patch /api/rest/v1/asset-families/{asset_family_code}/attributes/{attribute_code}/options/{code}
Path parameters
asset_family_code
(string)
• 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.
attribute_code
(string)
• This path parameter is used to specify the unique identifier of the attribute you want to retrieve or manipulate.
It is essential for identifying the specific attribute in the API requests.
Ensure that the attribute code is correctly formatted and corresponds to an existing attribute in the system.
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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 • URI of the updated resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Asset media file
Create a new media file for an asset
This endpoint allows you to create a new media file and associate it to a media file attribute value of an asset
REQUEST
post /api/rest/v1/asset-media-files
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
RESPONSES
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 • URI of the created resource
asset-media-file-code • Code of the created asset media file
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Download the media file associated to an asset
This endpoint allows you to download a given media file that is associated with an asset
REQUEST
get /api/rest/v1/asset-media-files/{code}
Path parameters
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Body
Ø
RESPONSES
Returns the binary of the media file
Body Format Mime-type of the media file
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.
Body Format Mime-type of the media file
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.
Body Format Mime-type of the media file
Asset
Get the list of the assets of a given asset family
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.
REQUEST
get /api/rest/v1/asset-families/{asset_family_code}/assets
Path parameters
asset_family_code
(string)
• 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.
Query parameters
search
(string)
• Filter assets,
for more details see the Asset filters section.
channel
(string)
• 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 section.
locales
(string)
• 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 section.
search_after
(string,
cursor to the first page
by default)
• 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 section for more details.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
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.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
code (string)
• Code of the asset
asset_family_code (string)
• Code of the asset family
values (object)
• Asset attributes values.
See the Focus on the asset values section for more details.
created (string)
• Date of creation
updated (string)
• Date of the last update
}
]
}
}
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",
"_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
}
]
},
"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",
"_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
}
]
},
"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",
"_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
}
]
},
"created": "2021-05-31T09:23:34+00:00",
"updated": "2021-05-31T09:23:34+00:00"
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Update/create several assets
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.
REQUEST
patch /api/rest/v1/asset-families/{asset_family_code}/assets
Path parameters
asset_family_code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
[
code (string)
• Code of the asset
asset_family_code (string)
• Code of the asset family
values (object)
• Asset attributes values.
See the Focus on the asset values section for more details.
created (string)
• Date of creation
updated (string)
• Date of the last update
]
}
Example
[
{
"code": "sku_54628_picture1",
"values": {
"media_preview": [
{
"data": "sku_54628_picture1.jpg",
"channel": null,
"locale": null
}
],
"model_wears_size": [
{
"data": "s",
"channel": null,
"locale": null
}
],
"photographer": [
{
"data": "ben_levy",
"channel": null,
"locale": null
}
],
"main_colors": [
{
"data": [
"red",
"purple"
],
"channel": null,
"locale": null
}
],
"end_of_use_date": [
{
"data": "02/03/2021",
"channel": null,
"locale": null
}
]
},
"created": "2021-05-31T09:23:34+00:00",
"updated": "2021-05-31T09:23:34+00:00"
},
{
"code": "sku_54628_picture2",
"values": {
"media_preview": [
{
"data": "sku_54628_picture2.jpg",
"channel": null,
"locale": null
}
],
"model_wears_size": [
{
"data": "s",
"channel": null,
"locale": null
}
],
"photographer": [
{
"data": "ben_levy",
"channel": null,
"locale": null
}
],
"main_colors": [
{
"data": [
"blue",
"white"
],
"channel": null,
"locale": null
}
],
"end_of_use_date": [
{
"data": "02/03/2021",
"channel": null,
"locale": null
}
]
},
"created": "2021-05-31T09:23:34+00:00",
"updated": "2021-05-31T09:23:34+00:00"
},
{
"code": "sku_54628_picture3",
"values": {
"media_preview": [
{
"data": "sku_54628_picture3.jpg",
"channel": null,
"locale": null
}
],
"model_wears_size": [
{
"data": "s",
"channel": null,
"locale": null
}
],
"photographer": [
{
"data": "ben_levy",
"channel": null,
"locale": null
}
],
"main_colors": [
{
"data": [
"purple"
],
"channel": null,
"locale": null
}
],
"end_of_use_date": [
{
"data": "02/03/2021",
"channel": null,
"locale": null
}
]
},
"created": "2021-05-31T09:23:34+00:00",
"updated": "2021-05-31T09:23:34+00:00"
}
]RESPONSES
Returns an JSON array in which each object gives you the status of each asset creation or update
Body Format application/json
[
{
code
(string)
• Resource code
status_code
(integer)
• HTTP status code,
see Client errors to understand the meaning of each code
message
(string)
• Message explaining the error
}
]
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
}
]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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 413,
"message": "Too many resources to process, 100 is the maximum allowed."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}Get an asset of a given asset family
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.
REQUEST
get /api/rest/v1/asset-families/{asset_family_code}/assets/{code}
Path parameters
asset_family_code
(string)
• 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.
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the asset in JSON standard format
Body Format application/json
{
code
(string)
• Code of the asset
asset_family_code
(string)
• Code of the asset family
values
(object)
• Asset attributes values.
See the Focus on the asset values section for more details.
created
(string)
• Date of creation
updated
(string)
• Date of the last update
}
Example
{
"code": "sku_54628_picture1",
"values": {
"media_preview": [
{
"locale": null,
"channel": null,
"data": "sku_54628_picture1.jpg"
}
],
"model_wears_size": [
{
"locale": null,
"channel": null,
"data": "s"
}
],
"photographer": [
{
"locale": null,
"channel": null,
"data": "ben_levy"
}
],
"main_colors": [
{
"locale": null,
"channel": null,
"data": [
"red",
"purple"
]
}
],
"end_of_use_date": [
{
"locale": null,
"channel": null,
"data": "02/03/2021"
}
]
},
"created": "2021-05-31T09:23:34+00:00",
"updated": "2021-05-31T09:23:34+00:00"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Update/create an asset
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.
REQUEST
patch /api/rest/v1/asset-families/{asset_family_code}/assets/{code}
Path parameters
asset_family_code
(string)
• 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.
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
code
(string)
• Code of the asset
asset_family_code
(string)
• Code of the asset family
values
(object)
• Asset attributes values.
See the Focus on the asset values section for more details.
created
(string)
• Date of creation
updated
(string)
• Date of the last update
}
Example
{
"code": "sku_54628_picture1",
"values": {
"media_preview": [
{
"locale": null,
"channel": null,
"data": "sku_54628_picture1.jpg"
}
],
"model_wears_size": [
{
"locale": null,
"channel": null,
"data": "s"
}
],
"photographer": [
{
"locale": null,
"channel": null,
"data": "ben_levy"
}
],
"main_colors": [
{
"locale": null,
"channel": null,
"data": [
"red",
"purple"
]
}
],
"end_of_use_date": [
{
"locale": null,
"channel": null,
"data": "02/03/2021"
}
]
},
"created": "2021-05-31T09:23:34+00:00",
"updated": "2021-05-31T09:23:34+00:00"
}RESPONSES
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 • URI of the created resource
Body Format application/json
Ø
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 • URI of the updated resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Delete an asset
This endpoint allows you to delete a given asset. This endpoint is case sensitive on the asset family code.
REQUEST
delete /api/rest/v1/asset-families/{asset_family_code}/assets/{code}
Path parameters
asset_family_code
(string)
• 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.
code
(string)
• 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.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
No content to return. Means that the deletion was successful.
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Catalogs for Apps
Make sure you have a valid App token with scopes related to catalogs authorized in order to use the following endpoints. You can find information about these scopes in the section ask for catalog scopes
Catalogs
Get the list of owned catalogs
This endpoint allows you to get the list of catalogs you owned
REQUEST
get /api/rest/v1/catalogs
Path parameters
Ø
Query parameters
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
Headers
Authorization
• Equal to 'Bearer xxx', 'xxx' being the App authentication token, see documentation for getting an app token
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return the paginated catalogs owned by the user making the request. The response is paginated and includes links to navigate through the pages.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
id (string)
• Catalog id
name (string)
• Catalog name
enabled (boolean)
• Whether the catalog is enabled or not
managed_currencies (array [string])
• List of currency codes
• List of currency codes
managed_locales (array [string])
• List of locale codes
• List of locale codes
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/catalogs?page=3&limit=2"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/catalogs?page=1&limit=2"
},
"previous": {
"href": "https://demo.akeneo.com/api/rest/v1/catalogs?page=2&limit=2"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/catalogs?page=4&limit=2"
}
},
"current_page": 3,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/catalogs/12351d98-200e-4bbc-aa19-7fdda1bd14f2"
}
},
"id": "12351d98-200e-4bbc-aa19-7fdda1bd14f2",
"name": "Store EUROPE",
"enabled": false,
"managed_currencies": [
"EUR",
"GBP"
],
"managed_locales": [
"fr_FR",
"en_UK",
"de_DE",
"it_IT",
"es_ES"
]
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/catalogs/092c5f22-ecd8-485f-97e9-3b78098e1386"
}
},
"id": "092c5f22-ecd8-485f-97e9-3b78098e1386",
"name": "Store US",
"enabled": true,
"managed_currencies": [
"USD"
],
"managed_locales": [
"en_US",
"es_ES"
]
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}Create a new catalog
This endpoint allows you to create a new catalog
REQUEST
post /api/rest/v1/catalogs
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', 'xxx' being the App authentication token, see documentation for getting an app token
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
Example
{
"name": "My app catalog",
"managed_currencies": [
"EUR",
"USD",
"GBP"
],
"managed_locales": [
"fr_FR",
"en_US"
]
}RESPONSES
Created
Body Format application/json
{
id
(string)
• Catalog id
name
(string)
• Catalog name
enabled
(boolean)
• Whether the catalog is enabled or not
managed_currencies
(array [string])
• List of currency codes
managed_locales
(array [string])
• List of locale codes
}
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Get a catalog
This endpoint allows you to get the information about a catalog
REQUEST
get /api/rest/v1/catalogs/{id}
Path parameters
id
(string)
• This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', 'xxx' being the App authentication token, see documentation for getting an app token
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return the catalog
Body Format application/json
{
id
(string)
• Catalog id
name
(string)
• Catalog name
enabled
(boolean)
• Whether the catalog is enabled or not
managed_currencies
(array [string])
• List of currency codes
managed_locales
(array [string])
• List of locale codes
}
Example
{
"id": "12351d98-200e-4bbc-aa19-7fdda1bd14f2",
"name": "My app catalog",
"enabled": false,
"managed_currencies": [
"EUR",
"USD",
"GBP"
],
"managed_locales": [
"fr_FR",
"en_US"
]
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Update a catalog
This endpoint allows you to update a catalog
REQUEST
patch /api/rest/v1/catalogs/{id}
Path parameters
id
(string)
• This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', 'xxx' being the App authentication token, see documentation for getting an app token
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
name
(string)
• Catalog name
managed_currencies
(array[string])
• List of currency codes
managed_locales
(array[string])
• List of locale codes
}
Example
{
"name": "My app catalog",
"managed_currencies": [
"EUR",
"USD",
"GBP"
],
"managed_locales": [
"fr_FR",
"en_US"
]
}RESPONSES
Updated
Body Format application/json
{
id
(string)
• Catalog id
name
(string)
• Catalog name
enabled
(boolean)
• Whether the catalog is enabled or not
managed_currencies
(array [string])
• List of currency codes
managed_locales
(array [string])
• List of locale codes
}
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Delete a catalog
This endpoint allows you to delete a catalog.
REQUEST
delete /api/rest/v1/catalogs/{id}
Path parameters
id
(string)
• This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', 'xxx' being the App authentication token, see documentation for getting an app token
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
No content to return. Means that the deletion was successful.
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Duplicate a catalog
This endpoint allows you to duplicate an existing catalog.
Note that the duplicated catalog will be deactivated (set to false).
REQUEST
post /api/rest/v1/catalogs/{id}/duplicate
Path parameters
id
(string)
• This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', 'xxx' being the App authentication token, see documentation for getting an app token
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
name
(string)
• Catalog name (optional for duplication)
managed_currencies
(array[string])
• List of currency codes
managed_locales
(array[string])
• List of locale codes
skip_required_checks
(boolean,
false by default)
• Option to skip required checks
}
Example
{}RESPONSES
Catalog successfully duplicated
Body Format application/json
{
id
(string)
• Catalog id
name
(string)
• Catalog name
enabled
(boolean)
• Whether the catalog is enabled or not
managed_currencies
(array [string])
• List of currency codes
managed_locales
(array [string])
• List of locale codes
}
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Catalog products
Get the list of product uuids
This endpoint allows you to get the list of uuids of products contained in a catalog. Please, note that a disabled catalog can return an HTTP 200 with a payload containing an error message, for more details see the App Catalog section.
REQUEST
get /api/rest/v1/catalogs/{id}/product-uuids
Path parameters
id
(string)
• This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
search_after
(string,
cursor to the first page
by default)
• 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 section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
updated_before
(string)
• Filter products that have been updated BEFORE the provided date.
It is useful for retrieving products that haven't been modified since a specific date, which is essential for historical data analysis and reporting.
This filter uses the PIM products updated date and is only available on Catalogs endpoints.
updated_after
(string)
• Filter products that have been updated AFTER the provided date.
It is useful for retrieving only recently modified products, which is essential for synchronization and incremental data processing.
This filter uses the PIM products updated date and is only available on Catalogs endpoints.
with_count
(boolean)
• Return the count of items in the response.
Be careful with that, on a big catalog, it can decrease performance in a significant way.
It is useful for understanding the size of the dataset being returned, especially when dealing with large collections.
Use it judiciously to avoid performance issues.
Headers
Authorization
• Equal to 'Bearer xxx', 'xxx' being the App authentication token, see documentation for getting an app token
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return the paginated product uuids.
The response is paginated and includes links to navigate through the pages.
Only search_after pagination is used.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
items_count
(integer)
• Total number of items (only if with_count parameter is set to true)
_embedded
(object)
: {
items (array)
: [
{
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/catalogs/12351d98-200e-4bbc-aa19-7fdda1bd14f2/product-uuids&with_count=true"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/catalogs/12351d98-200e-4bbc-aa19-7fdda1bd14f2/product-uuids&with_count=true"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/catalogs/12351d98-200e-4bbc-aa19-7fdda1bd14f2/product-uuids?search_after=eddfbd2a-abc7-488d-b9e3-41289c824f80&with_count=true"
}
},
"items_count": 10,
"_embedded": {
"items": [
"844c736b-a19b-48a6-a354-6056044729f0",
"b2a683ef-4a91-4ed3-b3fa-76dab065a8d5",
"eddfbd2a-abc7-488d-b9e3-41289c824f80"
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Get the list of products related to a catalog
This endpoint allows you to get the list of products related to a catalog. Products are paginated and they can be filtered. In the Enterprise Edition, permissions based on your app settings are applied to the set of products you request. Please, note that a disabled catalog can return an HTTP 200 with a payload containing an error message, for more details see the App Catalog section.
REQUEST
get /api/rest/v1/catalogs/{id}/products
Path parameters
id
(string)
• This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
search_after
(string,
cursor to the first page
by default)
• 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 section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
updated_before
(string)
• Filter products that have been updated BEFORE the provided date.
It is useful for retrieving products that haven't been modified since a specific date, which is essential for historical data analysis and reporting.
This filter uses the PIM products updated date and is only available on Catalogs endpoints.
updated_after
(string)
• Filter products that have been updated AFTER the provided date.
It is useful for retrieving only recently modified products, which is essential for synchronization and incremental data processing.
This filter uses the PIM products updated date and is only available on Catalogs endpoints.
Headers
Authorization
• Equal to 'Bearer xxx', 'xxx' being the App authentication token, see documentation for getting an app token
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return the paginated products or error message.
The response is paginated and includes links to navigate through the pages.
Only search_after pagination is used.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
_embedded
(object)
: {
items (array)
: [
{
uuid (string)
• Product UUID
identifier (string)
• Product identifier, i.e. the value of the only pim_catalog_identifier attribute
enabled (boolean)
• Whether the product is enabled
family (string,null)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories (array [string])
• Codes of the categories in which the product is classified
groups (array [string])
• Codes of the groups to which the product belong.
Each string of the array is equal to an existing group code.
parent (string,null)
• Code of the parent product model when the product is a variant
root_parent (string)
• Code of the root parent product model when the product is a variant
(only available when the with_root_parent is set to true).
values (object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations (object)
: {
{^\w+$} (object)
: {
groups
(array [string]) • Array of groups codes with which the product is in relation
products
(array [string]) • Array of product identifiers with which the product is in relation
product_models
(array [string]) • Array of product model codes with which the product is in relation
}
}
quantified_associations (object)
: {
{^\w+$} (object)
: {
products
(array [object]) • Array of objects containing product uuids and quantities with which the product is in relation
product_models
(array [object]) • Array of objects containing product model codes and quantities with which the product is in relation
}
}
created (string)
• Date of creation
updated (string)
• Date of the last update
metadata (object)
: {
workflow_status (string)
• Status of the product regarding the user permissions
}
quality_scores (array [object])
• Product quality scores for each channel/locale combination
(only available when the with_quality_scores query parameter is set to true).
completenesses (array [object])
• Product completenesses for each channel/locale combination
(only available when the with_completenesses query parameter is set to true).
workflow_execution_statuses (array [object])
• Workflow execution statuses of the product
(only available when the with_workflow_execution_statuses query parameter is set to true)
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/catalogs/65f5a521-e65c-4d7b-8be8-1f267fa2729c/products?limit=3"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/catalogs/65f5a521-e65c-4d7b-8be8-1f267fa2729c/products?limit=3"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/catalogs/65f5a521-e65c-4d7b-8be8-1f267fa2729c/products?search_after=0059d30f-6874-4277-81ed-3b3657c83f5e&limit=3"
}
},
"_embedded": {
"items": [
{
"uuid": "00073089-1310-4340-bcf0-9e33e4019b79",
"enabled": true,
"family": "mens_clothing",
"categories": [
"Cloths"
],
"groups": [],
"values": {
"Default_Price": [
{
"data": [
{
"amount": "10.00",
"currency": "USD"
}
],
"locale": null,
"scope": null
}
],
"sku": [
{
"data": "product_416",
"locale": null,
"scope": null
}
],
"Name": [
{
"data": "Product 416",
"locale": null,
"scope": null
}
],
"Weight": [
{
"data": {
"amount": 10,
"unit": "KILOGRAM"
},
"locale": null,
"scope": null
}
]
},
"created": "2022-03-14T15:25:45+00:00",
"updated": "2022-06-24T12:54:58+00:00",
"associations": {
"PACK": {
"products": [],
"product_models": [],
"groups": []
},
"UPSELL": {
"products": [],
"product_models": [],
"groups": []
},
"X_SELL": {
"products": [],
"product_models": [],
"groups": []
},
"SUBSTITUTION": {
"products": [],
"product_models": [],
"groups": []
}
},
"quantified_associations": {}
},
{
"uuid": "00248acf-f1f7-45cb-b409-c8c4b9a17a86",
"enabled": true,
"family": "mens_clothing",
"categories": [
"Cloths"
],
"groups": [],
"values": {
"Default_Price": [
{
"data": [
{
"amount": "10.00",
"currency": "USD"
}
],
"locale": null,
"scope": null
}
],
"sku": [
{
"data": "product_470",
"locale": null,
"scope": null
}
],
"Name": [
{
"data": "Product 470",
"locale": null,
"scope": null
}
],
"Weight": [
{
"data": {
"amount": 10,
"unit": "KILOGRAM"
},
"locale": null,
"scope": null
}
]
},
"created": "2022-03-14T15:25:45+00:00",
"updated": "2022-06-24T12:55:01+00:00",
"associations": {
"PACK": {
"products": [],
"product_models": [],
"groups": []
},
"UPSELL": {
"products": [],
"product_models": [],
"groups": []
},
"X_SELL": {
"products": [],
"product_models": [],
"groups": []
},
"SUBSTITUTION": {
"products": [],
"product_models": [],
"groups": []
}
},
"quantified_associations": {}
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Get a product related to a catalog
This endpoint allows you to get a specific product related to a catalog. In the Enterprise Edition, permissions based on your app settings are applied on the product you request. Please, note that a disabled catalog can return an HTTP 200 with a payload containing an error message, for more details see the App Catalog section.
REQUEST
get /api/rest/v1/catalogs/{id}/products/{uuid}
Path parameters
id
(string)
• This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.
uuid
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the UUID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', 'xxx' being the App authentication token, see documentation for getting an app token
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return the product
Body Format application/json
{
uuid
(string)
• Product UUID
identifier
(string)
• Product identifier, i.e. the value of the only pim_catalog_identifier attribute
enabled
(boolean)
• Whether the product is enabled
family
(string,null)
• Family code from which the product inherits its attributes and attributes requirements.
In the case of variant product, the given family should be the same as the product model family.
categories
(array [string])
• Codes of the categories in which the product is classified
groups
(array [string])
• Codes of the groups to which the product belong.
Each string of the array is equal to an existing group code.
parent
(string,null)
• Code of the parent product model when the product is a variant
root_parent
(string)
• Code of the root parent product model when the product is a variant
(only available when the with_root_parent is set to true).
values
(object)
• Product attributes values.
Each key is an attribute code, and the value is an array of value objects for that attribute.
See documentation for details.
associations
(object)
: {
{^\w+$}
(object)
: {
groups
(array[string])
• Array of groups codes with which the product is in relation
products
(array[string])
• Array of product identifiers with which the product is in relation
product_models
(array[string])
• Array of product model codes with which the product is in relation
}
}
quantified_associations
(object)
: {
{^\w+$}
(object)
: {
products
(array[object])
• Array of objects containing product uuids and quantities with which the product is in relation
product_models
(array[object])
• Array of objects containing product model codes and quantities with which the product is in relation
}
}
created
(string)
• Date of creation
updated
(string)
• Date of the last update
metadata
(object)
: {
workflow_status
(string)
• Status of the product regarding the user permissions
}
quality_scores
(array [object])
: [
{
scope (string) • Channel code for which the quality score is calculated
locale (string) • Locale code for which the quality score is calculated
data (string) • Quality score value for the given channel/locale combination
}
]
completenesses
(array [object])
: [
{
scope (string) • Channel code for which the completenesses score is calculated
locale (string) • Channel code for which the completenesses score is calculated
data (integer) • Completenesses score value for the given channel/locale combination
}
]
workflow_execution_statuses
(array [object])
: [
{
uuid (string) • Workflow execution UUID
status (string) • Status of the workflow execution
started_at (string) • Date and time when the workflow execution was started
completed_at (string,null) • Date and time when the workflow execution was completed, null if still in progress
workflow (object) • Workflow associated with the workflow execution
tasks (array) • Tasks associated with the workflow execution
}
]
}
Example
{
"uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
"enabled": true,
"family": "tshirt",
"categories": [
"summer_collection"
],
"groups": [],
"values": {
"sku": [
{
"data": "top"
}
],
"name": [
{
"data": "Top",
"locale": "en_US"
},
{
"data": "Débardeur",
"locale": "fr_FR"
}
],
"description": [
{
"data": "Summer top",
"locale": "en_US",
"scope": "ecommerce"
},
{
"data": "Top",
"locale": "en_US",
"scope": "tablet"
},
{
"data": "Débardeur pour l'été",
"locale": "fr_FR",
"scope": "ecommerce"
},
{
"data": "Débardeur",
"locale": "fr_FR",
"scope": "tablet"
}
],
"price": [
{
"data": [
{
"amount": "15.5",
"currency": "EUR"
},
{
"amount": "15",
"currency": "USD"
}
]
}
],
"color": [
{
"data": "black",
"linked_data": {
"attribute": "color",
"code": "black",
"labels": {
"en_US": "Black",
"fr_FR": "Noir"
}
}
}
],
"size": [
{
"data": "m",
"linked_data": {
"attribute": "size",
"code": "m",
"labels": {
"en_US": "M",
"fr_FR": "M"
}
}
}
],
"collection": [
{
"data": [
"winter_2016"
],
"linked_data": {
"winter_2016": {
"attribute": "collection",
"code": "winter_2016",
"labels": {
"en_US": "Winter 2016",
"fr_FR": "Hiver 2016"
}
}
}
}
]
},
"created": "2016-06-23T18:24:44+02:00",
"updated": "2016-06-25T17:56:12+02:00",
"associations": {
"PACK": {
"products": [
"d055527c-0698-4967-8f16-8a5f23f4e5cf"
],
"product_models": [],
"groups": []
}
},
"quantified_associations": {
"PRODUCT_SET": {
"products": [
{
"uuid": "fc24e6c3-933c-4a93-8a81-e5c703d134d5",
"quantity": 2
},
{
"uuid": "a9b69002-a0b1-4ead-85c2-f8dbf59c6cfc",
"quantity": 1
}
],
"product_models": [
{
"identifier": "model-biker-jacket-leather",
"quantity": 2
}
]
}
},
"root_parent": "clothes",
"quality_scores": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": "A"
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": "B"
},
{
"scope": "tablet",
"locale": "en_US",
"data": "D"
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": "E"
}
],
"completenesses": [
{
"scope": "ecommerce",
"locale": "en_US",
"data": 10
},
{
"scope": "ecommerce",
"locale": "fr_FR",
"data": 20
},
{
"scope": "tablet",
"locale": "en_US",
"data": 30
},
{
"scope": "tablet",
"locale": "fr_FR",
"data": 40
}
],
"workflow_execution_statuses": [
{
"uuid": "8c0fe59f-4d29-4faa-b4c3-d327e7f3cc52",
"status": "in_progress",
"started_at": "2024-02-22T17:31:00Z",
"completed_at": null,
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
"tasks": [
{
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"step": {
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "review_step",
"labels": {
"en_US": "Marketing review",
"fr_FR": "Revue marketing"
}
}
}
]
}
]
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Get the list of mapped flattened products or simple products related to a catalog
This endpoint is available when the mapping is enabled on a specified catalog. When the mapping is in a basic mode, this endpoint allows you to get the list of all flattened products related to the catalog. When it's in models/variants mode, this endpoint allows you to get the list of simple products with all specified targets in the two levels of the mapping schema. Please, note that a disabled catalog can return an HTTP 200 with a payload containing an error message, for more details see the App Catalog section.
REQUEST
get /api/rest/v1/catalogs/{id}/mapped-products
Path parameters
id
(string)
• This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
search_after
(string,
cursor to the first page
by default)
• 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 section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
updated_before
(string)
• Filter products that have been updated BEFORE the provided date.
It is useful for retrieving products that haven't been modified since a specific date, which is essential for historical data analysis and reporting.
This filter uses the PIM products updated date and is only available on Catalogs endpoints.
updated_after
(string)
• Filter products that have been updated AFTER the provided date.
It is useful for retrieving only recently modified products, which is essential for synchronization and incremental data processing.
This filter uses the PIM products updated date and is only available on Catalogs endpoints.
Headers
Authorization
• Equal to 'Bearer xxx', 'xxx' being the App authentication token, see documentation for getting an app token
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return the paginated mapped products.
The response is paginated and includes links to navigate through the pages.
Only search_after pagination is used.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
_embedded
(object)
: {
items (array)
: [
{
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/catalogs/d259aecf-3ec1-4b07-ae0f-ce234b86c025/mapped-products?limit=4"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/catalogs/d259aecf-3ec1-4b07-ae0f-ce234b86c025/mapped-products?limit=4"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/catalogs/d259aecf-3ec1-4b07-ae0f-ce234b86c025/mapped-products?search_after=0e957ed4-fa44-48de-b6c7-7149d890fb3a&limit=4"
}
},
"_embedded": {
"items": [
{
"uuid": "04f47a54-8cc9-4c51-90e9-eb9aace0865f",
"title": "Canon Video Visualiser RE-455X",
"code": "sku-1234"
},
{
"uuid": "06dc8c5b-9e2f-4423-b9dd-31a3aaa0a048",
"title": "Trust Cuby Pro",
"code": "sku-1235"
},
{
"uuid": "0c3635f9-fedc-4bbd-96ab-856f69746b56",
"title": "Trust Urban Revolt",
"code": "sku-1236"
},
{
"uuid": "0e957ed4-fa44-48de-b6c7-7149d890fb3a",
"title": "Microsoft LifeCam Studio",
"code": "sku-1237"
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Get the list of mapped models related to a catalog
This endpoint allows you to get the list of models related to a catalog when the mapping is enabled with a models/variants schema. Please, note that a disabled catalog can return an HTTP 200 with a payload containing an error message, for more details see the App Catalog section.
REQUEST
get /api/rest/v1/catalogs/{id}/mapped-models
Path parameters
id
(string)
• This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
search_after
(string,
cursor to the first page
by default)
• 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 section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
updated_before
(string)
• Filter products that have been updated BEFORE the provided date.
It is useful for retrieving products that haven't been modified since a specific date, which is essential for historical data analysis and reporting.
This filter uses the PIM products updated date and is only available on Catalogs endpoints.
updated_after
(string)
• Filter products that have been updated AFTER the provided date.
It is useful for retrieving only recently modified products, which is essential for synchronization and incremental data processing.
This filter uses the PIM products updated date and is only available on Catalogs endpoints.
Headers
Authorization
• Equal to 'Bearer xxx', 'xxx' being the App authentication token, see documentation for getting an app token
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return the paginated mapped models.
The response is paginated and includes links to navigate through the pages.
Only search_after pagination is used.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
_embedded
(object)
: {
items (array)
: [
{
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/catalogs/232be0b2-093c-4591-a506-2a2ed5176721/mapped-models?limit=2"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/catalogs/232be0b2-093c-4591-a506-2a2ed5176721/mapped-models?limit=2"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/catalogs/232be0b2-093c-4591-a506-2a2ed5176721/mapped-models?search_after=tshirt_pim&limit=2"
}
},
"_embedded": {
"items": [
{
"code": "tshirt_akeneo",
"title": "Beautiful t-shirt with Akeneo logo",
"variants": "https://demo.akeneo.com/api/rest/v1/catalogs/232be0b2-093c-4591-a506-2a2ed5176721/mapped-models/tshirt_akeneo/variants",
"variation_axes": [
{
"code": "color",
"label": [
{
"locale": "en_US",
"value": "Color"
},
{
"locale": "fr_FR",
"value": "Couleur"
}
]
},
{
"code": "size",
"label": [
{
"locale": "en_US",
"value": "Size"
},
{
"locale": "fr_FR",
"value": "Taille"
}
]
}
]
},
{
"code": "tshirt_pim",
"title": "Beautiful t-shirt with PIM logo",
"variants": "https://demo.akeneo.com/api/rest/v1/catalogs/232be0b2-093c-4591-a506-2a2ed5176721/mapped-models/tshirt_pim/variants",
"variation_axes": [
{
"code": "color",
"label": [
{
"locale": "en_US",
"value": "Color"
},
{
"locale": "fr_FR",
"value": "Couleur"
}
]
},
{
"code": "size",
"label": [
{
"locale": "en_US",
"value": "Size"
},
{
"locale": "fr_FR",
"value": "Taille"
}
]
}
]
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Get the list of mapped variants of a model related to a catalog
This endpoint allows you to get the list of variants of a model related to a catalog when the mapping is enabled. Please, note that a disabled catalog can return an HTTP 200 with a payload containing an error message, for more details see the App Catalog section.
REQUEST
get /api/rest/v1/catalogs/{id}/mapped-models/{model_code}/variants
Path parameters
id
(string)
• This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
search_after
(string,
cursor to the first page
by default)
• 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 section for more details.
limit
(integer,
10
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
updated_before
(string)
• Filter products that have been updated BEFORE the provided date.
It is useful for retrieving products that haven't been modified since a specific date, which is essential for historical data analysis and reporting.
This filter uses the PIM products updated date and is only available on Catalogs endpoints.
updated_after
(string)
• Filter products that have been updated AFTER the provided date.
It is useful for retrieving only recently modified products, which is essential for synchronization and incremental data processing.
This filter uses the PIM products updated date and is only available on Catalogs endpoints.
Headers
Authorization
• Equal to 'Bearer xxx', 'xxx' being the App authentication token, see documentation for getting an app token
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return the paginated mapped variants.
The response is paginated and includes links to navigate through the pages.
Only search_after pagination is used.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
_embedded
(object)
: {
items (array)
: [
{
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/catalogs/232be0b2-093c-4591-a506-2a2ed5176721/mapped-models/tshirt_akeneo/variants?limit=2"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/catalogs/232be0b2-093c-4591-a506-2a2ed5176721/mapped-models/tshirt_akeneo/variants?limit=2"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/catalogs/232be0b2-093c-4591-a506-2a2ed5176721/mapped-models/tshirt_akeneo/variants?search_after=6b025a71-537f-48d4-aa26-a6617d6199e9&limit=100"
}
},
"_embedded": {
"items": [
{
"is_published": true,
"sku": "AK10BLXL",
"uuid": "6b025a71-537f-48d4-aa26-a6617d6199e9",
"variant_axes_values": [
{
"code": "color",
"label": [
{
"locale": "en_US",
"value": "Blue"
},
{
"locale": "fr_FR",
"value": "Bleu"
}
],
"value": "blue"
},
{
"code": "size",
"label": [
{
"locale": "en_US",
"value": "XL"
},
{
"locale": "fr_FR",
"value": "XL"
}
],
"value": "xl"
}
]
},
{
"is_published": true,
"sku": "AK10YEXL",
"uuid": "6b025a71-537f-48d4-aa26-a6617d6199e9",
"variant_axes_values": [
{
"code": "color",
"label": [
{
"locale": "en_US",
"value": "Yellow"
},
{
"locale": "fr_FR",
"value": "Jaune"
}
],
"value": "yellow"
},
{
"code": "size",
"label": [
{
"locale": "en_US",
"value": "XL"
},
{
"locale": "fr_FR",
"value": "XL"
}
],
"value": "xl"
}
]
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Mapping schema for products
Get the product mapping schema related to a catalog
This endpoint allows you to retrieve the product mapping schema related to a catalog.
REQUEST
get /api/rest/v1/catalogs/{id}/mapping-schemas/product
Path parameters
id
(string)
• This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', 'xxx' being the App authentication token, see documentation for getting an app token
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return product mapping schema related to a catalog
Body Format application/json
{
$id
(string)
• id of your schema
$schema
(string)
• $schema indicates which product mapping schema version your app uses
$comment
(string)
• allows you to add a comment
title
(string)
• allows you to add a title to your mapping schema
description
(string)
• allows you to add a description of your mapping schema
type
(string)
• should always be "object"
properties
(object)
• list and describe the targets your app expects
}
Example
{
"$id": "https://example.com/product",
"$schema": "https://api.akeneo.com/mapping/product/1.0.3/schema",
"type": "object",
"properties": {
"code": {
"title": "Model ID",
"type": "string"
},
"brand": {
"title": "Brand name",
"type": "string"
},
"description": {
"title": "Product description",
"type": "string"
},
"fabrics": {
"title": "Fabrics",
"type": "array",
"items": {
"type": "string"
}
},
"localized_names": {
"title": "Name with multiple locales",
"type": "array",
"items": {
"type": "object",
"properties": {
"locale": {
"type": "string"
},
"value": {
"type": "string"
}
},
"required": [
"locale",
"value"
]
}
},
"localized_number": {
"type": "array",
"items": {
"type": "object",
"properties": {
"locale": {
"type": "string"
},
"value": {
"type": "number"
}
},
"required": [
"locale",
"value"
]
}
},
"localized_link": {
"type": "array",
"items": {
"type": "object",
"properties": {
"locale": {
"type": "string"
},
"value": {
"type": "string",
"format": "uri"
}
},
"required": [
"locale",
"value"
]
}
},
"localized_datetime": {
"type": "array",
"items": {
"type": "object",
"properties": {
"locale": {
"type": "string"
},
"value": {
"type": "string",
"format": "date-time"
}
},
"required": [
"locale",
"value"
]
}
},
"localized_boolean": {
"type": "array",
"items": {
"type": "object",
"properties": {
"locale": {
"type": "string"
},
"value": {
"type": "boolean"
}
},
"required": [
"locale",
"value"
]
}
},
"variation_axes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"label": {
"type": "array",
"items": {
"type": "object",
"properties": {
"locale": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
}
}
},
"variants": {
"oneOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "array",
"items": {
"type": "object",
"properties": {
"variation_axes_values": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"value": {
"oneOf": [
{
"type": [
"string",
"boolean"
]
},
{
"type": "object",
"properties": {
"amount": {
"type": "number"
},
"unit": {
"type": "string"
}
}
}
]
},
"label": {
"type": "array",
"items": {
"type": "object",
"properties": {
"locale": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
}
}
},
"uuid": {
"title": "uuid",
"type": "string"
},
"sku": {
"title": "SKU",
"type": "string"
},
"position": {
"title": "Position",
"type": "number"
},
"price": {
"title": "Price",
"type": "string"
},
"response_time": {
"title": "Response time",
"type": "string"
},
"localized_product_photos_media_file": {
"title": "Photos with value per locale(links)",
"type": "array",
"items": {
"type": "object",
"properties": {
"locale": {
"type": "string"
},
"value": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
}
}
},
"required": [
"locale",
"value"
]
}
},
"localized_prices": {
"title": "Price in multiple currencies with value per locale",
"type": "array",
"items": {
"type": "object",
"properties": {
"locale": {
"type": "string"
},
"value": {
"type": "array",
"items": {
"type": "object",
"properties": {
"amount": {
"type": "number"
},
"currency": {
"type": "string"
}
},
"required": [
"amount",
"currency"
]
}
}
},
"required": [
"locale",
"value"
]
}
}
},
"required": [
"uuid"
]
}
}
]
}
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Create or update the product mapping schema related to a catalog
This endpoint allows you to create or update the product mapping schema related to a catalog. See documentation to define your JSON schema.
REQUEST
put /api/rest/v1/catalogs/{id}/mapping-schemas/product
Path parameters
id
(string)
• This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', 'xxx' being the App authentication token, see documentation for getting an app token
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
$id
(string)
• id of your schema
$schema
(string)
• $schema indicates which product mapping schema version your app uses
$comment
(string)
• allows you to add a comment
title
(string)
• allows you to add a title to your mapping schema
description
(string)
• allows you to add a description of your mapping schema
type
(string)
• should always be "object"
properties
(object)
• list and describe the targets your app expects
}
Example
{
"$id": "https://example.com/product",
"$schema": "https://api.akeneo.com/mapping/product/1.0.3/schema",
"type": "object",
"properties": {
"code": {
"title": "Model ID",
"type": "string"
},
"brand": {
"title": "Brand name",
"type": "string"
},
"description": {
"title": "Product description",
"type": "string"
},
"fabrics": {
"title": "Fabrics",
"type": "array",
"items": {
"type": "string"
}
},
"localized_names": {
"title": "Name with multiple locales",
"type": "array",
"items": {
"type": "object",
"properties": {
"locale": {
"type": "string"
},
"value": {
"type": "string"
}
},
"required": [
"locale",
"value"
]
}
},
"localized_number": {
"type": "array",
"items": {
"type": "object",
"properties": {
"locale": {
"type": "string"
},
"value": {
"type": "number"
}
},
"required": [
"locale",
"value"
]
}
},
"localized_link": {
"type": "array",
"items": {
"type": "object",
"properties": {
"locale": {
"type": "string"
},
"value": {
"type": "string",
"format": "uri"
}
},
"required": [
"locale",
"value"
]
}
},
"localized_datetime": {
"type": "array",
"items": {
"type": "object",
"properties": {
"locale": {
"type": "string"
},
"value": {
"type": "string",
"format": "date-time"
}
},
"required": [
"locale",
"value"
]
}
},
"localized_boolean": {
"type": "array",
"items": {
"type": "object",
"properties": {
"locale": {
"type": "string"
},
"value": {
"type": "boolean"
}
},
"required": [
"locale",
"value"
]
}
},
"variation_axes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"label": {
"type": "array",
"items": {
"type": "object",
"properties": {
"locale": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
}
}
},
"variants": {
"oneOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "array",
"items": {
"type": "object",
"properties": {
"variation_axes_values": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"value": {
"oneOf": [
{
"type": [
"string",
"boolean"
]
},
{
"type": "object",
"properties": {
"amount": {
"type": "number"
},
"unit": {
"type": "string"
}
}
}
]
},
"label": {
"type": "array",
"items": {
"type": "object",
"properties": {
"locale": {
"type": "string"
},
"value": {
"type": "string"
}
}
}
}
}
}
},
"uuid": {
"title": "uuid",
"type": "string"
},
"sku": {
"title": "SKU",
"type": "string"
},
"position": {
"title": "Position",
"type": "number"
},
"price": {
"title": "Price",
"type": "string"
},
"response_time": {
"title": "Response time",
"type": "string"
},
"localized_product_photos_media_file": {
"title": "Photos with value per locale(links)",
"type": "array",
"items": {
"type": "object",
"properties": {
"locale": {
"type": "string"
},
"value": {
"type": "array",
"items": {
"type": "string",
"format": "uri"
}
}
},
"required": [
"locale",
"value"
]
}
},
"localized_prices": {
"title": "Price in multiple currencies with value per locale",
"type": "array",
"items": {
"type": "object",
"properties": {
"locale": {
"type": "string"
},
"value": {
"type": "array",
"items": {
"type": "object",
"properties": {
"amount": {
"type": "number"
},
"currency": {
"type": "string"
}
},
"required": [
"amount",
"currency"
]
}
}
},
"required": [
"locale",
"value"
]
}
}
},
"required": [
"uuid"
]
}
}
]
}
}
}RESPONSES
Successfully created or updated product mapping schema, empty response body
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 422,
"message": "Validation failed."
}Delete the product mapping schema related to a catalog
This endpoint allows you to delete the product mapping schema related to a catalog
REQUEST
delete /api/rest/v1/catalogs/{id}/mapping-schemas/product
Path parameters
id
(string)
• This path parameter is used to specify the unique identifier of the catalog you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the catalog ID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', 'xxx' being the App authentication token, see documentation for getting an app token
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
No content to return. Means that the deletion was successful.
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Utilities
Overview
Get list of all endpoints
This endpoint allows you to get the list of all the available endpoints. No need to be authenticated to use this endpoint.
REQUEST
get /api/rest/v1
Path parameters
Ø
Query parameters
Ø
Headers
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return the list of all available endpoints
Body Format application/json
{
host
(string)
• Host name
authentication
(object)
• Endpoint to get the authentication token
routes
(object)
• All the available endpoints
}
Example
{
"host": "https://demo.akeneo.com",
"authentication": {
"fos_oauth_server_token": {
"route": "/api/oauth/v1/token",
"methods": [
"POST"
]
}
},
"routes": {
"pim_api_attribute_list": {
"route": "/api/rest/v1/attributes",
"methods": [
"GET"
]
},
"pim_api_attribute_create": {
"route": "/api/rest/v1/attributes",
"methods": [
"POST"
]
},
"pim_api_attribute_partial_update": {
"route": "/api/rest/v1/attributes/{code}",
"methods": [
"PATCH"
]
},
"pim_api_attribute_get": {
"route": "/api/rest/v1/attributes/{code}",
"methods": [
"GET"
]
},
"pim_api_attribute_partial_update_list": {
"route": "/api/rest/v1/attributes",
"methods": [
"PATCH"
]
},
"pim_api_category_list": {
"route": "/api/rest/v1/categories",
"methods": [
"GET"
]
},
"pim_api_product_partial_update": {
"route": "/api/rest/v1/products/{code}",
"methods": [
"PATCH"
]
},
"pim_api_product_delete": {
"route": "/api/rest/v1/products/{code}",
"methods": [
"DELETE"
]
},
"pim_api_product_uuid_create": {
"route": "/api/rest/v1/products-uuid",
"methods": [
"POST"
]
},
"pim_api_channel_list": {
"route": "/api/rest/v1/channels",
"methods": [
"GET"
]
},
"akeneo_catalogs_public_get_catalogs": {
"route": "/api/rest/v1/catalogs",
"methods": [
"GET"
]
},
"akeneo_asset_manager_assets_rest_connector_create_or_update": {
"route": "/api/rest/v1/asset-families/{asset_family_code}/assets",
"methods": [
"PATCH"
]
},
"pim_api_locale_list": {
"route": "/api/rest/v1/locales",
"methods": [
"GET"
]
},
"pim_analytics_external_api_system_info_get": {
"route": "/api/rest/v1/system-information",
"methods": [
"GET"
]
}
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Authentication
Get an authentication token
This endpoint allows you to get an authentication token. No need to be authenticated to use this endpoint. Want to get your token directly in the API reference? Check the Get your API token guide.
REQUEST
post /api/oauth/v1/token
Path parameters
Ø
Query parameters
Ø
Headers
Content-Type
• This header indicates the media type of the resource being sent to the server.
It is used to specify the format of the request body, allowing the server to correctly interpret the data being sent.
Equal to 'application/json' or 'application/x-www-form-urlencoded', no other value allowed.
Authorization
• This header is used to authenticate requests to the API.
Equal to 'Basic xx', where 'xx' is the base 64 encoding of the client id and secret.
Find out how to generate them in the Client ID/secret generation section.
Body
RESPONSES
Return an authentication token
Body Format application/json
{
access_token
(string)
• Authentication token that should be given in every authenticated request to the API
expires_in
(integer)
• Validity of the token given in seconds, 3600s = 1h by default
token_type
(string)
• Token type, always equal to bearer
scope
(string,null)
• Unused, always equal to null
refresh_token
(string)
• Use this token when your access token has expired.
See.
}
Example
{
"access_token": "ZTZmYjU4ZmQxZWNmMzk1M2NlYzA5NmFhNmIzVjExMzE4NmJmODBkZGIyYTliYmQyNjk2ZDQwZThmNjdiZDQzOQ",
"expires_in": 3600,
"token_type": "bearer",
"scope": null,
"refresh_token": "M3FlODI0OTE3ODMyNjViMzRiOWE5ODMyNWViMThkNDU5YzJjNjFiZjNkZWFjMzIyYjc4YTgzZWY1MjE5ZTY5Mw"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}This response indicates that the validation of the entity given in the body of the request failed. It occurs when the data provided does not meet the required format or constraints defined by the API, and includes a link to the documentation for reference.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
Example
{
"code": 422,
"message": "Property \\\"labels\\\" expects an array as data, \\\"NULL\\\" given. Check the API reference documentation.",
"_links": {
"documentation": {
"href": "http://api.akeneo.com/api-reference.html"
}
}
}System
Get system information
This endpoint allows you to get the version and the edition of the PIM
REQUEST
get /api/rest/v1/system-information
Path parameters
Ø
Query parameters
Ø
Headers
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Return the version and the edition of the PIM
Body Format application/json
{
version
(string)
• Version of the PIM
edition
(string)
• Edition of the PIM
}
Example
{
"version": "v20250717143807",
"edition": "Serenity"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Extensions
UI Extensions
List UI extensions
List all UI extensions associated with your token
REQUEST
get /api/rest/v1/ui-extensions
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the list of extensions
Body Format application/json
[
{
name
(string)
• Name of the extension, shown within the Administration interface
description
(string)
• Short description, shown within the Administration interface
version
(string)
• Version of the extension, shown within the Administration
interface
position
(string)
• Position of the UI extension
type
(string)
• Type of the UI extension
configuration
(object)
: {
default_label (string)
• Default label, used if there is no translation for the PIM user locale
labels (object)
• Label translations
secret (string)
• Shows REDACTED if a secret is registered for the extension
url (string)
• Destination URL of the extension
}
status
(string)
• Status of the UI extension (active or inactive)
credentials
(array [object])
: [
{
type (string) • Type of credentials
value (object) • Custom header credentials
}
]
}
]
Example
[
{
"uuid": "d414135b-ff4d-44e1-8cb6-fce64cbe29c0",
"name": "my_awesome_iframe_extension",
"type": "iframe",
"position": "pim.product.tab",
"configuration": {
"url": "https://www.example.com",
"labels": {
"en_US": "My awesome iframe extension",
"fr_FR": "Ma super iframe extension"
},
"default_label": "My awesome iframe extension"
},
"status": "active",
"version": "V1.02.3",
"description": "A short human readable description."
},
{
"uuid": "64c683bd-452b-4609-b957-c586ff6b0999",
"name": "my_other_iframe_extension",
"type": "iframe",
"position": "pim.product.tab",
"configuration": {
"url": "https://www.example2.com",
"labels": {
"en_US": "My other iframe extension",
"fr_FR": "Mon autre iframe extension"
},
"default_label": "My other link extension"
},
"status": "active",
"version": "V0.1.0",
"description": "A short human readable description."
}
]Create a new UI extension
This endpoint allows you to create a new UI extension.
default_label and url configuration fields are mandatory for all UI extensions.
secret is optional and only available for action UI extension.
REQUEST
post /api/rest/v1/ui-extensions
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
name
(string)
• Name of the extension, shown within the Administration interface
description
(string)
• Short description, shown within the Administration interface
version
(string)
• Version of the extension, shown within the Administration
interface
position
(string)
• Position of the UI extension
type
(string)
• Type of the UI extension
configuration
(object)
: {
default_label
(string)
• Default label, used if there is no translation for the PIM user locale
labels
(object)
• Label translations
secret
(string)
• Shows REDACTED if a secret is registered for the extension
url
(string)
• Destination URL of the extension
}
status
(string)
• Status of the UI extension (active or inactive)
credentials
(array[object])
: [
{
type (string) • Type of credentials
value (object) • Custom header credentials
}
]
}
Example
{
"name": "my_awesome_button_extension",
"type": "iframe",
"position": "pim.product.tab",
"configuration": {
"url": "https://www.example.com",
"secret": "UOL2EHjh7P0nGNUV8RwDMBclyMwe4c5IA",
"labels": {
"en_US": "My awesome link extension",
"fr_FR": "Ma super link extension"
},
"default_label": "My awesome link extension"
},
"version": "V1.02.3",
"description": "A short human readable description."
}RESPONSES
Creation successfully applied. Returns a JSON document representing the UI extension created.
Body Format application/json
{
name
(string)
• Name of the extension, shown within the Administration interface
description
(string)
• Short description, shown within the Administration interface
version
(string)
• Version of the extension, shown within the Administration
interface
position
(string)
• Position of the UI extension
type
(string)
• Type of the UI extension
configuration
(object)
: {
default_label
(string)
• Default label, used if there is no translation for the PIM user locale
labels
(object)
• Label translations
secret
(string)
• Shows REDACTED if a secret is registered for the extension
url
(string)
• Destination URL of the extension
}
status
(string)
• Status of the UI extension (active or inactive)
credentials
(array [object])
: [
{
type (string) • Type of credentials
value (object) • Custom header credentials
}
]
}
Example
{
"uuid": "d414135b-ff4d-44e1-8cb6-fce64cbe29c0",
"name": "my_awesome_iframe_extension",
"type": "iframe",
"position": "pim.product.tab",
"configuration": {
"url": "https://www.example.com",
"labels": {
"en_US": "My awesome iframe extension",
"fr_FR": "Ma super iframe extension"
},
"default_label": "My awesome iframe extension"
},
"status": "active",
"credentials": [],
"version": "V1.02.3",
"description": "A short human readable 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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Update a UI extension
This endpoint allows you to update an existing UI extension. You can send only the fields that you want to update. If a field is not sent, the previous value is kept. This endpoint is also available as POST, prefer the POST if you need to upload a file.
REQUEST
patch /api/rest/v1/ui-extensions/{uuid}
Path parameters
uuid
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the UUID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
name
(string)
• Name of the extension, shown within the Administration interface
description
(string)
• Short description, shown within the Administration interface
version
(string)
• Version of the extension, shown within the Administration
interface
position
(string)
• Position of the UI extension
type
(string)
• Type of the UI extension
configuration
(object)
: {
default_label
(string)
• Default label, used if there is no translation for the PIM user locale
labels
(object)
• Label translations
secret
(string)
• Shows REDACTED if a secret is registered for the extension
url
(string)
• Destination URL of the extension
}
status
(string)
• Status of the UI extension (active or inactive)
credentials
(array[object])
: [
{
type (string) • Type of credentials
value (object) • Custom header credentials
}
]
}
Example
{
"type": "link",
"position": "pim.product.header",
"version": "V1.02.4"
}RESPONSES
Changes applied successfully. Returns a JSON document representing the UI extension updated.
Body Format application/json
{
name
(string)
• Name of the extension, shown within the Administration interface
description
(string)
• Short description, shown within the Administration interface
version
(string)
• Version of the extension, shown within the Administration
interface
position
(string)
• Position of the UI extension
type
(string)
• Type of the UI extension
configuration
(object)
: {
default_label
(string)
• Default label, used if there is no translation for the PIM user locale
labels
(object)
• Label translations
secret
(string)
• Shows REDACTED if a secret is registered for the extension
url
(string)
• Destination URL of the extension
}
status
(string)
• Status of the UI extension (active or inactive)
credentials
(array [object])
: [
{
type (string) • Type of credentials
value (object) • Custom header credentials
}
]
}
Example
{
"uuid": "d414135b-ff4d-44e1-8cb6-fce64cbe29c0",
"name": "my_awesome_iframe_extension",
"type": "iframe",
"position": "pim.product.tab",
"configuration": {
"url": "https://www.example.com",
"labels": {
"en_US": "My awesome iframe extension",
"fr_FR": "Ma super iframe extension"
},
"default_label": "My awesome iframe extension"
},
"status": "active",
"credentials": [],
"version": "V1.02.3",
"description": "A short human readable 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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
errors
(array [object])
: [
{
property (string) • Name of the invalid property
message (string) • Human-readable error message
attribute (string,null) • Attribute code (if the error is on an attribute)
locale (string,null) • Locale code involved in the error, if any
scope (string,null) • Channel code involved in the error, if any
}
]
_links
(object)
: {
documentation
(object)
: {
href
(string)
•
}
}
}
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"
}
}
}Delete a UI extension
This endpoint allows you to delete a given UI extension
REQUEST
delete /api/rest/v1/ui-extensions/{uuid}
Path parameters
uuid
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the UUID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
No content to return. Means that the deletion was successful.
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}Workflows
Workflows
Get list of workflows
Retrieves a paginated list of workflows
REQUEST
get /api/rest/v1/workflows
Path parameters
Ø
Query parameters
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
limit
(integer,
100
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Paginated list of workflows. The response is paginated and includes links to navigate through the pages.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
}
uuid (string)
• Workflow UUID
code (string)
• Workflow code
labels (object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$} (string,null)
• Label for locale
}
enabled (boolean)
• Whether the workflow is enabled
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/workflows?page=1"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/workflows?page=1"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/workflows?page=2"
}
},
"current_page": 1,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/workflows/6f37476a-04c2-46c0-b6d0-e18316959068"
}
},
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"enabled": true,
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
}
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/workflows/a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
},
"uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
"code": "translation_workflow",
"enabled": false,
"labels": {
"en_US": "Translation workflow",
"fr_FR": "Workflow de traduction"
}
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}Get a workflow
This endpoint allows you to get the information about a given workflow as well as its steps
REQUEST
get /api/rest/v1/workflows/{uuid}
Path parameters
uuid
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the UUID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Returns the content of the workflow in JSON standard format
Body Format application/json
{
uuid
(string)
• Workflow UUID
code
(string)
• Workflow code
labels
(object)
: {
{^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$}
(string,null)
• Workflow labels per locale
}
enabled
(boolean)
• Whether the workflow is enabled
steps
(array [object])
: [
{
uuid (string) • Step UUID
code (string) • Step code
type (string) • Step type (e.g. enrichment, review)
labels (object) • Locale code
descriptions (object) • Locale code
allotted_time (object,null) • Allotted time for the step (e.g. {"value": 1, "unit": "days"} or nullable)
channels_and_locales (object) • Step configuration for channels and locales
}
]
}
Example
{
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068",
"code": "enrichment_workflow",
"labels": {
"en_US": "Enrichment workflow",
"fr_FR": "Workflow d'enrichissement"
},
"enabled": true,
"steps": [
{
"uuid": "f626d0e5-84a5-41fc-8215-65508c253edb",
"code": "marketing_enrichment",
"type": "enrichment",
"labels": {
"en_US": "Marketing enrichment",
"fr_FR": "Enrichissement marketing"
},
"descriptions": {
"en_US": "Enrich marketing attributes"
},
"allotted_time": {
"value": 3,
"unit": "days"
},
"channels_and_locales": {
"ecommerce": [
"en_US"
],
"mobile": [
"en_US",
"fr_FR"
]
}
},
{
"uuid": "b2c1f3d4-5e6a-4c8b-9f0e-2d3e4f5a6b7c",
"code": "marketing_review",
"type": "review",
"labels": {},
"descriptions": {},
"allotted_time": null,
"channels_and_locales": {
"ecommerce": [
"en_US"
]
}
}
]
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 404,
"message": "Resource `my_resource_code` does not exist."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Get list of workflow step assignees
Retrieves a paginated list of assignees for a specified workflow step
REQUEST
get /api/rest/v1/workflows/steps/{uuid}/assignees
Path parameters
uuid
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the UUID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
limit
(integer,
100
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Paginated list of assignees for a specified workflow step. The response is paginated and includes links to navigate through the pages.
Body Format application/json
{
current_page
(integer)
• Current page number
_embedded
(object)
: {
items
(array[object])
: [
{
uuid (string
)
• Assignee UUID
first_name (string
)
• Assignee first name
last_name (string
)
• Assignee last name
email (string
)
• Assignee email address
}
]
}
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/workflows/steps/f626d0e5-84a5-41fc-8215-65508c253edb/assignees?page=1&limit=10"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/workflows/steps/f626d0e5-84a5-41fc-8215-65508c253edb/assignees?page=1&limit=10"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/workflows/steps/f626d0e5-84a5-41fc-8215-65508c253edb/assignees?page=2&limit=10"
}
},
"current_page": 1,
"_embedded": {
"items": [
{
"uuid": "25566245-55c3-42ce-86d9-8610ac459fa8",
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com"
},
{
"uuid": "be6354b0-4545-4aaa-882d-aa14be68642c",
"first_name": "Julia",
"last_name": "Stark",
"email": "julia@example.com"
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Workflow executions
Start several workflow executions
This endpoint allows you to start workflow executions for products and/or product models
REQUEST
post /api/rest/v1/workflows/executions
Path parameters
Ø
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
Example
[
{
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068"
},
"product": {
"uuid": "87654321-4321-4321-4321-210987654321"
}
},
{
"workflow": {
"uuid": "6f37476a-04c2-46c0-b6d0-e18316959068"
},
"product_model": {
"code": "model_1234"
}
}
]RESPONSES
Workflow execution started successfully. All elements have been processed.
Body Format application/json
Ø
Multi-status response. Workflow execution started with some errors.
Body Format application/json
{
code
(integer)
•
message
(string)
•
processed
(integer)
• Number of successfully processed elements
errors
(array [object])
: [
{
index (integer) • Index of the failed element in the request array
message (string) • Error message
}
]
}
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 406,
"message": "xxx in `Accept` header is not valid. Only `application/json` is allowed."
}Workflow tasks
Get list of workflow tasks
Retrieves a paginated list of tasks for a specified workflow step
REQUEST
get /api/rest/v1/workflows/tasks
Path parameters
Ø
Query parameters
search
(string)
• Stringified JSON to filter tasks.
For more details see the Filters section.
with_attributes
(boolean)
• Whether to include task attributes in the response
page
(integer,
1
by default)
• Specify which page of results to retrieve when using pagination.
It is useful for navigating through large datasets by breaking them into smaller, manageable pages.
See Pagination section for more details.
limit
(integer,
100
by default)
• Specify the maximum number of results to return per page.
It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets.
See Pagination section for more details.
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Accept • Equal to 'application/json', no other value allowed
Body
Ø
RESPONSES
Paginated list of tasks for a specified workflow step. The response is paginated and includes links to navigate through the pages.
Body Format application/json
{
_links
(object)
: {
self (object)
: {
href (string) • URI of the current page of resources
}
first (object)
: {
href (string) • URI of the first page of resources
}
previous (object)
: {
href (string) • URI of the previous page of resources
}
next (object)
: {
href (string) • URI of the next page of resources
}
}
current_page
(integer)
• Current page number
_embedded
(object)
: {
items (array)
: [
{
_links (object)
: {
self (object)
: {
href
(string) • URI of the resource
}
edit (object)
: {
href
(string) • URL to access the task in Akeneo
}
}
uuid (string)
• Task UUID
status (string)
• Task status
created_at (string)
• Task creation date
product (object)
: {
uuid (string)
• Product UUID
}
product_model (object)
: {
code (string)
• Product model code
}
due_date (string,null)
• Due date
rejected (boolean)
• Whether the task is rejected
pending_attributes (object)
• Object of attributes for the task that are awaiting completion or require user input.
Each key is an attribute code and each value is an array of objects with information on locale, scope, rejection status and comment.
This field is only included when with_attributes=true.
}
]
}
}
Example
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/workflows/tasks?search={\"step_uuid\":[{\"operator\":\"=\",\"value\":\"0a2c9f49-2b4f-42a5-b7f9-6c50f6bce8e9\"}]}&page=1&limit=10"
},
"first": {
"href": "https://demo.akeneo.com/api/rest/v1/workflows/tasks?search={\"step_uuid\":[{\"operator\":\"=\",\"value\":\"0a2c9f49-2b4f-42a5-b7f9-6c50f6bce8e9\"}]}&page=1&limit=10"
},
"next": {
"href": "https://demo.akeneo.com/api/rest/v1/workflows/tasks?search={\"step_uuid\":[{\"operator\":\"=\",\"value\":\"0a2c9f49-2b4f-42a5-b7f9-6c50f6bce8e9\"}]}&page=2&limit=10"
}
},
"current_page": 1,
"_embedded": {
"items": [
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/workflows/tasks/8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07"
},
"edit": {
"href": "https://demo.akeneo.com/public/workflows/tasks/8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07/edit"
}
},
"uuid": "8f6c2d18-fbd4-4f7e-81df-cb3dc368fe07",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"product": {
"uuid": "7108ee60-a1ea-4fe1-baca-b39909e23d24"
},
"due_date": "2024-03-31T18:00:00Z",
"rejected": true
},
{
"_links": {
"self": {
"href": "https://demo.akeneo.com/api/rest/v1/workflows/tasks/782dd26a-b58d-40d3-a8e2-c41bb342f20f"
},
"edit": {
"href": "https://demo.akeneo.com/public/workflows/tasks/782dd26a-b58d-40d3-a8e2-c41bb342f20f/edit"
}
},
"uuid": "782dd26a-b58d-40d3-a8e2-c41bb342f20f",
"status": "in_progress",
"created_at": "2024-02-22T17:31:00Z",
"product_model": {
"code": "a-product-model-code"
},
"due_date": "2024-03-28T18:00:00Z",
"rejected": false
}
]
}
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}Update a Workflow Task's Status (Approve, Reject, Complete)
Completes or approves/rejects a task. The request body's structure depends on the action being performed.
- To approve a 'review' task, set status to
approved. - To complete an 'enrichment' task, set status to
completed. - To reject a 'review' task, set status to
rejected, providesend_back_to_step_uuid, and optionally providerejected_attributesto specify details about rejected attributes.
REQUEST
patch /api/rest/v1/workflows/tasks/{uuid}
Path parameters
uuid
(string)
• This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the UUID is correctly formatted and corresponds to an existing entity in the system.
Query parameters
Ø
Headers
Authorization
• Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section
Content-type
• Equal to 'application/json', no other value allowed
Body
Follow the standard format of the entity
{
status
(string)
• Must be 'rejected' for this action
send_back_to_step_uuid
(string)
• The UUID of the workflow step to which the task should be returned
rejected_attributes
(object)
• Optionally provides details about which attributes were rejected.
For each attribute name you can specify a comment, the locale, and the scope for the rejection.
}
Example
{
"status": "rejected",
"send_back_to_step_uuid": "123e4567-e89b-12d3-a456-426614174000",
"rejected_attributes": {
"name": [
{
"comment": "",
"locale": null,
"scope": null
}
],
"description": [
{
"comment": "Wrong description",
"locale": "en_US",
"scope": "ecommerce"
},
{
"comment": "",
"locale": "fr_FR",
"scope": "mobile"
}
]
}
}RESPONSES
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 • URI of the updated resource
Body Format application/json
Ø
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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 400,
"message": "Invalid JSON message received"
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 401,
"message": "Authentication is required"
}This response indicates that the user does not have the permission to execute this request. It can occur when the user tries to access a resource or perform an action that they are not authorized to do.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 403,
"message": "Access forbidden. You are not allowed to list this entity."
}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.
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Message explaining the error
}
Example
{
"code": 415,
"message": "xxx in `Content-type` header is not valid. Only `application/json` is allowed.\""
}Unprocessable entity
Body Format application/json
{
code
(integer)
• HTTP status code
message
(string)
• Description of the validation error
}
Example
{
"code": 422,
"message": "Cannot update task, provided status is not supported."
}