Storage Operations File and folder operations, locking, previews, and transforms

Storage endpoints are available on both workspaces and shares. The API patterns are identical — replace workspace/{workspace_id} with share/{share_id} in any path below unless noted as workspace-only or share-only.

All endpoints require JWT authentication unless otherwise noted. Include the header Authorization: Bearer {jwt_token} with every request.

Conventions

• Root folder: Use the literal string "root" as the path parameter (e.g., /storage/root/list/)
• Trash folder: Use "trash" to list trashed items (e.g., /storage/trash/list/)
• Node IDs: OpaqueIds — 29-character alphanumeric strings displayed with hyphens (e.g., 2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4). Use as-is in API calls.
• Node ID prefixes: f = file, d = folder, n = note
• Name length: File, folder, and note names are 1–255 characters. Every endpoint that creates or renames a node by name enforces this range and rejects a longer name with 1605 (Invalid Input). The count is characters, not bytes, so an accented, CJK, or emoji character each counts as one.
• Node types in responses: "file", "folder", "note", "link" (lowercase strings)
• Parent field: Nodes at the storage root have "parent": "root"; nested nodes show the parent's OpaqueId
• Delete vs purge: DELETE .../storage/{node_id}/delete/ moves to trash. DELETE .../storage/trash/delete/ empties the entire trash. DELETE .../storage/{node_id}/purge/ permanently deletes a single trashed item.
• Workspace folder shares: Shares that reference a workspace folder have their root mapped to the designated folder. All operations are scoped to that subtree.
• Compact responses: Every storage endpoint that returns nodes (list, details, search, metadata, trash, quickshares) accepts an optional ?output=<token> query parameter with three detail levels: terse, standard, or full. See the "Compact Responses" section below for the full contract, field lists, and the HTTP 406 rule for multi-level combinations. (QuickShare creation is deprecated — use the durable File Share instead.)
• Reading the error tables: the four-digit 16xx/17xx values below are HTTP-status classes, not error.code. The error.code a client actually receives is assigned per endpoint, so use the HTTP status as the gate and a documented error.code — five or six digits, plus the 9661-9669 family — only as a refinement. A 16xx value identifies the status class — useful for telling which kind of failure occurred — but comparing one against error.code will never match. Five- and six-digit codes (and the 9661-9669 family) are real error.code values. If you widen a check from a specific code to a status, widen what you assert with it — a status covers failures the narrower code did not, so a message written for that one code becomes a confident falsehood on the rest.

Compact Responses (output=)

Every storage endpoint that returns node objects — folder listings, node details, search hits, metadata endpoints, trash listings, and quickshares — accepts an optional output query parameter that selects the shape of each node in the response. A single detail-level token may be combined with modifier tokens; specifying two detail levels (e.g. ?output=terse,standard) returns HTTP 406. When output= is omitted, responses are full and byte-for-byte unchanged.

A tier is a CEILING, not a guarantee — read every row above as "at most these fields". A key is present only when the node actually has it, so the same tier returns a different key set for a file, a folder, and a link. File/note-only: mimetype, size, summary, previews, metadata_facts, mimecategory, ai, metadata, hash, hash_algo, file_attributes. Folder-only: is_share_root, share_id, recursive nodes. Link-only: target_type, target_id. Trashed-only: deleted, deleted_from. The gap is large — at full, a file returns 27 keys and a folder 17 — so treat a missing key as "not applicable to this node type", never as a null value or an error, and never infer a node's state from a key's absence.

Use terse for list rows, tree rendering, pickers, breadcrumb navigation, and drag-and-drop targets — it carries modified (so list rows can render the date column and "sort by modified" without a follow-up fetch), a per-type previews readiness map (so the thumbnail selector can pick the best available source), and the summary title. Use standard for most detail views, file-browser main lists, and any UI that shows AI-processing state, lock/restricted chips, DMCA chips, import-provider chips, or trash state — it adds the ai.state that drives the "summarizing…" spinner, timestamps, origin creator plus type, the dmca flag for DMCA chip rendering, is_imported for import-provider chips, link-node target_type/target_id discriminators, and the metadata.title/metadata.short user overrides that list rows render when a custom title is set. Use full (or omit the parameter) for the node detail pane, virus/AI inspection, version history, and any workflow that reads long-form summaries, EXIF, import provider metadata, or content hashes. Unknown tokens are silently ignored. Add the markdown modifier (e.g. ?output=standard,markdown) to receive the response as GitHub-flavored Markdown (Content-Type: text/markdown; charset=UTF-8) instead of JSON — see the cross-cutting ?output= reference for the full contract.

Node Object Schema

All endpoints that return node data use this format. Fields vary by node type.

Embedded File Metadata (file_attributes)

file_attributes carries metadata read out of the file's own bytes: exif_metadata (camera and lens details, device make and model, authoring software, author and copyright text) and media_metadata (container, codec, and per-stream details). Because that content comes from inside the file, it is returned only to callers who are permitted to download the file.

• When the caller may view a file but not download it, the exif_metadata and media_metadata keys are omitted, so file_attributes comes back as an empty object {}. It is never null, no error is raised, and no other field changes.
• Everything else reported about a file — size, hash, hash_algo, mimetype, mimecategory, created, modified, origin, previews, virus, ai, and the AI summary — is derived by the platform rather than read from the file, and is returned regardless of download rights.
• Workspace responses are unaffected. Workspace members always have download rights, so workspace endpoints return file_attributes exactly as before.
• On a share, the gate follows the share's file download permission: a share whose downloads are turned off (and receive-share guests, who are upload-only) get {}. Members and administrators always download, so they always receive it.
• On a File Share link, the gate follows the link's effective_capability: view alone gets {}; download and edit receive the metadata.

Extracted Metadata Facts (metadata_facts)

metadata_facts carries the extracted metadata facts recorded for a file: the field-and-value pairs the extraction pipeline produced against the workspace's field vocabulary. It is returned on file and note nodes at all three ?output= levels, in a different shape at each level, and every shape carries count — how many facts this payload carries, not how many the node holds — total — how many the node holds, counted before any cap — and is_truncated. Folder and link nodes never carry it, and the lightweight recent-files listing does not include it.

If you send no output parameter you get full — on node listings and on node details alike. There is one global default and no endpoint overrides it, so the two cannot diverge: a node arriving from a folder listing carries the same complete fact records as the same node fetched directly. The lean and projected shapes below are reachable only by asking for them explicitly.

full — up to 100 facts as complete records: field, value, declared_type, stored_type, source (one of ai, user, exif, mediainfo, validated_server), confidence (low, medium, high, certain, or null), rationale (a string or null), and updated (YYYY-MM-DD HH:MM:SS UTC). A fact is identified by its field name — no id of any kind is returned.

"metadata_facts": {
  "count": 2,
  "total": 2,
  "is_truncated": false,
  "items": [
    {
      "field": "invoice_number",
      "value": "INV-1042",
      "declared_type": "string",
      "stored_type": "string",
      "source": "ai",
      "confidence": "high",
      "rationale": "Read from the header block on page 1",
      "updated": "2026-08-20 14:02:11 UTC"
    },
    {
      "field": "amount_due",
      "value": 4820.5,
      "declared_type": "float",
      "stored_type": "float",
      "source": "ai",
      "confidence": "certain",
      "rationale": null,
      "updated": "2026-08-20 14:02:11 UTC"
    }
  ]
}

standard — up to 8 facts carrying field, an abbreviated value, and a value_truncated boolean, with no provenance. The 8 are chosen in a fixed priority order — typed values first (numbers, dates, booleans), then identifier fields (names ending _number, _id, _code, _reference), then everything else, alphabetical by field name within each group — so a monetary or date fact is never cut in favour of an address or contact string. value_truncated is always present at this level. A string value longer than 64 characters is cut to 64 characters with … appended and value_truncated is true; a complete string, number, boolean or null value is returned unchanged with value_truncated: false. A json-typed list value is returned as a real array (no longer rendered as a JSON string): the array is whole, with value_truncated: false, when its JSON encoding is 64 characters or shorter — counted on the value’s own characters, with unicode and / counted unescaped rather than on an escaped-for-transmission byte form — and otherwise holds the longest leading run of elements whose encoding fits that same budget (at least one element) with value_truncated: true — elements present are exact, except that when the first element alone does not fit, it is cut so the one-element array’s own encoding fits the 64-character budget — the kept text comes out shorter than 64 characters (for example 59 plus … for a plain string) — cutting the string itself for a string element or the element’s JSON encoding for any other type, whatever the element’s own type (a number, boolean, null, nested object or array all reduce to that same cut string). A json-typed object value is returned as the structure itself when its encoding is 64 characters or shorter by the same measure, and otherwise as a cut JSON preview string with value_truncated: true. Use full when you need the exact value or its type. Never paste a value_truncated: true value into a metadata_filters equality predicate — it cannot match; call full (or the node facts endpoint) for the complete value. The same key name reappears elsewhere under a different rule: results[].matched_fields[].value_truncated under Metadata Search below cuts to a window taken around the matched text, with no ellipsis appended — do not apply one “strip the ellipsis” handler to both fields. Because each tier caps independently, count is not comparable across tiers for the same node: a node holding 9 facts can report "count": 9, "is_truncated": false at terse (under its 20-name cap) and "count": 8, "is_truncated": true at standard (capped at 8) for the identical set of facts — both are correct, and is_truncated signals that more facts exist beyond what was returned. total IS comparable across tiers, because it counts what the node holds rather than what the tier emitted: the same node reports "total": 9 at both levels. Compare totals across tiers, never counts.

"metadata_facts": {
  "count": 8,
  "total": 14,
  "is_truncated": true,
  "items": [
    {"field": "abstract", "value": "This master services agreement between Northwind and Con…", "value_truncated": true},
    {"field": "amount_due", "value": 4820.5, "value_truncated": false}
  ]
}

terse — up to 20 field names and no values at all, as one comma-separated string under a fields key (fields, not items), in the same priority order as standard (typed values, then identifiers, then the rest; alphabetical within each group). Splitting that string on , is safe: a field name may contain only letters, digits, spaces, underscores and hyphens (Unicode-aware, so accented and non-Latin names are fine), so a comma can never appear inside a name. That charset is enforced wherever a name enters the vocabulary, including names an AI proposes during extraction. Which characters are allowed is a different question from which names are the SAME name: field names are compared case-, accent- and width-insensitively, so Category, category and catégory are ONE field, not three — the first spelling written owns the name and a later write in another spelling resolves to it.

"metadata_facts": {
  "count": 5,
  "total": 5,
  "is_truncated": false,
  "fields": "abstract, amount_due, contract_type, currency, invoice_number"
}

• is_truncated is present at every level and is true when the node holds more facts than were returned. To read the complete set, call the node facts endpoint — GET /current/workspace/{workspace_id}/storage/{node_id}/metadata/facts/ — which is not paginated and returns every fact on the node in one call.
• total is present at every level and is how many facts the node holds, counted before any cap. count is what this payload carries; total is what there was to carry; total is never less than count. Read the pair as “8 shown of 14” — that is what tells you whether re-reading the node at ?output=full is worth a second call, and when total equals count there is nothing more to fetch. The node facts endpoint's own wrapper does not carry it, and does not need to: that read is uncapped, so its count already is the total.
• An absent metadata_facts does not mean the file has no metadata. The key is omitted entirely — never null — when the caller is not entitled to extracted metadata, or when the facts could not be read for that request. A file that genuinely holds none returns "count": 0, "total": 0 with an empty items (or an empty fields string) instead.
• Extracted metadata is a WORKSPACE-ONLY surface, because both the values and the field names are the owning team's own data. Workspace members receive it. It is never returned in a share context, to any share role — not to share members, not to share administrators, not to share guests or public-link guests — and File Share link recipients never do. A workspace-folder share mirrors workspace nodes, and those nodes are covered by the same rule.

AI States

Keyset Pagination (Storage List)

Storage listing endpoints (list and recent) use cursor-based pagination, not offset-based.

Request Parameters

Response Pagination Fields

Notes:

• Cursors are HMAC-signed; tampered cursors are rejected with an error.
• When using a cursor, the page size from the cursor takes precedence over the request parameter.
• Results for the first page may be slightly delayed.
• The recent endpoint ignores sort_by and sort_dir (always sorted by updated descending).

List Folder Contents

Auth required. Permission: View (workspace), Guest+ (share). Share list on public shares may not require JWT.

Path Parameters

Query parameters: See Keyset Pagination section above.

curl Example

curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/root/list/?sort_by=name&sort_dir=asc&page_size=100" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": true,
  "nodes": {
    "count": 2,
    "items": [
      {
        "id": "2qk7d-kri4y-yievb-q5hri-eq4io-hij5",
        "type": "folder",
        "name": "Documents",
        "parent": "root",
        "created": "2025-01-01 00:00:00 UTC",
        "modified": "2025-01-20 14:45:00 UTC"
      },
      {
        "id": "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4",
        "type": "file",
        "name": "photo.jpg",
        "parent": "root",
        "size": 2048000,
        "mimetype": "image/jpeg",
        "created": "2025-01-10 09:00:00 UTC",
        "modified": "2025-01-10 09:00:00 UTC"
      }
    ]
  },
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJwIjoiMmFiYzEyMy4uLiIsInMi...",
    "page_size": 100
  }
}

Response Fields

Error Responses

Workspace Inventory

Enumerate every live node in a workspace or share — files, folders, notes and links — as one flat, paged list covering the whole tree. There is no folder scope and no recursion to drive: one walk returns everything. Trashed nodes are excluded.

This is the intended way to enumerate every live file. Listing the tree with /storage/{parent_id}/list/ costs one call per folder, and the number of folders cannot be known in advance. An inventory row is deliberately lightweight, so enumerating a whole workspace is much cheaper per file than listing folders — reach for this endpoint instead of walking the tree whenever you want “everything in this workspace”.

Rows are ordered by node id ascending and walked with a keyset cursor. Ordering by id is what makes the walk stable: renaming or editing a file between pages does not move it, so it is neither skipped nor served twice.

The cursor is the id of the last row you kept — not an opaque token. The comparison is strictly greater than, so that row is not repeated, and it is independent of type and page_size, both of which may change between pages. This is deliberate: a client that renders a page and truncates it stopped somewhere the server does not know, and an opaque cursor would make it skip every row it dropped.

Rows are terse by design. There is no output= parameter on this endpoint and it is not accepted. A caller that wants a file's full record already has its id — read it with /storage/{node_id}/details/.

Auth required. Permission: View (workspace), Guest+ (share). Share inventory on public shares may not require JWT.

Path Parameters

Query Parameters

curl Example

curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/inventory/?type=file" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": true,
  "nodes": {
    "count": 2,
    "items": [
      {
        "id": "2qk7d-kri4y-yievb-q5hri-eq4io-hij5",
        "type": "folder",
        "name": "Documents",
        "parent_id": "root",
        "size": null,
        "mimetype": null,
        "updated": "2025-01-20 14:45:00 UTC",
        "version": "3u6cr-vxmyl-4y2pr-5jboz-afoke-k4s5",
        "summary": null,
        "facts_total": null
      },
      {
        "id": "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4",
        "type": "file",
        "name": "Q4 Report.pdf",
        "parent_id": "2qk7d-kri4y-yievb-q5hri-eq4io-hij5",
        "size": 2048000,
        "mimetype": "application/pdf",
        "updated": "2025-01-10 09:00:00 UTC",
        "version": "3gzfc-3x7gt-4xsnm-qw52d-sjzcx-cuxa",
        "summary": { "title": "Q4 revenue and headcount summary" },
        "facts_total": 12
      }
    ]
  },
  "pagination": {
    "has_more": true,
    "next_cursor": "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4",
    "page_size": 100
  }
}

The envelope uses the same key names as List Folder Contents (nodes.count, nodes.items, pagination.*), so a client that already pages folder listings reuses its parser unchanged.

Response Fields

facts_total — absent, null and a number mean three different things. The field is gated on permission to read metadata facts, and facts never cross into a share, so it is emitted only for callers who may read them (workspace members) and the share twin never emits it at all. Read the three states separately:

• Absent — unknown, or not permitted for this caller. The key is also absent when the count is not available for this response. Treat it as unknown: never as 0, and never as “this file has no metadata”.
• null — the key is present and the file has never had metadata extracted. Folders and links are always null when the key is present; notes follow the same rule as files.
• A number — that many extracted metadata fields.

include=path — where each node lives. Add include=path and every row gains three more fields: path (string/null), ancestors (array of {id, name}), and path_complete (boolean). They have exactly the same meaning and shape as the fields of the same names on a storage-search hit — read the Folder paths subsection under Search for the full contract, including why path_complete is the field the other two are read through. include is the only way to get them here; an include token other than path is refused with 1605 (Invalid Input) / 406 rather than ignored, so a typo can never look like “the field is unavailable”.

Share twin. Inventory is available on independent-storage shares only. A share backed by a workspace folder refuses it with 1609 (Not Found) / 404 and the message “Inventory is not available for Shared Folders” — the same restriction the share storage search twin has. Enumerate such a share's contents through the backing workspace instead.

Error Responses

Node Details

Auth required. Permission: View (workspace), View (share).

Path Parameters

curl Example

curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4/details/" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": true,
  "format": "single",
  "node": {
    "id": "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4",
    "type": "file",
    "name": "document.pdf",
    "parent": "2qk7d-kri4y-yievb-q5hri-eq4io-hij5",
    "size": 5242880,
    "hash": "d41d8cd98f00b204e9800998ecf8427e",
    "hash_algo": "md5",
    "mimetype": "application/pdf",
    "mimecategory": "document",
    "version": "3u6cr-vxmyl-4y2pr-5jboz-afoke-k4s5",
    "created": "2025-01-15 10:30:00 UTC",
    "modified": "2025-01-20 14:45:00 UTC",
    "restricted": false,
    "dmca": false,
    "locked": false,
    "lock_info": null,
    "virus": { "status": "scanned", "infected": false },
    "file_attributes": { "width": null, "height": null, "duration": null },
    "summary": {
      "title": "Quarterly Report",
      "short": "Q4 financial summary",
      "long": "Comprehensive financial report covering revenue and expenses."
    },
    "metadata": null,
    "previews": {
      "thumbnail": { "state": "ready" },
      "pdf": { "state": "ready" }
    },
    "ai": { "state": "indexed", "attach": true },
    "origin": { "type": "upload", "creator": "9876543210987654321" }
  }
}

Response fields: See Node Object Schema above for complete field reference.

Error Responses

Bulk Form

The details endpoint accepts a comma-separated list of node ids in place of a single {node_id}:

GET /current/workspace/{workspace_id}/storage/{id1},{id2},{id3}/details/

Up to 25 ids per call. Duplicate ids are silently deduplicated. Empty segments (e.g. trailing comma) return 406. The bulk form is currently only available for the workspace path.

The bulk response shape differs from the single-id form. Successfully resolved nodes appear as an array under nodes; per-id failures appear in a parallel errors array. HTTP status is 200 when at least one node resolves and 404 when every requested id errored.

curl Example

curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/abc123,def456,ghi789/details/" \
  -H "Authorization: Bearer {jwt_token}"

Response (HTTP 200)

{
  "result": true,
  "format": "multi",
  "nodes": [
    { "id": "abc123", "type": "file", "name": "report.pdf" },
    { "id": "def456", "type": "folder", "name": "Documents" }
  ],
  "errors": [
    { "node_id": "ghi789", "code": 133123, "message": "No such file or folder exists" }
  ]
}

Every details response carries a top-level format field — "single" (single-id form, paired with a node object) or "multi" (bulk form, paired with nodes + errors arrays). Clients can branch on format instead of inferring shape from key presence.

Bulk Error Responses

Node Content

This is the same text the platform already extracted and indexed for search and AI. read/ hands back raw bytes and search returns only a snippet, so this is the route that lets a caller actually read a PDF's words.

The unit is a chunk, not a page. Text is chunked for retrieval, and a chunk can span two pages or split one, so page= returns the whole chunks that OVERLAP that page — never a page-shaped blob of text. Pages are known only for formats that carry them (documents that were paginated when they were converted); spreadsheets, plain text, code, and notes have no pages and are addressed by chunk_from/chunk_to instead. Read page_addressable before sending a page. Audio and video files are not served by this route today and answer indexed: false.

A chunk's address is its position. position is the chunk's 0-based place in the file's read order, and it is what chunk_from/chunk_to select on. chunk_index is the older name for that idea and is now nullable — newer text may not carry one — so address chunks by position and treat chunk_index as legacy. sequence is a different coordinate, assigned when the file's text was extracted: it rises through the file without being contiguous, is null on text extracted before it was assigned, and is published for correlation rather than addressing. chunk_from/chunk_to reach the first 10000 positions of a file; a position at or beyond 10000 cannot be addressed with them and is refused as an invalid window — keep walking a large file with cursor, which has no such limit.

Only the file's current version has text. indexed_version_id names the version the returned chunks were indexed from. A cursor walk is not a snapshot: a cursor is stamped with the version it was issued against, so if the file is replaced mid-walk, the next call with the old cursor returns an EMPTY chunks list with next_cursor: null. indexed_version_id shows the new version once its text is indexed, and is null while it is still being processed — restart from the beginning either way, rather than splicing old text onto new.

Auth required. Permission: View (workspace). The share path requires download permission, not view — extracted text is the interior of the file, so a guest who may not fetch the bytes may not read the text either.

Path Parameters

Query Parameters

All optional. At most one window selector (page, chunk_from/chunk_to, q); with none, the response starts at the beginning of the file.

curl Example

curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4/content/?page=2&limit=5" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": true,
  "node_id": "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4",
  "name": "Master Services Agreement.pdf",
  "mimetype": "application/pdf",
  "indexed": true,
  "complete": true,
  "indexed_version_id": "3u6cr-vxmyl-4y2pr-5jboz-afoke-k4s5",
  "page_addressable": true,
  "num_pages": 3,
  "total_chunks": 3,
  "chunks": [
    {"position": 0, "sequence": 0, "chunk_index": 0, "start_page": 1, "end_page": 1, "chars": 4000, "score": null, "text": "MASTER SERVICES AGREEMENT ..."},
    {"position": 1, "sequence": 12, "chunk_index": 1, "start_page": 1, "end_page": 2, "chars": 4309, "score": null, "text": "... 5. TERM AND TERMINATION ..."}
  ],
  "next_cursor": "",
  "truncated": false
}

Response Fields

Reading a whole file: call with no selector, then keep re-calling with cursor set to the previous next_cursor until next_cursor is null, concatenating text. Chunks are contiguous and in order; joining them with a newline between chunks reproduces the extracted text apart from the whitespace the splitter dropped at each boundary.

Ordered modes and the byte budget. In the ordered modes (no selector, page, chunk_from/chunk_to) the response stops BEFORE the chunk that would push it past max_bytes; text is never cut inside a chunk, and at least one chunk is always returned even when that one chunk is larger than the budget. truncated: true means matched chunks were withheld — not that a chunk's text was shortened — and next_cursor is the last chunk actually sent, so continuing from it loses nothing.

Relevance mode (q). q ranks this one file's chunks by keyword match (the terms are matched independently, so a natural-language question still returns the passage carrying the most of its words first). It returns the top limit chunks — default 3 — sorted by score descending, each with its FULL text: max_bytes is deliberately not applied, so a hit is never silently dropped. Use it to locate and quote a clause without walking the file; use the ordered modes to read the file through.

output=terse returns the same envelope and the same chunk list with text omitted — a chunk map of positions, page ranges and chars. The byte budget is not spent on a response that carries no text, so a terse page is never shortened.

A File With No Extracted Text

This is a normal 200, not an error:

{
  "result": true,
  "node_id": "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4",
  "name": "scan.jpg",
  "mimetype": "image/jpeg",
  "indexed": false,
  "complete": false,
  "indexed_version_id": null,
  "page_addressable": false,
  "num_pages": null,
  "total_chunks": 0,
  "chunks": [],
  "next_cursor": null,
  "truncated": false
}

indexed: false means this version has no text in the index — it may never have been processed, processing may still be queued, or the format may carry no extractable text. It never means the read failed: a failure to read the index is a 500, so indexed: false is always a statement about the file and never about the platform.

Error Responses

Multi-File Content Search

This is the relevance mode of the single-file route above, asked of up to ten files at once, so a caller assembling context for a prompt makes one request instead of ten. The chunk objects are identical to that route's, field for field, so the two can be mixed freely.

Note the shape of the path: the file ids travel in the nodes query parameter, not in the path, so this route sits beside search/ rather than under a {node_id}.

Each file is scored against itself. Every file is ranked only among its own chunks, and the scores are not comparable BETWEEN files — keyword relevance scores are only meaningful within one result set. Take the top chunks per file; do not merge the lists and re-sort them by score.

Auth required. Permission: View (workspace) — the same gate as the single-file route. Workspace only; there is no share form of this route.

Path Parameters

Query Parameters

There is no page, chunk_from/chunk_to or cursor here: those address a walk through ONE file, which the single-file route already serves. Follow a passage found here by calling that route with the position this one returned.

curl Example

curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/content/?nodes=2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4,2azz3-bexth-xvixb-cpq37-azkzx-xinq&q=retention%20policy&limit=3" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": true,
  "q": "retention policy",
  "limit": 3,
  "nodes": {
    "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4": {
      "name": "Master Services Agreement.pdf",
      "mimetype": "application/pdf",
      "indexed": true,
      "indexed_version_id": "3u6cr-vxmyl-4y2pr-5jboz-afoke-k4s5",
      "page_addressable": true,
      "num_pages": 6,
      "total_chunks": 12,
      "chunks": [
        {"position": 4, "sequence": 1005, "chunk_index": 4, "start_page": 3, "end_page": 4, "chars": 4102, "score": 7.25, "text": "... 9. RECORD RETENTION ..."}
      ],
      "truncated": false
    }
  },
  "missing": [
    {"id": "2azz3-bexth-xvixb-cpq37-azkzx-xinq", "reason": "trashed"}
  ]
}

Response Fields

complete and next_cursor are deliberately not published here — those describe a walk through ONE file, which this route does not do. Ask the single-file route when you need them.

A failure to read the text index is a 500, never an empty chunks list. An empty list always means those files hold nothing matching your query, and never that the platform could not look.

Error Responses

Add File from Upload

Auth required. Permission: Guest (workspace), file creation permission (share).

Path Parameters

Request Body (form-encoded)

from format:

Both workspace and share variants accept the same JSON shape. Two source types are supported: upload (a completed upload session) and hash (deduplicate against an existing object by content hash).

{"type": "upload", "upload": {"id": "{upload_id}"}}

{"type": "hash", "hash": {"hash": "{file_hash}", "hash_type": "sha256"}}

A hash source adds the file instantly only when its content already exists in that storage; if the content is not present, the call returns 404 Not Found ("The specified file content was not found in this storage. Upload the file instead.") and the client should upload the file normally instead.

curl Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/storage/root/addfile/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'name=document.pdf' \
  -d 'from={"type":"upload","upload":{"id":"abc123opaqueid"}}'

Response

{
  "result": true,
  "node": {
    "id": "2emaf-exxpw-thkzj-5rlym-ocyoh-iufa",
    "type": "file",
    "name": "document.pdf",
    "parent": "root",
    "size": 5242880,
    "hash": "d41d8cd98f00b204e9800998ecf8427e",
    "hash_algo": "md5",
    "mimetype": "application/pdf",
    "mimecategory": "document",
    "version": "3u6cr-vxmyl-4y2pr-5jboz-afoke-k4s5",
    "created": "2025-01-15 10:30:00 UTC",
    "modified": "2025-01-15 10:30:00 UTC",
    "restricted": false,
    "dmca": false,
    "locked": false
  }
}

Error Responses

Notes:

• The upload session must be in COMPLETE status before adding the file.
• Virus scanning occurs during upload assembly, not at this stage.
• Conflict resolution: If a file with the same name exists, the default behavior is to replace (overwrite) the existing file, creating a version for rollback. Folder or type-mismatch conflicts fall back to renaming.

Add Link (Workspace Only)

Auth required. Permission: Guest.

Path Parameters

Request Body (form-encoded)

curl Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/storage/root/addlink/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'link_target_type=share' \
  -d 'share=my-share-name'

Response

{"result": true}

Error Responses

The link node is named after the share's title, falling back to its custom URL when no title is set.

Create Folder

This endpoint is idempotent by default: if a folder with the same name already exists in the parent, the existing folder is returned (HTTP 200) instead of creating a duplicate. Pass force=true to bypass this and always create a new folder (auto-renamed on a name collision, e.g. Documents (2)).

Auth required. Permission: Guest (workspace), folder creation permission (share).

Path Parameters

Request Body (form-encoded)

curl Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/storage/root/createfolder/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'name=Documents'

Response

{
  "result": true,
  "node": {
    "id": "2uvd6-rylta-qajvp-y3yr6-fzadn-e4rc",
    "type": "folder",
    "name": "Documents",
    "parent": "root",
    "created": "2025-01-15 10:30:00 UTC",
    "modified": "2025-01-15 10:30:00 UTC",
    "restricted": false,
    "dmca": false,
    "locked": false
  }
}

Error Responses

Create Note (Workspace Only)

Auth required. Permission: Guest.

Path Parameters

Request Body (form-encoded)

curl Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/storage/root/createnote/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'name=meeting-notes.md' \
  -d 'content=# Meeting Notes\n\nDiscussed project timeline.'

Response

{
  "result": true,
  "note": {
    "id": "2ik5q-a43cm-uixi2-van5r-3eolo-7mue",
    "type": "note",
    "name": "meeting-notes.md",
    "parent": "root",
    "mimetype": "text/markdown",
    "created": "2025-01-15 10:30:00 UTC",
    "modified": "2025-01-15 10:30:00 UTC"
  }
}

Error Responses

Update Note (Workspace Only)

Auth required. Permission: Guest.

