Read
List the immediate children of a directory in the workspace filesystem.
- path: directory to list (default "/", the workspace root). Also accepts a file path, which returns that file's entry.
- Output: directories first (with a trailing "/"), then files with their text sizes.
- Directory names map the topics: ls "/" first to learn the layout, then ls into the directory most related to the question — it often names the exact file you need.
- Shows at most 1,000 entries; if truncated, use find with a pattern to narrow.
Authorization
bearerAuth HTTP bearer credential in the Authorization header. Two planes share the
scheme, distinguished by prefix:
grp_sk_…— a management key: full control of the account (workspaces, files, token minting, audit export) plus the read tools.grp_at_…— a scoped read-only token: minted per workspace, it may call only the read tools (ls/find/cat/grep) and is rejected by every management route.
In: header
Path Parameters
Workspace name. Workspace name must be 1-64 lowercase letters, digits, hyphens, or underscores, starting and ending with a letter or digit.
^[a-z0-9](?:[a-z0-9_-]{0,62}[a-z0-9])?$Query Parameters
Directory to list (default "/").
Response Body
text/plain
text/plain
text/plain
text/plain
text/plain
curl -X GET "https://example.com/v1/workspaces/string/ls""string"Find files by glob pattern over workspace file paths.
- pattern: a glob like "/*.md" or "reports//q3*". A bare name matches literally and exactly — for a substring match use "**/name".
- path: optional directory to search under (default "/"); the pattern is matched relative to it.
- head_limit: max results (default 100, up to 1,000).
- Output: one "/"-prefixed path per line, most recently updated first. Use ls to explore directory structure instead of guessing patterns.
Authorization
bearerAuth HTTP bearer credential in the Authorization header. Two planes share the
scheme, distinguished by prefix:
grp_sk_…— a management key: full control of the account (workspaces, files, token minting, audit export) plus the read tools.grp_at_…— a scoped read-only token: minted per workspace, it may call only the read tools (ls/find/cat/grep) and is rejected by every management route.
In: header
Path Parameters
Workspace name. Workspace name must be 1-64 lowercase letters, digits, hyphens, or underscores, starting and ending with a letter or digit.
^[a-z0-9](?:[a-z0-9_-]{0,62}[a-z0-9])?$Query Parameters
Glob over file paths, e.g. **/*.md.
1 <= lengthDirectory to search under (default "/").
Max results (default 100, up to 1000).
1 <= value <= 1000Response Body
text/plain
text/plain
text/plain
text/plain
text/plain
curl -X GET "https://example.com/v1/workspaces/string/find?pattern=string""string"Read a file's text content with line numbers (like cat -n).
- path: the file to read.
- offset: 1-based line to start from (default 1). limit: max lines to return (default 2,000).
- Line numbers compose with grep output: grep shows "path:512:…", so cat(path, offset=500) reads around that match.
- Large responses are truncated with a footer telling you the offset to continue from; very long lines are cut with a marker. Binary originals (like PDFs) are served as their extracted text.
Authorization
bearerAuth HTTP bearer credential in the Authorization header. Two planes share the
scheme, distinguished by prefix:
grp_sk_…— a management key: full control of the account (workspaces, files, token minting, audit export) plus the read tools.grp_at_…— a scoped read-only token: minted per workspace, it may call only the read tools (ls/find/cat/grep) and is rejected by every management route.
In: header
Path Parameters
Workspace name. Workspace name must be 1-64 lowercase letters, digits, hyphens, or underscores, starting and ending with a letter or digit.
^[a-z0-9](?:[a-z0-9_-]{0,62}[a-z0-9])?$Query Parameters
File to read.
1 <= length1-based line to start from (default 1).
1 <= value <= 9007199254740991Max lines to return (default 2000).
1 <= value <= 9007199254740991Response Body
text/plain
text/plain
text/plain
text/plain
text/plain
curl -X GET "https://example.com/v1/workspaces/string/cat?path=string""string"Search file contents with a regular expression.
- pattern: an RE2 regex. Backreferences and lookaround are not supported (same family as ripgrep); everything else — literals, classes, alternation, quantifiers, anchors — works.
- The documents rarely use your question's wording. Search short stems and domain synonyms, not question phrases: for "how fast do they stop" grep "halt|brake|stop", not "how fast". One or two words per attempt beats a long phrase.
- path: optional directory to search under. glob: optional filename filter like "*.md".
- output_mode: "files_with_matches" (default — matching file paths, densest first; start here to find the right FILE, then cat it) or "content" (matching lines as "path:line:text", with -A/-B/-C context — raw matches can include boilerplate from unrelated files) or "count" (matches per file).
- -i: case-insensitive — use it by default. head_limit: cap the output.
- Zero matches? Reword and try again — synonyms, a shorter stem, no glob. Several cheap greps with different wordings beat one perfect pattern.
Authorization
bearerAuth HTTP bearer credential in the Authorization header. Two planes share the
scheme, distinguished by prefix:
grp_sk_…— a management key: full control of the account (workspaces, files, token minting, audit export) plus the read tools.grp_at_…— a scoped read-only token: minted per workspace, it may call only the read tools (ls/find/cat/grep) and is rejected by every management route.
In: header
Path Parameters
Workspace name. Workspace name must be 1-64 lowercase letters, digits, hyphens, or underscores, starting and ending with a letter or digit.
^[a-z0-9](?:[a-z0-9_-]{0,62}[a-z0-9])?$Query Parameters
An RE2 regular expression.
1 <= lengthDirectory to search under.
Filename filter, e.g. *.md.
files_with_matches (default), content, or count.
"files_with_matches"Value in
- "files_with_matches"
- "content"
- "count"
Case-insensitive.
Lines of context after each match.
0 <= value <= 9007199254740991Lines of context before each match.
0 <= value <= 9007199254740991Lines of context around each match.
0 <= value <= 9007199254740991Cap the number of output lines.
1 <= value <= 9007199254740991Response Body
text/plain
text/plain
text/plain
text/plain
text/plain
curl -X GET "https://example.com/v1/workspaces/string/grep?pattern=string""string"