v4

latestOpenAPI 3.0.22026-07-3188146256.6 KB

Entities

queryEntityGraph

Traverse an entity relationship graph starting from a seed entity.

Define the shape of the graph using nodes (entity schemas) and edges (relationships with cardinality). The API will traverse the graph bidirectionally and return all discovered entity IDs.

Example: Find all entities connected to a contact through portal_user -> contact -> billing_account -> files

post/v1/entity:graph

Request body

hydrateboolean

If true, return full entity objects in entityNodes instead of just entity IDs in nodes

apply_changesetsboolean

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.

Example request

{
  "seed": {
    "node_id": "contact"
  },
  "graph": {
    "nodes": [
      {
        "id": "portal_user",
        "schema": "portal_user",
        "cardinality": "one"
      },
      {
        "id": "contact",
        "schema": "contact",
        "cardinality": "one"
      },
      {
        "id": "billing_accounts",
        "schema": "billing_account",
        "cardinality": "many"
      }
    ],
    "edges": [
      {
        "from": "portal_user",
        "to": "contact"
      },
      {
        "from": "contact",
        "to": "billing_accounts"
      }
    ]
  }
}

Response

Graph traversal result

nodesobject

Map of node IDs to arrays of entity IDs found for that node (present when hydrate=false)

entityNodesobject

Map of node IDs to entity objects or arrays of entity objects (present when hydrate=true). The seed node and nodes with cardinality="one" return a single Entity object, or null if no entity was found. Nodes with cardinality="many" return an array of Entity objects.

Example response

{
  "nodes": {
    "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": {
    "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": [
    {
      "from": "portal_user",
      "to": "contact"
    },
    {
      "from": "contact",
      "to": "billing_accounts"
    }
  ]
}