This workspace endpoint also accepts a realtime-note bearer token (minted by GET /current/realtime/note-auth/{profile_id}/{note_id}) in place of a user JWT, for the collaborative-editing backend to save on the user's behalf. The token is bound to a specific note and workspace and is rejected (403 Forbidden) if it does not match the requested note or workspace, or if it carries only view permission (a view token cannot update). The share note endpoints do not accept this token.

Path Parameters

Request Body (form-encoded)

At least one of name or content is required.

curl Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/storage/2ik5q-a43cm-uixi2-van5r-3eolo-7mue/updatenote/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'content=# Updated Notes\n\nRevised content here.'

Response

{
  "result": true,
  "note": {
    "id": "2ik5q-a43cm-uixi2-van5r-3eolo-7mue",
    "type": "note",
    "name": "meeting-notes.md",
    "parent": "root",
    "mimetype": "text/markdown",
    "created": "2025-01-15 10:30:00 UTC",
    "modified": "2025-01-20 14:45:00 UTC"
  }
}

Conflict Response (if_version_id mismatch)

When if_version_id is supplied and does not match the note's current version, the request is rejected with HTTP 409 Conflict and no version is created. error.params is a list of parameter entries, matching the structured detail used elsewhere in this API:

{
  "error": {
    "code": 113958,
    "text": "The note was modified since the supplied version",
    "params": [
      {
        "name": "if_version_id",
        "kind": "conflict",
        "message": "The note was modified since the supplied version. current_version_id=3jnix-kx7lb-pf2lf-qw6jd-6jng2-hqjn",
        "code": 174450,
        "reason": "conflict_version_mismatch",
        "current_version_id": "3jnix-kx7lb-pf2lf-qw6jd-6jng2-hqjn"
      }
    ]
  }
}

How to recognise this conflict. Branch on params[].reason == "conflict_version_mismatch" — the only field naming the cause. If your client keeps only the four standard entry fields, params[].name == "if_version_id" with params[].kind == "conflict" proves a precondition on that parameter failed, not which one, so treat it as a generic conflict rather than as proof of a version mismatch. Do not branch on the HTTP status — 409 also reports several unrelated conditions — and do not branch on the numeric code, which is a diagnostic identifier and is not a stable indicator of the cause.

kind here is conflict, which extends the values used for validation failures (missing, invalid, type_mismatch, unknown_parameter). It is distinct from invalid on purpose: invalid means the supplied if_version_id was not a well-formed id, whereas conflict means it was well-formed and the version had moved.

Rebasing. Take the current version from current_version_id, re-read the note, and re-apply your edit against it. The id is also appended to message in the fixed form current_version_id=<id> for clients that surface only the message text. Do not resend the same request unchanged — the version has moved and will stay moved, so an unmodified retry cannot succeed.

If the current state cannot be resolved at the time of the conflict, current_version_id is omitted and the message carries no id suffix; the entry still carries name, kind, message, code and reason, so the conflict remains identifiable.

Error Responses

Read Note

Auth required. Permission: View (workspace), download permission or download token (share).

The workspace endpoint also accepts a realtime-note bearer token (minted by GET /current/realtime/note-auth/{profile_id}/{note_id}) in place of a user JWT, for the collaborative-editing backend to read on the user's behalf. The token is bound to a specific note and workspace and is rejected (403 Forbidden) if it does not match the requested note or workspace. The share note endpoint does not accept this token.

Path Parameters

Query Parameters

curl Example

# Workspace
curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/2ik5q-a43cm-uixi2-van5r-3eolo-7mue/readnote/" \
  -H "Authorization: Bearer {jwt_token}"

# Share
curl -X GET "https://api.fast.io/current/share/1234567890123456789/storage/2ik5q-a43cm-uixi2-van5r-3eolo-7mue/readnote/" \
  -H "Authorization: Bearer {jwt_token}"

# Share with download token (no JWT needed)
curl -X GET "https://api.fast.io/current/share/1234567890123456789/storage/2ik5q-a43cm-uixi2-van5r-3eolo-7mue/readnote/?token={download_token}"

Response

{
  "result": true,
  "content": "# Meeting Notes\n\nDiscussed project timeline.",
  "note": {
    "id": "2ik5q-a43cm-uixi2-van5r-3eolo-7mue",
    "type": "note",
    "name": "meeting-notes.md",
    "parent": "root",
    "mimetype": "text/markdown",
    "version": "3u6cr-vxmyl-4y2pr-5jboz-afoke-k4s5",
    "created": "2025-01-15 10:30:00 UTC",
    "modified": "2025-01-15 10:30:00 UTC"
  }
}

Response Fields

Error Responses

Update Node

Auth required. Permission: Guest (workspace), file modification permission (share).

Path Parameters

Request Body (form-encoded)

At least one field should be provided. if_version_id does not itself count toward that requirement — supplying only if_version_id (with no name, from, metadata_title, or metadata_short) still returns “No update parameters were specified”.

curl Example (rename)

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/storage/2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4/update/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'name=new-document-name.pdf'

curl Example (replace content and update metadata)

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/storage/2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4/update/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'from={"type":"upload","upload":{"id":"upload_opaque_id"}}' \
  -d 'metadata_title=Updated Report' \
  -d 'metadata_short=Q1 2025 revision'

Response

{
  "result": true,
  "node": {
    "id": "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4",
    "type": "file",
    "name": "new-document-name.pdf",
    "parent": "root",
    "size": 5242880,
    "version": "3ak5n-dr47a-qnylo-kzv6c-e6bnm-3u3c",
    "modified": "2025-01-22 11:00:00 UTC"
  }
}

A precondition must have something that can invalidate it. if_version_id is refused with 406 when the request supplies neither from nor name — a metadata-only update. Custom metadata does not create a new version, so the precondition would still be satisfied for the next writer: two callers holding the same version could both succeed and the second would silently overwrite the first, while both were told a compare-and-swap protected them. Send it together with name or from, or omit it. Metadata alongside a rename or a content replace is fine — those do create a version, so the precondition is real.

Conflict Response (if_version_id mismatch)

When if_version_id is supplied and does not match the node's current version, the request is rejected with HTTP 409 Conflict and no new version is created. error.params is a list of parameter entries, the same shape documented for updatenote above:

{
  "error": {
    "code": 180212,
    "text": "The file was modified since the supplied version",
    "params": [
      {
        "name": "if_version_id",
        "kind": "conflict",
        "message": "The file was modified since the supplied version. current_version_id=3jnix-kx7lb-pf2lf-qw6jd-6jng2-hqjn",
        "code": 106523,
        "reason": "conflict_version_mismatch",
        "current_version_id": "3jnix-kx7lb-pf2lf-qw6jd-6jng2-hqjn",
        "contested": true,
        "rebase_count": 3,
        "contested_since": "2026-08-26 04:00:00 UTC"
      }
    ]
  }
}

Contention (contested, rebase_count, contested_since). A sliding ~10-minute window of how many writes this node has refused, so a losing writer can tell bad luck from a genuine fight. rebase_count counts conflicts inside the window including this one; contested is true from the second onward; contested_since is when the window opened. contested: true means ESCALATE TO A HUMAN — which is not the same as “stop writing”, and what it implies depends on what you are. An autonomous agent deciding whether to loop should stop and surface: retrying against a live editor is how one conflict becomes a storm. A stateful relay holding a person’s live editing session must NOT stop persisting — its “retry” is the mechanism by which that person’s unsaved keystrokes reach the platform, so stopping silently drops their work. Escalate by telling the human a conflict is live, and keep holding their content.

These three keys are OMITTED, never zeroed, when the signal is unavailable. Absent means unknown; it does not mean uncontested. Treat a missing block as “no information” and fall back to your normal retry policy, not as permission to retry.

Shown for the workspace endpoint; the share endpoint returns the identical shape with outer error.code 158175 and nested params[].code 101301. Branch on params[].reason == "conflict_version_mismatch" — the only field naming the cause — and not on the 409 status (which also reports unrelated conditions) or on the numeric code (assigned per call site, so it differs between the workspace and share variants of this same endpoint, and between this endpoint and updatenote). See Conflict Response and How to recognise this conflict under Update Note above for the full field-by-field rationale; it applies unchanged here.

Rebasing. Take the current version from current_version_id, re-read the node (or re-fetch its version via list/details), and re-apply your update against it. Do not resend the same request unchanged — the version has moved and will stay moved, so an unmodified retry cannot succeed.

Link Rename Refusal. Supplying if_version_id together with a new name is refused with HTTP 406 when the target node is a link, rather than attempted: renaming a link propagates the new name to the link's target before the version check runs, so a rejected write could still leave the rename applied. Rename the link without if_version_id, or supply if_version_id without a new name.

Error Responses

Notes:

• At least one of name, from, metadata_title, or metadata_short must be provided.
• Replacing content creates a new version.
• Renaming a link node propagates the rename to the linked share.
• Custom metadata overrides AI-generated summary values for display.
• Share permissions may restrict modification to files the user created (creator-only restrictions).
• if_version_id guards a content replace with compare-and-swap; see Conflict Response above. It cannot be combined with a new name on a link node — see Link Rename Refusal above.

Move Node

Auth required. Permission: Guest (workspace), file modification permission (share).

Path Parameters

Request Body (form-encoded)

curl Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/storage/2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4/move/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'parent=2qk7d-kri4y-yievb-q5hri-eq4io-hij5'

Response

{"result": true}

Error Responses

Notes:

• Guests who can view or modify only their own files may copy or move individual files they created; copying or moving a whole folder requires permission to view (copy) or modify (move) all files in the share.
• Conflict resolution: If a file with the same name exists in the destination, the existing file is replaced (moved to trash for rollback). Folder or type-mismatch conflicts fall back to renaming.

Copy Node

Auth required. Permission: Guest (workspace), file/folder creation permission (share).

Path Parameters

Request Body (form-encoded)

curl Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/storage/2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4/copy/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'parent=2qk7d-kri4y-yievb-q5hri-eq4io-hij5'

Response

{
  "result": true,
  "node": {
    "id": "2fbt2-66lwc-hle6y-kokf2-wahnc-z4py",
    "type": "file",
    "name": "document.pdf",
    "parent": "2qk7d-kri4y-yievb-q5hri-eq4io-hij5"
  },
  "job": null
}

Error Responses

Notes:

• Creates a deep copy for folders (all children are copied recursively).
• Guests who can view only their own files may copy or move individual files they created; copying or moving a whole folder requires permission to view (copy) or modify (move) all files in the share.
• The copied node gets a new OpaqueId.
• Conflict resolution: If a file with the same name exists in the destination, the existing file is replaced (moved to trash for rollback). Folder or type-mismatch conflicts fall back to renaming.
• The copy normally inherits the original’s metadata. Copying a file or a note carries its extracted and hand-entered metadata values onto the copy, with their sources and confidence intact — the copy holds the same content, so the same values are true of it, and it is not re-analyzed at your expense. Inheritance happens after the copy itself is saved, and it is best-effort: if it cannot complete, or if the original’s stored content changed while the copy was being made — so the values would no longer describe the copy’s own content — the copy is still created successfully, just with no metadata, and is treated as new content from then on. Nothing is retried in the background, so a copy that arrives without metadata keeps none until it is analyzed or filled in again. See Transfer Node below for metadata behavior when copying to a different storage instance.

Transfer Node

Auth required. Permission: Guest on source + write access on destination.

Path Parameters

Request Body (form-encoded)

curl Example (copy, default)

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/storage/2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4/transfer/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'instance=9876543210987654321' \
  -d 'parent=root'

curl Example (move)

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/storage/2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4/transfer/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'instance=9876543210987654321' \
  -d 'parent=root' \
  -d 'mode=move'

Response (copy)

{
  "result": true,
  "node": {
    "id": "2rugc-wuylb-far5j-yxics-lla5z-rmbu",
    "type": "file",
    "name": "document.pdf",
    "parent": "root"
  },
  "job": null
}

Response (move)

{
  "result": true,
  "node": {
    "id": "2rugc-wuylb-far5j-yxics-lla5z-rmbu",
    "type": "file",
    "name": "document.pdf",
    "parent": "root"
  },
  "source_trashed": true,
  "job": null
}

Error Responses

Notes:

• Folder transfers are recursive.
• The user must have write access to both source and destination. Writing into a destination share requires file-creation permission on that share, honoring its type and access settings; a password-protected public destination share also requires a valid share password.
• When mode=move, the source node is trashed in the source storage instance after the copy completes. The response includes "source_trashed": true on success.
• Guests who can view or modify only their own files may copy or move individual files they created; copying or moving a whole folder requires permission to view (copy) or modify (move) all files in the share.
• Metadata does not carry over to the destination. Copying or moving a node to a different storage instance carries no metadata: field definitions belong to a workspace, so a value moved across would be attached to the wrong field. The transfer itself succeeds either way.

Delete Node (Move to Trash)

Auth required. Permission: Guest (workspace), file modification permission (share). Emptying trash on shares requires admin permission.

Path Parameters

curl Examples

# Delete a specific node
curl -X DELETE "https://api.fast.io/current/workspace/1234567890123456789/storage/2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4/delete/" \
  -H "Authorization: Bearer {jwt_token}"

# Empty the trash
curl -X DELETE "https://api.fast.io/current/workspace/1234567890123456789/storage/trash/delete/" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": true,
  "job": null
}

Error Responses

Notes:

• Deleting a folder moves it and all children to trash recursively.
• Share delete permissions may be restricted to files the user created.
• Trashed files still count toward storage usage. Moving a node to trash does not reduce the storage your org is billed for — the bytes are still stored, and they are still yours to restore. Only a permanent delete releases them.
• Emptying the trash returns as soon as the trash is empty, but what it held is not removed straight away: those files are retained for 30 days as a recovery window, and they keep counting toward your storage usage for the whole of that window. Emptying the trash therefore does NOT reduce storage usage immediately — the bytes are released only once the window has passed. The call is still not undoable from the API; the window is a safeguard against an accidental empty, not a second trash.
• A storage limit measured over a billing period does not clear when you free space. The storage meter records the highest usage seen during the period, so an org that went over its limit keeps returning 402 on writes until the period resets or more credit is added. Emptying the trash is not a remedy for it: the emptied files keep counting for their 30-day retention window, and even once they are released the period's high-water mark stands.

Purge Node (Permanent Delete)

Auth required. Permission: Member (workspace), admin (share).

Path Parameters

curl Example

curl -X DELETE "https://api.fast.io/current/workspace/1234567890123456789/storage/2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4/purge/" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": true,
  "job": null
}

Error Responses

Restore from Trash

Auth required. Permission: Guest (workspace), file modification + admin (share).

Path Parameters

curl Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/storage/2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4/restore/" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": true,
  "job": null
}

Error Responses

List Versions

Workspace route: auth required, View permission on the workspace.

Share route: auth is optional — an anonymous caller may read a public-link share (the share password, when set, must still be satisfied). Access is decided entirely by the share's own permissions.filesystem.file_view policy; there is no workspace-level requirement.

• file_view: "all" — every version of every node in the share is listable.
• file_view: "owned" — only versions of nodes the caller created are listable; every other node is rejected. An anonymous caller has no creator identity, so all nodes are rejected.
• file_view: "none" — the endpoint is rejected outright.

