ent.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)
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:
        '204':
          description: Success
  /v1/entity/schemas/{slug}/versions:
    get:
      operationId: getSchemaVersions
      summary: getSchemaVersions
      description: Get all versions of this schema ordered by the latest versions including drafts.
      tags:
      - Schemas
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - in: query
        name: versions_from
        schema:
          type: number
      - in: query
        name: versions_size
        schema:
          type: number
      - in: query
        name: drafts_from
        schema:
          type: number
      - in: query
        name: drafts_size
        schema:
          type: number
      - in: query
        name: fields
        required: false
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
          example:
          - id
          - attributes
          - capabilites
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  versions:
                    type: array
                    items:
                      $ref: '#/components/schemas/EntitySchemaItem'
                  drafts:
                    type: array
                    items:
                      $ref: '#/components/schemas/EntitySchemaItem'
  /v1/entity/schemas/blueprints:
    get:
      operationId: listSchemaBlueprints
      summary: listSchemaBlueprints
      description: List canonical versions of all available schemas
      tags:
      - Schemas
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/EntitySchemaItem'
  /v1/entity/schemas/{slug}/taxonomy/{taxonomySlug}:
    get:
      operationId: listTaxonomyClassificationsForSchema
      summary: listTaxonomyClassificationsForSchema
      description: List taxonomy classifications for a given schema
      tags:
      - Schemas
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/TaxonomySlugPathParam'
      - in: query
        name: query
        schema:
          type: string
      - in: query
        name: size
        schema:
          type: number
      responses:
        '200':
          description: List of taxonomy classifications
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/TaxonomyClassification'
  /v1/entity:search:
    post:
      operationId: searchEntities
      summary: searchEntities
      description: |
        Search for entities. Supports ordering and pagination. Lucene query 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/{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.
        - If more than one entity is matched a `409` Error is returned

        ## 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'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              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
                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/ActivityItem'
  /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/ActivityItem'
  /v1/entity/{slug}/{id}/activity:
    get:
      operationId: getEntityActivityFeed
      summary: getEntityActivityFeed
      description: |
        Get activity feed for an entity
      tags:
      - Activity
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/EntityIdPathParam'
      - in: query
        name: after
        description: Get activities after this timestamp
        schema:
          type: string
          format: date-time
      - in: query
        name: before
        description: get activities before this timestamp
        schema:
          type: string
          format: date-time
      - $ref: '#/components/parameters/FromPageQueryParam'
      - in: query
        name: size
        description: max number of results to return
        schema:
          type: integer
          minimum: 1
          default: 25
      - in: query
        name: type
        description: Filter by activity type
        schema:
          type: string
          example: SyncActivity
      - in: query
        name: include_relations
        description: Include activities from related entities
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    example: 1
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ActivityItem'
  /v1/entity/{slug}/{id}/relations:
    get:
      operationId: getRelations
      summary: getRelations
      description: |
        Returns 1st level direct relations for an entity.

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

        Reverse relations i.e. entities referring to this entity are included with the `?include_reverse` query param.
      tags:
      - Relations
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/EntityIdPathParam'
      - $ref: '#/components/parameters/HydrateEntitiesQueryParam'
      - $ref: '#/components/parameters/IncludeReverseQueryParam'
      - $ref: '#/components/parameters/FromPageQueryParam'
      - in: query
        name: size
        description: Number of results to return per page
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 100
      - $ref: '#/components/parameters/IncludeSchemasQueryParam'
      - $ref: '#/components/parameters/ExcludeSchemasQueryParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRelationsResp'
              example:
              - attribute: contacts
                entity_id: ed27830b-984c-4bca-9b87-2849bb5789ca
                _tags:
                - primary
                - billing
              - attribute: contacts
                entity_id: fadfc950-6e43-4e38-bae0-ffcf4b8b90e1
              - _id: 9924c4de-d3ed-4752-821d-fc0b9bd57c1b
                order_number: a34234jd
                customer_email: johndoe@epilot.cloud
                billing_first_name: john
                billing_last_name: doe
                billing_company_name: ePilot Gmbh
                billing_vat: 234823948,
                billing_email: johndoe@nowhere.com
                billing_phone: 1234234545,
                billing_address: wallstreet, 1
                billing_contact: villy or zilly
                $relation:
                  attribute: orders
                  entity_id: 9924c4de-d3ed-4752-821d-fc0b9bd57c1b
                  _tags:
                  - solar_panel
                  - one_time
    post:
      operationId: addRelations
      summary: addRelations
      description: Relates one or more entities to parent entity by adding items to a relation attribute
      tags:
      - Relations
      parameters:
      - $ref: '#/components/parameters/EntitySlugPathParam'
      - $ref: '#/components/parameters/EntityIdPathParam'
      - $ref: '#/components/parameters/AsyncOperationQueryParam'
      - $ref: '#/components/parameters/ActivityIdQueryParam'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/RelationItem'
            example:
            - attribute: contacts
              entity_id: e8878f62-2d3d-4c86-bfe7-01a4180ff048
              _tags:
              - billing
            - attribute: contacts
              entity_id: ee8a2af9-fb36-4981-b848-4e65275851af
            - attribute: opportunities
              entity_id: 30990430-a53d-41a2-83db-2de072dc4dd4
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RelationItem'
  /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
              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.
  /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/SavedView'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedViewItem'
    delete:
      operationId: deleteSavedView
      summary: deleteSavedView
      description: Deletes a saved view
      parameters:
      - $ref: '#/components/parameters/SavedViewIdPathParam'
      tags:
      - Saved Views
      responses:
        '200':
          description: List of all available saved views
  /v1/entity/views/favorites:
    get:
      operationId: listFavoriteViewsForUser
      summary: listFavoriteViewsForUser
      description: Get the Favorite Saved Views for user based on the schema
      tags:
      - Saved Views
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/SavedViewItem'
  /v1/entity/listTaxonomies:
    get:
      deprecated: true
      operationId: listTaxonomies
      summary: listTaxonomies
      description: List taxonomies in an organisation
      tags:
      - Taxonomy
      parameters:
      - in: query
        name: include_disabled
        description: Include disabled taxonomies
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Returns list of taxonomies in an organisation
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Taxonomy'
  /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:
              type: object
              properties:
                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
                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'
                enabled:
                  type: boolean
                  description: Whether the taxonomy is enabled or not
                  example: true
              example:
                name: Product Category
                plural: Product Categories
                icon: product-hub
                color: '#FF5733'
                enabled: true
      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/TaxonomySlugQueryParam'
      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'
  /v2/entity/taxonomies/{taxonomySlug}/classifications/{classificationSlug}:
    post:
      operationId: createTaxonomyClassification
      summary: createTaxonomyClassification
      description: Create a new classification for a taxonomy
      tags:
      - Taxonomy
      parameters:
      - $ref: '#/components/parameters/TaxonomySlugPathParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxonomyClassification'
      response:
        '201':
          description: Taxonomy classification created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxonomyClassification'
        '409':
          description: Taxonomy classification already exists"
    put:
      operationId: updateTaxonomyClassification
      summary: updateTaxonomyClassification
      description: Update a classification for a taxonomy
      tags:
      - Taxonomy
      parameters:
      - $ref: '#/components/parameters/TaxonomySlugPathParam'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxonomyClassification'
      response:
        '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/TaxonomySlugPathParam'
      - in: path
        name: classificationId
        description: The classification id
        required: true
        schema:
          $ref: '#/components/schemas/ClassificationId'
      - in: query
        name: permanent
        description: If true, the classification will be permanently deleted
        schema:
          type: boolean
      response:
        '204':
          description: Taxonomy classification deleted
components:
  securitySchemes:
    EpilotAuth:
      type: http
      scheme: bearer
      description: Authorization header with epilot OAuth2 bearer token
      bearerFormat: JWT
    EpilotOrg:
      description: Overrides the target organization to allow shared tenantaccess
      name: x-epilot-org-id
      in: header
      type: apiKey
  schemas:
    ExportJobId:
      description: The unique identifier of the import job.
      type: string
      example: abc123
    Language:
      description: Export headers translation Language
      type: string
    IsTemplate:
      description: Pass 'true' to generate import template
      type: boolean
    SchemaId:
      description: Generated uuid for schema
      type: string
      format: uuid
    EntitySchema:
      description: The "type" of an Entity. Describes the shape. Includes Entity Attributes, Relations and Capabilities.
      type: object
      properties:
        slug:
          $ref: '#/components/schemas/EntitySlug'
        version:
          type: integer
          minimum: 1
        blueprint:
          $ref: '#/components/schemas/BlueprintEntityId'
        feature_flag:
          type: string
          example: FF_MY_FEATURE_FLAG
          description: This schema should only be active when the feature flag is enabled
        enable_setting:
          description: This schema should only be active when one of the organization settings is enabled
          type: array
          items:
            type: string
            example: 360_features
        name:
          description: User-friendly identifier for the entity schema
          type: string
          example: Contact
        plural:
          type: string
          example: Contacts
        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 dictionary of Group Titles and associated settings if present.
          items:
            type: object
            properties:
              label:
                type: string
              id:
                type: string
              expanded:
                type: boolean
              render_condition:
                type: string
                example: _is_composite_price = "false"
              order:
                description: Render order of the group
                type: integer
                default: 0
              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:
                    type: string
                  default:
                    type: string
              _purpose:
                type: array
                items:
                  $ref: '#/components/schemas/ClassificationId'
            required:
            - label
            - id
          example:
          - id: Contact Details
            label: Contact Details
            expanded: true
            order: 1
          - id: Address Details
            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
        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'
    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'
    BaseAttribute:
      type: object
      properties:
        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
          default: true
        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
    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:
        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
    EntityViewDisabled:
      type: object
      properties:
        view_type:
          type: string
          enum:
          - disabled
    EntityDefaultTable:
      type: object
      properties:
        view_type:
          type: string
          enum:
          - default
        row_actions:
          type: array
          items:
            oneOf:
            - type: string
            - $ref: '#/components/schemas/EntityAction'
        bulk_actions:
          type: array
          items:
            oneOf:
            - type: string
            - $ref: '#/components/schemas/EntityAction'
        navbar_actions:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              options:
                type: array
                items:
                  type: object
                  properties:
                    label:
                      type: string
                    params:
                      type: object
                  required:
                  - label
            required:
            - type
        enable_thumbnails:
          description: Enable the thumbnail column
          type: boolean
          default: false
    EntityDefaultCreate:
      type: object
      properties:
        view_type:
          type: string
          enum:
          - default
        search_params:
          type: object
          additionalProperties:
            type: string
    EntityDefaultEdit:
      type: object
      properties:
        view_type:
          type: string
          enum:
          - default
        search_params:
          type: object
          additionalProperties:
            type: string
        summary_attributes:
          description: List of attribute names that we show in the summary header
          type: array
          items:
            type: string
            example: email
    RedirectEntityView:
      type: object
      properties:
        view_type:
          type: string
          enum:
          - redirect
        route:
          type: string
          example: /app/pricing-hub/product/:entityId
      example:
        type: redirect
        route: /app/pricing-hub/product/:entityId
    EntityId:
      type: string
      format: uuid
    BaseEntity:
      allOf:
      - $ref: '#/components/schemas/Entity'
      - required:
        - _id
        - _title
        - _org
        - _schema
        - _created_at
        - _updated_at
    Entity:
      type: object
      additionalProperties: true
      properties:
        _id:
          $ref: '#/components/schemas/EntityId'
        _org:
          type: string
          description: Organization Id the entity belongs to
        _owners:
          type: array
          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
        _updated_at:
          type: string
          format: date-time
          nullable: true
        _acl:
          $ref: '#/components/schemas/EntityAcl'
      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
    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:
      type: object
      properties:
        q:
          description: Lucene queries supported with ElasticSearch
          type: string
          example: _schema:contact AND status:active
        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
        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'
        include_scores:
          type: boolean
          default: false
          description: Adds a `_score` number field to results that can be used to rank by match score
        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
      required:
      - q
    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
      properties:
        S3Reference:
          type: object
          properties:
            bucket:
              type: string
              description: The name of the S3 bucket where the JSON file for import is stored.
              example: my-bucket
            key:
              type: string
              description: The key or path to the JSON file within the S3 bucket.
              example: imports/my-import.json
          required:
          - bucket
          - key
          description: The S3 bucket and key where the JSON file for import is located.
        schema:
          type: string
          description: The schema of the entities being imported. This must match the schema of the entities on the platform.
          example: contact
      required:
      - S3Reference
      - schema
      description: The parameters for importing entities.
    EntitySearchResults:
      type: object
      properties:
        hits:
          type: number
          example: 1
        results:
          type: array
          items:
            $ref: '#/components/schemas/EntityItem'
        aggregations:
          type: object
          example:
            contact-count-per-tag:
              doc_count_error_upper_bound: 0
              sum_other_doc_count: 23
              buckets:
              - key: automation
                doc_count: 108
              - key: primary
                doc_count: 66
    SearchMappings:
      description: |
        Advanced: explicit Elasticsearch index mapping definitions for entity data
      example:
        image:
          type: keyword
          index: false
      type: object
      additionalProperties:
        type: object
        properties:
          index:
            type: boolean
            default: true
          type:
            type: string
            enum:
            - keyword
            - text
            - boolean
            - integer
            - long
            - float
            - date
            - flattened
            - nested
          fields:
            additionalProperties: true
    ActivityId:
      type: string
      format: ulid
      description: See https://github.com/ulid/spec
      example: 01F130Q52Q6MWSNS8N2AVXV4JN
    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
      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
    ActivityItem:
      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'
      - type: object
        properties:
          operations_total:
            type: integer
            description: Count of total operations attached to this activity
            example: 1
          operations:
            type: array
            items:
              $ref: '#/components/schemas/EntityOperation'
    BlueprintEntityId:
      description: Reference to blueprint
      type: string
      format: uuid
    ListSavedViewsResults:
      type: object
      properties:
        hits:
          type: number
          example: 1
        results:
          type: array
          items:
            $ref: '#/components/schemas/SavedViewItem'
    SavedViewId:
      description: Generated uuid for a saved view
      type: string
      format: uuid
    SavedViewItem:
      allOf:
      - type: object
        properties:
          id:
            $ref: '#/components/schemas/SavedViewId'
          created_at:
            type: string
          updated_at:
            type: string
      - $ref: '#/components/schemas/SavedView'
    SavedView:
      description: A saved entity view
      type: object
      properties:
        slug:
          type: array
          description: list of schemas a view can belong to
          items:
            $ref: '#/components/schemas/EntitySlug'
        name:
          description: User-friendly identifier for the saved view
          type: string
          example: View listing German
          minLength: 1
          maxLength: 100
        org:
          description: Organisation ID a view belongs to
          type: string
          example: '66'
        shared:
          description: boolean property for if a view is shared with organisation
          type: boolean
          example: true
        isFavoritedBy:
          description: List of users (IDs) that have favorited the view
          type: array
          items:
            type: string
            example: 11701
        created_by:
          anyOf:
          - type: object
            description: A user that created the view
            properties:
              user_id:
                type: string
                example: '10598'
          - type: object
            description: A system-created view
            properties:
              source:
                type: string
                enum:
                - SYSTEM
                - BLUEPRINT
            additionalProperties: true
        ui_config:
          type: object
          additionalProperties: true
          example:
            filters:
              customer_name: suresh test
              _tags: '360'
            table_layout:
              opportunity:
                page: 1
                sort: _created_at:desc
                pageSize: 25
                columnSettings: []
      required:
      - slug
      - name
      - created_by
      - ui_config
    Taxonomy:
      type: object
      properties:
        slug:
          $ref: '#/components/schemas/TaxonomySlug'
        name:
          type: string
          description: A human friendly name of a Taxonomy e.g. Purpose, Product Category, Folder, Tag
          example: Purpose
        plural:
          type: string
          description: Plural name of a Taxonomy e.g. Purposes, Product Categories, Folders, Tags. Defaults to name is not provided.
          example: Purposes
        kind:
          readonly: true
          type: string
          enum:
          - system
          - user_defined
          description: Kind of taxonomy e.g. system or user_defined. By default, it's empty, which means 'user_defined'
          example: system
        icon:
          type: string
          description: Icon name for the taxonomy (from epilot360/icons icon set)
          example: purpose
        color:
          type: string
          description: HEX Color code for the taxonomy
          example: '#FF5733'
        created_at:
          readonly: true
          type: string
          format: date-time
        updated_at:
          readonly: true
          type: string
          format: date-time
        deleted_at:
          readonly: true
          type: string
          format: date-time
          description: 'Date when the taxonomy was soft-deleted (enabled: false)'
        created_by:
          readonly: true
          type: string
          description: User ID of the creator
          example: '10598'
        enabled:
          type: boolean
          description: Whether the taxonomy is enabled or not
          example: true
    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
      format: uuid
    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:
            $ref: '#/components/schemas/ClassificationId'
    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
    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'
servers:
- url: https://entity.sls.epilot.io