v36

OpenAPI 3.1.0raw.githubusercontent.com2026-08-0187270483.0 KB

File System

File System Operations

Navigate parsed documents and the cross-doc memory store via Unix-shell verbs.

POST /v3/fs is a single op-driven endpoint that lets an LLM agent (or any programmatic client) walk a corpus the way it would walk a filesystem — ls to list, cat to read, grep to search, head for a quick peek, stat for metadata, and find / open / xref for the cross-doc entity memory layer.

The body always carries an op field; other fields apply per op. The response envelope is uniform: {op, data, hasMore?, nextCursor?, count?, hint?}.

Quick reference

Op	path	Other fields	What it does
ls	—	filter, limit, cursor	List parsed documents
grep	referenceID (optional)	pattern, scope, countOnly	Search across documents
cat	referenceID	range, select	Read a document's parsed content
head	referenceID	n	First N sections (default 10)
stat	referenceID or entityID	—	Metadata only
find	—	filter, limit, cursor	List canonical entities
open	entityID	—	Entity detail + all mentions
xref	entityID	limit, cursor	Sections across docs mentioning an entity

path is the positional identifier. For doc ops (cat, head, stat), pass a referenceID from ls. For entity ops (open, xref), pass an entityID from find. grep optionally takes a path to scope search to one document.

Examples

List documents: {"op": "ls"}

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

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

Read a page range: {"op": "cat", "path": "my-doc-001", "range": {"pageRange": [5, 10]}}

Project section labels and pages only: {"op": "cat", "path": "my-doc-001", "select": ["sections.label", "sections.page", "sections.type"]}

Preview first 5 sections: {"op": "head", "path": "my-doc-001", "n": 5}

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

List entities: {"op": "find"}

Entity detail + mentions: {"op": "open", "path": "ent_abc123"}

Cross-document sections for an entity: {"op": "xref", "path": "ent_abc123"}

Key details

range is an object with optional keys: page (integer), pageRange (two-element array [from, to]), sectionTypes (array of strings like ["table", "heading"]).

select is an array of strings — dotted paths like ["sections.label", "sections.page"].

scope (grep) is one of "sections", "entities", "relationships", or "all" (default).

Pagination

List ops (ls, find) paginate by cursor: pass the last item's nextCursor from a previous response to fetch the next page; hasMore: false signals the last page. Same idiom as /v3/calls and /v3/outputs.

post/v3/fs

Request body

Operations exposed by POST /v3/fs.

The verbs and their flag names mirror Unix tools so an LLM agent's existing vocabulary maps directly:

ls — list parsed documents
cat — read one parsed doc (optionally sliced by range / projected by select)
grep — substring or regex search across parse outputs
head — first N sections of one doc
stat — metadata only (page count, section count, parsed at, ...)
find — list canonical entities (cross-doc memory)
open — entity + mentions
xref — entity → sections across docs that mention it

Doc-level ops (ls, cat, grep, head, stat) work on every parsed document, regardless of how the parse function was configured.

Memory-level ops (find, open, xref) operate on the global entities table which is only populated when the parse function had linkAcrossDocuments: true. On environments with no memory-linked docs they return empty data with a hint pointing at the toggle.

pathstring

Identifier for ops that operate on a single resource:

cat / head / stat: a parsed document, by referenceID or transformationID.
open / xref / stat: an entity, by entityID.

patternstring

Substring or regex pattern for op=grep.

regexboolean

When true, pattern is interpreted as a Go regex. Default false.

ignoreCaseboolean

When true (default), substring/regex matching is case-insensitive.

scopestring

Restricts grep to one part of the parse output. One of "sections", "entities", "relationships", "all" (default).

countOnlyboolean

When true, return only the hit count without snippet payload. Cheaper than fetching matches when the agent only wants a yes/no.

selectstring[]

Project the parse output to specific dotted paths (e.g. ["sections.label", "sections.page"]), letting an agent map a doc's structure cheaply before reading content. Used with op=cat.

ninteger

First-N count for op=head. Defaults to 10.

limitinteger

Maximum results to return. Defaults vary per op (25–50).

cursorstring

Pagination cursor. Pass the last item's ID from a previous response (nextCursor) to fetch the next page.

Response

The request has succeeded.

Operations exposed by POST /v3/fs.

The verbs and their flag names mirror Unix tools so an LLM agent's existing vocabulary maps directly:

ls — list parsed documents
cat — read one parsed doc (optionally sliced by range / projected by select)
grep — substring or regex search across parse outputs
head — first N sections of one doc
stat — metadata only (page count, section count, parsed at, ...)
find — list canonical entities (cross-doc memory)
open — entity + mentions
xref — entity → sections across docs that mention it

Doc-level ops (ls, cat, grep, head, stat) work on every parsed document, regardless of how the parse function was configured.

{"stackTrail":"components:schemas:FSResponse:properties:data","oasType":"schema","type":"unknown","description":"Op-specific payload. See per-op shapes below."}

hasMoreboolean

True when more pages exist for cursor-paginated ops.

nextCursorstring

Cursor to pass as cursor in the next request to fetch the next page. Empty when hasMore=false.

countinteger

Set for ops that return a count rather than a list (grep with countOnly=true) or as a sanity check on lists.

hintstring

Optional human-readable note. Surfaced on memory-level ops (find / open / xref) when the corpus has no memory-linked docs, pointing users at the linkAcrossDocuments toggle on the parse function.