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.

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}