API reference

Complete reference on how to handle Akeneo PIM resources

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 availables endpoints

}

Example

{
  "host": "https://demo.akeneo.com",
  "authentication": {
    "fos_oauth_server_token": {
      "route": "/api/oauth/v1/token",
      "methods": [
        "POST"
      ]
    }
  },
  "routes": {
    "pim_api_category_list": {
      "route": "/api/rest/v1/categories",
      "methods": [
        "GET"
      ]
    },
    "pim_api_category_get": {
      "route": "/api/rest/v1/categories/{code}",
      "methods": [
        "GET"
      ]
    },
    "pim_api_category_create": {
      "route": "/api/rest/v1/categories",
      "methods": [
        "POST"
      ]
    },
    "pim_api_category_partial_update": {
      "route": "/api/rest/v1/categories/{code}",
      "methods": [
        "PATCH"
      ]
    },
    "pim_api_category_partial_update_list": {
      "route": "/api/rest/v1/categories",
      "methods": [
        "PATCH"
      ]
    },
    "pim_api_family_list": {
      "route": "/api/rest/v1/families",
      "methods": [
        "GET"
      ]
    },
    "pim_api_family_get": {
      "route": "/api/rest/v1/families/{code}",
      "methods": [
        "GET"
      ]
    },
    "pim_api_family_create": {
      "route": "/api/rest/v1/families",
      "methods": [
        "POST"
      ]
    },
    "pim_api_family_partial_update": {
      "route": "/api/rest/v1/families/{code}",
      "methods": [
        "PATCH"
      ]
    },
    "pim_api_family_partial_update_list": {
      "route": "/api/rest/v1/families",
      "methods": [
        "PATCH"
      ]
    },
    "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_attribute_option_list": {
      "route": "/api/rest/v1/attributes/{attributeCode}/options",
      "methods": [
        "GET"
      ]
    },
    "pim_api_attribute_option_create": {
      "route": "/api/rest/v1/attributes/{attributeCode}/options",
      "methods": [
        "POST"
      ]
    },
    "pim_api_attribute_option_partial_update": {
      "route": "/api/rest/v1/attributes/{attributeCode}/options/{optionCode}",
      "methods": [
        "PATCH"
      ]
    },
    "pim_api_attribute_option_get": {
      "route": "/api/rest/v1/attributes/{attributeCode}/options/{code}",
      "methods": [
        "GET"
      ]
    },
    "pim_api_attribute_group_list": {
      "route": "/api/rest/v1/attribute-groups",
      "methods": [
        "GET"
      ]
    },
    "pim_api_attribute_group_get": {
      "route": "/api/rest/v1/attribute-groups/{code}",
      "methods": [
        "GET"
      ]
    },
    "pim_api_channel_list": {
      "route": "/api/rest/v1/channels",
      "methods": [
        "GET"
      ]
    },
    "pim_api_channel_get": {
      "route": "/api/rest/v1/channels/{code}",
      "methods": [
        "GET"
      ]
    },
    "pim_api_locale_list": {
      "route": "/api/rest/v1/locales",
      "methods": [
        "GET"
      ]
    },
    "pim_api_locale_get": {
      "route": "/api/rest/v1/locales/{code}",
      "methods": [
        "GET"
      ]
    },
    "pim_api_product_list": {
      "route": "/api/rest/v1/products",
      "methods": [
        "GET"
      ]
    },
    "pim_api_product_get": {
      "route": "/api/rest/v1/products/{code}",
      "methods": [
        "GET"
      ]
    },
    "pim_api_product_create": {
      "route": "/api/rest/v1/products",
      "methods": [
        "POST"
      ]
    },
    "pim_api_product_partial_update": {
      "route": "/api/rest/v1/products/{code}",
      "methods": [
        "PATCH"
      ]
    },
    "pim_api_product_partial_update_list": {
      "route": "/api/rest/v1/products",
      "methods": [
        "PATCH"
      ]
    },
    "pim_api_product_delete": {
      "route": "/api/rest/v1/products/{code}",
      "methods": [
        "DELETE"
      ]
    },
    "pim_api_media_file_list": {
      "route": "/api/rest/v1/media-files",
      "methods": [
        "GET"
      ]
    },
    "pim_api_media_file_download": {
      "route": "/api/rest/v1/media-files/{code}/download",
      "methods": [
        "GET"
      ]
    },
    "pim_api_media_file_get": {
      "route": "/api/rest/v1/media-files/{code}",
      "methods": [
        "GET"
      ]
    },
    "pim_api_media_file_create": {
      "route": "/api/rest/v1/media-files",
      "methods": [
        "POST"
      ]
    }
  }
}

Not Acceptable

The `Accept` header is not `application/json` but it should

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."
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Authentication

Get authentication token

This endpoint allows you to get an authentication token. No need to be authenticated to use this endpoint.

REQUEST

post /api/oauth/v1/token

Path parameters

Ø

Query parameters

Ø

Headers

Authorization • 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 Create an OAuth client section.

Content-type • Equal to 'application/json', no other value allowed

Body

Follow the standard format of the entity

{

username (string ) • Your PIM username

password (string ) • Your PIM password

grant_type (string ) • Always equal to "password"

}

Example

{
  "username": "admin",
  "password": "admin",
  "grant_type": "password"
}

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 ) • Unused, always equal to "null"

refresh_token (string ) • Use this token when your access token has expired. See Refresh an expired token section for more details.

}

Example

{
  "access_token": "ZTZmYjU4ZmQxZWNmMzk1M2NlYzA5NmFhNmIzVjExMzE4NmJmODBkZGIyYTliYmQyNjk2ZDQwZThmNjdiZDQzOQ",
  "expires_in": 3600,
  "token_type": "bearer",
  "scope": null,
  "refresh_token": "M2FlODI0OTE3ODMyNjViMzRiOWE5ODMyNWViMThkNDU5YzJjNjFiZjNkZWFjMzIyYjc4YTgzZWY1MjE5ZTY5Mw"
}

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 400,
  "message": "Invalid JSON message received"
}

