File System API

The File System API lets an LLM agent (or any programmatic client) navigate parsed documents the way it would navigate a filesystem — ls to list, grep to search, cat to read, head for a quick peek, stat for metadata, and find / open / xref for the cross-document entity memory layer.

POST /v3/fs
Content-Type: application/json
x-api-key: <your API key>

Every request sends {"op": "<verb>", ...}. Every response returns {"op", "data", "hasMore?", "nextCursor?", "count?", "hint?"}.

Operations at a glance

The path field

path is the positional identifier — what it refers to depends on the op:

• Doc ops (cat, head, stat): pass the document's referenceID from ls.
• Entity ops (open, xref): pass the entityID from find.
• grep: optionally pass a referenceID to scope search to one document.
• ls and find do not use path.

Doc-level operations

ls — list documents

{ "op": "ls" }

Returns an array of parsed documents with metadata:

[
  {
    "referenceID": "my-doc-001",
    "transformationID": "tr_abc123",
    "functionName": "doc-parser",
    "parsedAt": "2025-01-15T10:30:00Z",
    "pageCount": 23,
    "sectionCount": 254,
    "entityCount": 66,
    "previewEntities": ["Acme Corp", "John Smith"]
  }
]

Filter by function name or referenceID substring:

{ "op": "ls", "filter": { "search": "invoice", "functionName": "doc-parser" } }

grep — search documents

{ "op": "grep", "pattern": "holiday", "scope": "sections" }

Returns matching sections with page numbers and text snippets:

[
  {
    "referenceID": "my-doc-001",
    "page": 7,
    "sectionLabel": "Article 8 Header",
    "snippet": "ARTICLE 8 - HOLIDAYS",
    "scope": "section"
  }
]

Scope to one document with path:

{
  "op": "grep",
  "path": "my-doc-001",
  "pattern": "holiday",
  "scope": "sections"
}

Count only (no snippets):

{ "op": "grep", "pattern": "holiday", "countOnly": true }

scope values: "sections", "entities", "relationships", "all" (default).

cat — read a document

{ "op": "cat", "path": "my-doc-001", "range": { "page": 7 } }

Returns the document's parsed content — sections, entities, and relationships.

range is an object with optional keys:

{"op": "cat", "path": "my-doc-001", "range": {"page": 7}}
{"op": "cat", "path": "my-doc-001", "range": {"pageRange": [5, 10]}}
{"op": "cat", "path": "my-doc-001", "range": {"sectionTypes": ["table", "heading"]}}

select projects to specific fields (an array of strings):

{
  "op": "cat",
  "path": "my-doc-001",
  "select": ["sections.label", "sections.page", "sections.type"]
}

Without range or select, returns the entire document. Use range to keep responses small.

head — preview first sections

{ "op": "head", "path": "my-doc-001", "n": 10 }

Returns {"sections": [{content, label, page, type}, ...]} for the first N sections. Default N is 10.

stat — document or entity metadata

{ "op": "stat", "path": "my-doc-001" }

Returns {kind, path, referenceID, pageCount, sectionCount, entityCount, parsedAt}.

Also works for entities:

{ "op": "stat", "path": "ent_abc123" }

Entity memory operations

These require linkAcrossDocuments: true on the parse function. Without it, they return empty data with a hint explaining how to enable it.

Workflow: call find first to discover entities and their IDs, then pass an entityID as path to open or xref.

See also: these ops walk entities one at a time. To read the entity graph in bulk — every relation for an entity, or a whole slice of nodes and edges — use the Knowledge Graph API.

find — list entities

{"op": "find"}
{"op": "find", "filter": {"type": "person"}}
{"op": "find", "filter": {"search": "ryder"}}

Returns [{entityID, canonical, type, description, mentionCount, surfaceForms}].

open — entity detail + mentions

{ "op": "open", "path": "ent_abc123" }

path must be an entityID from find (not an entity name). Returns the entity record plus every mention across documents.

xref — cross-document sections for an entity

{ "op": "xref", "path": "ent_abc123" }

Returns the actual section text from every document that mentions this entity — the "where exactly is X discussed?" query in one call.

[
  {
    "referenceID": "my-doc-001",
    "page": 20,
    "sectionLabel": "Signatures",
    "sectionContent": "Signed this 7th day of September 2024...",
    "surface": "TEAMSTERS LOCAL 222"
  }
]

Pagination

ls and find paginate by cursor. Pass the nextCursor from one response as cursor in the next request. hasMore: false means last page.

{ "op": "ls", "cursor": "tr_abc123", "limit": 10 }