@epilot/entity-client
Version:
JavaScript client library for the epilot Core Entity API
1,449 lines • 309 kB
JSON
{
"openapi": "3.0.2",
"info": {
"title": "Entity API",
"version": "2.2.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",
"schema": {
"type": "boolean",
"default": false
}
}
],
"tags": [
"Schemas"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntitySchemaItem"
}
}
}
}
}
}
}
}
}
},
"/v1/entity/schemas/{slug}": {
"get": {
"operationId": "getSchema",
"summary": "getSchema",
"description": "By default gets the latest version of the Schema and to get the specific version of schema pass the id.",
"tags": [
"Schemas"
],
"parameters": [
{
"$ref": "#/components/parameters/EntitySlugPathParam"
},
{
"in": "query",
"name": "id",
"schema": {
"$ref": "#/components/schemas/SchemaId"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntitySchemaItem"
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFoundError"
}
}
},
"put": {
"operationId": "putSchema",
"summary": "putSchema",
"description": "Create or update a schema with a new version",
"tags": [
"Schemas"
],
"parameters": [
{
"$ref": "#/components/parameters/EntitySlugPathParam"
},
{
"in": "query",
"name": "draft",
"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": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntitySchemaItem"
}
},
"versions_more": {
"description": "Pagination: Whether more versions are available",
"type": "boolean"
},
"drafts_more": {
"description": "Pagination: Whether more drafts are available",
"type": "boolean"
}
},
"required": [
"versions",
"versions_more"
]
}
}
}
}
}
}
},
"/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"
}
}
],
"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"
}
],
"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"
}