Path Parameters

curl Example

curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4/versions/" \
  -H "Authorization: Bearer {jwt_token}"

Response

versions is an object carrying a count and an items array — not a bare array.

{
  "result": true,
  "versions": {
    "count": 2,
    "items": [
      {
        "id": "3maag-qdkzs-whhrp-5jifb-zgbni-2udf",
        "type": "file",
        "current_version": true,
        "nodeId": "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4",
        "name": "document.pdf",
        "parent": "2qk7d-kri4y-yievb-q5hri-eq4io-hij5",
        "created": "2025-01-20 14:45:00 UTC",
        "size": 5242880,
        "hash": "abc123def456789...",
        "hash_algo": "sha256",
        "mimetype": "application/pdf",
        "mimecategory": "document",
        "previews": { "thumbnail": { "state": "ready" }, "pdf": { "state": "ready" } },
        "virus": { "status": "scanned", "infected": false },
        "ai": { "state": "indexed", "attach": true, "summary": true },
        "file_attributes": {},
        "summary": { "title": "Quarterly Report", "short": "Q4 financial summary", "long": "..." },
        "origin": {
          "type": "User",
          "creator": "9876543210987654321",
          "operations": ["modify"],
          "created": "2025-01-20 14:45:00 UTC"
        },
        "replaces": { "status": "known", "version_id": "34wse-ehjvl-zefmd-2dfeh-hhw66-t4xe" },
        "author": { "status": "known", "user_id": "9876543210987654321", "actor_type": "User", "agent_name": "Claude-2", "agent_name_source": "api_key_label" }
      },
      {
        "id": "34wse-ehjvl-zefmd-2dfeh-hhw66-t4xe",
        "type": "file",
        "current_version": false,
        "nodeId": "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4",
        "name": "document.pdf",
        "parent": "2qk7d-kri4y-yievb-q5hri-eq4io-hij5",
        "created": "2025-01-15 10:30:00 UTC",
        "size": 4194304,
        "hash": "def456abc789012...",
        "hash_algo": "sha256",
        "mimetype": "application/pdf",
        "mimecategory": "document",
        "previews": { "thumbnail": { "state": "ready" }, "pdf": { "state": "ready" } },
        "virus": { "status": "scanned", "infected": false },
        "ai": { "state": "indexed", "attach": true, "summary": false },
        "file_attributes": {},
        "summary": null,
        "origin": {
          "type": "User",
          "creator": "9876543210987654321",
          "operations": ["create"],
          "created": "2025-01-15 10:30:00 UTC"
        },
        "replaces": { "status": "none", "version_id": null },
        "author": { "status": "known", "user_id": "9876543210987654321", "actor_type": "User", "agent_name": null, "agent_name_source": null }
      }
    ]
  }
}

Response Fields

Per Version Entry

origin Object

replaces Object

• known — version_id is the version this version replaced.
• none — this version replaced nothing; it is the version the file was created with.
• unknown — it cannot be determined; version_id is null. Clients must branch on status and must never treat a null version_id as "this was the first version" — none and unknown are different answers.
• Replacement lineage is derived from the order of the versions that still exist, not stored. Older version history is thinned over time, so for versions older than roughly half a day the preceding surviving version is not necessarily the one that was replaced — those report unknown rather than naming a version that might be wrong. The current version's replaces is always resolvable, at any age.
• unknown is also returned when the returned list is not the file's complete history — a full page of results (older versions exist beyond it), or a listing that omits versions the caller may not access (the File Share version listing omits versions whose content is unavailable).

author Object

• user_id is a PROFILE id and it is not always a person. Check actor_type before resolving it against a user lookup: some versions are attributed to a workspace rather than to a user, and looking one of those up as a user will find nothing. author.user_id / author.actor_type carry the same pair as origin.creator / origin.type.
• The account is who the version is attributed to; the agent name only qualifies it — there is always an account behind an agent.
• agent_name is self-declared, not verified. Display it; never rely on it to identify or authorize anyone.
• status is unknown in two different situations that user_id alone cannot tell apart. Most history does carry an author, so unknown is not the common case — but it is a value you will genuinely receive, and it never fills in later:
  • Authorship was never recorded — versions created before authorship tracking existed. These also return an empty origin.operations and a null origin.created, which is how you distinguish this case.
  • Nothing was acting as an account — versions created by background processing rather than by a request: a synced file that changed at the connected cloud provider, a folder copy large enough to run in the background, or an upload assembled without an associated account.
  Render both as "unknown", never as an empty or missing author.

Folder versions carry only the basic fields (id, type, current_version, nodeId, name, parent, created, replaces, author) plus origin; the file-specific fields above are omitted. A version that was created by trashing carries additional deleted / deleted_from fields.

Error Responses

The Error Code column shows the application error class followed by the per-call-site value returned in error.code.

Notes:

• Share permissions may restrict version listing to files the user created (file_view: "owned").
• The share route needs no workspace permission and no authenticated user; a public-link share is readable anonymously.

Restore Version

Auth required. Permission: Guest (workspace), file modification permission (share).

Path Parameters

Request Body (form-encoded)

curl Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/storage/2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4/restore-version/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'version_id=34wse-ehjvl-zefmd-2dfeh-hhw66-t4xe'

Response

{
  "result": true,
  "new_version": {
    "id": "3qced-56d4r-4o7q3-w3xru-zw3m5-nutj",
    "type": "file",
    "current_version": true,
    "nodeId": "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4",
    "name": "original-name.pdf",
    "parent": "2qk7d-kri4y-yievb-q5hri-eq4io-hij5",
    "created": "2025-01-25 09:00:00 UTC",
    "size": 4194304,
    "hash": "def456abc789012...",
    "hash_algo": "sha256",
    "mimetype": "application/pdf",
    "mimecategory": "document",
    "previews": { "thumbnail": { "state": "ready" }, "pdf": { "state": "ready" } },
    "virus": { "status": "scanned", "infected": false },
    "ai": { "state": "indexed", "attach": true, "summary": false },
    "file_attributes": {},
    "summary": null,
    "origin": {
      "type": "User",
      "creator": "9876543210987654321",
      "operations": ["restore"],
      "created": "2025-01-25 09:00:00 UTC"
    },
    "replaces": { "status": "unknown", "version_id": null },
    "author": { "status": "known", "user_id": "9876543210987654321", "actor_type": "User", "agent_name": null, "agent_name_source": null }
  },
  "node": {
    "id": "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4",
    "type": "file",
    "name": "original-name.pdf",
    "version": "3qpwy-4fuxn-o5zkk-qqqh5-w6zqd-habx"
  }
}

new_version carries the same per-version fields as a List Versions entry (it is the freshly created current version); node is the standard node resource (see Node Object Schema).

Error Responses

Notes:

• Original versions are preserved; restoring creates a new current version whose content and name match the selected historical version.
• Both filename and content are restored to the historical version's state.
• new_version.replaces is always "unknown" on this endpoint — this response returns a single version with no surrounding history to derive lineage from. Call List Versions for lineage.

Download File (Read)

Auth: JWT or download token. Permission: View (workspace), download permission (share). With a valid token query parameter, no JWT is required.

Path Parameters

Query Parameters

curl Examples

# Download with JWT auth
curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4/read/" \
  -H "Authorization: Bearer {jwt_token}" \
  -o output.pdf

# Download with token (no JWT needed)
curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4/read/?token={download_token}" \
  -o output.pdf

# Download specific version
curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4/read/?version_id=34wse-ehjvl-zefmd-2dfeh-hhw66-t4xe" \
  -H "Authorization: Bearer {jwt_token}" \
  -o output_v1.pdf

# Byte-range request (streaming)
curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4/read/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Range: bytes=0-1023"

Response: Binary file content streamed directly.

• Status 200 OK for full file, 206 Partial Content for range requests.
• Headers: Content-Type, Content-Length, Content-Disposition, Accept-Ranges: bytes.
• On a 206, Content-Length is the length of the returned slice; the total size is the value after the slash in Content-Range: bytes {first}-{last}/{total}.
• A syntactically valid range that cannot be satisfied — a first byte at or past the end of the file — returns 416 Range Not Satisfiable with Content-Range: */{total}. An unparseable Range header is ignored and the full file is returned with 200.
• Only GET is accepted; HEAD returns 405. To learn a file's size without downloading it, send Range: bytes=0-0 and read the total from Content-Range.

Error Responses

Request Download Token

Auth required. Permission: View (workspace), download permission (share).

Path Parameters

curl Example

curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4/requestread/" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Usage: Append ?token={token} to the read endpoint to download without an Authorization header. Useful for opening files in browser tabs.

Query Parameters

Pinning a Token to a Version

Pass version_id and the issued token is bound to that exact version. The response then echoes the version it was pinned to:

{
  "result": true,
  "token": "{download_token}",
  "version_id": "3o2ex-os4uz-32bkm-icr5l-uv3jd-546r"
}

Why pin. Without it, the token authorises the node and the version_id on the read selects the bytes — the two are never compared, so a token issued while looking at one version can fetch a different one committed in between. A pinned token cannot: a read naming any other version is rejected. Use this whenever the bytes you read will become the basis of a later write, so the version you record is provably the version you received.

Pass the same version_id on the subsequent read call. A pinned token is rejected on a read that names a different version, and on a read that names none.

Compatibility. version_id is optional and additive — omit it and behaviour is exactly as before. Tokens already issued without it keep working, including on reads that name a version.

Applies to the note read too. GET /current/share/{share_id}/storage/{node_id}/readnote/ accepts the same token and the same version_id, and enforces the same pin.

Errors are raised at mint time rather than later at fetch time: an unknown version returns 404, a version belonging to a different file returns 406, and a version whose content is no longer stored returns 404. A backend failure returns a 5xx and is safe to retry — it is deliberately not reported as a missing version, which would say the resource is gone when it is not.

Error Responses

Download Folder as ZIP

Auth required. Permission: View (workspace), download permission (share).

Path Parameters

curl Example

curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/root/zip/" \
  -H "Authorization: Bearer {jwt_token}" \
  -o workspace.zip

Response: Binary ZIP archive streamed directly with Content-Type and Content-Disposition headers.

Notes:

• Uses ZIP64 format — supports archives up to 50GB (plan-dependent limits may be lower).
• Compatible with all modern extraction tools (WinRAR, 7-Zip, macOS Archive Utility, Windows Explorer).
• The archive is streamed; it is not buffered in memory.
• Files are stored without compression for immediate streaming.
• Maximum 10,000 files per archive.
• Rate limited more aggressively than other endpoints due to resource cost.

Recent Files

Auth required. Permission: View (workspace), Guest+ (share). Public shares may allow password-only access.

Query Parameters

curl Example

curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/recent/?type=file&page_size=250" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": true,
  "nodes": {
    "count": 3,
    "items": [
      {
        "id": "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4",
        "name": "report.pdf",
        "type": "file",
        "parent": "2qk7d-kri4y-yievb-q5hri-eq4io-hij5",
        "size": 2048576,
        "modified": "2025-02-18 14:30:00 UTC",
        "created": "2025-02-17 10:00:00 UTC"
      }
    ]
  },
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJsYXN0X3VwZGF0ZWQiOiIyMDI1LTAyLTE4...",
    "page_size": 100
  }
}

Response Fields

Error Responses

Notes:

• Sort order is always updated DESC and is not configurable.
• Uses cursor-based (keyset) pagination, same as the list endpoint.
• For workspace folder shares, results are post-filtered to the share's subtree.

Search

Auth required. Permission: View (workspace), search + file view permissions (share).

Query Parameters

search_in, name_match, and case_sensitive are all optional and all additive: omit them and you get exactly the behavior this endpoint has always had — same query, same ranking, same response keys. Values are matched case-insensitively (GLOB and glob are the same value).

curl Example

curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/search/?search=quarterly+report" \
  -H "Authorization: Bearer {jwt_token}"

Search Modes

search_in — which side of the file to match

content is not a text scan of the file. Fastio does not index the literal bytes of your documents, so search_in=content is not a substring or full-text search — it matches the AI-generated summary of a file and the file's semantic index. Those are two channels, and intelligence gates only the meaning-based one: switching AI features off stops new semantic matching but does not un-index summaries that were already written, so a content search on a workspace with AI features off still returns hits for files summarized earlier and returns nothing when there are none. Either way the file must have finished indexing at some point (ai.state: indexed): a file uploaded a moment ago is findable by name immediately and by content only once indexing completes. A phrase that appears verbatim inside a document will not necessarily match, and a phrase that never appears in it may match — ask content questions in terms of what a document is about. If you need an exact string, that string is almost always in the filename; use search_in=filename.

name_match — how the filename is matched. Only meaningful when the filename participates in the query (search_in=filename or both); ignored under search_in=content.

glob spans spaces and hyphens. Because the pattern runs against the complete filename rather than word-by-word, Quarterly*.pdf finds Quarterly Report.pdf, report-*.xlsx finds report-2026-q1.xlsx, and Q?-2026.csv finds Q1-2026.csv. *.pdf gives you every PDF. This is the reason glob exists — it is the only mode that can match across a space or a hyphen in a filename.

Do not escape your query — escaping is handled for you. Under exact, prefix, and contains, * and ? are matched literally: name_match=contains with search=report* looks for a filename that really contains the two characters report* — it will not match report-2026.pdf. That is what makes a filename containing an asterisk searchable at all (name_match=prefix with search=weird* finds weird*name.txt). Only glob treats * and ? as wildcards. A client that pre-escapes its query (report\*) will search for the backslash.

Case sensitivity. case_sensitive defaults to false. Case-insensitive matching folds non-ASCII letters too — ÄNDERUNG matches änderung.docx and RÉSUMÉ matches résumé.pdf. It folds case only and does not strip accents, so resume will not match résumé.pdf. Send the query exactly as the user typed it: do not lowercase or otherwise normalize it client-side.

Pattern rules (precise modes only). Under any name_match other than auto: the query must be non-empty after trimming, and at most 256 characters; and a glob pattern made up of nothing but * and ? is rejected because it matches every file. Violations return 1605 (Invalid Input). auto keeps the length rules it has always had — search is not capped on this endpoint.

Search Mode Examples

# Every PDF in the workspace, by name only — no content lookup at all
curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/search/?search=*.pdf&search_in=filename&name_match=glob" \
  -H "Authorization: Bearer {jwt_token}"

# A filename that spans a space
curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/search/?search=Quarterly*.pdf&search_in=filename&name_match=glob" \
  -H "Authorization: Bearer {jwt_token}"

# Everything whose name starts with a known prefix, case-sensitively
curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/search/?search=Invoice-&search_in=filename&name_match=prefix&case_sensitive=true" \
  -H "Authorization: Bearer {jwt_token}"

# Ask what a document is about, ignoring filenames entirely
curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/search/?search=revenue+guidance+for+next+year&search_in=content" \
  -H "Authorization: Bearer {jwt_token}"

Response (keyword-only, intelligence disabled)

