v4

latestOpenAPI 3.0.22026-07-3188146256.6 KB

Entities

searchEntities

Search for entities. Supports ordering and pagination. Lucene query syntax supported for complex querying.

Passing comma-separated x-epilot-org-id is supported for cross-org entity search.

Relations

When hydrate=true, relation attributes are replaced in-place with nested entity values.

Example:

{
  "_id": "123",
  "name": "parent",
  "_tags": ["parent"],
  "contacts": {
    "$relation": [
      { "entity_id": "456", "_tags": ["primary"] },
      { "entity_id": "789", "_tags": ["secondary"] },
    ]
  },
  "addresses": {
    "$relation_ref": [
      { "entity_id": "123", "_tags": ["primary"], "path": "address.0" },
      { "entity_id": "234", "_tags": ["secondary"], "path": "address.0" },
    ]
  }
}

Becomes:

{
  "_id": "123",
  "name": "parent",
  "_tags": ["parent"],
  "contacts": [
    {
      "$relation": { "entity_id": "456", "_tags": ["primary"] },
      "_id": "456",
      "name": "child 1",
      "_tags": ["child"]
    },
    {
      "$relation": { "entity_id": "789", "_tags": ["secondary"] },
      "_id": "789",
      "name": "child 2",
      "_tags": ["child"]
    }
  ],
  "addresses": [
    {
      "$relation_ref": { "entity_id": "123", "_tags": ["primary"], "path": "address.0" },
      "_id": "123",
      "address": "address 1",
      "_tags": ["child"]
    },
    {
      "$relation_ref": { "entity_id": "234", "_tags": ["secondary"], "path": "address.0" },
      "_id": "234",
      "address": "address 2",
      "_tags": ["child"]
    }
  ]
}

post/v1/entity:search

Request body

qstring required

Lucene queries supported with ElasticSearch

include_scoresboolean

Adds a _score number field to results that can be used to rank by match score

frominteger

The offset from which to start the search results. Only one of from or search_after should be used.

sizeinteger

Max search size is 1000 with higher values defaulting to 1000

hydrateboolean

When true, enables entity hydration to resolve nested $relation & $relation_ref references in-place.

anonymizeboolean

When true, anonymizes PII in the response: identifiers are replaced with deterministic pseudonyms, addresses are generalized and well-known free-text fields are redacted. Anonymization is forced (regardless of this parameter) when the access token was created with anonymize: true.

fieldsstring[]

List of entity fields to include or exclude in the response

Use ! to exclude fields, e.g. !_id to exclude the _id field.

Globbing and globstart (**) is supported for nested fields.

aggsobject

Aggregation supported by ElasticSearch allows summarizing data as metrics, statistics, or other analytics.

include_deleted'true' | 'false' | 'only'

Whether to include deleted entities in the search results

true: include deleted entities
false: exclude deleted entities
only: include only deleted entities

By default, no deleted entities are included in the search results.

{"stackTrail":"components:schemas:EntitySearchParams:allOf:properties:highlight","oasType":"schema","type":"unknown"}

stable_forinteger

A TTL (in seconds) that specifies how long the context should be maintained. Defaults to 30 seconds; configurable up to 60 seconds to prevent abuse. A value of 0 can be provided the close the context after the query. Defaults to none.

stable_query_idstring

A unique identifier of the query context from the last stable query. The context is maintained for the duration of the stable_for value.

Example request

{
  "q": "_schema:contact AND status:active",
  "fields": [
    "_id",
    "_title",
    "first_name",
    "account",
    "!account.*._files",
    "**._product"
  ],
  "aggs": {
    "contact-count-per-tag": {
      "terms": {
        "field": "_tags.keyword"
      }
    }
  }
}

Response

Success

hitsnumber

aggregationsobject

stable_query_idstring

A unique identifier of the query context. Should be used on the input for the next query that needs to be executed in the same context.

Example response

{
  "hits": 1,
  "results": [
    {
      "_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"
      ]
    }
  ],
  "aggregations": {
    "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
        }
      ]
    }
  },
  "sort_end": [
    1747905443332,
    "0.000023312468"
  ]
}