Full Graph

Get the full document linking graph as nodes and edges, or get the graph neighbourhood for a single document with configurable traversal depth.

The linking graph is a bipartite graph with two node types: documents and entities. Edges connect documents to the entity values they share. This endpoint returns the complete graph for your workspace, including detected cases (groups of documents linked through transaction or reference entities) and entity groups (documents linked only through identity entities).

The full graph endpoint can return large payloads for workspaces with many documents. For targeted exploration, use the document subgraph endpoint with a configurable depth parameter instead.

Nodes represent documents (with filename and detected type) or entities (with value and link key category)
Edges connect a document to an entity through a specific field key
Cases are connected components containing transaction or reference entities (2+ documents)
Entity groups are components linked only through identity entities
Excluded entities are high-frequency or owner entities removed from BFS case detection to avoid merging unrelated cases

GET/v1/linking/graph

Response

Response fields

nodesarrayAll document and entity nodes.

nodes[].idstringNode ID. Document nodes use their UUID; entity nodes are prefixed with "entity:".

nodes[].typestring"document" or "entity".

nodes[].labelstringFilename (documents) or entity value (entities).

nodes[].document_typestring | nullInferred document type (document nodes only).

nodes[].categorystring | nullLink key category (entity nodes only).

nodes[].document_countintegerNumber of documents sharing this entity (entity nodes only).

nodes[].excludedbooleanWhether this entity was excluded from BFS (high-frequency or owner).

edgesarrayAll document-entity edges.

edges[].sourcestringDocument node ID.

edges[].targetstringEntity node ID (prefixed with "entity:").

edges[].field_keystringField name where the shared value was found.

edges[].categorystringLink key category of the entity.

casesarrayDetected cases (components with transaction/reference entities).

cases[].case_keystringComputed case key (hex hash of document IDs).

cases[].document_idsstring[]Document IDs in this case.

entity_groupsarrayComponents linked only through identity entities (not cases).

stats.total_documentsintegerTotal completed documents in the workspace.

stats.linked_documentsintegerDocuments with at least one entity link.

stats.unlinked_documentsintegerDocuments with no entity links.

stats.excluded_entitiesintegerNumber of entities excluded from BFS.

Response

{
  "nodes": [
    { "id": "doc_uuid_1", "type": "document", "label": "invoice_oct.pdf", "document_type": "Invoice" },
    { "id": "doc_uuid_2", "type": "document", "label": "po_2024_001.pdf", "document_type": "Purchase Order" },
    {
      "id": "entity:ent_uuid_1",
      "type": "entity",
      "label": "ACME-001",
      "category": "identity",
      "document_count": 2,
      "excluded": false
    }
  ],
  "edges": [
    { "source": "doc_uuid_1", "target": "entity:ent_uuid_1", "field_key": "vendor_id", "category": "identity" },
    { "source": "doc_uuid_2", "target": "entity:ent_uuid_1", "field_key": "vendor_id", "category": "identity" }
  ],
  "cases": [
    { "case_key": "a1b2c3d4e5f6a7b8", "document_ids": ["doc_uuid_1", "doc_uuid_2"], "entity_ids": ["ent_uuid_1"] }
  ],
  "entity_groups": [],
  "stats": {
    "total_documents": 50,
    "linked_documents": 38,
    "unlinked_documents": 12,
    "excluded_entities": 1,
    "owner_entities": ["GlobalCorp"],
    "high_frequency_entities": []
  }
}

To explore the graph from a single document outward, use the document subgraph endpoint below. The depth parameter controls how many hops to traverse — each hop alternates between document and entity nodes.

GET/v1/linking/graph/documents/{id}

depthintegerGraph traversal depth (default 2). Each hop alternates between document and entity nodes. Default: 2

Response

Response fields

nodesarrayDocument and entity nodes reachable within the specified depth.

nodes[].idstringNode ID. Document UUIDs or entity IDs prefixed with "entity:".

nodes[].typestring"document" or "entity".

nodes[].labelstringFilename or entity value.

edgesarrayEdges between the returned nodes.

edges[].sourcestringDocument node ID.

edges[].targetstringEntity node ID.

edges[].field_keystringField name where the shared value was found.

edges[].categorystringLink key category of the entity.

Response

{
  "nodes": [
    { "id": "doc_uuid_1", "type": "document", "label": "invoice_oct.pdf", "document_type": "Invoice" },
    { "id": "entity:ent_uuid_1", "type": "entity", "label": "ACME-001", "category": "identity" },
    { "id": "doc_uuid_2", "type": "document", "label": "po_2024_001.pdf", "document_type": "Purchase Order" }
  ],
  "edges": [
    { "source": "doc_uuid_1", "target": "entity:ent_uuid_1", "field_key": "vendor_id", "category": "identity" },
    { "source": "doc_uuid_2", "target": "entity:ent_uuid_1", "field_key": "vendor_id", "category": "identity" }
  ]
}

Errors

Error responses

400validation_errorInvalid document ID format. Must be a UUID.

401unauthorizedMissing or invalid API key.

429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Document Links

Document-Case Map

Full Graph

Response

Response

Errors

Related