Unsupported Media type

The `Content-type` header has to be `application/json`

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 validation of the entity given in the body of the request failed

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

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"
    }
  }
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Products

Get list of products

This endpoint allows you to get a list of products. Products are paginated and they can be filtered.

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, for more details see the Filter on product values 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 on product values section

attributes (string ) • Filter product values to only return those concerning the given attributes, for more details see the Filter on product values section

pagination_type (string , page by default ) • Pagination method type, see Pagination section

page (integer , 1 by default ) • Number of the page to retrieve when using the `page` pagination method type. Should never be set manually, see Pagination section

search_after (string , cursor to the first page by default ) • Cursor when using the `search_after` pagination method type. Should never be set manually, see Pagination section

limit (integer , 10 by default ) • Number of results by page, see Pagination section

with_count (boolean ) • Return the count of products in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way

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 products paginated

Body Format application/json

Follow the standard format of the entity

{

_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
              }
          }
          identifier (string) • Product identifier, i.e. the value of the only `pim_catalog_identifier` attribute
          enabled (boolean) • Whether the product is enable
          family (string) • Family code from which the product inherits its attributes and attributes requirements
          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
          variant_group (string) • Code of the variant group in which the product is
          values (object) : {
              attributeCode (array [object ]) : [
                  {
                    scope (string ) • Channel code of the product value
                    locale (string ) • Locale code of the product value
                    data (object ) • Product value
                   }
              ]
          }
          associations (object) : {
              associationTypeCode (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
              }
          }
          created (string) • Date of creation
          updated (string) • Date of the last update
        }
    ]
}

}

Example

{
  "_links": {
    "self": {
      "href": "https://demo.akeneo.com/api/rest/v1/products?page=3&limit=3"
    },
    "first": {
      "href": "https://demo.akeneo.com/api/rest/v1/products?page=1&limit=3"
    },
    "previous": {
      "href": "https://demo.akeneo.com/api/rest/v1/products?page=2&limit=3"
    },
    "next": {
      "href": "https://demo.akeneo.com/api/rest/v1/products?page=4&limit=3"
    }
  },
  "current_page": 3,
  "_embedded": {
    "_items": [
      {
        "_links": {
          "self": {
            "href": "https://demo.akeneo.com/api/rest/v1/product/top"
          }
        },
        "identifier": "top",
        "family": "tshirt",
        "groups": [],
        "variant_group": null,
        "categories": [
          "summer_collection"
        ],
        "enabled": true,
        "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": [
            {
              "locale": null,
              "scope": null,
              "data": [
                {
                  "amount": "15.5",
                  "currency": "EUR"
                },
                {
                  "amount": "15",
                  "currency": "USD"
                }
              ]
            }
          ],
          "color": [
            {
              "locale": null,
              "scope": null,
              "data": "black"
            }
          ],
          "size": [
            {
              "locale": null,
              "scope": null,
              "data": "m"
            }
          ]
        },
        "created": "2016-06-23T18:24:44+02:00",
        "updated": "2016-06-25T17:56:12+02:00",
        "associations": {
          "PACK": {
            "products": [
              "sunglasses"
            ],
            "groups": []
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "https://demo.akeneo.com/api/rest/v1/product/cap"
          }
        },
        "identifier": "cap",
        "family": "caps",
        "groups": [],
        "variant_group": null,
        "categories": [
          "summer_collection"
        ],
        "enabled": true,
        "values": {
          "name": [
            {
              "data": "Cap",
              "locale": "en_US",
              "scope": null
            },
            {
              "data": "Casquette",
              "locale": "fr_FR",
              "scope": null
            }
          ],
          "description": [
            {
              "data": "Cap unisex",
              "locale": "en_US",
              "scope": "ecommerce"
            },
            {
              "data": "Cap unisex",
              "locale": "en_US",
              "scope": "tablet"
            },
            {
              "data": "Casquette unisexe",
              "locale": "fr_FR",
              "scope": "ecommerce"
            },
            {
              "data": "Casquette unisexe",
              "locale": "fr_FR",
              "scope": "tablet"
            }
          ],
          "price": [
            {
              "locale": null,
              "scope": null,
              "data": [
                {
                  "amount": "20",
                  "currency": "EUR"
                },
                {
                  "amount": "20",
                  "currency": "USD"
                }
              ]
            }
          ],
          "color": [
            {
              "locale": null,
              "scope": null,
              "data": "black"
            }
          ]
        },
        "created": "2016-06-23T18:24:44+02:00",
        "updated": "2016-06-25T17:56:12+02:00",
        "associations": {
          "PACK": {
            "products": [
              "sunglasses"
            ],
            "groups": []
          }
        }
      },
      {
        "_links": {
          "self": {
            "href": "https://demo.akeneo.com/api/rest/v1/product/sweat"
          }
        },
        "identifier": "sweat",
        "family": null,
        "groups": [],
        "variant_group": null,
        "categories": [
          "winter_collection"
        ],
        "enabled": true,
        "values": {},
        "created": "2016-06-23T11:24:44+02:00",
        "updated": "2016-06-23T11:24:44+02:00",
        "associations": {}
      }
    ]
  }
}

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 400,
  "message": "Invalid JSON message received"
}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Not Acceptable

The `Accept` header is not `application/json` but it should

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."
}

Unprocessable entity

The validation of the entity given in the body of the request failed

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

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"
    }
  }
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Create a new product

This endpoint allows you to create a new product.

REQUEST

post /api/rest/v1/products

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

{

identifier (string ) • Product identifier, i.e. the value of the only `pim_catalog_identifier` attribute

enabled (boolean , true by default) • Whether the product is enable

family (string , null by default) • Family code from which the product inherits its attributes and attributes requirements

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

variant_group (string , null by default) • Code of the variant group in which the product is

values (object { attributeCode : array [ object { scope : string , locale : string , data : object } ] } ) • Product attributes values, see Product values section for more details

associations (object { associationTypeCode : object { groups : array [string] , products : array [string] } } ) • Several associations related to groups and/or other products, grouped by association types

}

