{ "openapi": "3.0.2", "info": { "title": "Entity API", "version": "2.9.0", "description": "Flexible data layer for epilot Entities.\n\nUse this API configure and access your business objects like Contacts, Opportunities and Products.\n\n[Feature Documentation](https://docs.epilot.io/docs/entities/flexible-entities)\n" }, "tags": [ { "name": "Schemas", "description": "Model Entities" }, { "name": "Entities", "description": "CRUD Access for Entities" }, { "name": "Relations", "description": "Entity Relationships" }, { "name": "Activity", "description": "Entity Events" }, { "name": "Import-Export", "description": "Import and Export entities via portable files (CSV)" }, { "name": "Saved Views", "description": "Saved Views for Entities" }, { "name": "Taxonomy", "description": "Taxonomies and Classifications" }, { "name": "Elastic Cluster Assignment", "description": "Elastic Cluster assignment for organizations" }, { "name": "Internal", "description": "Internal APIs" }, { "name": "Public", "description": "Public" } ], "security": [ { "EpilotAuth": [] }, { "EpilotOrg": [] } ], "paths": { "/v1/entity/schemas": { "get": { "operationId": "listSchemas", "summary": "listSchemas", "description": "Get the latest versions of all schemas", "parameters": [ { "in": "query", "name": "unpublished", "description": "Return unpublished draft schemas", "deprecated": true, "schema": { "type": "boolean", "default": false } }, { "in": "query", "name": "latest", "description": "When true, return the latest version instead of the frozen version for frozen schemas.", "schema": { "type": "boolean", "default": false } }, { "in": "query", "name": "exclude", "description": "List of schema slugs to exclude from the results. Accepts a comma-separated list of slugs to exclude from the results.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "in": "query", "name": "include", "description": "List of schema slugs to include in the results. When provided, only these schemas are returned. Accepts a comma-separated list of slugs.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false } ], "tags": [ "Schemas" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/EntitySchemaItem" } } } } } } } } } }, "/v2/entity/schemas": { "get": { "operationId": "listSchemasV2", "summary": "listSchemasV2", "description": "Get the latest versions of all schemas.\nReturns summary schemas by default (only summary attributes, no capabilities).\nUse ?full=true for complete schemas.\n", "parameters": [ { "in": "query", "name": "full", "description": "Return full schemas including all attributes and capabilities", "schema": { "type": "boolean", "default": false } }, { "in": "query", "name": "unpublished", "description": "Return unpublished draft schemas", "deprecated": true, "schema": { "type": "boolean", "default": false } }, { "in": "query", "name": "latest", "description": "When true, return the latest version instead of the frozen version for frozen schemas.", "schema": { "type": "boolean", "default": false } }, { "in": "query", "name": "exclude", "description": "List of schema slugs to exclude from the results. Accepts a comma-separated list of slugs to exclude from the results.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false }, { "in": "query", "name": "include", "description": "List of schema slugs to include in the results. When provided, only these schemas are returned. Accepts a comma-separated list of slugs.", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false } ], "tags": [ "Schemas" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/EntitySchemaItem" } } } } } } } } } }, "/v1/entity/schemas/{slug}": { "get": { "operationId": "getSchema", "summary": "getSchema", "description": "By default gets the current version of the Schema (frozen version if frozen, otherwise latest).\nPass ?latest=true to get the latest version when the schema is frozen.\nPass ?id= to get a specific version by ID.\n", "tags": [ "Schemas" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathParam" }, { "in": "query", "name": "id", "schema": { "$ref": "#/components/schemas/SchemaId" } }, { "in": "query", "name": "latest", "description": "When true, return the latest version instead of the frozen version for frozen schemas.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitySchemaItem" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "put": { "operationId": "putSchema", "summary": "putSchema", "description": "Create or update a schema with a new version.\nWhen the schema is frozen, writes update the latest version without affecting the frozen version.\n", "tags": [ "Schemas" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathParam" }, { "in": "query", "name": "draft", "deprecated": true, "schema": { "default": false, "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitySchema" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitySchemaItem" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } }, "delete": { "operationId": "deleteSchema", "summary": "deleteSchema", "description": "Delete a schema, or a specific version of a schema", "tags": [ "Schemas" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathParam" } ], "responses": { "200": { "description": "Success" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity/schemas/{slug}/json/schema": { "get": { "operationId": "getJsonSchema", "summary": "getJsonSchema", "description": "Get formal JSON schema definition draft 2020-12 for the given epilot schema", "tags": [ "Schemas" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathParam" }, { "in": "query", "name": "dereference", "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "example": { "$schema": "http://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "_org": { "type": "string", "description": "Organization Id the entity belongs to", "readOnly": true }, "_owners": { "type": "array", "readOnly": true, "items": { "description": "The user / organization owning this entity.\n\nNote: Owner implicitly has access to the entity regardless of ACLs.\n", "type": "object", "properties": { "org_id": { "type": "string", "example": "123" }, "user_id": { "type": "string", "example": "123" } }, "required": [ "org_id" ] } }, "_schema": { "readOnly": true, "type": "string" }, "_title": { "readOnly": true, "type": "string" }, "_tags": { "type": "array", "nullable": true, "items": { "type": "string" } }, "_manifest": { "type": "array", "description": "Manifest ID used to create/update the entity", "items": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" } }, "_created_at": { "readOnly": true, "type": "string", "format": "date-time" }, "_updated_at": { "readOnly": true, "type": "string", "format": "date-time" }, "_acl": { "readOnly": true, "type": "object", "description": "Access control list (ACL) for an entity. Defines sharing access to external orgs or users.", "additionalProperties": true, "properties": { "view": { "type": "array", "items": { "type": "string", "example": "org:456" } }, "edit": { "type": "array", "items": { "type": "string", "example": "org:456" } }, "delete": { "type": "array", "items": { "type": "string", "example": "org:456" } } } }, "title": { "type": "string", "nullable": true, "enum": [ "Dr.", "Prof.", "Prof. Dr.", null ] }, "salutation": { "type": "string", "nullable": true, "enum": [ "Mr.", "Ms. / Mrs.", "Company", "Contact Person", "Company/Contact Person", "Spouse", "Family", "Ownership", "Assembly", "Other", null ] }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "customer_number": { "type": "string", "nullable": true }, "birthdate": { "type": "string", "format": "date", "nullable": true }, "account": { "type": "object", "nullable": true, "properties": { "$relation": { "type": "array", "items": { "type": "object", "properties": { "entity_id": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "_tags": { "type": "array", "nullable": true, "items": { "type": "string" } } }, "required": [ "entity_id" ] } } }, "additionalProperties": true }, "address": { "type": "array", "nullable": true, "description": "Addresses as a list of object, the element with index 0 is treated as the primary one.\n", "items": { "type": "object", "properties": { "street": { "type": "string", "nullable": true }, "street_number": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true, "enum": [ "DE", "AT", "CH", null ] }, "additional_info": { "type": "string", "nullable": true }, "_tags": { "type": "array", "nullable": true, "items": { "type": "string" } }, "_id": { "type": "string", "example": "xHcOoJCa07eysJ1GaQeSb" } }, "required": [ "street", "street_number", "postal_code", "city", "country" ] } }, "email": { "type": "array", "nullable": true, "description": "Email addresses as a list of object, the element with index 0 is treated as the primary one.\n", "items": { "type": "object", "properties": { "_id": { "type": "string", "example": "xHcOoJCa07eysJ1GaQeSb" }, "_tags": { "type": "array", "nullable": true, "items": { "type": "string" } }, "email": { "type": "string" } }, "required": [ "email" ] } }, "phone": { "type": "array", "description": "Phone numbers as a list of object, the element with index 0 is treated as the primary one.\n", "items": { "type": "object", "properties": { "_id": { "type": "string", "example": "xHcOoJCa07eysJ1GaQeSb" }, "_tags": { "type": "array", "nullable": true, "items": { "type": "string" } }, "phone": { "type": "string" } }, "required": [ "phone" ] } } }, "required": [ "first_name", "last_name", "_id", "_org", "_owners", "_schema", "_title", "_tags", "_created_at", "_updated_at", "_acl" ] } } } } } } } }, "/v1/entity/schemas/{slug}/json/example": { "get": { "operationId": "getSchemaExample", "summary": "getSchemaExample", "description": "Get a full example entity for the given schema", "tags": [ "Schemas" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathParam" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "contact": { "$ref": "#/components/examples/ContactEntity" } } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity/schemas/{slug}/versions": { "get": { "operationId": "getSchemaVersions", "summary": "getSchemaVersions", "description": "Get all versions of this schema ordered by the latest versions including drafts.", "tags": [ "Schemas" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathParam" }, { "in": "query", "name": "versions_from", "schema": { "type": "number", "default": 0 } }, { "in": "query", "name": "versions_size", "schema": { "type": "number", "default": 20 } }, { "in": "query", "name": "drafts_from", "schema": { "type": "number", "default": 0 } }, { "in": "query", "name": "drafts_size", "schema": { "type": "number", "default": 0 } }, { "in": "query", "name": "fields", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" }, "example": [ "id", "attributes", "capabilites" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "versions": { "type": "array", "items": { "$ref": "#/components/schemas/EntitySchemaItem" } }, "drafts": { "deprecated": true, "type": "array", "items": { "$ref": "#/components/schemas/EntitySchemaItem" } }, "versions_more": { "description": "Pagination: Whether more versions are available", "type": "boolean" }, "drafts_more": { "deprecated": true, "description": "Pagination: Whether more drafts are available", "type": "boolean" }, "frozen_version": { "description": "The version ID that is currently frozen, if any", "allOf": [ { "$ref": "#/components/schemas/SchemaId" } ] } }, "required": [ "versions", "versions_more" ] } } } } } } }, "/v1/entity/schemas/{slug}/freeze": { "post": { "operationId": "freezeSchema", "summary": "freezeSchema", "description": "Freeze a schema at its current version, or at a specific version.\nWhen frozen, getSchema returns the frozen version by default.\nNew edits via putSchema update the latest version without affecting the frozen version.\n", "tags": [ "Schemas" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathParam" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "version_id": { "description": "Freeze to a specific version ID. Defaults to the current version.", "allOf": [ { "$ref": "#/components/schemas/SchemaId" } ] } } } } } }, "responses": { "200": { "description": "Schema frozen successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitySchemaItem" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/v1/entity/schemas/{slug}/unfreeze": { "post": { "operationId": "unfreezeSchema", "summary": "unfreezeSchema", "description": "Unfreeze a schema. Promotes the latest version to the current version for all users.\n", "tags": [ "Schemas" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathParam" } ], "responses": { "200": { "description": "Schema unfrozen successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitySchemaItem" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/v1/entity/schemas/{slug}/capabilities/available": { "get": { "operationId": "listAvailableCapabilities", "summary": "listAvailableCapabilities", "description": "List available capabilities for schema", "tags": [ "Schemas" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathParam" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/EntityCapability" } } } } } } } } } }, "/v1/entity/schemas/blueprints": { "get": { "operationId": "listSchemaBlueprints", "summary": "listSchemaBlueprints", "description": "List canonical versions of all available schemas", "tags": [ "Schemas" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/EntitySchemaItem" } } } } } } } } } }, "/v1/entity:search": { "post": { "operationId": "searchEntities", "summary": "searchEntities", "x-rate-limit": { "limit": 5000, "window": 60, "pool": "search" }, "description": "Search for entities. Supports ordering and pagination. [Lucene query syntax](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax) supported for complex querying.\n\nPassing comma-separated `x-epilot-org-id` is supported for cross-org entity search.\n\n## Relations\n\nWhen `hydrate=true`, relation attributes are replaced in-place with nested entity values.\n\nExample:\n```json\n{\n \"_id\": \"123\",\n \"name\": \"parent\",\n \"_tags\": [\"parent\"],\n \"contacts\": {\n \"$relation\": [\n { \"entity_id\": \"456\", \"_tags\": [\"primary\"] },\n { \"entity_id\": \"789\", \"_tags\": [\"secondary\"] },\n ]\n },\n \"addresses\": {\n \"$relation_ref\": [\n { \"entity_id\": \"123\", \"_tags\": [\"primary\"], \"path\": \"address.0\" },\n { \"entity_id\": \"234\", \"_tags\": [\"secondary\"], \"path\": \"address.0\" },\n ]\n }\n}\n```\n\nBecomes:\n```json\n{\n \"_id\": \"123\",\n \"name\": \"parent\",\n \"_tags\": [\"parent\"],\n \"contacts\": [\n {\n \"$relation\": { \"entity_id\": \"456\", \"_tags\": [\"primary\"] },\n \"_id\": \"456\",\n \"name\": \"child 1\",\n \"_tags\": [\"child\"]\n },\n {\n \"$relation\": { \"entity_id\": \"789\", \"_tags\": [\"secondary\"] },\n \"_id\": \"789\",\n \"name\": \"child 2\",\n \"_tags\": [\"child\"]\n }\n ],\n \"addresses\": [\n {\n \"$relation_ref\": { \"entity_id\": \"123\", \"_tags\": [\"primary\"], \"path\": \"address.0\" },\n \"_id\": \"123\",\n \"address\": \"address 1\",\n \"_tags\": [\"child\"]\n },\n {\n \"$relation_ref\": { \"entity_id\": \"234\", \"_tags\": [\"secondary\"], \"path\": \"address.0\" },\n \"_id\": \"234\",\n \"address\": \"address 2\",\n \"_tags\": [\"child\"]\n }\n ]\n}\n```\n", "tags": [ "Entities" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitySearchParams" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitySearchResults" } }, "text/csv": { "schema": { "type": "string" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity:list": { "post": { "operationId": "listEntities", "summary": "listEntities", "x-rate-limit": { "limit": 5000, "window": 60, "pool": "search" }, "description": "List entities that meet the specified conditions.\n\nSupports the same options as entity search but utilizes filtering using a subset of [Elastic Query DSL](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html) and does not perform scoring.\n", "tags": [ "Entities" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityListParams" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitySearchResults" } }, "text/csv": { "schema": { "type": "string" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity:graph": { "post": { "operationId": "queryEntityGraph", "summary": "queryEntityGraph", "description": "Traverse an entity relationship graph starting from a seed entity.\n\nDefine the shape of the graph using nodes (entity schemas) and edges (relationships with cardinality).\nThe API will traverse the graph bidirectionally and return all discovered entity IDs.\n\nExample: Find all entities connected to a contact through portal_user -> contact -> billing_account -> files\n", "tags": [ "Entities" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphQueryRequest" } } } }, "responses": { "200": { "description": "Graph traversal result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphQueryResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequestError" }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/v1/entity/{slug}": { "post": { "operationId": "createEntity", "summary": "createEntity", "description": "Creates a new entity using a key.\n\n## Activity\n\nIf no `activity_id` query parameter is provided, implicitly creates Activity of type `EntityCreated`\n\n## Relations\n\nTo create a relation, store a property object that defines a `$relation` array.\n\nExample:\n\n```json\n{\n \"contacts\": {\n \"$relation\": [\n { \"entity_id\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\" }\n ]\n }\n}\n```\n\nThe items in `$relation` support two properties:\n- `entity_id` - The ID of the entity to link\n- `_tags` - Tags or labels for the relation (optional)\n", "tags": [ "Entities" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathParam" }, { "$ref": "#/components/parameters/ActivityIdQueryParam" }, { "$ref": "#/components/parameters/FillActivityQueryParam" }, { "$ref": "#/components/parameters/AsyncOperationQueryParam" }, { "$ref": "#/components/parameters/ValidateEntityQueryParam" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" }, "examples": { "contact": { "$ref": "#/components/examples/ContactEntity" }, "account": { "$ref": "#/components/examples/AccountEntity" }, "product": { "$ref": "#/components/examples/ProductEntity" }, "price": { "$ref": "#/components/examples/PriceEntity" }, "tax": { "$ref": "#/components/examples/TaxEntity" }, "order": { "$ref": "#/components/examples/OrderEntity" }, "opportunity": { "$ref": "#/components/examples/OpportunityEntity" }, "email template": { "$ref": "#/components/examples/EmailTemplateEntity" }, "file": { "$ref": "#/components/examples/FileEntity" }, "workflow step": { "$ref": "#/components/examples/WorkflowStepEntity" }, "submission": { "$ref": "#/components/examples/SubmissionEntity" } } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityItem" } } } }, "422": { "description": "Entity validation error when `?validate=true`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityValidationV2ResultError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity/{slug}:validate": { "post": { "operationId": "validateEntity", "summary": "validateEntity", "description": "Validates an entity against the schema.", "tags": [ "Entities" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathPriceParam" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" }, "examples": { "Valid Price": { "$ref": "#/components/examples/PriceEntity" }, "Invalid Price": { "$ref": "#/components/examples/EmptyGenericEntity" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityValidationResultSuccess" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityValidationResultError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v2/entity/{slug}:validate": { "post": { "operationId": "validateEntityV2", "summary": "validateEntityV2", "description": "Validates an entity against the schema.", "tags": [ "Entities" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathPriceParam" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" }, "examples": { "Valid Price": { "$ref": "#/components/examples/PriceEntity" }, "Invalid Price": { "$ref": "#/components/examples/EmptyGenericEntity" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityValidationV2ResultSuccess" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityValidationV2ResultError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity/{slug}:upsert": { "patch": { "operationId": "upsertEntity", "summary": "upsertEntity", "description": "Create or update an entity using `unique_key`\n\n- If no entities are matched, a new entity is created.\n- If exactly one entity is matched, a `PATCH`-style update is applied to the existing entity.\n\n## Activity\n\nIf no `activity_id` query parameter is provided, implicitly creates Activity of type `EntityCreated` or `EntityUpdated`\n", "tags": [ "Entities" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathParam" }, { "$ref": "#/components/parameters/ActivityIdQueryParam" }, { "$ref": "#/components/parameters/FillActivityQueryParam" }, { "$ref": "#/components/parameters/DryRunQueryParam" }, { "$ref": "#/components/parameters/AsyncOperationQueryParam" }, { "$ref": "#/components/parameters/ValidateEntityQueryParam" }, { "name": "strict", "description": "Strict mode = return 409 if more than one entity is matched", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "unique_key": { "type": "array", "items": { "type": "string", "example": "email.0.email" }, "example": [ "_id" ] }, "entity": { "$ref": "#/components/schemas/Entity" } }, "required": [ "unique_key", "entity" ] } } } }, "responses": { "200": { "description": "Entity was updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityItem" } } } }, "201": { "description": "Entity was created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityItem" } } } }, "405": { "description": "Deleted entities cannot be updated. You'll need to recover the entity first before updating." }, "409": { "description": "Conflict: multiple entities were matched with `unique_key`" }, "422": { "description": "Entity validation error when `?validate=true`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityValidationV2ResultError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v2/entity/{slug}/{id}": { "get": { "operationId": "getEntityV2", "summary": "getEntityV2", "description": "Gets Entity by id.\n\nSupports `hydrate` and `fields` parameters to control the shape of the response.\n", "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" } }, { "$ref": "#/components/parameters/ApplyChangesetsQueryParam" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityItem" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/v1/entity/{slug}/{id}:restore": { "patch": { "operationId": "restoreEntity", "summary": "restoreEntity", "description": "Restores an entity by id\n\n## Activity\n\nIf no `activity_id` query parameter is provided, implicitly creates Activity of type `EntityRestore`\n", "tags": [ "Entities" ], "parameters": [ { "$ref": "#/components/parameters/EntityIdPathParam" }, { "$ref": "#/components/parameters/EntitySlugPathParam" }, { "$ref": "#/components/parameters/ActivityIdQueryParam" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "This endpoint doesn't require a payload, but an empty object can be sent to satisfy certain HTTP clients." } } } }, "responses": { "200": { "description": "The restored entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityItem" } } } }, "400": { "description": "The entity is not deleted" }, "404": { "description": "The entity was not found" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity/{slug}/{id}:reindex": { "post": { "operationId": "reindexEntity", "summary": "reindexEntity", "description": "Triggers a reindex for the Entity for search.\n", "tags": [ "Entities" ], "parameters": [ { "$ref": "#/components/parameters/EntityIdPathParam" }, { "$ref": "#/components/parameters/EntitySlugPathParam" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "This endpoint doesn't require a payload, but an empty object can be sent to satisfy certain HTTP clients." } } } }, "responses": { "200": { "description": "The reindexed entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityItem" } } } }, "404": { "description": "The entity was not found" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "500": { "description": "The entity could not be indexed" } } } }, "/v1/entity/{slug}/{id}": { "get": { "operationId": "getEntity", "summary": "getEntity", "description": "Gets Entity and relations by id.\n\n## Relations\n\nWhen `hydrate=true`, relation attributes are replaced in-place with nested entity values.\n\nExample:\n```json\n{\n \"_id\": \"123\",\n \"name\": \"parent\",\n \"_tags\": [\"parent\"],\n \"contacts\": {\n \"$relation\": [\n { \"entity_id\": \"456\", \"_tags\": [\"primary\"] },\n { \"entity_id\": \"789\", \"_tags\": [\"secondary\"] },\n ]\n },\n \"addresses\": {\n \"$relation_ref\": [\n { \"entity_id\": \"123\", \"_tags\": [\"primary\"], \"path\": \"address.0\" },\n { \"entity_id\": \"234\", \"_tags\": [\"secondary\"], \"path\": \"address.0\" },\n ]\n }\n}\n```\n\nBecomes:\n```json\n{\n \"_id\": \"123\",\n \"name\": \"parent\",\n \"_tags\": [\"parent\"],\n \"contacts\": [\n {\n \"$relation\": { \"entity_id\": \"456\", \"_tags\": [\"primary\"] },\n \"_id\": \"456\",\n \"name\": \"child 1\",\n \"_tags\": [\"child\"]\n },\n {\n \"$relation\": { \"entity_id\": \"789\", \"_tags\": [\"secondary\"] },\n \"_id\": \"789\",\n \"name\": \"child 2\",\n \"_tags\": [\"child\"]\n }\n ],\n \"addresses\": [\n {\n \"$relation_ref\": { \"entity_id\": \"123\", \"_tags\": [\"primary\"], \"path\": \"address.0\" },\n \"_id\": \"123\",\n \"address\": \"address 1\",\n \"_tags\": [\"child\"]\n },\n {\n \"$relation_ref\": { \"entity_id\": \"234\", \"_tags\": [\"secondary\"], \"path\": \"address.0\" },\n \"_id\": \"234\",\n \"address\": \"address 2\",\n \"_tags\": [\"child\"]\n }\n ]\n}\n```\n", "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" } } } } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "put": { "operationId": "updateEntity", "summary": "updateEntity", "description": "Updates an Entity\n\n## Activity\n\nIf no `activity_id` query parameter is provided, implicitly creates Activity of type `EntityUpdated`\n\n## Relations\n\nTo create a relation, store a property that defines a `$relation` array.\n\nExample:\n\n```json\n{\n \"contacts\": {\n \"$relation\": [\n { \"entity_id\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\" }\n ]\n }\n}\n```\n\nThe items in `$relation` support two properties:\n- `entity_id` - The ID of the entity to link\n- `_tags` - Tags or labels for the relation (optional)\n", "tags": [ "Entities" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathParam" }, { "$ref": "#/components/parameters/EntityIdPathParam" }, { "$ref": "#/components/parameters/ActivityIdQueryParam" }, { "$ref": "#/components/parameters/FillActivityQueryParam" }, { "$ref": "#/components/parameters/AsyncOperationQueryParam" }, { "$ref": "#/components/parameters/ValidateEntityQueryParam" }, { "$ref": "#/components/parameters/DirectQueryParam" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" }, "example": {} } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityItem" } } } }, "422": { "description": "Entity validation error when `?validate=true`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityValidationV2ResultError" } } } } } }, "patch": { "operationId": "patchEntity", "summary": "patchEntity", "description": "Partially updates an entity with the passed in entity data.\n\n- If an _updated_at is passed and the server contains a newer version of the entity a `409` Error is returned\n\n## Activity\n\nIf no `activity_id` query parameter is provided, implicitly creates Activity of type `EntityUpdated`\n\n## Relations\n\nTo create a relation, store a property that defines a `$relation` array.\n\nExample:\n\n```json\n{\n \"contacts\": {\n \"$relation\": [\n { \"entity_id\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\" }\n ]\n }\n}\n```\n\nThe items in `$relation` support two properties:\n- `entity_id` - The ID of the entity to link\n- `_tags` - Tags or labels for the relation (optional)\n", "tags": [ "Entities" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathParam" }, { "$ref": "#/components/parameters/EntityIdPathParam" }, { "$ref": "#/components/parameters/ActivityIdQueryParam" }, { "$ref": "#/components/parameters/FillActivityQueryParam" }, { "$ref": "#/components/parameters/DryRunQueryParam" }, { "$ref": "#/components/parameters/AsyncOperationQueryParam" }, { "$ref": "#/components/parameters/ValidateEntityQueryParam" }, { "$ref": "#/components/parameters/DirectQueryParam" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" }, "example": {} } }, "required": true }, "responses": { "200": { "description": "Entity was updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityItem" } } } }, "409": { "description": "Conflict: newer version exists" }, "422": { "description": "Entity validation error when `?validate=true`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityValidationV2ResultError" } } } } } }, "delete": { "operationId": "deleteEntity", "summary": "deleteEntity", "description": "Deletes an Entity\n\n## Activity\n\nIf no `activity_id` query parameter is provided, implicitly creates Activity of type `EntityDeleted`\n\n## Deletion Mode\n\nAll entities are soft deleted by default. To force an actual deletion from the system, provide `purge:true` to delete the entity and all its activity history permanently.\n", "tags": [ "Entities" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathParam" }, { "$ref": "#/components/parameters/EntityIdPathParam" }, { "$ref": "#/components/parameters/ActivityIdQueryParam" }, { "in": "query", "name": "purge", "description": "Permanently deletes the entity when set to `true`", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Success" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity:autocomplete": { "get": { "operationId": "autocomplete", "summary": "autocomplete", "description": "Autocomplete entity attributes\n", "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:wipeAllEntities": { "post": { "operationId": "wipeAllEntities", "summary": "wipeAllEntities", "description": "Creates a request to queue the deletion of all entities in the system. This is a destructive operation and should only be used in sandbox environments.\n", "tags": [ "Entities" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "schemas": { "type": "array", "items": { "$ref": "#/components/schemas/EntitySlug" } } } } } } }, "responses": { "201": { "description": "Wipe request was created" } } } }, "/v1/entity/activity": { "post": { "operationId": "createActivity", "summary": "createActivity", "description": "Create an activity that can be displayed in activity feeds.\n\n- All activites are published as events on the event bus\n- Entity mutations are always part of an activity\n- When more than 10 entities are passed, the first 10 are attached synchronously and the rest are processed asynchronously to avoid DynamoDB throttling\n", "tags": [ "Activity" ], "parameters": [ { "in": "query", "name": "entities", "description": "Comma-separated list of entities which the activity primarily concerns", "style": "form", "explode": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EntityId" } } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Activity" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseActivityItem" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity/activity/{id}": { "get": { "operationId": "getActivity", "summary": "getActivity", "description": "Get activity by id", "tags": [ "Activity" ], "parameters": [ { "$ref": "#/components/parameters/ActivityIdPathParam" }, { "in": "query", "name": "operations_size", "description": "Maximum number of operations to include in response (default: 10)\n", "schema": { "type": "integer", "minimum": 0, "maximum": 1000, "default": 25 } }, { "in": "query", "name": "operations_from", "description": "Pagination offset for operations\n", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityItem" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/v1/entity/activity/{id}:attach": { "post": { "operationId": "attachActivity", "summary": "attachActivity", "description": "Attach existing activity to entity activity feeds", "tags": [ "Activity" ], "parameters": [ { "$ref": "#/components/parameters/ActivityIdPathParam" }, { "in": "query", "name": "entities", "description": "Comma-separated list of entities which the activity primarily concerns", "style": "form", "explode": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EntityId" } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaseActivityItem" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity/{slug}/{id}/changesets/{attribute}:apply": { "post": { "operationId": "applyChangeset", "summary": "applyChangeset", "description": "Applies the proposed value from a pending changeset to the entity attribute\nand removes the changeset. Used for human approval of pending changes.\n", "tags": [ "Entities" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathParam" }, { "$ref": "#/components/parameters/EntityIdPathParam" }, { "in": "path", "name": "attribute", "required": true, "description": "Attribute name of the changeset to apply", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Changeset applied successfully — returns updated entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityItem" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/v1/entity/{slug}/{id}/changesets/{attribute}:dismiss": { "post": { "operationId": "dismissChangeset", "summary": "dismissChangeset", "description": "Removes a pending changeset without applying it. The attribute value remains unchanged.\n", "tags": [ "Entities" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathParam" }, { "$ref": "#/components/parameters/EntityIdPathParam" }, { "in": "path", "name": "attribute", "required": true, "description": "Attribute name of the changeset to dismiss", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "description": "Optional reason for dismissing the changeset" } } } } } }, "responses": { "200": { "description": "Changeset dismissed successfully — returns updated entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityItem" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/v1/entity/{slug}/{id}/changesets": { "get": { "operationId": "listChangesets", "summary": "listChangesets", "description": "Returns all pending changesets for an entity.", "tags": [ "Entities" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathParam" }, { "$ref": "#/components/parameters/EntityIdPathParam" } ], "responses": { "200": { "description": "Pending changesets for the entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangesetMap" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/v1/entity/{slug}/{id}/activity": { "get": { "operationId": "getEntityActivityFeed", "summary": "getEntityActivityFeed", "description": "Get activity feed for an entity\n", "tags": [ "Activity" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathParam" }, { "$ref": "#/components/parameters/EntityIdPathParam" }, { "in": "query", "name": "after", "description": "Get activities strictly after this timestamp. Cannot be used with 'before', 'start_date', 'end_date', or 'preset_range'.", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "before", "description": "Get activities strictly before this timestamp. Cannot be used with 'after', 'start_date', 'end_date', or 'preset_range'.", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "start_date", "description": "The inclusive start timestamp for a date range filter. Requires 'end_date' to also be provided. Cannot be used with 'before', 'after', or 'preset_range'.", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "end_date", "description": "The inclusive end timestamp for a date range filter. Requires 'start_date' to also be provided. Cannot be used with 'before', 'after', or 'preset_range'.", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "preset_range", "description": "Get activities within a predefined date range (e.g., 'today', 'last_week'). Cannot be used with 'before', 'after', 'start_date', or 'end_date'.", "schema": { "type": "string", "example": "last_week", "enum": [ "today", "this_week", "last_week" ] } }, { "$ref": "#/components/parameters/FromPageQueryParam" }, { "in": "query", "name": "size", "description": "max number of results to return", "schema": { "type": "integer", "minimum": 1, "default": 25 } }, { "in": "query", "name": "type", "description": "Filter by activity type(s)", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" }, "example": [ "EntityUpdated", "EntityCreated" ] } }, { "in": "query", "name": "include_relations", "description": "Include activities from related entities", "schema": { "type": "boolean", "default": false } }, { "in": "query", "name": "exclude_activity_groups", "description": "Exclude all activity types that are part of an activity group from results", "schema": { "type": "string", "example": "workflow" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "example": 1 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityItem" } } } } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/v1/entity/{slug}/{id}/relations": { "get": { "operationId": "getRelations", "summary": "getRelations", "description": "Returns 1st level direct relations for an entity.\n\nYou can control whether to return the full entity or just the relation item with the `?hydrate` query param.\n\nReverse relations i.e. entities referring to this entity are included with the `?include_reverse` query param.\n", "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", "_title": "John Doe", "attribute": "contacts", "entity_id": "9924c4de-d3ed-4752-821d-fc0b9bd57c1b", "order_number": "a34234jd", "customer_email": "johndoe@epilot.cloud", "billing_first_name": "john", "billing_last_name": "doe", "billing_company_name": "ePilot Gmbh", "billing_vat": "234823948,", "billing_email": "johndoe@nowhere.com", "billing_phone": "1234234545,", "billing_address": "wallstreet, 1", "billing_contact": "villy or zilly", "$relation": { "attribute": "orders", "entity_id": "9924c4de-d3ed-4752-821d-fc0b9bd57c1b", "_tags": [ "solar_panel", "one_time" ] } } ] } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "post": { "operationId": "addRelations", "summary": "addRelations", "description": "Relates one or more entities to parent entity by adding items to a relation attribute", "tags": [ "Relations" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathParam" }, { "$ref": "#/components/parameters/EntityIdPathParam" }, { "$ref": "#/components/parameters/AsyncOperationQueryParam" }, { "$ref": "#/components/parameters/ActivityIdQueryParam" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RelationItem" } }, "example": [ { "attribute": "contacts", "entity_id": "e8878f62-2d3d-4c86-bfe7-01a4180ff048", "_tags": [ "billing" ] }, { "attribute": "contacts", "entity_id": "ee8a2af9-fb36-4981-b848-4e65275851af" }, { "attribute": "opportunities", "entity_id": "30990430-a53d-41a2-83db-2de072dc4dd4" } ] } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationItem" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "delete": { "operationId": "removeRelations", "summary": "removeRelations", "description": "Disassociate one or more entities to parent entity by removing items to a relation attribute", "tags": [ "Relations" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathParam" }, { "$ref": "#/components/parameters/EntityIdPathParam" }, { "$ref": "#/components/parameters/AsyncOperationQueryParam" }, { "$ref": "#/components/parameters/ActivityIdQueryParam" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RelationItem" } }, "example": [ { "attribute": "contacts", "entity_id": "e8878f62-2d3d-4c86-bfe7-01a4180ff048", "_tags": [ "billing" ] }, { "attribute": "contacts", "entity_id": "ee8a2af9-fb36-4981-b848-4e65275851af" }, { "attribute": "opportunities", "entity_id": "30990430-a53d-41a2-83db-2de072dc4dd4" } ] } } }, "responses": { "204": { "description": "Relations deleted with success." }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v2/entity/{slug}/{id}/relations": { "get": { "operationId": "getRelationsV2", "summary": "getRelationsV2", "description": "Returns 1st level direct relations for an entity with pagination.\n\nYou can control whether to return the full entity or just the relation item with the `?hydrate` query param.\n\nReverse relations i.e. entities referring to this entity are included with the `?include_reverse` query param.\n", "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" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/v3/entity/{slug}/{id}/relations": { "get": { "operationId": "getRelationsV3", "summary": "getRelationsV3", "description": "Returns 1st level direct relations for an entity with pagination.\n\nYou can control whether to return the full entity or just the relation item with the `?hydrate` query param.\n\nReverse relations i.e. entities referring to this entity are included with the `?include_reverse` query param.\n", "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" }, { "in": "query", "name": "fields", "description": "List of entity fields to include in results", "schema": { "$ref": "#/components/schemas/FieldsParam" } }, { "in": "query", "name": "include_deleted", "description": "Whether to include relations to/from deleted entities\n- `true`: include relations to/from deleted entities\n- `false`: exclude relations to/from deleted entities (default)\n- `only`: include only relations to/from deleted entities\n", "required": false, "schema": { "$ref": "#/components/schemas/EntitySearchIncludeDeletedParam" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRelationsRespWithPagination" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/v2/entity/{slug}/{id}/relations/count": { "get": { "operationId": "getRelatedEntitiesCount", "summary": "getRelatedEntitiesCount", "description": "Returns the amount of unique related entities for an entity - includes direct and reverse relations.\n", "tags": [ "Relations" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathParam" }, { "$ref": "#/components/parameters/EntityIdPathParam" }, { "$ref": "#/components/parameters/ExcludeSchemasQueryParam" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRelatedEntitiesCount" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } } }, "/v1/entity/{slug}/{id}/relations/{attribute}/{entity_id}": { "put": { "operationId": "updateRelation", "summary": "updateRelation", "description": "Updates an existing relation between two entities.", "tags": [ "Relations" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathParam" }, { "$ref": "#/components/parameters/EntityIdPathParam" }, { "in": "path", "name": "attribute", "description": "The attribute that express meaning", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "entity_id", "description": "The attribute that express meaning", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/AsyncOperationQueryParam" }, { "$ref": "#/components/parameters/ActivityIdQueryParam" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "_tags": { "type": "array", "items": { "type": "string" } } } }, "example": { "_tags": [ "billing", "prepaid" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationItem" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "delete": { "operationId": "deleteRelation", "summary": "deleteRelation", "description": "Removes relation between two entities", "tags": [ "Relations" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathParam" }, { "$ref": "#/components/parameters/EntityIdPathParam" }, { "in": "path", "name": "attribute", "description": "The attribute that express meaning", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "entity_id", "description": "The attribute that express meaning", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/AsyncOperationQueryParam" }, { "$ref": "#/components/parameters/ActivityIdQueryParam" } ], "responses": { "204": { "description": "Relation deleted with success." }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity:export": { "post": { "operationId": "exportEntities", "summary": "exportEntities", "description": "Export entity data in a CSV-format. The export will export data as close as possible to what is visible on Entity UI tables.\nThe values exported as in some cases, transformed to human-readable values.\n\nTo force the export of raw values, use the `#` prefix in front of your field name when specifying the field on the `fields` param.\n", "tags": [ "Import-Export" ], "parameters": [ { "in": "query", "name": "job_id", "description": "Export Job Id to get the result", "schema": { "$ref": "#/components/schemas/ExportJobId" } }, { "in": "query", "name": "is_template", "description": "Pass 'true' to generate import template", "schema": { "$ref": "#/components/schemas/IsTemplate" } }, { "in": "query", "name": "language", "description": "Export headers translation language", "schema": { "$ref": "#/components/schemas/Language" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitySearchParams" } } } }, "responses": { "201": { "description": "created export url and download url" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity:import": { "post": { "operationId": "importEntities", "summary": "Import Entities", "description": "This endpoint enables the import of entities into the platform.\nThe entities should be provided in a CSV format inside an S3 bucket.\nThis API will return the `job_id`` which can be used to fetch the status of the import process.\n", "tags": [ "Import-Export" ], "parameters": [ { "in": "query", "name": "job_id", "description": "The ID of the import job. This ID is used to track the progress and fetch the result of the import operation.", "schema": { "$ref": "#/components/schemas/ExportJobId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityImportParams" } } } }, "responses": { "201": { "description": "The import operation was initiated successfully.\nThe response includes the URLs for the files containing the successful and failed imported entities.\n" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity/views": { "get": { "operationId": "listSavedViews", "summary": "listSavedViews", "description": "Get the Saved Views based on the schema", "tags": [ "Saved Views" ], "parameters": [ { "in": "query", "name": "slug", "description": "Return views belonging to this schema", "required": false, "schema": { "$ref": "#/components/schemas/EntitySlug" } }, { "in": "query", "name": "sort", "description": "The sort key to use if present", "required": false, "schema": { "type": "string", "default": "name:asc" } }, { "in": "query", "name": "from", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "in": "query", "name": "size", "description": "Number of saved views to return", "required": false, "schema": { "type": "integer", "default": 80, "minimum": 1, "maximum": 250 } }, { "in": "query", "name": "fields", "required": false, "schema": { "$ref": "#/components/schemas/FieldsParam" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSavedViewsResults" } } } } } } }, "/v1/entity/view": { "post": { "operationId": "createSavedView", "summary": "createSavedView", "description": "Creates a new saved view", "tags": [ "Saved Views" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedView" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedViewItem" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity/view/{id}": { "get": { "operationId": "getSavedView", "summary": "getSavedView", "description": "Gets Saved View configuration by id.", "tags": [ "Saved Views" ], "parameters": [ { "$ref": "#/components/parameters/SavedViewIdPathParam" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedViewItem" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "put": { "operationId": "updateSavedView", "summary": "updateSavedView", "description": "Updates a saved view", "tags": [ "Saved Views" ], "parameters": [ { "$ref": "#/components/parameters/SavedViewIdPathParam" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedViewItem" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedViewItem" } } } } } }, "patch": { "operationId": "patchSavedView", "summary": "patchSavedView", "description": "Partially updates a saved view with the provided payload. If an updated_at is passed and the server contains a newer version of the view a `409` error is returned", "tags": [ "Saved Views" ], "parameters": [ { "$ref": "#/components/parameters/SavedViewIdPathParam" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedViewPartial" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedViewItem" } } } } } }, "delete": { "operationId": "deleteSavedView", "summary": "deleteSavedView", "description": "Deletes a saved view", "parameters": [ { "$ref": "#/components/parameters/SavedViewIdPathParam" } ], "tags": [ "Saved Views" ], "responses": { "200": { "description": "List of all available saved views" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity/views/favorites": { "get": { "operationId": "listFavoriteViewsForUser", "summary": "listFavoriteViewsForUser", "description": "Get the Favorite Saved Views for user based on the schema", "tags": [ "Saved Views" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SavedViewItem" } } } } } } } } } }, "/v1/entity/taxonomies": { "get": { "operationId": "listTaxonomies", "summary": "listTaxonomies", "description": "List taxonomies in an organization", "parameters": [ { "in": "query", "name": "include_disabled", "description": "Include disabled taxonomies", "schema": { "type": "boolean", "default": false } }, { "in": "query", "name": "type", "description": "Type of taxonomy to include", "schema": { "type": "string", "enum": [ "entity", "relation" ], "default": "entity" } } ], "tags": [ "Taxonomy" ], "responses": { "200": { "description": "Returns list of taxonomies in an organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/Taxonomy" } } } } } } } } }, "post": { "operationId": "createTaxonomy", "summary": "createTaxonomy", "description": "Create a new taxonomy", "tags": [ "Taxonomy" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Taxonomy" } } } }, "responses": { "201": { "description": "Taxonomy created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Taxonomy" } } } }, "409": { "description": "Taxonomy already exists" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity/taxonomies/{taxonomySlug}": { "get": { "operationId": "getTaxonomy", "summary": "getTaxonomy", "description": "Get taxonomy by slug", "tags": [ "Taxonomy" ], "parameters": [ { "$ref": "#/components/parameters/TaxonomySlugPathParam" } ], "responses": { "200": { "description": "Taxonomy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Taxonomy" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "put": { "operationId": "updateTaxonomy", "summary": "updateTaxonomy", "description": "Update a taxonomy", "tags": [ "Taxonomy" ], "parameters": [ { "$ref": "#/components/parameters/TaxonomySlugPathParam" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Taxonomy" } } } }, "responses": { "200": { "description": "Taxonomy updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Taxonomy" } } } } } }, "delete": { "operationId": "deleteTaxonomy", "summary": "deleteTaxonomy", "description": "Delete a taxonomy", "tags": [ "Taxonomy" ], "parameters": [ { "$ref": "#/components/parameters/TaxonomySlugPathParam" }, { "in": "query", "x-implemented": false, "name": "permanent", "description": "⚠️ NOT IMPLEMENTED - If true, the taxonomy will be permanently deleted", "schema": { "type": "boolean", "default": false } } ], "responses": { "204": { "description": "Taxonomy deleted" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity/taxonomies/{taxonomySlug}/classifications": { "post": { "operationId": "updateClassificationsForTaxonomy", "summary": "updateClassificationsForTaxonomy", "description": "Update the classifications for a taxonomy", "tags": [ "Taxonomy" ], "parameters": [ { "$ref": "#/components/parameters/TaxonomySlugPathParam" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassificationsUpdate" } } } }, "responses": { "200": { "description": "Taxonomies classifications", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomyClassification" } }, "updated": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomyClassification" } }, "deleted": { "type": "array", "items": { "$ref": "#/components/schemas/ClassificationId" } } } } } } }, "404": { "$ref": "#/components/responses/NotFoundError" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v2/entity/taxonomies/classifications": { "post": { "operationId": "createTaxonomyClassification", "summary": "createTaxonomyClassification", "description": "Create a new classification for a taxonomy\n", "tags": [ "Taxonomy" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyClassification" } } } }, "responses": { "201": { "description": "Created taxonomy classification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyClassification" } } } }, "409": { "description": "Taxonomy classification already exists" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v2/entity/taxonomies/classifications/{classificationSlug}": { "get": { "operationId": "getTaxonomyClassification", "summary": "getTaxonomyClassification", "description": "Get a classification for a taxonomy by slug\n\nFor backwards compatibility with purposes, you can also pass the classification id instead of the slug.\n", "tags": [ "Taxonomy" ], "parameters": [ { "$ref": "#/components/parameters/TaxonomyClassificationSlugPathParam" } ], "responses": { "200": { "description": "Taxonomy classification", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyClassification" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "put": { "operationId": "updateTaxonomyClassification", "summary": "updateTaxonomyClassification", "description": "Update a classification for a taxonomy", "tags": [ "Taxonomy" ], "parameters": [ { "$ref": "#/components/parameters/TaxonomyClassificationSlugPathParam" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyClassification" } } } }, "responses": { "200": { "description": "Taxonomy classification updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyClassification" } } } }, "404": { "description": "Taxonomy classification not found" } } }, "delete": { "operationId": "deleteTaxonomyClassification", "summary": "deleteTaxonomyClassification", "description": "Delete a classification for a taxonomy", "tags": [ "Taxonomy" ], "parameters": [ { "$ref": "#/components/parameters/TaxonomyClassificationSlugPathParam" } ], "responses": { "200": { "description": "Taxonomy classification deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyClassification" } } } }, "403": { "description": "Taxonomy classification deletion not allowed" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity/taxonomies/{taxonomySlug}:autocomplete": { "get": { "operationId": "taxonomyAutocomplete", "summary": "taxonomyAutocomplete", "description": "Taxonomies autocomplete", "tags": [ "Taxonomy" ], "parameters": [ { "$ref": "#/components/parameters/TaxonomySlugPathParam" }, { "in": "query", "name": "query", "description": "Input to autocomplete", "schema": { "type": "string" } }, { "in": "query", "name": "size", "description": "Minimum number of results to return", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Taxonomy classifications", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomyClassification" } } } } } } } } } }, "/v1/entity/taxonomies/classifications:search": { "post": { "operationId": "taxonomiesClassificationsSearch", "summary": "taxonomiesClassificationsSearch", "description": "List taxonomy classifications in an organization based on taxonomy slug", "tags": [ "Taxonomy" ], "parameters": [ { "in": "query", "name": "taxonomySlug", "description": "The taxonomy slug(s) to search within. When provided with multiple taxonomy slugs, the search will be performed across all the provided taxonomies.\n", "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, { "in": "query", "name": "query", "description": "The label names to search for (lowercase insensitive)", "schema": { "type": "string", "example": "sales" } }, { "in": "query", "name": "archived", "description": "Filter by archived status. Deprecated. Use `include_archived` instead.", "deprecated": true, "schema": { "type": "boolean", "example": false } }, { "in": "query", "name": "include_archived", "schema": { "$ref": "#/components/schemas/TaxonomySearchIncludeArchivedParam" } }, { "in": "query", "name": "exclude_types", "description": "Taxonomy type(s) to exclude from the results. Useful to filter out relation labels, schema labels, and system labels.\n", "schema": { "anyOf": [ { "type": "string", "enum": [ "relation", "schema", "system" ] }, { "type": "array", "items": { "type": "string", "enum": [ "relation", "schema", "system" ] } } ] } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "classificationIds": { "type": "array", "items": { "$ref": "#/components/schemas/ClassificationIdOrPattern" } } } } } } }, "responses": { "200": { "description": "Returns the classifications for the taxonomy slug provided", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomyClassification" } }, "hits": { "type": "integer", "example": 10 } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity/schemas/{slug}/taxonomy/{taxonomySlug}": { "get": { "operationId": "listTaxonomyClassificationsForSchema", "summary": "listTaxonomyClassificationsForSchema", "description": "List taxonomy classifications for a given schema", "tags": [ "Schemas" ], "parameters": [ { "$ref": "#/components/parameters/EntitySlugPathParam" }, { "$ref": "#/components/parameters/TaxonomySlugPathParam" }, { "in": "query", "name": "query", "schema": { "type": "string" } }, { "in": "query", "name": "size", "schema": { "type": "number" } } ], "responses": { "200": { "description": "List of taxonomy classifications", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomyClassification" } } } } } } } } } }, "/v1/entity/taxonomies/bulk-jobs": { "get": { "operationId": "getTaxonomyBulkActionJobs", "summary": "getTaxonomyBulkActionJobs", "description": "Gets bulk actions jobs by job status:\n- = all active jobs\n- PENDING = all active jobs\n- FAILED = all failed jobs\n- COMPLETED = all completed jobs\n", "tags": [ "Taxonomy" ], "parameters": [ { "in": "query", "description": "The status of the jobs to return", "name": "status", "schema": { "description": "A comma separated list of job statuses to return", "type": "array", "items": { "type": "string" } } }, { "in": "query", "name": "size", "schema": { "description": "The maximum number of jobs to return (defaults to 20)", "type": "number", "default": 20 } }, { "in": "query", "name": "created_after", "schema": { "description": "ISO 8601 timestamp to filter jobs created after this time (e.g., 2023-01-01T00:00:00Z).", "type": "string", "format": "date-time", "example": "2023-01-01T00:00:00Z" } }, { "in": "query", "name": "sort_pending_first", "schema": { "description": "When true, sorts PENDING status jobs to the top of the results.", "type": "boolean", "default": false } }, { "in": "query", "name": "scope", "schema": { "description": "Scope of jobs to return. 'me' returns only jobs created by the current user, 'all' returns jobs from all users in the organization.", "type": "string", "enum": [ "me", "all" ], "default": "me" } } ], "responses": { "200": { "description": "Returns the jobs matching the given query or the active jobs if no status is provided", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomyBulkJob" } } } } } } } }, "/v1/entity/taxonomies/bulk-jobs/{job_id}": { "get": { "operationId": "getTaxonomyBulkActionJobById", "summary": "getTaxonomyBulkActionJobById", "description": "Gets a bulk action job by job id", "tags": [ "Taxonomy" ], "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns the job matching the given job id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyBulkJob" } } } } } } }, "/v1/entity/taxonomies/bulk-jobs/{job_id}/cancel": { "post": { "operationId": "cancelBulkAction", "summary": "cancelBulkAction", "description": "Cancels a running bulk action job. The job status will be updated to CANCELLED\nand the job will be stopped.\n", "tags": [ "Taxonomy" ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Job ID of the bulk operation to cancel" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyBulkJob" } } } }, "400": { "description": "Bad Request" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" }, "500": { "description": "Internal Server Error" } } } }, "/v1/entity/taxonomies/classifications:move": { "post": { "operationId": "bulkMoveClassifications", "summary": "bulkMoveClassifications", "description": "Moves classifications from one taxonomy to another, through a bulk async operation which\nalso updates all references from the old classification to the new one under the target taxonomy.\n", "tags": [ "Taxonomy" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "description": "Job ID for tracking the status of a bulk operation request", "type": "string" }, "target_taxonomy": { "allOf": [ { "description": "The target taxonomy to which the classifications will be moved" }, { "$ref": "#/components/schemas/TaxonomySlug" } ] }, "classification_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ClassificationId" } } } }, "example": { "classification_ids": [ "taxonomy-slug:classification-slug" ] } } } }, "responses": { "200": { "description": "Returns the job id for the async job and current status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyBulkJobTriggerResponse" }, "example": { "job_id": "5684fcb1-62ef-45e4-9187-ebf96dcbff12", "status": "PENDING" } } } }, "400": { "description": "Invalid request" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity/taxonomies/classifications:merge": { "post": { "operationId": "bulkMergeClassifications", "summary": "bulkMergeClassifications", "description": "Merges classifications from one taxonomy into one individual classification, through a bulk async operation which\nalso updates all references from the old Classifications to the new one.\n", "tags": [ "Taxonomy" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "description": "Job ID for tracking the status of a bulk operation request", "type": "string" }, "target_classification": { "allOf": [ { "description": "The target classification id to which the classifications will be merged into" }, { "$ref": "#/components/schemas/TaxonomySlug" } ] }, "classification_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ClassificationId" } } } }, "example": { "classification_ids": [ "taxonomy-slug:classification-slug" ] } } } }, "responses": { "200": { "description": "Returns the job id for the async job and current status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyBulkJobTriggerResponse" }, "example": { "job_id": "5684fcb1-62ef-45e4-9187-ebf96dcbff12", "status": "PENDING" } } } }, "400": { "description": "Invalid request" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity/taxonomies/classifications:delete": { "post": { "operationId": "bulkDeleteClassifications", "summary": "bulkDeleteClassifications", "description": "Permanently deletes taxonomy classifications. The classifications are deleted through a bulk\nasync operation which also deletes all references of the deleted classifications from the entities\nreferencing them.\n", "tags": [ "Taxonomy" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "description": "Job ID for tracking the status of a bulk operation request", "type": "string" }, "classification_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ClassificationId" } } } }, "example": { "classification_ids": [ "taxonomy-slug:classification-slug" ] } } } }, "responses": { "200": { "description": "Returns the job id for the async job and current status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyBulkJobTriggerResponse" }, "example": { "job_id": "5684fcb1-62ef-45e4-9187-ebf96dcbff12", "status": "PENDING" } } } }, "400": { "description": "Invalid request" }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity/schemas/attributes": { "post": { "operationId": "createSchemaAttribute", "summary": "createSchemaAttribute", "description": "Create a schema attribute", "tags": [ "Schemas" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributeWithCompositeID" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributeWithCompositeID" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity/schemas/attributes/{composite_id}": { "get": { "operationId": "getSchemaAttribute", "summary": "getSchemaAttribute", "description": "Get a schema attribute from given attribute ID", "tags": [ "Schemas" ], "parameters": [ { "name": "composite_id", "description": "Schema Slug and the Attribute ID", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^.+:.+$", "example": "contact:97644baa-083f-4e49-9188-fcff2ecaad7d" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributeWithCompositeID" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "put": { "operationId": "putSchemaAttribute", "summary": "putSchemaAttribute", "description": "Updates an attribute in the schema", "tags": [ "Schemas" ], "parameters": [ { "name": "composite_id", "description": "Schema Slug and the Attribute ID", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^.+:.+$", "example": "contact:97644baa-083f-4e49-9188-fcff2ecaad7d" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributeWithCompositeID" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributeWithCompositeID" } } } } } }, "delete": { "operationId": "deleteSchemaAttribute", "summary": "deleteSchemaAttribute", "description": "Deletes an attribute from a schema", "tags": [ "Schemas" ], "parameters": [ { "name": "composite_id", "description": "Schema Slug and the Attribute ID", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^.+:.+$", "example": "contact:97644baa-083f-4e49-9188-fcff2ecaad7d" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributeWithCompositeID" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity/schemas/capabilities": { "post": { "operationId": "createSchemaCapability", "summary": "createSchemaCapability", "description": "Create a schema capability", "tags": [ "Schemas" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityCapabilityWithCompositeID" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityCapabilityWithCompositeID" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity/schemas/capabilities/{composite_id}": { "get": { "operationId": "getSchemaCapability", "summary": "getSchemaCapability", "description": "Get a schema capability from given capability ID", "tags": [ "Schemas" ], "parameters": [ { "name": "composite_id", "description": "Schema Slug and the Attribute ID", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^.+:.+$", "example": "contact:97644baa-083f-4e49-9188-fcff2ecaad7d" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityCapabilityWithCompositeID" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "put": { "operationId": "putSchemaCapability", "summary": "putSchemaCapability", "description": "Adds or updates an capability in the schema", "tags": [ "Schemas" ], "parameters": [ { "name": "composite_id", "description": "Schema Slug and the Attribute ID", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^.+:.+$", "example": "contact:97644baa-083f-4e49-9188-fcff2ecaad7d" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityCapabilityWithCompositeID" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityCapabilityWithCompositeID" } } } } } }, "delete": { "operationId": "deleteSchemaCapability", "summary": "deleteSchemaCapability", "description": "Deletes a Capability from a schema", "tags": [ "Schemas" ], "parameters": [ { "name": "composite_id", "description": "Schema Slug and the Attribute ID", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^.+:.+$", "example": "contact:97644baa-083f-4e49-9188-fcff2ecaad7d" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityCapabilityWithCompositeID" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity/schemas/group": { "post": { "operationId": "createSchemaGroup", "summary": "createSchemaGroup", "description": "Create a schema group", "tags": [ "Schemas" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitySchemaGroupWithCompositeID" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitySchemaGroupWithCompositeID" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity/schemas/group/{composite_id}": { "get": { "operationId": "getSchemaGroup", "summary": "getSchemaGroup", "description": "Get a schema group from given group composite ID", "tags": [ "Schemas" ], "parameters": [ { "name": "composite_id", "description": "Schema Slug and the Group ID", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^.+:.+$", "example": "contact:97644baa-083f-4e49-9188-fcff2ecaad7d" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitySchemaGroupWithCompositeID" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "put": { "operationId": "putSchemaGroup", "summary": "putSchemaGroup", "description": "Adds or updates an capability in the schema", "tags": [ "Schemas" ], "parameters": [ { "name": "composite_id", "description": "Schema Slug and the Group ID", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^.+:.+$", "example": "contact:97644baa-083f-4e49-9188-fcff2ecaad7d" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitySchemaGroupWithCompositeID" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitySchemaGroupWithCompositeID" } } } } } }, "delete": { "operationId": "deleteSchemaGroup", "summary": "deleteSchemaGroup", "description": "Deletes a Capability from a schema", "tags": [ "Schemas" ], "parameters": [ { "name": "composite_id", "description": "Schema Slug and the Group ID", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^.+:.+$", "example": "contact:97644baa-083f-4e49-9188-fcff2ecaad7d" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitySchemaGroupWithCompositeID" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity/schemas/headline": { "post": { "operationId": "createSchemaGroupHeadline", "summary": "createSchemaGroupHeadline", "description": "Create a headline in a schema group", "tags": [ "Schemas" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupHeadlineWithCompositeID" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupHeadlineWithCompositeID" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } }, "/v1/entity/schemas/headline/{composite_id}": { "get": { "operationId": "getSchemaGroupHeadline", "summary": "getSchemaGroupHeadline", "description": "Get a group headline from schema from given headline composite ID", "tags": [ "Schemas" ], "parameters": [ { "name": "composite_id", "description": "Schema Slug and the Schema Group ID", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^.+:.+$", "example": "contact:97644baa-083f-4e49-9188-fcff2ecaad7d" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupHeadlineWithCompositeID" } } } }, "404": { "$ref": "#/components/responses/NotFoundError" } } }, "put": { "operationId": "putSchemaGroupHeadline", "summary": "putSchemaGroupHeadline", "description": "Adds or updates a group headline in the schema", "tags": [ "Schemas" ], "parameters": [ { "name": "composite_id", "description": "Schema Slug and the Schema Group ID", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^.+:.+$", "example": "contact:97644baa-083f-4e49-9188-fcff2ecaad7d" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupHeadlineWithCompositeID" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupHeadlineWithCompositeID" } } } } } }, "delete": { "operationId": "deleteSchemaGroupHeadline", "summary": "deleteSchemaGroupHeadline", "description": "Deletes a group headline from a schema", "tags": [ "Schemas" ], "parameters": [ { "name": "composite_id", "description": "Schema Slug and the Schema Group ID", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^.+:.+$", "example": "contact:97644baa-083f-4e49-9188-fcff2ecaad7d" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GroupHeadlineWithCompositeID" } } } }, "429": { "$ref": "#/components/responses/TooManyRequestsError" } } } } }, "components": { "securitySchemes": { "EpilotAuth": { "type": "http", "scheme": "bearer", "description": "Authorization header with epilot OAuth2 bearer token", "bearerFormat": "JWT" }, "EpilotOrg": { "description": "Overrides the target organization to allow shared tenantaccess", "name": "x-epilot-org-id", "in": "header", "type": "apiKey" } }, "schemas": { "ExportJobId": { "description": "The unique identifier of the import job.", "type": "string", "example": "abc123" }, "Language": { "description": "Export headers translation Language", "type": "string" }, "IsTemplate": { "description": "Pass 'true' to generate import template", "type": "boolean" }, "SchemaId": { "description": "Generated uuid for schema", "type": "string", "format": "uuid" }, "EntitySchema": { "description": "The \"type\" of an Entity. Describes the shape. Includes Entity Attributes, Relations and Capabilities.", "type": "object", "properties": { "slug": { "$ref": "#/components/schemas/EntitySlug" }, "version": { "type": "integer", "minimum": 1 }, "blueprint": { "$ref": "#/components/schemas/BlueprintEntityId" }, "feature_flag": { "type": "string", "example": "FF_MY_FEATURE_FLAG", "description": "This schema should only be active when the feature flag is enabled" }, "enable_setting": { "description": "This schema should only be active when one of the organization settings is enabled", "type": "array", "items": { "type": "string", "example": "360_features" } }, "name": { "description": "User-friendly identifier for the entity schema", "type": "string", "example": "Contact" }, "plural": { "type": "string", "example": "Contacts" }, "description": { "type": "string", "example": "Example description" }, "docs_url": { "type": "string", "format": "uri", "example": "https://docs.epilot.io/docs/pricing/entities" }, "category": { "type": "string", "example": "customer_relations" }, "published": { "type": "boolean", "example": false }, "draft": { "deprecated": true, "type": "boolean", "example": false }, "icon": { "type": "string", "example": "person" }, "title_template": { "type": "string", "description": "Template for rendering the title field. Uses handlebars", "example": "{{first_name}} {{last_name}}" }, "ui_config": { "type": "object", "properties": { "table_view": { "anyOf": [ { "$ref": "#/components/schemas/EntityDefaultTable" }, { "$ref": "#/components/schemas/RedirectEntityView" }, { "$ref": "#/components/schemas/EntityViewDisabled" } ] }, "create_view": { "anyOf": [ { "$ref": "#/components/schemas/EntityDefaultCreate" }, { "$ref": "#/components/schemas/RedirectEntityView" }, { "$ref": "#/components/schemas/EntityViewDisabled" } ] }, "edit_view": { "anyOf": [ { "$ref": "#/components/schemas/EntityDefaultEdit" }, { "$ref": "#/components/schemas/RedirectEntityView" }, { "$ref": "#/components/schemas/EntityViewDisabled" } ] }, "single_view": { "anyOf": [ { "$ref": "#/components/schemas/EntityDefaultEdit" }, { "$ref": "#/components/schemas/RedirectEntityView" }, { "$ref": "#/components/schemas/EntityViewDisabled" } ] }, "list_item": { "type": "object", "properties": { "summary_attributes": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/SummaryAttribute" }, { "type": "string", "description": "List of attributes to show in list item", "example": "email" } ] } }, "quick_actions": { "type": "array", "items": { "$ref": "#/components/schemas/EntityAction" } }, "ui_config": { "type": "object", "properties": { "content_direction": { "type": "string", "enum": [ "row", "column" ], "description": "Show attributes in a row or column" } } } } }, "sharing": { "type": "object", "properties": { "show_sharing_button": { "type": "boolean", "description": "Show the sharing button in entity detail view", "example": true } } } } }, "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/EntityCapability" } }, "group_settings": { "type": "array", "description": "A list of Group Titles and associated settings if present.", "items": { "$ref": "#/components/schemas/EntitySchemaGroup" }, "example": [ { "id": "e18a532b-ae79-4d86-a6a5-e5dbfb579d14", "label": "Contact Details", "expanded": true, "order": 1 }, { "id": "e9a1ae28-27ba-4fa0-a79c-e279cc5c4a6e", "label": "Address Details", "expanded": false, "order": 2, "info_tooltip_title": { "key": "partner.partner_information_group_tooltip", "default": "These informations are provided by the partner company and cannot be edited." } } ] }, "layout_settings": { "type": "object", "description": "Custom grid definitions for the layout. These settings are composed by managed and un-managed properties:\n- Managed Properties: are interpreted and transformed into layout styles\n- Un-managed Properties: are appended as styles into the attribute mounting node\n", "additionalProperties": true, "properties": { "grid_gap": { "type": "string", "description": "Defines the grid gap for the mounting node of the attribute." }, "grid_template_columns": { "type": "string", "description": "Defines the grid column template for the mounting node of the attribute." } } }, "dialog_config": { "type": "object", "additionalProperties": true }, "attributes": { "description": "An ordered list of attributes the entity contains", "type": "array", "items": { "$ref": "#/components/schemas/Attribute" }, "example": [ { "name": "email", "type": "email", "label": "Email", "required": true }, { "name": "first_name", "type": "string", "label": "First Name" }, { "name": "last_name", "type": "string", "label": "Last Name" }, { "name": "birthdate", "type": "date", "label": "Birthdate" }, { "name": "salutation", "type": "select", "label": "Salutation", "options": [ "Mr.", "Ms. / Mrs.", "Other" ] }, { "name": "marketing_permission", "type": "boolean", "label": "Marketing permission" }, { "name": "image", "type": "file", "label": "Image" } ] }, "_purpose": { "type": "array", "items": { "type": "string" } }, "_manifest": { "type": "array", "description": "Manifest ID used to create the schema", "items": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "nullable": true }, "explicit_search_mappings": { "$ref": "#/components/schemas/SearchMappings" }, "group_headlines": { "type": "array", "items": { "$ref": "#/components/schemas/GroupHeadline" } } }, "required": [ "slug", "name", "plural", "attributes", "capabilities" ] }, "EntitySchemaItem": { "allOf": [ { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/SchemaId" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "comment": { "type": "string" }, "source": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } } }, "frozen": { "description": "Indicates this schema is currently frozen. Present when the returned version is the frozen version.", "type": "boolean" }, "latest": { "description": "Indicates this is the latest version of the schema. Both frozen and latest can be true if no changes were made since freezing.", "type": "boolean" }, "_summary": { "description": "Indicates this is a truncated summary schema (attributes trimmed to summary_attributes only, no capabilities or group_settings)", "type": "boolean" } } }, { "$ref": "#/components/schemas/EntitySchema" } ] }, "GenerateEntityTableAIFiltersRequest": { "type": "object", "properties": { "prompt": { "type": "string", "description": "The prompt to generate the filters", "example": "Show me all contacts that are not customers", "maxLength": 300 }, "main_entity_slug": { "type": "string", "description": "The main entity slug", "example": "order" }, "filter_options": { "type": "array", "items": { "$ref": "#/components/schemas/EntityTableFilterOption" } } }, "required": [ "prompt", "main_entity_slug", "filter_options" ] }, "GenerateEntityTableAIFiltersResponse": { "type": "array", "items": { "$ref": "#/components/schemas/EntityTableFilterSearch" } }, "EntityTableFilterSearch": { "type": "object", "properties": { "label": { "type": "string", "description": "The label for the search filter" }, "type": { "type": "string", "description": "The type for the search filter" }, "value": { "type": "string", "description": "The value for the search filter" } }, "required": [ "label", "type", "value" ] }, "EntityTableFilterOption": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of filter option", "enum": [ "search", "filter" ] }, "label": { "type": "string", "description": "The label for the filter option" }, "label_type": { "type": "string", "description": "The label type for the filter option" }, "name": { "type": "string", "description": "The name for the filter option" }, "group": { "type": "string", "description": "The group for the filter option" }, "allowedSchemas": { "type": "array", "items": { "type": "string", "description": "The allowed schemas for the filter option" } }, "relatedOptions": { "type": "array", "items": { "$ref": "#/components/schemas/EntityTableFilterOption" }, "description": "The related options for the filter option" } }, "required": [ "label" ] }, "EntitySchemaGroup": { "type": "object", "properties": { "label": { "type": "string", "example": "Contact Details" }, "id": { "type": "string", "example": "e18a532b-ae79-4d86-a6a5-e5dbfb579d14" }, "order": { "description": "Render order of the group", "type": "integer", "default": 0 }, "expanded": { "description": "Expanded by default", "type": "boolean", "default": false }, "render_condition": { "description": "Only render group when render_condition resolves to true", "type": "string", "example": "_is_composite_price = \"false\"" }, "_purpose": { "description": "Only render group when one of the purposes is enabled", "type": "array", "items": { "$ref": "#/components/schemas/ClassificationId" } }, "_manifest": { "type": "array", "description": "Manifest ID used to create/update the schema group", "items": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "nullable": true }, "feature_flag": { "type": "string", "example": "FF_MY_FEATURE_FLAG", "description": "This group should only be active when the feature flag is enabled" }, "settings_flag": { "type": "array", "description": "This group should only be active when all the settings have the correct value", "items": { "$ref": "#/components/schemas/SettingFlag" } }, "info_tooltip_title": { "type": "object", "properties": { "key": { "description": "Translation key for info tooltip", "type": "string" }, "default": { "description": "Default string for info tooltip", "type": "string" } } } }, "required": [ "label" ] }, "EntitySchemaGroupWithCompositeID": { "allOf": [ { "$ref": "#/components/schemas/EntitySchemaGroup" }, { "type": "object", "description": "a readonly computed ID for the group including schema slug and the group ID", "properties": { "composite_id": { "type": "string", "readOnly": true, "example": "contact:e18a532b-ae79-4d86-a6a5-e5dbfb579d14" }, "schema": { "type": "string", "description": "Schema slug the group belongs to", "example": "contact" } } } ] }, "Attribute": { "anyOf": [ { "$ref": "#/components/schemas/TextAttribute" }, { "$ref": "#/components/schemas/LinkAttribute" }, { "$ref": "#/components/schemas/DateAttribute" }, { "$ref": "#/components/schemas/CountryAttribute" }, { "$ref": "#/components/schemas/BooleanAttribute" }, { "$ref": "#/components/schemas/SelectAttribute" }, { "$ref": "#/components/schemas/MultiSelectAttribute" }, { "$ref": "#/components/schemas/StatusAttribute" }, { "$ref": "#/components/schemas/SequenceAttribute" }, { "$ref": "#/components/schemas/RelationAttribute" }, { "$ref": "#/components/schemas/UserRelationAttribute" }, { "$ref": "#/components/schemas/AddressAttribute" }, { "$ref": "#/components/schemas/AddressRelationAttribute" }, { "$ref": "#/components/schemas/PaymentMethodRelationAttribute" }, { "$ref": "#/components/schemas/CurrencyAttribute" }, { "$ref": "#/components/schemas/TagsAttribute" }, { "$ref": "#/components/schemas/MessageEmailAddressAttribute" }, { "$ref": "#/components/schemas/NumberAttribute" }, { "$ref": "#/components/schemas/TableAttribute" }, { "$ref": "#/components/schemas/ConsentAttribute" }, { "$ref": "#/components/schemas/InternalAttribute" }, { "$ref": "#/components/schemas/OrderedListAttribute" }, { "$ref": "#/components/schemas/FileAttribute" }, { "$ref": "#/components/schemas/ComputedAttribute" }, { "$ref": "#/components/schemas/PartnerStatusAttribute" }, { "$ref": "#/components/schemas/InvitationEmailAttribute" }, { "$ref": "#/components/schemas/AutomationAttribute" }, { "$ref": "#/components/schemas/InternalUserAttribute" }, { "$ref": "#/components/schemas/PurposeAttribute" }, { "$ref": "#/components/schemas/PartnerOrganisationAttribute" }, { "$ref": "#/components/schemas/PortalAccessAttribute" }, { "$ref": "#/components/schemas/PhoneAttribute" }, { "$ref": "#/components/schemas/EmailAttribute" }, { "$ref": "#/components/schemas/PaymentAttribute" }, { "$ref": "#/components/schemas/PriceComponentAttribute" } ] }, "AttributeWithCompositeID": { "allOf": [ { "$ref": "#/components/schemas/Attribute" }, { "type": "object", "description": "a readonly computed ID for the attribute including schema slug and the attribute ID", "properties": { "composite_id": { "type": "string", "readOnly": true, "example": "contact:97644baa-083f-4e49-9188-fcff2ecaad7d" }, "schema": { "type": "string", "description": "Schema slug the attribute belongs to", "example": "contact" } } } ] }, "BaseAttribute": { "type": "object", "properties": { "id": { "type": "string", "description": "ID for the entity attribute", "example": "d5839b94-ba20-4225-a78e-76951d352bd6" }, "name": { "type": "string" }, "label": { "type": "string" }, "placeholder": { "type": "string" }, "hidden": { "description": "Do not render attribute in entity views", "type": "boolean", "default": false }, "show_in_table": { "description": "Render as a column in table views. When defined, overrides `hidden`", "type": "boolean" }, "sortable": { "description": "Allow sorting by this attribute in table views if `show_in_table` is true", "type": "boolean", "default": true }, "required": { "type": "boolean", "default": false }, "readonly": { "type": "boolean", "default": false }, "deprecated": { "type": "boolean", "default": false }, "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.\nThe value must be a valid @epilot/base-elements Icon name\n" }, "render_condition": { "type": "string", "description": "Defines the conditional rendering expression for showing this field.\nWhen a valid expression is parsed, their evaluation defines the visibility of this attribute.\nNote: Empty or invalid expression have no effect on the field visibility.\n" }, "_purpose": { "type": "array", "items": { "$ref": "#/components/schemas/ClassificationId" } }, "_manifest": { "type": "array", "description": "Manifest ID used to create/update the schema attribute", "items": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "nullable": true }, "constraints": { "type": "object", "description": "A set of constraints applicable to the attribute.\nThese constraints should and will be enforced by the attribute renderer.\n", "example": { "disablePast": true } }, "feature_flag": { "type": "string", "example": "FF_MY_FEATURE_FLAG", "description": "This attribute should only be active when the feature flag is enabled" }, "settings_flag": { "type": "array", "description": "This attribute should only be active when one of the provided settings have the correct value", "items": { "$ref": "#/components/schemas/SettingFlag" } }, "value_formatter": { "type": "string" }, "preview_value_formatter": { "type": "string" }, "entity_builder_disable_edit": { "description": "Setting to `true` disables editing the attribute on the entity builder UI", "type": "boolean", "default": false }, "protected": { "description": "Setting to `true` prevents the attribute from being modified / deleted", "type": "boolean" }, "info_helpers": { "description": "A set of configurations meant to document and assist the user in filling the attribute.", "type": "object", "properties": { "hint_text": { "type": "string", "description": "The text to be displayed in the attribute hint helper.\nWhen specified it overrides the `hint_text_key` configuration.\n" }, "hint_text_key": { "type": "string", "description": "The key of the hint text to be displayed in the attribute hint helper.\nThe key should be a valid i18n key.\n" }, "hint_custom_component": { "type": "string", "description": "The name of the custom component to be used as the hint helper.\nThe component should be registered in the `@epilot360/entity-ui` on the index of the components directory.\nWhen specified it overrides the `hint_text` or `hint_text_key` configuration.\n" }, "hint_tooltip_placement": { "type": "string", "description": "The placement of the hint tooltip.\nThe value should be a valid `@mui/core` tooltip placement.\n", "example": "top" } } }, "explicit_searchable": { "type": "boolean", "description": "When set to true, this attribute will always be searchable regardless of\nthe ELASTIC_MAX_SEARCH_FIELDS limit. Use this for critical search fields\nthat must always be included in search operations.\n", "default": false }, "exclude_from_search": { "type": "boolean", "description": "When set to true, this attribute will be excluded from search fields.\nUse this for fields that should not be matched during entity search operations,\nsuch as internal hashes or identifiers that might accidentally match search terms.\n", "default": false }, "repeatable": { "description": "The attribute is a repeatable", "type": "boolean" }, "has_primary": { "type": "boolean" }, "edit_mode": { "allOf": [ { "$ref": "#/components/schemas/EditMode" } ], "description": "Controls how updates to this attribute are handled. See the `EditMode`\nschema for the per-mode semantics. Defaults to `direct`.\n" }, "edit_mode_config": { "description": "Configuration for auto-clear matching on `edit_mode: external` attributes.\n`match_strategy` and `fuzzy_config` are only consulted for `external` mode —\nthey are ignored for `approval` mode, which resolves via explicit\n`:apply` / `:dismiss` endpoints and never auto-clears.\n", "allOf": [ { "$ref": "#/components/schemas/EditModeConfig" } ] } }, "required": [ "name", "label", "type" ] }, "TextAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Textarea or text input", "properties": { "type": { "type": "string", "enum": [ "string" ] }, "multiline": { "type": "boolean" }, "rich_text": { "type": "boolean" }, "rows": { "description": "Number of rows for rich_text textarea", "oneOf": [ { "type": "integer" }, { "type": "string" } ], "example": 3 } } } ] }, "LinkAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Link with title and href", "properties": { "type": { "type": "string", "enum": [ "link" ] } } } ] }, "InternalAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "No UI representation", "properties": { "type": { "type": "string", "enum": [ "internal" ] } } } ] }, "BooleanAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Yes / No Toggle", "properties": { "type": { "type": "string", "enum": [ "boolean" ] }, "display_type": { "type": "string", "enum": [ "switch", "checkbox" ], "default": "switch" } } } ] }, "DateAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Date or Datetime picker", "properties": { "type": { "type": "string", "enum": [ "date", "datetime" ] } } } ] }, "CountryAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Country picker", "properties": { "type": { "type": "string", "enum": [ "country" ] } } } ] }, "SelectAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Dropdown select", "properties": { "type": { "type": "string", "enum": [ "select", "radio" ] }, "options": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "value": { "type": "string" }, "title": { "type": "string" } }, "required": [ "value" ] }, { "type": "string", "nullable": true } ] } }, "allow_any": { "type": "boolean", "description": "Allow arbitrary input values in addition to provided options" } } } ] }, "MultiSelectAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Multi Choice Selection", "properties": { "type": { "type": "string", "enum": [ "multiselect", "checkbox" ] }, "disable_case_sensitive": { "type": "boolean", "nullable": true, "description": "controls if the matching of values against the options is case sensitive or not" }, "allow_extra_options": { "type": "boolean", "nullable": true, "description": "controls if the 360 ui will allow the user to enter a value which is not defined by the options" }, "options": { "type": "array", "items": { "anyOf": [ { "type": "string", "nullable": true }, { "type": "object", "properties": { "value": { "type": "string" }, "title": { "type": "string" } }, "required": [ "value" ] } ] } }, "allow_any": { "type": "boolean", "description": "Allow arbitrary input values in addition to provided options" } } } ] }, "StatusAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Status select", "properties": { "type": { "type": "string", "enum": [ "status" ] }, "options": { "type": "array", "items": { "anyOf": [ { "type": "string", "nullable": true }, { "type": "object", "properties": { "value": { "description": "The stored value of the option", "type": "string" }, "title": { "description": "The displayed title of the option", "type": "string" } }, "required": [ "value" ] } ] } } } } ] }, "SequenceAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Sequence of unique identifiers", "properties": { "type": { "type": "string", "enum": [ "sequence" ] }, "prefix": { "description": "Prefix added before the sequence number", "type": "string", "example": "OR-" }, "start_number": { "type": "integer", "minimum": 0 } } } ] }, "FileAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "File or Image Attachment", "properties": { "type": { "type": "string", "enum": [ "image", "file" ] }, "multiple": { "type": "boolean" }, "allowed_extensions": { "description": "List of file extensions (without the dot suffix)", "type": "array", "items": { "type": "string", "example": "csv" } }, "display_images_landscaped": { "type": "boolean", "description": "Controls how the images are presented to the user during upload on the Entity Details view." }, "enable_description": { "type": "boolean", "description": "When set to true, an i18n description will be used alongside the attribute label.\nThis description should be set through the platform locales in the form: `file.{attribute_name}.description_text`.\n" }, "default_access_control": { "type": "string", "enum": [ "public-read", "private" ] }, "file_size_bytes": { "type": "integer", "description": "The maximum file size in bytes. Used to derive file_size and file_size_unit in the UI.", "example": 5000000 } }, "required": [ "type" ] } ] }, "CurrencyAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Currency input", "properties": { "type": { "type": "string", "enum": [ "currency" ] }, "currency_selector_only": { "type": "boolean", "default": false }, "currency": { "description": "An array of currency configurations with a country code (ISO-4217)", "type": "array", "items": { "anyOf": [ { "type": "object", "description": "A currency configuration", "properties": { "code": { "type": "string" }, "description": { "type": "string" }, "symbol": { "type": "string" }, "flag": { "type": "string" } }, "required": [ "code", "description", "symbol" ], "example": { "code": "EUR", "description": "Euro", "symbol": "€", "flag": "🇪🇺" } } ] } } }, "required": [ "type", "currency" ] } ] }, "SummaryField": { "type": "object", "description": "Summary Fields are displayed inside list view as a resume of the relation entity.", "properties": { "field": { "type": "string", "description": "The field from the entity attributes to display" }, "display_as": { "type": "string", "description": "An hint on how to display the summary field" } } }, "EntityAction": { "type": "object", "description": "An entity action configured from the entity schema", "properties": { "action": { "type": "string", "description": "A unique action name", "example": "preview_file" }, "label": { "type": "string", "example": "Preview File" }, "icon": { "type": "string", "example": "visibility" }, "permission": { "type": "string", "example": "entity:edit", "description": "Permission required to show the action.\nIf not provided, the action will be shown to all users.\n" } }, "required": [ "action", "label" ] }, "RelationAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Entity Relationship", "properties": { "type": { "type": "string", "enum": [ "relation" ] }, "relation_type": { "type": "string", "enum": [ "has_many", "has_one" ] }, "reverse_attributes": { "description": "Map of schema slug to target relation attribute", "type": "object", "additionalProperties": { "type": "string", "example": "contact.account" }, "example": { "contact": "account", "opportunity": "customer" } }, "relation_affinity_mode": { "description": "Weak relation attributes are kept when duplicating an entity. Strong relation attributes are discarded when duplicating an entity.", "type": "string", "enum": [ "weak", "strong" ] }, "enable_relation_picker": { "type": "boolean", "default": true, "description": "When enable_relation_picker is set to true the user will be able to pick existing relations as values. Otherwise, the user will need to create new relation to link." }, "edit_mode": { "type": "string", "enum": [ "list-view" ] }, "details_view_mode_enabled": { "type": "boolean", "default": false, "description": "Enables the preview, edition, and creation of relation items on a Master-Details view mode." }, "relation_picker_filter": { "description": "Additional entity search filter for relation picker", "type": "object", "properties": { "q": { "type": "string", "example": "NOT is_composite_price:true", "nullable": true } }, "required": [ "q" ] }, "actions": { "type": "array", "items": { "type": "object", "properties": { "action_type": { "type": "string", "enum": [ "add_existing", "create_new", "create_from_existing" ], "description": "The action type. Currently supported actions:\n\n| action | description |\n|--------|-------------|\n| add_existing | Enables the user to pick an existing entity to link as relation |\n| create_new | Enables the user to create a new entity using the first/main `allowed_schemas` schema\n| create_from_existing | Enables the user to pick an existing entity to clone from, while creating a blank new entity to link as relation |\n" }, "label": { "type": "string", "description": "The action label or action translation key (i18n)" }, "default": { "type": "boolean", "description": "Sets the action as the default action, visible as the main action button." }, "feature_flag": { "type": "string", "description": "Name of the feature flag that enables this action" }, "settings_flag": { "type": "array", "description": "This action should only be active when all the settings have the correct value", "items": { "$ref": "#/components/schemas/SettingFlag" } }, "new_entity_item": { "description": "Default field values for new entity to create", "nullable": true, "type": "object", "additionalProperties": true, "example": { "_schema": "order" } } } }, "example": [ { "action_type": "add_existing", "label": "entityrelation.add_existing", "default": true }, { "action_type": "create_new", "label": "entityrelation.create_new" }, { "action_type": "create_from_existing", "label": "entityrelation.create_from_existing" } ] }, "drawer_size": { "type": "string", "enum": [ "small", "medium", "large" ] }, "icon": { "type": "string" }, "summary_fields": { "type": "array", "items": { "anyOf": [ { "type": "string", "description": "The field name from the entity attributes to display" }, { "$ref": "#/components/schemas/SummaryField" } ] } }, "has_primary": { "type": "boolean" }, "allowedSchemas": { "type": "array", "items": { "$ref": "#/components/schemas/EntitySlug" } }, "enable_relation_tags": { "type": "boolean", "default": true, "description": "When enable_relation_tags is set to true the user will be able to set tags(labels) in each relation item." }, "add_button_label": { "type": "string", "description": "Optional label for the add button. The translated value for add_button_lable is used, if found else the string is used as is." }, "search_placeholder": { "type": "string", "description": "Optional placeholder text for the relation search input. The translated value for search_placeholder is used, if found else the string is used as is." }, "repeatable": { "description": "Relations are always repeatables", "type": "boolean", "default": true } } } ] }, "UserRelationAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "User Relationship", "properties": { "type": { "type": "string", "enum": [ "relation_user" ] }, "multiple": { "type": "boolean", "default": false } } } ] }, "PartnerOrganisationAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Shared Partner Organisations", "properties": { "type": { "type": "string", "enum": [ "partner_organisation" ] } } } ] }, "PortalAccessAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Portal access configuration", "properties": { "type": { "type": "string", "enum": [ "portal_access" ] } } } ] }, "DefaultAddressFields": { "type": "array", "nullable": true, "description": "Default fields visible on addresses\n\nValid values are:\n - postal_code (default)\n - city (default)\n - street (default)\n - street_number (default)\n - plot_area\n - plot_of_land\n - suburb\n - country\n - postbox\n - additional_info\n - coordinates\n - start_date\n - end_date\n - salutation\n - title\n - first_name\n - last_name\n - name_suffix\n - company_name\n", "items": { "type": "string" } }, "AddressAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Address attribute", "properties": { "type": { "type": "string", "enum": [ "address" ] }, "default_address_fields": { "$ref": "#/components/schemas/DefaultAddressFields" } } } ] }, "AddressRelationAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Reference to an address attribute of another entity", "properties": { "type": { "type": "string", "enum": [ "relation_address" ] }, "has_primary": { "type": "boolean" }, "default_address_fields": { "$ref": "#/components/schemas/DefaultAddressFields" } } } ] }, "PaymentMethodRelationAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Reference to a payment method attribute of another entity", "properties": { "type": { "type": "string", "enum": [ "relation_payment_method" ] }, "has_primary": { "type": "boolean" } } } ] }, "InvitationEmailAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Email address for send invitation", "properties": { "type": { "type": "string", "enum": [ "invitation_email" ] } } } ] }, "AutomationAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Automation entity", "properties": { "type": { "type": "string", "enum": [ "automation" ] } } } ] }, "InternalUserAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Epilot internal user info", "properties": { "type": { "type": "string", "enum": [ "internal_user" ] } } } ] }, "PurposeAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Entity Taxonomy", "properties": { "type": { "type": "string", "enum": [ "purpose" ] } } } ] }, "RepeatableAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Repeatable (add N number of fields)", "properties": { "repeatable": { "type": "boolean" }, "has_primary": { "type": "boolean" } } } ] }, "TagsAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Tags", "properties": { "type": { "type": "string", "enum": [ "tags" ] }, "options": { "type": "array", "items": { "type": "string" } }, "suggestions": { "type": "array", "items": { "type": "string" } } } } ] }, "MessageEmailAddressAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Message emil address", "properties": { "type": { "type": "string", "enum": [ "message_email_address" ] }, "address": { "type": "string" }, "name": { "type": "string" }, "send_status": { "type": "string" }, "email_type": { "type": "string" } }, "required": [ "type", "name" ] } ] }, "NumberAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Numeric input", "properties": { "type": { "type": "string", "enum": [ "number" ] }, "data_type": { "type": "string", "enum": [ "number", "string" ], "default": "string", "description": "Optional data type override. When set to 'number', the value is stored as a number instead of a string. Defaults to 'string'." }, "format": { "type": "string" }, "show_separator": { "description": "Whether or not to show a thousands separator", "type": "boolean", "default": true } } } ] }, "TableAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Dynamic data table with configurable columns. Data is stored as an array of objects where each object represents a row.", "properties": { "type": { "type": "string", "enum": [ "table" ] }, "columns": { "type": "array", "description": "Column definitions for the table", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The column identifier (used as object key in row data)" }, "label": { "type": "string", "description": "Display label for the column header" }, "type": { "type": "string", "description": "The data type for cells in this column", "enum": [ "string", "number", "date", "boolean" ], "default": "string" }, "width": { "type": "string", "description": "Optional column width (e.g., \"100px\", \"20%\")" }, "required": { "type": "boolean", "description": "Whether this column is required for each row", "default": false }, "bold": { "type": "boolean", "description": "When true, the row is rendered in bold (only applies in transposed mode)", "default": false } }, "required": [ "name", "label" ] } }, "min_rows": { "type": "integer", "description": "Minimum number of rows required", "minimum": 0, "default": 0 }, "max_rows": { "type": "integer", "description": "Maximum number of rows allowed (or maximum periods when transposed)", "minimum": 1 }, "transposed": { "type": "boolean", "description": "Enable transposed layout where rows become metrics and columns become periods", "default": false }, "column_header": { "type": "object", "description": "Configuration for column headers in transposed mode", "properties": { "template": { "type": "string", "description": "Header label pattern with {{i}} as index placeholder (e.g., \"Year {{i}}\")", "example": "Year {{i}}" }, "start": { "type": "integer", "description": "Starting index value for the template placeholder", "default": 0, "minimum": 0 } } } } } ] }, "ConsentAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Consent Management", "properties": { "type": { "type": "string", "enum": [ "consent" ] }, "topic": { "type": "string" }, "identifiers": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "topic" ] } ] }, "OrderedListAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Type of attribute to render N number of ordered fields", "properties": { "type": { "type": "string", "enum": [ "ordered_list" ] } } } ] }, "EmailAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Email address", "properties": { "type": { "type": "string", "enum": [ "email" ] } } } ] }, "PhoneAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Phone number", "properties": { "type": { "type": "string", "enum": [ "phone" ] } } } ] }, "PaymentAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Payment method", "properties": { "type": { "type": "string", "enum": [ "payment" ] } } } ] }, "PriceComponentAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Price component", "properties": { "type": { "type": "string", "enum": [ "price_component" ] } } } ] }, "ComputedAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "An attribute that is computed from the entity data. For more details on how to use them, check the docs [here](https://e-pilot.atlassian.net/wiki/spaces/EO/pages/5642977476/How+To+Computed+Schema+Attributes)", "properties": { "type": { "type": "string", "enum": [ "computed" ] }, "computed": { "type": "boolean", "default": true }, "value_formatter": { "type": "string", "description": "Variable template used to format the computed value", "example": "{{formatCurrencyAttribute entity attribute locale}}" }, "preview_value_formatter": { "type": "string", "description": "Variable template used to format a preview for the computed value", "example": "{{formatCurrencyAttribute entity attribute locale}}" }, "amount_field": { "type": "string", "description": "A source amount field that is used to compute the value of the attribute" }, "currency_field": { "type": "string", "description": "A currency field used to format a computed currency value" } }, "required": [ "value_formatter" ] } ] }, "PartnerStatusAttribute": { "allOf": [ { "$ref": "#/components/schemas/BaseAttribute" }, { "type": "object", "description": "Partner Status", "properties": { "type": { "type": "string", "enum": [ "partner_status" ] } } } ] }, "SummaryAttribute": { "description": "Represents an expanded version of an attribute to be displayed in the list item summary.\nThis configuration can be used in the following way:\n```js\n{\n \"label\": \"Price components\"\n \"value\": \"{{item.prices.length}} price components\"\n \"show_as_tag\": true\n \"render_condition\": \"is_composite_price = \"true\"\"\n}\n```\nThe value field supports handlebar expressions from which you can pick any field from the entity state.\n", "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.\nWhen a valid expression is parsed, their evaluation defines the visibility of this attribute.\nNote: Empty or invalid expression have no effect on the field visibility.\n" }, "feature_flag": { "type": "string", "description": "Binds summary field visibility to the feature flag state." }, "settings_flag": { "type": "array", "description": "This summary attribute should only be visible when all the settings have the correct value", "items": { "$ref": "#/components/schemas/SettingFlag" } }, "display_mode": { "type": "string", "enum": [ "inline", "block" ], "description": "Defines the display mode of the summary attribute.\nWhen set to `inline`, the label and value will be displayed in the same line.\nWhen set to `block`, the label and value will be displayed in separate lines.\n" }, "content_line_cap": { "type": "number", "description": "Defines the line numbers of the content.\nFor instance, When set to 1, the content will be displayed in a single line.\n" }, "content_wrap": { "type": "string", "enum": [ "normal", "nowrap", "pre", "pre-wrap" ], "description": "Defines white-space of the content.\n" }, "hide_label": { "type": "boolean", "description": "When set to true, will hide the label of the field." }, "highlight_container": { "type": "boolean", "description": "When set to true, will highlight the container of the field." } }, "required": [ "label", "value" ] }, "GroupHeadline": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "label": { "type": "string" }, "layout": { "type": "string" }, "group": { "type": "string", "description": "The group of headline attribute" }, "order": { "type": "integer", "description": "The order of headline attribute" }, "type": { "type": "string", "enum": [ "headline" ] }, "enable_divider": { "type": "boolean", "default": false }, "divider": { "type": "string", "enum": [ "top_divider", "bottom_divider" ] }, "_purpose": { "type": "array", "items": { "$ref": "#/components/schemas/ClassificationId" } }, "_manifest": { "type": "array", "description": "Manifest ID used to create/update the schema group headline", "items": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "nullable": true } }, "required": [ "name", "label", "group", "type" ] }, "GroupHeadlineWithCompositeID": { "allOf": [ { "$ref": "#/components/schemas/GroupHeadline" }, { "type": "object", "description": "a readonly computed ID for the entity group headline including schema slug and the headline ID", "properties": { "composite_id": { "type": "string", "readOnly": true, "example": "contact:97644baa-083f-4e49-9188-fcff2ecaad7d" }, "schema": { "type": "string", "description": "Schema slug the capability belongs to", "example": "contact" } } } ] }, "EntitySlug": { "description": "URL-friendly identifier for the entity schema", "type": "string", "pattern": "^[a-zA-Z0-9_-]+$", "example": "contact" }, "EntityCapability": { "description": "Capabilities the Entity has. Turn features on/off for entities.", "type": "object", "properties": { "id": { "type": "string", "description": "ID for the entity capability", "example": "d5839b94-ba20-4225-a78e-76951d352bd6" }, "name": { "type": "string", "description": "Unique name for the capability", "example": "customer_messaging" }, "title": { "type": "string", "description": "Human readable title of the capability", "example": "Messaging" }, "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/Attribute" } }, "_purpose": { "type": "array", "items": { "$ref": "#/components/schemas/ClassificationId" } }, "_manifest": { "type": "array", "description": "Manifest ID used to create/update the schema capabilility", "items": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "nullable": true }, "app_id": { "type": "string", "description": "ID of the app if the capability is provided by an app", "example": "123e4567-e89b-12d3-a456-426614174000" }, "ui_config": { "type": "object", "properties": { "is_filterable": { "type": "boolean", "description": "Whether the capability is filterable", "example": true, "default": false } } }, "ui_hooks": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "hook": { "type": "string", "description": "name of the hook to use", "example": "EntityDetailsV2:Tab" }, "render_condition": { "type": "string", "example": "_is_composite_price = \"false\"" }, "order": { "type": "integer", "description": "render order (ascending)", "example": 10 }, "title": { "type": "string", "example": "Notes" }, "group_expanded": { "type": "boolean", "description": "Sets the group expand/collapse default state" }, "import": { "type": "string", "description": "package to be imported", "example": "@epilot360/notes" }, "component": { "type": "string", "description": "the component to be dynamically loaded", "example": "PricingItems" }, "route": { "type": "string", "description": "route for specified capability", "example": "notes" }, "icon": { "type": "string", "description": "Preview icon name(As in Base elements) for the capability", "example": "email" }, "disabled": { "type": "boolean", "description": "Whether capability should be disabled" }, "header": { "type": "boolean", "description": "Specific to Activity pilot" }, "requiredPermission": { "type": "object", "description": "Require a permission to display UI hook", "properties": { "action": { "type": "string", "example": "note:view" }, "resource": { "type": "string", "example": "123" } }, "required": [ "action" ] } }, "required": [ "hook" ] } }, "feature_flag": { "type": "string", "example": "FF_MY_FEATURE_FLAG", "description": "This capability should only be active when the feature flag is enabled" }, "settings_flag": { "type": "array", "description": "This capability should only be active when all the settings have the correct value", "items": { "$ref": "#/components/schemas/SettingFlag" } }, "schemas": { "type": "array", "description": "Schema-specific configuration for the capability", "items": { "type": "object", "additionalProperties": true, "required": [ "schema" ], "properties": { "schema": { "type": "string", "description": "Entity schema slug", "example": "contact" } } } } }, "required": [ "name" ] }, "EntityCapabilityWithCompositeID": { "allOf": [ { "$ref": "#/components/schemas/EntityCapability" }, { "type": "object", "description": "a readonly computed ID for the entity capability including schema slug and the capability ID", "properties": { "composite_id": { "type": "string", "readOnly": true, "example": "contact:97644baa-083f-4e49-9188-fcff2ecaad7d" }, "schema": { "type": "string", "description": "Schema slug the capability belongs to", "example": "contact" } } } ] }, "EntityViewDisabled": { "type": "object", "properties": { "view_type": { "type": "string", "enum": [ "disabled" ] } } }, "EntityDefaultTable": { "type": "object", "properties": { "view_type": { "type": "string", "enum": [ "default" ] }, "row_actions": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/EntityAction" } ] } }, "bulk_actions": { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "$ref": "#/components/schemas/EntityAction" } ] } }, "navbar_actions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "params": { "type": "object" } }, "required": [ "label" ] } } }, "required": [ "type" ] } }, "enable_thumbnails": { "description": "Enable the thumbnail column", "type": "boolean", "default": false } } }, "EntityDefaultCreate": { "type": "object", "properties": { "view_type": { "type": "string", "enum": [ "default" ] }, "search_params": { "type": "object", "additionalProperties": { "type": "string" } } } }, "EntityDefaultEdit": { "type": "object", "properties": { "view_type": { "type": "string", "enum": [ "default" ] }, "search_params": { "type": "object", "additionalProperties": { "type": "string" } }, "summary_attributes": { "description": "List of attribute names that we show in the summary header", "type": "array", "items": { "type": "string", "example": "email" } } } }, "RedirectEntityView": { "type": "object", "properties": { "view_type": { "type": "string", "enum": [ "redirect" ] }, "route": { "type": "string", "example": "/app/pricing-hub/product/:entityId" } }, "example": { "type": "redirect", "route": "/app/pricing-hub/product/:entityId" } }, "EntityId": { "type": "string", "format": "uuid" }, "BaseEntity": { "allOf": [ { "$ref": "#/components/schemas/Entity" }, { "required": [ "_id", "_title", "_org", "_schema", "_created_at", "_updated_at" ] } ] }, "Entity": { "type": "object", "additionalProperties": true, "properties": { "_id": { "allOf": [ { "readOnly": true }, { "$ref": "#/components/schemas/EntityId" } ] }, "_org": { "type": "string", "readOnly": true, "description": "Organization Id the entity belongs to" }, "_owners": { "type": "array", "readOnly": true, "items": { "$ref": "#/components/schemas/EntityOwner" } }, "_schema": { "$ref": "#/components/schemas/EntitySlug" }, "_title": { "type": "string", "description": "Title of entity", "nullable": true }, "_tags": { "type": "array", "items": { "type": "string" }, "nullable": true }, "_created_at": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "_updated_at": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "_deleted_at": { "type": "string", "format": "date-time", "nullable": true, "readOnly": true }, "_acl": { "allOf": [ { "readOnly": true }, { "$ref": "#/components/schemas/EntityAcl" } ] }, "_purpose": { "type": "array", "items": { "type": "string" }, "nullable": true }, "_purpose_name": { "description": "Automatically computed purpose names from _purpose attribute", "type": "array", "items": { "type": "string" }, "nullable": true }, "_manifest": { "type": "array", "description": "Manifest ID used to create/update the entity", "items": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "nullable": true }, "_changesets": { "readOnly": true, "type": "object", "nullable": true, "description": "Pending attribute changesets for attributes configured with external or approval edit mode.\n\nThe value shape is `Changeset` (`proposed_value`, `created_at`, `edit_mode`, ...)\nand is what `:apply` / `:dismiss` operate on.\n\nRead-only via normal entity PATCH/PUT operations — those handlers strip `_changesets`\nfrom request bodies. Use the changeset management endpoints to mutate this field.\n", "additionalProperties": { "$ref": "#/components/schemas/Changeset" } } }, "example": { "_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "_org": "123", "_owners": [ { "org_id": "123", "user_id": "123" } ], "_schema": "contact", "_tags": [ "example", "mock" ], "_created_at": "2021-02-09T12:41:43.662Z", "_updated_at": "2021-02-09T12:41:43.662Z", "_acl": { "view": [ "org:456", "org:789" ], "edit": [ "org:456" ], "delete": [ "org:456" ] }, "_manifest": [ "123e4567-e89b-12d3-a456-426614174000" ] } }, "NullableEntity": { "allOf": [ { "$ref": "#/components/schemas/Entity" }, { "type": "object", "nullable": true } ] }, "EntityOwner": { "description": "The user / organization owning this entity.\n\nNote: Owner implicitly has access to the entity regardless of ACLs.\n", "type": "object", "properties": { "org_id": { "type": "string", "example": "123" }, "user_id": { "type": "string", "example": "123" } }, "required": [ "org_id" ] }, "EntityAcl": { "description": "Access control list (ACL) for an entity. Defines sharing access to external orgs or users.", "type": "object", "properties": { "view": { "type": "array", "items": { "type": "string", "example": "org:456" } }, "edit": { "type": "array", "items": { "type": "string", "example": "org:456" } }, "delete": { "type": "array", "items": { "type": "string", "example": "org:456" } } }, "additionalProperties": true }, "HydratedEntity": { "type": "object", "description": "Entity with relation data resolved into the attribute values", "properties": { "_relations": { "type": "array", "items": { "type": "object", "properties": { "entity_id": { "$ref": "#/components/schemas/EntityId" } }, "required": [ "entity_id" ] } } }, "additionalProperties": true, "required": [ "_relations" ], "example": { "_relations": [ { "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ], "status": "active", "customer_number": "abc123", "email": [ { "label": "work", "email": "user@example.com" } ], "phone": [ { "label": "work", "phone": "+49123456789" } ], "first_name": "First Name", "middle_name": "Middle Name", "last_name": "Last Name", "date_of_birth": "2019-08-24", "title": "Mr.", "account": [ { "status": "active", "name": "Company name", "company_email": [ { "label": "Company email", "email": "company@example.com" } ], "company_phone": [ { "label": "Support phone", "phone": "+49123456789" } ], "company_website": "https://example.com", "tax_id": "DE123456789", "tax_exemption": "2019-08-24", "contacts": { "$relation": [ { "_tags": [ "CEO" ], "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } } ] } }, "EntityItem": { "allOf": [ { "$ref": "#/components/schemas/BaseEntity" }, { "$ref": "#/components/schemas/Entity" } ] }, "EntityValidationError": { "type": "object", "description": "Validation error for an entity attribute", "properties": { "code": { "type": "string", "description": "Error code identifier", "example": "custom" }, "params": { "type": "object", "description": "Additional parameters for the error", "properties": { "type": { "type": "string", "description": "The type of the error", "example": "missing_field" } } }, "path": { "type": "array", "description": "The path to the attribute that failed validation", "items": { "type": "string" }, "example": [ "first_name" ] }, "message": { "type": "string", "description": "A human-readable message describing the error", "example": "Invalid input" } }, "required": [ "code", "params", "path", "message" ] }, "EntityValidationResultSuccess": { "type": "object", "description": "Validation result for a successful validation", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "errors": { "type": "array", "maxItems": 0, "items": { "$ref": "#/components/schemas/EntityValidationError" } } }, "required": [ "status", "errors" ] }, "EntityValidationResultError": { "type": "object", "description": "Validation result for a failed validation", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "errors": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/EntityValidationError" } } }, "required": [ "status", "errors" ] }, "EntityValidationResult": { "oneOf": [ { "$ref": "#/components/schemas/EntityValidationResultSuccess" }, { "$ref": "#/components/schemas/EntityValidationResultError" } ] }, "EntityValidationV2Error": { "type": "object", "properties": { "keyword": { "type": "string", "description": "validation keyword." }, "instance_path": { "type": "string", "description": "JSON Pointer to the location in the data instance (e.g., `\"/prop/1/subProp\"`)." }, "schema_path": { "type": "string", "description": "JSON Pointer to the location of the failing keyword in the schema." }, "params": { "type": "object", "description": "Additional information about error.", "additionalProperties": true }, "property_name": { "type": "string", "description": "Set for errors in `propertyNames` keyword schema. `instance_path` still points to the object in this case." }, "message": { "type": "string", "description": "The error message." }, "schema": { "type": "object", "description": "The value of the failing keyword in the schema." }, "parent_schema": { "type": "object", "description": "The schema containing the keyword.", "additionalProperties": true }, "data": { "type": "object", "description": "The data validated by the keyword.", "additionalProperties": true } }, "required": [ "keyword", "instance_path", "schema_path", "params" ] }, "EntityValidationV2ResultSuccess": { "type": "object", "description": "Validation result for a successful validation", "properties": { "status": { "type": "string", "enum": [ "success" ] }, "errors": { "type": "array", "maxItems": 0, "items": { "$ref": "#/components/schemas/EntityValidationV2Error" } } }, "required": [ "status", "errors" ] }, "EntityValidationV2ResultError": { "type": "object", "description": "Validation result for a failed validation", "properties": { "status": { "type": "string", "enum": [ "error" ] }, "errors": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/EntityValidationV2Error" } } }, "required": [ "status", "errors" ] }, "EntityValidationV2Result": { "oneOf": [ { "$ref": "#/components/schemas/EntityValidationV2ResultSuccess" }, { "$ref": "#/components/schemas/EntityValidationV2ResultError" } ] }, "HydratedEntityItem": { "allOf": [ { "$ref": "#/components/schemas/BaseEntity" }, { "$ref": "#/components/schemas/HydratedEntity" } ] }, "GetRelationsResp": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/RelationItem" }, { "$ref": "#/components/schemas/RelationEntity" } ] } }, "GetRelationsRespWithPagination": { "type": "object", "properties": { "hits": { "type": "number", "example": 1 }, "relations": { "$ref": "#/components/schemas/GetRelationsResp" } } }, "GetRelatedEntitiesCount": { "type": "object", "properties": { "hits": { "type": "integer", "example": 1 } } }, "RelationEntity": { "allOf": [ { "$ref": "#/components/schemas/BaseEntity" }, { "type": "object", "properties": { "$relation": { "$ref": "#/components/schemas/RelationItem" } } } ] }, "RelationItem": { "type": "object", "properties": { "entity_id": { "$ref": "#/components/schemas/EntityId" }, "org_id": { "type": "string", "description": "Organization Id the entity belongs to" }, "_schema": { "$ref": "#/components/schemas/EntitySlug" }, "attribute": { "type": "string" }, "_tags": { "type": "array", "items": { "type": "string" } }, "reverse": { "description": "Whether this is a reverse relation", "type": "boolean" } }, "required": [ "entity_id", "attribute" ] }, "EntitySearchIncludeDeletedParam": { "type": "string", "enum": [ "true", "false", "only" ], "description": "Whether to include deleted entities in the search results\n- `true`: include deleted entities\n- `false`: exclude deleted entities\n- `only`: include only deleted entities\n\nBy default, no deleted entities are included in the search results.\n", "default": "false" }, "EntitySearchParams": { "allOf": [ { "type": "object", "properties": { "q": { "description": "Lucene [queries supported with ElasticSearch](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html#query-string-syntax)", "type": "string", "example": "_schema:contact AND status:active" }, "include_scores": { "type": "boolean", "default": false, "description": "Adds a `_score` number field to results that can be used to rank by match score" }, "sort": {}, "from": {}, "size": {}, "hydrate": {}, "fields": {}, "aggs": {}, "include_deleted": {}, "highlight": {}, "stable_for": {}, "stable_query_id": {}, "search_after": {} }, "additionalProperties": false, "required": [ "q" ] }, { "$ref": "#/components/schemas/EntitySearchOptions" } ] }, "EntityListParams": { "allOf": [ { "type": "object", "properties": { "query": { "description": "Query configuration object for searching entities", "type": "object", "properties": { "query_string": { "description": "Query string configuration based on Elasticsearch query_string query", "type": "object", "properties": { "query": { "description": "The actual query string using Lucene query syntax", "type": "string", "example": "status:active" }, "fields": { "description": "List of fields to search in. If not provided, searches in default fields", "type": "array", "items": { "type": "string" }, "example": [ "_title", "_tags", "status" ] }, "default_operator": { "description": "The default boolean operator used if no explicit operator is specified", "type": "string", "enum": [ "AND", "OR" ], "default": "OR" }, "lenient": { "description": "If true, format-based errors are ignored", "type": "boolean", "default": true } }, "required": [ "query" ] } }, "required": [ "query_string" ] }, "filter": { "$ref": "#/components/schemas/SearchFilter" }, "allow_targeting_all_schemas": { "type": "boolean", "default": false, "description": "Allow running the listing without any schema filter. This is disabled by default to prevent security and performance issues if done by an accident." }, "sort": {}, "from": {}, "size": {}, "hydrate": {}, "fields": {}, "aggs": {}, "include_deleted": {}, "include_scores": {}, "highlight": {}, "stable_for": {}, "stable_query_id": {}, "search_after": {} }, "additionalProperties": false, "required": [ "filter" ] }, { "$ref": "#/components/schemas/EntitySearchOptions" } ] }, "SearchFilter": { "type": "array", "description": "A subset of simplified Elasticsearch query clauses. The default operator is a logical AND. Use nested $and, $or, $not to combine filters using different logical operators.", "items": { "type": "object", "minProperties": 1, "maxProperties": 1, "properties": { "term": { "description": "Returns documents that contain an exact term in a provided field.\n\nTo return a document, the query term must exactly match the queried field's value, including whitespace and capitalization.\n\nYou likely DO NOT want to use this filter on text fields and want to target its .keyword instead.\n", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-term-query.html" }, "type": "object", "minProperties": 1, "maxProperties": 1, "additionalProperties": { "$ref": "#/components/schemas/SearchFilterValue" }, "example": { "_schema": "contact" } }, "terms": { "description": "Returns documents that contain one of the exact terms in a provided field. See term filter for more info.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-terms-query.html" }, "type": "object", "minProperties": 1, "maxProperties": 1, "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/SearchFilterValue" } }, "example": { "status": [ "active" ] } }, "ids": { "description": "Returns documents based on their IDs.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-ids-query.html" }, "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string" } } }, "example": { "values": [ "550e8400-e29b-41d4-a716-446655440000" ] } }, "range": { "description": "Returns documents with fields that have terms within a certain range.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-range-query.html" }, "type": "object", "minProperties": 1, "maxProperties": 1, "additionalProperties": { "type": "object", "properties": { "gt": { "$ref": "#/components/schemas/SearchFilterValue" }, "gte": { "$ref": "#/components/schemas/SearchFilterValue" }, "lt": { "$ref": "#/components/schemas/SearchFilterValue" }, "lte": { "$ref": "#/components/schemas/SearchFilterValue" }, "format": { "type": "string", "description": "The date format used to parse date values." }, "relation": { "type": "string", "enum": [ "INTERSECTS", "CONTAINS", "WITHIN" ], "description": "Indicates how the range query matches values for range fields." }, "time_zone": { "type": "string", "description": "Coordinated Universal Time (UTC) offset or IANA time zone used to convert date values in the query to UTC." } } }, "example": { "_created_at": { "gte": "2021-01-01T00:00:00.000Z", "lte": "2021-01-31T23:59:59.999Z" } } }, "exists": { "description": "Returns documents that have a value in the specified field.", "externalDocs": { "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-exists-query.html" }, "type": "object", "properties": { "field": { "type": "string" } }, "required": [ "field" ], "example": { "field": "_tags" } }, "$and": { "$ref": "#/components/schemas/SearchFilter" }, "$or": { "$ref": "#/components/schemas/SearchFilter" }, "$not": { "$ref": "#/components/schemas/SearchFilter" } } }, "example": [ { "term": { "_schema": "contact" } }, { "terms": { "status": [ "active" ] } } ] }, "SearchFilterValue": { "description": "A filter field value.", "oneOf": [ { "type": "string", "nullable": true }, { "type": "number" }, { "type": "boolean" } ] }, "EntitySearchOptions": { "type": "object", "properties": { "sort": { "description": "You can pass one sort field or an array of sort fields. Each sort field can be a string", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "from": { "type": "integer", "minimum": 0, "default": 0, "description": "The offset from which to start the search results.\nOnly one of `from` or `search_after` should be used.\n" }, "size": { "type": "integer", "minimum": 0, "default": 10, "description": "Max search size is 1000 with higher values defaulting to 1000" }, "hydrate": { "type": "boolean", "description": "When true, enables entity hydration to resolve nested $relation & $relation_ref references in-place.", "default": false }, "fields": { "$ref": "#/components/schemas/FieldsParam" }, "aggs": { "type": "object", "description": "Aggregation supported by ElasticSearch allows summarizing data as metrics, statistics, or other analytics.", "example": { "contact-count-per-tag": { "terms": { "field": "_tags.keyword" } } } }, "include_deleted": { "$ref": "#/components/schemas/EntitySearchIncludeDeletedParam" }, "include_scores": { "type": "boolean", "description": "Adds a `_score` number field to results that can be used to rank by match score", "default": false }, "stable_for": { "type": "integer", "minimum": 0, "maximum": 60, "description": "A TTL (in seconds) that specifies how long the context should be maintained.\nDefaults to 30 seconds; configurable up to 60 seconds to prevent abuse.\nA value of 0 can be provided the close the context after the query.\nDefaults to none.\n" }, "stable_query_id": { "type": "string", "description": "A unique identifier of the query context from the last stable query.\nThe context is maintained for the duration of the stable_for value.\n" }, "search_after": { "type": "array", "items": { "oneOf": [ { "type": "string", "nullable": true }, { "type": "number", "nullable": true } ] }, "description": "The sort values from which to start the search results.\nOnly one of `from` or `search_after` should be used.\nIt is strongly recommended to always use the `sort_end` field from the last search result.\nUsed for deep pagination, typically together with `stable_query_id` to maintain the context between requests.\nRequires explicit sort to work reliably.\nTypically used sort fields are `_id` or `_created_at`.\n" } } }, "FieldsParam": { "type": "array", "description": "List of entity fields to include or exclude in the response\n\nUse ! to exclude fields, e.g. `!_id` to exclude the `_id` field.\n\nGlobbing and globstart (**) is supported for nested fields.\n", "items": { "type": "string" }, "example": [ "_id", "_title", "first_name", "account", "!account.*._files", "**._product" ] }, "EntityImportParams": { "type": "object", "additionalProperties": false, "properties": { "S3Reference": { "type": "object", "properties": { "bucket": { "type": "string", "description": "The name of the S3 bucket where the JSON file for import is stored.", "example": "my-bucket" }, "key": { "type": "string", "description": "The key or path to the JSON file within the S3 bucket.", "example": "imports/my-import.json" } }, "required": [ "bucket", "key" ], "description": "The S3 bucket and key where the JSON file for import is located." }, "schema": { "type": "string", "description": "The schema of the entities being imported. This must match the schema of the entities on the platform.", "example": "contact" } }, "required": [ "S3Reference", "schema" ], "description": "The parameters for importing entities." }, "GraphQueryRequest": { "type": "object", "required": [ "seed", "graph" ], "properties": { "seed": { "$ref": "#/components/schemas/GraphSeed" }, "graph": { "$ref": "#/components/schemas/GraphDefinition" }, "hydrate": { "type": "boolean", "description": "If true, return full entity objects in entityNodes instead of just entity IDs in nodes", "default": false }, "apply_changesets": { "type": "boolean", "description": "When true and hydrate is also true, entity objects in entityNodes have pending changeset proposed values applied in-place. The _changesets field is still included in the response.", "default": false } } }, "GraphSeed": { "type": "object", "required": [ "entity_id", "node_id" ], "properties": { "entity_id": { "$ref": "#/components/schemas/EntityId" }, "node_id": { "type": "string", "description": "The node ID in the graph definition that corresponds to the seed entity", "example": "contact" } } }, "GraphDefinition": { "type": "object", "required": [ "nodes", "edges" ], "properties": { "nodes": { "type": "array", "description": "List of node definitions in the graph", "items": { "$ref": "#/components/schemas/GraphNode" }, "example": [ { "id": "portal_user", "schema": "portal_user", "cardinality": "one" }, { "id": "contact", "schema": "contact", "cardinality": "one" }, { "id": "billing_accounts", "schema": "billing_account", "cardinality": "many" } ] }, "edges": { "type": "array", "description": "List of edge definitions connecting nodes", "items": { "$ref": "#/components/schemas/GraphEdge" }, "example": [ { "from": "portal_user", "to": "contact" }, { "from": "contact", "to": "billing_accounts" } ] } } }, "GraphNode": { "type": "object", "required": [ "id", "schema" ], "properties": { "id": { "type": "string", "description": "Unique identifier for this node in the graph definition", "example": "contact" }, "schema": { "type": "string", "description": "Entity schema slug for this node", "example": "contact" }, "cardinality": { "type": "string", "enum": [ "one", "many" ], "description": "Optional cardinality for this node when used with hydrate=true:\n- \"one\": Node can only contain one entity, return single Entity object in entityNodes\n- \"many\": Node can contain multiple entities, return array of Entity objects in entityNodes\nIf not specified, defaults to \"many\" (returns array). The seed node always returns a single entity regardless of this setting.\n", "example": "one" }, "fields": { "allOf": [ { "$ref": "#/components/schemas/FieldsParam" }, { "description": "Optional array of field names to include in the hydrated entity response for this node.\nWhen specified, only the requested fields plus required internal fields (_id, _schema, _org) will be returned.\nOnly applies when hydrate=true.\n" } ] } } }, "GraphEdge": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "description": "Source node ID", "example": "contact" }, "to": { "type": "string", "description": "Target node ID", "example": "billing_account" } } }, "GraphQueryResponse": { "type": "object", "properties": { "nodes": { "type": "object", "description": "Map of node IDs to arrays of entity IDs found for that node (present when hydrate=false)", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/EntityId" } }, "example": { "portal_user": [ "550e8400-e29b-41d4-a716-446655440001" ], "contact": [ "550e8400-e29b-41d4-a716-446655440002" ], "billing_accounts": [ "550e8400-e29b-41d4-a716-446655440003", "550e8400-e29b-41d4-a716-446655440004" ] } }, "entityNodes": { "type": "object", "description": "Map of node IDs to entity objects or arrays of entity objects (present when hydrate=true).\nThe seed node and nodes with cardinality=\"one\" return a single Entity object, or null if no entity was found.\nNodes with cardinality=\"many\" return an array of Entity objects.\n", "additionalProperties": { "oneOf": [ { "$ref": "#/components/schemas/NullableEntity" }, { "type": "array", "items": { "$ref": "#/components/schemas/Entity" } } ] }, "example": { "portal_user": { "_id": "550e8400-e29b-41d4-a716-446655440001", "_schema": "portal_user" }, "contact": { "_id": "550e8400-e29b-41d4-a716-446655440002", "_schema": "contact" }, "billing_accounts": [ { "_id": "550e8400-e29b-41d4-a716-446655440003", "_schema": "billing_account" }, { "_id": "550e8400-e29b-41d4-a716-446655440004", "_schema": "billing_account" } ] } }, "edges": { "type": "array", "description": "List of edges as defined in the request", "items": { "$ref": "#/components/schemas/GraphEdge" }, "example": [ { "from": "portal_user", "to": "contact" }, { "from": "contact", "to": "billing_accounts" } ] } }, "required": [ "edges" ] }, "EntitySearchResults": { "type": "object", "properties": { "hits": { "type": "number", "example": 1 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/EntityItem" } }, "aggregations": { "type": "object", "example": { "contact-count-per-tag": { "doc_count_error_upper_bound": 0, "sum_other_doc_count": 23, "buckets": [ { "key": "automation", "doc_count": 108 }, { "key": "primary", "doc_count": 66 } ] } } }, "stable_query_id": { "type": "string", "description": "A unique identifier of the query context.\nShould be used on the input for the next query that needs to be executed in the same context.\n" }, "sort_end": { "type": "array", "items": { "oneOf": [ { "type": "string", "nullable": true }, { "type": "number", "nullable": true } ] }, "description": "The sort value of the last item returned in `results`.\nCan be used as the input for the `search_after` in the next query.\n", "example": [ 1747905443332, "0.000023312468" ] } } }, "SearchMappings": { "description": "Advanced: explicit Elasticsearch index mapping definitions for entity data\n", "example": { "image": { "type": "keyword", "index": false } }, "type": "object", "additionalProperties": { "type": "object", "properties": { "index": { "type": "boolean", "default": true }, "type": { "type": "string", "enum": [ "keyword", "text", "boolean", "integer", "long", "float", "date", "flattened", "nested", "object" ] }, "fields": { "additionalProperties": true }, "dynamic": { "type": "boolean", "description": "When false, prevents ES from inferring types for nested fields. Used for _changesets where values can be any type." } } } }, "ActivityId": { "type": "string", "format": "ulid", "description": "See https://github.com/ulid/spec", "example": "01F130Q52Q6MWSNS8N2AVXV4JN", "pattern": "^01[0-9a-zA-Z]{24}$" }, "ActivityCallerContext": { "type": "object", "additionalProperties": true, "properties": { "EpilotAuth": { "type": "object", "properties": { "token": { "type": "object", "properties": { "sub": { "type": "string", "example": "476e9b48-42f4-4234-a2b0-4668b34626ce" }, "email": { "type": "string", "example": "example@epilot.cloud" }, "cognito:username": { "type": "string", "example": "example@epilot.cloud" }, "custom:ivy_user_id": { "type": "string", "example": "10006129" } }, "example": { "sub": "476e9b48-42f4-4234-a2b0-4668b34626ce", "cognito:groups": [ "Administrator" ], "cognito:preferred_role": "arn:aws:iam::912468240823:role/base-administrator-role", "iss": "https://cognito-idp.eu-central-1.amazonaws.com/eu-central-1_6lZSgmU6D", "custom:ivy_org_id": "739224", "cognito:username": "n.ahmad@epilot.cloud", "custom:ivy_user_id": "10006129", "cognito:roles": [ "arn:aws:iam::912468240823:role/base-administrator-role" ], "aud": "6e0jbdnger7nmoktaaflarue1l", "event_id": "cd5f5583-d90c-4db5-8e99-5f5dd29a4d75", "token_use": "id", "auth_time": 1614333023, "exp": 1614336623, "iat": 1614333023, "email": "n.ahmad@epilot.cloud" } } } } } }, "ActivityType": { "type": "string", "description": "A type for the activity. Used to categorize activities in the activity feed and for event subscriptions.\n\nBuilt-in entity activity types (custom activities can be defined as well):\n- EntityCreated\n- EntityUpdated\n- EntityDeleted\n- EntitySoftDeleted\n- EntityRestored\n- RelationsAdded\n- RelationsRemoved\n- RelationsSoftDeleted\n- RelationsRestored\n- RelationsDeleted\n- ChangesetCreated\n- ChangesetAutoCleared\n- ChangesetApplied\n- ChangesetDismissed\n" }, "Activity": { "type": "object", "additionalProperties": false, "properties": { "type": { "$ref": "#/components/schemas/ActivityType" }, "title": { "type": "string", "description": "Title for activity. Supports handlebars syntax.", "example": "My custom activity" }, "message": { "type": "string", "description": "Message for activity. Supports handlebars syntax.", "example": "{{caller}} did something with {{entity payload.entity.id}}." }, "payload": { "type": "object", "properties": {}, "additionalProperties": true, "example": { "entity": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "schema": "contact" } } }, "pending": { "type": "boolean", "description": "Indicates whether the activity is in the pending state.\nPending activities are not yet visible in the activity feed and events are not yet dispatched.\n", "default": false } }, "required": [ "type", "title", "message" ] }, "EntityOperation": { "type": "object", "properties": { "entity": { "$ref": "#/components/schemas/EntityId" }, "org": { "type": "string", "example": "123" }, "activity_id": { "$ref": "#/components/schemas/ActivityId" }, "activity_type": { "$ref": "#/components/schemas/ActivityType" }, "operation": { "type": "string", "enum": [ "createEntity", "updateEntity", "deleteEntity", "softDeleteEntity", "restoreEntity", "relationsAdded", "relationsRemoved", "relationsSoftDeleted", "relationsRestored", "relationsDeleted" ] }, "params": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/EntityId" }, "slug": { "$ref": "#/components/schemas/EntitySlug" } }, "example": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "slug": "contact" } }, "payload": { "allOf": [ { "$ref": "#/components/schemas/Entity" }, { "example": { "_schema": "contact", "_org": "123", "status": "Inactive" } } ] }, "diff": { "type": "object", "properties": { "added": { "allOf": [ { "description": "New attributes added to the entity as part of the operation" }, { "$ref": "#/components/schemas/Entity" } ] }, "updated": { "allOf": [ { "description": "Attributes updated in the entity. Note: These values contain the previous values before the update!" }, { "$ref": "#/components/schemas/Entity" } ] }, "deleted": { "allOf": [ { "description": "Attributes removed from the entity as part of the operation" }, { "$ref": "#/components/schemas/Entity" } ] } } }, "_workflow_origin": { "type": "object", "description": "Internal property for workflow origin tracking and infinite loop prevention.\nPopulated when an entity update originates from a workflow execution.\nThis allows downstream automation services to prevent circular triggering.\n", "properties": { "workflow_exec_id": { "type": "string", "description": "The ID of the workflow execution that triggered this entity update" }, "flow_template_id": { "type": "string", "description": "The flow template ID - used to detect and prevent circular triggering" } } } }, "required": [ "entity", "org", "operation" ] }, "BaseActivityItem": { "allOf": [ { "type": "object", "properties": { "_id": { "$ref": "#/components/schemas/ActivityId" }, "timestamp": { "type": "string", "format": "date-time" } } }, { "$ref": "#/components/schemas/Activity" }, { "type": "object", "properties": { "caller": { "$ref": "#/components/schemas/ActivityCallerContext" } } } ] }, "ActivityItem": { "allOf": [ { "$ref": "#/components/schemas/BaseActivityItem" }, { "type": "object", "properties": { "operations_total": { "type": "integer", "description": "Count of total operations attached to this activity", "example": 1 }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/EntityOperation" } } } } ] }, "BlueprintEntityId": { "description": "Reference to blueprint", "type": "string", "format": "uuid" }, "ListSavedViewsResults": { "type": "object", "properties": { "hits": { "type": "number", "example": 1 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SavedViewItem" } } } }, "SavedViewId": { "description": "Generated uuid for a saved view", "type": "string", "format": "uuid" }, "SavedViewItem": { "allOf": [ { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/SavedViewId" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } }, { "$ref": "#/components/schemas/SavedView" } ] }, "SavedViewPartial": { "description": "A saved entity view", "type": "object", "properties": { "slug": { "type": "array", "description": "list of schemas a view can belong to", "items": { "$ref": "#/components/schemas/EntitySlug" } }, "name": { "description": "User-friendly identifier for the saved view", "type": "string", "example": "View listing German", "minLength": 1, "maxLength": 100 }, "org": { "description": "Organisation ID a view belongs to", "type": "string", "example": "66" }, "shared": { "description": "boolean property for if a view is shared with organisation", "type": "boolean", "example": true }, "isFavoritedBy": { "description": "List of users (IDs) that have favorited the view", "type": "array", "items": { "type": "string", "example": "11701" } }, "created_by": { "anyOf": [ { "type": "object", "description": "A user that created the view", "properties": { "user_id": { "type": "string", "example": "10598" } } }, { "type": "object", "description": "A system-created view", "properties": { "source": { "type": "string", "enum": [ "SYSTEM", "BLUEPRINT" ] } }, "additionalProperties": true } ] }, "ui_config": { "type": "object", "additionalProperties": true, "example": { "filters": { "customer_name": "suresh test", "_tags": "360" }, "table_layout": { "opportunity": { "page": 1, "sort": "_created_at:desc", "pageSize": 25, "columnSettings": [] } } } }, "shared_with": { "type": "array", "description": "List of users ('${userId}'), user groups ('group_${groupId}'), or partner users ('${partnerOrgId}_${partnerUserId}') that the view is shared with", "items": { "type": "string", "example": "112233" } } } }, "SavedView": { "description": "A saved entity view", "allOf": [ { "$ref": "#/components/schemas/SavedViewPartial" }, { "type": "object", "required": [ "slug", "name", "ui_config" ] } ] }, "Taxonomy": { "type": "object", "properties": { "slug": { "$ref": "#/components/schemas/TaxonomySlug" }, "name": { "type": "string", "description": "A human friendly name of a Taxonomy e.g. Purpose, Product Category, Folder, Tag", "example": "Purpose" }, "plural": { "type": "string", "description": "Plural name of a Taxonomy e.g. Purposes, Product Categories, Folders, Tags. Defaults to name is not provided.", "example": "Purposes" }, "kind": { "readOnly": true, "type": "string", "enum": [ "system", "user_defined" ], "description": "Kind of taxonomy e.g. system or user_defined. By default, it's empty, which means 'user_defined'", "example": "system" }, "type": { "type": "string", "enum": [ "entity", "relation", "system", "file_collection" ], "description": "Type of taxonomy. Whether it classifies:\n- entity (default)\n- relation (for relations)\n- system (for system taxonomies - default for all slugs starting with _system_)\n- file_collection (for file collections)\n", "default": "entity", "example": "entity" }, "icon": { "type": "string", "description": "Icon name for the taxonomy (from epilot360/icons icon set)", "example": "purpose" }, "color": { "type": "string", "description": "HEX Color code for the taxonomy", "example": "#FF5733" }, "created_at": { "readOnly": true, "type": "string", "format": "date-time" }, "updated_at": { "readOnly": true, "type": "string", "format": "date-time" }, "deleted_at": { "readOnly": true, "type": "string", "format": "date-time", "description": "Date when the taxonomy was soft-deleted (enabled: false)" }, "created_by": { "readOnly": true, "type": "string", "description": "User ID of the creator", "example": "10598" }, "enabled": { "type": "boolean", "description": "Whether the taxonomy is enabled or not", "example": true }, "order": { "type": "number", "description": "Position of the taxonomy", "example": 10 }, "enabled_locations": { "description": "List of locations where the taxonomy is enabled to be used. If empty, it's enabled for all locations.", "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/TaxonomyLocationId" }, { "type": "string" } ] } } } }, "TaxonomyLocationId": { "type": "string", "enum": [ "account", "contact", "contract", "email_template", "file", "journey", "meter_counter", "meter", "opportunity", "order", "partner", "price", "product", "submission", "tax", "message", "portal_user", "request", "comment" ] }, "TaxonomySearchIncludeArchivedParam": { "type": "string", "enum": [ "true", "false", "only" ], "description": "Whether to include archived labels in the search results\n- `true`: include archived labels\n- `false`: exclude archived labels\n- `only`: include only archived labels\n\nBy default, no archived labels are included in the search results.\n", "default": "false" }, "TaxonomyClassification": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ClassificationId" }, "slug": { "type": "string", "description": "URL-friendly identifier for the classification", "example": "wallbox-pv" }, "name": { "type": "string", "example": "Wallbox PV" }, "parents": { "type": "array", "items": { "$ref": "#/components/schemas/ClassificationId" } }, "color": { "type": "string", "description": "Color of the classification", "example": "#FF5733" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "archived": { "type": "boolean", "description": "Archived classification are not visible in the UI", "default": false }, "starred": { "type": "boolean", "description": "Starred taxonomy classifications can represent \"favorites\" or commonly used classifications", "default": false }, "enabled_locations": { "description": "List of locations where the classification is enabled to be used. If empty, it's enabled for all locations.", "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/TaxonomyLocationId" }, { "type": "string" } ] } }, "enabled_purposes": { "description": "List of purpose slugs where the classification is enabled to be used. If empty, it's enabled for all purposes.", "type": "array", "items": { "type": "string" } }, "_manifest": { "type": "array", "description": "Manifest ID used to create/update the taxonomy classification", "items": { "type": "string", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "nullable": true } }, "required": [ "name", "slug" ] }, "ClassificationId": { "type": "string", "example": "taxonomy-slug:classification-slug", "readOnly": true }, "ClassificationIdOrPattern": { "anyOf": [ { "$ref": "#/components/schemas/ClassificationId" }, { "type": "object", "properties": { "pattern": { "type": "string", "example": "taxonomy-slug:*", "description": "Wildcard pattern to match classification IDs starting with the prefix before ':*'" } }, "required": [ "pattern" ] } ] }, "ClassificationSlug": { "type": "string", "description": "URL-friendly identifier for the classification", "example": "wallbox-pv" }, "TaxonomySlug": { "type": "string", "description": "URL-friendly name for taxonomy", "example": "purpose" }, "ClassificationsUpdate": { "type": "object", "properties": { "create": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomyClassification" } }, "update": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomyClassification" } }, "delete": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/ClassificationId" }, { "type": "string", "example": "taxonomy-slug:classification-slug" } ] } } } }, "TaxonomyBulkJobTriggerResponse": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "status": { "$ref": "#/components/schemas/TaxonomyBulkJobStatus" } } }, "TaxonomyBulkJobStatus": { "type": "string", "description": "The status of the bulk job", "enum": [ "PENDING", "FAILED", "COMPLETED", "CANCELLED" ] }, "TaxonomyBulkJobActionType": { "type": "string", "enum": [ "MOVE_CLASSIFICATIONS", "MERGE_CLASSIFICATIONS", "DELETE_CLASSIFICATIONS" ] }, "TaxonomyBulkJob": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "job_status": { "$ref": "#/components/schemas/TaxonomyBulkJobStatus" }, "failure_reason": { "type": "string" }, "action_type": { "$ref": "#/components/schemas/TaxonomyBulkJobActionType" }, "request": { "type": "object", "properties": { "target_taxonomy": { "$ref": "#/components/schemas/TaxonomySlug" }, "target_classification": { "$ref": "#/components/schemas/ClassificationId" }, "classification_ids": { "type": "array", "items": { "$ref": "#/components/schemas/ClassificationId" } } } }, "output": { "type": "object", "properties": { "target_entities_count": { "type": "number" }, "affected_entities_count": { "type": "number" }, "failures_count": { "type": "number" }, "failed_entities": { "type": "array", "items": { "$ref": "#/components/schemas/EntityId" } } } }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "org": { "type": "string" } }, "example": { "job_id": "123e4567-e89b-12d3-a456-426614174000", "status": "PENDING", "action_type": "MOVE_CLASSIFICATIONS", "created_by": "10598", "created_at": "2024-01-01T00:00:00.000Z", "updated_at": "2024-01-01T00:00:00.000Z", "org": "66" } }, "ESClusterAssignment": { "type": "object", "properties": { "orgId": { "type": "string", "description": "The organization for which the cluster assignment is returned" }, "cluster": { "type": "string", "description": "Name of the elastic cluster the organization is assigned to" } } }, "SettingFlag": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the organization setting to check" }, "enabled": { "type": "boolean", "description": "Whether the setting should be enabled or not" } } }, "ErrorObject": { "description": "A generic error returned by the API", "type": "object", "properties": { "status": { "type": "integer", "description": "The HTTP status code of the error", "example": 400 }, "error": { "type": "string", "description": "The error message", "example": "Bad Request" } } }, "ChangesetCreator": { "type": "object", "description": "Identifies the actor that created the changeset.", "properties": { "type": { "type": "string", "description": "Type of actor that created the changeset", "enum": [ "user", "portal_user", "api_client", "automation" ] }, "id": { "type": "string", "description": "ID of the actor (user ID, portal user ID, API client ID, etc.)" } } }, "Changeset": { "type": "object", "description": "A pending proposed change for a single entity attribute, awaiting external confirmation or human approval.", "required": [ "proposed_value", "created_at", "edit_mode" ], "properties": { "proposed_value": { "description": "The proposed new value for the attribute. Type matches the attribute type." }, "previous_value": { "description": "The attribute value at the time the changeset was created. Stored for reference." }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the changeset was created" }, "created_by": { "$ref": "#/components/schemas/ChangesetCreator" }, "edit_mode": { "type": "string", "description": "The edit mode that triggered this changeset.\n- `external`: auto-cleared by a matching `?direct=true` write (see `match_strategy`).\n- `approval`: resolved only via explicit `:apply` / `:dismiss` endpoints; never auto-clears.\n", "enum": [ "external", "approval" ] }, "match_strategy": { "description": "Match strategy copied from the attribute's `edit_mode_config` at changeset\ncreation time. Only consulted when `edit_mode` is `external`; ignored for\n`approval` (which never auto-clears).\n", "allOf": [ { "$ref": "#/components/schemas/MatchStrategy" } ] }, "source": { "type": "string", "description": "Optional label indicating where the change originated (e.g. end_customer_portal, installer_portal, journey, automation)" }, "related_values": { "type": "object", "description": "Proposed and previous values for related fields in a multi-field attribute group (e.g. currency _decimal/_currency suffixes). Keyed by full field name.", "additionalProperties": { "type": "object", "properties": { "proposed_value": { "description": "The proposed new value for the related field." }, "previous_value": { "description": "The value of the related field when the changeset was created." } } } } } }, "ChangesetMap": { "type": "object", "description": "Map of attribute name to pending changeset. At most one changeset per attribute.", "additionalProperties": { "$ref": "#/components/schemas/Changeset" } }, "MeterReadingChangesetEntry": { "type": "object", "description": "A meter readings changeset entry — service-managed by metering-api.\nStored on `Meter._meter_readings_changeset` array attribute. Each entry mirrors a\nClickHouse meter reading row plus a changeset metadata overlay.\n\nNote: `org_id` is NOT stored on the entry. The entries live on the Meter entity,\nwhich is already org-scoped (`_org`). Round-tripping it would only invite drift;\ndownstream consumers receive the org from the meter / handler context.\n", "required": [ "changeset_id", "meter_id", "counter_id", "value", "edit_mode", "created_at" ], "properties": { "value": { "type": "number" }, "direction": { "type": "string", "enum": [ "feed-in", "feed-out" ] }, "timestamp": { "type": "string", "format": "date-time" }, "meter_id": { "type": "string", "format": "uuid" }, "counter_id": { "type": "string", "format": "uuid" }, "source": { "type": "string" }, "reason": { "type": "string" }, "read_by": { "type": "string" }, "status": { "type": "string", "enum": [ "valid", "in-validation", "implausible" ] }, "external_id": { "type": "string" }, "remark": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "changeset_id": { "type": "string", "description": "Unique changeset identifier (UUID v4)." }, "edit_mode": { "type": "string", "enum": [ "external", "approval" ] }, "match_strategy": { "type": "string", "enum": [ "exact", "fuzzy" ] }, "timestamp_tolerance": { "description": "Slack on `reading.timestamp` when metering-api auto-clear matches an\nincoming reading against this pending changeset.\n\nVariants:\n- `'exact'`: strict millisecond equality.\n- `{ type: 'same-day', timezone? }`: strip the time component and\n compare year-month-day. Optional `timezone` is an IANA name\n (e.g. `'Europe/Berlin'`); the day is bucketed in that zone.\n Defaults to UTC when omitted.\n- `{ type: 'within-seconds', seconds }`: symmetric ±N-second window.\n", "oneOf": [ { "type": "string", "enum": [ "exact" ] }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "same-day" ] }, "timezone": { "type": "string", "description": "IANA timezone identifier (e.g. `'Europe/Berlin'`, `'UTC'`).\nWhen omitted, the day is bucketed in UTC.\n" } } }, { "type": "object", "required": [ "type", "seconds" ], "properties": { "type": { "type": "string", "enum": [ "within-seconds" ] }, "seconds": { "type": "integer", "minimum": 0, "description": "Tolerance in seconds. e.g. 60 = ±1 minute, 3600 = ±1 hour." } } } ] }, "fuzzy_config": { "type": "object", "properties": { "percentage_threshold": { "type": "number" }, "absolute_threshold": { "type": "number" } } }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/ChangesetCreator" }, "previous": { "type": "object", "properties": { "value": { "type": "number" }, "direction": { "type": "string", "enum": [ "feed-in", "feed-out" ] }, "timestamp": { "type": "string", "format": "date-time" } } } } }, "EditMode": { "type": "string", "description": "Controls whether a write goes through immediately or is held as a pending entry\non the parent entity's `_changesets` map.\n\n- `direct`: write applied immediately. No changeset created.\n- `external`: write held as a pending changeset; auto-cleared on a matching direct/ERP write.\n- `approval`: write held as a pending changeset; requires explicit human apply/dismiss.\n\nUsed at two levels: per-attribute (entity-attribute changesets) and per-capability\n(currently the `meter_readings` capability on the Meter schema, gating reading submissions).\n", "enum": [ "direct", "external", "approval" ], "default": "direct" }, "EditModeConfig": { "type": "object", "description": "Configuration for `edit_mode: external` auto-clear matching.\nFields here (`match_strategy`, `fuzzy_config`) only take effect when\n`edit_mode` is `external`. They are ignored for `edit_mode: approval`,\nwhich never auto-clears and is resolved exclusively via the\n`:apply` / `:dismiss` changeset endpoints.\n", "properties": { "match_strategy": { "$ref": "#/components/schemas/MatchStrategy" }, "fuzzy_config": { "$ref": "#/components/schemas/FuzzyConfig" } } }, "FuzzyConfig": { "type": "object", "description": "Configuration for fuzzy auto-clear matching on `edit_mode: external` attributes.\nNot used for `edit_mode: approval`.\n\nType compatibility with attribute shape is enforced at schema save time:\n- scalar string attributes: `suffix`, `digits_only`, `regex`\n- repeatable attributes: `set_equivalent`, `entry_match`, `ignore_fields`, `normalize_phone`\n- relation attributes: `relation_set`\n", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "Which fuzzy algorithm to apply.", "enum": [ "suffix", "digits_only", "normalize_phone", "ignore_fields", "set_equivalent", "entry_match", "relation_set", "regex" ] }, "suffix_length": { "type": "integer", "description": "For type=suffix: number of characters to compare from end of string." }, "fields_to_ignore": { "type": "array", "items": { "type": "string" }, "description": "For type=ignore_fields and type=set_equivalent: field names to exclude when comparing array entries. `_id` is always stripped by the platform regardless of this config." }, "regex_flags": { "type": "string", "description": "For type=regex: flags to apply to the regex (e.g. 'i' for case-insensitive)." }, "country_code": { "type": "string", "description": "For type=normalize_phone: country dialing code digits to strip (e.g. '49' for Germany). No '+' prefix." }, "match_on": { "type": "string", "description": "For type=normalize_phone: attribute key within array entries to compare on (e.g. 'phone_number')." }, "key": { "description": "For type=entry_match: business key(s) within each entry used to match proposed entries against incoming entries.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "mode": { "type": "string", "description": "For type=entry_match and type=set_equivalent: how strict the comparison is.\n- `subset` (default for entry_match): every proposed entry must exist in incoming; extra incoming entries are allowed.\n- `exact_set` (default for set_equivalent): the two sides must contain the same entries (order-insensitive, multiset semantics).\n", "enum": [ "subset", "exact_set" ] }, "ordered": { "type": "boolean", "description": "For type=relation_set: when true, relation order is significant. Defaults to false (order-insensitive)." }, "require_tags_match": { "type": "boolean", "description": "For type=relation_set: when true, each relation item's `_tags` must match on both sides (order-insensitive). Defaults to false — `_tags` are stripped before compare." }, "pattern": { "type": "string", "description": "For type=regex: regular expression pattern to test the incoming value against." } } }, "MatchStrategy": { "type": "string", "description": "Strategy for auto-clearing a changeset on an `edit_mode: external` attribute\nwhen a direct write (`?direct=true`) arrives — typically an ERP inbound sync.\nIgnored for `edit_mode: approval`, which does not auto-clear and is resolved\nexclusively via the `:apply` / `:dismiss` changeset endpoints.\n- `exact`: The inbound value must exactly match the proposed value (deep equality).\n- `fuzzy`: The inbound value is compared using the configured `fuzzy_config` algorithm.\n- `any`: Any update to the attribute clears the changeset, regardless of value.\n", "enum": [ "exact", "fuzzy", "any" ], "default": "exact" } }, "parameters": { "EntityIdPathParam": { "name": "id", "description": "Entity id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EntityId" } }, "EntitySlugPathParam": { "name": "slug", "description": "Entity Type", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/EntitySlug" } }, "EntitySlugPathPriceParam": { "name": "slug", "description": "Entity Type", "in": "path", "required": true, "schema": { "allOf": [ { "$ref": "#/components/schemas/EntitySlug" } ], "example": "price" } }, "TaxonomySlugQueryParam": { "name": "taxonomySlug", "description": "Taxonomy slug", "in": "query", "schema": { "type": "string" }, "required": true }, "TaxonomySlugPathParam": { "name": "taxonomySlug", "description": "Taxonomy slug", "in": "path", "required": true, "schema": { "type": "string" } }, "TaxonomySlugQueryParamOptional": { "name": "taxonomySlug", "description": "Taxonomy slug", "in": "query", "schema": { "type": "string" } }, "TaxonomyClassificationSlugPathParam": { "name": "classificationSlug", "description": "Taxonomy Classification slug", "in": "path", "required": true, "schema": { "type": "string" }, "example": "purpose:" }, "SavedViewIdPathParam": { "name": "id", "description": "View id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/SavedViewId" } }, "AsyncOperationQueryParam": { "name": "async", "description": "Don't wait for updated entity to become available in Search API. Useful for large migrations", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, "HydrateEntitiesQueryParam": { "name": "hydrate", "description": "When true, enables entity hydration to resolve nested $relation & $relation_ref references in-place.", "in": "query", "schema": { "default": false, "type": "boolean" } }, "ActivityIdQueryParam": { "name": "activity_id", "description": "Activity to include in event feed", "in": "query", "required": false, "schema": { "oneOf": [ { "$ref": "#/components/schemas/ActivityId" }, { "type": "string", "nullable": true, "enum": [ "", null ] } ] } }, "ActivityIdPathParam": { "name": "id", "description": "Activity Id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/ActivityId" } }, "FromPageQueryParam": { "name": "from", "description": "Starting page number", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, "IncludeReverseDeprecatedQueryParam": { "name": "include_reverse", "description": "When true, includes reverse relations in response (other entities pointing to this entity)\n*It gets overriden by mode query parameter.*\n", "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.\n*It overrides the include_reverse query param.*\nExplanation of possible options:\n- direct: include relations to which the searched entity refers\n- reverse: include relations that refer to the entity you are looking for\n- both: both direct and reverse relations\n", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "direct", "reverse", "both" ] } }, "DryRunQueryParam": { "name": "dry_run", "description": "Dry Run mode = return results but does not perform the operation.", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, "FillActivityQueryParam": { "name": "fill_activity", "description": "Update the diff and entity for the custom activity included in the query.\nPending state on activity is automatically ended when activity is filled.\n", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, "ValidateEntityQueryParam": { "name": "validate", "description": "When true, enables entity validation against the entity schema.", "in": "query", "schema": { "default": false, "type": "boolean" } }, "DirectQueryParam": { "name": "direct", "description": "When true, bypasses changeset interception: attribute values in the payload\nare written directly to the entity regardless of each attribute's `edit_mode`.\nThe write always lands, independently of any auto-clear outcome below.\n\nAfter the direct write, for each attribute in the payload that also has a\npending changeset:\n- `edit_mode: external` — the incoming value is checked against the\n changeset's `match_strategy` (and `fuzzy_config` when `fuzzy`). On match,\n `_changesets[attr]` is cleared. On no-match, the write still stands and\n the changeset stays pending (signalling the ERP/trusted source applied a\n different correction than originally proposed; resolve via a later\n matching direct write, or via the `:apply` / `:dismiss` endpoints).\n- `edit_mode: approval` — never auto-cleared. The write lands but the\n pending changeset remains until explicitly resolved via `:apply` or\n `:dismiss`.\n\nIntended for trusted integrations (e.g. ERP inbound sync). ERP middleware\nmust always use `?direct=true` — without it, an inbound sync on an\n`external` attribute would create a new changeset instead of confirming\nthe pending one.\n\nDefaults to false — no breaking change for existing callers.\n", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, "ApplyChangesetsQueryParam": { "name": "apply_changesets", "description": "When true, applies pending changeset proposed values in-place on the response entity.\nThe response includes both the hydrated values and the raw _changesets field.\nDoes not mutate stored data — pure read-time transform.\n", "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": "

Variablen - Kontakt

", "brand_id": 7066103, "from": { "name": "Name", "email": "admin@email.xyz" }, "name": "PH Test", "subject": "Example Subject", "system_template": false, "to": [ { "id": "1", "name": "Contact Name", "email": "Contact email" } ], "_tags": [ "Bestellung" ] } }, "FileEntity": { "description": "Example of a file template entity", "value": { "access_control": "private", "filename": "solar_panel_ph.jpeg", "s3ref": { "bucket": "epilot-staging-user-content", "key": "728/temp/6d450fd1-2d63-435f-b598-c605dfb89cbc/solar_panel_ph.jpeg" } } }, "WorkflowStepEntity": { "description": "Example of a workflow step template entity", "value": { "name": "Name", "assigned_to\"": [ "10000563" ], "status": "Unassigned", "order": 123, "tags": [ "tag1" ] } }, "SubmissionEntity": { "description": "Example of a submission step template entity", "value": { "mapped_entities": { "$relation": [ { "entity_id": "4ffb071c-2821-4505-86d0-09b801ffd97a", "relationText": "4ffb071c-2821-4505-86d0-09b801ffd97a", "_schema": "price", "_tags": [] } ] } } }, "EntityValidationError": { "description": "Example of an entity validation error", "value": { "code": "string", "params": { "type": "string" }, "path": [ "string" ], "message": "string" } }, "EntityValidationResultSuccess": { "description": "Example of a successful entity validation result", "value": { "status": "success", "errors": [] } }, "EntityValidationResultError": { "description": "Example of a failed entity validation result", "value": { "status": "error", "errors": [ { "$ref": "#/components/examples/EntityValidationError" } ] } } }, "responses": { "BadRequestError": { "description": "Bad request - invalid input parameters", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorObject" }, { "example": { "status": 400, "error": "Bad Request" } } ] } } } }, "NotFoundError": { "description": "The requested resource was not found", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorObject" }, { "example": { "status": 404, "error": "Not Found" } } ] } } } }, "TooManyRequestsError": { "description": "Too many requests", "headers": { "Retry-After": { "description": "Time to wait in seconds before retrying", "schema": { "type": "integer", "example": 10 } } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ErrorObject" }, { "example": { "status": 429, "error": "Too many requests. Try again later." } } ] } } } } } }, "servers": [ { "url": "https://entity.sls.epilot.io" } ] }