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.

Authorization

API Key

x-api-key<token>

Authenticate using API Key in request header

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

op*string

The operation to run. Required.

path?string

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.

pattern?string

Substring or regex pattern for op=grep.

regex?boolean

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

ignoreCase?boolean

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

scope?string

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

countOnly?boolean

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

filter?

Narrows results for op=ls and op=find.

range?

Slices the parse output for op=cat.

select?array<>

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.

n?integer

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

limit?integer

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

cursor?string

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

Response Body

`application/json`

curl -X POST "https://api.bem.ai/v3/fs" \  -H "Content-Type: application/json" \  -d '{    "op": "ls"  }'

{
  "op": "ls",
  "data": null,
  "hasMore": true,
  "nextCursor": "string",
  "count": 0,
  "hint": "string"
}