Example

{
  "identifier": "top",
  "enabled": true,
  "family": "tshirt",
  "categories": [
    "summer_collection"
  ],
  "groups": [],
  "variant_group": null,
  "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": [
      {
        "locale": null,
        "scope": null,
        "data": [
          {
            "amount": "15.5",
            "currency": "EUR"
          },
          {
            "amount": "15",
            "currency": "USD"
          }
        ]
      }
    ],
    "color": [
      {
        "locale": null,
        "scope": null,
        "data": "black"
      }
    ],
    "size": [
      {
        "locale": null,
        "scope": null,
        "data": "m"
      }
    ]
  },
  "associations": {
    "PACK": {
      "products": [
        "sunglass"
      ],
      "groups": []
    }
  }
}

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 400,
  "message": "Invalid JSON message received"
}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Unsupported Media type

The `Content-type` header has to be `application/json`

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 validation of the entity given in the body of the request failed

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

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"
    }
  }
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Update/create several products

This endpoint allows you to update and/or create several products at once.

REQUEST

patch /api/rest/v1/products

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 product in JSON standard format

{

identifier (string ) • Product identifier, i.e. the value of the only `pim_catalog_identifier` attribute

enabled (boolean , true by default) • Whether the product is enable

family (string , null by default) • Family code from which the product inherits its attributes and attributes requirements

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

variant_group (string , null by default) • Code of the variant group in which the product is

values (object { attributeCode : array [ object { scope : string , locale : string , data : object } ] } ) • Product attributes values, see Product values section for more details

associations (object { associationTypeCode : object { groups : array [string] , products : array [string] } } ) • Several associations related to groups and/or other products, grouped by association types

created (string ) • Date of creation

updated (string ) • Date of the last update

}

Example

{"identifier":"cap","values":{"description":[{"scope":"ecommerce","locale":"en_US","data":"My amazing cap"}]}}
{"identifier":"mug","group":["promotion"]}
{"identifier":"tshirt","family":"clothes"}

RESPONSES

OK

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 ) • Resource identifier, only filled when the resource is a product

code (string ) • Resource code, only filled when the resource is a category, a family or an attribute

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}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Request Entity Too Large

There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)

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."
}

Unsupported Media type

The `Content-type` header has to be `application/vnd.akeneo.collection+json`

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/vnd.akeneo.collection+json’ is allowed."
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Get a product

This endpoint allows you to get the information about a given product.

REQUEST

get /api/rest/v1/products/{code}

Path parameters

code (string) • Code of the resource

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

OK

Returns the content of the product in JSON standard format

Body Format application/json

Follow the standard format of the entity

{

identifier (string ) • Product identifier, i.e. the value of the only `pim_catalog_identifier` attribute

enabled (boolean ) • Whether the product is enable

family (string ) • Family code from which the product inherits its attributes and attributes requirements

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

variant_group (string ) • Code of the variant group in which the product is

values (object ) : {
attributeCode (array [object] ) : [
        {
            scope (string ) • Channel code of the product value
            locale (string ) • Locale code of the product value
            data (object ) • Product value
        }
    ]
  }

associations (object ) : {
associationTypeCode (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
    }
  }

created (string ) • Date of creation

updated (string ) • Date of the last update

}

Example

{
  "identifier": "top",
  "enabled": true,
  "family": "tshirt",
  "categories": [
    "summer_collection"
  ],
  "groups": [],
  "variant_group": null,
  "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": [
      {
        "locale": null,
        "scope": null,
        "data": [
          {
            "amount": "15.5",
            "currency": "EUR"
          },
          {
            "amount": "15",
            "currency": "USD"
          }
        ]
      }
    ],
    "color": [
      {
        "locale": null,
        "scope": null,
        "data": "black"
      }
    ],
    "size": [
      {
        "locale": null,
        "scope": null,
        "data": "m"
      }
    ]
  },
  "created": "2016-06-23T18:24:44+02:00",
  "updated": "2016-06-25T17:56:12+02:00",
  "associations": {
    "PACK": {
      "products": [
        "sunglass"
      ],
      "groups": []
    }
  }
}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Resource not found

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."
}

Not Acceptable

The `Accept` header is not `application/json` but it should

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."
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Update/create a product

This endpoint allows you to update a given product. Know more about Update behavior. Note that if no product exists for the given identifier, it creates it.

REQUEST

patch /api/rest/v1/products/{code}

Path parameters

code (string) • Code of the resource

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

{

identifier (string ) • Product identifier, i.e. the value of the only `pim_catalog_identifier` attribute

enabled (boolean , true by default) • Whether the product is enable

family (string , null by default) • Family code from which the product inherits its attributes and attributes requirements

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

variant_group (string , null by default) • Code of the variant group in which the product is

values (object { attributeCode : array [ object { scope : string , locale : string , data : object } ] } ) • Product attributes values, see Product values section for more details

associations (object { associationTypeCode : object { groups : array [string] , products : array [string] } } ) • Several associations related to groups and/or other products, grouped by association types

created (string ) • Date of creation

updated (string ) • Date of the last update

}

Example

{
  "identifier": "top",
  "enabled": true,
  "family": "tshirt",
  "categories": [
    "summer_collection"
  ],
  "groups": [],
  "variant_group": null,
  "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": [
      {
        "locale": null,
        "scope": null,
        "data": [
          {
            "amount": "15.5",
            "currency": "EUR"
          },
          {
            "amount": "15",
            "currency": "USD"
          }
        ]
      }
    ],
    "color": [
      {
        "locale": null,
        "scope": null,
        "data": "black"
      }
    ],
    "size": [
      {
        "locale": null,
        "scope": null,
        "data": "m"
      }
    ]
  },
  "created": "2016-06-23T18:24:44+02:00",
  "updated": "2016-06-25T17:56:12+02:00",
  "associations": {
    "PACK": {
      "products": [
        "sunglass"
      ],
      "groups": []
    }
  }
}

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

