original.yaml

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)

servers:
  - url: https://entity.sls.epilot.io

tags:
  - name: Schemas
    description: Model Entities
  - name: Entities
    description: CRUD Access for Entities
  - name: Relations
    description: Entity Relationships
  - name: Activity
    description: Entity Events
  - name: Export
    description: Export and Import entities via files
  - 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
                    _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.
                    salutation:
                      type: string
                      nullable: true
                      enum:
                        - Mr.
                        - Ms. / Mrs.
                        - Company
                        - Contact Person
                        - Company/Contact Person
                        - Spouse
                        - Family
                        - Ownership
                        - Assembly
                        - Other
                    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
                          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"

  # Entities
  /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/AsyncOperationQueryParam"
      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"

  /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"

  /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/DryRunQueryParam"
        - $ref: "#/components/parameters/AsyncOperationQueryParam"
        - 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"
        "409":
          description: "Conflict: multiple entities were matched with `unique_key`"

  /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}:
    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 # relations_array
                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/AsyncOperationQueryParam"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Entity"
            example: {}
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EntityItem"
    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/DryRunQueryParam"
        - $ref: "#/components/parameters/AsyncOperationQueryParam"
      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"
    delete:
      operationId: deleteEntity
      summary: deleteEntity
      description: |
        Deletes an Entity

        ## Activity

        If no `activity_id` query parameter is provided, implicitly creates Activity of type `EntityDeleted`
      tags:
        - Entities
      parameters:
        - $ref: "#/components/parameters/EntitySlugPathParam"
        - $ref: "#/components/parameters/EntityIdPathParam"
        - $ref: "#/components/parameters/ActivityIdQueryParam"
      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"

  # Relations
  /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"
      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"
      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: create export file of entities
      tags:
        - 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:
        - Entity Import
      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.

  # Saved Views
  /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"

  # Taxonomies
  /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}: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/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"

  /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"

  /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"

  # Elastic Cluster Assignment
  /v1/internal/clusterAssignment/{orgId}:
    get:
      operationId: getElasticClusterForOrg
      summary: getElasticClusterForOrg
      description: Gets the Elastic cluster assignment by orgId.
      x-internal: true
      tags:
        - Elastic Cluster Assignment
        - Internal
      parameters:
        - in: path
          name: orgId
          description: The organization to fetch the cluster assigment
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ESClusterAssignment"

  # Terraform Schema API - CRUDable schema attributes and capabilities
  # Attributes
  /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"

  # Capabilities
  /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"

  # Groups
  /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"

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:
    # 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
        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"
      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"
        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"
        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 all the 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
    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."
    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

    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"
        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

    # Entity
    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
      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"]

    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"

    HydratedEntityItem:
      allOf:
        - $ref: "#/components/schemas/BaseEntity"
        - $ref: "#/components/schemas/HydratedEntity"

    # Relations
    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

    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: {}
          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:
          type: string
          example: "_created_at:desc"
        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
          # maximum: 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

    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

    # Activity (Event System)
    ActivityId:
      type: string
      format: ulid
      description: See https://github.com/ulid/spec
      example: 01F130Q52Q6MWSNS8N2AVXV4JN
    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
      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

    # * Region Start: Taxonomies *
    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"
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      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"
    # * Region End: Taxonomies *

    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:
        $ref: "#/components/schemas/ActivityId"
    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

  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"