{
  "result": true,
  "files": {
    "2ltsuq4mjacuv7pgc5ydlxnsjwee4": {
      "name": "Q4 Report.pdf",
      "parent_id": "2qk7d-kri4y-yievb-q5hri-eq4io-hij5",
      "path": "Finance/Reports",
      "ancestors": [
        { "id": "2e2f3-inlkh-p63sd-3ungd-vfyvc-gilh", "name": "Finance" },
        { "id": "2qk7d-kri4y-yievb-q5hri-eq4io-hij5", "name": "Reports" }
      ],
      "path_complete": true,
      "type": "file",
      "summary_short": null,
      "best_chunk": null,
      "metadata_match": false,
      "metadata_match_field": null,
      "text_indexed": true
    }
  }
}

Response (hybrid, intelligence enabled)

{
  "result": true,
  "files": {
    "2emafexxpwthkzj5rlymocyohiufa": {
      "name": "MSA - Northwind Traders.pdf",
      "parent_id": "27ifb-ytevm-pzori-ybzul-dro2u-dqcm",
      "path": "Legal/Contracts",
      "ancestors": [
        { "id": "2tyji-byjgb-3f72a-cpvhd-5jw2i-6um7", "name": "Legal" },
        { "id": "27ifb-ytevm-pzori-ybzul-dro2u-dqcm", "name": "Contracts" }
      ],
      "path_complete": true,
      "type": "file",
      "relevance_score": 0.98,
      "raw_score": 4.31,
      "score_source": "metadata",
      "content_snippet": "This Master Services Agreement is entered into by Northwind Traders …",
      "match_source": "keyword",
      "media_segment": null,
      "mimetype": "application/pdf",
      "page": { "start_page": 1, "end_page": 1 },
      "text_indexed": true,
      "summary_short": "Master services agreement with Northwind Traders, effective 2026-01-01.",
      "best_chunk": {
        "text": "This Master Services Agreement is entered into by Northwind Traders …",
        "same_as_snippet": false,
        "page": { "start_page": 1, "end_page": 1 },
        "media_segment": null,
        "score": 6.42,
        "result_type": "doc",
        "position": 0,
        "sequence": 2001,
        "indexed_version_id": "3u6cr-vxmyl-4y2pr-5jboz-afoke-k4s5"
      },
      "metadata_match": true,
      "metadata_match_field": null
    },
    "2ltsuq4mjacuv7pgc5ydlxnsjwee4": {
      "name": "Q4 Report.pdf",
      "parent_id": "2qk7d-kri4y-yievb-q5hri-eq4io-hij5",
      "path": "Finance/Reports",
      "ancestors": [
        { "id": "2e2f3-inlkh-p63sd-3ungd-vfyvc-gilh", "name": "Finance" },
        { "id": "2qk7d-kri4y-yievb-q5hri-eq4io-hij5", "name": "Reports" }
      ],
      "path_complete": true,
      "type": "file",
      "relevance_score": 1.0,
      "raw_score": 0.87,
      "score_source": "semantic",
      "content_snippet": "Quarterly revenue grew 18% year-over-year …",
      "match_source": "both",
      "media_segment": null,
      "mimetype": "application/pdf",
      "page": { "start_page": 3, "end_page": 3 },
      "text_indexed": true,
      "summary_short": "Q4 revenue and margin review for the North America segment.",
      "best_chunk": {
        "text": "Quarterly revenue grew 18% year-over-year …",
        "same_as_snippet": false,
        "page": { "start_page": 3, "end_page": 3 },
        "media_segment": null,
        "score": 0.87,
        "result_type": "doc",
        "position": 12,
        "sequence": 3001,
        "indexed_version_id": "3mcys-2dr56-rmgdt-nh36b-prmp7-b47q"
      },
      "metadata_match": false,
      "metadata_match_field": null
    }
  },
  "search_metadata": {
    "intelligence_enabled": true,
    "semantic_available": true,
    "scoped": false
  }
}

Response Fields

Passages vs Summaries (content_snippet vs best_chunk). content_snippet reports whichever piece of evidence ranked the file highest — and that can be the file's whole-document summary. A summary is not located anywhere in the file, so page is null on such a hit and there is nothing to jump to. best_chunk always reports a real passage, with the locator that belongs to it — page for a document passage, media_segment for a transcript passage, and the other one null — which is what you want when you are opening the file at the right place, quoting it, or citing a page. When the top-ranked evidence is already a passage, best_chunk.text carries the same text as content_snippet — as in the example above, which is at the default full tier where both stay populated and same_as_snippet is false. At ?output=terse and ?output=standard, once both are trimmed to the tier's byte budget, the server drops the duplicate instead: best_chunk.text is null and best_chunk.same_as_snippet is true, and the caller reads content_snippet for the text while still using best_chunk's locator fields.

Passages on a filename or metadata match. A keyword hit is found by the file's name and its extracted metadata, neither of which is document text, so such a row used to come back with nothing to quote even where the file's text was fully indexed. It is now quoted the same way any other row is: the search takes the best-matching passage of that file's indexed text and fills content_snippet, page and best_chunk from it. Three limits are worth knowing. It applies to the top few results of the page, not all of them, so a null on a lower-ranked keyword row is a budget, not a verdict. It applies only where text_indexed is true. And best_chunk.score on such a row is a text-match score inside that one file — do not compare it with a semantic passage's score, or with the row's own raw_score.

Reading around the passage. best_chunk.position is the address the storage content/ endpoint takes: send it back as chunk_from (and chunk_to a little higher) on GET /current/{workspace|share}/{id}/storage/{node_id}/content/ to read the matching passage in full together with the text on either side of it, without downloading the file. Clamp both ends — chunk_from at 0, chunk_to at 9999. Then compare best_chunk.indexed_version_id with the indexed_version_id that response returns: if they differ the file was re-indexed between the two calls, the position is stale, and the search should be re-run rather than the text quoted.

raw_score and score_source are on /storage/search/ only — the unified /search/ route does not return them.

Result shape under search_in=filename. A filename search has no content leg at all, so it returns the keyword-only item shape shown above — name, parent_id, type, content_snippet: null, match_source: "keyword", plus summary_short: null, best_chunk: null, metadata_match and metadata_match_field: null — even on a workspace or share with AI features enabled. The hybrid-only fields (relevance_score, raw_score, score_source, mimetype, media_segment, page) are absent, because there is no content match to score or locate. If your client requires relevance_score, use both (the default) rather than filename. This shape is not new — it is exactly what every response looks like when AI features are off. The unified endpoints are unaffected: their files bucket keeps its usual item shape in every mode.

Folder paths

Every search hit says where it lives, so you do not have to list folders one at a time to find out. Three fields, one answer:

• path — the ancestor folder names from the workspace or share root down to the folder holding the file, joined with /, no leading or trailing slash: "Finance/Invoices/AR". The file’s own name is not in it. "" means the root.
• ancestors — the same folders as {id, name} objects in the same order, with id in the formatted form /storage/{parent_id}/list/ takes. Use this when you want to navigate rather than display.
• path_complete — whether the walk reached the root. Read this first.

When path_complete is true, path is exactly the ancestors names joined with /, and [] / "" together mean the file is at the root.

When it is false, path is null and ancestors carries only a best-effort suffix — the folders nearest the file, with an unknown number of levels missing from the top, never padded and never guessed. It goes false when a folder could not be read and past an internal depth limit. It is never a claim about where the file is.

A hit that came back with an empty parent_id — which is every hit the meaning side found on its own — still gets a path: the server reads the file’s own record to recover its folder. You do not need details=true for that, and the two retrieval legs answer alike.

Paths are built when the response is assembled, so a folder rename shows up on the next call with no re-indexing delay. Through a share the root is the shared folder, so a path never names anything outside it.

path is a display value, not an address. Folder names are returned exactly as stored and the / separator is not escaped, so a folder whose own name contains / is indistinguishable from a level boundary. Address folders with ancestors[].id or parent_id.

Result Ordering

Results are ordered tier first, then by relevance_score descending within a tier. Two rows tie on the score readily — a file at position r of the name/text leg and another at position r of the content leg fuse to the same value — so the comparator has two further steps: a row whose raw_score is on the keyword scale (score_source keyword or metadata) sorts above one on the semantic scale, matching the rule that decides attribution on an equal position, and node_id ascending ends the comparison so the same result set always paginates the same way.

The tiers, highest first:

Rows in the fourth group are ordered by relevance_score descending.

⚠ A promoted hit can appear above a hit with a higher relevance_score. This is the one thing most likely to surprise an integrator, and it is the ordering working as designed rather than a scoring bug: the tier is applied first, and relevance_score only breaks ties inside a tier. Do not re-sort results by relevance_score client-side — that throws the promotion away. To see why a row sits where it does, read score_source and metadata_match.

A promotion changes the ORDER, never the score. All three promoting tiers work the same way: they place the row above the untiered results and leave relevance_score exactly as retrieval produced it. A promoted row is therefore identifiable by its position and by score_source / metadata_match — never by a special score value. The one field a promotion does change is raw_score on a name match (tiers 1 and 2): a name equality is not a measurement, so those rows report score_source: "filename" with raw_score: null. A metadata-promoted row (tier 3) keeps its raw_score, and that number is on the keyword scale only where score_source is metadata — that value is reported when the keyword leg ranked the file higher. A metadata-promoted row the content engine ranked higher reports score_source: "semantic" and carries the provider score.

Knowing Whether Content Search Is Possible

A content search on an instance that cannot match content returns HTTP 200 with an empty result set, not an error. An empty list therefore has two very different meanings, and search_metadata is how you tell them apart:

"search_metadata": {
  "intelligence_enabled": false,
  "semantic_available": false,
  "scoped": false,
  "content_search_available": false,
  "reason": "intelligence_disabled"
}

Required client behavior: when content_search_available is false, do not report “no files found.” Either retry the same query with search_in=filename or tell the user that content search is unavailable here. This is the difference between recovering and confidently reporting a wrong answer.

What the flag does and does not tell you. content_search_available answers “can content search work here at all?” — not “will this query return results?” It is true whenever either channel is open to you, so a true flag over an empty list is an ordinary “nothing matched,” not a malfunction. For the per-request outcome, read semantic_available: it reports whether the meaning-based channel actually served this request.

It is reachable as false only on share routes, and only on a share where neither channel is open. A workspace member may always search file summaries, so on /workspace/{id}/storage/search/ the flag is always true and reason never appears — including when AI features are off for that workspace, because the summary channel is still open there. There is no workspace recovery path to code for.

When the block is emitted. search_metadata is returned whenever the response is a hybrid one (AI features enabled), exactly as before. It is additionally returned on the keyword-only path when you explicitly supply search_in. The two capability keys (content_search_available, reason) appear only when you explicitly supply search_in. Supplying only name_match and/or case_sensitive does not change the response shape at all.

⚠ search_metadata sits in a DIFFERENT PLACE on the two search routes, and reading only one position is indistinguishable from “no metadata”. On this route (/storage/search/) it is top level. On the unified route (/workspace/{workspace_id}/search/) it rides inside the files bucket, at buckets.files.search_metadata — see Unified search below. Nothing in either response points at the other location, so a client that hard-codes one position reads null on the other route and will report a search as unscored, unscoped, or semantically unavailable when it was none of those.

⇒ Read the top-level key first and fall back to buckets.files.search_metadata (or branch on which route you called). Treat a missing block as “not reported”, never as “the capability is off” — and note the two are not interchangeable in content either: the unified route carries no scope parameters, so its scoped is always false and it never emits scope_incomplete / scope_requested / scope_resolved.

Filtering by Metadata

filters narrows a search to files whose extracted metadata satisfies a set of predicates, so one call answers “find payment terms in open invoices over $1,000” instead of two. It is available on the workspace route only.

⚠ On the share route filters is IGNORED, not refused. The share search does not declare the parameter, so sending it there does not fail — the request returns 200 with the unfiltered result set and no metadata_filter block. Nothing in the response says the filter was discarded except that absent block, so a client that sends filters to a share and does not check for metadata_filter will present unfiltered results as filtered. metadata_filter is workspace-only for the same reason. If you need metadata narrowing on a share, do it client-side.

The filter runs first, as a stage of its own, and produces the candidate set the search is then confined to. Both legs of the search obey it: filename/text matches outside the candidate set are dropped, and the meaning-based leg searches only the survivors. This is deliberately not a post-filter — you are searching within the filtered files, not filtering what a workspace-wide search happened to return.

A filter that matches nothing yields no results. There is no fallback to an unfiltered search. If you asked for files satisfying a predicate and none do, the answer is an empty files map with metadata_filter.matched: 0.

A folder scope cannot be combined with filters. Sending both folders and filters is refused with an input error rather than quietly answered. The filter stage does not narrow by folder, so “inside this folder, matching this filter” is not something this endpoint can answer accurately today — and answering it by ignoring the folder would search the whole workspace and hand back far more than you asked for, which is worse than saying no. Filter the whole workspace instead, or name specific files. Combining filters with files is supported: the result is the intersection of the two.

The predicate array. filters is a JSON array of clause objects, each {"field", "operator", "value"} — the same shape the saved metadata filter predicate uses. Clauses are AND-combined. A request may carry at most 5 clauses. field names a field in the workspace's metadata vocabulary (canonical name or alias); the field's type is resolved server-side, so you never declare it.

confidence_gte — read these before using it. The operator takes the integer, while a fact's confidence comes back as the band name, so the mapping is 0 = low, 1 = medium, 2 = high, 3 = certain. Send the integer (a decimal string such as "2" is also accepted); a band name such as "high" is rejected, as is any non-integer, including 2.0.

• confidence_gte: 3 excludes every AI-extracted value. certain is reserved for deterministic sources (exif, mediainfo, validated_server); AI-extracted facts are capped at high on write. So 3 means “deterministic sources only”, not “the most confident AI results”.
• confidence_gte: 0 is not “no minimum”. A value entered by a person has no extraction confidence (confidence is null), and a null confidence satisfies no level — including 0. So 0 matches extracted values only and drops every hand-entered value. To match a field regardless of how it was obtained, use exists instead.

A value can be a bare JSON integer, and the server compares it exactly as sent. Do not round-trip such a value through a JavaScript Number — anything above Number.MAX_SAFE_INTEGER (9007199254740991) silently loses precision if you JSON.parse it into a Number and re-serialize; pass it through unmodified.

curl Example (filtered search)

curl -G "https://api.fast.io/current/workspace/1234567890123456789/storage/search/" \
  -H "Authorization: Bearer {jwt_token}" \
  --data-urlencode "search=payment terms" \
  --data-urlencode 'filters=[{"field":"status","operator":"=","value":"open"},{"field":"invoice_total","operator":">=","value":1000}]'

Response (filtered search)