No content to return

Means that the update was successful

Headers

Location • URI of the updated resource

Body Format application/json

Ø

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Unsupported Media type

The `Content-type` header has to be `application/json`

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 validation of the entity given in the body of the request failed

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

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"
    }
  }
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Delete a product

This endpoint allows you to delete a given product.

REQUEST

delete /api/rest/v1/products/{code}

Path parameters

code (string) • Code of the resource

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

Ø

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Resource not found

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."
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Categories

Get list of categories

This endpoint allows you to get a list of categories. Categories are paginated and sorted by `root/left`.

REQUEST

get /api/rest/v1/categories

Path parameters

Ø

Query parameters

page (integer , 1 by default ) • Number of the page to retrieve when using the `page` pagination method type. Should never be set manually, see Pagination section

limit (integer , 10 by default ) • Number of results by page, see Pagination section

with_count (boolean ) • Return the count of products in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way

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

Body Format application/json

Follow the standard format of the entity

{

_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
              }
          }
          code (string) • Category code
          parent (string) • Category code of the parent's category
          labels (object) : {
              localeCode (string) • Category label for the locale `localeCode`
          }
        }
    ]
}

}

Example

{
  "_links": {
    "self": {
      "href": "https://demo.akeneo.com/api/rest/v1/categories?page=2&limit=5"
    },
    "first": {
      "href": "https://demo.akeneo.com/api/rest/v1/categories?page=1&limit=5"
    },
    "previous": {
      "href": "https://demo.akeneo.com/api/rest/v1/categories?page=1&limit=5"
    },
    "next": {
      "href": "https://demo.akeneo.com/api/rest/v1/categories?page=3&limit=5"
    }
  },
  "current_page": 2,
  "_embedded": {
    "_items": [
      {
        "_links": {
          "self": {
            "href": "https://demo.akeneo.com/api/rest/v1/categories/winter_collection"
          }
        },
        "code": "winter_collection",
        "parent": null,
        "labels": {
          "en_US": "Winter collection",
          "fr_FR": "Collection hiver",
          "de_DE": "Winter-Kollektion"
        }
      },
      {
        "_links": {
          "self": {
            "href": "https://demo.akeneo.com/api/rest/v1/categories/woman"
          }
        },
        "code": "woman",
        "parent": "winter_collection",
        "labels": {
          "en_US": "Woman",
          "fr_FR": "Femme",
          "de_DE": "Damen"
        }
      },
      {
        "_links": {
          "self": {
            "href": "https://demo.akeneo.com/api/rest/v1/categories/man"
          }
        },
        "code": "man",
        "parent": "winter_collection",
        "labels": {
          "en_US": "Man",
          "fr_FR": "Homme",
          "de_DE": "Herren"
        }
      },
      {
        "_links": {
          "self": {
            "href": "https://demo.akeneo.com/api/rest/v1/categories/kids"
          }
        },
        "code": "kids",
        "parent": "winter_collection",
        "labels": {
          "en_US": "Kids",
          "fr_FR": "Enfant",
          "de_DE": "Kinder"
        }
      },
      {
        "_links": {
          "self": {
            "href": "https://demo.akeneo.com/api/rest/v1/categories/summer_collection"
          }
        },
        "code": "summer_collection",
        "parent": null,
        "labels": {
          "en_US": "Summer collection",
          "fr_FR": "Collection été",
          "de_DE": "Sommer-Kollektion"
        }
      }
    ]
  }
}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Not Acceptable

The `Accept` header is not `application/json` but it should

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."
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Create a new category

This endpoint allows you to create a new 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

{

code (string ) • Category code

parent (string , null by default) • Category code of the parent's category

labels (object { localeCode : string } , [] by default) • Category labels for each locale

}

Example

{
  "code": "winter_collection",
  "parent": null,
  "labels": {
    "en_US": "Winter collection",
    "fr_FR": "Collection hiver"
  }
}

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 400,
  "message": "Invalid JSON message received"
}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Unsupported Media type

The `Content-type` header has to be `application/json`

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 validation of the entity given in the body of the request failed

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

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"
    }
  }
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Update/create several categories

This endpoint allows you to update 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 product in JSON standard format

{

code (string ) • Category code

parent (string , null by default) • Category code of the parent's category

labels (object { localeCode : string } , [] by default) • Category labels for each locale

}

Example

{"code":"spring_collection","parent":null}
{"code":"woman","parent":"spring_collectionn"}
{"code":"man","parent":"spring_collection"}

RESPONSES

OK

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 ) • Resource identifier, only filled when the resource is a product

code (string ) • Resource code, only filled when the resource is a category, a family or an attribute

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}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Request Entity Too Large

There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)

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."
}

Unsupported Media type

The `Content-type` header has to be `application/vnd.akeneo.collection+json`

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/vnd.akeneo.collection+json’ is allowed."
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Get a category

This endpoint allows you to get the information about a given category.

REQUEST

get /api/rest/v1/categories/{code}

Path parameters

code (string) • Code of the resource

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

OK

Returns the content of the category in JSON standard format

Body Format application/json

Follow the standard format of the entity

{

code (string ) • Category code

parent (string ) • Category code of the parent's category

labels (object ) : {
localeCode (string )   }

}

Example

{
  "code": "winter_collection",
  "parent": null,
  "labels": {
    "en_US": "Winter collection",
    "fr_FR": "Collection hiver"
  }
}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Resource not found

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."
}

Not Acceptable

The `Accept` header is not `application/json` but it should

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."
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Update/create a category

This endpoint allows you to update a given category. Know more about Update behavior. Note that if no category exists for the given code, it creates it.

