A reference entity is a custom entity that can be used to store additional information about products or product models. It allows you to create your own entities with their own attributes and values, which can be linked to products or product models. Reference entities are useful for managing complex data structures or for integrating with external systems.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/akeneo:akeneo-reference-entity-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Akeneo API REFERENCE Reference entity API
version: 1.0.0
description: 'This is the reference documentation for the Akeneo PIM REST API.
It provides detailed information about the available endpoints, request and response formats, and authentication methods.
For more information, visit the Akeneo PIM documentation.'
license:
name: Open Software License 3.0
url: http://opensource.org/licenses/OSL-3.0
contact:
name: Akeneo Support
url: https://www.akeneo.com/support-help-center/
email: contact@akeneo.com
servers:
- url: '{your-pim-url}'
variables:
your-pim-url:
default: ''
description: 'Set the PIM url you want to target ex: https://my-pim.cloud.akeneo.com or https://localhost:8443'
tags:
- name: Reference entity
description: 'A reference entity is a custom entity that can be used to store additional information about products or product models.
It allows you to create your own entities with their own attributes and values, which can be linked to products or product models.
Reference entities are useful for managing complex data structures or for integrating with external systems.'
paths:
/api/rest/v1/reference-entities:
get:
operationId: get_reference_entities
x-visibility: public
summary: Get list of reference entities
description: 'This endpoint allows you to get a list of reference entities.
Reference entities are paginated.'
tags:
- Reference entity
security:
- bearerToken: []
parameters:
- in: query
name: search_after
description: 'Cursor when using the `search_after` pagination method type.
It is essential for navigating through pages in cursor-based pagination, providing more efficient pagination for large datasets.
Should never be set manually, see [Pagination](https://api.akeneo.com/documentation/pagination.html) section for more details.
'
required: false
schema:
type: string
default: cursor to the first page
example: qaXbcde
responses:
'200':
description: 'Return reference entities paginated.
The response is paginated and includes links to navigate through the pages.
Only `search_after` pagination is used.
'
content:
application/json:
schema:
title: Reference Entities
type: object
allOf:
- type: object
properties:
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
description: URI of the current page of resources
example: https://demo.akeneo.com/api/rest/v1/categories?page=2&limit=5
first:
type: object
properties:
href:
type: string
description: URI of the first page of resources
example: https://demo.akeneo.com/api/rest/v1/categories?page=1&limit=5
previous:
type: object
properties:
href:
type: string
description: URI of the previous page of resources
example: https://demo.akeneo.com/api/rest/v1/categories?page=1&limit=5
next:
type: object
properties:
href:
type: string
description: URI of the next page of resources
example: https://demo.akeneo.com/api/rest/v1/categories?page=3&limit=5
- type: object
properties:
_embedded:
type: object
properties:
items:
type: array
items:
type: object
allOf:
- type: object
properties:
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
description: URI of the resource
example: https://demo.akeneo.com/api/rest/v1/reference-entities/brands
image_download:
type: object
properties:
href:
type: string
description: URI to download the binaries of the reference entity image file
example: https://demo.akeneo.com/api/rest/v1/reference-entities-media-files/0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png
- type: object
required:
- code
properties:
code:
type: string
description: Reference entity code
x-immutable: true
example: brands
labels:
type: object
description: Reference entity labels for each locale
default: {}
patternProperties:
^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$:
description: Reference entity label for the locale
type:
- string
- 'null'
example: Brands
x-validation-rules: The `localeCode` is the code of an existing and activated locale
example:
en_US: Brands
fr_FR: Marques
image:
type:
- string
- 'null'
description: Code of the reference entity image
example: 0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png
default: null
example:
_links:
self:
href: https://demo.akeneo.com/api/rest/v1/reference-entities
first:
href: https://demo.akeneo.com/api/rest/v1/reference-entities
next:
href: https://demo.akeneo.com/api/rest/v1/reference-entities?search_after=colors
_embedded:
items:
- _links:
self:
href: https://demo.akeneo.com/api/rest/v1/reference-entities/brands
image_download:
href: https://demo.akeneo.com/api/rest/v1/reference-entities-media-files/0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png
code: brands
labels:
en_US: Brands
fr_FR: Marques
image: 0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png
- _links:
self:
href: https://demo.akeneo.com/api/rest/v1/reference-entities/designers
code: designers
labels:
en_US: Designers
fr_FR: Designers
image: null
- _links:
self:
href: https://demo.akeneo.com/api/rest/v1/reference-entities/colors
code: colors
labels:
en_US: Colors
fr_FR: Couleurs
image: null
'401':
description: 'This response indicates that authentication is required to access the requested resource.
It can be caused by a missing or expired token, or if the provided credentials are invalid.
'
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: HTTP status code
example: 401
message:
type: string
description: Message explaining the error
example: Full authentication is required to access this resource.
example:
code: 401
message: Full authentication is required to access this resource.
'406':
description: 'This response indicates that the server cannot produce a response matching the list of acceptable values defined in the request''s `Accept` header.
It is typically used when the requested resource is not available in the requested format.
'
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: HTTP status code
example: 401
message:
type: string
description: Message explaining the error
example: Full authentication is required to access this resource.
example:
code: 406
message: xxx in `Accept` header is not valid. Only `application/json` is allowed.
/api/rest/v1/reference-entities/{code}:
get:
operationId: get_reference_entity_by_code
x-visibility: public
summary: Get a reference entity
description: This endpoint allows you to get the information about a given reference entity
tags:
- Reference entity
security:
- bearerToken: []
parameters:
- in: path
name: code
description: 'This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the code is correctly formatted and corresponds to an existing entity in the system.
'
required: true
schema:
type: string
example: my_entity_code
responses:
'200':
description: Returns the content of the reference entity in JSON format
content:
application/json:
schema:
type: object
allOf:
- type: object
properties:
_links:
type: object
readOnly: true
properties:
image_download:
type: object
properties:
href:
type: string
description: URI to download the binaries of the reference entity image file
example: https://demo.akeneo.com/api/rest/v1/reference-entities-media-files/0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png
- type: object
required:
- code
properties:
code:
type: string
description: Reference entity code
x-immutable: true
example: brands
labels:
type: object
description: Reference entity labels for each locale
default: {}
patternProperties:
^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$:
description: Reference entity label for the locale
type:
- string
- 'null'
example: Brands
x-validation-rules: The `localeCode` is the code of an existing and activated locale
example:
en_US: Brands
fr_FR: Marques
image:
type:
- string
- 'null'
description: Code of the reference entity image
example: 0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png
default: null
example:
_links:
image_download:
href: https://demo.akeneo.com/api/rest/v1/reference-entities-media-files/0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png
code: brands
labels:
en_US: Brands
fr_FR: Marques
image: 0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png
'401':
description: 'This response indicates that authentication is required to access the requested resource.
It can be caused by a missing or expired token, or if the provided credentials are invalid.
'
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: HTTP status code
example: 401
message:
type: string
description: Message explaining the error
example: Full authentication is required to access this resource.
example:
code: 401
message: Full authentication is required to access this resource.
'404':
description: 'This response indicates that the requested resource could not be found on the server.
It can occur when the resource code given in the URI does not correspond to any existing PIM resource.
'
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: HTTP status code
example: 401
message:
type: string
description: Message explaining the error
example: Full authentication is required to access this resource.
example:
code: 404
message: Resource `my_resource_code` does not exist.
'406':
description: 'This response indicates that the server cannot produce a response matching the list of acceptable values defined in the request''s `Accept` header.
It is typically used when the requested resource is not available in the requested format.
'
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: HTTP status code
example: 401
message:
type: string
description: Message explaining the error
example: Full authentication is required to access this resource.
example:
code: 406
message: xxx in `Accept` header is not valid. Only `application/json` is allowed.
patch:
operationId: patch_reference_entity_by_code
x-visibility: public
summary: Update/create a reference entity
description: 'This endpoint allows you to update a given reference entity.
Note that if the reference entity does not already exist, it creates it.'
tags:
- Reference entity
security:
- bearerToken: []
parameters:
- in: path
name: code
description: 'This path parameter is used to specify the unique identifier of the entity you want to retrieve or manipulate.
It is essential for identifying the specific entity in the API requests.
Ensure that the code is correctly formatted and corresponds to an existing entity in the system.
'
required: true
schema:
type: string
example: my_entity_code
requestBody:
description: Payload to create or update a reference entity
required: true
content:
application/json:
schema:
type: object
required:
- code
properties:
code:
type: string
description: Reference entity code
x-immutable: true
example: brands
labels:
type: object
description: Reference entity labels for each locale
default: {}
patternProperties:
^[a-zA-Z]{2,}_[a-zA-Z0-9_]{2,}$:
description: Reference entity label for the locale
type:
- string
- 'null'
example: Brands
x-validation-rules: The `localeCode` is the code of an existing and activated locale
example:
en_US: Brands
fr_FR: Marques
image:
type:
- string
- 'null'
description: Code of the reference entity image
example: 0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png
default: null
example:
code: brands
labels:
en_US: Brands
fr_FR: Marques
image: 0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png
responses:
'201':
description: 'This response indicates that the entity was successfully created.
The server has fulfilled the request and created a new resource.
The response includes a `Location` header that contains the URI of the newly created resource.
'
headers:
Location:
description: URI of the created resource
schema:
type: string
'204':
description: 'This response indicates that the request was successful and that there is no content to return.
It is typically used in response to a successful update operation where the server does not need to return any data to the client.
'
headers:
Location:
description: URI of the updated resource
schema:
type: string
'401':
description: 'This response indicates that authentication is required to access the requested resource.
It can be caused by a missing or expired token, or if the provided credentials are invalid.
'
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: HTTP status code
example: 401
message:
type: string
description: Message explaining the error
example: Full authentication is required to access this resource.
example:
code: 401
message: Full authentication is required to access this resource.
'415':
description: 'This response indicates that the `Content-type` header of the request is not supported by the server.
The server expects the `Content-type` header to be `application/json`, and any other value will result in this error.
'
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: HTTP status code
example: 401
message:
type: string
description: Message explaining the error
example: Full authentication is required to access this resource.
example:
code: 415
message: xxx in `Content-type` header is not valid. Only `application/json` is allowed."
'422':
description: 'This response indicates that the validation of the entity given in the body of the request failed.
It occurs when the server understands the request but cannot process it due to validation errors in the provided data.
'
content:
application/json:
schema:
type: object
required:
- code
- message
properties:
code:
type: integer
description: HTTP status code
example: 422
message:
type: string
description: Description of the validation error
example: The code of the reference entity provided in the URI must be the same as the one provided in the request body.
examples:
codeMismatch:
summary: Code mismatch between URI and request body
value:
code: 422
message: The code of the reference entity provided in the URI must be the same as the one provided in the request body.
imageNotFound:
summary: Provided image code does not exist
value:
code: 422
message: The image "0/2/d/6/54d81dc888ba1501a8g765f3ab5797569f3bv756c_ref_img.png" was not found
components:
securitySchemes:
basicToken:
scheme: basic
type: http
description: 'HTTP Basic authentication using user credentials.
[More information here](https://api.akeneo.com/documentation/authentication.html)
'
bearerToken:
scheme: bearer
type: http
description: 'Bearer token obtained via the "Password Grant" flow.
This token authenticates a user, is valid for one hour, and can be refreshed using a refresh token.
[More information here](https://api.akeneo.com/documentation/authentication.html)
'
appToken:
scheme: bearer
type: http
description: 'Bearer token for Apps, obtained via the OAuth 2.0 flow.
This permanent token allows an application to make requests on behalf of a user.
[More information here](https://api.akeneo.com/apps/authentication-and-authorization.html)
'
x-provenance:
method: harvested
publisher: Akeneo
source: https://storage.googleapis.com/akecld-prd-pim-saas-shared-openapi-spec/openapi.yaml
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)