openapi: 3.0.2
info:
  title: Entity API
  version: 2.10.0
  description: |
    Flexible data layer for epilot Entities.

    Use this API configure and access your business objects like Contacts, Opportunities and Products.

    [Feature Documentation](https://docs.epilot.io/docs/entities/flexible-entities)
tags:
- name: Schemas
  description: Model Entities
- name: Entities
  description: CRUD Access for Entities
- name: Relations
  description: Entity Relationships
- name: Activity
  description: Entity Events
- name: Import-Export
  description: Import and Export entities via portable files (CSV)
- name: Saved Views
  description: Saved Views for Entities
- name: Taxonomy
  description: Taxonomies and Classifications
- name: Elastic Cluster Assignment
  description: Elastic Cluster assignment for organizations
- name: Internal
  description: Internal APIs
- name: Public
  description: Public
security:
- EpilotAuth: []
- EpilotOrg: []
paths:
  /v1/entity/schemas:
    get:
      operationId: listSchemas
      summary: listSchemas
      description: Get the latest versions of all schemas
      parameters:
      - in: query
        name: unpublished
        description: Return unpublished draft schemas
        deprecated: true
        schema:
          type: boolean
          default: false
      - in: query
        name: latest
        deprecated: true
        description: |
          No longer has any effect: schema freezing is retired and the latest version is always returned.
        schema:
          type: boolean
          default: false
      - in: query
        name: exclude
        description: List of schema slugs to exclude from the results. Accepts a comma-separated list of slugs to exclude from the results.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: false
      - in: query
        name: include
        description: List of schema slugs to include in the results. When provided, only these schemas are returned. Accepts a comma-separated list of slugs.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: false
      tags:
      - Schemas
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/EntitySchemaItem'
  /v2/entity/schemas:
    get:
      operationId: listSchemasV2
      summary: listSchemasV2
      description: |
        Get the latest versions of all schemas.
        Returns summary schemas by default (only summary attributes, no capabilities).
        Use ?full=true for complete schemas.
      parameters:
      - in: query
        name: full
        description: Return full schemas including all attributes and capabilities
        schema:
          type: boolean
          default: false
      - in: query
        name: unpublished
        description: Return unpublished draft schemas
        deprecated: true
        schema:
          type: boolean
          default: false
      - in: query
        name: latest
        deprecated: true
        description: |
          No longer has any effect: schema freezing is retired and the latest version is always returned.
        schema:
          type: boolean
          default: false
      - in: query
        name: exclude
        description: List of schema slugs to exclude from the results. Accepts a comma-separated list of slugs to exclude from the results.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: false
      - in: query
        name: include
        description: List of schema slugs to include in the results. When provided, only these schemas are returned. Accepts a comma-separated list of slugs.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: false
      tags:
      - Schemas
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/EntitySchemaItem'
  /v1/entity/schemas/{slug}:
    get:
      operationId: getSchema
      summary: getSchema
      description: |
        Gets the latest version of the Schema.
        Pass ?id= to get a specific version by ID.
      tags:
      - Schemas
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - in: query
        name: id
        schema:
          $ref: '#/components/schemas/SchemaId'
      - in: query
        name: latest
        deprecated: true
        description: |
          No longer has any effect: schema freezing is retired and the latest version is always returned.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitySchemaItem'
        '404':
          $ref: '#/components/responses/NotFoundError'
    put:
      operationId: putSchema
      summary: putSchema
      description: |
        Create or update a schema with a new version.
      tags:
      - Schemas
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - in: query
        name: draft
        deprecated: true
        schema:
          default: false
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitySchema'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitySchemaItem'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
    delete:
      operationId: deleteSchema
      summary: deleteSchema
      description: Delete a schema, or a specific version of a schema
      tags:
      - Schemas
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      responses:
        '200':
          description: Success
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity/schemas/{slug}/json/schema:
    get:
      operationId: getJsonSchema
      summary: getJsonSchema
      description: Get formal JSON schema definition draft 2020-12 for the given epilot schema
      tags:
      - Schemas
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - in: query
        name: dereference
        schema:
          default: false
          type: boolean
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                example:
                  $schema: http://json-schema.org/draft/2020-12/schema
                  type: object
                  properties:
                    _id:
                      type: string
                      format: uuid
                      example: 123e4567-e89b-12d3-a456-426614174000
                    _org:
                      type: string
                      description: Organization Id the entity belongs to
                      readOnly: true
                    _owners:
                      type: array
                      readOnly: true
                      items:
                        description: |
                          The user / organization owning this entity.

                          Note: Owner implicitly has access to the entity regardless of ACLs.
                        type: object
                        properties:
                          org_id:
                            type: string
                            example: '123'
                          user_id:
                            type: string
                            example: '123'
                        required:
                        - org_id
                    _schema:
                      readOnly: true
                      type: string
                    _title:
                      readOnly: true
                      type: string
                    _tags:
                      type: array
                      nullable: true
                      items:
                        type: string
                    _manifest:
                      type: array
                      description: Manifest ID used to create/update the entity
                      items:
                        type: string
                        format: uuid
                        example: 123e4567-e89b-12d3-a456-426614174000
                    _created_at:
                      readOnly: true
                      type: string
                      format: date-time
                    _updated_at:
                      readOnly: true
                      type: string
                      format: date-time
                    _acl:
                      readOnly: true
                      type: object
                      description: Access control list (ACL) for an entity. Defines sharing access to external orgs or users.
                      additionalProperties: true
                      properties:
                        view:
                          type: array
                          items:
                            type: string
                            example: org:456
                        edit:
                          type: array
                          items:
                            type: string
                            example: org:456
                        delete:
                          type: array
                          items:
                            type: string
                            example: org:456
                    title:
                      type: string
                      nullable: true
                      enum:
                      - Dr.
                      - Prof.
                      - Prof. Dr.
                      - null
                    salutation:
                      type: string
                      nullable: true
                      enum:
                      - Mr.
                      - Ms. / Mrs.
                      - Company
                      - Contact Person
                      - Company/Contact Person
                      - Spouse
                      - Family
                      - Ownership
                      - Assembly
                      - Other
                      - null
                    first_name:
                      type: string
                    last_name:
                      type: string
                    customer_number:
                      type: string
                      nullable: true
                    birthdate:
                      type: string
                      format: date
                      nullable: true
                    account:
                      type: object
                      nullable: true
                      properties:
                        $relation:
                          type: array
                          items:
                            type: object
                            properties:
                              entity_id:
                                type: string
                                format: uuid
                                example: 123e4567-e89b-12d3-a456-426614174000
                              _tags:
                                type: array
                                nullable: true
                                items:
                                  type: string
                            required:
                            - entity_id
                      additionalProperties: true
                    address:
                      type: array
                      nullable: true
                      description: |
                        Addresses as a list of object, the element with index 0 is treated as the primary one.
                      items:
                        type: object
                        properties:
                          street:
                            type: string
                            nullable: true
                          street_number:
                            type: string
                            nullable: true
                          postal_code:
                            type: string
                            nullable: true
                          city:
                            type: string
                            nullable: true
                          country:
                            type: string
                            nullable: true
                            enum:
                            - DE
                            - AT
                            - CH
                            - null
                          additional_info:
                            type: string
                            nullable: true
                          _tags:
                            type: array
                            nullable: true
                            items:
                              type: string
                          _id:
                            type: string
                            example: xHcOoJCa07eysJ1GaQeSb
                        required:
                        - street
                        - street_number
                        - postal_code
                        - city
                        - country
                    email:
                      type: array
                      nullable: true
                      description: |
                        Email addresses as a list of object, the element with index 0 is treated as the primary one.
                      items:
                        type: object
                        properties:
                          _id:
                            type: string
                            example: xHcOoJCa07eysJ1GaQeSb
                          _tags:
                            type: array
                            nullable: true
                            items:
                              type: string
                          email:
                            type: string
                        required:
                        - email
                    phone:
                      type: array
                      description: |
                        Phone numbers as a list of object, the element with index 0 is treated as the primary one.
                      items:
                        type: object
                        properties:
                          _id:
                            type: string
                            example: xHcOoJCa07eysJ1GaQeSb
                          _tags:
                            type: array
                            nullable: true
                            items:
                              type: string
                          phone:
                            type: string
                        required:
                        - phone
                  required:
                  - first_name
                  - last_name
                  - _id
                  - _org
                  - _owners
                  - _schema
                  - _title
                  - _tags
                  - _created_at
                  - _updated_at
                  - _acl
  /v1/entity/schemas/{slug}/json/example:
    get:
      operationId: getSchemaExample
      summary: getSchemaExample
      description: Get a full example entity for the given schema
      tags:
      - Schemas
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              examples:
                contact:
                  $ref: '#/components/examples/ContactEntity'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity/schemas/{slug}/versions:
    get:
      operationId: getSchemaVersions
      summary: getSchemaVersions
      description: Get all versions of this schema ordered by the latest versions including drafts.
      tags:
      - Schemas
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - in: query
        name: versions_from
        schema:
          type: number
          default: 0
      - in: query
        name: versions_size
        schema:
          type: number
          default: 20
      - in: query
        name: drafts_from
        schema:
          type: number
          default: 0
      - in: query
        name: drafts_size
        schema:
          type: number
          default: 0
      - in: query
        name: fields
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
          example:
          - id
          - attributes
          - capabilites
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  versions:
                    type: array
                    items:
                      $ref: '#/components/schemas/EntitySchemaItem'
                  drafts:
                    deprecated: true
                    type: array
                    items:
                      $ref: '#/components/schemas/EntitySchemaItem'
                  versions_more:
                    description: 'Pagination: Whether more versions are available'
                    type: boolean
                  drafts_more:
                    deprecated: true
                    description: 'Pagination: Whether more drafts are available'
                    type: boolean
                  frozen_version:
                    deprecated: true
                    description: |
                      No longer returned: schema freezing is retired.
                    allOf:
                    - $ref: '#/components/schemas/SchemaId'
                required:
                - versions
                - versions_more
  /v1/entity/schemas/{slug}/freeze:
    post:
      operationId: freezeSchema
      summary: freezeSchema
      deprecated: true
      description: |
        Deprecated no-op: schema freezing is retired and every read returns the latest version.
        Returns the latest version of the schema unchanged. This endpoint will be removed.
      tags:
      - Schemas
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                version_id:
                  description: Freeze to a specific version ID. Defaults to the current version.
                  allOf:
                  - $ref: '#/components/schemas/SchemaId'
      responses:
        '200':
          description: Schema frozen successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitySchemaItem'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /v1/entity/schemas/{slug}/unfreeze:
    post:
      operationId: unfreezeSchema
      summary: unfreezeSchema
      deprecated: true
      description: |
        Deprecated: schema freezing is retired. Cleans up a leftover frozen pointer by promoting the
        latest version to the current version, and succeeds when there is nothing to clean up.
        This endpoint will be removed.
      tags:
      - Schemas
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      responses:
        '200':
          description: Schema unfrozen successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitySchemaItem'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /v1/entity/schemas/{slug}/capabilities/available:
    get:
      operationId: listAvailableCapabilities
      summary: listAvailableCapabilities
      description: List available capabilities for schema
      tags:
      - Schemas
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/EntityCapability'
  /v1/entity/schemas/blueprints:
    get:
      operationId: listSchemaBlueprints
      summary: listSchemaBlueprints
      description: List canonical versions of all available schemas
      tags:
      - Schemas
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/EntitySchemaItem'
  /v1/entity:search:
    post:
      operationId: searchEntities
      summary: searchEntities
      x-rate-limit:
        limit: 5000
        window: 60
        pool: search
      description: |
        Search for entities. Supports ordering and pagination. [Lucene query syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax) supported for complex querying.

        Passing comma-separated `x-epilot-org-id` is supported for cross-org entity search.

        ## Relations

        When `hydrate=true`, relation attributes are replaced in-place with nested entity values.

        Example:
        ```json
        {
          "_id": "123",
          "name": "parent",
          "_tags": ["parent"],
          "contacts": {
            "$relation": [
              { "entity_id": "456", "_tags": ["primary"] },
              { "entity_id": "789", "_tags": ["secondary"] },
            ]
          },
          "addresses": {
            "$relation_ref": [
              { "entity_id": "123", "_tags": ["primary"], "path": "address.0" },
              { "entity_id": "234", "_tags": ["secondary"], "path": "address.0" },
            ]
          }
        }
        ```

        Becomes:
        ```json
        {
          "_id": "123",
          "name": "parent",
          "_tags": ["parent"],
          "contacts": [
            {
              "$relation": { "entity_id": "456", "_tags": ["primary"] },
              "_id": "456",
              "name": "child 1",
              "_tags": ["child"]
            },
            {
              "$relation": { "entity_id": "789", "_tags": ["secondary"] },
              "_id": "789",
              "name": "child 2",
              "_tags": ["child"]
            }
          ],
          "addresses": [
            {
              "$relation_ref": { "entity_id": "123", "_tags": ["primary"], "path": "address.0" },
              "_id": "123",
              "address": "address 1",
              "_tags": ["child"]
            },
            {
              "$relation_ref": { "entity_id": "234", "_tags": ["secondary"], "path": "address.0" },
              "_id": "234",
              "address": "address 2",
              "_tags": ["child"]
            }
          ]
        }
        ```
      tags:
      - Entities
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitySearchParams'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitySearchResults'
            text/csv:
              schema:
                type: string
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity:list:
    post:
      operationId: listEntities
      summary: listEntities
      x-rate-limit:
        limit: 5000
        window: 60
        pool: search
      description: |
        List entities that meet the specified conditions.

        Supports the same options as entity search but utilizes filtering using a subset of [Elastic Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html) and does not perform scoring.
      tags:
      - Entities
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityListParams'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitySearchResults'
            text/csv:
              schema:
                type: string
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity:graph:
    post:
      operationId: queryEntityGraph
      summary: queryEntityGraph
      description: |
        Traverse an entity relationship graph starting from a seed entity.

        Define the shape of the graph using nodes (entity schemas) and edges (relationships with cardinality).
        The API will traverse the graph bidirectionally and return all discovered entity IDs.

        Example: Find all entities connected to a contact through portal_user -> contact -> billing_account -> files
      tags:
      - Entities
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQueryRequest'
      responses:
        '200':
          description: Graph traversal result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphQueryResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /v1/entity/{slug}:
    post:
      operationId: createEntity
      summary: createEntity
      description: |
        Creates a new entity using a key.

        ## Activity

        If no `activity_id` query parameter is provided, implicitly creates Activity of type `EntityCreated`

        ## Relations

        To create a relation, store a property object that defines a `$relation` array.

        Example:

        ```json
        {
          "contacts": {
            "$relation": [
              { "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }
            ]
          }
        }
        ```

        The items in `$relation` support two properties:
        - `entity_id` - The ID of the entity to link
        - `_tags` - Tags or labels for the relation (optional)
      tags:
      - Entities
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/ActivityIdQueryParam'
      - $ref: '#/components/parameters/FillActivityQueryParam'
      - $ref: '#/components/parameters/AsyncOperationQueryParam'
      - $ref: '#/components/parameters/ValidateEntityQueryParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Entity'
            examples:
              contact:
                $ref: '#/components/examples/ContactEntity'
              account:
                $ref: '#/components/examples/AccountEntity'
              product:
                $ref: '#/components/examples/ProductEntity'
              price:
                $ref: '#/components/examples/PriceEntity'
              tax:
                $ref: '#/components/examples/TaxEntity'
              order:
                $ref: '#/components/examples/OrderEntity'
              opportunity:
                $ref: '#/components/examples/OpportunityEntity'
              email template:
                $ref: '#/components/examples/EmailTemplateEntity'
              file:
                $ref: '#/components/examples/FileEntity'
              workflow step:
                $ref: '#/components/examples/WorkflowStepEntity'
              submission:
                $ref: '#/components/examples/SubmissionEntity'
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityItem'
        '422':
          description: Entity validation error when `?validate=true`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityValidationV2ResultError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity/{slug}:validate:
    post:
      operationId: validateEntity
      summary: validateEntity
      description: Validates an entity against the schema.
      tags:
      - Entities
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathPriceParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Entity'
            examples:
              Valid Price:
                $ref: '#/components/examples/PriceEntity'
              Invalid Price:
                $ref: '#/components/examples/EmptyGenericEntity'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityValidationResultSuccess'
        '422':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityValidationResultError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v2/entity/{slug}:validate:
    post:
      operationId: validateEntityV2
      summary: validateEntityV2
      description: Validates an entity against the schema.
      tags:
      - Entities
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathPriceParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Entity'
            examples:
              Valid Price:
                $ref: '#/components/examples/PriceEntity'
              Invalid Price:
                $ref: '#/components/examples/EmptyGenericEntity'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityValidationV2ResultSuccess'
        '422':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityValidationV2ResultError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity/{slug}:upsert:
    patch:
      operationId: upsertEntity
      summary: upsertEntity
      description: |
        Create or update an entity using `unique_key`

        - If no entities are matched, a new entity is created.
        - If exactly one entity is matched, a `PATCH`-style update is applied to the existing entity.

        ## Activity

        If no `activity_id` query parameter is provided, implicitly creates Activity of type `EntityCreated` or `EntityUpdated`
      tags:
      - Entities
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/ActivityIdQueryParam'
      - $ref: '#/components/parameters/FillActivityQueryParam'
      - $ref: '#/components/parameters/DryRunQueryParam'
      - $ref: '#/components/parameters/AsyncOperationQueryParam'
      - $ref: '#/components/parameters/ValidateEntityQueryParam'
      - name: strict
        description: Strict mode = return 409 if more than one entity is matched
        in: query
        required: false
        schema:
          type: boolean
          default: false
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                unique_key:
                  type: array
                  items:
                    type: string
                    example: email.0.email
                  example:
                  - _id
                entity:
                  $ref: '#/components/schemas/Entity'
              required:
              - unique_key
              - entity
      responses:
        '200':
          description: Entity was updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityItem'
        '201':
          description: Entity was created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityItem'
        '405':
          description: Deleted entities cannot be updated. You'll need to recover the entity first before updating.
        '409':
          description: 'Conflict: multiple entities were matched with `unique_key`'
        '422':
          description: Entity validation error when `?validate=true`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityValidationV2ResultError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v2/entity/{slug}/{id}:
    get:
      operationId: getEntityV2
      summary: getEntityV2
      description: |
        Gets Entity by id.

        Supports `hydrate` and `fields` parameters to control the shape of the response.
      tags:
      - Entities
      parameters:
      - $ref: '#/components/parameters/EntityIdPathParam'
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/HydrateEntitiesQueryParam'
      - $ref: '#/components/parameters/AnonymizeQueryParam'
      - in: query
        name: fields
        description: List of entity fields to include in results
        style: form
        explode: false
        schema:
          $ref: '#/components/schemas/FieldsParam'
      - $ref: '#/components/parameters/ApplyChangesetsQueryParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityItem'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /v1/entity/{slug}/{id}:restore:
    patch:
      operationId: restoreEntity
      summary: restoreEntity
      description: |
        Restores an entity by id

        ## Activity

        If no `activity_id` query parameter is provided, implicitly creates Activity of type `EntityRestore`
      tags:
      - Entities
      parameters:
      - $ref: '#/components/parameters/EntityIdPathParam'
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/ActivityIdQueryParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: This endpoint doesn't require a payload, but an empty object can be sent to satisfy certain HTTP clients.
      responses:
        '200':
          description: The restored entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityItem'
        '400':
          description: The entity is not deleted
        '404':
          description: The entity was not found
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity/{slug}/{id}:reindex:
    post:
      operationId: reindexEntity
      summary: reindexEntity
      description: |
        Triggers a reindex for the Entity for search.
      tags:
      - Entities
      parameters:
      - $ref: '#/components/parameters/EntityIdPathParam'
      - $ref: '#/components/parameters/EntitySlugPathParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: This endpoint doesn't require a payload, but an empty object can be sent to satisfy certain HTTP clients.
      responses:
        '200':
          description: The reindexed entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityItem'
        '404':
          description: The entity was not found
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
        '500':
          description: The entity could not be indexed
  /v1/entity/{slug}/{id}:
    get:
      operationId: getEntity
      summary: getEntity
      description: |
        Gets Entity and relations by id.

        ## Relations

        When `hydrate=true`, relation attributes are replaced in-place with nested entity values.

        Example:
        ```json
        {
          "_id": "123",
          "name": "parent",
          "_tags": ["parent"],
          "contacts": {
            "$relation": [
              { "entity_id": "456", "_tags": ["primary"] },
              { "entity_id": "789", "_tags": ["secondary"] },
            ]
          },
          "addresses": {
            "$relation_ref": [
              { "entity_id": "123", "_tags": ["primary"], "path": "address.0" },
              { "entity_id": "234", "_tags": ["secondary"], "path": "address.0" },
            ]
          }
        }
        ```

        Becomes:
        ```json
        {
          "_id": "123",
          "name": "parent",
          "_tags": ["parent"],
          "contacts": [
            {
              "$relation": { "entity_id": "456", "_tags": ["primary"] },
              "_id": "456",
              "name": "child 1",
              "_tags": ["child"]
            },
            {
              "$relation": { "entity_id": "789", "_tags": ["secondary"] },
              "_id": "789",
              "name": "child 2",
              "_tags": ["child"]
            }
          ],
          "addresses": [
            {
              "$relation_ref": { "entity_id": "123", "_tags": ["primary"], "path": "address.0" },
              "_id": "123",
              "address": "address 1",
              "_tags": ["child"]
            },
            {
              "$relation_ref": { "entity_id": "234", "_tags": ["secondary"], "path": "address.0" },
              "_id": "234",
              "address": "address 2",
              "_tags": ["child"]
            }
          ]
        }
        ```
      tags:
      - Entities
      parameters:
      - $ref: '#/components/parameters/EntityIdPathParam'
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/HydrateEntitiesQueryParam'
      - $ref: '#/components/parameters/AnonymizeQueryParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entity:
                    $ref: '#/components/schemas/EntityItem'
                  relations:
                    type: array
                    items:
                      $ref: '#/components/schemas/EntityItem'
        '404':
          $ref: '#/components/responses/NotFoundError'
    put:
      operationId: updateEntity
      summary: updateEntity
      description: |
        Updates an Entity

        ## Activity

        If no `activity_id` query parameter is provided, implicitly creates Activity of type `EntityUpdated`

        ## Relations

        To create a relation, store a property that defines a `$relation` array.

        Example:

        ```json
        {
          "contacts": {
            "$relation": [
              { "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }
            ]
          }
        }
        ```

        The items in `$relation` support two properties:
        - `entity_id` - The ID of the entity to link
        - `_tags` - Tags or labels for the relation (optional)
      tags:
      - Entities
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/EntityIdPathParam'
      - $ref: '#/components/parameters/ActivityIdQueryParam'
      - $ref: '#/components/parameters/FillActivityQueryParam'
      - $ref: '#/components/parameters/AsyncOperationQueryParam'
      - $ref: '#/components/parameters/ValidateEntityQueryParam'
      - $ref: '#/components/parameters/DirectQueryParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Entity'
            example: {}
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityItem'
        '422':
          description: Entity validation error when `?validate=true`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityValidationV2ResultError'
    patch:
      operationId: patchEntity
      summary: patchEntity
      description: |
        Partially updates an entity with the passed in entity data.

        - If an _updated_at is passed and the server contains a newer version of the entity a `409` Error is returned

        ## Activity

        If no `activity_id` query parameter is provided, implicitly creates Activity of type `EntityUpdated`

        ## Relations

        To create a relation, store a property that defines a `$relation` array.

        Example:

        ```json
        {
          "contacts": {
            "$relation": [
              { "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }
            ]
          }
        }
        ```

        The items in `$relation` support two properties:
        - `entity_id` - The ID of the entity to link
        - `_tags` - Tags or labels for the relation (optional)
      tags:
      - Entities
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/EntityIdPathParam'
      - $ref: '#/components/parameters/ActivityIdQueryParam'
      - $ref: '#/components/parameters/FillActivityQueryParam'
      - $ref: '#/components/parameters/DryRunQueryParam'
      - $ref: '#/components/parameters/AsyncOperationQueryParam'
      - $ref: '#/components/parameters/ValidateEntityQueryParam'
      - $ref: '#/components/parameters/DirectQueryParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Entity'
            example: {}
        required: true
      responses:
        '200':
          description: Entity was updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityItem'
        '409':
          description: 'Conflict: newer version exists'
        '422':
          description: Entity validation error when `?validate=true`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityValidationV2ResultError'
    delete:
      operationId: deleteEntity
      summary: deleteEntity
      description: |
        Deletes an Entity

        ## Activity

        If no `activity_id` query parameter is provided, implicitly creates Activity of type `EntityDeleted`

        ## Deletion Mode

        All entities are soft deleted by default. To force an actual deletion from the system, provide `purge:true` to delete the entity and all its activity history permanently.
      tags:
      - Entities
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/EntityIdPathParam'
      - $ref: '#/components/parameters/ActivityIdQueryParam'
      - in: query
        name: purge
        description: Permanently deletes the entity when set to `true`
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Success
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity:autocomplete:
    get:
      operationId: autocomplete
      summary: autocomplete
      description: |
        Autocomplete entity attributes
      tags:
      - Entities
      parameters:
      - $ref: '#/components/parameters/AnonymizeQueryParam'
      - name: input
        in: query
        description: Input to autocomplete
        schema:
          type: string
      - name: attribute
        in: query
        description: Autocomplete attribute
        schema:
          type: string
          example: _tags
        required: true
      - name: slug
        in: query
        description: Limit results to entity schema
        schema:
          $ref: '#/components/schemas/EntitySlug'
      - name: size
        in: query
        description: Maximum number of results to return
        schema:
          type: integer
          default: 10
          minimum: 1
          maximum: 250
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  hits:
                    type: number
                    example: 1
                  results:
                    type: array
                    items:
                      anyOf:
                      - type: string
                      - type: boolean
                      - type: object
                        additionalProperties: true
                    example:
                    - value
  /v1/entity:wipeAllEntities:
    post:
      operationId: wipeAllEntities
      summary: wipeAllEntities
      description: |
        Creates a request to queue the deletion of all entities in the system. This is a destructive operation and should only be used in sandbox environments.
      tags:
      - Entities
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                schemas:
                  type: array
                  items:
                    $ref: '#/components/schemas/EntitySlug'
      responses:
        '201':
          description: Wipe request was created
  /v1/entity/activity:
    post:
      operationId: createActivity
      summary: createActivity
      description: |
        Create an activity that can be displayed in activity feeds.

        - All activites are published as events on the event bus
        - Entity mutations are always part of an activity
        - When more than 10 entities are passed, the first 10 are attached synchronously and the rest are processed asynchronously to avoid DynamoDB throttling
      tags:
      - Activity
      parameters:
      - in: query
        name: entities
        description: Comma-separated list of entities which the activity primarily concerns
        style: form
        explode: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/EntityId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Activity'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseActivityItem'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity/activity/{id}:
    get:
      operationId: getActivity
      summary: getActivity
      description: Get activity by id
      tags:
      - Activity
      parameters:
      - $ref: '#/components/parameters/AnonymizeQueryParam'
      - $ref: '#/components/parameters/ActivityIdPathParam'
      - in: query
        name: operations_size
        description: |
          Maximum number of operations to include in response (default: 10)
        schema:
          type: integer
          minimum: 0
          maximum: 1000
          default: 25
      - in: query
        name: operations_from
        description: |
          Pagination offset for operations
        schema:
          type: integer
          minimum: 0
          default: 0
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivityItem'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /v1/entity/activity/{id}:attach:
    post:
      operationId: attachActivity
      summary: attachActivity
      description: Attach existing activity to entity activity feeds
      tags:
      - Activity
      parameters:
      - $ref: '#/components/parameters/ActivityIdPathParam'
      - in: query
        name: entities
        description: Comma-separated list of entities which the activity primarily concerns
        style: form
        explode: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/EntityId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseActivityItem'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity/{slug}/{id}/changesets/{attribute}:apply:
    post:
      operationId: applyChangeset
      summary: applyChangeset
      description: |
        Applies the proposed value from a pending changeset to the entity attribute
        and removes the changeset. Used for human approval of pending changes.
      tags:
      - Entities
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/EntityIdPathParam'
      - in: path
        name: attribute
        required: true
        description: Attribute name of the changeset to apply
        schema:
          type: string
      responses:
        '200':
          description: Changeset applied successfully — returns updated entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityItem'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /v1/entity/{slug}/{id}/changesets/{attribute}:dismiss:
    post:
      operationId: dismissChangeset
      summary: dismissChangeset
      description: |
        Removes a pending changeset without applying it. The attribute value remains unchanged.
      tags:
      - Entities
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/EntityIdPathParam'
      - in: path
        name: attribute
        required: true
        description: Attribute name of the changeset to dismiss
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: Optional reason for dismissing the changeset
      responses:
        '200':
          description: Changeset dismissed successfully — returns updated entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityItem'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /v1/entity/{slug}/{id}/changesets:
    get:
      operationId: listChangesets
      summary: listChangesets
      description: Returns all pending changesets for an entity.
      tags:
      - Entities
      parameters:
      - $ref: '#/components/parameters/AnonymizeQueryParam'
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/EntityIdPathParam'
      responses:
        '200':
          description: Pending changesets for the entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangesetMap'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /v1/entity/{slug}/{id}/activity:
    get:
      operationId: getEntityActivityFeed
      summary: getEntityActivityFeed
      description: |
        Get activity feed for an entity
      tags:
      - Activity
      parameters:
      - $ref: '#/components/parameters/AnonymizeQueryParam'
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/EntityIdPathParam'
      - in: query
        name: after
        description: Get activities strictly after this timestamp. Cannot be used with 'before', 'start_date', 'end_date', or 'preset_range'.
        schema:
          type: string
          format: date-time
      - in: query
        name: before
        description: Get activities strictly before this timestamp. Cannot be used with 'after', 'start_date', 'end_date', or 'preset_range'.
        schema:
          type: string
          format: date-time
      - in: query
        name: start_date
        description: The inclusive start timestamp for a date range filter. Requires 'end_date' to also be provided. Cannot be used with 'before', 'after', or 'preset_range'.
        schema:
          type: string
          format: date-time
      - in: query
        name: end_date
        description: The inclusive end timestamp for a date range filter. Requires 'start_date' to also be provided. Cannot be used with 'before', 'after', or 'preset_range'.
        schema:
          type: string
          format: date-time
      - in: query
        name: preset_range
        description: Get activities within a predefined date range (e.g., 'today', 'last_week'). Cannot be used with 'before', 'after', 'start_date', or 'end_date'.
        schema:
          type: string
          example: last_week
          enum:
          - today
          - this_week
          - last_week
      - $ref: '#/components/parameters/FromPageQueryParam'
      - in: query
        name: size
        description: max number of results to return
        schema:
          type: integer
          minimum: 1
          default: 25
      - in: query
        name: type
        description: Filter by activity type(s)
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
          example:
          - EntityUpdated
          - EntityCreated
      - in: query
        name: include_relations
        description: Include activities from related entities
        schema:
          type: boolean
          default: false
      - in: query
        name: exclude_activity_groups
        description: Exclude all activity types that are part of an activity group from results
        schema:
          type: string
          example: workflow
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    example: 1
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ActivityItem'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /v1/entity/{slug}/{id}/relations:
    get:
      operationId: getRelations
      summary: getRelations
      description: |
        Returns 1st level direct relations for an entity.

        You can control whether to return the full entity or just the relation item with the `?hydrate` query param.

        Reverse relations i.e. entities referring to this entity are included with the `?include_reverse` query param.
      tags:
      - Relations
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/EntityIdPathParam'
      - $ref: '#/components/parameters/HydrateEntitiesQueryParam'
      - $ref: '#/components/parameters/AnonymizeQueryParam'
      - $ref: '#/components/parameters/IncludeReverseQueryParam'
      - $ref: '#/components/parameters/FromPageQueryParam'
      - in: query
        name: size
        description: Number of results to return per page
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 100
      - $ref: '#/components/parameters/IncludeSchemasQueryParam'
      - $ref: '#/components/parameters/ExcludeSchemasQueryParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRelationsResp'
              example:
              - attribute: contacts
                entity_id: ed27830b-984c-4bca-9b87-2849bb5789ca
                _tags:
                - primary
                - billing
              - attribute: contacts
                entity_id: fadfc950-6e43-4e38-bae0-ffcf4b8b90e1
              - _id: 9924c4de-d3ed-4752-821d-fc0b9bd57c1b
                _title: John Doe
                attribute: contacts
                entity_id: 9924c4de-d3ed-4752-821d-fc0b9bd57c1b
                order_number: a34234jd
                customer_email: johndoe@epilot.cloud
                billing_first_name: john
                billing_last_name: doe
                billing_company_name: ePilot Gmbh
                billing_vat: 234823948,
                billing_email: johndoe@nowhere.com
                billing_phone: 1234234545,
                billing_address: wallstreet, 1
                billing_contact: villy or zilly
                $relation:
                  attribute: orders
                  entity_id: 9924c4de-d3ed-4752-821d-fc0b9bd57c1b
                  _tags:
                  - solar_panel
                  - one_time
        '404':
          $ref: '#/components/responses/NotFoundError'
    post:
      operationId: addRelations
      summary: addRelations
      description: Relates one or more entities to parent entity by adding items to a relation attribute
      tags:
      - Relations
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/EntityIdPathParam'
      - $ref: '#/components/parameters/AsyncOperationQueryParam'
      - $ref: '#/components/parameters/ActivityIdQueryParam'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/RelationItem'
            example:
            - attribute: contacts
              entity_id: e8878f62-2d3d-4c86-bfe7-01a4180ff048
              _tags:
              - billing
            - attribute: contacts
              entity_id: ee8a2af9-fb36-4981-b848-4e65275851af
            - attribute: opportunities
              entity_id: 30990430-a53d-41a2-83db-2de072dc4dd4
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelationItem'
        '404':
          $ref: '#/components/responses/NotFoundError'
    delete:
      operationId: removeRelations
      summary: removeRelations
      description: Disassociate one or more entities to parent entity by removing items to a relation attribute
      tags:
      - Relations
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/EntityIdPathParam'
      - $ref: '#/components/parameters/AsyncOperationQueryParam'
      - $ref: '#/components/parameters/ActivityIdQueryParam'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/RelationItem'
            example:
            - attribute: contacts
              entity_id: e8878f62-2d3d-4c86-bfe7-01a4180ff048
              _tags:
              - billing
            - attribute: contacts
              entity_id: ee8a2af9-fb36-4981-b848-4e65275851af
            - attribute: opportunities
              entity_id: 30990430-a53d-41a2-83db-2de072dc4dd4
      responses:
        '204':
          description: Relations deleted with success.
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v2/entity/{slug}/{id}/relations:
    get:
      operationId: getRelationsV2
      summary: getRelationsV2
      description: |
        Returns 1st level direct relations for an entity with pagination.

        You can control whether to return the full entity or just the relation item with the `?hydrate` query param.

        Reverse relations i.e. entities referring to this entity are included with the `?include_reverse` query param.
      tags:
      - Relations
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/EntityIdPathParam'
      - $ref: '#/components/parameters/HydrateEntitiesQueryParam'
      - $ref: '#/components/parameters/AnonymizeQueryParam'
      - in: query
        name: query
        description: Input to filter search results
        schema:
          type: string
      - $ref: '#/components/parameters/IncludeReverseQueryParam'
      - $ref: '#/components/parameters/FromPageQueryParam'
      - in: query
        name: size
        description: Number of results to return per page
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 50
      - in: query
        name: fields
        description: List of entity fields to include in results
        schema:
          $ref: '#/components/schemas/FieldsParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRelationsRespWithPagination'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /v3/entity/{slug}/{id}/relations:
    get:
      operationId: getRelationsV3
      summary: getRelationsV3
      description: |
        Returns 1st level direct relations for an entity with pagination.

        You can control whether to return the full entity or just the relation item with the `?hydrate` query param.

        Reverse relations i.e. entities referring to this entity are included with the `?include_reverse` query param.
      tags:
      - Relations
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/EntityIdPathParam'
      - $ref: '#/components/parameters/HydrateEntitiesQueryParam'
      - $ref: '#/components/parameters/AnonymizeQueryParam'
      - $ref: '#/components/parameters/IncludeReverseDeprecatedQueryParam'
      - $ref: '#/components/parameters/FromPageQueryParam'
      - in: query
        name: size
        description: Number of results to return per page
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 100
      - $ref: '#/components/parameters/IncludeSchemasQueryParam'
      - $ref: '#/components/parameters/ExcludeSchemasQueryParam'
      - $ref: '#/components/parameters/EntityRelationsModeQueryParam'
      - in: query
        name: fields
        description: List of entity fields to include in results
        schema:
          $ref: '#/components/schemas/FieldsParam'
      - in: query
        name: include_deleted
        description: |
          Whether to include relations to/from deleted entities
          - `true`: include relations to/from deleted entities
          - `false`: exclude relations to/from deleted entities (default)
          - `only`: include only relations to/from deleted entities
        required: false
        schema:
          $ref: '#/components/schemas/EntitySearchIncludeDeletedParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRelationsRespWithPagination'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /v2/entity/{slug}/{id}/relations/count:
    get:
      operationId: getRelatedEntitiesCount
      summary: getRelatedEntitiesCount
      description: |
        Returns the amount of unique related entities for an entity - includes direct and reverse relations.
      tags:
      - Relations
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/EntityIdPathParam'
      - $ref: '#/components/parameters/ExcludeSchemasQueryParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRelatedEntitiesCount'
        '404':
          $ref: '#/components/responses/NotFoundError'
  /v1/entity/{slug}/{id}/relations/{attribute}/{entity_id}:
    put:
      operationId: updateRelation
      summary: updateRelation
      description: Updates an existing relation between two entities.
      tags:
      - Relations
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/EntityIdPathParam'
      - in: path
        name: attribute
        description: The attribute that express meaning
        required: true
        schema:
          type: string
      - in: path
        name: entity_id
        description: The attribute that express meaning
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/AsyncOperationQueryParam'
      - $ref: '#/components/parameters/ActivityIdQueryParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                _tags:
                  type: array
                  items:
                    type: string
            example:
              _tags:
              - billing
              - prepaid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelationItem'
        '404':
          $ref: '#/components/responses/NotFoundError'
    delete:
      operationId: deleteRelation
      summary: deleteRelation
      description: Removes relation between two entities
      tags:
      - Relations
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/EntityIdPathParam'
      - in: path
        name: attribute
        description: The attribute that express meaning
        required: true
        schema:
          type: string
      - in: path
        name: entity_id
        description: The attribute that express meaning
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/AsyncOperationQueryParam'
      - $ref: '#/components/parameters/ActivityIdQueryParam'
      responses:
        '204':
          description: Relation deleted with success.
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity:export:
    post:
      operationId: exportEntities
      summary: exportEntities
      description: |
        Export entity data in a CSV-format. The export will export data as close as possible to what is visible on Entity UI tables.
        The values exported as in some cases, transformed to human-readable values.

        To force the export of raw values, use the `#` prefix in front of your field name when specifying the field on the `fields` param.
      tags:
      - Import-Export
      parameters:
      - in: query
        name: job_id
        description: Export Job Id to get the result
        schema:
          $ref: '#/components/schemas/ExportJobId'
      - in: query
        name: is_template
        description: Pass 'true' to generate import template
        schema:
          $ref: '#/components/schemas/IsTemplate'
      - in: query
        name: language
        description: Export headers translation language
        schema:
          $ref: '#/components/schemas/Language'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitySearchParams'
      responses:
        '201':
          description: created export url and download url
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity:import:
    post:
      operationId: importEntities
      summary: Import Entities
      description: |
        This endpoint enables the import of entities into the platform.
        The entities should be provided in a CSV format inside an S3 bucket.
        This API will return the `job_id`` which can be used to fetch the status of the import process.
      tags:
      - Import-Export
      parameters:
      - in: query
        name: job_id
        description: The ID of the import job. This ID is used to track the progress and fetch the result of the import operation.
        schema:
          $ref: '#/components/schemas/ExportJobId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityImportParams'
      responses:
        '201':
          description: |
            The import operation was initiated successfully.
            The response includes the URLs for the files containing the successful and failed imported entities.
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity:abortImport:
    post:
      operationId: abortEntityImport
      summary: Abort a running entity import
      description: |
        Asks a running import to stop. Rows already imported are **kept** - this is a stop, not a
        rollback - and the job still produces its result reports for everything that landed before
        the stop, then reaches the terminal status `CANCELLED`.

        The stop is cooperative: the worker notices the request at its next batch boundary, so the
        job typically reaches `CANCELLED` within seconds. Poll `POST /v1/entity:import` with the
        `job_id` as usual to observe it.

        Idempotent - aborting an already-aborted or already-finished job is not an error.
      tags:
      - Import-Export
      parameters:
      - in: query
        name: job_id
        required: true
        description: The ID of the import job to stop.
        schema:
          $ref: '#/components/schemas/ExportJobId'
      - in: query
        name: schema
        required: true
        description: Slug of the schema being imported, used to authorize the caller.
        schema:
          type: string
      responses:
        '202':
          description: |
            The stop was requested. The job is still running until the worker picks the request up.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: The job status at the time of the request.
                  jobPollId:
                    type: string
        '400':
          description: Bad Request
        '403':
          description: Forbidden
        '404':
          description: No such import job
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity/views:
    get:
      operationId: listSavedViews
      summary: listSavedViews
      description: Get the Saved Views based on the schema
      tags:
      - Saved Views
      parameters:
      - in: query
        name: slug
        description: Return views belonging to this schema
        required: false
        schema:
          $ref: '#/components/schemas/EntitySlug'
      - in: query
        name: sort
        description: The sort key to use if present
        required: false
        schema:
          type: string
          default: name:asc
      - in: query
        name: from
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
      - in: query
        name: size
        description: Number of saved views to return
        required: false
        schema:
          type: integer
          default: 80
          minimum: 1
          maximum: 250
      - in: query
        name: q
        description: Free-text search on the saved view name (case-insensitive)
        required: false
        schema:
          type: string
      - in: query
        name: fields
        required: false
        schema:
          $ref: '#/components/schemas/FieldsParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSavedViewsResults'
  /v1/entity/view:
    post:
      operationId: createSavedView
      summary: createSavedView
      description: Creates a new saved view
      tags:
      - Saved Views
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavedView'
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedViewItem'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity/view/{id}:
    get:
      operationId: getSavedView
      summary: getSavedView
      description: Gets Saved View configuration by id.
      tags:
      - Saved Views
      parameters:
      - $ref: '#/components/parameters/SavedViewIdPathParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedViewItem'
        '404':
          $ref: '#/components/responses/NotFoundError'
    put:
      operationId: updateSavedView
      summary: updateSavedView
      description: Updates a saved view
      tags:
      - Saved Views
      parameters:
      - $ref: '#/components/parameters/SavedViewIdPathParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavedViewItem'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedViewItem'
    patch:
      operationId: patchSavedView
      summary: patchSavedView
      description: Partially updates a saved view with the provided payload. If an updated_at is passed and the server contains a newer version of the view a `409` error is returned
      tags:
      - Saved Views
      parameters:
      - $ref: '#/components/parameters/SavedViewIdPathParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavedViewPartial'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedViewItem'
    delete:
      operationId: deleteSavedView
      summary: deleteSavedView
      description: Deletes a saved view
      parameters:
      - $ref: '#/components/parameters/SavedViewIdPathParam'
      tags:
      - Saved Views
      responses:
        '200':
          description: The saved view was deleted
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity/views/favorites:
    get:
      operationId: listFavoriteViewsForUser
      summary: listFavoriteViewsForUser
      description: Get the Favorite Saved Views for user based on the schema
      tags:
      - Saved Views
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/SavedViewItem'
  /v1/entity/taxonomies:
    get:
      operationId: listTaxonomies
      summary: listTaxonomies
      description: List taxonomies in an organization
      parameters:
      - in: query
        name: include_disabled
        description: Include disabled taxonomies
        schema:
          type: boolean
          default: false
      - in: query
        name: type
        description: Type of taxonomy to include
        schema:
          type: string
          enum:
          - entity
          - relation
          default: entity
      tags:
      - Taxonomy
      responses:
        '200':
          description: Returns list of taxonomies in an organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Taxonomy'
    post:
      operationId: createTaxonomy
      summary: createTaxonomy
      description: Create a new taxonomy
      tags:
      - Taxonomy
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Taxonomy'
      responses:
        '201':
          description: Taxonomy created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Taxonomy'
        '409':
          description: Taxonomy already exists
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity/taxonomies/{taxonomySlug}:
    get:
      operationId: getTaxonomy
      summary: getTaxonomy
      description: Get taxonomy by slug
      tags:
      - Taxonomy
      parameters:
      - $ref: '#/components/parameters/TaxonomySlugPathParam'
      responses:
        '200':
          description: Taxonomy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Taxonomy'
        '404':
          $ref: '#/components/responses/NotFoundError'
    put:
      operationId: updateTaxonomy
      summary: updateTaxonomy
      description: Update a taxonomy
      tags:
      - Taxonomy
      parameters:
      - $ref: '#/components/parameters/TaxonomySlugPathParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Taxonomy'
      responses:
        '200':
          description: Taxonomy updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Taxonomy'
    delete:
      operationId: deleteTaxonomy
      summary: deleteTaxonomy
      description: Delete a taxonomy
      tags:
      - Taxonomy
      parameters:
      - $ref: '#/components/parameters/TaxonomySlugPathParam'
      - in: query
        x-implemented: false
        name: permanent
        description: ⚠️ NOT IMPLEMENTED - If true, the taxonomy will be permanently deleted
        schema:
          type: boolean
          default: false
      responses:
        '204':
          description: Taxonomy deleted
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity/taxonomies/{taxonomySlug}/classifications:
    post:
      operationId: updateClassificationsForTaxonomy
      summary: updateClassificationsForTaxonomy
      description: Update the classifications for a taxonomy
      tags:
      - Taxonomy
      parameters:
      - $ref: '#/components/parameters/TaxonomySlugPathParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClassificationsUpdate'
      responses:
        '200':
          description: Taxonomies classifications
          content:
            application/json:
              schema:
                type: object
                properties:
                  created:
                    type: array
                    items:
                      $ref: '#/components/schemas/TaxonomyClassification'
                  updated:
                    type: array
                    items:
                      $ref: '#/components/schemas/TaxonomyClassification'
                  deleted:
                    type: array
                    items:
                      $ref: '#/components/schemas/ClassificationId'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v2/entity/taxonomies/classifications:
    post:
      operationId: createTaxonomyClassification
      summary: createTaxonomyClassification
      description: |
        Create a new classification for a taxonomy
      tags:
      - Taxonomy
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxonomyClassification'
      responses:
        '201':
          description: Created taxonomy classification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxonomyClassification'
        '409':
          description: Taxonomy classification already exists
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v2/entity/taxonomies/classifications/{classificationSlug}:
    get:
      operationId: getTaxonomyClassification
      summary: getTaxonomyClassification
      description: |
        Get a classification for a taxonomy by slug

        For backwards compatibility with purposes, you can also pass the classification id instead of the slug.
      tags:
      - Taxonomy
      parameters:
      - $ref: '#/components/parameters/TaxonomyClassificationSlugPathParam'
      responses:
        '200':
          description: Taxonomy classification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxonomyClassification'
        '404':
          $ref: '#/components/responses/NotFoundError'
    put:
      operationId: updateTaxonomyClassification
      summary: updateTaxonomyClassification
      description: Update a classification for a taxonomy
      tags:
      - Taxonomy
      parameters:
      - $ref: '#/components/parameters/TaxonomyClassificationSlugPathParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxonomyClassification'
      responses:
        '200':
          description: Taxonomy classification updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxonomyClassification'
        '404':
          description: Taxonomy classification not found
    delete:
      operationId: deleteTaxonomyClassification
      summary: deleteTaxonomyClassification
      description: Delete a classification for a taxonomy
      tags:
      - Taxonomy
      parameters:
      - $ref: '#/components/parameters/TaxonomyClassificationSlugPathParam'
      responses:
        '200':
          description: Taxonomy classification deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxonomyClassification'
        '403':
          description: Taxonomy classification deletion not allowed
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity/taxonomies/{taxonomySlug}:autocomplete:
    get:
      operationId: taxonomyAutocomplete
      summary: taxonomyAutocomplete
      description: Taxonomies autocomplete
      tags:
      - Taxonomy
      parameters:
      - $ref: '#/components/parameters/TaxonomySlugPathParam'
      - in: query
        name: query
        description: Input to autocomplete
        schema:
          type: string
      - in: query
        name: size
        description: Minimum number of results to return
        schema:
          type: number
      responses:
        '200':
          description: Taxonomy classifications
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/TaxonomyClassification'
  /v1/entity/taxonomies/classifications:search:
    post:
      operationId: taxonomiesClassificationsSearch
      summary: taxonomiesClassificationsSearch
      description: List taxonomy classifications in an organization based on taxonomy slug
      tags:
      - Taxonomy
      parameters:
      - in: query
        name: taxonomySlug
        description: |
          The taxonomy slug(s) to search within. When provided with multiple taxonomy slugs, the search will be performed across all the provided taxonomies.
        schema:
          anyOf:
          - type: string
          - type: array
            items:
              type: string
      - in: query
        name: query
        description: The label names to search for (lowercase insensitive)
        schema:
          type: string
          example: sales
      - in: query
        name: archived
        description: Filter by archived status. Deprecated. Use `include_archived` instead.
        deprecated: true
        schema:
          type: boolean
          example: false
      - in: query
        name: include_archived
        schema:
          $ref: '#/components/schemas/TaxonomySearchIncludeArchivedParam'
      - in: query
        name: exclude_types
        description: |
          Taxonomy type(s) to exclude from the results. Useful to filter out relation labels, schema labels, and system labels.
        schema:
          anyOf:
          - type: string
            enum:
            - relation
            - schema
            - system
          - type: array
            items:
              type: string
              enum:
              - relation
              - schema
              - system
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                classificationIds:
                  type: array
                  items:
                    $ref: '#/components/schemas/ClassificationIdOrPattern'
      responses:
        '200':
          description: Returns the classifications for the taxonomy slug provided
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/TaxonomyClassification'
                  hits:
                    type: integer
                    example: 10
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity/schemas/{slug}/taxonomy/{taxonomySlug}:
    get:
      operationId: listTaxonomyClassificationsForSchema
      summary: listTaxonomyClassificationsForSchema
      description: List taxonomy classifications for a given schema
      tags:
      - Schemas
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/TaxonomySlugPathParam'
      - in: query
        name: query
        schema:
          type: string
      - in: query
        name: size
        schema:
          type: number
      responses:
        '200':
          description: List of taxonomy classifications
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/TaxonomyClassification'
  /v1/entity/taxonomies/bulk-jobs:
    get:
      operationId: getTaxonomyBulkActionJobs
      summary: getTaxonomyBulkActionJobs
      description: |
        Gets bulk actions jobs by job status:
        - <undefined> = all active jobs
        - PENDING = all active jobs
        - FAILED = all failed jobs
        - COMPLETED = all completed jobs
      tags:
      - Taxonomy
      parameters:
      - in: query
        description: The status of the jobs to return
        name: status
        schema:
          description: A comma separated list of job statuses to return
          type: array
          items:
            type: string
      - in: query
        name: size
        schema:
          description: The maximum number of jobs to return (defaults to 20)
          type: number
          default: 20
      - in: query
        name: created_after
        schema:
          description: ISO 8601 timestamp to filter jobs created after this time (e.g., 2023-01-01T00:00:00Z).
          type: string
          format: date-time
          example: 2023-01-01T00:00:00.000Z
      - in: query
        name: sort_pending_first
        schema:
          description: When true, sorts PENDING status jobs to the top of the results.
          type: boolean
          default: false
      - in: query
        name: scope
        schema:
          description: Scope of jobs to return. 'me' returns only jobs created by the current user, 'all' returns jobs from all users in the organization.
          type: string
          enum:
          - me
          - all
          default: me
      responses:
        '200':
          description: Returns the jobs matching the given query or the active jobs if no status is provided
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TaxonomyBulkJob'
  /v1/entity/taxonomies/bulk-jobs/{job_id}:
    get:
      operationId: getTaxonomyBulkActionJobById
      summary: getTaxonomyBulkActionJobById
      description: Gets a bulk action job by job id
      tags:
      - Taxonomy
      parameters:
      - in: path
        name: job_id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns the job matching the given job id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxonomyBulkJob'
  /v1/entity/taxonomies/bulk-jobs/{job_id}/cancel:
    post:
      operationId: cancelBulkAction
      summary: cancelBulkAction
      description: |
        Cancels a running bulk action job. The job status will be updated to CANCELLED
        and the job will be stopped.
      tags:
      - Taxonomy
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
        description: Job ID of the bulk operation to cancel
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxonomyBulkJob'
        '400':
          description: Bad Request
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
        '500':
          description: Internal Server Error
  /v1/entity/taxonomies/classifications:move:
    post:
      operationId: bulkMoveClassifications
      summary: bulkMoveClassifications
      description: |
        Moves classifications from one taxonomy to another, through a bulk async operation which
        also updates all references from the old classification to the new one under the target taxonomy.
      tags:
      - Taxonomy
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                job_id:
                  description: Job ID for tracking the status of a bulk operation request
                  type: string
                target_taxonomy:
                  allOf:
                  - description: The target taxonomy to which the classifications will be moved
                  - $ref: '#/components/schemas/TaxonomySlug'
                classification_ids:
                  type: array
                  items:
                    $ref: '#/components/schemas/ClassificationId'
            example:
              classification_ids:
              - taxonomy-slug:classification-slug
      responses:
        '200':
          description: Returns the job id for the async job and current status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxonomyBulkJobTriggerResponse'
              example:
                job_id: 5684fcb1-62ef-45e4-9187-ebf96dcbff12
                status: PENDING
        '400':
          description: Invalid request
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity/taxonomies/classifications:merge:
    post:
      operationId: bulkMergeClassifications
      summary: bulkMergeClassifications
      description: |
        Merges classifications from one taxonomy into one individual classification, through a bulk async operation which
        also updates all references from the old Classifications to the new one.
      tags:
      - Taxonomy
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                job_id:
                  description: Job ID for tracking the status of a bulk operation request
                  type: string
                target_classification:
                  allOf:
                  - description: The target classification id to which the classifications will be merged into
                  - $ref: '#/components/schemas/TaxonomySlug'
                classification_ids:
                  type: array
                  items:
                    $ref: '#/components/schemas/ClassificationId'
            example:
              classification_ids:
              - taxonomy-slug:classification-slug
      responses:
        '200':
          description: Returns the job id for the async job and current status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxonomyBulkJobTriggerResponse'
              example:
                job_id: 5684fcb1-62ef-45e4-9187-ebf96dcbff12
                status: PENDING
        '400':
          description: Invalid request
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity/taxonomies/classifications:delete:
    post:
      operationId: bulkDeleteClassifications
      summary: bulkDeleteClassifications
      description: |
        Permanently deletes taxonomy classifications. The classifications are deleted through a bulk
        async operation which also deletes all references of the deleted classifications from the entities
        referencing them.
      tags:
      - Taxonomy
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                job_id:
                  description: Job ID for tracking the status of a bulk operation request
                  type: string
                classification_ids:
                  type: array
                  items:
                    $ref: '#/components/schemas/ClassificationId'
            example:
              classification_ids:
              - taxonomy-slug:classification-slug
      responses:
        '200':
          description: Returns the job id for the async job and current status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxonomyBulkJobTriggerResponse'
              example:
                job_id: 5684fcb1-62ef-45e4-9187-ebf96dcbff12
                status: PENDING
        '400':
          description: Invalid request
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity/schemas/attributes:
    post:
      operationId: createSchemaAttribute
      summary: createSchemaAttribute
      description: Create a schema attribute
      tags:
      - Schemas
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttributeWithCompositeID'
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeWithCompositeID'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity/schemas/attributes/{composite_id}:
    get:
      operationId: getSchemaAttribute
      summary: getSchemaAttribute
      description: Get a schema attribute from given attribute ID
      tags:
      - Schemas
      parameters:
      - name: composite_id
        description: Schema Slug and the Attribute ID
        in: path
        required: true
        schema:
          type: string
          pattern: ^.+:.+$
          example: contact:97644baa-083f-4e49-9188-fcff2ecaad7d
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeWithCompositeID'
        '404':
          $ref: '#/components/responses/NotFoundError'
    put:
      operationId: putSchemaAttribute
      summary: putSchemaAttribute
      description: Updates an attribute in the schema
      tags:
      - Schemas
      parameters:
      - name: composite_id
        description: Schema Slug and the Attribute ID
        in: path
        required: true
        schema:
          type: string
          pattern: ^.+:.+$
          example: contact:97644baa-083f-4e49-9188-fcff2ecaad7d
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttributeWithCompositeID'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeWithCompositeID'
    delete:
      operationId: deleteSchemaAttribute
      summary: deleteSchemaAttribute
      description: Deletes an attribute from a schema
      tags:
      - Schemas
      parameters:
      - name: composite_id
        description: Schema Slug and the Attribute ID
        in: path
        required: true
        schema:
          type: string
          pattern: ^.+:.+$
          example: contact:97644baa-083f-4e49-9188-fcff2ecaad7d
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttributeWithCompositeID'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity/schemas/capabilities:
    post:
      operationId: createSchemaCapability
      summary: createSchemaCapability
      description: Create a schema capability
      tags:
      - Schemas
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityCapabilityWithCompositeID'
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityCapabilityWithCompositeID'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity/schemas/capabilities/{composite_id}:
    get:
      operationId: getSchemaCapability
      summary: getSchemaCapability
      description: Get a schema capability from given capability ID
      tags:
      - Schemas
      parameters:
      - name: composite_id
        description: Schema Slug and the Attribute ID
        in: path
        required: true
        schema:
          type: string
          pattern: ^.+:.+$
          example: contact:97644baa-083f-4e49-9188-fcff2ecaad7d
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityCapabilityWithCompositeID'
        '404':
          $ref: '#/components/responses/NotFoundError'
    put:
      operationId: putSchemaCapability
      summary: putSchemaCapability
      description: Adds or updates an capability in the schema
      tags:
      - Schemas
      parameters:
      - name: composite_id
        description: Schema Slug and the Attribute ID
        in: path
        required: true
        schema:
          type: string
          pattern: ^.+:.+$
          example: contact:97644baa-083f-4e49-9188-fcff2ecaad7d
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntityCapabilityWithCompositeID'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityCapabilityWithCompositeID'
    delete:
      operationId: deleteSchemaCapability
      summary: deleteSchemaCapability
      description: Deletes a Capability from a schema
      tags:
      - Schemas
      parameters:
      - name: composite_id
        description: Schema Slug and the Attribute ID
        in: path
        required: true
        schema:
          type: string
          pattern: ^.+:.+$
          example: contact:97644baa-083f-4e49-9188-fcff2ecaad7d
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityCapabilityWithCompositeID'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity/schemas/group:
    post:
      operationId: createSchemaGroup
      summary: createSchemaGroup
      description: Create a schema group
      tags:
      - Schemas
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitySchemaGroupWithCompositeID'
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitySchemaGroupWithCompositeID'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity/schemas/group/{composite_id}:
    get:
      operationId: getSchemaGroup
      summary: getSchemaGroup
      description: Get a schema group from given group composite ID
      tags:
      - Schemas
      parameters:
      - name: composite_id
        description: Schema Slug and the Group ID
        in: path
        required: true
        schema:
          type: string
          pattern: ^.+:.+$
          example: contact:97644baa-083f-4e49-9188-fcff2ecaad7d
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitySchemaGroupWithCompositeID'
        '404':
          $ref: '#/components/responses/NotFoundError'
    put:
      operationId: putSchemaGroup
      summary: putSchemaGroup
      description: Adds or updates an capability in the schema
      tags:
      - Schemas
      parameters:
      - name: composite_id
        description: Schema Slug and the Group ID
        in: path
        required: true
        schema:
          type: string
          pattern: ^.+:.+$
          example: contact:97644baa-083f-4e49-9188-fcff2ecaad7d
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitySchemaGroupWithCompositeID'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitySchemaGroupWithCompositeID'
    delete:
      operationId: deleteSchemaGroup
      summary: deleteSchemaGroup
      description: Deletes a Capability from a schema
      tags:
      - Schemas
      parameters:
      - name: composite_id
        description: Schema Slug and the Group ID
        in: path
        required: true
        schema:
          type: string
          pattern: ^.+:.+$
          example: contact:97644baa-083f-4e49-9188-fcff2ecaad7d
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitySchemaGroupWithCompositeID'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity/schemas/headline:
    post:
      operationId: createSchemaGroupHeadline
      summary: createSchemaGroupHeadline
      description: Create a headline in a schema group
      tags:
      - Schemas
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupHeadlineWithCompositeID'
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupHeadlineWithCompositeID'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
  /v1/entity/schemas/headline/{composite_id}:
    get:
      operationId: getSchemaGroupHeadline
      summary: getSchemaGroupHeadline
      description: Get a group headline from schema from given headline composite ID
      tags:
      - Schemas
      parameters:
      - name: composite_id
        description: Schema Slug and the Schema Group ID
        in: path
        required: true
        schema:
          type: string
          pattern: ^.+:.+$
          example: contact:97644baa-083f-4e49-9188-fcff2ecaad7d
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupHeadlineWithCompositeID'
        '404':
          $ref: '#/components/responses/NotFoundError'
    put:
      operationId: putSchemaGroupHeadline
      summary: putSchemaGroupHeadline
      description: Adds or updates a group headline in the schema
      tags:
      - Schemas
      parameters:
      - name: composite_id
        description: Schema Slug and the Schema Group ID
        in: path
        required: true
        schema:
          type: string
          pattern: ^.+:.+$
          example: contact:97644baa-083f-4e49-9188-fcff2ecaad7d
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupHeadlineWithCompositeID'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupHeadlineWithCompositeID'
    delete:
      operationId: deleteSchemaGroupHeadline
      summary: deleteSchemaGroupHeadline
      description: Deletes a group headline from a schema
      tags:
      - Schemas
      parameters:
      - name: composite_id
        description: Schema Slug and the Schema Group ID
        in: path
        required: true
        schema:
          type: string
          pattern: ^.+:.+$
          example: contact:97644baa-083f-4e49-9188-fcff2ecaad7d
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupHeadlineWithCompositeID'
        '429':
          $ref: '#/components/responses/TooManyRequestsError'
components:
  securitySchemes:
    EpilotAuth:
      type: http
      scheme: bearer
      description: Authorization header with epilot OAuth2 bearer token
      bearerFormat: JWT
    EpilotOrg:
      description: Overrides the target organization to allow shared tenantaccess
      name: x-epilot-org-id
      in: header
      type: apiKey
  schemas:
    ExportJobId:
      description: The unique identifier of the import job.
      type: string
      example: abc123
    Language:
      description: Export headers translation Language
      type: string
    IsTemplate:
      description: Pass 'true' to generate import template
      type: boolean
    SchemaId:
      description: Generated uuid for schema
      type: string
      format: uuid
    EntitySchema:
      description: The "type" of an Entity. Describes the shape. Includes Entity Attributes, Relations and Capabilities.
      type: object
      properties:
        slug:
          $ref: '#/components/schemas/EntitySlug'
        version:
          type: integer
          minimum: 1
        blueprint:
          $ref: '#/components/schemas/BlueprintEntityId'
        feature_flag:
          type: string
          example: FF_MY_FEATURE_FLAG
          description: This schema should only be active when the feature flag is enabled
        enable_setting:
          description: This schema should only be active when one of the organization settings is enabled
          type: array
          items:
            type: string
            example: 360_features
        name:
          description: User-friendly identifier for the entity schema
          type: string
          example: Contact
        plural:
          type: string
          example: Contacts
        description:
          type: string
          example: Example description
        docs_url:
          type: string
          format: uri
          example: https://docs.epilot.io/docs/pricing/entities
        category:
          type: string
          example: customer_relations
        published:
          type: boolean
          example: false
        draft:
          deprecated: true
          type: boolean
          example: false
        icon:
          type: string
          example: person
        title_template:
          type: string
          description: Template for rendering the title field. Uses handlebars
          example: '{{first_name}} {{last_name}}'
        ui_config:
          type: object
          properties:
            table_view:
              anyOf:
              - $ref: '#/components/schemas/EntityDefaultTable'
              - $ref: '#/components/schemas/RedirectEntityView'
              - $ref: '#/components/schemas/EntityViewDisabled'
            create_view:
              anyOf:
              - $ref: '#/components/schemas/EntityDefaultCreate'
              - $ref: '#/components/schemas/RedirectEntityView'
              - $ref: '#/components/schemas/EntityViewDisabled'
            edit_view:
              anyOf:
              - $ref: '#/components/schemas/EntityDefaultEdit'
              - $ref: '#/components/schemas/RedirectEntityView'
              - $ref: '#/components/schemas/EntityViewDisabled'
            single_view:
              anyOf:
              - $ref: '#/components/schemas/EntityDefaultEdit'
              - $ref: '#/components/schemas/RedirectEntityView'
              - $ref: '#/components/schemas/EntityViewDisabled'
            list_item:
              type: object
              properties:
                summary_attributes:
                  type: array
                  items:
                    anyOf:
                    - $ref: '#/components/schemas/SummaryAttribute'
                    - type: string
                      description: List of attributes to show in list item
                      example: email
                quick_actions:
                  type: array
                  items:
                    $ref: '#/components/schemas/EntityAction'
                ui_config:
                  type: object
                  properties:
                    content_direction:
                      type: string
                      enum:
                      - row
                      - column
                      description: Show attributes in a row or column
            sharing:
              type: object
              properties:
                show_sharing_button:
                  type: boolean
                  description: Show the sharing button in entity detail view
                  example: true
            grid_layout:
              type: object
              deprecated: true
              description: >-
                Superseded by `widget_widths`. A whole-grid layout preset that assigned each widget a width by its POSITION, so a widget that rendered nothing shifted every width after it. Neither the entity app nor the entity builder reads
                it any more; values stored before it was replaced are left in place rather than migrated.
              properties:
                id:
                  type: string
                  description: Identifier of the chosen grid-layout preset.
                columns:
                  type: number
                  description: Number of columns in the widget grid.
                cells:
                  type: array
                  description: Per-cell column span, positionally paired with the widgets in order.
                  items:
                    type: number
            widget_order:
              type: array
              description: >-
                Ordered list of widget ids controlling the entity-details widget-grid order. Each id is a capability widget's `component` (or `summary` for the synthesized summary card); widgets absent from the list keep their natural order
                at the end.
              items:
                type: string
            widget_visibility:
              type: object
              description: >-
                Per-widget on/off state for the entity-details widget grid, keyed by widget id (a capability widget's `component`, or `summary` for the synthesized summary card). Holds only the admin's deviations from each widget's declared
                default: a widget absent from this map falls back to its ui_hook `default_visible`, and then to visible. Do not seed this map from migrations — doing so would freeze today's defaults into the schema.
              additionalProperties:
                type: boolean
              example:
                next_best_action: true
                address_map: false
            widget_widths:
              type: object
              description: >-
                Per-widget width in the entity-details widget grid, keyed by widget id (a capability widget's `component`, or `summary` for the synthesized summary card). Spans a 12-column grid: `one_third_width` = 4, `half_width` = 6,
                `two_third_width` = 8, `full_width` = 12. Holds only the admin's deviations from each widget's declared default: a widget absent from this map falls back to its ui_hook `default_width`, and then to `full_width`. Do not seed
                this map from migrations — doing so would freeze today's defaults into the schema. Replaces the positional `grid_layout` preset.
              additionalProperties:
                type: string
                enum:
                - one_third_width
                - half_width
                - two_third_width
                - full_width
              example:
                address_map: full_width
                recent_communications: one_third_width
        capabilities:
          type: array
          items:
            $ref: '#/components/schemas/EntityCapability'
        group_settings:
          type: array
          description: A list of Group Titles and associated settings if present.
          items:
            $ref: '#/components/schemas/EntitySchemaGroup'
          example:
          - id: e18a532b-ae79-4d86-a6a5-e5dbfb579d14
            label: Contact Details
            expanded: true
            order: 1
          - id: e9a1ae28-27ba-4fa0-a79c-e279cc5c4a6e
            label: Address Details
            expanded: false
            order: 2
            info_tooltip_title:
              key: partner.partner_information_group_tooltip
              default: These informations are provided by the partner company and cannot be edited.
        layout_settings:
          type: object
          description: |
            Custom grid definitions for the layout. These settings are composed by managed and un-managed properties:
            - Managed Properties: are interpreted and transformed into layout styles
            - Un-managed Properties: are appended as styles into the attribute mounting node
          additionalProperties: true
          properties:
            grid_gap:
              type: string
              description: Defines the grid gap for the mounting node of the attribute.
            grid_template_columns:
              type: string
              description: Defines the grid column template for the mounting node of the attribute.
        dialog_config:
          type: object
          additionalProperties: true
        attributes:
          description: An ordered list of attributes the entity contains
          type: array
          items:
            $ref: '#/components/schemas/Attribute'
          example:
          - name: email
            type: email
            label: Email
            required: true
          - name: first_name
            type: string
            label: First Name
          - name: last_name
            type: string
            label: Last Name
          - name: birthdate
            type: date
            label: Birthdate
          - name: salutation
            type: select
            label: Salutation
            options:
            - Mr.
            - Ms. / Mrs.
            - Other
          - name: marketing_permission
            type: boolean
            label: Marketing permission
          - name: image
            type: file
            label: Image
        _purpose:
          type: array
          items:
            type: string
        _manifest:
          type: array
          description: Manifest ID used to create the schema
          items:
            type: string
            format: uuid
            example: 123e4567-e89b-12d3-a456-426614174000
          nullable: true
        explicit_search_mappings:
          $ref: '#/components/schemas/SearchMappings'
        group_headlines:
          type: array
          items:
            $ref: '#/components/schemas/GroupHeadline'
        conditions:
          type: array
          nullable: true
          description: |
            Dimensions that conditional variants of this entity type are keyed by.

            Absent or `null` means entities of this type are not conditional. Attributes whose
            values a variant may override are marked with `overridable_attribute`.
          items:
            $ref: '#/components/schemas/ConditionDefinition'
      required:
      - slug
      - name
      - plural
      - attributes
      - capabilities
    EntitySchemaItem:
      allOf:
      - type: object
        properties:
          id:
            $ref: '#/components/schemas/SchemaId'
          created_at:
            type: string
          updated_at:
            type: string
          comment:
            type: string
          source:
            type: object
            properties:
              id:
                type: string
              type:
                type: string
          frozen:
            deprecated: true
            description: |
              No longer returned: schema freezing is retired.
            type: boolean
          latest:
            deprecated: true
            description: |
              No longer returned: every read returns the latest version.
            type: boolean
          _summary:
            description: Indicates this is a truncated summary schema (attributes trimmed to summary_attributes only, no capabilities or group_settings)
            type: boolean
      - $ref: '#/components/schemas/EntitySchema'
    GenerateEntityTableAIFiltersRequest:
      type: object
      properties:
        prompt:
          type: string
          description: The prompt to generate the filters
          example: Show me all contacts that are not customers
          maxLength: 300
        main_entity_slug:
          type: string
          description: The main entity slug
          example: order
        filter_options:
          type: array
          items:
            $ref: '#/components/schemas/EntityTableFilterOption'
      required:
      - prompt
      - main_entity_slug
      - filter_options
    GenerateEntityTableAIFiltersResponse:
      type: array
      items:
        $ref: '#/components/schemas/EntityTableFilterSearch'
    EntityTableFilterSearch:
      type: object
      properties:
        label:
          type: string
          description: The label for the search filter
        type:
          type: string
          description: The type for the search filter
        value:
          type: string
          description: The value for the search filter
      required:
      - label
      - type
      - value
    EntityTableFilterOption:
      type: object
      properties:
        type:
          type: string
          description: The type of filter option
          enum:
          - search
          - filter
        label:
          type: string
          description: The label for the filter option
        label_type:
          type: string
          description: The label type for the filter option
        name:
          type: string
          description: The name for the filter option
        group:
          type: string
          description: The group for the filter option
        allowedSchemas:
          type: array
          items:
            type: string
            description: The allowed schemas for the filter option
        relatedOptions:
          type: array
          items:
            $ref: '#/components/schemas/EntityTableFilterOption'
          description: The related options for the filter option
      required:
      - label
    EntitySchemaGroup:
      type: object
      properties:
        label:
          type: string
          example: Contact Details
        id:
          type: string
          example: e18a532b-ae79-4d86-a6a5-e5dbfb579d14
        order:
          description: Render order of the group
          type: integer
          default: 0
        expanded:
          description: Expanded by default
          type: boolean
          default: false
        render_condition:
          description: Only render group when render_condition resolves to true
          type: string
          example: _is_composite_price = "false"
        _purpose:
          description: Only render group when one of the purposes is enabled
          type: array
          items:
            $ref: '#/components/schemas/ClassificationId'
        _manifest:
          type: array
          description: Manifest ID used to create/update the schema group
          items:
            type: string
            format: uuid
            example: 123e4567-e89b-12d3-a456-426614174000
          nullable: true
        feature_flag:
          type: string
          example: FF_MY_FEATURE_FLAG
          description: This group should only be active when the feature flag is enabled
        settings_flag:
          type: array
          description: This group should only be active when all the settings have the correct value
          items:
            $ref: '#/components/schemas/SettingFlag'
        info_tooltip_title:
          type: object
          properties:
            key:
              description: Translation key for info tooltip
              type: string
            default:
              description: Default string for info tooltip
              type: string
      required:
      - label
    EntitySchemaGroupWithCompositeID:
      allOf:
      - $ref: '#/components/schemas/EntitySchemaGroup'
      - type: object
        description: a readonly computed ID for the group including schema slug and the group ID
        properties:
          composite_id:
            type: string
            readOnly: true
            example: contact:e18a532b-ae79-4d86-a6a5-e5dbfb579d14
          schema:
            type: string
            description: Schema slug the group belongs to
            example: contact
    Attribute:
      anyOf:
      - $ref: '#/components/schemas/TextAttribute'
      - $ref: '#/components/schemas/LinkAttribute'
      - $ref: '#/components/schemas/DateAttribute'
      - $ref: '#/components/schemas/CountryAttribute'
      - $ref: '#/components/schemas/BooleanAttribute'
      - $ref: '#/components/schemas/SelectAttribute'
      - $ref: '#/components/schemas/MultiSelectAttribute'
      - $ref: '#/components/schemas/StatusAttribute'
      - $ref: '#/components/schemas/SequenceAttribute'
      - $ref: '#/components/schemas/RelationAttribute'
      - $ref: '#/components/schemas/UserRelationAttribute'
      - $ref: '#/components/schemas/AddressAttribute'
      - $ref: '#/components/schemas/AddressRelationAttribute'
      - $ref: '#/components/schemas/PaymentMethodRelationAttribute'
      - $ref: '#/components/schemas/CurrencyAttribute'
      - $ref: '#/components/schemas/TagsAttribute'
      - $ref: '#/components/schemas/MessageEmailAddressAttribute'
      - $ref: '#/components/schemas/NumberAttribute'
      - $ref: '#/components/schemas/TableAttribute'
      - $ref: '#/components/schemas/ConsentAttribute'
      - $ref: '#/components/schemas/InternalAttribute'
      - $ref: '#/components/schemas/OrderedListAttribute'
      - $ref: '#/components/schemas/FileAttribute'
      - $ref: '#/components/schemas/ComputedAttribute'
      - $ref: '#/components/schemas/PartnerStatusAttribute'
      - $ref: '#/components/schemas/InvitationEmailAttribute'
      - $ref: '#/components/schemas/AutomationAttribute'
      - $ref: '#/components/schemas/InternalUserAttribute'
      - $ref: '#/components/schemas/PurposeAttribute'
      - $ref: '#/components/schemas/PartnerOrganisationAttribute'
      - $ref: '#/components/schemas/PortalAccessAttribute'
      - $ref: '#/components/schemas/PhoneAttribute'
      - $ref: '#/components/schemas/EmailAttribute'
      - $ref: '#/components/schemas/PaymentAttribute'
      - $ref: '#/components/schemas/PriceComponentAttribute'
    AttributeWithCompositeID:
      allOf:
      - $ref: '#/components/schemas/Attribute'
      - type: object
        description: a readonly computed ID for the attribute including schema slug and the attribute ID
        properties:
          composite_id:
            type: string
            readOnly: true
            example: contact:97644baa-083f-4e49-9188-fcff2ecaad7d
          schema:
            type: string
            description: Schema slug the attribute belongs to
            example: contact
    BaseAttribute:
      type: object
      properties:
        id:
          type: string
          description: ID for the entity attribute
          example: d5839b94-ba20-4225-a78e-76951d352bd6
        name:
          type: string
        label:
          type: string
        placeholder:
          type: string
        hidden:
          description: Do not render attribute in entity views
          type: boolean
          default: false
        show_in_table:
          description: Render as a column in table views. When defined, overrides `hidden`
          type: boolean
        sortable:
          description: Allow sorting by this attribute in table views if `show_in_table` is true
          type: boolean
          default: true
        required:
          type: boolean
          default: false
        readonly:
          type: boolean
          default: false
        deprecated:
          type: boolean
          default: false
        overridable_attribute:
          type: boolean
          default: false
          description: |
            Allow conditional variants of the entity to override this attribute's value.
            Only meaningful on schemas that declare `conditions`. Unflagged attributes stay
            fixed on the base entity.
        default_value: {}
        group:
          description: Which group the attribute should appear in. Accepts group ID or group name
          type: string
        order:
          description: Attribute sort order (ascending) in group
          type: integer
          example: 0
        layout:
          type: string
          example: full_width
        hide_label:
          type: boolean
          description: When set to true, will hide the label of the field.
        icon:
          type: string
          description: |
            Code name of the icon to used to represent this attribute.
            The value must be a valid @epilot/base-elements Icon name
        render_condition:
          type: string
          description: |
            Defines the conditional rendering expression for showing this field.
            When a valid expression is parsed, their evaluation defines the visibility of this attribute.
            Note: Empty or invalid expression have no effect on the field visibility.
        data_classification:
          type: string
          enum:
          - public
          - pii
          description: |
            Data classification of the attribute, used by anonymized responses (`?anonymize=true` or tokens minted with `anonymize: true`).

            - `pii`: the attribute value is always anonymized in anonymized responses (use to opt in free-text fields containing personal data)
            - `public`: the attribute value is never anonymized (use to opt out fields matched by built-in defaults, e.g. non-personal identifiers)

            When unset, built-in defaults apply based on the attribute type (email, phone, address, payment) and a curated list of well-known PII fields.
        _purpose:
          type: array
          items:
            $ref: '#/components/schemas/ClassificationId'
        _manifest:
          type: array
          description: Manifest ID used to create/update the schema attribute
          items:
            type: string
            format: uuid
            example: 123e4567-e89b-12d3-a456-426614174000
          nullable: true
        constraints:
          type: object
          description: |
            A set of constraints applicable to the attribute.
            These constraints should and will be enforced by the attribute renderer.
          example:
            disablePast: true
        feature_flag:
          type: string
          example: FF_MY_FEATURE_FLAG
          description: This attribute should only be active when the feature flag is enabled
        settings_flag:
          type: array
          description: This attribute should only be active when one of the provided settings have the correct value
          items:
            $ref: '#/components/schemas/SettingFlag'
        value_formatter:
          type: string
        preview_value_formatter:
          type: string
        entity_builder_disable_edit:
          description: Setting to `true` disables editing the attribute on the entity builder UI
          type: boolean
          default: false
        protected:
          description: Setting to `true` prevents the attribute from being modified / deleted
          type: boolean
        info_helpers:
          description: A set of configurations meant to document and assist the user in filling the attribute.
          type: object
          properties:
            hint_text:
              type: string
              description: |
                The text to be displayed in the attribute hint helper.
                When specified it overrides the `hint_text_key` configuration.
            hint_text_key:
              type: string
              description: |
                The key of the hint text to be displayed in the attribute hint helper.
                The key should be a valid i18n key.
            hint_custom_component:
              type: string
              description: |
                The name of the custom component to be used as the hint helper.
                The component should be registered in the `@epilot360/entity-ui` on the index of the components directory.
                When specified it overrides the `hint_text` or `hint_text_key` configuration.
            hint_tooltip_placement:
              type: string
              description: |
                The placement of the hint tooltip.
                The value should be a valid `@mui/core` tooltip placement.
              example: top
        explicit_searchable:
          type: boolean
          description: |
            When set to true, this attribute will always be searchable regardless of
            the ELASTIC_MAX_SEARCH_FIELDS limit. Use this for critical search fields
            that must always be included in search operations.
          default: false
        exclude_from_search:
          type: boolean
          description: |
            When set to true, this attribute will be excluded from search fields.
            Use this for fields that should not be matched during entity search operations,
            such as internal hashes or identifiers that might accidentally match search terms.
          default: false
        repeatable:
          description: The attribute is a repeatable
          type: boolean
        has_primary:
          type: boolean
        edit_mode:
          allOf:
          - $ref: '#/components/schemas/EditMode'
          description: |
            Controls how updates to this attribute are handled. See the `EditMode`
            schema for the per-mode semantics. Defaults to `direct`.
        edit_mode_config:
          description: |
            Configuration for auto-clear matching on `edit_mode: external` attributes.
            `match_strategy` and `fuzzy_config` are only consulted for `external` mode —
            they are ignored for `approval` mode, which resolves via explicit
            `:apply` / `:dismiss` endpoints and never auto-clears.
          allOf:
          - $ref: '#/components/schemas/EditModeConfig'
      required:
      - name
      - label
      - type
    TextAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Textarea or text input
        properties:
          type:
            type: string
            enum:
            - string
          multiline:
            type: boolean
          rich_text:
            type: boolean
          rows:
            description: Number of rows for rich_text textarea
            oneOf:
            - type: integer
            - type: string
            example: 3
    LinkAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Link with title and href
        properties:
          type:
            type: string
            enum:
            - link
    InternalAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: No UI representation
        properties:
          type:
            type: string
            enum:
            - internal
    BooleanAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Yes / No Toggle
        properties:
          type:
            type: string
            enum:
            - boolean
          display_type:
            type: string
            enum:
            - switch
            - checkbox
            default: switch
    DateAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Date or Datetime picker
        properties:
          type:
            type: string
            enum:
            - date
            - datetime
    CountryAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Country picker
        properties:
          type:
            type: string
            enum:
            - country
    SelectAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Dropdown select
        properties:
          type:
            type: string
            enum:
            - select
            - radio
          options:
            type: array
            items:
              anyOf:
              - type: object
                properties:
                  value:
                    type: string
                  title:
                    type: string
                required:
                - value
              - type: string
                nullable: true
          allow_any:
            type: boolean
            description: Allow arbitrary input values in addition to provided options
    MultiSelectAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Multi Choice Selection
        properties:
          type:
            type: string
            enum:
            - multiselect
            - checkbox
          disable_case_sensitive:
            type: boolean
            nullable: true
            description: controls if the matching of values against the options is case sensitive or not
          allow_extra_options:
            type: boolean
            nullable: true
            description: controls if the 360 ui will allow the user to enter a value which is not defined by the options
          options:
            type: array
            items:
              anyOf:
              - type: string
                nullable: true
              - type: object
                properties:
                  value:
                    type: string
                  title:
                    type: string
                required:
                - value
          allow_any:
            type: boolean
            description: Allow arbitrary input values in addition to provided options
    StatusAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Status select
        properties:
          type:
            type: string
            enum:
            - status
          options:
            type: array
            items:
              anyOf:
              - type: string
                nullable: true
              - type: object
                properties:
                  value:
                    description: The stored value of the option
                    type: string
                  title:
                    description: The displayed title of the option
                    type: string
                required:
                - value
    SequenceAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Sequence of unique identifiers
        properties:
          type:
            type: string
            enum:
            - sequence
          prefix:
            description: Prefix added before the sequence number
            type: string
            example: OR-
          start_number:
            type: integer
            minimum: 0
    FileAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: File or Image Attachment
        properties:
          type:
            type: string
            enum:
            - image
            - file
          multiple:
            type: boolean
          allowed_extensions:
            description: List of file extensions (without the dot suffix)
            type: array
            items:
              type: string
              example: csv
          display_images_landscaped:
            type: boolean
            description: Controls how the images are presented to the user during upload on the Entity Details view.
          enable_description:
            type: boolean
            description: |
              When set to true, an i18n description will be used alongside the attribute label.
              This description should be set through the platform locales in the form: `file.{attribute_name}.description_text`.
          default_access_control:
            type: string
            enum:
            - public-read
            - private
          file_size_bytes:
            type: integer
            description: The maximum file size in bytes. Used to derive file_size and file_size_unit in the UI.
            example: 5000000
        required:
        - type
    CurrencyAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Currency input
        properties:
          type:
            type: string
            enum:
            - currency
          currency_selector_only:
            type: boolean
            default: false
          currency:
            description: An array of currency configurations with a country code (ISO-4217)
            type: array
            items:
              anyOf:
              - type: object
                description: A currency configuration
                properties:
                  code:
                    type: string
                  description:
                    type: string
                  symbol:
                    type: string
                  flag:
                    type: string
                required:
                - code
                - description
                - symbol
                example:
                  code: EUR
                  description: Euro
                  symbol: €
                  flag: 🇪🇺
        required:
        - type
        - currency
    SummaryField:
      type: object
      description: Summary Fields are displayed inside list view as a resume of the relation entity.
      properties:
        field:
          type: string
          description: The field from the entity attributes to display
        display_as:
          type: string
          description: An hint on how to display the summary field
    EntityAction:
      type: object
      description: An entity action configured from the entity schema
      properties:
        action:
          type: string
          description: A unique action name
          example: preview_file
        label:
          type: string
          example: Preview File
        icon:
          type: string
          example: visibility
        permission:
          type: string
          example: entity:edit
          description: |
            Permission required to show the action.
            If not provided, the action will be shown to all users.
      required:
      - action
      - label
    RelationAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Entity Relationship
        properties:
          type:
            type: string
            enum:
            - relation
          relation_type:
            type: string
            enum:
            - has_many
            - has_one
          reverse_attributes:
            description: Map of schema slug to target relation attribute
            type: object
            additionalProperties:
              type: string
              example: contact.account
            example:
              contact: account
              opportunity: customer
          relation_affinity_mode:
            description: Weak relation attributes are kept when duplicating an entity. Strong relation attributes are discarded when duplicating an entity.
            type: string
            enum:
            - weak
            - strong
          enable_relation_picker:
            type: boolean
            default: true
            description: When enable_relation_picker is set to true the user will be able to pick existing relations as values. Otherwise, the user will need to create new relation to link.
          edit_mode:
            type: string
            enum:
            - list-view
          details_view_mode_enabled:
            type: boolean
            default: false
            description: Enables the preview, edition, and creation of relation items on a Master-Details view mode.
          relation_picker_filter:
            description: Additional entity search filter for relation picker
            type: object
            properties:
              q:
                type: string
                example: NOT is_composite_price:true
                nullable: true
            required:
            - q
          actions:
            type: array
            items:
              type: object
              properties:
                action_type:
                  type: string
                  enum:
                  - add_existing
                  - create_new
                  - create_from_existing
                  description: |
                    The action type. Currently supported actions:

                    | action | description |
                    |--------|-------------|
                    | add_existing | Enables the user to pick an existing entity to link as relation |
                    | create_new | Enables the user to create a new entity using the first/main `allowed_schemas` schema
                    | create_from_existing | Enables the user to pick an existing entity to clone from, while creating a blank new entity to link as relation |
                label:
                  type: string
                  description: The action label or action translation key (i18n)
                default:
                  type: boolean
                  description: Sets the action as the default action, visible as the main action button.
                feature_flag:
                  type: string
                  description: Name of the feature flag that enables this action
                settings_flag:
                  type: array
                  description: This action should only be active when all the settings have the correct value
                  items:
                    $ref: '#/components/schemas/SettingFlag'
                new_entity_item:
                  description: Default field values for new entity to create
                  nullable: true
                  type: object
                  additionalProperties: true
                  example:
                    _schema: order
            example:
            - action_type: add_existing
              label: entityrelation.add_existing
              default: true
            - action_type: create_new
              label: entityrelation.create_new
            - action_type: create_from_existing
              label: entityrelation.create_from_existing
          drawer_size:
            type: string
            enum:
            - small
            - medium
            - large
          icon:
            type: string
          summary_fields:
            type: array
            items:
              anyOf:
              - type: string
                description: The field name from the entity attributes to display
              - $ref: '#/components/schemas/SummaryField'
          has_primary:
            type: boolean
          allowedSchemas:
            type: array
            items:
              $ref: '#/components/schemas/EntitySlug'
          enable_relation_tags:
            type: boolean
            default: true
            description: When enable_relation_tags is set to true the user will be able to set tags(labels) in each relation item.
          add_button_label:
            type: string
            description: Optional label for the add button. The translated value for add_button_lable is used, if found else the string is used as is.
          search_placeholder:
            type: string
            description: Optional placeholder text for the relation search input. The translated value for search_placeholder is used, if found else the string is used as is.
          repeatable:
            description: Relations are always repeatables
            type: boolean
            default: true
    UserRelationAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: User Relationship
        properties:
          type:
            type: string
            enum:
            - relation_user
          multiple:
            type: boolean
            default: false
    PartnerOrganisationAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Shared Partner Organisations
        properties:
          type:
            type: string
            enum:
            - partner_organisation
    PortalAccessAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Portal access configuration
        properties:
          type:
            type: string
            enum:
            - portal_access
    DefaultAddressFields:
      type: array
      nullable: true
      description: |
        Default fields visible on addresses

        Valid values are:
          - postal_code (default)
          - city (default)
          - street (default)
          - street_number (default)
          - plot_area
          - plot_of_land
          - suburb
          - country
          - postbox
          - additional_info
          - coordinates
          - start_date
          - end_date
          - salutation
          - title
          - first_name
          - last_name
          - name_suffix
          - company_name
      items:
        type: string
    AddressAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Address attribute
        properties:
          type:
            type: string
            enum:
            - address
          default_address_fields:
            $ref: '#/components/schemas/DefaultAddressFields'
    AddressRelationAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Reference to an address attribute of another entity
        properties:
          type:
            type: string
            enum:
            - relation_address
          has_primary:
            type: boolean
          default_address_fields:
            $ref: '#/components/schemas/DefaultAddressFields'
    PaymentMethodRelationAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Reference to a payment method attribute of another entity
        properties:
          type:
            type: string
            enum:
            - relation_payment_method
          has_primary:
            type: boolean
    InvitationEmailAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Email address for send invitation
        properties:
          type:
            type: string
            enum:
            - invitation_email
    AutomationAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Automation entity
        properties:
          type:
            type: string
            enum:
            - automation
    InternalUserAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Epilot internal user info
        properties:
          type:
            type: string
            enum:
            - internal_user
    PurposeAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Entity Taxonomy
        properties:
          type:
            type: string
            enum:
            - purpose
    RepeatableAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Repeatable (add N number of fields)
        properties:
          repeatable:
            type: boolean
          has_primary:
            type: boolean
    TagsAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Tags
        properties:
          type:
            type: string
            enum:
            - tags
          options:
            type: array
            items:
              type: string
          suggestions:
            type: array
            items:
              type: string
    MessageEmailAddressAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Message emil address
        properties:
          type:
            type: string
            enum:
            - message_email_address
          address:
            type: string
          name:
            type: string
          send_status:
            type: string
          email_type:
            type: string
        required:
        - type
        - name
    NumberAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Numeric input
        properties:
          type:
            type: string
            enum:
            - number
          data_type:
            type: string
            enum:
            - number
            - string
            default: string
            description: Optional data type override. When set to 'number', the value is stored as a number instead of a string. Defaults to 'string'.
          format:
            type: string
          show_separator:
            description: Whether or not to show a thousands separator
            type: boolean
            default: true
    TableAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Dynamic data table with configurable columns. Data is stored as an array of objects where each object represents a row.
        properties:
          type:
            type: string
            enum:
            - table
          columns:
            type: array
            description: Column definitions for the table
            items:
              type: object
              properties:
                name:
                  type: string
                  description: The column identifier (used as object key in row data)
                label:
                  type: string
                  description: Display label for the column header
                type:
                  type: string
                  description: The data type for cells in this column
                  enum:
                  - string
                  - number
                  - date
                  - boolean
                  default: string
                width:
                  type: string
                  description: Optional column width (e.g., "100px", "20%")
                required:
                  type: boolean
                  description: Whether this column is required for each row
                  default: false
                bold:
                  type: boolean
                  description: When true, the row is rendered in bold (only applies in transposed mode)
                  default: false
              required:
              - name
              - label
          min_rows:
            type: integer
            description: Minimum number of rows required
            minimum: 0
            default: 0
          max_rows:
            type: integer
            description: Maximum number of rows allowed (or maximum periods when transposed)
            minimum: 1
          transposed:
            type: boolean
            description: Enable transposed layout where rows become metrics and columns become periods
            default: false
          column_header:
            type: object
            description: Configuration for column headers in transposed mode
            properties:
              template:
                type: string
                description: Header label pattern with {{i}} as index placeholder (e.g., "Year {{i}}")
                example: Year {{i}}
              start:
                type: integer
                description: Starting index value for the template placeholder
                default: 0
                minimum: 0
    ConsentAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Consent Management
        properties:
          type:
            type: string
            enum:
            - consent
          topic:
            type: string
          identifiers:
            type: array
            items:
              type: string
        required:
        - type
        - topic
    OrderedListAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Type of attribute to render N number of ordered fields
        properties:
          type:
            type: string
            enum:
            - ordered_list
    EmailAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Email address
        properties:
          type:
            type: string
            enum:
            - email
    PhoneAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Phone number
        properties:
          type:
            type: string
            enum:
            - phone
    PaymentAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Payment method
        properties:
          type:
            type: string
            enum:
            - payment
    PriceComponentAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Price component
        properties:
          type:
            type: string
            enum:
            - price_component
    ComputedAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: An attribute that is computed from the entity data. For more details on how to use them, check the docs [here](https://e-pilot.atlassian.net/wiki/spaces/EO/pages/5642977476/How+To+Computed+Schema+Attributes)
        properties:
          type:
            type: string
            enum:
            - computed
          computed:
            type: boolean
            default: true
          value_formatter:
            type: string
            description: Variable template used to format the computed value
            example: '{{formatCurrencyAttribute entity attribute locale}}'
          preview_value_formatter:
            type: string
            description: Variable template used to format a preview for the computed value
            example: '{{formatCurrencyAttribute entity attribute locale}}'
          amount_field:
            type: string
            description: A source amount field that is used to compute the value of the attribute
          currency_field:
            type: string
            description: A currency field used to format a computed currency value
        required:
        - value_formatter
    PartnerStatusAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Partner Status
        properties:
          type:
            type: string
            enum:
            - partner_status
    SummaryAttribute:
      description: |
        Represents an expanded version of an attribute to be displayed in the list item summary.
        This configuration can be used in the following way:
        ```js
        {
          "label": "Price components"
          "value": "{{item.prices.length}} price components"
          "show_as_tag": true
          "render_condition": "is_composite_price = "true""
        }
        ```
        The value field supports handlebar expressions from which you can pick any field from the entity state.
      type: object
      properties:
        label:
          type: string
          description: Label to be shown on the top of the value.
        value:
          type: string
          description: A static value or an handlebar expression.
        show_as_tag:
          type: boolean
          description: Displays the value within a tag chip.
        tag_color:
          type: string
          description: CSS hex color or CSS color name for the tag chip.
        render_condition:
          type: string
          description: |
            Defines the conditional rendering expression for showing this field.
            When a valid expression is parsed, their evaluation defines the visibility of this attribute.
            Note: Empty or invalid expression have no effect on the field visibility.
        feature_flag:
          type: string
          description: Binds summary field visibility to the feature flag state.
        settings_flag:
          type: array
          description: This summary attribute should only be visible when all the settings have the correct value
          items:
            $ref: '#/components/schemas/SettingFlag'
        display_mode:
          type: string
          enum:
          - inline
          - block
          description: |
            Defines the display mode of the summary attribute.
            When set to `inline`, the label and value will be displayed in the same line.
            When set to `block`, the label and value will be displayed in separate lines.
        content_line_cap:
          type: number
          description: |
            Defines the line numbers of the content.
            For instance, When set to 1, the content will be displayed in a single line.
        content_wrap:
          type: string
          enum:
          - normal
          - nowrap
          - pre
          - pre-wrap
          description: |
            Defines white-space of the content.
        hide_label:
          type: boolean
          description: When set to true, will hide the label of the field.
        highlight_container:
          type: boolean
          description: When set to true, will highlight the container of the field.
      required:
      - label
      - value
    GroupHeadline:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        label:
          type: string
        layout:
          type: string
        group:
          type: string
          description: The group of headline attribute
        order:
          type: integer
          description: The order of headline attribute
        type:
          type: string
          enum:
          - headline
        enable_divider:
          type: boolean
          default: false
        divider:
          type: string
          enum:
          - top_divider
          - bottom_divider
        _purpose:
          type: array
          items:
            $ref: '#/components/schemas/ClassificationId'
        _manifest:
          type: array
          description: Manifest ID used to create/update the schema group headline
          items:
            type: string
            format: uuid
            example: 123e4567-e89b-12d3-a456-426614174000
          nullable: true
      required:
      - name
      - label
      - group
      - type
    GroupHeadlineWithCompositeID:
      allOf:
      - $ref: '#/components/schemas/GroupHeadline'
      - type: object
        description: a readonly computed ID for the entity group headline including schema slug and the headline ID
        properties:
          composite_id:
            type: string
            readOnly: true
            example: contact:97644baa-083f-4e49-9188-fcff2ecaad7d
          schema:
            type: string
            description: Schema slug the capability belongs to
            example: contact
    BaseConditionDefinition:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: |
            Stable identity of the condition, generated by the client when the condition is
            created. It is what makes a rename distinguishable from a remove + add, so it must
            be round-tripped unchanged for the lifetime of the condition.
          example: d5839b94-ba20-4225-a78e-76951d352bd6
        name:
          type: string
          pattern: ^[a-z0-9_]+$
          description: |
            The key variant values are stored under. Unique within the schema and immutable
            once the condition has been saved.
          example: delivery_area
        label:
          type: string
          description: Display label. Always editable.
          example: Delivery Area
      required:
      - id
      - name
      - label
    ScalarConditionDefinition:
      allOf:
      - $ref: '#/components/schemas/BaseConditionDefinition'
      - type: object
        description: A condition whose value is a plain scalar, with no further configuration.
        properties:
          type:
            type: string
            description: Immutable once the condition has been saved.
            enum:
            - string
            - number
            - date
            - daterange
            - boolean
        required:
        - type
    SelectConditionDefinition:
      allOf:
      - $ref: '#/components/schemas/BaseConditionDefinition'
      - type: object
        description: A condition whose value is one of a fixed set of options.
        properties:
          type:
            type: string
            description: Immutable once the condition has been saved.
            enum:
            - select
          values:
            type: array
            description: Selectable options. May be empty while the condition is being configured.
            items:
              type: string
            example:
            - 12_months
            - 24_months
        required:
        - type
    LocationConditionDefinition:
      allOf:
      - $ref: '#/components/schemas/BaseConditionDefinition'
      - type: object
        description: A condition whose value identifies a place.
        properties:
          type:
            type: string
            description: Immutable once the condition has been saved.
            enum:
            - location
          format:
            type: string
            description: The shape of the location value. Immutable once the condition has been saved.
            enum:
            - zipcode
            - zipcode_town
        required:
        - type
    ConditionDefinition:
      description: |
        One dimension that conditional variants of an entity type are keyed by. `type`
        discriminates the variants: only a `select` condition carries `values`, and only a
        `location` condition carries `format`.
      oneOf:
      - $ref: '#/components/schemas/ScalarConditionDefinition'
      - $ref: '#/components/schemas/SelectConditionDefinition'
      - $ref: '#/components/schemas/LocationConditionDefinition'
    EntitySlug:
      description: URL-friendly identifier for the entity schema
      type: string
      pattern: ^[a-zA-Z0-9_-]+$
      example: contact
    AdjustInstallmentCapabilityConfig:
      description: Configuration for adjusting a contract installment through a Journey.
      type: object
      additionalProperties: false
      example:
        journey_id: adjust-installment-flow
      required:
      - journey_id
      properties:
        journey_id:
          type: string
          minLength: 1
          description: ID of the Flow Journey to open when adjusting the installment.
    EntityCapability:
      description: Capabilities the Entity has. Turn features on/off for entities.
      type: object
      properties:
        id:
          type: string
          description: ID for the entity capability
          example: d5839b94-ba20-4225-a78e-76951d352bd6
        name:
          type: string
          description: Unique name for the capability
          example: customer_messaging
        title:
          type: string
          description: Human readable title of the capability
          example: Messaging
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/Attribute'
        overridable_attribute:
          type: boolean
          default: false
          description: |
            Allow conditional variants of the entity to override the values managed by this
            capability. Only meaningful on schemas that declare `conditions` and on capabilities
            that render an attribute group (`EntityAttributes:Group` ui hook), e.g. pricing tiers.
            Attributes carried by the capability opt in individually via their own
            `overridable_attribute` flag.
        _purpose:
          type: array
          items:
            $ref: '#/components/schemas/ClassificationId'
        _manifest:
          type: array
          description: Manifest ID used to create/update the schema capabilility
          items:
            type: string
            format: uuid
            example: 123e4567-e89b-12d3-a456-426614174000
          nullable: true
        app_id:
          type: string
          description: ID of the app if the capability is provided by an app
          example: 123e4567-e89b-12d3-a456-426614174000
        adjust_installment:
          $ref: '#/components/schemas/AdjustInstallmentCapabilityConfig'
        ui_config:
          type: object
          properties:
            is_filterable:
              type: boolean
              description: Whether the capability is filterable
              example: true
              default: false
        ui_hooks:
          type: array
          items:
            type: object
            additionalProperties: true
            properties:
              hook:
                type: string
                description: name of the hook to use
                example: EntityDetailsV2:Tab
              render_condition:
                type: string
                example: _is_composite_price = "false"
              order:
                type: integer
                description: render order (ascending)
                example: 10
              title:
                type: string
                example: Notes
              group_expanded:
                type: boolean
                description: Sets the group expand/collapse default state
              import:
                type: string
                description: package to be imported
                example: '@epilot360/notes'
              component:
                type: string
                description: the component to be dynamically loaded
                example: PricingItems
              route:
                type: string
                description: route for specified capability
                example: notes
              icon:
                type: string
                description: Preview icon name(As in Base elements) for the capability
                example: email
              disabled:
                type: boolean
                description: Whether capability should be disabled
              header:
                type: boolean
                description: Specific to Activity pilot
              requiredPermission:
                type: object
                description: Require a permission to display UI hook
                properties:
                  action:
                    type: string
                    example: note:view
                  resource:
                    type: string
                    example: '123'
                required:
                - action
              default_visible:
                type: boolean
                description: >-
                  Whether this widget is switched on by default for entity types that have the capability. Only meaningful on the `EntityDetailsV2:Widget` hook. Defaults to true when omitted. An admin's explicit choice in the entity builder
                  is stored in the schema's `ui_config.widget_visibility` and wins over this.
                example: false
              default_width:
                type: string
                enum:
                - one_third_width
                - half_width
                - two_third_width
                - full_width
                description: >-
                  How wide this widget is by default in the entity-details widget grid. Only meaningful on the `EntityDetailsV2:Widget` and `EntityDetailsV2:Header` hooks. Defaults to `full_width` when omitted — deliberately unlike the
                  attribute layout default of `half_width`, because a full-width widget can never leave a hole in a row. An admin's explicit choice in the entity builder is stored in the schema's `ui_config.widget_widths` and wins over
                  this.
                example: half_width
              pricing_tier_setting:
                type: string
                description: >-
                  The pricing-tier settings key an organisation must have enabled to use this widget. Omit for widgets available to everyone. Resolved against `GET /v2/pricing-tiers/me` as `override_settings[key].enabled ??
                  settings[key].enabled`. Note this is commercial packaging enforced in the UI, not a security control — the key must also be added to the pricing tier settings list in epilot-admin-portal, or it can never be switched on for
                  a tier.
                example: entity_address_maps
            required:
            - hook
        feature_flag:
          type: string
          example: FF_MY_FEATURE_FLAG
          description: This capability should only be active when the feature flag is enabled
        settings_flag:
          type: array
          description: This capability should only be active when all the settings have the correct value
          items:
            $ref: '#/components/schemas/SettingFlag'
        schemas:
          type: array
          description: Schema-specific configuration for the capability
          items:
            type: object
            additionalProperties: true
            required:
            - schema
            properties:
              schema:
                type: string
                description: Entity schema slug
                example: contact
      required:
      - name
    EntityCapabilityWithCompositeID:
      allOf:
      - $ref: '#/components/schemas/EntityCapability'
      - type: object
        description: a readonly computed ID for the entity capability including schema slug and the capability ID
        properties:
          composite_id:
            type: string
            readOnly: true
            example: contact:97644baa-083f-4e49-9188-fcff2ecaad7d
          schema:
            type: string
            description: Schema slug the capability belongs to
            example: contact
    EntityViewDisabled:
      type: object
      properties:
        view_type:
          type: string
          enum:
          - disabled
    EntityDefaultTable:
      type: object
      properties:
        view_type:
          type: string
          enum:
          - default
        row_actions:
          type: array
          items:
            oneOf:
            - type: string
            - $ref: '#/components/schemas/EntityAction'
        bulk_actions:
          type: array
          items:
            oneOf:
            - type: string
            - $ref: '#/components/schemas/EntityAction'
        navbar_actions:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              options:
                type: array
                items:
                  type: object
                  properties:
                    label:
                      type: string
                    params:
                      type: object
                  required:
                  - label
            required:
            - type
        enable_thumbnails:
          description: Enable the thumbnail column
          type: boolean
          default: false
    EntityDefaultCreate:
      type: object
      properties:
        view_type:
          type: string
          enum:
          - default
        search_params:
          type: object
          additionalProperties:
            type: string
    EntityDefaultEdit:
      type: object
      properties:
        view_type:
          type: string
          enum:
          - default
        search_params:
          type: object
          additionalProperties:
            type: string
        summary_attributes:
          description: List of attribute names that we show in the summary header
          type: array
          items:
            type: string
            example: email
    RedirectEntityView:
      type: object
      properties:
        view_type:
          type: string
          enum:
          - redirect
        route:
          type: string
          example: /app/pricing-hub/product/:entityId
      example:
        type: redirect
        route: /app/pricing-hub/product/:entityId
    EntityId:
      type: string
      format: uuid
    BaseEntity:
      allOf:
      - $ref: '#/components/schemas/Entity'
      - required:
        - _id
        - _title
        - _org
        - _schema
        - _created_at
        - _updated_at
    Entity:
      type: object
      additionalProperties: true
      properties:
        _id:
          allOf:
          - readOnly: true
          - $ref: '#/components/schemas/EntityId'
        _org:
          type: string
          readOnly: true
          description: Organization Id the entity belongs to
        _owners:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/EntityOwner'
        _schema:
          $ref: '#/components/schemas/EntitySlug'
        _title:
          type: string
          description: Title of entity
          nullable: true
        _tags:
          type: array
          items:
            type: string
          nullable: true
        _created_at:
          type: string
          format: date-time
          nullable: true
          readOnly: true
        _updated_at:
          type: string
          format: date-time
          nullable: true
          readOnly: true
        _deleted_at:
          type: string
          format: date-time
          nullable: true
          readOnly: true
        _acl:
          allOf:
          - readOnly: true
          - $ref: '#/components/schemas/EntityAcl'
        _purpose:
          type: array
          items:
            type: string
          nullable: true
        _purpose_name:
          description: Automatically computed purpose names from _purpose attribute
          type: array
          items:
            type: string
          nullable: true
        _manifest:
          type: array
          description: Manifest ID used to create/update the entity
          items:
            type: string
            format: uuid
            example: 123e4567-e89b-12d3-a456-426614174000
          nullable: true
        _changesets:
          readOnly: true
          type: object
          nullable: true
          description: |
            Pending attribute changesets for attributes configured with external or approval edit mode.

            The value shape is `Changeset` (`proposed_value`, `created_at`, `edit_mode`, ...)
            and is what `:apply` / `:dismiss` operate on.

            Read-only via normal entity PATCH/PUT operations — those handlers strip `_changesets`
            from request bodies. Use the changeset management endpoints to mutate this field.
          additionalProperties:
            $ref: '#/components/schemas/Changeset'
      example:
        _id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        _org: '123'
        _owners:
        - org_id: '123'
          user_id: '123'
        _schema: contact
        _tags:
        - example
        - mock
        _created_at: 2021-02-09T12:41:43.662Z
        _updated_at: 2021-02-09T12:41:43.662Z
        _acl:
          view:
          - org:456
          - org:789
          edit:
          - org:456
          delete:
          - org:456
        _manifest:
        - 123e4567-e89b-12d3-a456-426614174000
    NullableEntity:
      allOf:
      - $ref: '#/components/schemas/Entity'
      - type: object
        nullable: true
    EntityOwner:
      description: |
        The user / organization owning this entity.

        Note: Owner implicitly has access to the entity regardless of ACLs.
      type: object
      properties:
        org_id:
          type: string
          example: '123'
        user_id:
          type: string
          example: '123'
      required:
      - org_id
    EntityAcl:
      description: Access control list (ACL) for an entity. Defines sharing access to external orgs or users.
      type: object
      properties:
        view:
          type: array
          items:
            type: string
            example: org:456
        edit:
          type: array
          items:
            type: string
            example: org:456
        delete:
          type: array
          items:
            type: string
            example: org:456
      additionalProperties: true
    HydratedEntity:
      type: object
      description: Entity with relation data resolved into the attribute values
      properties:
        _relations:
          type: array
          items:
            type: object
            properties:
              entity_id:
                $ref: '#/components/schemas/EntityId'
            required:
            - entity_id
      additionalProperties: true
      required:
      - _relations
      example:
        _relations:
        - entity_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        status: active
        customer_number: abc123
        email:
        - label: work
          email: user@example.com
        phone:
        - label: work
          phone: '+49123456789'
        first_name: First Name
        middle_name: Middle Name
        last_name: Last Name
        date_of_birth: '2019-08-24'
        title: Mr.
        account:
        - status: active
          name: Company name
          company_email:
          - label: Company email
            email: company@example.com
          company_phone:
          - label: Support phone
            phone: '+49123456789'
          company_website: https://example.com
          tax_id: DE123456789
          tax_exemption: '2019-08-24'
          contacts:
            $relation:
            - _tags:
              - CEO
              entity_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
    EntityItem:
      allOf:
      - $ref: '#/components/schemas/BaseEntity'
      - $ref: '#/components/schemas/Entity'
    EntityValidationError:
      type: object
      description: Validation error for an entity attribute
      properties:
        code:
          type: string
          description: Error code identifier
          example: custom
        params:
          type: object
          description: Additional parameters for the error
          properties:
            type:
              type: string
              description: The type of the error
              example: missing_field
        path:
          type: array
          description: The path to the attribute that failed validation
          items:
            type: string
          example:
          - first_name
        message:
          type: string
          description: A human-readable message describing the error
          example: Invalid input
      required:
      - code
      - params
      - path
      - message
    EntityValidationResultSuccess:
      type: object
      description: Validation result for a successful validation
      properties:
        status:
          type: string
          enum:
          - success
        errors:
          type: array
          maxItems: 0
          items:
            $ref: '#/components/schemas/EntityValidationError'
      required:
      - status
      - errors
    EntityValidationResultError:
      type: object
      description: Validation result for a failed validation
      properties:
        status:
          type: string
          enum:
          - error
        errors:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/EntityValidationError'
      required:
      - status
      - errors
    EntityValidationResult:
      oneOf:
      - $ref: '#/components/schemas/EntityValidationResultSuccess'
      - $ref: '#/components/schemas/EntityValidationResultError'
    EntityValidationV2Error:
      type: object
      properties:
        keyword:
          type: string
          description: validation keyword.
        instance_path:
          type: string
          description: JSON Pointer to the location in the data instance (e.g., `"/prop/1/subProp"`).
        schema_path:
          type: string
          description: JSON Pointer to the location of the failing keyword in the schema.
        params:
          type: object
          description: Additional information about error.
          additionalProperties: true
        property_name:
          type: string
          description: Set for errors in `propertyNames` keyword schema. `instance_path` still points to the object in this case.
        message:
          type: string
          description: The error message.
        schema:
          type: object
          description: The value of the failing keyword in the schema.
        parent_schema:
          type: object
          description: The schema containing the keyword.
          additionalProperties: true
        data:
          type: object
          description: The data validated by the keyword.
          additionalProperties: true
      required:
      - keyword
      - instance_path
      - schema_path
      - params
    EntityValidationV2ResultSuccess:
      type: object
      description: Validation result for a successful validation
      properties:
        status:
          type: string
          enum:
          - success
        errors:
          type: array
          maxItems: 0
          items:
            $ref: '#/components/schemas/EntityValidationV2Error'
      required:
      - status
      - errors
    EntityValidationV2ResultError:
      type: object
      description: Validation result for a failed validation
      properties:
        status:
          type: string
          enum:
          - error
        errors:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/EntityValidationV2Error'
      required:
      - status
      - errors
    EntityValidationV2Result:
      oneOf:
      - $ref: '#/components/schemas/EntityValidationV2ResultSuccess'
      - $ref: '#/components/schemas/EntityValidationV2ResultError'
    HydratedEntityItem:
      allOf:
      - $ref: '#/components/schemas/BaseEntity'
      - $ref: '#/components/schemas/HydratedEntity'
    GetRelationsResp:
      type: array
      items:
        anyOf:
        - $ref: '#/components/schemas/RelationItem'
        - $ref: '#/components/schemas/RelationEntity'
    GetRelationsRespWithPagination:
      type: object
      properties:
        hits:
          type: number
          example: 1
        relations:
          $ref: '#/components/schemas/GetRelationsResp'
    GetRelatedEntitiesCount:
      type: object
      properties:
        hits:
          type: integer
          example: 1
    RelationEntity:
      allOf:
      - $ref: '#/components/schemas/BaseEntity'
      - type: object
        properties:
          $relation:
            $ref: '#/components/schemas/RelationItem'
    RelationItem:
      type: object
      properties:
        entity_id:
          $ref: '#/components/schemas/EntityId'
        org_id:
          type: string
          description: Organization Id the entity belongs to
        _schema:
          $ref: '#/components/schemas/EntitySlug'
        attribute:
          type: string
        _tags:
          type: array
          items:
            type: string
        reverse:
          description: Whether this is a reverse relation
          type: boolean
      required:
      - entity_id
      - attribute
    EntitySearchIncludeDeletedParam:
      type: string
      enum:
      - 'true'
      - 'false'
      - only
      description: |
        Whether to include deleted entities in the search results
        - `true`: include deleted entities
        - `false`: exclude deleted entities
        - `only`: include only deleted entities

        By default, no deleted entities are included in the search results.
      default: 'false'
    EntitySearchParams:
      allOf:
      - type: object
        properties:
          q:
            description: Lucene [queries supported with ElasticSearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax)
            type: string
            example: _schema:contact AND status:active
          include_scores:
            type: boolean
            default: false
            description: Adds a `_score` number field to results that can be used to rank by match score
          sort: {}
          from: {}
          size: {}
          hydrate: {}
          anonymize: {}
          fields: {}
          aggs: {}
          include_deleted: {}
          highlight: {}
          stable_for: {}
          stable_query_id: {}
          search_after: {}
        additionalProperties: false
        required:
        - q
      - $ref: '#/components/schemas/EntitySearchOptions'
    EntityListParams:
      allOf:
      - type: object
        properties:
          query:
            description: Query configuration object for searching entities
            type: object
            properties:
              query_string:
                description: Query string configuration based on Elasticsearch query_string query
                type: object
                properties:
                  query:
                    description: The actual query string using Lucene query syntax
                    type: string
                    example: status:active
                  fields:
                    description: List of fields to search in. If not provided, searches in default fields
                    type: array
                    items:
                      type: string
                    example:
                    - _title
                    - _tags
                    - status
                  default_operator:
                    description: The default boolean operator used if no explicit operator is specified
                    type: string
                    enum:
                    - AND
                    - OR
                    default: OR
                  lenient:
                    description: If true, format-based errors are ignored
                    type: boolean
                    default: true
                required:
                - query
            required:
            - query_string
          filter:
            $ref: '#/components/schemas/SearchFilter'
          allow_targeting_all_schemas:
            type: boolean
            default: false
            description: Allow running the listing without any schema filter. This is disabled by default to prevent security and performance issues if done by an accident.
          sort: {}
          from: {}
          size: {}
          hydrate: {}
          anonymize: {}
          fields: {}
          aggs: {}
          include_deleted: {}
          include_scores: {}
          highlight: {}
          stable_for: {}
          stable_query_id: {}
          search_after: {}
        additionalProperties: false
        required:
        - filter
      - $ref: '#/components/schemas/EntitySearchOptions'
    SearchFilter:
      type: array
      description: A subset of simplified Elasticsearch query clauses. The default operator is a logical AND. Use nested $and, $or, $not to combine filters using different logical operators.
      items:
        type: object
        minProperties: 1
        maxProperties: 1
        properties:
          term:
            description: |
              Returns documents that contain an exact term in a provided field.

              To return a document, the query term must exactly match the queried field's value, including whitespace and capitalization.

              You likely DO NOT want to use this filter on text fields and want to target its .keyword instead.
            externalDocs:
              url: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-term-query.html
            type: object
            minProperties: 1
            maxProperties: 1
            additionalProperties:
              $ref: '#/components/schemas/SearchFilterValue'
            example:
              _schema: contact
          terms:
            description: Returns documents that contain one of the exact terms in a provided field. See term filter for more info.
            externalDocs:
              url: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-terms-query.html
            type: object
            minProperties: 1
            maxProperties: 1
            additionalProperties:
              type: array
              items:
                $ref: '#/components/schemas/SearchFilterValue'
            example:
              status:
              - active
          ids:
            description: Returns documents based on their IDs.
            externalDocs:
              url: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-ids-query.html
            type: object
            properties:
              values:
                type: array
                items:
                  type: string
            example:
              values:
              - 550e8400-e29b-41d4-a716-446655440000
          range:
            description: Returns documents with fields that have terms within a certain range.
            externalDocs:
              url: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-range-query.html
            type: object
            minProperties: 1
            maxProperties: 1
            additionalProperties:
              type: object
              properties:
                gt:
                  $ref: '#/components/schemas/SearchFilterValue'
                gte:
                  $ref: '#/components/schemas/SearchFilterValue'
                lt:
                  $ref: '#/components/schemas/SearchFilterValue'
                lte:
                  $ref: '#/components/schemas/SearchFilterValue'
                format:
                  type: string
                  description: The date format used to parse date values.
                relation:
                  type: string
                  enum:
                  - INTERSECTS
                  - CONTAINS
                  - WITHIN
                  description: Indicates how the range query matches values for range fields.
                time_zone:
                  type: string
                  description: Coordinated Universal Time (UTC) offset or IANA time zone used to convert date values in the query to UTC.
            example:
              _created_at:
                gte: '2021-01-01T00:00:00.000Z'
                lte: '2021-01-31T23:59:59.999Z'
          exists:
            description: Returns documents that have a value in the specified field.
            externalDocs:
              url: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-exists-query.html
            type: object
            properties:
              field:
                type: string
            required:
            - field
            example:
              field: _tags
          $and:
            $ref: '#/components/schemas/SearchFilter'
          $or:
            $ref: '#/components/schemas/SearchFilter'
          $not:
            $ref: '#/components/schemas/SearchFilter'
      example:
      - term:
          _schema: contact
      - terms:
          status:
          - active
    SearchFilterValue:
      description: A filter field value.
      oneOf:
      - type: string
        nullable: true
      - type: number
      - type: boolean
    EntitySearchOptions:
      type: object
      properties:
        sort:
          description: You can pass one sort field or an array of sort fields. Each sort field can be a string
          oneOf:
          - type: string
          - type: array
            items:
              type: string
        from:
          type: integer
          minimum: 0
          default: 0
          description: |
            The offset from which to start the search results.
            Only one of `from` or `search_after` should be used.
        size:
          type: integer
          minimum: 0
          default: 10
          description: Max search size is 1000 with higher values defaulting to 1000
        hydrate:
          type: boolean
          description: When true, enables entity hydration to resolve nested $relation & $relation_ref references in-place.
          default: false
        anonymize:
          type: boolean
          description: |
            When true, anonymizes PII in the response: identifiers are replaced with deterministic pseudonyms,
            addresses are generalized and well-known free-text fields are redacted.
            Anonymization is forced (regardless of this parameter) when the access token was created with `anonymize: true`.
          default: false
        fields:
          $ref: '#/components/schemas/FieldsParam'
        aggs:
          type: object
          description: Aggregation supported by ElasticSearch allows summarizing data as metrics, statistics, or other analytics.
          example:
            contact-count-per-tag:
              terms:
                field: _tags.keyword
        include_deleted:
          $ref: '#/components/schemas/EntitySearchIncludeDeletedParam'
        include_scores:
          type: boolean
          description: Adds a `_score` number field to results that can be used to rank by match score
          default: false
        stable_for:
          type: integer
          minimum: 0
          maximum: 60
          description: |
            A TTL (in seconds) that specifies how long the context should be maintained.
            Defaults to 30 seconds; configurable up to 60 seconds to prevent abuse.
            A value of 0 can be provided the close the context after the query.
            Defaults to none.
        stable_query_id:
          type: string
          description: |
            A unique identifier of the query context from the last stable query.
            The context is maintained for the duration of the stable_for value.
        search_after:
          type: array
          items:
            oneOf:
            - type: string
              nullable: true
            - type: number
              nullable: true
          description: |
            The sort values from which to start the search results.
            Only one of `from` or `search_after` should be used.
            It is strongly recommended to always use the `sort_end` field from the last search result.
            Used for deep pagination, typically together with `stable_query_id` to maintain the context between requests.
            Requires explicit sort to work reliably.
            Typically used sort fields are `_id` or `_created_at`.
    FieldsParam:
      type: array
      description: |
        List of entity fields to include or exclude in the response

        Use ! to exclude fields, e.g. `!_id` to exclude the `_id` field.

        Globbing and globstart (**) is supported for nested fields.
      items:
        type: string
      example:
      - _id
      - _title
      - first_name
      - account
      - '!account.*._files'
      - '**._product'
    EntityImportParams:
      type: object
      additionalProperties: false
      properties:
        S3Reference:
          type: object
          properties:
            bucket:
              type: string
              description: The name of the S3 bucket where the JSON file for import is stored.
              example: my-bucket
            key:
              type: string
              description: The key or path to the JSON file within the S3 bucket.
              example: imports/my-import.json
          required:
          - bucket
          - key
          description: The S3 bucket and key where the JSON file for import is located.
        schema:
          type: string
          description: The schema of the entities being imported. This must match the schema of the entities on the platform.
          example: contact
      required:
      - S3Reference
      - schema
      description: The parameters for importing entities.
    GraphQueryRequest:
      type: object
      required:
      - seed
      - graph
      properties:
        seed:
          $ref: '#/components/schemas/GraphSeed'
        graph:
          $ref: '#/components/schemas/GraphDefinition'
        hydrate:
          type: boolean
          description: If true, return full entity objects in entityNodes instead of just entity IDs in nodes
          default: false
        apply_changesets:
          type: boolean
          description: When true and hydrate is also true, entity objects in entityNodes have pending changeset proposed values applied in-place. The _changesets field is still included in the response.
          default: false
    GraphSeed:
      type: object
      required:
      - entity_id
      - node_id
      properties:
        entity_id:
          $ref: '#/components/schemas/EntityId'
        node_id:
          type: string
          description: The node ID in the graph definition that corresponds to the seed entity
          example: contact
    GraphDefinition:
      type: object
      required:
      - nodes
      - edges
      properties:
        nodes:
          type: array
          description: List of node definitions in the graph
          items:
            $ref: '#/components/schemas/GraphNode'
          example:
          - id: portal_user
            schema: portal_user
            cardinality: one
          - id: contact
            schema: contact
            cardinality: one
          - id: billing_accounts
            schema: billing_account
            cardinality: many
        edges:
          type: array
          description: List of edge definitions connecting nodes
          items:
            $ref: '#/components/schemas/GraphEdge'
          example:
          - from: portal_user
            to: contact
          - from: contact
            to: billing_accounts
    GraphNode:
      type: object
      required:
      - id
      - schema
      properties:
        id:
          type: string
          description: Unique identifier for this node in the graph definition
          example: contact
        schema:
          type: string
          description: Entity schema slug for this node
          example: contact
        cardinality:
          type: string
          enum:
          - one
          - many
          description: |
            Optional cardinality for this node when used with hydrate=true:
            - "one": Node can only contain one entity, return single Entity object in entityNodes
            - "many": Node can contain multiple entities, return array of Entity objects in entityNodes
            If not specified, defaults to "many" (returns array). The seed node always returns a single entity regardless of this setting.
          example: one
        fields:
          allOf:
          - $ref: '#/components/schemas/FieldsParam'
          - description: |
              Optional array of field names to include in the hydrated entity response for this node.
              When specified, only the requested fields plus required internal fields (_id, _schema, _org) will be returned.
              Only applies when hydrate=true.
        filter:
          type: array
          description: |
            Narrows this node's traversal results to entities matching every filter (AND semantics). Useful for
            disambiguating among multiple entities reachable via the same graph edge.
          items:
            $ref: '#/components/schemas/GraphNodeFilter'
    GraphNodeFilter:
      type: object
      description: Entities are included in this node's result only if `attribute` exactly equals the literal `value`.
      required:
      - attribute
      - value
      properties:
        attribute:
          type: string
          description: Entity attribute name to match against. Must be a plain attribute name, not an Elasticsearch field path.
          example: order_number
        value:
          allOf:
          - $ref: '#/components/schemas/SearchFilterValue'
          - description: Literal value the attribute must exactly equal for the entity to be included in this node's result.
          example: OR-113
    GraphEdge:
      type: object
      required:
      - from
      - to
      properties:
        from:
          type: string
          description: Source node ID
          example: contact
        to:
          type: string
          description: Target node ID
          example: billing_account
    GraphQueryResponse:
      type: object
      properties:
        nodes:
          type: object
          description: Map of node IDs to arrays of entity IDs found for that node (present when hydrate=false)
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/EntityId'
          example:
            portal_user:
            - 550e8400-e29b-41d4-a716-446655440001
            contact:
            - 550e8400-e29b-41d4-a716-446655440002
            billing_accounts:
            - 550e8400-e29b-41d4-a716-446655440003
            - 550e8400-e29b-41d4-a716-446655440004
        entityNodes:
          type: object
          description: |
            Map of node IDs to entity objects or arrays of entity objects (present when hydrate=true).
            The seed node and nodes with cardinality="one" return a single Entity object, or null if no entity was found.
            Nodes with cardinality="many" return an array of Entity objects.
          additionalProperties:
            oneOf:
            - $ref: '#/components/schemas/NullableEntity'
            - type: array
              items:
                $ref: '#/components/schemas/Entity'
          example:
            portal_user:
              _id: 550e8400-e29b-41d4-a716-446655440001
              _schema: portal_user
            contact:
              _id: 550e8400-e29b-41d4-a716-446655440002
              _schema: contact
            billing_accounts:
            - _id: 550e8400-e29b-41d4-a716-446655440003
              _schema: billing_account
            - _id: 550e8400-e29b-41d4-a716-446655440004
              _schema: billing_account
        edges:
          type: array
          description: List of edges as defined in the request
          items:
            $ref: '#/components/schemas/GraphEdge'
          example:
          - from: portal_user
            to: contact
          - from: contact
            to: billing_accounts
      required:
      - edges
    EntitySearchResults:
      type: object
      properties:
        hits:
          type: number
          example: 1
        results:
          type: array
          items:
            $ref: '#/components/schemas/EntityItem'
        aggregations:
          type: object
          example:
            contact-count-per-tag:
              doc_count_error_upper_bound: 0
              sum_other_doc_count: 23
              buckets:
              - key: automation
                doc_count: 108
              - key: primary
                doc_count: 66
        stable_query_id:
          type: string
          description: |
            A unique identifier of the query context.
            Should be used on the input for the next query that needs to be executed in the same context.
        sort_end:
          type: array
          items:
            oneOf:
            - type: string
              nullable: true
            - type: number
              nullable: true
          description: |
            The sort value of the last item returned in `results`.
            Can be used as the input for the `search_after` in the next query.
          example:
          - 1747905443332
          - '0.000023312468'
    SearchMappings:
      description: |
        Advanced: explicit Elasticsearch index mapping definitions for entity data
      example:
        image:
          type: keyword
          index: false
      type: object
      additionalProperties:
        type: object
        properties:
          index:
            type: boolean
            default: true
          type:
            type: string
            enum:
            - keyword
            - text
            - boolean
            - integer
            - long
            - float
            - date
            - flattened
            - nested
            - object
          fields:
            additionalProperties: true
          dynamic:
            type: boolean
            description: When false, prevents ES from inferring types for nested fields. Used for _changesets where values can be any type.
    ActivityId:
      type: string
      format: ulid
      description: See https://github.com/ulid/spec
      example: 01F130Q52Q6MWSNS8N2AVXV4JN
      pattern: ^01[0-9a-zA-Z]{24}$
    ActivityCallerContext:
      type: object
      additionalProperties: true
      properties:
        EpilotAuth:
          type: object
          properties:
            token:
              type: object
              properties:
                sub:
                  type: string
                  example: 476e9b48-42f4-4234-a2b0-4668b34626ce
                email:
                  type: string
                  example: example@epilot.cloud
                cognito:username:
                  type: string
                  example: example@epilot.cloud
                custom:ivy_user_id:
                  type: string
                  example: '10006129'
              example:
                sub: 476e9b48-42f4-4234-a2b0-4668b34626ce
                cognito:groups:
                - Administrator
                cognito:preferred_role: arn:aws:iam::912468240823:role/base-administrator-role
                iss: https://cognito-idp.eu-central-1.amazonaws.com/eu-central-1_6lZSgmU6D
                custom:ivy_org_id: '739224'
                cognito:username: n.ahmad@epilot.cloud
                custom:ivy_user_id: '10006129'
                cognito:roles:
                - arn:aws:iam::912468240823:role/base-administrator-role
                aud: 6e0jbdnger7nmoktaaflarue1l
                event_id: cd5f5583-d90c-4db5-8e99-5f5dd29a4d75
                token_use: id
                auth_time: 1614333023
                exp: 1614336623
                iat: 1614333023
                email: n.ahmad@epilot.cloud
    ActivityType:
      type: string
      description: |
        A type for the activity. Used to categorize activities in the activity feed and for event subscriptions.

        Built-in entity activity types (custom activities can be defined as well):
        - EntityCreated
        - EntityUpdated
        - EntityDeleted
        - EntitySoftDeleted
        - EntityRestored
        - RelationsAdded
        - RelationsRemoved
        - RelationsSoftDeleted
        - RelationsRestored
        - RelationsDeleted
        - ChangesetCreated
        - ChangesetAutoCleared
        - ChangesetApplied
        - ChangesetDismissed
    Activity:
      type: object
      additionalProperties: false
      properties:
        type:
          $ref: '#/components/schemas/ActivityType'
        title:
          type: string
          description: Title for activity. Supports handlebars syntax.
          example: My custom activity
        message:
          type: string
          description: Message for activity. Supports handlebars syntax.
          example: '{{caller}} did something with {{entity payload.entity.id}}.'
        payload:
          type: object
          properties: {}
          additionalProperties: true
          example:
            entity:
              id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
              schema: contact
        pending:
          type: boolean
          description: |
            Indicates whether the activity is in the pending state.
            Pending activities are not yet visible in the activity feed and events are not yet dispatched.
          default: false
      required:
      - type
      - title
      - message
    EntityOperation:
      type: object
      properties:
        entity:
          $ref: '#/components/schemas/EntityId'
        org:
          type: string
          example: '123'
        activity_id:
          $ref: '#/components/schemas/ActivityId'
        activity_type:
          $ref: '#/components/schemas/ActivityType'
        operation:
          type: string
          enum:
          - createEntity
          - updateEntity
          - deleteEntity
          - softDeleteEntity
          - restoreEntity
          - relationsAdded
          - relationsRemoved
          - relationsSoftDeleted
          - relationsRestored
          - relationsDeleted
        params:
          type: object
          properties:
            id:
              $ref: '#/components/schemas/EntityId'
            slug:
              $ref: '#/components/schemas/EntitySlug'
          example:
            id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            slug: contact
        payload:
          allOf:
          - $ref: '#/components/schemas/Entity'
          - example:
              _schema: contact
              _org: '123'
              status: Inactive
        diff:
          type: object
          properties:
            added:
              allOf:
              - description: New attributes added to the entity as part of the operation
              - $ref: '#/components/schemas/Entity'
            updated:
              allOf:
              - description: 'Attributes updated in the entity. Note: These values contain the previous values before the update!'
              - $ref: '#/components/schemas/Entity'
            deleted:
              allOf:
              - description: Attributes removed from the entity as part of the operation
              - $ref: '#/components/schemas/Entity'
        source_context:
          $ref: '#/components/schemas/EntityOperationSourceContext'
        _workflow_origin:
          type: object
          description: |
            Internal property for workflow origin tracking and infinite loop prevention.
            Populated when an entity update originates from a workflow execution.
            This allows downstream automation services to prevent circular triggering.
          properties:
            workflow_exec_id:
              type: string
              description: The ID of the workflow execution that triggered this entity update
            flow_template_id:
              type: string
              description: The flow template ID - used to detect and prevent circular triggering
        _automation_chain:
          type: array
          description: Ordered automation flow ids that caused this change; used to break multi-automation trigger loops.
          items:
            type: string
      required:
      - entity
      - org
      - operation
    EntityOperationSourceContext:
      type: object
      description: Billing and audit source context for the operation event.
      properties:
        source:
          type: string
          description: Normalized source bucket for the operation.
          enum:
          - portal
          - epilot
          - erp
          - system
          - api
          - external
          - journey
          - automation
          - unknown
        source_label:
          type: string
          description: Original free-form source label from the caller or changeset, when available.
        source_system:
          type: string
          description: Optional upstream system label, for example an ERP system name.
        source_reference:
          type: string
          description: Optional upstream change reference.
        actor_type:
          type: string
          enum:
          - user
          - portal_user
          - api_client
          - automation
          - system
        actor_id:
          type: string
        effective_at:
          type: string
          format: date-time
      required:
      - source
    BaseActivityItem:
      allOf:
      - type: object
        properties:
          _id:
            $ref: '#/components/schemas/ActivityId'
          timestamp:
            type: string
            format: date-time
      - $ref: '#/components/schemas/Activity'
      - type: object
        properties:
          caller:
            $ref: '#/components/schemas/ActivityCallerContext'
    ActivityItem:
      allOf:
      - $ref: '#/components/schemas/BaseActivityItem'
      - type: object
        properties:
          operations_total:
            type: integer
            description: Count of total operations attached to this activity
            example: 1
          operations:
            type: array
            items:
              $ref: '#/components/schemas/EntityOperation'
    BlueprintEntityId:
      description: Reference to blueprint
      type: string
      format: uuid
    ListSavedViewsResults:
      type: object
      properties:
        hits:
          type: number
          example: 1
        results:
          type: array
          items:
            $ref: '#/components/schemas/SavedViewItem'
    SavedViewId:
      description: Generated uuid for a saved view
      type: string
      format: uuid
    SavedViewItem:
      allOf:
      - type: object
        properties:
          id:
            $ref: '#/components/schemas/SavedViewId'
          created_at:
            type: string
          updated_at:
            type: string
      - $ref: '#/components/schemas/SavedView'
    SavedViewPartial:
      description: A saved entity view
      type: object
      properties:
        slug:
          type: array
          description: list of schemas a view can belong to
          items:
            $ref: '#/components/schemas/EntitySlug'
        name:
          description: User-friendly identifier for the saved view
          type: string
          example: View listing German
          minLength: 1
          maxLength: 100
        org:
          description: Organisation ID a view belongs to
          type: string
          example: '66'
        shared:
          description: boolean property for if a view is shared with organisation
          type: boolean
          example: true
        isFavoritedBy:
          description: List of users (IDs) that have favorited the view
          type: array
          items:
            type: string
            example: '11701'
        created_by:
          anyOf:
          - type: object
            description: A user that created the view
            properties:
              user_id:
                type: string
                example: '10598'
              org_id:
                type: string
                description: The organization ID of the user who created the view. Used for partner access control.
                example: '739224'
          - type: object
            description: A system-created view
            properties:
              source:
                type: string
                enum:
                - SYSTEM
                - BLUEPRINT
            additionalProperties: true
        ui_config:
          type: object
          additionalProperties: true
          example:
            filters:
              customer_name: suresh test
              _tags: '360'
            table_layout:
              opportunity:
                page: 1
                sort: _created_at:desc
                pageSize: 25
                columnSettings: []
        shared_with:
          type: array
          description: List of users ('${userId}'), user groups ('group_${groupId}'), or partner users ('${partnerOrgId}_${partnerUserId}') that the view is shared with
          items:
            type: string
            example: '112233'
    SavedView:
      description: A saved entity view
      allOf:
      - $ref: '#/components/schemas/SavedViewPartial'
      - type: object
        required:
        - slug
        - name
        - ui_config
    Taxonomy:
      type: object
      properties:
        slug:
          $ref: '#/components/schemas/TaxonomySlug'
        name:
          type: string
          description: A human friendly name of a Taxonomy e.g. Purpose, Product Category, Folder, Tag
          example: Purpose
        plural:
          type: string
          description: Plural name of a Taxonomy e.g. Purposes, Product Categories, Folders, Tags. Defaults to name is not provided.
          example: Purposes
        kind:
          readOnly: true
          type: string
          enum:
          - system
          - user_defined
          description: Kind of taxonomy e.g. system or user_defined. By default, it's empty, which means 'user_defined'
          example: system
        type:
          type: string
          enum:
          - entity
          - relation
          - system
          - file_collection
          description: |
            Type of taxonomy. Whether it classifies:
            - entity (default)
            - relation (for relations)
            - system (for system taxonomies - default for all slugs starting with _system_)
            - file_collection (for file collections)
          default: entity
          example: entity
        icon:
          type: string
          description: Icon name for the taxonomy (from epilot360/icons icon set)
          example: purpose
        color:
          type: string
          description: HEX Color code for the taxonomy
          example: '#FF5733'
        created_at:
          readOnly: true
          type: string
          format: date-time
        updated_at:
          readOnly: true
          type: string
          format: date-time
        deleted_at:
          readOnly: true
          type: string
          format: date-time
          description: 'Date when the taxonomy was soft-deleted (enabled: false)'
        created_by:
          readOnly: true
          type: string
          description: User ID of the creator
          example: '10598'
        enabled:
          type: boolean
          description: Whether the taxonomy is enabled or not
          example: true
        order:
          type: number
          description: Position of the taxonomy
          example: 10
        enabled_locations:
          description: List of locations where the taxonomy is enabled to be used. If empty, it's enabled for all locations.
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/TaxonomyLocationId'
            - type: string
    TaxonomyLocationId:
      type: string
      enum:
      - account
      - contact
      - contract
      - email_template
      - file
      - journey
      - meter_counter
      - meter
      - opportunity
      - order
      - partner
      - price
      - product
      - submission
      - tax
      - message
      - portal_user
      - request
      - comment
      - user
    TaxonomySearchIncludeArchivedParam:
      type: string
      enum:
      - 'true'
      - 'false'
      - only
      description: |
        Whether to include archived labels in the search results
        - `true`: include archived labels
        - `false`: exclude archived labels
        - `only`: include only archived labels

        By default, no archived labels are included in the search results.
      default: 'false'
    TaxonomyClassification:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ClassificationId'
        slug:
          type: string
          description: URL-friendly identifier for the classification
          example: wallbox-pv
        name:
          type: string
          example: Wallbox PV
        parents:
          type: array
          items:
            $ref: '#/components/schemas/ClassificationId'
        color:
          type: string
          description: Color of the classification
          example: '#FF5733'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        archived:
          type: boolean
          description: Archived classification are not visible in the UI
          default: false
        starred:
          type: boolean
          description: Starred taxonomy classifications can represent "favorites" or commonly used classifications
          default: false
        enabled_locations:
          description: List of locations where the classification is enabled to be used. If empty, it's enabled for all locations.
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/TaxonomyLocationId'
            - type: string
        enabled_purposes:
          description: List of purpose slugs where the classification is enabled to be used. If empty, it's enabled for all purposes.
          type: array
          items:
            type: string
        _manifest:
          type: array
          description: Manifest ID used to create/update the taxonomy classification
          items:
            type: string
            format: uuid
            example: 123e4567-e89b-12d3-a456-426614174000
          nullable: true
      required:
      - name
      - slug
    ClassificationId:
      type: string
      example: taxonomy-slug:classification-slug
      readOnly: true
    ClassificationIdOrPattern:
      anyOf:
      - $ref: '#/components/schemas/ClassificationId'
      - type: object
        properties:
          pattern:
            type: string
            example: taxonomy-slug:*
            description: Wildcard pattern to match classification IDs starting with the prefix before ':*'
        required:
        - pattern
    ClassificationSlug:
      type: string
      description: URL-friendly identifier for the classification
      example: wallbox-pv
    TaxonomySlug:
      type: string
      description: URL-friendly name for taxonomy
      example: purpose
    ClassificationsUpdate:
      type: object
      properties:
        create:
          type: array
          items:
            $ref: '#/components/schemas/TaxonomyClassification'
        update:
          type: array
          items:
            $ref: '#/components/schemas/TaxonomyClassification'
        delete:
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/ClassificationId'
            - type: string
              example: taxonomy-slug:classification-slug
    TaxonomyBulkJobTriggerResponse:
      type: object
      properties:
        job_id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/TaxonomyBulkJobStatus'
    TaxonomyBulkJobStatus:
      type: string
      description: The status of the bulk job
      enum:
      - PENDING
      - FAILED
      - COMPLETED
      - CANCELLED
    TaxonomyBulkJobActionType:
      type: string
      enum:
      - MOVE_CLASSIFICATIONS
      - MERGE_CLASSIFICATIONS
      - DELETE_CLASSIFICATIONS
    TaxonomyBulkJob:
      type: object
      properties:
        job_id:
          type: string
          format: uuid
        job_status:
          $ref: '#/components/schemas/TaxonomyBulkJobStatus'
        failure_reason:
          type: string
        action_type:
          $ref: '#/components/schemas/TaxonomyBulkJobActionType'
        request:
          type: object
          properties:
            target_taxonomy:
              $ref: '#/components/schemas/TaxonomySlug'
            target_classification:
              $ref: '#/components/schemas/ClassificationId'
            classification_ids:
              type: array
              items:
                $ref: '#/components/schemas/ClassificationId'
        output:
          type: object
          properties:
            target_entities_count:
              type: number
            affected_entities_count:
              type: number
            failures_count:
              type: number
            failed_entities:
              type: array
              items:
                $ref: '#/components/schemas/EntityId'
        created_by:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        org:
          type: string
      example:
        job_id: 123e4567-e89b-12d3-a456-426614174000
        status: PENDING
        action_type: MOVE_CLASSIFICATIONS
        created_by: '10598'
        created_at: 2024-01-01T00:00:00.000Z
        updated_at: 2024-01-01T00:00:00.000Z
        org: '66'
    ESClusterAssignment:
      type: object
      properties:
        orgId:
          type: string
          description: The organization for which the cluster assignment is returned
        cluster:
          type: string
          description: Name of the elastic cluster the organization is assigned to
    SettingFlag:
      type: object
      properties:
        name:
          type: string
          description: The name of the organization setting to check
        enabled:
          type: boolean
          description: Whether the setting should be enabled or not
    ErrorObject:
      description: A generic error returned by the API
      type: object
      properties:
        status:
          type: integer
          description: The HTTP status code of the error
          example: 400
        error:
          type: string
          description: The error message
          example: Bad Request
    ChangesetCreator:
      type: object
      description: Identifies the actor that created the changeset.
      properties:
        type:
          type: string
          description: Type of actor that created the changeset
          enum:
          - user
          - portal_user
          - api_client
          - automation
        id:
          type: string
          description: ID of the actor (user ID, portal user ID, API client ID, etc.)
    Changeset:
      type: object
      description: A pending proposed change for a single entity attribute, awaiting external confirmation or human approval.
      required:
      - proposed_value
      - created_at
      - edit_mode
      properties:
        proposed_value:
          description: The proposed new value for the attribute. Type matches the attribute type.
        previous_value:
          description: The attribute value at the time the changeset was created. Stored for reference.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the changeset was created
        created_by:
          $ref: '#/components/schemas/ChangesetCreator'
        edit_mode:
          type: string
          description: |
            The edit mode that triggered this changeset.
            - `external`: auto-cleared by a matching `?direct=true` write (see `match_strategy`).
            - `approval`: resolved only via explicit `:apply` / `:dismiss` endpoints; never auto-clears.
          enum:
          - external
          - approval
        match_strategy:
          description: |
            Match strategy copied from the attribute's `edit_mode_config` at changeset
            creation time. Only consulted when `edit_mode` is `external`; ignored for
            `approval` (which never auto-clears).
          allOf:
          - $ref: '#/components/schemas/MatchStrategy'
        source:
          type: string
          description: Optional label indicating where the change originated (e.g. end_customer_portal, installer_portal, journey, automation)
        related_values:
          type: object
          description: Proposed and previous values for related fields in a multi-field attribute group (e.g. currency _decimal/_currency suffixes). Keyed by full field name.
          additionalProperties:
            type: object
            properties:
              proposed_value:
                description: The proposed new value for the related field.
              previous_value:
                description: The value of the related field when the changeset was created.
    ChangesetMap:
      type: object
      description: Map of attribute name to pending changeset. At most one changeset per attribute.
      additionalProperties:
        $ref: '#/components/schemas/Changeset'
    MeterReadingChangesetEntry:
      type: object
      description: |
        A meter readings changeset entry — service-managed by metering-api.
        Stored on `Meter._meter_readings_changeset` array attribute. Each entry mirrors a
        ClickHouse meter reading row plus a changeset metadata overlay.

        Note: `org_id` is NOT stored on the entry. The entries live on the Meter entity,
        which is already org-scoped (`_org`). Round-tripping it would only invite drift;
        downstream consumers receive the org from the meter / handler context.
      required:
      - changeset_id
      - meter_id
      - counter_id
      - value
      - edit_mode
      - created_at
      properties:
        value:
          type: number
        direction:
          type: string
          enum:
          - feed-in
          - feed-out
        timestamp:
          type: string
          format: date-time
        meter_id:
          type: string
          format: uuid
        counter_id:
          type: string
          format: uuid
        source:
          type: string
        reason:
          type: string
        read_by:
          type: string
        status:
          type: string
          enum:
          - valid
          - in-validation
          - implausible
        external_id:
          type: string
        remark:
          type: string
        metadata:
          type: object
          additionalProperties:
            type: string
        changeset_id:
          type: string
          description: Unique changeset identifier (UUID v4).
        edit_mode:
          type: string
          enum:
          - external
          - approval
        match_strategy:
          type: string
          enum:
          - exact
          - fuzzy
        timestamp_tolerance:
          description: |
            Slack on `reading.timestamp` when metering-api auto-clear matches an
            incoming reading against this pending changeset.

            Variants:
            - `'exact'`: strict millisecond equality.
            - `{ type: 'same-day', timezone? }`: strip the time component and
              compare year-month-day. Optional `timezone` is an IANA name
              (e.g. `'Europe/Berlin'`); the day is bucketed in that zone.
              Defaults to UTC when omitted.
            - `{ type: 'within-seconds', seconds }`: symmetric ±N-second window.
          oneOf:
          - type: string
            enum:
            - exact
          - type: object
            required:
            - type
            properties:
              type:
                type: string
                enum:
                - same-day
              timezone:
                type: string
                description: |
                  IANA timezone identifier (e.g. `'Europe/Berlin'`, `'UTC'`).
                  When omitted, the day is bucketed in UTC.
          - type: object
            required:
            - type
            - seconds
            properties:
              type:
                type: string
                enum:
                - within-seconds
              seconds:
                type: integer
                minimum: 0
                description: Tolerance in seconds. e.g. 60 = ±1 minute, 3600 = ±1 hour.
        fuzzy_config:
          type: object
          properties:
            percentage_threshold:
              type: number
            absolute_threshold:
              type: number
        created_at:
          type: string
          format: date-time
        created_by:
          $ref: '#/components/schemas/ChangesetCreator'
        previous:
          type: object
          properties:
            value:
              type: number
            direction:
              type: string
              enum:
              - feed-in
              - feed-out
            timestamp:
              type: string
              format: date-time
    EditMode:
      type: string
      description: |
        Controls whether a write goes through immediately or is held as a pending entry
        on the parent entity's `_changesets` map.

        - `direct`: write applied immediately. No changeset created.
        - `external`: write held as a pending changeset; auto-cleared on a matching direct/ERP write.
        - `approval`: write held as a pending changeset; requires explicit human apply/dismiss.

        Used at two levels: per-attribute (entity-attribute changesets) and per-capability
        (currently the `meter_readings` capability on the Meter schema, gating reading submissions).
      enum:
      - direct
      - external
      - approval
      default: direct
    EditModeConfig:
      type: object
      description: |
        Configuration for `edit_mode: external` auto-clear matching.
        Fields here (`match_strategy`, `fuzzy_config`) only take effect when
        `edit_mode` is `external`. They are ignored for `edit_mode: approval`,
        which never auto-clears and is resolved exclusively via the
        `:apply` / `:dismiss` changeset endpoints.
      properties:
        match_strategy:
          $ref: '#/components/schemas/MatchStrategy'
        fuzzy_config:
          $ref: '#/components/schemas/FuzzyConfig'
    FuzzyConfig:
      type: object
      description: |
        Configuration for fuzzy auto-clear matching on `edit_mode: external` attributes.
        Not used for `edit_mode: approval`.

        Type compatibility with attribute shape is enforced at schema save time:
        - scalar string attributes: `suffix`, `digits_only`, `regex`
        - repeatable attributes: `set_equivalent`, `entry_match`, `ignore_fields`, `normalize_phone`
        - relation attributes: `relation_set`
      required:
      - type
      properties:
        type:
          type: string
          description: Which fuzzy algorithm to apply.
          enum:
          - suffix
          - digits_only
          - normalize_phone
          - ignore_fields
          - set_equivalent
          - entry_match
          - relation_set
          - regex
        suffix_length:
          type: integer
          description: 'For type=suffix: number of characters to compare from end of string.'
        fields_to_ignore:
          type: array
          items:
            type: string
          description: 'For type=ignore_fields and type=set_equivalent: field names to exclude when comparing array entries. `_id` is always stripped by the platform regardless of this config.'
        regex_flags:
          type: string
          description: 'For type=regex: flags to apply to the regex (e.g. ''i'' for case-insensitive).'
        country_code:
          type: string
          description: 'For type=normalize_phone: country dialing code digits to strip (e.g. ''49'' for Germany). No ''+'' prefix.'
        match_on:
          type: string
          description: 'For type=normalize_phone: attribute key within array entries to compare on (e.g. ''phone_number'').'
        key:
          description: 'For type=entry_match: business key(s) within each entry used to match proposed entries against incoming entries.'
          oneOf:
          - type: string
          - type: array
            items:
              type: string
        mode:
          type: string
          description: |
            For type=entry_match and type=set_equivalent: how strict the comparison is.
            - `subset` (default for entry_match): every proposed entry must exist in incoming; extra incoming entries are allowed.
            - `exact_set` (default for set_equivalent): the two sides must contain the same entries (order-insensitive, multiset semantics).
          enum:
          - subset
          - exact_set
        ordered:
          type: boolean
          description: 'For type=relation_set: when true, relation order is significant. Defaults to false (order-insensitive).'
        require_tags_match:
          type: boolean
          description: 'For type=relation_set: when true, each relation item''s `_tags` must match on both sides (order-insensitive). Defaults to false — `_tags` are stripped before compare.'
        pattern:
          type: string
          description: 'For type=regex: regular expression pattern to test the incoming value against.'
    MatchStrategy:
      type: string
      description: |
        Strategy for auto-clearing a changeset on an `edit_mode: external` attribute
        when a direct write (`?direct=true`) arrives — typically an ERP inbound sync.
        Ignored for `edit_mode: approval`, which does not auto-clear and is resolved
        exclusively via the `:apply` / `:dismiss` changeset endpoints.
        - `exact`: The inbound value must exactly match the proposed value (deep equality).
        - `fuzzy`: The inbound value is compared using the configured `fuzzy_config` algorithm.
        - `any`: Any update to the attribute clears the changeset, regardless of value.
      enum:
      - exact
      - fuzzy
      - any
      default: exact
  parameters:
    AnonymizeQueryParam:
      name: anonymize
      description: |
        When true, anonymizes PII in the response: identifiers (names, emails, phone numbers, IBANs) are replaced
        with deterministic pseudonyms (stable within an org), addresses are generalized to postal code / city / country,
        and well-known free-text fields (e.g. note content) are redacted.

        Useful for AI agents and data analysis use cases that must not access personal data.

        Anonymization is forced (regardless of this parameter) when the access token was created with `anonymize: true`.
      in: query
      required: false
      schema:
        type: boolean
        default: false
    EntityIdPathParam:
      name: id
      description: Entity id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/EntityId'
    EntitySlugPathParam:
      name: slug
      description: Entity Type
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/EntitySlug'
    EntitySlugPathPriceParam:
      name: slug
      description: Entity Type
      in: path
      required: true
      schema:
        allOf:
        - $ref: '#/components/schemas/EntitySlug'
        example: price
    TaxonomySlugQueryParam:
      name: taxonomySlug
      description: Taxonomy slug
      in: query
      schema:
        type: string
      required: true
    TaxonomySlugPathParam:
      name: taxonomySlug
      description: Taxonomy slug
      in: path
      required: true
      schema:
        type: string
    TaxonomySlugQueryParamOptional:
      name: taxonomySlug
      description: Taxonomy slug
      in: query
      schema:
        type: string
    TaxonomyClassificationSlugPathParam:
      name: classificationSlug
      description: Taxonomy Classification slug
      in: path
      required: true
      schema:
        type: string
      example: purpose:<name>
    SavedViewIdPathParam:
      name: id
      description: View id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/SavedViewId'
    AsyncOperationQueryParam:
      name: async
      description: Don't wait for updated entity to become available in Search API. Useful for large migrations
      in: query
      required: false
      schema:
        type: boolean
        default: false
    HydrateEntitiesQueryParam:
      name: hydrate
      description: When true, enables entity hydration to resolve nested $relation & $relation_ref references in-place.
      in: query
      schema:
        default: false
        type: boolean
    ActivityIdQueryParam:
      name: activity_id
      description: Activity to include in event feed
      in: query
      required: false
      schema:
        oneOf:
        - $ref: '#/components/schemas/ActivityId'
        - type: string
          nullable: true
          enum:
          - ''
          - null
    ActivityIdPathParam:
      name: id
      description: Activity Id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/ActivityId'
    FromPageQueryParam:
      name: from
      description: Starting page number
      in: query
      schema:
        type: integer
        minimum: 0
        default: 0
    IncludeReverseDeprecatedQueryParam:
      name: include_reverse
      description: |
        When true, includes reverse relations in response (other entities pointing to this entity)
        *It gets overriden by mode query parameter.*
      in: query
      deprecated: true
      schema:
        default: false
        type: boolean
    IncludeReverseQueryParam:
      name: include_reverse
      description: When true, includes reverse relations in response (other entities pointing to this entity)
      in: query
      schema:
        default: false
        type: boolean
    IncludeSchemasQueryParam:
      name: include_schemas
      description: Filter results to only include schemas
      in: query
      required: false
      style: form
      explode: false
      example:
      - contact
      - account
      schema:
        type: array
        items:
          $ref: '#/components/schemas/EntitySlug'
    ExcludeSchemasQueryParam:
      name: exclude_schemas
      description: Filter results to exclude schemas
      in: query
      required: false
      style: form
      explode: false
      example:
      - file
      - message
      schema:
        type: array
        items:
          $ref: '#/components/schemas/EntitySlug'
    EntityRelationsModeQueryParam:
      name: mode
      description: |
        Options to determine how relations will be included in the result.
        *It overrides the include_reverse query param.*
        Explanation of possible options:
        - direct: include relations to which the searched entity refers
        - reverse: include relations that refer to the entity you are looking for
        - both: both direct and reverse relations
      in: query
      required: false
      schema:
        type: string
        enum:
        - direct
        - reverse
        - both
    DryRunQueryParam:
      name: dry_run
      description: Dry Run mode = return results but does not perform the operation.
      in: query
      required: false
      schema:
        type: boolean
        default: false
    FillActivityQueryParam:
      name: fill_activity
      description: |
        Update the diff and entity for the custom activity included in the query.
        Pending state on activity is automatically ended when activity is filled.
      in: query
      required: false
      schema:
        type: boolean
        default: false
    ValidateEntityQueryParam:
      name: validate
      description: When true, enables entity validation against the entity schema.
      in: query
      schema:
        default: false
        type: boolean
    DirectQueryParam:
      name: direct
      description: |
        When true, bypasses changeset interception: attribute values in the payload
        are written directly to the entity regardless of each attribute's `edit_mode`.
        The write always lands, independently of any auto-clear outcome below.

        After the direct write, for each attribute in the payload that also has a
        pending changeset:
        - `edit_mode: external` — the incoming value is checked against the
          changeset's `match_strategy` (and `fuzzy_config` when `fuzzy`). On match,
          `_changesets[attr]` is cleared. On no-match, the write still stands and
          the changeset stays pending (signalling the ERP/trusted source applied a
          different correction than originally proposed; resolve via a later
          matching direct write, or via the `:apply` / `:dismiss` endpoints).
        - `edit_mode: approval` — never auto-cleared. The write lands but the
          pending changeset remains until explicitly resolved via `:apply` or
          `:dismiss`.

        Intended for trusted integrations (e.g. ERP inbound sync). ERP middleware
        must always use `?direct=true` — without it, an inbound sync on an
        `external` attribute would create a new changeset instead of confirming
        the pending one.

        Defaults to false — no breaking change for existing callers.
      in: query
      required: false
      schema:
        type: boolean
        default: false
    ApplyChangesetsQueryParam:
      name: apply_changesets
      description: |
        When true, applies pending changeset proposed values in-place on the response entity.
        The response includes both the hydrated values and the raw _changesets field.
        Does not mutate stored data — pure read-time transform.
      in: query
      required: false
      schema:
        type: boolean
        default: false
  examples:
    EmptyGenericEntity:
      description: Example of an empty, generic entity
      value: {}
    TaxEntity:
      description: Example of a Tax Rate entity
      value:
        active: true
        type: VAT
        region: Germany
        region_label: All Regions
        rate: 19
        behavior: Exclusive
        description: MwSt. 19%
    ContactEntity:
      description: Example of a contact entity
      value:
        status: Active
        customer_number: abc123
        first_name: First
        middle_name: Middle
        last_name: Last
        title: Herr Prof. Dr.
        email:
        - email: user@example.com
          _tags:
          - work
        phone:
        - phone: '+49123456789'
          _tags:
          - personal
          - mobile
        address:
        - country: Germany
          city: Koln
          postal_code: 81475
          street: Melatengürtel
          street_number: 71
          additional_info: 5. Etage
          _tags:
          - billing
          - delivery
        birthdate: '2019-08-24'
        account:
          $relation:
          - entity_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            _tags:
            - company
        consent_email_marketing:
          status: OPTED_IN
          events:
          - type: OPT_IN
            organization_id: '123'
            created_at: 2021-07-05T09:12:29.352Z
            topic: EMAIL_MARKETING
            identifier: user@example.com
            source: https://consent.sls.epilot.io/optin?token=abc123
            meta:
              ip_address: 1.1.1.1
              user_agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.114 Safari/537.36
          - type: DOUBLE_OPT_IN_REQUEST
            organization_id: '123'
            created_at: 2021-07-05T08:12:29.352Z
            topic: EMAIL_MARKETING
            identifier: user@example.com
            source: consent-api
            meta:
              token: abc123
          - type: OPT_IN
            organization_id: '123'
            created_at: 2021-07-04T09:12:29.352Z
            topic: EMAIL_MARKETING
            identifier: user@example.com
            source: https://frontend.epilot.cloud
            meta:
              ip_address: 1.1.1.1
              user_agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.114 Safari/537.36
    AccountEntity:
      description: Example of an account entity
      value:
        status: Active
        name: Example Company
        tax_id: DE123456789
        email:
        - email: user@example.com
          _tags:
          - work
        phone:
        - phone: '+49123456789'
          _tags:
          - personal
          - mobile
        address:
        - country: Germany
          city: Koln
          postal_code: 81475
          street: Melatengürtel
          street_number: 71
          additional_info: 5. Etage
          _tags:
          - billing
          - delivery
        website: http://company.com
        tax_exemption: '2021-02-23T09:08:57.320Z'
        registry_court: Amtsgericht Köln
        registry_number: HRB 95505
        company_size: 50-99
        industry:
        - ecommerce
        - tech
        annual_revenue: '5000000'
        contact:
          $relation:
          - entity_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
            _tags:
            - CEO
    ProductEntity:
      description: Example of a product entity
      value:
        code: SunrockSolar375
        type: Product
        name: Sunrock Solar Panel
        description: Sunrock Solar Panel, provide high capacity power generation even at night.
        shippable: true,
        _files:
          type: file
          attachments:
          - key: f001-32123-asdasd-23213
            mime: application/pdf
            name: wallbox-premium.pdf
            size: 6933430
            image_url: https://s3-bucket.epilot.cloud/uid/f001-32123-asdasd-23213
            download_url: https://s3-bucket.epilot.cloud/uid/f001-32123-asdasd-23213
        _images:
          type: image
          attachments:
          - key: i001-32123-asdasd-23213
            mime: application/pdf
            name: wallbox-premium.pdf
            size: 6933430
            image_url: https://s3-bucket.epilot.cloud/uid/f001-32123-asdasd-23213
            download_url: https://s3-bucket.epilot.cloud/uid/f001-32123-asdasd-23213
        prices:
          $relation:
          - entity_id: a38cca03-18a2-4e9c-8516-0918d81e7830
            _tags:
            - price
          - entity_id: 3d10c912-c419-42d7-9270-02b7d05294e5
            _tags:
            - price
    PriceEntity:
      description: Example of a price entity
      value:
        code: MODEL_375KW_PREMIUM
        type: One Time
        description: Solar Panel 375 kWp Premium
        internal_description: Solar Panel 375 kWp Premium
        billing_scheme: per_unit
        unit_amount: € 28500
        tiers_mode: Standard
    OrderEntity:
      description: Example of a Order entity
      value:
        amount_subtotal: 23045
        amount_total: 27424
        billing_address:
        - additional_info: ''
          city: City
          country: DE
          postal_code: '123'
          street: Street 1
          street_number: '2'
          _tags: []
        billing_company_name: Epilot
        billing_contact:
          $relation:
          - entity_id: 0691f503-5a3c-4e9e-b036-ffb21ea1d284
            relationText: Daniel Test
            _schema: contact
            _tags: []
        billing_email: x@email.xyz
        billing_first_name: Paulo
        billing_last_name: Henriques
        billing_phone: '00351912611099'
        billing_vat: '123456789'
        currency: EUR
        delivery_address:
        - additional_info: ''
          city: City
          country: DE
          postal_code: '123'
          street: Street 1
          street_number: '2'
          _tags: []
        footer_notes: Footer
        line_items:
        - amount_subtotal: 23045
          amount_total: 27424
          currency: EUR
          description: Basic Model - No Wifi
          price_id: efe9ff76-865c-4287-8de9-422cfc741ff9
          product_id: beefa9f1-29a8-448e-94d5-ebf1963428f8
          quantity: 1
          taxes:
          - amount: 4379
            rate: standard
          unit_amount: 23045
          _price:
            active: false
            billing_duration_amount: '2'
            billing_duration_unit: years
            billing_period: monthly
            description: Basic Model - No Wifi
            notice_time_amount: '1'
            notice_time_unit: months
            price_display_in_journeys: show_price
            renewal_duration_amount: '1'
            renewal_duration_unit: years
            sales_tax: standard
            tax_behavior: exclusive
            termination_time_amount: '1'
            termination_time_unit: months
            type: recurring
            unit_amount: 23045
            unit_amount_currency: EUR
            unit_amount_decimal: '230.4524'
            _created_at: '2021-12-15T12:34:59.579Z'
            _id: efe9ff76-865c-4287-8de9-422cfc741ff9
            _org: '739224'
            _schema: price
            _tags:
            - basic-model
            - wifi
            _title: Basic Model - No Wifi
            _updated_at: '2021-12-31T13:07:51.392Z'
          _product:
            active: true
            code: PWB
            feature:
            - _tags: []
              feature: Pure Energon Fueled
            - _tags: []
              feature: Mobile App Available
            name: Pinho Walls in a Box
            price_options:
              $relation:
              - entity_id: efe9ff76-865c-4287-8de9-422cfc741ff9
            type: product
            _created_at: '2021-12-15T12:35:08.438Z'
            _id: beefa9f1-29a8-448e-94d5-ebf1963428f8
            _org: '739224'
            _schema: product
            _tags:
            - energon
            - eco-friendly
            - wallbox
            _title: Pinho Walls in a Box
            _updated_at: '2022-01-03T17:14:41.042Z'
        memo: Memo
        status: Paid
        total_details:
          amount_tax: 4379
          breakdown:
            recurrences:
            - amount_subtotal: 23045
              amount_tax: 4379
              amount_total: 27424
              billing_period: monthly
              type: recurring
            taxes:
            - amount: 4379
              rate: standard
    OpportunityEntity:
      description: Example of an Opportunity entity
      value:
        amount_subtotal: 23045
        amount_total: 27424
        assignees:
          $relation:
          - entity_id: 66a1a6a3-38ee-4ffe-b68d-ee90e3bb1a77
            relationText: Claudius Iohannis
            _schema: contact
            _tags: []
        billing_address:
        - additional_info: ''
          city: City
          country: DE
          postal_code: '123'
          street: Street 1
          street_number: '2'
          _tags: []
        billing_company_name: Epilot
        billing_contact:
          $relation:
          - entity_id: 0691f503-5a3c-4e9e-b036-ffb21ea1d284
            relationText: Daniel Test
            _schema: contact
            _tags: []
        billing_email: customer@email.xyz
        billing_first_name: Customer First Name
        billing_last_name: Customer Last Name
        billing_phone: '00351912611098'
        billing_vat: '123456789'
        currency: EUR
        delivery_address:
        - additional_info: ''
          city: City
          country: DE
          postal_code: '123'
          street: Street 1
          street_number: '2'
          _tags: []
        line_items:
        - amount_subtotal: 23045
          amount_total: 27424
          currency: EUR
          description: Basic Model - No Wifi
          price_id: efe9ff76-865c-4287-8de9-422cfc741ff9
          product_id: beefa9f1-29a8-448e-94d5-ebf1963428f8
          quantity: 1
          taxes:
          - amount: 4379
            rate: standard
          unit_amount: 23045
          _price:
            active: false
            billing_duration_amount: '2'
            billing_duration_unit: years
            billing_period: monthly
            description: Basic Model - No Wifi
            notice_time_amount: '1'
            notice_time_unit: months
            price_display_in_journeys: show_price
            renewal_duration_amount: '1'
            renewal_duration_unit: years
            sales_tax: standard
            tax_behavior: exclusive
            termination_time_amount: '1'
            termination_time_unit: months
            type: recurring
            unit_amount: 23045
            unit_amount_currency: EUR
            unit_amount_decimal: '230.4524'
            _created_at: '2021-12-15T12:34:59.579Z'
            _id: efe9ff76-865c-4287-8de9-422cfc741ff9
            _org: '739224'
            _schema: price
            _tags:
            - basic-model
            - wifi
            _title: Basic Model - No Wifi
            _updated_at: '2021-12-31T13:07:51.392Z'
          _product:
            active: true
            code: PWB
            feature:
            - _tags: []
              feature: Pure Energon Fueled
            - _tags: []
              feature: Mobile App Available
            name: Pinho Walls in a Box
            price_options:
              $relation:
              - entity_id: efe9ff76-865c-4287-8de9-422cfc741ff9
            type: product
            _created_at: '2021-12-15T12:35:08.438Z'
            _id: beefa9f1-29a8-448e-94d5-ebf1963428f8
            _org: '739224'
            _schema: product
            _tags:
            - energon
            - eco-friendly
            - wallbox
            _title: Pinho Walls in a Box
            _updated_at: '2022-01-03T17:14:41.042Z'
        opportunity_number: 20220105-768854819
        participants:
          $relation:
          - entity_id: 9bbfdaa9-22b2-4100-a256-67600202e3f4
            relationText: Alex Marques
            _schema: contact
            _tags: []
        status: Lead
        total_details:
          amount_tax: 4379
          breakdown:
            recurrences:
            - amount_subtotal: 23045
              amount_tax: 4379
              amount_total: 27424
              billing_period: monthly
              type: recurring
            taxes:
            - amount: 4379
              rate: standard
    EmailTemplateEntity:
      description: Example of an email template entity
      value:
        attachments: []
        body: >-
          <p fr-original-style="caret-color: rgb(65, 65, 65); color: rgb(65, 65, 65); font-family: sans-serif;" id="isPasted" style="caret-color: rgb(65, 65, 65); color: rgb(65, 65, 65); font-family: sans-serif; box-sizing: inherit;
          border-color: rgba(229, 231, 235, var(--tw-border-opacity));"><span fr-original-style="font-weight: 700;" style="font-weight: 700; box-sizing: inherit; border-color: rgba(229, 231, 235, var(--tw-border-opacity));">Variablen -
          Kontakt</span></p>
        brand_id: 7066103
        from:
          name: Name
          email: admin@email.xyz
        name: PH Test
        subject: Example Subject
        system_template: false
        to:
        - id: '1'
          name: Contact Name
          email: Contact email
        _tags:
        - Bestellung
    FileEntity:
      description: Example of a file template entity
      value:
        access_control: private
        filename: solar_panel_ph.jpeg
        s3ref:
          bucket: epilot-staging-user-content
          key: 728/temp/6d450fd1-2d63-435f-b598-c605dfb89cbc/solar_panel_ph.jpeg
    WorkflowStepEntity:
      description: Example of a workflow step template entity
      value:
        name: Name
        assigned_to":
        - '10000563'
        status: Unassigned
        order: 123
        tags:
        - tag1
    SubmissionEntity:
      description: Example of a submission step template entity
      value:
        mapped_entities:
          $relation:
          - entity_id: 4ffb071c-2821-4505-86d0-09b801ffd97a
            relationText: 4ffb071c-2821-4505-86d0-09b801ffd97a
            _schema: price
            _tags: []
    EntityValidationError:
      description: Example of an entity validation error
      value:
        code: string
        params:
          type: string
        path:
        - string
        message: string
    EntityValidationResultSuccess:
      description: Example of a successful entity validation result
      value:
        status: success
        errors: []
    EntityValidationResultError:
      description: Example of a failed entity validation result
      value:
        status: error
        errors:
        - $ref: '#/components/examples/EntityValidationError'
  responses:
    BadRequestError:
      description: Bad request - invalid input parameters
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorObject'
            - example:
                status: 400
                error: Bad Request
    NotFoundError:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorObject'
            - example:
                status: 404
                error: Not Found
    TooManyRequestsError:
      description: Too many requests
      headers:
        Retry-After:
          description: Time to wait in seconds before retrying
          schema:
            type: integer
            example: 10
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorObject'
            - example:
                status: 429
                error: Too many requests. Try again later.
servers:
- url: https://entity.sls.epilot.io