REQUEST

patch /api/rest/v1/categories/{code}

Path parameters

code (string) • Code of the resource

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 ) • Category code

parent (string , null by default) • Category code of the parent's category

labels (object { localeCode : string } , [] by default) • Category labels for each locale

}

Example

{
  "code": "winter_collection",
  "parent": null,
  "labels": {
    "en_US": "Winter collection",
    "fr_FR": "Collection hiver"
  }
}

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

No content to return

Means that the update was successful

Headers

Location • URI of the updated resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 400,
  "message": "Invalid JSON message received"
}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Unsupported Media type

The `Content-type` header has to be `application/json`

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 validation of the entity given in the body of the request failed

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

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"
    }
  }
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Families

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

page (integer , 1 by default ) • Number of the page to retrieve when using the `page` pagination method type. Should never be set manually, see Pagination section

limit (integer , 10 by default ) • Number of results by page, see Pagination section

with_count (boolean ) • Return the count of products in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way

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 families paginated

Body Format application/json

Follow the standard format of the entity

{

_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
              }
          }
          code (string) • Family code
          attribute_as_label (string) • Attribute code used as label
          attributes (array [string ]) • Attributes codes that compose the family
          attribute_requirements (object) : {
              channelCode (array [string ]) • Attributes codes of the family that are required for the completeness calculation for the channel `channelCode`
          }
          labels (object) : {
              localeCode (string) • Family label for the locale `localeCode`
          }
        }
    ]
}

}

Example

{
  "_links": {
    "self": {
      "href": "https://demo.akeneo.com/api/rest/v1/families?page=2&limit=2"
    },
    "first": {
      "href": "https://demo.akeneo.com/api/rest/v1/families?page=1&limit=2"
    },
    "previous": {
      "href": "https://demo.akeneo.com/api/rest/v1/families?page=1&limit=2"
    },
    "next": {
      "href": "https://demo.akeneo.com/api/rest/v1/families?page=3&limit=2"
    }
  },
  "current_page": 2,
  "_embedded": {
    "_items": [
      {
        "_links": {
          "self": {
            "href": "https://demo.akeneo.com/api/rest/v1/families/tshirt"
          }
        },
        "code": "tshirt",
        "attributes": [
          "sku",
          "name",
          "description",
          "price",
          "size",
          "color"
        ],
        "attribute_as_label": "name",
        "attribute_requirements": {
          "ecommerce": [
            "sku",
            "name",
            "description",
            "price",
            "size",
            "color"
          ],
          "tablet": [
            "sku",
            "name",
            "description",
            "price"
          ]
        },
        "labels": {
          "en_US": "Tshirt",
          "fr_FR": "Tshirt"
        }
      },
      {
        "_links": {
          "self": {
            "href": "https://demo.akeneo.com/api/rest/v1/families/caps"
          }
        },
        "code": "caps",
        "attributes": [
          "sku",
          "name",
          "description",
          "price",
          "color"
        ],
        "attribute_as_label": "name",
        "attribute_requirements": {
          "ecommerce": [
            "sku",
            "name",
            "description",
            "price",
            "color"
          ],
          "tablet": [
            "sku",
            "name",
            "description",
            "price"
          ]
        },
        "labels": {
          "en_US": "Caps",
          "fr_FR": "Casquettes"
        }
      }
    ]
  }
}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Not Acceptable

The `Accept` header is not `application/json` but it should

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."
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

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 • Equal to 'application/json', no other value allowed

Body

Follow the standard format of the entity

{

code (string ) • Family code

attribute_as_label (string ) • Attribute code used as label

attributes (array [string] , [] by default) • Attributes codes that compose the family

attribute_requirements (object { channelCode : array [ string ] } ) • Attributes codes of the family that are required for the completeness calculation for each channel

labels (object { localeCode : string } , [] by default) • Family labels for each locale

}

Example

{
  "code": "caps",
  "attributes": [
    "sku",
    "name",
    "description",
    "price",
    "color"
  ],
  "attribute_as_label": "name",
  "attribute_requirements": {
    "ecommerce": [
      "sku",
      "name",
      "description",
      "price",
      "color"
    ],
    "tablet": [
      "sku",
      "name",
      "description",
      "price"
    ]
  },
  "labels": {
    "en_US": "Caps",
    "fr_FR": "Casquettes"
  }
}

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 400,
  "message": "Invalid JSON message received"
}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Unsupported Media type

The `Content-type` header has to be `application/json`

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 validation of the entity given in the body of the request failed

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

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"
    }
  }
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

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 product in JSON standard format

{

code (string ) • Family code

attribute_as_label (string ) • Attribute code used as label

attributes (array [string] , [] by default) • Attributes codes that compose the family

attribute_requirements (object { channelCode : array [ string ] } ) • Attributes codes of the family that are required for the completeness calculation for each channel

labels (object { localeCode : string } , [] by default) • Family labels for each locale

}

Example

{"code":"tshirt","attributes":["description","size"]}
{"code":"cap","attribute_as_label":"descripion"}
{"code":"mug","attributes":["description","short_description"]}

RESPONSES

OK

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 ) • Resource identifier, only filled when the resource is a product

code (string ) • Resource code, only filled when the resource is a category, a family or an attribute

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":"tshirt","status_code":201}
{"line":2,"code":"cap","status_code":422,"message":"Attribute "descripion" does not exist."}
{"line":3,"code":"mug","status_code":204}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Request Entity Too Large

There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)

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."
}

Unsupported Media type

The `Content-type` header has to be `application/vnd.akeneo.collection+json`

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/vnd.akeneo.collection+json’ is allowed."
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

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) • Code of the resource

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

OK

Returns the content of the family in JSON standard format

Body Format application/json

Follow the standard format of the entity