{
  "result": true,
  "files": {
    "2ltsuq4mjacuv7pgc5ydlxnsjwee4": {
      "name": "Invoice-2026-0042.pdf",
      "parent_id": "2qk7d-kri4y-yievb-q5hri-eq4io-hij5",
      "type": "file",
      "relevance_score": 1.0,
      "raw_score": 0.62,
      "score_source": "semantic",
      "content_snippet": "Payment terms are net 30 from the invoice date …",
      "match_source": "semantic",
      "media_segment": null,
      "mimetype": "application/pdf",
      "page": { "start_page": 1, "end_page": 1 },
      "summary_short": "Invoice 2026-0042 for professional services, net 30.",
      "best_chunk": {
        "text": "Payment terms are net 30 from the invoice date …",
        "same_as_snippet": false,
        "page": { "start_page": 1, "end_page": 1 },
        "media_segment": null,
        "score": 0.62,
        "result_type": "doc",
        "position": 4,
        "sequence": 1000,
        "indexed_version_id": "3u6cr-vxmyl-4y2pr-5jboz-afoke-k4s5"
      },
      "metadata_match": false,
      "metadata_match_field": null
    }
  },
  "pagination": {
    "total": 1,
    "limit": 100,
    "offset": 0,
    "has_more": false
  },
  "search_metadata": {
    "intelligence_enabled": true,
    "semantic_available": true,
    "scoped": false
  },
  "metadata_filter": {
    "applied": true,
    "matched": 34,
    "truncated": false,
    "scope_incomplete": false,
    "coverage": {
      "scope": "files",
      "available": true,
      "files_in_scope": 40,
      "files_without_metadata": 28
    }
  }
}

Coverage — How Many Files the Filter Could Not Even See

Because a file with no extracted metadata is never a candidate, it is absent from a filtered result rather than unmatched, and matched cannot express that: a file the filter never got to evaluate is not a file it rejected. metadata_filter.coverage puts a number on it.

• scope: "files", available: true — you named the files, so both counts are exact.
• scope: "workspace", available: true — a whole-workspace filtered search reports coverage too. files_in_scope counts the live files in the workspace — files and notes, which are exactly the things metadata is extracted from. Folders, links and anything in the trash are not counted, because no clause could match them. files_without_metadata is that number minus the files that currently carry any metadata. The covered share — files_in_scope minus files_without_metadata — counts only files that are both live and currently carrying metadata. A file that has been deleted is never counted as covered, even when metadata was extracted from it before it was deleted.
• scope: "workspace", available: false, both counts null — the numbers could not be established for this request. Either the workspace is larger than the ceiling the two counts are read under (5,000), so the count stopped short of a total and a partial one would understate the uncovered share; or a count could not be read at all; or the two counts came back as a pair that cannot be true (see below); or a zero failed the final check described below. The search itself still answers normally — only this advisory block goes unfilled.

The ceiling is there because establishing the covered count means checking every file that carries metadata against live storage, so the work grows with how many of them there are; the limit is set from what that costs. It bounds the counting only — it never limits the search itself.

⚠ That ceiling counts metadata RECORDS, not live files. A file’s metadata record outlives the file — deleting a file leaves it behind — so a workspace with a long history of uploads and deletions can be permanently past the ceiling while holding very few files today, and will report available: false on every filtered search. (Explicitly clearing a file’s metadata does remove it from the count; deleting the file does not.) Nothing about the workspace’s current size tells you whether coverage will be available for it.

⚠ A 0 is VERIFIED against the actual files, not computed from two totals. A 0 is the one answer a caller acts on — it says the predicate saw every file, so an empty result set is a real absence rather than a coverage gap — and a difference of two totals cannot support that claim: a covered file deleted and a different file appearing in the same moment leave both totals untouched while a real file goes uncovered. So before a 0 is published, the live files in scope are listed and every one of them is checked for a metadata record. The 0 means: at the final read of this request, every live file in scope had metadata. If any live file is missing one, or the list does not match the count being published, the block answers available: false instead.

⚠ available: false means the numbers are UNKNOWN, never that they are zero. Rendering an absent count as 0 states that every file in scope has metadata, which nothing measured. Say nothing about coverage when available is false. coverage is workspace-only for the same reason metadata_filter is: the share route accepts no filters, so no predicate runs there and neither block is emitted.

⚠ A pair of counts that cannot be true is reported as unknown, never as a zero. The two whole-workspace counts are read separately, so a workspace changing underneath the request can produce a pair that is impossible — more covered files than there are files in scope. An impossible pair means one of the counts could not be trusted, so the block answers available: false with both counts null rather than publishing a coverage of 0. A zero is the one value a caller would act on by trusting the result set, which is exactly what an untrustworthy count must not invite.

⚠ files_without_metadata is not a fault count. It counts files a predicate cannot evaluate at all, and that includes files with nothing to extract — an image carrying no text — as well as files nobody has run extraction over. A non-zero value is therefore not by itself a sign that anything is wrong; only a value of 0 proves the predicate saw every file in the scope.

⚠ metadata_filter is an acknowledgement that the filter RAN, and its absence is meaningful. The block is emitted only when a filters value actually reached the server and ran. A request that sent no filter gets exactly the response it always got, with no such key. So, for a request you believe carried filters:

• metadata_filter present → the filter ran on the server, and matched is trustworthy.
• metadata_filter absent → the filter did not reach the server. The results in your hands are unfiltered and must not be treated as filtered.

What the block does not tell you. applied certifies that the predicate executed — nothing more. It is not a statement that the result set is exactly what you asked for. truncated and scope_incomplete are the fields that qualify the result set, and you must read them separately.

matched describes the PREDICATE, not the PAYLOAD. It counts the files the filter selected; it does not count the files this response contains. The two answer different questions and are routinely different numbers — matched is measured before the search narrows further and before any cap, so it is normally the larger of the two. Do not derive a result count from it, and do not treat matched being non-zero as a promise that files is non-empty.

Two things cause the key to be absent on a request you believe carried filters: an intermediate client, proxy, or SDK that strips query parameters it does not recognise (at least one client library does), or a deployment that does not yet accept filters. You do not need to tell them apart — the correct action is the same either way: do not treat the results as filtered.

Check for the key before trusting a filtered result. It is the only way to tell a filter that ran from one that never arrived: both come back 200 with a plausible-looking list of files.

truncated and scope_incomplete are different conditions — do not collapse them into “results may be incomplete.” One is worth retrying and the other never is:

