Emporix Changelogs API

openapi: 3.2.0
info:
  title: Emporix Changelogs API
  version: ''
  contact:
    name: Emporix
    url: https://www.emporix.com/contact-us
    email: documentation@emporix.com
  description: 'Operations tagged Changelogs across 2 of this provider''s published API definitions: emporix-audit-logs-changelog-openapi.yml, emporix-audit-logs-changelog-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.emporix.io
security:
- OAuth2: []
tags:
- name: Changelogs
  description: Query tenant change history.
paths:
  /changelog/{tenant}/changelogs:
    parameters:
    - $ref: '#/components/parameters/path_tenant'
    get:
      tags:
      - Changelogs
      summary: Retrieving logs
      operationId: GET-changelog-retrieve-tenant-changelogs
      description: 'Retrieves a paginated list of changes for the tenant. Results are ordered by occurrence time.


        Filter results with the standard `q` query parameter. Supported fields:


        * `entity` — Entity type, for example `order`, `customer`, `company`, `product`, `segment`, `group`, `group-assignment`, `coupon`, `quote`, `site`, or a custom entity created with the Schema Service.

        * `entityId` — Document identifier. Requires `entity`.

        * `type` — Change type. Possible values: `create`, `update`, `delete`.

        * `actor` — Actor display name. Supports exact match, glob patterns such as `John*`, and regex such as `actor:~^sys`. Special values: `system`, `unknown`.

        * `occurredAt` — Time range, for example `occurredAt:(>"2026-06-01T00:00:00.000Z" AND entityId:)`.

        * `compoundLogicalQuery` — Nested `OR` / `AND` expressions.


        Scope a single document with `entity` and `entityId` in `q`. There is no path-based history endpoint.


        {% hint style="info" %}

        When the query omits a conjunctive `occurredAt` from-bound, the API applies a default trailing window of **30 days**. Pass an explicit top-level or `AND` `occurredAt` range to override it. An `occurredAt` only inside an `OR` arm does not disable the default window.

        {% endhint %}'
      security:
      - OAuth2:
        - changelog.changelog_read
        - changelog.changelog_manage
      parameters:
      - $ref: '#/components/parameters/query_q'
      - $ref: '#/components/parameters/query_page'
      - $ref: '#/components/parameters/query_size'
      responses:
        '200':
          description: The request was successful. A paginated list of changed entries has been returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangelogHistoryResponse'
              examples:
                Order status update:
                  $ref: '#/components/examples/changelogHistoryOrderUpdate'
                Related group-assignment rows:
                  $ref: '#/components/examples/changelogHistoryRelated'
        '400':
          description: Bad Request. The page, size, or q parameter is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              examples:
                Invalid page:
                  value:
                    status: 400
                    message: page must be >= 1
                Invalid size:
                  value:
                    status: 400
                    message: size must be between 1 and 100
                Unsupported query field:
                  value:
                    status: 400
                    message: 'Unsupported query field: status'
                Missing entity for entityId:
                  value:
                    status: 400
                    message: entity is required when entityId is provided
        '401':
          $ref: '#/components/responses/Unauthorized_401'
        '403':
          $ref: '#/components/responses/Forbidden_403'
        '500':
          $ref: '#/components/responses/InternalServiceError_500'
    servers:
    - url: https://api.emporix.io