{

code (string ) • Family code

attribute_as_label (string ) • Attribute code used as label

attributes (array [string] ) • Attributes codes that compose the family

attribute_requirements (object ) : {
channelCode (array [string] ) • Attributes codes of the family that are required for the completeness calculation for the channel `channelCode`
  }

labels (object ) : {
localeCode (string )   }

}

Example

{
  "code": "caps",
  "attributes": [
    "sku",
    "name",
    "description",
    "price",
    "color"
  ],
  "attribute_as_label": "name",
  "attribute_requirements": {
    "ecommerce": [
      "sku",
      "name",
      "description",
      "price",
      "color"
    ],
    "tablet": [
      "sku",
      "name",
      "description",
      "price"
    ]
  },
  "labels": {
    "en_US": "Caps",
    "fr_FR": "Casquettes"
  }
}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Resource not found

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."
}

Not Acceptable

The `Accept` header is not `application/json` but it should

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."
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

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) • Code of the resource

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 code

attribute_as_label (string ) • Attribute code used as label

attributes (array [string] , [] by default) • Attributes codes that compose the family

attribute_requirements (object { channelCode : array [ string ] } ) • Attributes codes of the family that are required for the completeness calculation for each channel

labels (object { localeCode : string } , [] by default) • Family labels for each locale

}

Example

{
  "code": "caps",
  "attributes": [
    "sku",
    "name",
    "description",
    "price",
    "color"
  ],
  "attribute_as_label": "name",
  "attribute_requirements": {
    "ecommerce": [
      "sku",
      "name",
      "description",
      "price",
      "color"
    ],
    "tablet": [
      "sku",
      "name",
      "description",
      "price"
    ]
  },
  "labels": {
    "en_US": "Caps",
    "fr_FR": "Casquettes"
  }
}

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

No content to return

Means that the update was successful

Headers

Location • URI of the updated resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 400,
  "message": "Invalid JSON message received"
}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Unsupported Media type

The `Content-type` header has to be `application/json`

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 validation of the entity given in the body of the request failed

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

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"
    }
  }
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Attributes

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

page (integer , 1 by default ) • Number of the page to retrieve when using the `page` pagination method type. Should never be set manually, see Pagination section

limit (integer , 10 by default ) • Number of results by page, see Pagination section

with_count (boolean ) • Return the count of products in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way

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

Body Format application/json

Follow the standard format of the entity

{

_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
              }
          }
          code (string) • Attribute code
          type (string) • Attribute type
          labels (object) : {
              localeCode (string) • Attribute label for the locale `localeCode`
          }
          group (string) • Attribute group
          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) • 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) • Validation rule type used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`
          validation_regexp (string) • Regexp expression used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`
          wysiwyg_enabled (boolean) • Whether the WYSIWYG interface is shown when the attribute type is `pim_catalog_textarea`
          number_min (string) • Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`
          number_max (string) • Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`
          decimals_allowed (boolean) • Whether decimals are allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`
          negative_allowed (boolean) • Whether negative values are allowed when the attribute type is `pim_catalog_metric` or `pim_catalog_number`
          metric_family (string) • Metric family when the attribute type is `pim_catalog_metric`
          default_metric_unit (string) • Default metric unit when the attribute type is `pim_catalog_metric`
          date_min (string) • Minimum date allowed when the attribute type is `pim_catalog_date`
          date_max (string) • 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) • Max file size when the attribute type is `pim_catalog_file` or `pim_catalog_image`
        }
    ]
}

}

Example

{
  "_links": {
    "self": {
      "href": "https://demo.akeneo.com/api/rest/v1/attributes?page=3&limit=2"
    },
    "first": {
      "href": "https://demo.akeneo.com/api/rest/v1/attributes?page=1&limit=2"
    },
    "previous": {
      "href": "https://demo.akeneo.com/api/rest/v1/attributes?page=2&limit=2"
    },
    "next": {
      "href": "https://demo.akeneo.com/api/rest/v1/attributes?page=4&limit=2"
    }
  },
  "current_page": 3,
  "_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"
        }
      },
      {
        "_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"
        }
      }
    ]
  }
}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Not Acceptable

The `Accept` header is not `application/json` but it should

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."
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

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

labels (object { localeCode : string } , [] by default) • Attribute labels for each locale

group (string ) • Attribute group

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 ) • 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 ) • Validation rule type used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`

validation_regexp (string ) • Regexp expression used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`

wysiwyg_enabled (boolean ) • Whether the WYSIWYG interface is shown when the attribute type is `pim_catalog_textarea`

number_min (string ) • Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`

number_max (string ) • Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`

decimals_allowed (boolean ) • Whether decimals are allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`

negative_allowed (boolean ) • Whether negative values are allowed when the attribute type is `pim_catalog_metric` or `pim_catalog_number`

metric_family (string ) • Metric family when the attribute type is `pim_catalog_metric`

default_metric_unit (string ) • Default metric unit when the attribute type is `pim_catalog_metric`

date_min (string ) • Minimum date allowed when the attribute type is `pim_catalog_date`

date_max (string ) • 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 ) • Max file size when the attribute type is `pim_catalog_file` or `pim_catalog_image`

}

Example

{
  "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": 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,
  "labels": {
    "en_US": "Sale date",
    "fr_FR": "Date des soldes"
  }
}

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 400,
  "message": "Invalid JSON message received"
}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Unsupported Media type

The `Content-type` header has to be `application/json`

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 validation of the entity given in the body of the request failed

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

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"
    }
  }
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

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 a product in JSON standard format

{

code (string ) • Attribute code

type (string ) • Attribute type

labels (object { localeCode : string } , [] by default) • Attribute labels for each locale

group (string ) • Attribute group

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 ) • 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 ) • Validation rule type used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`

validation_regexp (string ) • Regexp expression used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`

wysiwyg_enabled (boolean ) • Whether the WYSIWYG interface is shown when the attribute type is `pim_catalog_textarea`

number_min (string ) • Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`

number_max (string ) • Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`

