storage
Destructive
Files & folders on workspaces/shares: list, search, copy, move, delete, rename, trash, transfer, versions, locks, previews, and per-node metadata (get/set/delete/extract/versions). FILES OFTEN ALREADY CARRY AI-EXTRACTED METADATA, AND IT IS SEARCHABLE — check or search metadata before reading files: it frequently answers the question without opening anything, and finds files by value without listing folders. Call action='describe' for the full action/param reference. Destructive: purge (irreversible). delete moves to trash. metadata-delete removes metadata keys. Verbosity (detail param): list/recent/trash-list default to terse (compact rows); search defaults to standard (rows keep their facts values); details defaults to full (drill-down). Pass an explicit detail to override.
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. | |
| keys | No | metadata-delete: JSON array of metadata keys to delete (omit to clear all). | |
| name | No | Name for new folder or file. | |
| 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 intelligence 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. Return fully-hydrated node objects per result (default limit drops to 10). Distinct from `detail` — call action='describe' for the contrast. | |
| node_id | No | Storage tree node opaque ID. Both files and folders are nodes — use this name regardless of which. Storage node opaque ID, 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. | |
| duration | No | lock-acquire only — how long the lock should hold, in seconds (60-3600). Omit for the platform default, which is SHORT: measured at 300s (5 minutes) on dev1. | |
| max_size | No | Max read-content bytes (default 512000, max 1048576). | |
| new_name | No | New name for file or folder. | |
| node_ids | No | Storage node opaque IDs (details: 1-25 max). | |
| share_id | No | For add-link: the target share to link (workspace-only). For the dual-type actions (list/details/copy/move/etc.): a profile alias implying profile_type=share — the share you are operating in (so profile_type may be omitted). | |
| 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. | |
| node_type | No | rename-only OPTIONAL hint: the node's type, when the caller already knows it. Notes route to a dedicated endpoint, so supplying node_type lets rename skip the /details/ type-probe round-trip. Omit to have rename probe automatically. Distinct from the list/recent `type` filter. | |
| 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. OMIT unless you mean it — sending it changes the response shape (adds a search_metadata block); omitting reproduces today's behavior byte-for-byte. Pair filename with name_match. | |
| upload_id | No | Opaque ID of completed upload session. | |
| 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) | |
| key_values | No | metadata-set: JSON object of field-name -> value, max 100 entries, matching the workspace field VOCABULARY (list names with `metadata action=fields-list`) — NOT template fields; templates were removed. ADDITIVE: send ONLY the fields you are changing, and note it CANNOT clear a field (use metadata-delete with an explicit `keys` list). | |
| lock_token | No | lock-release only — the token returned by lock-acquire. REQUIRED to release a lock. | |
| 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. Do NOT pre-escape. 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 | Polymorphic context ID (pair with profile_type=workspace|share). Typed aliases let you omit profile_type: workspace_id (⇒ workspace) / share_id (⇒ share, on dual-type actions); also context_id / instance_id. 19-digit workspace or share ID, or custom name. | |
| version_id | No | Version ID to restore. | |
| as_markdown | No | Opt-in (list/recent/search/details/trash-list): when true, the platform renders the response as GitHub-flavored Markdown (?output=<detail>,markdown) for compact, human/agent-readable output instead of JSON. Omit (default) for the unchanged JSON shape with web_url enrichment + _next hints. Markdown is a passthrough — no client-side reshaping. | |
| 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). | |
| template_id | No | RETIRED — metadata templates were removed, so there is no template to scope to. Supplying it FAILS the request: the platform hard-refuses it on metadata-extract, metadata-set and the search routes alike, and OPTIONS does not advertise it. Node metadata is written as facts against the workspace field vocabulary — use key_values to write, and extract_fields to scope an extraction. | |
| context_type | No | Alias for profile_type (either name works) | |
| preview_type | No | Type of preview to generate. See describe for which preview_types apply to which file categories. | |
| profile_type | No | Profile type: "workspace" or "share". | |
| workspace_id | No | Alias for profile_id when the profile is a workspace — implies profile_type=workspace (so profile_type may be omitted). Valid on every storage action. | |
| display_limit | No | How many items to return. Default 10, max 500. The MCP trims post-fetch; backend cache stays warm. Used by: list, recent, search. list/recent paginate via the `cursor` param; search paginates via `offset` (increase offset by the page size) for additional pages. | |
| folders_scope | No | Scope semantic search to folders via BFS. See describe for full constraints. | |
| output_format | No | Output format: "png", "jpg", "webp". | |
| transfer_mode | No | 'copy' (default) or 'move'. 'move' invalid for node_id 'root'. | |
| 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. | |
| dest_parent_id | No | Destination parent folder opaque ID, or 'root'. Primary param for transfer (the parent in the OTHER instance). For copy/move within the same instance use target_parent_id — dest_parent_id is also accepted there as an alias. | |
| extract_fields | No | metadata-extract: JSON array of field names (e.g. `["vendor","amount"]`); omit for a full-row extract. WITH a template bound it narrows extraction to those fields. WITHOUT one it is NOT a filter: the request may be REFUSED, and where accepted the names act only as a re-run key — the file is still read in full, other fields are still written, and named fields are not guaranteed to return. | |
| parent_node_id | No | Parent folder opaque ID, or 'root'. (On `list`, also accepted as an alias for node_id — the folder to list; `list` defaults to 'root' when omitted.) | |
| transform_name | No | Transform name, e.g. "image" for resize/crop/format. | |
| describe_action | No | When action='describe', narrow the output to ONE action's full params/notes (e.g. 'list'). Omit to get the compact action index. | |
| dest_instance_id | No | Destination workspace or share profile ID. | |
| 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. | |
| target_parent_id | No | Destination folder opaque ID, or 'root'. |