openapi.yml

openapi: 3.0.2
info:
  title: Entity API
  version: 1.0.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
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
        schema:
          type: boolean
          default: 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: By default gets the latest version of the Schema and to get the specific version of schema pass the id.
      tags:
      - Schemas
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - in: query
        name: id
        schema:
          $ref: '#/components/schemas/SchemaId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitySchemaItem'
    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
        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'
    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
  /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'
      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'
  /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
      - in: query
        name: versions_size
        schema:
          type: number
      - in: query
        name: drafts_from
        schema:
          type: number
      - in: query
        name: drafts_size
        schema:
          type: number
      - 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:
                    type: array
                    items:
                      $ref: '#/components/schemas/EntitySchemaItem'
  /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
      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
  /v1/entity:list:
    post:
      operationId: listEntities
      summary: listEntities
      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
  /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'
  /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'
  /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'
  /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'
  /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'
      - in: query
        name: fields
        description: List of entity fields to include in results
        style: form
        explode: false
        schema:
          $ref: '#/components/schemas/FieldsParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityItem'
  /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
  /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'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entity:
                    $ref: '#/components/schemas/EntityItem'
                  relations:
                    type: array
                    items:
                      $ref: '#/components/schemas/EntityItem'
    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'
      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'
      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
  /v1/entity:autocomplete:
    get:
      operationId: autocomplete
      summary: autocomplete
      description: |
        Autocomplete entity attributes
      tags:
      - Entities
      parameters:
      - 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/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
      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'
  /v1/entity/activity/{id}:
    get:
      operationId: getActivity
      summary: getActivity
      description: Get activity by id
      tags:
      - Activity
      parameters:
      - $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'
  /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'
  /v1/entity/{slug}/{id}/activity:
    get:
      operationId: getEntityActivityFeed
      summary: getEntityActivityFeed
      description: |
        Get activity feed for an entity
      tags:
      - Activity
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/EntityIdPathParam'
      - in: query
        name: after
        description: Get activities after this timestamp
        schema:
          type: string
          format: date-time
      - in: query
        name: before
        description: get activities before this timestamp
        schema:
          type: string
          format: date-time
      - $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
        schema:
          type: string
          example: SyncActivity
      - in: query
        name: include_relations
        description: Include activities from related entities
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    example: 1
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ActivityItem'
  /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/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
                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
    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'
    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.
  /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'
      - 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'
  /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/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'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRelationsRespWithPagination'
  /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'
  /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'
    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.
  /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
  /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.
  /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: 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'
  /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'
    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'
    delete:
      operationId: deleteSavedView
      summary: deleteSavedView
      description: Deletes a saved view
      parameters:
      - $ref: '#/components/parameters/SavedViewIdPathParam'
      tags:
      - Saved Views
      responses:
        '200':
          description: List of all available saved views
  /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
      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
  /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'
    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
        name: permanent
        description: If true, the taxonomy will be permanently deleted
        schema:
          type: boolean
      responses:
        '204':
          description: Taxonomy deleted
  /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: object
                    items:
                      $ref: '#/components/schemas/ClassificationId'
  /v2/entity/taxonomies/classifications/{classificationSlug}:
    get:
      operationId: getTaxonomyClassification
      summary: getTaxonomyClassification
      description: Get a classification for a taxonomy
      tags:
      - Taxonomy
      parameters:
      - $ref: '#/components/parameters/TaxonomyClassificationSlugPathParam'
      responses:
        '200':
          description: Taxonomy classification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxonomyClassification'
        '404':
          description: Taxonomy classification not found
    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'
  /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:
      - $ref: '#/components/parameters/TaxonomySlugQueryParamOptional'
      - in: query
        name: query
        description: Input to search
        schema:
          type: string
          example: sales
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                classificationIds:
                  type: array
                  items:
                    $ref: '#/components/schemas/ClassificationId'
      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'
  /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
        name: status
        schema:
          $ref: '#/components/schemas/TaxonomyBulkJobStatus'
      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:
                type: array
                items:
                  $ref: '#/components/schemas/TaxonomyBulkJob'
  /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:
                  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: '123'
                status: PENDING
  /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: '123'
                status: PENDING
  /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'
  /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'
    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'
  /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'
  /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'
    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'
  /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'
  /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'
    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'
  /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'
  /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'
    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'
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
          enum:
          - customer_relations
          - sales
          - product_hub
          - contracts
          - journeys
          - messaging
          - system
        published:
          type: boolean
          example: false
        draft:
          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'
            sharing:
              type: object
              properties:
                show_sharing_button:
                  type: boolean
                  description: Show the sharing button in entity detail view
                  example: true
        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
        explicit_search_mappings:
          $ref: '#/components/schemas/SearchMappings'
        group_headlines:
          type: array
          items:
            $ref: '#/components/schemas/GroupHeadline'
      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
      - $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/AddressRelationAttribute'
      - $ref: '#/components/schemas/PaymentMethodRelationAttribute'
      - $ref: '#/components/schemas/CurrencyAttribute'
      - $ref: '#/components/schemas/RepeatableAttribute'
      - $ref: '#/components/schemas/TagsAttribute'
      - $ref: '#/components/schemas/NumberAttribute'
      - $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'
    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
        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.
        _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
      required:
      - name
      - label
    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
    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
    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
        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.
          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:
                  type: object
                  allOf:
                  - $ref: '#/components/schemas/EntityItem'
            example:
              value:
              - 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.
    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
    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
    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'
      - $ref: '#/components/schemas/TaxonomyClassification'
      - 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
          relation_affinity_mode:
            description: Weak repeatable attributes are kept when duplicating an entity. Strong repeatable attributes are discarded when duplicating an entity.
            type: string
            enum:
            - weak
            - strong
          type:
            type: string
            enum:
            - string
            - phone
            - email
            - address
            - relation
            - payment
            - price_component
            - date
          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.
          allowedSchemas:
            type: array
            items:
              $ref: '#/components/schemas/EntitySlug'
    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
    NumberAttribute:
      allOf:
      - $ref: '#/components/schemas/BaseAttribute'
      - type: object
        description: Numeric input
        properties:
          type:
            type: string
            enum:
            - number
          format:
            type: string
          show_separator:
            description: Whether or not to show a thousands separator
            type: boolean
            default: true
    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
    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
    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'
      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
    EntitySlug:
      description: URL-friendly identifier for the entity schema
      type: string
      example: contact
    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'
        _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
        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
            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'
      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:
          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
        _acl:
          readOnly: true
          $ref: '#/components/schemas/EntityAcl'
        _purpose:
          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
      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
    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'
        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: {}
          fields: {}
          aggs: {}
          include_deleted:
            $ref: '#/components/schemas/EntitySearchIncludeDeletedParam'
        additionalProperties: false
        required:
        - q
      - $ref: '#/components/schemas/EntitySearchOptions'
    EntityListParams:
      allOf:
      - type: object
        properties:
          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: {}
          fields: {}
          aggs: {}
        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
        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
        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'
    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.
    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
    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
          fields:
            additionalProperties: true
    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
    Activity:
      type: object
      additionalProperties: false
      properties:
        type:
          type: string
          example: MyCustomActivity
        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'
        operation:
          type: string
          enum:
          - createEntity
          - updateEntity
          - deleteEntity
        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:
              $ref: '#/components/schemas/Entity'
            updated:
              $ref: '#/components/schemas/Entity'
            deleted:
              $ref: '#/components/schemas/Entity'
      required:
      - entity
      - org
      - operation
    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'
    SavedView:
      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'
          - 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: []
      required:
      - slug
      - name
      - created_by
      - 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
        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:
            $ref: '#/components/schemas/TaxonomyLocationId'
    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
    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
        _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
    ClassificationId:
      type: string
      example: taxonomy-slug:classification-slug
    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
      - DELETE_CLASSIFICATIONS
    TaxonomyBulkJob:
      type: object
      properties:
        job_id:
          type: string
          format: uuid
        job_status:
          $ref: '#/components/schemas/TaxonomyBulkJobStatus'
        action_type:
          $ref: '#/components/schemas/TaxonomyBulkJobActionType'
        request:
          type: object
          properties:
            target_taxonomy:
              $ref: '#/components/schemas/TaxonomySlug'
            classification_ids:
              type: array
              items:
                $ref: '#/components/schemas/ClassificationId'
        output:
          type: object
          properties:
            target_entities:
              type: array
              items:
                $ref: '#/components/schemas/EntityId'
            affected_entities:
              type: array
              items:
                $ref: '#/components/schemas/EntityId'
            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
        progress:
          description: Progress of the job on a scale of 0 to 1
          type: number
      example:
        job_id: 123e4567-e89b-12d3-a456-426614174000
        status: PENDING
        action_type: MOVE_LABELS
        created_by: 10598
        created_at: 2024-01-01T00:00:00.000Z
        updated_at: 2024-01-01T00:00:00.000Z
        org: 66
        progress: 0.5
    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
  parameters:
    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:
          - ''
    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
  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'
servers:
- url: https://entity.sls.epilot.io