decimals_allowed (boolean ) • Whether decimals are allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`

negative_allowed (boolean ) • Whether negative values are allowed when the attribute type is `pim_catalog_metric` or `pim_catalog_number`

metric_family (string ) • Metric family when the attribute type is `pim_catalog_metric`

default_metric_unit (string ) • Default metric unit when the attribute type is `pim_catalog_metric`

date_min (string ) • Minimum date allowed when the attribute type is `pim_catalog_date`

date_max (string ) • 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 ) • Max file size when the attribute type is `pim_catalog_file` or `pim_catalog_image`

}

Example

{"code":"description","useable_as_grid_filter":true}
{"code":"short_description","group":"marketig"}
{"code":"release_date","date_min":"2017-06-28T08:00:00"}

RESPONSES

OK

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 ) • Resource identifier, only filled when the resource is a product

code (string ) • Resource code, only filled when the resource is a category, a family or an attribute

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}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Request Entity Too Large

There are too many resources to process (max 100) or the line of JSON is too long (max 1 000 000 characters)

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."
}

Unsupported Media type

The `Content-type` header has to be `application/vnd.akeneo.collection+json`

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/vnd.akeneo.collection+json’ is allowed."
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

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) • Code of the resource

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

OK

Returns the content of the attribute in JSON standard format

Body Format application/json

Follow the standard format of the entity

{

code (string ) • Attribute code

type (string ) • Attribute type

labels (object ) : {
localeCode (string )   }

group (string ) • Attribute group

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 ) • 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 ) • Validation rule type used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`

validation_regexp (string ) • Regexp expression used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`

wysiwyg_enabled (boolean ) • Whether the WYSIWYG interface is shown when the attribute type is `pim_catalog_textarea`

number_min (string ) • Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`

number_max (string ) • Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`

decimals_allowed (boolean ) • Whether decimals are allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`

negative_allowed (boolean ) • Whether negative values are allowed when the attribute type is `pim_catalog_metric` or `pim_catalog_number`

metric_family (string ) • Metric family when the attribute type is `pim_catalog_metric`

default_metric_unit (string ) • Default metric unit when the attribute type is `pim_catalog_metric`

date_min (string ) • Minimum date allowed when the attribute type is `pim_catalog_date`

date_max (string ) • 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 ) • Max file size when the attribute type is `pim_catalog_file` or `pim_catalog_image`

}

Example

{
  "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": 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,
  "labels": {
    "en_US": "Sale date",
    "fr_FR": "Date des soldes"
  }
}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Resource not found

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."
}

Not Acceptable

The `Accept` header is not `application/json` but it should

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."
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

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) • Code of the resource

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

labels (object { localeCode : string } , [] by default) • Attribute labels for each locale

group (string ) • Attribute group

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 ) • 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 ) • Validation rule type used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`

validation_regexp (string ) • Regexp expression used to validate any attribute value when the attribute type is `pim_catalog_text` or `pim_catalog_identifier`

wysiwyg_enabled (boolean ) • Whether the WYSIWYG interface is shown when the attribute type is `pim_catalog_textarea`

number_min (string ) • Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`

