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?}.

Doc-level ops (work on every parsed document)

ls: list parsed documents with pageCount, sectionCount, entityCount, and a short previewEntities array.
cat: read one doc's full parse JSON, optionally sliced by range (page / pageRange / sectionTypes) or projected by select (dotted paths like ["sections.label", "sections.page"]).
head: first N sections of one doc.
grep: substring or regex search across recent parse outputs. scope restricts to sections / entities / relationships. path scopes to one doc. countOnly: true returns only the hit count.
stat: metadata only — page/section/entity counts, timestamps.

Memory-level ops (require `linkAcrossDocuments: true` on the parse function)

find: list canonical entities, filterable by type, search, since. Returns an empty list with a hint when no docs have been memory-linked.
open: fetch one entity plus its mentions across docs.
xref: for one entity, return the actual sections (with content) across docs that mention it. The "where exactly is X discussed" loop in one round trip.

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"
}