openapi: 3.2.0 info: title: Akeneo API REFERENCE Rule definition 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: Rule definition description: 'Rule definitions automate product data enrichment by applying actions when conditions are met. These endpoints allow you to list, read, and create or update rule definitions.' paths: /api/rest/v1/rule-definitions: get: operationId: get_rule_definitions x-visibility: public summary: Get list of rule definitions description: 'This endpoint allows you to get a list of rule definitions. Rules automate product data enrichment by applying actions when conditions are met. Rule definitions are paginated and sorted by code. Note: conditions and actions are omitted from the list response for performance. Triggers are included for product rules. Use the single GET endpoint to retrieve the full rule definition.' tags: - Rule definition security: - bearerToken: [] parameters: - in: query name: page description: 'Specify which page of results to retrieve when using pagination. It is useful for navigating through large datasets by breaking them into smaller, manageable pages. See [Pagination](https://api.akeneo.com/documentation/pagination.html) section for more details. ' required: false schema: type: integer default: 1 example: 1 - in: query name: limit description: 'Specify the maximum number of results to return per page. It is useful for controlling the amount of data returned in a single request, especially when dealing with large datasets. See [Pagination](https://api.akeneo.com/documentation/pagination.html) section for more details. ' required: false schema: type: integer default: 10 minimum: 1 maximum: 100 example: 100 - in: query name: with_count description: 'Return the count of items in the response. Be careful with that, on a big catalog, it can decrease performance in a significant way. It is useful for understanding the size of the dataset being returned, especially when dealing with large collections. Use it judiciously to avoid performance issues. ' required: false schema: type: boolean default: false example: true - name: codes in: query description: Filter by comma-separated rule codes required: false schema: type: string - name: type in: query description: 'Filter by rule type: product or record' required: false schema: type: string enum: - product - record - name: execution_type in: query description: 'Filter by execution type: triggered, scheduled, workflow_based' required: false schema: type: string enum: - triggered - scheduled - workflow_based - name: enabled in: query description: Filter by enabled status required: false schema: type: boolean responses: '200': description: Returns a paginated list of rule definitions content: application/json: schema: title: Rule definitions 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: current_page: type: integer description: Current page number example: 1 items_count: type: integer description: Total number of items (only if `with_count` parameter is set to true) example: 5 _embedded: type: object properties: items: type: array items: allOf: - type: object properties: _links: type: object properties: self: type: object properties: href: type: string description: URI of the resource example: https://demo.akeneo.com/api/rest/v1/rule-definitions/my_rule - type: object description: Summary of a rule definition (without conditions and actions) properties: code: type: string description: Unique rule definition code example: my_rule type: type: string description: 'Rule type: product or record' enum: - product - record example: product execution_type: type: string description: 'Execution mode: triggered, scheduled, or workflow_based' example: triggered enabled: type: boolean description: Whether the rule is active example: true priority: type: integer description: Execution priority (higher runs first) example: 10 reference_entity_identifier: type: - string - 'null' description: Reference entity identifier. Required when type is `record`, null otherwise. example: brand labels: type: object description: Rule labels indexed by locale code additionalProperties: type: string example: en_US: My rule triggers: type: array description: Array of trigger objects defining which attribute changes trigger the rule (only for triggered execution_type on product) items: type: object properties: field: type: string locale: type: string scope: type: string example: - field: name action_types: type: array description: List of action types used in this rule items: type: string example: - set example: _links: self: href: https://demo.akeneo.com/api/rest/v1/rule-definitions?page=1&limit=10&with_count=true first: href: https://demo.akeneo.com/api/rest/v1/rule-definitions?page=1&limit=10&with_count=true current_page: 1 items_count: 2 _embedded: items: - _links: self: href: https://demo.akeneo.com/api/rest/v1/rule-definitions/my_rule code: my_rule type: product execution_type: triggered enabled: true priority: 10 labels: en_US: My rule triggers: - field: name action_types: - set '400': description: 'This response indicates that the server cannot process the request due to a client error, such as malformed request syntax, invalid request message framing, or deceptive request routing. It is typically used when the server cannot understand the request due to invalid JSON or other client-side issues. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 400 message: Invalid JSON message received '401': description: 'This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 401 message: Full authentication is required to access this resource. '403': description: 'This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 403 message: Access forbidden. You are not allowed to list this entity. /api/rest/v1/rule-definitions/{code}: get: operationId: get_rule_definition_by_code x-visibility: public summary: Get a rule definition description: This endpoint allows you to get a single rule definition by its code. tags: - Rule definition 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 rule definition content: application/json: schema: type: object properties: code: type: string description: Unique rule definition code example: my_rule type: type: string description: 'Rule type: product or record' enum: - product - record example: product execution_type: type: string description: 'Execution mode: triggered, scheduled, or workflow_based' example: triggered enabled: type: boolean description: Whether the rule is active example: true priority: type: integer description: Execution priority (higher runs first) example: 10 reference_entity_identifier: type: - string - 'null' description: Reference entity identifier. Required when type is `record`, null otherwise. example: brand labels: type: object description: Rule labels indexed by locale code additionalProperties: type: string example: en_US: My rule conditions: type: array description: Array of condition objects defining when the rule applies items: type: object example: - field: family operator: IN value: - shoes actions: type: array description: Array of action objects defining what changes to apply items: type: object example: - type: set field: description value: Default description locale: en_US scope: ecommerce triggers: type: array description: Array of trigger objects defining which attribute changes trigger the rule (only for triggered execution_type on product) items: type: object properties: field: type: string description: Attribute code that triggers the rule locale: type: string description: Optional locale for localizable attributes scope: type: string description: Optional scope for scopable attributes example: - field: name - field: description locale: en_US scope: ecommerce action_types: type: array description: List of action types used in this rule items: type: string example: - set example: code: my_rule type: product execution_type: triggered enabled: true priority: 10 labels: en_US: My rule conditions: - field: family operator: IN value: - shoes actions: - type: set field: description value: Default description locale: en_US scope: ecommerce triggers: - field: name - field: description locale: en_US scope: ecommerce action_types: - set '401': description: 'This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 401 message: Full authentication is required to access this resource. '403': description: 'This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 403 message: Access forbidden. You are not allowed to list this entity. '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. put: operationId: put_rule_definition_by_code x-visibility: public summary: Create or update a rule definition description: 'This endpoint allows you to create or update a rule definition. If the rule definition does not exist yet, it creates it, otherwise it updates it. When `type` is `record`, the `reference_entity_identifier` field is required. When `execution_type` is omitted, it defaults to `scheduled`.' tags: - Rule definition 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: The rule definition to create or update. required: true content: application/json: schema: type: object required: - type - actions properties: type: type: string description: 'Rule type: product or record' enum: - product - record example: product reference_entity_identifier: type: - string - 'null' description: Reference entity identifier. Required when type is `record`, must be omitted or null for `product` rules. example: brand conditions: type: array description: Array of condition objects defining when the rule applies. Defaults to an empty array if omitted. items: type: object example: - field: family operator: IN value: - shoes actions: type: array description: Array of action objects defining what changes to apply items: type: object example: - type: set field: description value: Default description locale: en_US scope: ecommerce labels: type: object description: Rule labels indexed by locale code additionalProperties: type: string example: en_US: My rule priority: type: integer description: Execution priority (higher runs first) example: 10 enabled: type: boolean description: Whether the rule is active example: true execution_type: type: string description: Execution mode. Defaults to `scheduled` if omitted. enum: - triggered - scheduled - workflow_based example: triggered triggers: type: array description: Array of trigger objects defining which attribute changes trigger the rule. Only applicable for `triggered` execution_type on a product rule. items: type: object properties: field: type: string description: Attribute code that triggers the rule locale: type: string description: Optional locale for localizable attributes scope: type: string description: Optional scope for scopable attributes example: - field: name - field: description locale: en_US scope: ecommerce example: type: product conditions: - field: family operator: IN value: - shoes actions: - type: set field: description value: Default description locale: en_US scope: ecommerce labels: en_US: My rule priority: 10 enabled: false execution_type: triggered triggers: - field: name responses: '201': description: Created, returned when the rule definition has been created headers: Location: description: URI of the created resource schema: type: string '204': description: No content, returned when the rule definition has been updated headers: Location: description: URI of the updated resource schema: type: string '400': description: 'This response indicates that the server cannot process the request due to a client error, such as malformed request syntax, invalid request message framing, or deceptive request routing. It is typically used when the server cannot understand the request due to invalid JSON or other client-side issues. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 400 message: Invalid JSON message received '401': description: 'This response indicates that authentication is required to access the requested resource. It can be caused by a missing or expired token, or if the provided credentials are invalid. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 401 message: Full authentication is required to access this resource. '403': description: 'This response indicates that the request is not authorized. This can occur when the user lacks the necessary permissions to access a resource or perform an action, or when the request payload is too large for the platform to process. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 401 message: type: string description: Message explaining the error example: Full authentication is required to access this resource. example: code: 403 message: Access forbidden. You are not allowed to list this entity. '422': description: 'This response indicates that the validation of the entity given in the body of the request failed. It occurs when the server understands the request but cannot process it due to validation errors in the provided data. ' content: application/json: schema: type: object properties: code: type: integer description: HTTP status code example: 422 message: type: string description: Message explaining the error example: Validation failed. errors: type: array description: A list of validation error messages (optional) items: type: object properties: property: type: string description: Name of the invalid property message: type: string description: Human-readable error message attribute: type: - string - 'null' description: Attribute code (if the error is on an attribute) locale: type: - string - 'null' description: Locale code involved in the error, if any scope: type: - string - 'null' description: Channel code involved in the error, if any example: - property: family message: The tshirts family does not exist in your PIM. _links: type: object properties: documentation: type: object properties: href: type: string example: documentation: href: http://api.akeneo.com/api-reference.html example: code: 422 message: Validation failed. errors: - property: family message: The tshirts family does not exist in your PIM. - property: categories message: The "tvs_projectors" category does not exist. - property: associations.SUBSTITUTION.groups message: You should associate existing groups. The "promotion" group does not exist. - property: values message: The "description" attribute requires a channel. attribute: description locale: en_US scope: null - property: values message: The "name" attribute requires a locale. attribute: name locale: null scope: null _links: documentation: href: http://api.akeneo.com/api-reference.html components: securitySchemes: basicToken: scheme: basic type: http description: 'HTTP Basic authentication using user credentials. [More information here](https://api.akeneo.com/documentation/authentication.html) ' bearerToken: scheme: bearer type: http description: 'Bearer token obtained via the "Password Grant" flow. This token authenticates a user, is valid for one hour, and can be refreshed using a refresh token. [More information here](https://api.akeneo.com/documentation/authentication.html) ' appToken: scheme: bearer type: http description: 'Bearer token for Apps, obtained via the OAuth 2.0 flow. This permanent token allows an application to make requests on behalf of a user. [More information here](https://api.akeneo.com/apps/authentication-and-authorization.html) ' x-provenance: method: harvested publisher: Akeneo source: https://storage.googleapis.com/akecld-prd-pim-saas-shared-openapi-spec/openapi.yaml note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json); stamped by stamp-openapi-provenance.py (roadmap#793)