number_max (string ) • Minimum integer value allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`

decimals_allowed (boolean ) • Whether decimals are allowed when the attribute type is `pim_catalog_metric`, `pim_catalog_price` or `pim_catalog_number`

negative_allowed (boolean ) • Whether negative values are allowed when the attribute type is `pim_catalog_metric` or `pim_catalog_number`

metric_family (string ) • Metric family when the attribute type is `pim_catalog_metric`

default_metric_unit (string ) • Default metric unit when the attribute type is `pim_catalog_metric`

date_min (string ) • Minimum date allowed when the attribute type is `pim_catalog_date`

date_max (string ) • 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 ) • Max file size when the attribute type is `pim_catalog_file` or `pim_catalog_image`

}

Example

{
  "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": 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,
  "labels": {
    "en_US": "Sale date",
    "fr_FR": "Date des soldes"
  }
}

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

No content to return

Means that the update was successful

Headers

Location • URI of the updated resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 400,
  "message": "Invalid JSON message received"
}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Unsupported Media type

The `Content-type` header has to be `application/json`

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 validation of the entity given in the body of the request failed

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

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"
    }
  }
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Attribute options

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) • Code of the attribute

Query parameters

page (integer , 1 by default ) • Number of the page to retrieve when using the `page` pagination method type. Should never be set manually, see Pagination section

limit (integer , 10 by default ) • Number of results by page, see Pagination section

with_count (boolean ) • Return the count of products in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way

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

Body Format application/json

Follow the standard format of the entity

{

_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
              }
          }
          code (string) • Code of option
          attribute (string) • Code of attribute related to the attribute option
          sort_order (integer) • Order of attribute option
          labels (object) : {
              localeCode (string) • Attribute option label for the locale `localeCode`
          }
        }
    ]
}

}

Example

{
  "_links": {
    "self": {
      "href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options?page=3&limit=3"
    },
    "first": {
      "href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options?page=1&limit=3"
    },
    "previous": {
      "href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options?page=2&limit=3"
    },
    "next": {
      "href": "https://demo.akeneo.com/api/rest/v1/attributes/color/options?page=4&limit=3"
    }
  },
  "current_page": 3,
  "_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"
        }
      }
    ]
  }
}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Not Acceptable

The `Accept` header is not `application/json` but it should

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."
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

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) • Code of the attribute

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 option

attribute (string ) • Code of attribute related to the attribute option

sort_order (integer ) • Order of attribute option

labels (object { localeCode : string } , [] by default) • Attribute option labels for each locale

}

Example

{
  "code": "black",
  "attribute": "a_simple_select",
  "sort_order": 2,
  "labels": {
    "en_US": "Black",
    "fr_FR": "Noir"
  }
}

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 400,
  "message": "Invalid JSON message received"
}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Unsupported Media type

The `Content-type` header has to be `application/json`

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 validation of the entity given in the body of the request failed

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

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"
    }
  }
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

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) • Code of the attribute

code (string) • Code of the resource

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

OK

Returns the content of the attribute option in JSON standard format

Body Format application/json

Follow the standard format of the entity

{

code (string ) • Code of option

attribute (string ) • Code of attribute related to the attribute option

sort_order (integer ) • Order of attribute option

labels (object ) : {
localeCode (string )   }

}

Example

{
  "code": "black",
  "attribute": "a_simple_select",
  "sort_order": 2,
  "labels": {
    "en_US": "Black",
    "fr_FR": "Noir"
  }
}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Resource not found

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."
}

Not Acceptable

The `Accept` header is not `application/json` but it should

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."
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

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.

REQUEST

patch /api/rest/v1/attributes/{attribute_code}/options/{code}

Path parameters

attribute_code (string) • Code of the attribute

code (string) • Code of the resource

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 option

attribute (string ) • Code of attribute related to the attribute option

sort_order (integer ) • Order of attribute option

labels (object { localeCode : string } , [] by default) • Attribute option labels for each locale

}

Example

{
  "code": "black",
  "attribute": "a_simple_select",
  "sort_order": 2,
  "labels": {
    "en_US": "Black",
    "fr_FR": "Noir"
  }
}

RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

No content to return

Means that the update was successful

Headers

Location • URI of the updated resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 400,
  "message": "Invalid JSON message received"
}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Unsupported Media type

The `Content-type` header has to be `application/json`

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 validation of the entity given in the body of the request failed

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

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"
    }
  }
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Media files

Get a list of media files

This endpoint allows you to get a list of media files.

REQUEST

get /api/rest/v1/media-files

Path parameters

Ø

Query parameters

page (integer , 1 by default ) • Number of the page to retrieve when using the `page` pagination method type. Should never be set manually, see Pagination section

limit (integer , 10 by default ) • Number of results by page, see Pagination section

with_count (boolean ) • Return the count of products in the response. Be carefull with that, on a big catalog, it can decrease performance in a significative way

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

Body Format application/json

Follow the standard format of the entity

{

_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 to get the metadata of the media file
              }
              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
          _links (object) : {
              download (object) : {
                  href (string ) • Link to download the media file binaries
              }
          }
        }
    ]
}

}

Example

{
  "_links": {
    "self": {
      "href": "https://demo.akeneo.com/api/rest/v1/media-files?page=2&limit=4"
    },
    "first": {
      "href": "https://demo.akeneo.com/api/rest/v1/media-files?page=1&limit=4"
    },
    "previous": {
      "href": "https://demo.akeneo.com/api/rest/v1/media-files?page=1&limit=4"
    },
    "next": {
      "href": "https://demo.akeneo.com/api/rest/v1/media-files?page=2&limit=4"
    }
  },
  "current_page": 2,
  "_embedded": {
    "_items": [
      {
        "_links": {
          "self": {
            "href": "https://demo.akeneo.com/api/rest/v1/media-files/7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg"
          },
          "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"
      },
      {
        "_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"
      }
    ]
  }
}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Not Acceptable

The `Accept` header is not `application/json` but it should

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."
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Create a new media file

This endpoint allows you to create a new media file and associate it to the product value of a given product.

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 'multipart/form-data', no other value allowed

Body

Given as form-data

product (string ) • The product to which the media file will be associated. It is a JSON string that follows this formula '{"identifier":"product_identifier", "attribute":"attribute_code", "scope":"channel_code","locale":"locale_code"}'

file (string / binary) • The binaries of the file


RESPONSES

Created

Means that the creation was successful

Headers

Location • URI of the created resource

Body Format application/json

Ø

Bad request

Can be caused by a malformed JSON request

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 400,
  "message": "Invalid JSON message received"
}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Unsupported Media type

The `Content-type` header has to be `multipart/form-data`

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 ‘multipart/form-data’ is allowed."
}

Unprocessable entity

The validation of the entity given in the body of the request failed

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

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"
    }
  }
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Get a media file

This endpoint allows you to get the information about a given media file.

REQUEST

get /api/rest/v1/media-files/{code}

Path parameters

code (string) • Code of the resource

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

OK

Returns the content of the media file in JSON standard format

Body Format application/json

Follow the standard format of the entity

{

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

_links (object ) : {
download (object ) : {
        href (string ) • Link to download the media file binaries
    }
  }

}

Example

{
  "code": "7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg",
  "original_filename": "10806799-1356.jpg",
  "mime_type": "image/jpeg",
  "size": 16070,
  "extension": "jpg",
  "_links": {
    "download": {
      "href": "https://demo.akeneo.com/api/rest/v1/media-files/7/5/8/e/758e39d48ea7b42a55091434fd3d8b6cf3189b7f_10806799_1356.jpg/download"
    }
  }
}

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Resource not found

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."
}

Not Acceptable

The `Accept` header is not `application/json` but it should

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."
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Download a media file

This endpoint allows you to download a given media file.

REQUEST

get /api/rest/v1/media-files/{code}/download

Path parameters

code (string) • Code of the resource

Query parameters

Ø

Headers

Authorization • Equal to 'Bearer xxx', `xxx` being the authentication token, see Authentication section

Body

Ø


RESPONSES

OK

Returns the binary of the media file

Body Format Mime-type of the media file
Media file binary

Authentication required

Can be caused by a missing or expired token

Body Format application/json

{

code (integer ) • HTTP status code

message (string ) • Message explaining the error

}

Example

{
  "code": 401,
  "message": "Authentication is required"
}

Access forbidden

The user does not have the permission to execute this request

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 categories."
}

Resource not found

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."
}

Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!

Locales

Get a list of locales

This endpoint allows you to get a list of locales. Locales are paginated and sorted by code.

REQUEST

get /api/rest/v1/locales

Path parameters

Ø

Query parameters

page (integer , 1 by default ) • Number of the page to retrieve when using the `page` pagination method type. Should never be set manually, see Pagination s