• truncated: true — deterministic. Retrying changes nothing. The candidate set was larger than a cap (the filter's own match ceiling, or the ceiling on how many files the meaning-based leg will accept) and was clipped. Re-running the identical request returns the identical answer. The fix is to narrow: add a clause, or make an existing one more selective.
• scope_incomplete: true — transient. Retrying is worth it. A temporary fault dropped candidates that genuinely match your filter, so the answer is short for a reason that has nothing to do with your query. Re-run the same request — it may return more. Do not report the short list as complete.

They are independent booleans and both can be true at once. truncated says you asked for too much; scope_incomplete says we lost some of it.

A filtered search only reaches files that have extracted metadata. Predicates are evaluated against the metadata Fastio has already extracted for a file, so a file with no extracted metadata is not a candidate for any clause — including not_exists, which means “has metadata, but none for this field,” not “has no metadata at all.” Extraction is asynchronous, so a file added moments ago may not be filterable yet. To see what has been extracted for a file, read its metadata_facts on the node object. Read an empty filtered result as nothing that has been extracted matches this filter, not no such files exist.

Combining filters with a scope. filters and files_scope work together: the search runs over the intersection — the files you named that also satisfy the filter.

filters and folders_scope cannot currently be used together, and sending both is refused with 1605 (Invalid Input). Either drop the folder scope and let the filter select across the whole workspace, or name the specific files you want with files_scope. This is a current limitation rather than a permanent rule, so handle the refusal as a condition rather than building on it as an invariant.

Note that search_metadata.scoped reports only files_scope / folders_scope. A metadata filter is reported by metadata_filter, not by scoped, so scoped: false alongside a metadata_filter block is normal.

Scoping to Files or Folders (files_scope / folders_scope)

Both narrow the meaning-based (semantic) leg only. The filename/summary leg is deliberately not restricted by them, so a hybrid response can contain files from outside the scope carrying match_source: "keyword".

For a hard boundary, filter on match_source yourself: keep the results marked "semantic" or "both", and drop the ones marked "keyword". Both of the kept values mean the file came back from the meaning-based leg — the leg the scope narrowed — so they are the results that are genuinely inside the scope.

⚠ search_in=content is not a substitute for that filter. content matches two channels, and only one of them is the meaning-based leg; the other is a keyword match against the file's AI-generated summary, which the scope does not restrict either. Wherever summary search is open to you, a scoped search_in=content request can therefore still return files from outside the scope, carrying match_source: "keyword". Summary search is always open on the workspace routes, so search_in=content never bounds the result set there; on a share it depends on that share's permissions for you specifically. Filtering on match_source is the only approach that holds on every route and for every caller.

Because the scope applies to that leg alone, it changes nothing at all when that leg does not run — AI features off on the workspace or share, search_in=filename, or the leg failing on this request. search_metadata.scoped reports that honestly: it is true only when the narrowing was really applied, so scoped: false on a request that carried a scope means the scope had no effect on what came back.

A scope that resolves to no files returns no meaning-based results — never the whole workspace or share. A reference you name can drop out during resolution (the file was trashed, or a transient fault made it unreadable), and when every one of them does, the answer is an empty meaning-based result set rather than an unscoped search. An empty scope is still a scope: the empty one.

Entries are validated, not silently dropped. A value that is not a nodeId:versionId / nodeId:depth pair at all — including a bare 0 — a pair whose versionId is not a version of the file it is paired with, an id that is not a valid node or version id, or a node of a type the parameter does not take — a folder in files_scope, a file or note in folders_scope, or a link in either — is refused with 1605 (Invalid Input) / 406, and the message names the entry that was wrong. This matters because ids render both hyphenated and unhyphenated for the same value, so a pair assembled from two different responses is easy to mismatch by accident while each half stays individually well-formed. To send no scope, omit the parameter rather than sending a placeholder value.

files_scope takes files AND notes; folders_scope takes folders; links cannot be scoped. Search results carry a type of file, folder, link or note. Notes are indexed the same way files are and are returned by meaning-based search, so files_scope accepts a note's nodeId:versionId pair exactly as it accepts a file's — if a note came back as a hit, you can scope your next query to it. A link has no stored content to index and is accepted by neither parameter. A node of the wrong type for the parameter it was named in is refused with 1605 (Invalid Input) / 406, and the message names the type the node actually is and, where the other parameter would take it, which one to use instead.

Both parameters are read from the query string only. These are GET endpoints and the scope is a query parameter; a scope sent in a request body is not read, and the search runs unscoped. Put files_scope / folders_scope in the URL.

Folder aliases are not accepted. folders_scope takes a folder's own node id. The root and trash aliases are refused with 1605 (Invalid Input) / 406, and the message names the alias you sent. To search everything, omit files_scope and folders_scope rather than scoping to the root.

A scope carries at most 100 references in total, counting every file you name plus every folder you name plus every subfolder reached by expanding a folders_scope entry to its :depth. Naming more than 100 files is refused. A folder tree that runs past the limit is not refused — you cannot count a subtree before naming it — so it is truncated instead, and the truncation is reported: the response carries search_metadata.scope_incomplete: true, meaning the search covered less than you asked for. Narrow the :depth, or name fewer folders, and retry.

Verbosity (output)

content_snippet, best_chunk.text, best_chunk.same_as_snippet and summary_short are the fields affected by output=. All other fields are returned unchanged at every level.

Snippets shorter than the budget are returned unchanged (no padding, no …). Null/empty snippets are returned unchanged at every level. The byte budget is inclusive of the trailing … so the wire payload never exceeds the cap. best_chunk.text follows the same budget and the same … rule as content_snippet; at terse and standard, if the trimmed best_chunk.text then comes out byte-identical to the trimmed content_snippet, text is replaced with null and best_chunk.same_as_snippet is true (otherwise text is present and same_as_snippet is false) — at full, text is never suppressed and same_as_snippet is always false. The rest of best_chunk (page, media_segment, score, result_type, position, sequence, indexed_version_id) is returned unchanged at every level. Default output=full preserves the prior best_chunk.text value and never deduplicates it; the same_as_snippet key is the one additive change at that level.

A snippet is an excerpt, not the passage. When you need the surrounding text in full — to quote a clause, or to read what the match sits in — do not widen output and hope: call the file's Node Content endpoint with ?q= (the same query terms) and it returns that file's best-matching chunks with their complete text, page ranges, and no snippet budget at all.

Error Responses

Notes:

• Share search is not available for workspace-backed shares (shared folders).
• Search results are filtered by the user's file view permissions.
• Omitting search_in, name_match, and case_sensitive reproduces the exact query, ranking, and response keys this endpoint returned before they existed.
• search_in=filename skips the content lookup entirely rather than running it and discarding the result, so it is also the fastest mode.
• The pattern rules are checked whenever a precise name_match is asked for, even in combination with search_in=content where the filename is not matched at all — a request that would be silently ignored is rejected instead.
• A single search examines at most 1,000 matching files. A deliberately broad pattern (*, *a*) can reach that ceiling and return a truncated view, so prefer the narrowest pattern that answers the question.
• The precise name_match values (exact, prefix, contains, glob) depend on filename indexing that is rolled out per environment; auto works everywhere. If a precise match returns nothing where you expect a hit, retry with name_match=auto before concluding the file is absent.
• Omitting filters reproduces the exact response this endpoint returned before it existed — no metadata_filter key is added.
• Sending filters as an empty array ([]) is treated as no filter at all: the search runs unfiltered and no metadata_filter block is returned.
• filters is accepted on the workspace route only, and the share route ignores it rather than refusing it — the request succeeds and returns the unfiltered results, with no metadata_filter block. A 406 would tell you the parameter did not apply; a 200 does not, so the absent block is the only signal and you have to look for it. Same for metadata_filter: workspace-only.
• Always read metadata_filter before presenting a filtered result. A missing block means the results are unfiltered, and a truncated or scope_incomplete flag means they are partial for two very different reasons.

Metadata Search (Workspace Only)

Every result now tells you which metadata field matched. A metadata hit used to carry only the node, its name and a score — exactly what a filename hit carries — so there was no way to show a user why a file came back, and a correct match was indistinguishable from a match on the filename. Each result now includes matched_fields: the field name(s) whose value matched, each with the matching value. This is additive; every field that was there before is unchanged.

Auth required. Permission: View (workspace member).

Query Parameters

curl Example

curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/metadata/search/?q=invoice&limit=25" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": true,
  "results": [
    {
      "node_id": "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4",
      "score": 4.215,
      "template_ids": [],
      "matched_fields": [
        { "field": "document_type", "value": "Invoice", "value_truncated": false },
        { "field": "vendor", "value": "Invoice Systems Ltd", "value_truncated": false }
      ],
      "matched_fields_truncated": false,
      "node": {
        "id": "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4",
        "type": "file",
        "name": "Invoice-2026-0042.pdf",
        "parent": "2qk7d-kri4y-yievb-q5hri-eq4io-hij5",
        "size": 524288,
        "mimetype": "application/pdf",
        "mimecategory": "document",
        "version": "3u6cr-vxmyl-4y2pr-5jboz-afoke-k4s5",
        "created": "2026-04-20 14:12:08 UTC",
        "modified": "2026-04-22 09:30:55 UTC",
        "restricted": false,
        "dmca": false,
        "locked": false
      }
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 25,
    "offset": 0,
    "has_more": false
  }
}

Response Fields

Access. matched_fields and matched_fields_truncated are returned only to callers holding Member permission on the workspace — the same level every dedicated metadata read requires. The route itself is unchanged and still opens at View: a caller below Member still searches metadata and still receives every matching file, its score, its ranking and its full node payload. The two keys are simply not present on each result.

Read them with a presence check on the key, not with a length check. An absent matched_fields means the caller is not cleared to see metadata values. An empty matched_fields means something different and unrelated: the match could not be attributed to a specific field on that file. Do not treat the two as the same state, and never suppress a hit for either one.

Error Responses

Notes:

• Returns at most one entry per node, even when multiple metadata fields on that node matched — the fields that matched are listed in matched_fields on that single entry.
• Matching is substring and case-insensitive — inv already matches invoice, so no wildcard is needed. * and ? in your query are treated literally, not as wildcards: inv* searches for a literal asterisk and will NOT match invoice. A multi-word query requires ALL of its words to be present, not any.
• Indexing is event-driven — newly written or updated metadata typically becomes searchable within a few seconds.
• Binary metadata values are not indexed; only textual values (including JSON leaves) participate in matching.
• Each indexed document is bounded; metadata values exceeding the per-node ceiling are truncated for indexing only — source data is unaffected.
• This endpoint is independent of /storage/search/ — that endpoint searches filenames and file content, this one searches metadata field values. To search content within files selected by their metadata, use /storage/search/ with its filters parameter instead (see Filtering by Metadata under Search).
• Reading matched_fields. Values are truncated to at most 256 characters, and at most 10 fields are listed per result; both limits are reported rather than applied silently (value_truncated and matched_fields_truncated). An empty matched_fields is a valid result, not an error — it means attribution was not available for this file, so the match could not be tied back to a specific field. The result itself is still correct: the file genuinely matched. Render it normally when the list is empty; never suppress the hit. An absent matched_fields is a different state entirely — the caller is below Member permission; see Access above.
• Field names come from the metadata on the file and are caller data. Compare them byte-for-byte against your own vocabulary; a lowercased or accent-stripped comparison will miss fields that genuinely matched.

Compound Search (Metadata Filter + Content Query)

Workspace only — there is no share form.

Auth required. Permission: Member on the workspace. The organization’s plan must include both the metadata and content_ai features, and the workspace must have Intelligence enabled: the second stage searches the content index the Intelligence pipeline builds, so a workspace with Intelligence off is refused up front rather than handed a misleadingly empty result. There is no keyword leg to fall back on here — where /storage/search/ degrades, this endpoint refuses.

Parameters

🔴 filters is a FORM FIELD whose value is a JSON string — not a JSON request body. This is the most common way to call this endpoint wrong. Send the request form-encoded (application/x-www-form-urlencoded or multipart/form-data). A request sent as Content-Type: application/json does not populate filters at all, and is refused exactly as though you had sent no filters — 406 with error.code 119701 — which reads as “my filter is invalid” when the real problem is how the body was encoded.

The three parameters are not symmetric about this. content_query and limit are read from either the POST body or the query string, so they survive being sent either way. filters is read from the POST body only — there is no query-string form of it, and it is the one that goes missing.

curl Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/metadata/compound-search/" \
  -H "Authorization: Bearer {jwt_token}" \
  --data-urlencode 'filters=[{"field":"document_type","operator":"=","value":"contract"}]' \
  --data-urlencode "content_query=early termination clause" \
  --data-urlencode "limit=25"

Response

{
  "result": true,
  "items": [],
  "scope": {
    "match_count": 12,
    "match_relation": "eq",
    "scope_used": 100,
    "scope_truncated": false,
    "files_not_indexed": 3,
    "limit_clamped_from": null,
    "causes": []
  }
}

items holds standard node resources — the same shape as storage list/details, ranked by content relevance, honouring the request’s output= tier.

Read the scope object; it is the point of this endpoint. A short items list can mean “twelve files matched” or “far more matched and the answer was cut short”, and scope is what tells the two apart.

Response Fields

causes values and what to do about each:

Treat causes as an open set: handle the values you know and fall back for the rest. Only the count-bounding causes (filter_cap, scope_cap, result_budget) make match_relation a floor, so causes can be non-empty while match_relation is still eq — a degraded coverage read does not clip the candidate set.

Error Responses

Notes:

• A 503 here is specifically not an empty result. The endpoint refuses rather than returning a partial answer that looks complete.
• This is distinct from /metadata/search/, which is a keyword search over metadata values only and never reads file content.
• To filter by metadata inside a plain content search instead, use /storage/search/ with its filters parameter — see Filtering by Metadata under Search.

Unified Search (Grouped by Type)

Each bucket is independently paginated and independently health-reported, so a transient problem affecting one bucket never blocks the others — that bucket comes back degraded with an empty result set while the rest return normally.

Auth required. Permission: View (workspace), search + file view permissions (share). All buckets are permission-filtered — see Permission Model below.

Query Parameters

Search modes apply to the files bucket only. search_in, name_match, and case_sensitive behave exactly as documented under Search above — same values, same defaults, same escaping and case rules, same pattern limits, same 1605 (Invalid Input) on a bad value. They shape only the files bucket; the metadata and comments buckets are unaffected and keep matching as they always have. Omit all three and the response is byte-for-byte what it was before they existed. search_in=filename is the most useful of the three here: it turns the files bucket into a pure filename lookup while still returning metadata and comments matches from the same call.

details=true adds extracted metadata facts to the files bucket. Each file or note item whose facts were read then carries metadata_facts — the same block /storage/search/ and the node object emit, in the same three output shapes (terse, standard, full) with the same per-tier caps and the same count/total/is_truncated semantics — see Extracted Metadata Facts above. Folder and link items never carry the key, matching every other surface. Visibility follows the same rule as everywhere else metadata_facts appears: the key is omitted entirely (never emitted empty) when the caller is not entitled to extracted metadata. Because extracted metadata is a workspace-only surface, that omission is unconditional on the share twin — /share/{share_id}/search/ never returns metadata_facts regardless of details, for any share role. On the workspace route it is present for callers who are members of the owning workspace. With details absent or any string other than "true", the response is unchanged from before this parameter existed — no new key; a non-string value is rejected as invalid input, like any other declared parameter. Cost is at most one batched facts read per files-bucket page, not one read per item, so details=true is cheap here even at files_limit=25.

Verbosity (output)

content_snippet on files-bucket items is trimmed to a byte budget by the output level — the same budget /storage/search/ applies, so every search surface sizes the field the same way.

The budget is inclusive of the trailing …, so the wire payload never exceeds the cap, and the … is appended only when the value was actually cut. Snippets shorter than the budget are returned unchanged (no padding, no …), and a null snippet — what a keyword-only hit carries — is returned unchanged at every level. Only the files bucket is affected: the metadata and comments buckets are identical at every level, and content_snippet is the only field trimmed here, because this route returns no best_chunk and no summary_short. output sizes the snippet whether or not you send details=true — the two parameters are independent, and details governs only whether metadata_facts is added. As on /storage/search/, when you need the surrounding text in full, do not widen output: call the file's Node Content endpoint with ?q= and read the whole chunk with no snippet budget at all.

The capability report rides on the bucket it describes, at buckets.files.search_metadata, and is present only when search_in was explicitly supplied. ⚠ This is the reciprocal of the /storage/search/ placement — there the same block is top level. A client that reads only one position gets null on the other route, which is indistinguishable from “no metadata”: read the top-level key first, then fall back to buckets.files.search_metadata, or branch on which route you called. Its fields and reason values are identical to the /storage/search/ block documented under Knowing Whether Content Search Is Possible, and the same client rule applies: on content_search_available: false, do not report “no files found” — retry with search_in=filename. scoped is always false here because this endpoint has no scope parameters, and content_search_available reports capability, not result likelihood — it is reachable as false only on share routes, and semantic_available is the field that tells you what this particular request got.

Pagination is per bucket: files_offset/files_limit page the files bucket, comments_offset/comments_limit page the comments bucket, and so on. Each pair is optional; an omitted offset defaults to 0 and an omitted limit to 25. A request beyond the supported result window for any bucket returns a 406 input error. Every applicable bucket is always searched (the share endpoint omits metadata).

curl Example

curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/search/?search=quarterly+report&files_limit=10&comments_limit=5" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": true,
  "buckets": {
    "files": {
      "items": [
        {
          "node_id": "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4",
          "name": "Q4 Report.pdf",
          "parent_id": "2qk7d-kri4y-yievb-q5hri-eq4io-hij5",
          "type": "file",
          "relevance_score": 1.0,
          "content_snippet": "Quarterly revenue grew 18% year-over-year …",
          "match_source": "both",
          "media_segment": null,
          "page": { "start_page": 3, "end_page": 3 },
          "mimetype": "application/pdf",
          "updated": "2026-04-22 09:30:55 UTC"
        }
      ],
      "offset": 0,
      "limit": 10,
      "total": 1,
      "total_relation": "eq",
      "has_more": false,
      "status": "ok"
    },
    "metadata": {
      "items": [
        {
          "node_id": "23kgh-fgzmg-72knw-u676u-vibbh-jizb",
          "name": "Invoice-2026-0042.pdf",
          "parent_id": "2qk7d-kri4y-yievb-q5hri-eq4io-hij5",
          "type": "file",
          "relevance_score": 4.215,
          "template_ids": [],
          "matched_fields": [
            { "field": "document_type", "value": "Invoice", "value_truncated": false }
          ],
          "matched_fields_truncated": false,
          "updated": "2026-04-22 09:30:55 UTC"
        }
      ],
      "offset": 0,
      "limit": 25,
      "total": 1,
      "total_relation": "eq",
      "has_more": false,
      "status": "ok"
    },
    "comments": {
      "items": [
        {
          "comment_id": "caaq5-twdpg-axqnt-bbtt4-v2xit-unmv2",
          "entity": "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4",
          "author_profile_id": "1234567890123456789",
          "snippet": "Can we double-check the Q4 totals …",
          "reference_type": null,
          "relevance_score": 2.118,
          "created": "2026-04-21 08:02:11 UTC",
          "updated": "2026-04-21 08:02:11 UTC"
        }
      ],
      "offset": 0,
      "limit": 5,
      "total": 1,
      "total_relation": "eq",
      "has_more": false,
      "status": "ok"
    },
  }
}

Response Fields

Bucket Item Shapes

Every item carries a relevance_score (higher is more relevant) and an updated timestamp. Beyond that, fields are type-specific:

• files — node_id, name, parent_id, type, plus (when workspace/share intelligence is enabled) the hybrid-match fields content_snippet (the matching text, null for keyword-only matches, trimmed per output), match_source (keyword / semantic / both, where both means both legs matched rather than several semantic passages), media_segment ({start_seconds, end_seconds} for audio/video, else null), page ({start_page, end_page} for paginated documents, else null), and mimetype. A file or note item additionally carries metadata_facts when the request set details=true — see details=true adds extracted metadata facts above.
• metadata (workspace only) — node_id, name, parent_id, type, matched_fields + matched_fields_truncated, and template_ids. matched_fields lists the metadata field(s) whose value matched, each as {field, value, value_truncated} — this is what distinguishes a metadata hit from a filename hit in the files bucket, and it is identical in shape and meaning to the matched_fields returned by /metadata/search/ (see that endpoint for the full field table and the truncation rules). It may be empty, which is a valid result rather than an error. matched_fields and matched_fields_truncated are returned only to callers holding Member permission on the workspace, exactly as on /metadata/search/; below that level the two keys are absent from each item rather than empty, and the item’s node_id, name, parent_id, type and ranking are unaffected. Test for the key’s presence, not the list’s length. template_ids is now ALWAYS EMPTY — templates are retired and the searched corpus records no template association. The key is kept so existing clients keep parsing; it will not be populated again.
• comments — comment_id, entity (the commented-on node/container), author_profile_id, snippet (the matching comment text), reference_type (the anchor type when the comment is anchored to a position in a file, else null), created.

Permission Model

Every bucket is permission-filtered against the same rules as that type's dedicated endpoint. Results are produced by reading each match from the source of truth and re-checking the caller's permission before any content or count is returned, so search can never reveal an item, a snippet, or even a count for something the caller is not allowed to see. In particular:

• files / metadata — filtered by the caller's file view permissions (and, on a share, the share's per-item file-view rules).
• comments — only comments the caller can see in that workspace or share. On a workspace, the comments bucket is owner-inclusive of File Shares: it also returns comments left through the workspace's own live (active, non-expired, non-revoked) File Shares (a File Share is a view of a workspace file, so the comments belong to the same node). This is one-directional — workspace members see File Share comments, but File Share recipients never see the workspace's internal comments. Share search is unaffected. In rare cases (a workspace with a very large number of File Shares, or a transient error while enumerating them) workspace comment search may temporarily cover only the workspace's own comments; the File Share comments reappear on a later retry.

Error Responses

Notes:

• Search is not available for workspace-backed shares (shared folders) — the share endpoint returns 404 in that case.
• Comments become searchable shortly after they are created or updated (indexing is asynchronous — typically within a few seconds).
• A degraded bucket is safe to retry; the rest of the response is still valid.
• This unified endpoint composes the same per-type searches as /storage/search/, /metadata/search/, and the comments surface — use it when you want a single grouped result set, or the per-type endpoints when you only need one kind of result.

QuickShare (Workspace Only)

Auth required. Permission: Member.

Path Parameters

POST — Create or Update QuickShare (deprecated → 403)

This path is deprecated and returns 10756 (Quickshare Deprecated) (403) for both create and extend-expiry. Use POST /current/workspace/{workspace_id}/create/fileshare/ (see File Share). The legacy expires / expires_at request parameters no longer apply because creation is closed.

GET — Get QuickShare Details

Returns the same format as POST. Returns 1609 (Not Found) (404) if no quickshare exists.

DELETE — Delete QuickShare

Returns {"result": true}. Returns 1609 (Not Found) (404) if no quickshare exists.

Public Access Endpoints (No Auth Required)

Once a quickshare is created, these endpoints are accessible without authentication:

GET /current/quickshare/{quickshare_id}/details/                                    -- metadata and file info
GET /current/quickshare/{quickshare_id}/storage/read/                               -- download the file
GET /current/quickshare/{quickshare_id}/storage/preview/{preview_type}/read/        -- preview
GET /current/quickshare/{quickshare_id}/storage/preview/{preview_type}/read/file/{filename}  -- preview sub-file

List QuickShares in Workspace

Auth required. Permission: Member.

curl Example

curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/quickshares/list/" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": true,
  "quickshares": [
    {
      "id": "qs_abc123def456",
      "node": { "id": "...", "type": "file", "name": "presentation.pdf" },
      "creator_uid": { "id": "...", "email_address": "john@example.com" },
      "limit_exceeded": false,
      "expires": "2025-01-22 10:30:00 UTC",
      "created": "2025-01-15 10:30:00 UTC"
    }
  ]
}

File Share Read Endpoints (Public)

