Storage
storageRead-only
Fastio files and folders in workspaces and shares (read): list, recent, search, details, trash, versions, locks, previews, content reads, and per-node metadata. FILES OFTEN ALREADY CARRY AI-EXTRACTED METADATA, AND IT IS SEARCHABLE: it frequently answers the question without opening anything, and finds files by value without listing folders. Writes are on storage_manage. action='describe' gives the full reference.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | list/search: alias for `query`. content: the relevance query (1-512 chars) — BM25 over THAT ONE FILE's chunks, never across the workspace, so it cannot find another file; returns every one of the top `limit` hits (default 3, max 20) with FULL text, is not byte-budgeted, and cannot be combined with `cursor`, `max_bytes`, or a page/chunk window. | |
| page | No | content: read one page (1-based). A window selector. | |
| size | No | Size preset: "IconSmall", "IconMedium", "Preview", or custom. | |
| type | No | Filter by node type. | |
| limit | No | Max results — 1-500, default 100 on list/search. content NARROWS it to 1-20, default 5 (3 with q); a value outside 1-20 is refused before any platform call. | |
| query | No | Search query — keyword, or keyword + semantic when Deep Indexing is on. | |
| width | No | Target width in pixels. | |
| action | Yes | Operation. Use 'describe' for full action reference. | |
| cursor | No | Opaque cursor from a previous response. | |
| detail | No | Per-node verbosity for list/recent/search/trash-list/details. Defaults: terse for list/recent/trash-list, STANDARD for search (terse drops fact values), full for details. Bump to full when you need ai.attach (files_attach preflight), virus, hashes, file_attributes, lock_info, or long-form summaries. See action='describe' for per-level field lists. Not to be confused with `details` (search-only). | |
| height | No | Target height in pixels. | |
| offset | No | Results to skip (default 0). | |
| output | No | content-only response tier (default full). terse OMITS each chunk's `text` — every other field still comes back, so it is the cheap way to map a file's chunks before reading any. Not `detail`, the per-node tier on list/recent/search/details. EXACTLY ONE tier: markdown composition is NOT supported here, so `full,markdown` is rejected before the request is built. | |
| details | No | Search-only: attach the hydrated node to each hit (default limit drops to 10). Distinct from `detail` (see describe). | |
| node_id | No | Storage node opaque ID (files and folders are both nodes), or 'root'. On `list`, the target folder may also be given as parent_node_id or parent_id (aliases), and defaults to 'root' (the storage top level) when all three are omitted. | |
| sort_by | No | Sort column (default: name). | |
| chunk_to | No | content: last chunk `position` of a chunk range (0-based, >= chunk_from, and under 10000). Requires chunk_from. | |
| max_size | No | Max read-content bytes (default 512000, max 1048576). | |
| node_ids | No | Storage node opaque IDs (details: 1-25 max). | |
| share_id | No | Alias for profile_id implying profile_type=share (dual-type actions). | |
| sort_dir | No | Sort direction (default: asc). | |
| max_bytes | No | content, ORDERED reads only: UTF-8 byte budget for the returned passages (1024-262144, default 32768). Text is never cut inside a chunk — the page stops BEFORE the chunk that would exceed the budget. Refused alongside q: a relevance read is unbudgeted. | |
| parent_id | No | Alias for node_id on `list` (the folder whose contents to list), or 'root'. `list` defaults to 'root' when omitted. | |
| search_in | No | filename | content | both (DEFAULT). filename = name only, find-style. content = the AI's summary + semantic, NOT grep. Sending it changes the response shape (adds a search_metadata block); omitting it reproduces today's behavior byte-for-byte. filename pairs with name_match. | |
| chunk_from | No | content: start of an inclusive chunk `position` range (0-based, a chunk's ordinal in read order, under 10000). LEGAL ALONE — it reads on from that position; chunk_from=N chunk_to=N reads one chunk in full. | |
| context_id | No | Alias for profile_id (either name works) | |
| name_match | No | auto (DEFAULT) | exact | prefix | contains | glob. exact = whole name; prefix = starts with; contains = substring — those three are LITERAL (* and ? are ordinary chars). glob = wildcards over the WHOLE name: *.pdf, report-*.xlsx. No pre-escaping needed. Applies when search_in is filename or both; auto keeps today's relevance. Precise modes cap the pattern at 256 chars, reject an empty one. | |
| profile_id | No | Workspace or share ID (19-digit, or custom name); pair with profile_type. Typed aliases imply the type: workspace_id (workspace), share_id (share, dual-type actions); also context_id / instance_id. | |
| as_markdown | No | Opt-in (list/recent/search/details/trash-list): the platform renders the response as GitHub-flavored Markdown (?output=<detail>,markdown) instead of JSON. Omit for JSON with web_url enrichment + _next hints. | |
| files_scope | No | Scope semantic search to file versions. See describe for full constraints. | |
| instance_id | No | Alias for profile_id (REST/how-to name; profile_id is canonical). | |
| context_type | No | Alias for profile_type (either name works) | |
| preview_type | No | Preview kind; each applies only to compatible file categories (see describe). | |
| profile_type | No | Profile type: "workspace" or "share". | |
| workspace_id | No | Alias for profile_id that implies profile_type=workspace. Valid on every action. | |
| display_limit | No | How many items to return (default 10, max 500) on list, recent and search. list/recent page via `cursor`; search pages via `offset` (increase it by the page size). | |
| folders_scope | No | Scope semantic search to folders via BFS. See describe for full constraints. | |
| output_format | No | Output format: "png", "jpg", "webp". | |
| case_sensitive | No | Case-sensitive matching for exact/prefix/contains/glob. Default false (like find -iname), which folds non-ASCII too. Ignored under name_match=auto. | |
| parent_node_id | No | Parent folder opaque ID, or 'root'. On `list`, an alias for node_id. | |
| transform_name | No | Transform name, e.g. "image" for resize/crop/format. | |
| describe_action | No | With action='describe': return one action's params and notes instead of the action index. | |
| metadata_filters | No | search: JSON array of metadata predicates, e.g. '[{"field":"category","operator":"=","value":"Legal"}]'. Narrows to files whose metadata satisfies EVERY predicate BEFORE the query ranks — see describe. |