Full Graph
Get the full bipartite document linking graph as nodes and edges, or fetch the graph neighbourhood of 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/graphResponse
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:
2Response
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.
Frequently asked questions
What does the depth parameter control?+
Depth controls BFS traversal hops from the starting document. Depth 1 returns only the document and its direct entities. Depth 2 (default) also includes other documents sharing those entities. Higher depths expand the neighbourhood further.
Why are some entities excluded from case detection?+
High-frequency entities (e.g. a company name appearing on every document) and owner entities are excluded from BFS to prevent merging unrelated document groups into a single oversized case.
What is the difference between cases and entity groups in the graph response?+
Cases are connected components that include at least one transaction or reference entity, such as a shared PO number. Entity groups are components held together only by identity entities, such as a shared vendor ID, and are not promoted to cases.