A File Share is the durable successor to QuickShare — a long-lived, link-shareable view of one workspace file. These public read endpoints serve the link viewer. They are anonymous-allowed where the access tier (anyone_with_link) permits; for any_registered / named_people the caller must present a bearer token and have sufficient access. A link password, if set, is presented via the x-ve-password request header (never in the URL). The bound file is read from the File Share record, so a caller can never substitute a different node id. Bandwidth is metered to the owning organization (no per-link transfer cap). Management endpoints (create / list / update / delete / grants) are in the Workspaces reference.

GET /current/fileshare/{fileshare_id}/details/                                       -- viewer metadata + bound file info
GET /current/fileshare/{fileshare_id}/storage/metadata/details/                      -- the bound file's metadata pointer: node, template, extraction eligibility; no field values (view capability)
GET /current/fileshare/{fileshare_id}/storage/read/                                  -- download the bound file (download capability)
GET /current/fileshare/{fileshare_id}/storage/preview/{preview_type}/read/           -- preview (view capability)
GET /current/fileshare/{fileshare_id}/storage/preview/{preview_type}/read/{download_token}/file/{filename}  -- preview sub-file
GET /current/fileshare/{fileshare_id}/storage/versions/                              -- list the bound file's version history (view capability)
GET /current/fileshare/{fileshare_id}/storage/versions/{version_id}/read/            -- download a specific version (download capability)

Details Response

{
  "result": true,
  "fileshare": {
    "fileshare": "1234567890123456789",
    "title": "Quarterly Presentation",
    "access_option": "anyone_with_link",
    "has_password": false,
    "effective_capability": "download",
    "file": {
      "id": "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4",
      "type": "file",
      "name": "presentation.pdf",
      "parent": "2ekc7-5efba-yapdo-psqmq-3ntiv-ri56",
      "version": "3u6cr-vxmyl-4y2pr-5jboz-afoke-k4s5",
      "created": "2026-01-28 10:00:00 UTC",
      "modified": "2026-01-28 12:30:00 UTC",
      "size": 5242880,
      "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "hash_algo": "sha256",
      "mimetype": "application/pdf",
      "mimecategory": "document",
      "previews": { "pdf": { "state": "ready" }, "thumbnail": { "state": "ready" } },
      "virus": { "status": "scanned", "infected": false },
      "summary": { "title": "Quarterly Presentation", "short": "Q4 results deck", "long": "..." },
      "metadata": { "title": null, "short": null }
    }
  }
}

The bound file object carries the same fields as a workspace file-node detail (see Node Details in this reference): a viewer of the share sees that one file's full info — versioning, previews, summary, metadata, and provenance — exactly as it appears in the workspace. The share-level effective_capability (view / download / edit) reflects the highest capability the access tier / grant / password admit for the calling viewer.

One field follows effective_capability: embedded file metadata. file_attributes.exif_metadata and file_attributes.media_metadata are read out of the file's own bytes, so they are served only to a viewer who may download it. A view-only viewer receives file_attributes as an empty object {} (keys omitted, not null, not an error) — on details, on versions, and on the nested node object the metadata endpoint returns; download and edit viewers receive the metadata. See Embedded File Metadata.

Metadata Response

GET /current/fileshare/{fileshare_id}/storage/metadata/details/ identifies the bound file's metadata — which node it is, which template governs it, and whether the file is eligible for automatic extraction. It returns no metadata field VALUES. View capability; the node is the bound file (never a caller-supplied node id).

{
  "result": true,
  "object_id": "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4",
  "template_id": "cl4ev-5j54o-cladr-lnyuj-2lcub-gqjm",
  "node_id": { "id": "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4", "type": "file", "name": "presentation.pdf", "parent": "2ekc7-5efba-yapdo-psqmq-3ntiv-ri56", "mimetype": "application/pdf" },
  "autoextractable": true
}

Those five keys are the entire response — there is no sixth. template_id is null when the bound file is mapped to no template. Do not code against an instance_id here either: the workspace metadata endpoint returns one, this endpoint deliberately does not, because it names the workspace the link was cut from.

No metadata VALUE crosses a File Share link, and that is deliberate. A link admits anonymous recipients, while the values are the file’s own contents and the field names are the owning team’s private vocabulary — so this surface serves neither corpus. metadata_facts is absent (see Extracted Metadata Facts): absent here, absent on the nested node object this endpoint returns, and absent on every other File Share surface. The legacy template_metadata / custom_metadata key/value sets are absent too — those blocks have been withdrawn from every Fastio response, on this surface and in the workspace alike. This is the settled end state, not a temporary restriction; a recipient sees no metadata values, and nothing is queued to bring them back, so do not build a viewer that waits for them. A workspace member reading the same file through the workspace endpoint gets its facts — see Get file metadata in the AI & Metadata reference.

Preview types match the storage preview surface (thumbnail, image, pdf, mp4, hlsstream, etc.); multi-file previews (e.g. HLS) return a 307 Temporary Redirect to a sub-file endpoint. Version listing is read-only — there is no restore/promote on the public surface; each entry carries the same per-version fields as a workspace version listing.

Error Responses

File Share Note Endpoints (Collaborative Editing)

When a File Share's bound node is a note (a markdown .md node), recipients can read — and, with an edit-capable grant, collaboratively edit — the note through the File Share link. These endpoints back the real-time collaborative editor. The flow is two-step:

1. Mint a realtime-note token (realtime/note-auth) with a normal signed-in File Share credential. The token is bound to this File Share and this note, and it carries either view or edit standing.
2. Read / update the note content with that token in the Authorization: Bearer header. readnote and updatenote are token-only — they accept the realtime-note token, not a workspace user JWT (an external File Share recipient is not a workspace member).

The bound note id is fixed on the File Share record; a caller can never substitute a different node id. Bandwidth is metered to the owning organization.

Mint Realtime-Note Token

Auth required. The caller must be signed in (an anonymous anyone_with_link visitor cannot mint a token) and must pass the File Share's own access gate (access tier + named grant + link password). A link password, if set, is presented via the x-ve-password request header. The minted token's standing is capped at the caller's effective capability: an edit grant mints an edit token (permits updatenote); a view / download grant mints a view token (read-only). A read-only scoped access token also caps the result to view.

curl Example

curl -X GET "https://api.fast.io/current/fileshare/1234567890123456789/realtime/note-auth/2ik5q-a43cm-uixi2-van5r-3eolo-7mue/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "x-ve-password: {link_password_if_set}"

Response

{
  "result": true,
  "expires_in": 3600,
  "auth_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response Fields

Error Responses

Read Note (File Share)

Token-only. Present the realtime-note token (from note-auth) as the Authorization: Bearer credential. There is no session fallback on this surface. An optional version_id query parameter reads a specific version.

curl Example

curl -X GET "https://api.fast.io/current/fileshare/1234567890123456789/storage/readnote/2ik5q-a43cm-uixi2-van5r-3eolo-7mue/" \
  -H "Authorization: Bearer {realtime_note_token}"

Error Responses

Update Note (File Share)

Token-only. Present a realtime-note token that carries edit standing (a view token is rejected 403). name and content must be supplied in the POST body (they are body-only — a write field in the query string is rejected).

Request Body (form-encoded)

At least one of name or content is required.

curl Example

curl -X POST "https://api.fast.io/current/fileshare/1234567890123456789/storage/updatenote/2ik5q-a43cm-uixi2-van5r-3eolo-7mue/" \
  -H "Authorization: Bearer {realtime_note_edit_token}" \
  -d 'content=# Updated Notes\n\nRevised content here.'

Error Responses

File Locking

Lock a file to prevent concurrent edits. Locks expire automatically if not renewed via heartbeat. Available on both workspace and share storage.

Acquire Lock

Auth required. Permission: Guest (workspace), file modification permission (share).

Request Body (form-encoded)

curl Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/storage/2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4/lock/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'duration=300' \
  -d 'client_info={"device_name":"My Laptop","client_version":"2.1.0"}'

Response

{
  "result": true,
  "lock_token": "unique_lock_token_string",
  "locked_at": "2025-01-28 10:00:00 UTC",
  "expires_at": "2025-01-28 10:05:00 UTC",
  "node_id": "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4"
}

Response Fields

Error Responses

Heartbeat (Extend Lock)

Auth required. Permission: Guest (workspace), file modification permission (share).

Request Body (form-encoded)

curl Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/storage/2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4/lock/heartbeat/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'lock_token=unique_lock_token_string'

Response

{
  "result": true,
  "expires_at": "2025-01-28 10:10:00 UTC",
  "time_remaining": 300
}

Error Responses

Notes:

• A heartbeat renews the lock for the same duration it was acquired with. A lock taken for an hour is renewed for another hour, not shortened to some fixed amount. The renewal replaces the time still remaining rather than adding to it, so expires_at always comes back as roughly now plus that duration.
• Send heartbeats well before the lock expires (e.g., at 50% of lock duration).
• Heartbeats can recreate a lock that has already expired — the lock_token is what is checked. Any authorized caller presenting the correct token recreates it, and the recreated lock is then held by that caller, so treat the token as a secret. A recreated lock starts a fresh lease at the service default duration, not at the duration the original lock was acquired with — the expired lock is gone and its duration cannot be recovered, and this endpoint accepts no duration. Read expires_at from the response rather than assuming, and re-acquire with an explicit duration if you need a longer lease again.

Release Lock

Auth required. Permission: Guest (workspace), file modification permission (share).

Request Body/Query

Response

{
  "result": true,
  "released": true
}

Error Responses

Lock Status

Auth required. Permission: Guest (workspace), file view permission (share).

Error Responses

The holder’s identity requires MEMBER level or above. locked and node_id are returned to every caller who may reach the endpoint — a client that cannot see them will offer a busy node as editable. The remaining fields (locker_uid, locked_at, expires_at, locker, and time_remaining on workspaces) identify who holds the lock and when they started and stopped working, and are returned only to callers at member level or above. Below that — workspace guests, share guests, public-link recipients — those keys are absent, exactly as lock_info is null on the node object for the same callers. Read locked for occupancy and treat the identity keys as optional; do not infer “unlocked” from a missing locker_uid.

locker.agent_name names the agent that took the lock on the holder’s behalf, when one did, and locker.agent_name_source says where that name came from; both are null when a person took the lock directly. agent_name is self-declared, not verified — display it beside the holder, never rely on it to identify or authorize anyone.

🔴 The name belongs to the CREDENTIAL, not to the lock. It is read from the credential that took the lock — a JWT claim (agent_name_source: "jwt_claim") or the API key’s own label ("api_key_label") — and it is set once, when you sign in or mint the key. There is no per-lock parameter for it, and nothing you send at acquire time can set, override, or suppress it. Two consequences worth designing around: every lock taken by one credential carries the same label, and a credential with no agent name produces null on every lock it takes, forever, until the credential itself is changed. If you want a lock to show an agent name, that decision happens at sign-in or key creation — not at the lock call.

This block carries no display_name; read the node object’s lock_info.locker when you need the holder’s name.

Response (locked, member or above)

{
  "result": true,
  "locked": true,
  "node_id": "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4",
  "locked_at": "2025-01-28 10:00:00 UTC",
  "expires_at": "2025-01-28 10:05:00 UTC",
  "time_remaining": 245,
  "locker_uid": "1234567890123456789",
  "locker": {
    "agent_name": "Claude-2",
    "agent_name_source": "api_key_label"
  }
}

Response (locked, below member)

{
  "result": true,
  "locked": true,
  "node_id": "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4"
}

Response (unlocked)

{
  "result": true,
  "locked": false
}

Override Lock

Auth required. Permission: Guest (workspace), file modification permission (share) — the same bar as writing the file.

Takes the lock over from whoever holds it, without their lock_token, and gives it to you. Use it when a collaborator left a file locked and is no longer editing. Anyone who can write the file can override its lock: the lock is advisory and expires on its own, so it never granted exclusive write rights, and requiring more than write access to take it over would protect nothing.

This is a TAKEOVER, not a release — you end up holding the lock. The response carries a new lock_token that is yours: heartbeat it and release it exactly as if you had acquired it. The displaced holder’s token stops working immediately; their next heartbeat is refused with 1680 (Access Denied), which is how their client learns a person took the file rather than that their own lock lapsed. That refusal holds even after you release the lock again — for the remainder of the lifetime their own lock had left — so a slow or paused client cannot quietly pick the file back up.

Overriding does NOT let you overwrite someone else’s changes, and must not be presented to a user as “force save”. A lock and a version precondition are different protections. The override takes the lock; it does not waive if_version_id. An update sent afterwards with a stale if_version_id still fails with the same 409 conflict it would have returned before the override — see Conflict Response above. To save after an override, re-read the file, rebase onto the current version_id, and send that.

Overriding a file that is not locked also succeeds — you simply acquire it, and overridden is false. Overriding a lock you already hold is also safe: you keep your existing lock_token, nothing is displaced, and your in-flight heartbeat keeps working. A retry is therefore harmless. Every override is recorded as an event on the owning workspace or share, naming who overrode and which file, and is readable through the events API. The displaced holder is deliberately NOT named in that event: their identity requires member level, while the event itself is readable one tier below that, so it is recorded internally rather than published.

No request body.

curl Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/storage/2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4/lock/override/" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": true,
  "lock_token": "unique_lock_token_string",
  "node_id": "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4",
  "locked_at": "2025-01-28 10:03:12 UTC",
  "expires_at": "2025-01-28 10:08:12 UTC",
  "overridden": true,
  "previous_locker_uid": "1234567890123456789"
}

Response Fields

Error Responses

Notes:

• After overriding, heartbeat the returned lock_token on the usual schedule — it is an ordinary lock with an ordinary expiry.
• A client that has its heartbeat refused with 1680 (Access Denied) should stop editing and re-read the file: someone took the lock. That is different from 1609 (Not Found) on heartbeat, which means the lock lapsed and can be re-acquired.

Previews

File previews provide rendered views of documents, images, video, and other content without downloading the original file.

Preview Types

Preview States

Returned in node details responses under previews.{type}.state:

Preauthorize Preview

Auth required. Permission: View (workspace), file view permission (share).

Path Parameters

curl Example

curl -X GET "https://api.fast.io/current/workspace/1234567890123456789/storage/2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4/preview/thumbnail/preauthorize/" \
  -H "Authorization: Bearer {jwt_token}"

Response

{
  "result": true,
  "downloadToken": "eyJhbGciOiJIUzI1NiJ9...",
  "path": "/current/workspace/.../preview/thumbnail/read/eyJhbGci.../file/preview.png",
  "primaryFilename": "preview.png"
}

Response Fields

Error Responses

Read Preview

Auth required.

Token-Based Preview Read

Path Parameters

Range requests are supported, with the same semantics as the file read endpoint above: 206 Partial Content with Content-Range for a satisfiable range, 416 for a range that starts at or past the end, 200 with the whole body for an unparseable Range header, and GET only (HEAD returns 405).

The download token is not single-use — it stays valid for its lifetime, so a client may issue many ranged requests against the same URL. Note that the size being ranged over is the preview artifact's, which is not the source file's size unless the preview is served as the original (as it is for a PDF preview of a PDF).

Request Preview Nonce (Share Only)

Auth required. File-view permission on the share.

curl Example