components:
  responses:
    Unauthorized_401:
      description: Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.
      content:
        application/json:
          schema:
            type: object
            properties:
              fault:
                type: object
                properties:
                  faultstring:
                    type: string
                  detail:
                    type: object
                    properties:
                      errorcode:
                        type: string
          examples:
            Invalid access token:
              value:
                fault:
                  faultstring: Invalid access token
                  detail:
                    errorcode: oauth.v2.InvalidAccessToken
            Access token expired:
              value:
                fault:
                  faultstring: Access Token expired
                  detail:
                    errorcode: keymanagement.service.access_token_expired
    Forbidden_403:
      description: 'Given authorization scopes are not sufficient and do not match required scopes.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Forbidden:
              value:
                status: 403
                message: Given request does not have required scopes. It is not authorized to perform this operation.
                type: insufficient_permissions
    InternalServiceError_500:
      description: Internal Server Error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Internal Server Error:
              value:
                status: 500
                message: Problem encountered while trying to retrieve changelog history.
  schemas:
    ErrorMessage:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code.
        type:
          type: string
          description: Error type identifier.
        message:
          type: string
          description: Human-readable error message.
        details:
          type: array
          description: Field-level validation details.
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
    ChangelogHistoryResponse:
      type: object
      description: Paginated tenant changelog history.
      properties:
        items:
          type: array
          description: List of changed entries for the requested page.
          items:
            $ref: '#/components/schemas/ChangelogChangeItem'
        page:
          type: integer
          description: Current page number. The number of the first page is 1.
        size:
          type: integer
          description: Number of items requested per page.
        totalElements:
          type: integer
          format: int64
          description: Total number of changed entries matching the query.
        totalPages:
          type: integer
          description: Total number of pages for the matching result set.
      required:
      - items
      - page
      - size
      - totalElements
      - totalPages
    ChangelogChangeItem:
      type: object
      description: A single changelog entry describing a change to a platform entity.
      properties:
        at:
          type: string
          format: date-time
          description: 'ISO-8601 UTC timestamp with milliseconds when the change occurred, for example `2026-06-01T13:01:29.123Z`.

            '
        type:
          type: string
          enum:
          - create
          - update
          - delete
          description: 'Change type returned by the API.

            * `create` — Document insert.

            * `update` — Document update or replace.

            * `delete` — Document delete.

            '
        entity:
          type: string
          description: 'Logical entity type of the changed document, for example `order`, `customer`, `company`, `product`, `segment`, `group`, `group-assignment`, `coupon`, `quote`, `site`, or a custom entity created with the Schema Service.

            '
        entityId:
          type: string
          description: Unique identifier of the changed document.
        name:
          type: string
          description: Optional display name of the changed document when available.
        paths:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/PathValueChange'
          description: 'Flattened map of changed field paths to before/after values derived from the change patch.

            '
        schemaVersion:
          type: string
          description: Optional schema or document format version associated with the change.
        actor:
          type: string
          description: 'Actor display name that performed the change. Possible values include a person name, `system`, `external`, or `unknown`.

            '
        related:
          type: array
          description: Related entities linked to the changed document, for example junction-style references.
          items:
            $ref: '#/components/schemas/ChangelogRelatedItem'
    PathValueChange:
      type: object
      description: Before and after values for a changed field path.
      properties:
        before:
          description: Value of the field before the change. Omitted when not available.
        after:
          description: Value of the field after the change. Omitted when not available.
    ChangelogRelatedItem:
      type: object
      description: A related entity referenced by a changelog entry.
      properties:
        entity:
          type: string
          description: Related entity type, for example `group` or `customer`.
        entityId:
          type: string
          description: Unique identifier of the related entity.
  examples:
    changelogHistoryRelated:
      summary: Group-assignment related to a group
      value:
        items:
        - at: '2026-06-01T10:00:00.000Z'
          type: create
          entity: group-assignment
          entityId: 264e59c0-0130-4f1b-a83f-cea06264a397
          actor: system
          related:
          - entity: group
            entityId: 1gr5e52e-6e27-4ac5-9471-2467d3fb7501
          - entity: customer
            entityId: cd6818c8-ec9b-42d4-83c4-8c51dfbe9ce0
        page: 1
        size: 20
        totalElements: 1
        totalPages: 1
    changelogHistoryOrderUpdate:
      summary: Order status update
      value:
        items:
        - at: '2026-06-01T13:01:29.123Z'
          type: update
          entity: order
          entityId: 6a2bce93592855a33518fc2f
          paths:
            status:
              before: CREATED
              after: CONFIRMED
          schemaVersion: v2
          actor: John Doe
        page: 1
        size: 20
        totalElements: 1
        totalPages: 1
  parameters:
    path_tenant:
      name: tenant
      in: path
      required: true
      schema:
        pattern: ^[a-z][a-z0-9]+$
        minLength: 3
        maxLength: 16
        type: string
      description: 'Your Emporix tenant''s name.

        **Note**: The tenant should always be written in lowercase.

        '
    query_q:
      name: q
      in: query
      required: false
      schema:
        type: string
      description: 'Standard query parameter used to filter changed entries.


        Supported fields:

        * `entity` — Entity type, for example `q=entity:order`.

        * `entityId` — Document identifier. Requires `entity`, for example `q=entity:order entityId:6a2bce93592855a33518fc2f`.

        * `type` — Change type (`create`, `update`, or `delete`), for example `q=type:update`.

        * `actor` — Actor display name. Exact match: `q=actor:system`. Glob: `q=actor:John*`. Regex: `q=actor:~^sys`.

        * `occurredAt` — Time range, for example `q=occurredAt:(>"2026-06-01T00:00:00.000Z" AND <"2026-06-30T23:59:59.999Z")`.

        * `related.entity` / `related.entityId` — Related-entity filters, for example `q=related.entity:group related.entityId:1gr5e52e-6e27-4ac5-9471-2467d3fb7501`.

        * `related:elemMatch(...)` — ElemMatch syntax, for example `q=related:elemMatch(entity:group entityId:1gr5e52e-6e27-4ac5-9471-2467d3fb7501)`.

        * `compoundLogicalQuery` — Nested `OR` / `AND` expressions, for example `q=compoundLogicalQuery:((entity:group type:update) OR (related:elemMatch(entity:group)))`.


        See also [Query Parameter](https://developer.emporix.io/api-documentation/standard-practices/q-param).'
      example: entity:order entityId:6a2bce93592855a33518fc2f
    query_size:
      name: size
      in: query
      required: false
      schema:
        default: 20
        minimum: 1
        maximum: 100
        type: integer
      description: 'Number of changed entries to be retrieved per page. Maximum value is 100.

        '
    query_page:
      name: page
      in: query
      required: false
      schema:
        default: 1
        minimum: 1
        type: integer
      description: 'Page number to be retrieved. The number of the first page is 1.

        '
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.emporix.io/oauth/token
          scopes:
            changelog.changelog_read: Needed to retrieve changelog history.
            changelog.changelog_manage: Needed to manage changelog resources. Also grants read access.
x-refined-from:
- emporix-audit-logs-changelog-openapi.yml
- emporix-audit-logs-changelog-openapi.yml