Files API

Store and organize files and folders, tag them, leave notes on them, build photo albums, run searches, create and manage share links (including who has joined one), manage workspaces and invitations, and receive signed webhooks. Uses a files key.

It calls the same code as the website and the phone apps. A few things only a signed-in person can do are listed below.

Base   https://dev.bodek.us/v1/files
Auth   Authorization: Bearer bf_live_…

Every path on this page is shown with the full gateway prefix, e.g. GET /v1/files/files/{id} is https://dev.bodek.us/v1/files/files/{id}.

A key is bound to one workspace (your personal workspace, or an organization) and acts as the person who created it. Everything the key reads or writes lives in that workspace. If that person later leaves the workspace, the key stops working (401 token_orphaned).

A key can also be folder-scoped: it then only sees that folder and everything beneath it. Ids outside the folder answer 404 not_found (never 403, so the key can't probe for them), calls that would default to the workspace root use the scope folder instead, and anything that would write outside the folder answers 403 out_of_scope.

Switching from the old endpoint? Replace file.bodeksolutions.com/api/v1 with dev.bodek.us/v1/files — resource paths are identical. The same key also works directly against the files origin, https://files.bodek.us/api/v1, which is the better choice for very large transfers (see Chunked uploads).

Tags, notes, albums & sharing

Tick these scopes when you create a key, or add them to an existing key with Edit scopes in the console. The token stays the same.

To do thisScopeReference
List tags, find files by tagtags:readTags
Create tags; tag one file or 500tags:writeTags
Sort a folder and filter it by tagfiles:readFiles
Read notesnotes:readNotes
Write, edit and delete notesnotes:writeNotes
Read albums; sort and filter their photosalbums:readAlbums
Create albums, add and remove photosalbums:writeAlbums
Upload a new photo into an albumfiles:write + albums:writeUpload into an album
Turn downloads off, let visitors contributeshare:writeShare links
Manage an organization's membersiam:read / iam:writeMembers & invites
See who opened or joined a shareshare:readWho has a share

Not available to keys, because a key is bound to its own workspace: joining or leaving somebody else's share, and uploading or leaving notes through somebody else's share link. People do those on the website or in the apps. Album chat, reactions and face management aren't in the API either.

Read notes, tags & albums

A key with files:read can read all of it; no other scope is needed. Downloading a file does not include its notes or tags. They are stored with the file's record, not inside its bytes, so a download (or a ZIP) is only the original content. Fetch them alongside it:

To getCall
The file's bytesGET /v1/files/files/{id}/content
Its tags, and how many notes it hasGET /v1/files/files/{id} (tags, notes)
The text of its notesGET /v1/files/files/{id}/notes
The same for a whole folderGET /v1/files/files?parent_id={id}, then /notes for each file with notes above 0
Every file with a tagGET /v1/files/tags/search?tags={name}
Your albumsGET /v1/files/albums
An album's photos, with their tags and note countsGET /v1/files/albums/{id}/items

One file: content, tags and notes

KEY=bf_live_XXXX
ID=AbCd1234
API=https://dev.bodek.us/v1/files

curl -sS -H "Authorization: Bearer $KEY" "$API/files/$ID/content" -o "$ID.bin"
curl -sS -H "Authorization: Bearer $KEY" "$API/files/$ID"         -o "$ID.info.json"
curl -sS -H "Authorization: Bearer $KEY" "$API/files/$ID/notes"   -o "$ID.notes.json"

The two JSON files look like this:

// AbCd1234.info.json
{ "data": { "id": "AbCd1234", "name": "report.pdf", …,
            "tags": [{ "id": 11, "name": "Tax 2026", "slug": "tax 2026", "color": null }],
            "notes": 1 } }

// AbCd1234.notes.json
{ "data": [{ "id": "fd0560425dcc", "text": "This is the signed copy.", "by": 42, "by_name": "Dana Levi",
             "at": "2026-11-22T15:54:09+00:00", "via": "web", "edited_at": null }] }

A whole folder, subfolders included

Needs curl and jq. Prints one JSON line per file. Every call counts toward the key's rate limits.

KEY=bf_live_XXXX
API=https://dev.bodek.us/v1/files
get() { curl -fsS -H "Authorization: Bearer $KEY" "$API$1"; }

walk() {
  local parent=$1 offset=0 page row id notes
  while [ "$offset" != null ]; do
    page=$(get "/files?parent_id=$parent&limit=100&offset=$offset") || return 1
    while read -r row; do
      id=$(jq -r .id <<<"$row")
      if [ "$(jq -r .type <<<"$row")" = folder ]; then
        walk "$id" || return 1
        continue
      fi
      notes='[]'
      if [ "$(jq -r .notes <<<"$row")" -gt 0 ]; then
        notes=$(get "/files/$id/notes" | jq -c .data) || return 1
      fi
      jq -c --argjson notes "$notes" '{id, name, tags: [.tags[].name], notes: $notes}' <<<"$row"
    done < <(jq -c '.data[]' <<<"$page")
    offset=$(jq -r '.meta.next_offset' <<<"$page")
  done
}

walk ""   # "" is the top of the workspace; or pass a folder id

A copy made with POST …/copy is a new file and starts without the original's notes and tags.

Conventions

Requests

Request bodies are JSON (Content-Type: application/json) except for the simple upload (multipart) and upload chunks (raw bytes or multipart). File and folder ids are 8-character strings such as AbCd1234.

Responses

Successful responses wrap the payload in data; list endpoints add meta. DELETE endpoints return 204 with no body.

{
  "data": [ { "id": "AbCd1234", "type": "file", "name": "report.pdf", … } ],
  "meta": { "total": 134, "offset": 0, "limit": 20, "next_offset": 20 }
}

Pagination

List endpoints use offset pagination: limit (1–100, default 20) and offset (default 0). meta.next_offset is the offset of the next page, or null on the last page. A single folder listing returns at most 5,000 items in total.

Errors

Errors carry a stable machine code, a human message, and sometimes details:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This key needs the scope: files:write",
    "details": { "required": ["files:write"] }
  }
}

Unexpected failures return 500 internal_error with details.request_id. See Error codes for the full list.

Response headers

HeaderMeaning
X-Request-IdUnique id for this request. Quote it in bug reports.
X-RateLimit-Limit-MinuteYour key's per-minute cap.
X-RateLimit-Remaining-MinuteRequests left in the current minute.
X-RateLimit-Reset-SecondsSeconds until the minute window resets.
X-RateLimit-Limit-DayYour key's cap over a rolling 24 hours.
X-RateLimit-Remaining-DayRequests left in the rolling 24 hours.

Rate limits

Every authenticated request counts once against both caps — including each upload chunk. Going over either cap returns 429 rate_limited with details.limit; wait for the window to reset.

Expensive endpoints have additional limits on top of your key's caps, counted per key and per user (across all of the user's keys). Going over returns 429 rate_limited with a Retry-After header.

EndpointPer keyPer user
GET /search60 / minute120 / minute
POST /files/{id}/copy, /compress, /unzip (combined)30 / 10 minutes60 / 10 minutes
POST /uploads (open a session)300 / 10 minutes600 / 10 minutes
POST /workspaces/{id}/members, POST /iam/members (invitation emails)20 / hour per user; 100 / day per workspace; 3 / day per recipient

Request bodies

JSON bodies are limited to 1 MB (413 body_too_large). String fields must be JSON strings; ids in the path must be well-formed or the call returns 404.

Keys, accounts and browsers

A key acts as the account that created it, with that account's current role. It stops working (401) when the key is revoked or expires, when the account is removed from the workspace (token_orphaned) or disabled (account_disabled), and returns 402 subscription_required / plan_upgrade_required while the account's subscription is inactive. test and live keys currently have identical access to the same data — the prefix is a label only.

Browser calls are allowed from any origin via CORS (Access-Control-Allow-Origin: *); credentials (cookies) are never accepted — only the Authorization header authenticates. A key's domains restriction checks the Origin (or Referer) header, matching a listed host exactly or, for *.example.com, that host and its subdomains; those headers are set by browsers but can be forged by other clients, so for server-side keys prefer the IPs restriction (IPv4 and IPv6 addresses and CIDR ranges).

The file object

Files and folders share one shape. Folders have "type": "folder".

{
  "id": "AbCd1234",
  "type": "file",                     // "file" | "folder"
  "name": "report.pdf",
  "parent_id": "FoLd5678",            // null = workspace root
  "size": 48213,                      // bytes; always 0 for folders
  "mime_type": "application/pdf",
  "extension": "pdf",
  "has_thumbnail": false,
  "share_status": "private",          // "private" | "public" | "limited"
  "share_url": "https://files.bodek.us/sl/AbCd1234",
  "share_active": false,              // true when the link currently opens the file
  "shared_with": null,                // comma-separated emails for "limited" shares
  "share_password_protected": false,
  "share_expires_at": null,           // ISO 8601 or null
  "share_allow_download": true,
  "share_allow_edit": false,
  "tags": [{ "id": 11, "name": "Tax 2026", "slug": "tax 2026", "color": null }],
  "notes": 2,                         // how many, not the text
  "created_at": "2026-09-01 12:00:00",
  "updated_at": "2026-09-01 12:00:00"
}

tags and notes are included by get, list, search and tag search. Responses to changes, and webhook payloads, leave them out.

share_url is always present — it's derived from the id — but only opens the file while share_active is true.

Files

List files

GET /v1/files/files

Scope files:read. Lists the direct contents of a folder, folders first.

QueryDescription
parent_idFolder to list. Omit for the workspace root (or the scope folder, for a folder-scoped key).
qCase-insensitive name filter within this folder. For a workspace-wide search use /search.
sortname_asc (default), name_desc, created_asc, created_desc, size_asc or size_desc. Folders always come first.
tagsComma-separated tag names. Only files carrying all of them are returned; folders are never filtered out.
limit / offsetPagination (see Conventions).
curl "https://dev.bodek.us/v1/files/files?parent_id=FoLd5678&limit=50" \
  -H "Authorization: Bearer bf_live_XXXX"
{
  "data": [ { "id": "AbCd1234", "type": "file", "name": "report.pdf", … } ],
  "meta": { "total": 1, "offset": 0, "limit": 50, "next_offset": null }
}

Errors: 404 folder_not_found, 400 not_a_folder.

Get a file

GET /v1/files/files/{id}

Scope files:read. Returns one file object. Works for folders too. Errors: 404 not_found.

Download content

GET /v1/files/files/{id}/content

Scope files:read. Streams the raw bytes with Content-Disposition: attachment. Requesting a folder returns 400 not_a_file. Byte-range requests (Range) are honoured; the gateway forwards Range and relays 206/Content-Range. For very large downloads call the files origin directly (https://files.bodek.us/api/v1) to avoid the gateway's 60-second limit.

curl -L -o report.pdf https://dev.bodek.us/v1/files/files/AbCd1234/content \
  -H "Authorization: Bearer bf_live_XXXX"

Upload a file

POST /v1/files/files

Scope files:write. One-shot multipart/form-data upload, up to 5 GB. For large files or unreliable networks use chunked uploads instead.

FieldDescription
fileRequired. The file.
parent_idDestination folder. Defaults to the root (or the scope folder).
nameOptional name override.
curl -X POST https://dev.bodek.us/v1/files/files \
  -H "Authorization: Bearer bf_live_XXXX" \
  -F "file=@report.pdf" -F "parent_id=FoLd5678"

Returns 201 with the new file object and fires file.created. Errors: 400 missing_file, 400 upload_failed, 400 file_type_blocked, 404 folder_not_found, 413 quota_exceeded. File and folder names can't contain /, \ or control characters (400 invalid_name).

Rename or move

PATCH /v1/files/files/{id}

Scope files:write. Send name, parent_id (null = workspace root), or both. Works for files and folders.

curl -X PATCH https://dev.bodek.us/v1/files/files/AbCd1234 \
  -H "Authorization: Bearer bf_live_XXXX" -H "Content-Type: application/json" \
  -d '{ "name": "report-final.pdf" }'

Returns the updated file object; fires file.renamed and/or file.moved. Errors: 400 no_changes, 400 invalid_name, 400 file_type_blocked, 400 not_a_folder, 400 invalid_move, 403 out_of_scope, 404 folder_not_found.

Move

POST /v1/files/files/{id}/move

Scope files:write. Like PATCH with parent_id, but reports refusals from the storage layer (e.g. not enough space when moving between workspaces) instead of ignoring them.

curl -X POST https://dev.bodek.us/v1/files/files/AbCd1234/move \
  -H "Authorization: Bearer bf_live_XXXX" -H "Content-Type: application/json" \
  -d '{ "parent_id": "FoLd5678" }'

Returns the moved file object; fires file.moved. Errors: 400 missing_parent_id, 400 not_a_folder, 400 invalid_move, 400 move_failed, 403 out_of_scope, 404 folder_not_found, 413 quota_exceeded.

Copy

POST /v1/files/files/{id}/copy

Scope files:write. Duplicates a file, or a folder with everything inside it. Copies start out private (share settings are not copied).

BodyDescription
parent_idDestination folder, or null for the root. Omit to copy next to the original.
nameName for the copy. Defaults to the original name.
curl -X POST https://dev.bodek.us/v1/files/files/AbCd1234/copy \
  -H "Authorization: Bearer bf_live_XXXX" -H "Content-Type: application/json" \
  -d '{ "parent_id": "Arch1ve0", "name": "report-2026.pdf" }'

Returns 201 with the new file object; fires file.created (or folder.created). Errors: 400 invalid_copy, 400 invalid_name, 400 not_a_folder, 400 copy_failed, 403 out_of_scope, 404 folder_not_found, 413 quota_exceeded, 413 too_many_items (a folder with more than 10,000 items inside), 429 rate_limited.

Compress to .zip

POST /v1/files/files/{id}/compress

Scope files:write. No body. Zips a file or folder into <name>.zip next to the original. Returns 201 with the archive's file object; fires file.created. A folder-scoped key cannot compress its scope folder itself (403 out_of_scope, the archive would land outside it). Limits: at most 10,000 items and 10 GB of input, and no more than the workspace's free space. Other errors: 400 compress_failed, 413 quota_exceeded, 413 too_many_items, 413 too_large, 429 rate_limited.

curl -X POST https://dev.bodek.us/v1/files/files/FoLd5678/compress \
  -H "Authorization: Bearer bf_live_XXXX"

Extract a .zip

POST /v1/files/files/{id}/unzip

Scope files:write. No body. Extracts a .zip into a new folder named after the archive, next to it. Blocked file types inside the archive are skipped; extraction stops early if the workspace runs out of space. Entry paths are always kept inside the new folder (../ and absolute paths are stripped; symlink entries are stored as plain files). Before extracting, the archive is checked: at most 10,000 entries and 10 GB uncompressed, no more than the workspace's free space, and no control characters in entry names.

{
  "data": { "id": "NeWf0ldr", "type": "folder", "name": "photos", … },
  "meta": { "message": "Extracted 42 item(s)." }
}

Returns 201; fires folder.created. Errors: 400 not_a_file, 400 not_a_zip, 400 unzip_failed, 400 invalid_archive, 413 quota_exceeded, 413 too_many_items, 413 too_large, 429 rate_limited.

Compress, extract and folder downloads run synchronously. The gateway waits up to 60 seconds; for very large folders call the files origin directly.

Delete

DELETE /v1/files/files/{id}

Scope files:delete. Deletes a file, or a folder and everything inside it. Deletion is permanent — there is no trash to restore from. Returns 204; fires file.deleted with a snapshot of the item.

Folders

Folders are files with type: "folder", so every /files endpoint above also works on them. The /folders/{id} routes additionally reject file ids with 400 not_a_folder.

Create a folder

POST /v1/files/folders

Scope folders:write.

curl -X POST https://dev.bodek.us/v1/files/folders \
  -H "Authorization: Bearer bf_live_XXXX" -H "Content-Type: application/json" \
  -d '{ "name": "Invoices", "parent_id": null }'

Returns 201 with the folder; fires folder.created. Errors: 400 invalid_name, 400 not_a_folder, 404 folder_not_found.

Get a folder

GET /v1/files/folders/{id}

Scope files:read. The file object plus total_size (bytes in the whole subtree), item_count (direct children) and path (breadcrumbs from the top — for a folder-scoped key, from the scope folder).

{
  "data": {
    "id": "FoLd5678", "type": "folder", "name": "Invoices", "parent_id": "Acc0unts", …,
    "total_size": 1843200,
    "item_count": 12,
    "path": [ { "id": "Acc0unts", "name": "Accounts" }, { "id": "FoLd5678", "name": "Invoices" } ]
  }
}

List a folder

GET /v1/files/folders/{id}/children

Scope files:read. Same query parameters, response and paging as GET /v1/files/files?parent_id={id}.

Rename or move a folder

PATCH /v1/files/folders/{id}

Scope files:write. Same body and behavior as PATCH /files/{id}.

Delete a folder

DELETE /v1/files/folders/{id}

Scope files:delete. Permanently deletes the folder and its contents. Returns 204.

Chunked uploads

Resumable uploads for large files (up to 100 GB). Open a session, send the file in fixed-size chunks (in any order, in parallel if you like), then complete it. If the connection drops, ask which chunks are missing and resend only those. All routes need scope files:write. Sessions belong to the key's user, workspace and folder scope; a session with no activity for 7 days is deleted.

1. Open a session

POST /v1/files/uploads
BodyDescription
nameRequired. File name.
sizeRequired. Total size in bytes.
parent_idDestination folder. Defaults to the root (or scope folder).
curl -X POST https://dev.bodek.us/v1/files/uploads \
  -H "Authorization: Bearer bf_live_XXXX" -H "Content-Type: application/json" \
  -d '{ "name": "video.mp4", "size": 734003200, "parent_id": "FoLd5678" }'
{
  "data": {
    "upload_key": "9f2c4e1a0b7d4c3e8a6f5b2d1c0e9f8a",
    "name": "video.mp4", "size": 734003200, "parent_id": "FoLd5678",
    "chunk_size": 5242880, "total_chunks": 140,
    "missing_chunks": [0, 1, 2, …, 139],
    "resumed": false
  }
}

Returns 201. Opening a session with the same name, size and folder as an unfinished one resumes it instead: 200, "resumed": true, and missing_chunks lists only what is still needed. Always use the returned chunk_size (5 MB, 16 MB above 1 GB, 32 MB above 20 GB).

Errors: 400 invalid_name, 400 invalid_size, 400 invalid_upload, 400 file_type_blocked, 400 not_a_folder, 404 folder_not_found, 413 quota_exceeded, and 429 upload_queue_full when too many bytes are already in flight for this account — retry after the Retry-After header (also in details.retry_after_ms).

2. Send chunks

POST /v1/files/uploads/{upload_key}/chunk?index={n}

Send chunk n (zero-based) as the raw request body, or as a multipart field named chunk (with index as a form field). Every chunk must be exactly chunk_size bytes except the last one.

# chunk 0 of a file split with: split -b 5242880 -d -a 4 video.mp4 part.
curl -X POST "https://dev.bodek.us/v1/files/uploads/9f2c…9f8a/chunk?index=0" \
  -H "Authorization: Bearer bf_live_XXXX" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @part.0000
{ "data": { "upload_key": "9f2c…9f8a", "index": 0, "received": true, "duplicate": false, "complete": false } }

complete turns true once every chunk has arrived. Resending a chunk that was already stored is harmless ("duplicate": true). Errors: 400 invalid_index, 400 empty_chunk, 400 chunk_rejected (wrong size, index out of range, session no longer open), 410 upload_gone.

3. Check progress (optional)

GET /v1/files/uploads/{upload_key}
{
  "data": {
    "upload_key": "9f2c…9f8a", "status": "open", "name": "video.mp4", "size": 734003200,
    "parent_id": "FoLd5678", "chunk_size": 5242880, "total_chunks": 140,
    "received_chunks": 138, "missing_chunks": [17, 93],
    "created_at": "2026-09-23 10:00:00"
  }
}

Errors: 410 upload_gone (unknown, finished, aborted or expired session).

4. Complete

POST /v1/files/uploads/{upload_key}/complete

Assembles the file and returns 201 with the new file object; fires file.created. Thumbnails and metadata are generated in the background right after. Errors: 409 incomplete_upload (with details.missing_chunks), 413 quota_exceeded, 400 complete_failed (safe to retry), 410 upload_gone.

Abort

DELETE /v1/files/uploads/{upload_key}

Discards the session and any chunks received. Returns 204.

Each chunk is one request against your rate limit. For multi-gigabyte files, calling the files origin directly (https://files.bodek.us/api/v1/uploads…, same key) avoids the gateway's 60-second per-request limit on slow links.

Share links

A share link (https://files.bodek.us/sl/{file_id}) is either private (off), public (anyone with the link) or limited (only listed emails, after they verify their address). Links can carry a password and an expiry, after which they revert to private.

The share object

{
  "file_id": "AbCd1234",
  "status": "public",
  "url": "https://files.bodek.us/sl/AbCd1234",
  "share_active": true,
  "shared_with": null,
  "share_password_protected": true,
  "share_expires_at": "2026-12-31T23:59:59+00:00",
  "allow_download": false,            // view only: no download, no ZIP, no save
  "allow_edit": true,                 // folders only: visitors may contribute
  "perms": ["upload", "mkdir"]        // what contributors may do
}

Downloads are their own setting

allow_download: false is "people can look at this but not keep a copy". It applies to any share — a view-only one included — and it is enforced on the bytes, not just in the interface:

  • the file's own download, a folder's ZIP and an album's ZIP answer 403;
  • the raw endpoints serve only what a preview needs (images, video, audio, PDF, plain text) and refuse everything else;
  • the website hides every download and ZIP button, turns off the save-image menu, dragging an image out and printing;
  • the Android app marks the screen secure, so Android itself refuses a screenshot, a screen recording, a cast and the recents thumbnail. iOS cannot block a screenshot — it hides the content while the screen is recorded or mirrored, and covers it right after a screenshot.

Omit allow_download to leave the owner's choice alone: a call that only changes status must never reopen a share that was closed. Going private resets it to true, so the next share starts from "downloads allowed".

Before 22 November 2026 this setting did not exist, and "no downloads" could only be expressed as an editing share whose perms left download out — which meant every view-only share allowed downloads however the owner set it. Existing shares were migrated to the equivalent allow_download, and download inside perms is now kept in step with it automatically.

Create or change a share

POST /v1/files/shares

Scope share:write. Returns 201 with the share object; fires share.changed.

BodyDescription
file_idRequired.
statuspublic, limited or private. If omitted, a file that is already shared keeps its status and one that isn't becomes public.
emailsComma-separated addresses allowed to open a limited share (max 100). Omit to keep the current list. No email is sent to them — share the link yourself.
passwordOptional. Set a password; "" clears it; omit to keep the current one.
expires_atOptional. ISO 8601 or Y-m-d H:i:s; "" clears it; omit to keep.
allow_downloadOptional boolean. false = view only (see above). Omit to keep the current choice.
allow_editOptional boolean, folders only. true lets signed-in visitors contribute.
permsArray (or comma-separated) of what contributors may do: upload, mkdir, rename, move, copy, delete. Only read when allow_edit is sent; omit to keep the current ones.
curl -X POST https://dev.bodek.us/v1/files/shares \
  -H "Authorization: Bearer bf_live_XXXX" -H "Content-Type: application/json" \
  -d '{ "file_id": "AbCd1234", "status": "public", "password": "s3cret-pass", "expires_at": "2026-12-31T23:59:59Z" }'

Errors: 400 invalid_file_id, 400 invalid_status, 400 share_failed (e.g. password too short, expiry in the past, bad emails), 404 not_found.

Change share status

PATCH /v1/files/shares/{file_id}

Scope share:write. Same body as POST without file_id. status is only required when the file isn't shared yet; send just { "allow_download": false } to change that one setting. Returns 200 with the share object.

Read share status

GET /v1/files/shares/{file_id}

Scope share:read. Returns the share object.

Revoke a share

DELETE /v1/files/shares/{file_id}

Scope share:write. Sets the share to private and clears its password and expiry, and fires share.changed. Returns 204.

Who has a share

A share link used to be anonymous in both directions: the owner typed a list of addresses and then had no way of knowing whether anybody had opened it, and a recipient had no way of saying "yes, I'm in". These endpoints answer both.

The member object

{
  "email": "someone@example.com",   // the identity — what the owner typed
  "user_id": 42,                    // null until that address has an account
  "name": "Dana Levi",              // from the account, when there is one
  "avatar": null,
  "state": "joined",                // invited | viewed | joined | removed
  "has_account": true,
  "first_seen": "2026-11-20 14:01:52",
  "joined_at": "2026-11-20 14:02:11",
  "last_seen": "2026-11-22 09:31:40",
  "views": 7,
  "status_text": "Joined"           // one phrase, worded by the server
}
StateMeaning
invitedThe owner put this address on a limited share's list. Nobody has opened it yet.
viewedSomebody signed in as that address and opened the link.
joinedThey pressed Join: they mean to keep using it.
removedThe owner took the address off the list. The row is kept, so "joined then removed" is distinguishable from "never invited", and re-inviting restores their history. A removed address cannot join its way back on.

A public link has no invite list, so it has no invited rows: its members appear as they open it. Identity is the email address, not the user id, because that is what the owner types and because people are invited long before they have an account.

List a share's members

GET /v1/files/shares/{file_id}/members

Scope share:read. Returns the members, most recent activity first, with people who have not opened it yet at the end. meta carries the counts:

{
  "data": [ { … }, { … } ],
  "meta": { "total": 4, "joined": 2, "viewed": 1, "invited": 1, "removed": 0 }
}
GET /v1/files/albums/{id}/members

Scopes share:read + albums:read. The same list for an album.

Joining itself is something a person does in the website or an app, not something a key does on their behalf — joining says "this account has this", which an integration cannot truthfully assert for somebody else. Keys read the list.

Tags

A tag is part of how a workspace files its own content, and it is what a shared folder or album can then be sorted and filtered by. People you share with see tags and can filter by them; they cannot change them.

Tags are matched by a normalised form of their name, so Tax 2026, tax 2026 and TAX 2026 are one tag and the workspace keeps whichever capitalisation it typed first. Names are at most 48 characters; commas and slashes are collapsed to spaces (tag lists travel comma-separated). A workspace may define up to 2,000 tags and a file may carry up to 50.

The vocabulary belongs to the file's owner within a workspace, as in the apps. In an organization, /tags and /tags/search therefore cover the key creator's own tags and files, while the per-file endpoints work on colleagues' files too.

A folder-scoped key sees only tags used inside its folder, with counts for that folder. It can tag files there, but creating, renaming or deleting a tag as such answers 403 out_of_scope.

The tag object

{
  "id": 11,
  "name": "Tax 2026",
  "slug": "tax 2026",      // the matching key
  "color": "#00aa55",      // or null
  "use_count": 34          // files carrying it (a folder/album listing sends "count" instead)
}

List tags

GET /v1/files/tags

Scope tags:read (or files:read). Most used first. ?q= filters by substring for a type-ahead; ?limit= 1–500, default 100.

Create a tag

POST /v1/files/tags

Scope tags:write. Body { "name": "Tax 2026", "color": "#00aa55" } (color optional, #rrggbb; anything else is ignored rather than stored). Idempotent: a name that already exists returns 200 with the existing tag, a new one returns 201.

Read, rename, delete

GET /v1/files/tags/{id}
PATCH /v1/files/tags/{id}
DELETE /v1/files/tags/{id}

PATCH takes name and/or color ("" clears the color); renaming moves the matching key with it, and a name another tag already has answers 409. DELETE removes the tag and every attachment of it and answers 204 — the files themselves are untouched.

A file's tags

GET /v1/files/files/{id}/tags
POST /v1/files/files/{id}/tags
PUT /v1/files/files/{id}/tags
DELETE /v1/files/files/{id}/tags?tag={name}
DELETE /v1/files/files/{id}/tags/{tag}

Scopes tags:read (or files:read) to read, tags:write to change. POST adds to what is there; PUT replaces the set exactly; both take { "tags": ["Invoice", "Tax 2026"] } and create any tag that does not exist yet. To remove a tag by name use ?tag= (URL-encoded), or send { "tags": [...] } as the DELETE body for several. The path form takes an id, or a name made only of plain letters and digits: spaces, other alphabets and punctuation aren't accepted in a path. A name wins over an id when both match. Each returns the file's full tag list, so a client never has to guess; meta.added / meta.failed / meta.removed say what changed.

curl -X PUT https://dev.bodek.us/v1/files/files/AbCd1234/tags \
  -H "Authorization: Bearer bf_live_XXXX" -H "Content-Type: application/json" \
  -d '{ "tags": ["Invoice", "Tax 2026"] }'

Tag many files at once

POST /v1/files/tags/apply

Scope tags:write. Up to 500 files and 50 tags per call.

BodyDescription
file_idsRequired array of file or folder ids.
tagsRequired array of names. [] is allowed with replace, to clear.
modeadd (default), remove or replace.

data maps each file id to its tags afterwards. meta.refused lists ids the key can't reach and meta.failed any tags that couldn't be added. If no file could be changed the call answers 404.

curl -X POST https://dev.bodek.us/v1/files/tags/apply \
  -H "Authorization: Bearer bf_live_XXXX" -H "Content-Type: application/json" \
  -d '{ "file_ids": ["AbCd1234", "EfGh5678"], "tags": ["Invoice"], "mode": "add" }'

What is tagged where

GET /v1/files/folders/{id}/tags

Every tag carried by anything inside that folder, at any depth, each with a count — this is what a filter menu is built from.

GET /v1/files/albums/{id}/tags

The same for the photos in an album.

GET /v1/files/tags/search?tags=a,b

The key creator's files in this workspace carrying all of the named tags (AND, not OR — which is what picking two filters means). Paged with limit/offset; each item is a file object with its tags attached.

Notes

A note is a short piece of text somebody left on a file. It lives in the file's own metadata, so it stays with the file when it is moved or renamed. It is not part of the downloaded bytes: see Read notes, tags & albums.

Anyone who can reach a file may leave one — the owner, a colleague in the workspace, and somebody the file was shared with. That is the point of them: the person looking at a file saying something about it. Each note records who wrote it and by what route, so the owner can tell a note left through a share link from one they typed themselves. Notes are at most 2,000 characters (longer text is cut off) and a file holds at most 200, or 64 KB of text in all if that comes first (409). A key reaches notes only on files in its own workspace.

The note object

{
  "id": "fd0560425dcc",
  "text": "This is the signed copy.",
  "by": 42,                              // the account, or null if it is gone
  "by_name": "Dana Levi",                // kept with the note, so it survives the account
  "at": "2026-11-22T15:54:09+00:00",     // ISO 8601, UTC
  "via": "api",                          // web | app | api | share
  "edited_at": null
}
GET /v1/files/files/{id}/notes
POST /v1/files/files/{id}/notes
PATCH /v1/files/files/{id}/notes/{note_id}
DELETE /v1/files/files/{id}/notes/{note_id}

Scopes notes:read (or files:read) to list, notes:write to change. POST and PATCH take { "text": "…" }; a key writes as the account that created it, with via: "api".

Only the author may edit a note — a note rewritten by somebody else would still carry the original author's name (403 otherwise). Deleting is the author or the file's owner, who can always clear anything left on their own file.

curl -X POST https://dev.bodek.us/v1/files/files/AbCd1234/notes \
  -H "Authorization: Bearer bf_live_XXXX" -H "Content-Type: application/json" \
  -d '{ "text": "This is the signed copy." }'

Every file listing carries a notes count for a badge; the text is only in these endpoints, so a listing of 500 files does not ship every note of every one of them.

Albums

An album is a named set of photos and videos that already live in the workspace. Adding a photo to an album never moves or copies bytes — it records that the photo belongs to the album. Deleting an album leaves its photos in the library.

An album's share link is a token (/a/{token}), not the album id. The token is kept when you revoke, so sharing the album again brings the same link back to life.

Albums are workspace-wide by nature, so a folder-scoped key has no album access at all (403 out_of_scope): confining an album to one folder is not meaningful, and pretending otherwise would let a narrow key reach photos outside its scope.

The album object

{
  "id": "ExAlbum123",
  "title": "Summer trip",
  "kind": "manual",                 // manual | person (person albums resolve live from a face)
  "item_count": 184,
  "cover_file_id": "AbCd1234",
  "share_status": "public",
  "share_url": "https://files.bodek.us/a/ExampleToken",
  "is_person": false,
  "updated_at": "2026-11-22 15:53:40"
}

List and create

GET /v1/files/albums
POST /v1/files/albums

Scopes albums:read (or files:read) / albums:write. Only albums in the key's workspace. Paged with limit/offset; ?filter=shared lists only shared albums. POST takes { "title": "…", "file_ids": ["AbCd1234", …] } (file_ids optional).

Read, change, delete

GET /v1/files/albums/{id}
PATCH /v1/files/albums/{id}
DELETE /v1/files/albums/{id}

PATCH takes title and/or cover_file_id (a photo already in the album). DELETE answers 204 and leaves the photos alone.

The photos in an album

GET /v1/files/albums/{id}/items
POST /v1/files/albums/{id}/items
DELETE /v1/files/albums/{id}/items

GET is paged (limit/offset) and takes ?sort= date_desc (default), date_asc, added_desc, added_asc, name_asc, name_desc and ?tags=a,b (photos carrying all of them). Each item carries its tags and a notes count.

POST and DELETE take { "file_ids": [...] }. The photos must already be in the workspace; DELETE removes them from the album, never from the library. They return added / removed counts. A person album fills itself, so both answer 400 dynamic_album for one.

{
  "id": "AbCd1234", "name": "beach.jpg", "kind": "image", "mime": "image/jpeg",
  "size": 2481332, "thumb": "/thumb/AbCd1234", "width": 4032, "height": 3024,
  "duration": null,                 // milliseconds, for video
  "favorite": false, "place": null, "ts": "2026-07-14 16:20:05", "added_by": 42,
  "tags": [{ "id": 11, "name": "Best", "slug": "best", "color": null }],
  "notes": 1
}

Upload into an album

Two calls: upload the photo or video (POST /v1/files/files, or a chunked upload for a large one), then add the returned id. Files that aren't photos or videos are not added.

curl -X POST https://dev.bodek.us/v1/files/files \
  -H "Authorization: Bearer bf_live_XXXX" -F "file=@beach.jpg"

curl -X POST https://dev.bodek.us/v1/files/albums/ExAlbum123/items \
  -H "Authorization: Bearer bf_live_XXXX" -H "Content-Type: application/json" \
  -d '{ "file_ids": ["AbCd1234"] }'

Sharing an album

GET /v1/files/albums/{id}/share
PUT /v1/files/albums/{id}/share
DELETE /v1/files/albums/{id}/share

Scopes share:read / share:write. PUT takes the same settings as a file share — status, emails, password, expires_at, allow_download, allow_edit, perms — plus people_tab (whether visitors may browse the faces in it). Anything omitted stays as it is, status and emails included; status is required to share a private album. allow_download behaves exactly as it does for a file share, including what each app can and can't protect; see Downloads are their own setting. An album's contributor permissions are upload, rename, move, copy, delete and people_edit. Fires album.share_changed.

curl -X PUT https://dev.bodek.us/v1/files/albums/ExAlbum123/share \
  -H "Authorization: Bearer bf_live_XXXX" -H "Content-Type: application/json" \
  -d '{ "status": "limited", "emails": "a@example.com,b@example.com", "allow_download": false }'

Storage

GET /v1/files/storage

Scope workspace:read. Usage and limits for the key's workspace.

{
  "data": {
    "workspace_id": 12,
    "used": 5368709120, "limit": 107374182400, "unlimited": false,
    "remaining": 102005473280, "percent_used": 5,
    "used_human": "5 GB", "limit_human": "100 GB",
    "file_count": 1834, "folder_count": 97,
    "scope_folder_id": null, "scope_used": null,
    "max_upload_size": { "simple": 5368709120, "chunked": 107374182400 }
  }
}

used/limit are workspace-wide (limit is null when unlimited). file_count and folder_count cover what the key can see; for a folder-scoped key they, and scope_used, describe the scope folder's contents. max_upload_size is the per-file limit for the simple and chunked uploads.

Workspaces

File, share, webhook and member calls always act on the workspace the key is bound to. These endpoints read and manage workspaces. Scopes workspace:read / workspace:write.

The workspace object

{
  "id": 12,
  "name": "Acme Inc.",
  "type": "org",                       // "personal" | "org"
  "owner_id": 3,
  "storage": { "used": 5368709120, "limit": 107374182400, "unlimited": false },
  "role": "admin",                     // your role; only in GET /workspaces
  "created_at": "2026-01-15 09:30:00"
}

Current workspace

GET /v1/files/workspaces/current

The workspace this key is bound to, with human-readable storage figures (used_human, limit_human).

List workspaces

GET /v1/files/workspaces

Every workspace the key's user belongs to, with their role.

Create an organization

POST /v1/files/workspaces
curl -X POST https://dev.bodek.us/v1/files/workspaces \
  -H "Authorization: Bearer bf_live_XXXX" -H "Content-Type: application/json" \
  -d '{ "name": "Acme Inc.", "ein": "12-3456789" }'

Scope workspace:write. The caller becomes the owner; the key stays bound to its original workspace. Returns 201. Errors: 400 invalid_name, 400 create_failed, 403 org_limit_reached.

Get a workspace

GET /v1/files/workspaces/{id}

Any workspace the user is a member of; otherwise 404 workspace_not_found.

Rename a workspace

PATCH /v1/files/workspaces/{id}

Scope workspace:write; owner or admin only, and only for the workspace the key is bound to (403 cross_workspace otherwise). Folder-scoped keys can't rename workspaces (403 out_of_scope). Body { "name": "…" } (max 100 characters). Errors: 400 no_changes, 400 rename_failed, 403 not_admin.

Deleting a workspace is intentionally not available through the API; use the web app.

Members & invites

Organization-workspace members and invitations can be managed with a files key through these workspace-scoped aliases, or with an iam key through the IAM API. They take the same bodies and return the same shapes as the IAM endpoints. {id} must be the key's own workspace (403 cross_workspace otherwise), and the key needs the iam:read / iam:write scopes. Member writes and invitations need an admin or the owner; changing a role (and inviting someone as admin) is owner-only, as in the web app.

To get such a key, pick the organization as the key's workspace in the console and tick Members (it isn't part of “Select all”). On an existing key use Edit scopes. You must be the organization's owner or an admin to add them. Personal-workspace keys answer 400 not_an_org_workspace and folder-scoped keys 403 out_of_scope.

curl https://dev.bodek.us/v1/files/workspaces/12/members \
  -H "Authorization: Bearer bf_live_XXXX"

curl -X POST https://dev.bodek.us/v1/files/workspaces/12/members \
  -H "Authorization: Bearer bf_live_XXXX" -H "Content-Type: application/json" \
  -d '{ "email": "new@example.com", "role": "member" }'
Files-key routeSame as
GET /v1/files/workspaces/{id}/members
GET /v1/iam/members
POST /v1/files/workspaces/{id}/members
POST /v1/iam/members
PATCH /v1/files/workspaces/{id}/members/{user_id}
PATCH /v1/iam/members/{user_id}
DELETE /v1/files/workspaces/{id}/members/{user_id}
DELETE /v1/iam/members/{user_id}
GET /v1/files/workspaces/{id}/invites
GET /v1/iam/invites
DELETE /v1/files/workspaces/{id}/invites/{invite_id}
DELETE /v1/iam/invites/{invite_id}
GET /v1/files/workspaces/{id}/invite-codes
GET /v1/iam/invite-codes
POST /v1/files/workspaces/{id}/invite-codes
POST /v1/iam/invite-codes
DELETE /v1/files/workspaces/{id}/invite-codes/{code}
DELETE /v1/iam/invite-codes/{code}

Webhooks

Get an HTTPS POST when something changes in the workspace. Scopes webhooks:read / webhooks:write. Creating, updating and deleting webhooks requires the key's owner to be a workspace admin or the owner (403 not_admin). Folder-scoped keys can't use the webhook endpoints at all (403 out_of_scope), because webhooks report on the whole workspace. A workspace can have up to 20 webhooks (409 webhook_limit_reached).

The webhook object

{
  "id": 7,
  "workspace_id": 12,
  "name": "Sync to CRM",
  "url": "https://example.com/hooks/bodek",
  "events": ["file.created", "file.deleted"],   // or ["*"]
  "active": true,
  "last_status": 200,
  "last_delivered_at": "2026-09-23 10:01:00",
  "last_error": null,
  "created_at": "2026-09-01 08:00:00"
}

List webhooks

GET /v1/files/webhooks

Create a webhook

POST /v1/files/webhooks
BodyDescription
nameRequired, max 120 characters.
urlRequired. An https:// URL (max 2,048 characters) on port 443 or 1024–65535, without a username/password, whose host resolves only to public internet addresses. http://, localhost, private / loopback / link-local ranges (including 169.254.169.254) and other internal addresses are rejected. The address is checked again on every delivery.
eventsRequired. Event names from the catalog, or ["*"] for everything.
activeDefault true.
curl -X POST https://dev.bodek.us/v1/files/webhooks \
  -H "Authorization: Bearer bf_live_XXXX" -H "Content-Type: application/json" \
  -d '{ "name": "Sync to CRM", "url": "https://example.com/hooks/bodek", "events": ["file.created", "file.deleted"] }'
{
  "data": {
    "webhook": { "id": 7, "name": "Sync to CRM", … },
    "secret": "3f9a…64 hex characters…",
    "secret_warning": "Save this secret. It will not be shown again."
  }
}

Returns 201. The secret is shown only once. Errors: 400 invalid_webhook.

Get a webhook

GET /v1/files/webhooks/{id}

Update a webhook

PATCH /v1/files/webhooks/{id}

Send any of name, url, events, active (other fields are ignored; the same URL rules apply). Returns the updated webhook. The secret cannot be rotated — delete and recreate the webhook instead.

Delete a webhook

DELETE /v1/files/webhooks/{id}

Returns 204.

List event types

GET /v1/files/webhooks/events

Scope webhooks:read. The event names you can subscribe to.

{
  "data": [ { "event": "file.created", "description": "A file was uploaded" }, … ],
  "meta": { "wildcard": "*" }
}

Recent deliveries

GET /v1/files/webhooks/{id}/deliveries

Scope webhooks:read. The most recent delivery attempts, newest first. limit 1–200 (default 30).

{
  "data": [
    {
      "id": 912, "event": "file.created",
      "status": "delivered",          // "pending" | "delivered" | "failed"
      "attempts": 1, "response_status": 200, "last_error": null,
      "created_at": "2026-09-23 10:00:02", "delivered_at": "2026-09-23 10:01:00",
      "next_attempt_at": null         // set while a retry is scheduled
    }
  ],
  "meta": { "webhook_id": 7, "limit": 30 }
}

Webhook events

Events are produced by changes made through this API (the share-expiry sweep is the exception). Subscribe to a name below, or to *.

EventFired bydata
file.createdUpload, chunked-upload complete, copy of a file, compressFile object
folder.createdCreate folder, copy of a folder, unzipFile object (folder)
file.renamedPATCH with nameFile object
file.movedPATCH with parent_id, POST …/moveFile object
file.deletedDelete a file or folderFile object (snapshot before deletion)
share.changedCreate, change or revoke a shareShare object
album.share_changedShare, change or revoke an album's share{ "album_id", "status" }
member.role_changedChange a member's role{ "user_id", "new_role" }
member.removedRemove a member{ "user_id" }
member.addedReserved — accepted in subscriptions but not currently emitted—

Only * subscribers also receive workspace.created, workspace.renamed (workspace object) and share.expired (sent when an expired share link is switched back to private).

Delivery

POST /hooks/bodek HTTP/1.1
Content-Type: application/json
User-Agent: Bodek-Files-Webhook/1.0
X-Bodek-Event: file.created
X-Bodek-Signature: 5d41402abc4b2a76b9719d911017c592…
X-Bodek-Delivery: 912

{
  "event": "file.created",
  "workspace_id": 12,
  "timestamp": "2026-09-23T10:00:02+00:00",
  "data": { "id": "AbCd1234", "type": "file", "name": "report.pdf", … }
}

Deliveries are sent by a background worker, usually within a minute. Respond with any 2xx within 5 seconds (3 seconds to connect); redirects are not followed and only the first 64 KB of your response is read. The destination is resolved and checked on every attempt; if it no longer points to a public address the attempt fails. Deliveries stop if the member who created the webhook leaves the workspace. Anything else is retried after 1 min, 5 min, 15 min, 1 h and 6 h, then marked failed. Deliveries can arrive more than once or out of order — de-duplicate on X-Bodek-Delivery (the same id on every retry of a delivery) if it matters.

Verifying deliveries

X-Bodek-Signature is the lowercase hex HMAC-SHA256 of the raw request body, keyed with the webhook's secret. Compute it over the exact bytes you received (before JSON parsing) and compare in constant time. To reject replayed requests, also check that the signed body's timestamp is recent (e.g. within 10 minutes, allowing for retries by comparing against X-Bodek-Delivery ids you've already processed).

// PHP
$body     = file_get_contents('php://input');
$expected = hash_hmac('sha256', $body, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_BODEK_SIGNATURE'] ?? '')) {
    http_response_code(401); exit;
}
$event = json_decode($body, true);
// Node.js (Express)
const crypto = require('crypto');
app.post('/hooks/bodek', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = crypto.createHmac('sha256', SECRET).update(req.body).digest('hex');
  const given = Buffer.from(req.get('X-Bodek-Signature') || '');
  if (given.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(expected), given)) return res.sendStatus(401);
  const event = JSON.parse(req.body);
  res.sendStatus(204);
});
# Python (Flask)
import hmac, hashlib
body = request.get_data()
expected = hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get('X-Bodek-Signature', '')):
    abort(401)

Key info & health

GET /v1/files/me

Any scope. Describes the calling key.

{
  "data": {
    "key_id": 28, "key_name": "Backup script", "key_prefix": "bf_live_ABCDEF…",
    "environment": "live", "workspace_id": 12,
    "scopes": ["files:read", "files:write"],
    "scope_folder_id": null,
    "origin_mode": "server", "allowed_origins": [],
    "rate_limit_per_min": 100, "rate_limit_per_day": 10000,
    "created_at": "…", "last_used_at": "…", "expires_at": null
  }
}
GET /v1/files/health

Liveness check — no authentication required.

{ "data": { "ok": true, "service": "Bodek Files API", "version": "v1", "timestamp": "2026-09-23T10:00:00+00:00" } }

Scopes

A key with * has every scope. An existing key's scopes can be changed in the console with Edit scopes.

ScopeGrants
files:readList, get, download, search; get and list folders. Also reads tags, notes and albums.
files:writeUpload (simple and chunked), rename, move, copy, compress, unzip.
files:deleteDelete files and folders.
folders:writeCreate folders.
share:readRead share-link status, and who is on a share.
share:writeCreate, change and revoke share links (files and albums).
tags:readList tags, read a file's tags, and the tags inside a folder or album. files:read also grants this.
tags:writeCreate, rename and delete tags; tag and untag files.
notes:readRead the notes on a file. files:read also grants this.
notes:writeAdd, edit and delete notes.
albums:readList albums and the photos in them. files:read also grants this.
albums:writeCreate and change albums; add and remove photos.
workspace:readRead workspaces and storage usage.
workspace:writeCreate organizations and rename workspaces.
webhooks:readList webhooks, event types and deliveries.
webhooks:writeCreate, update and delete webhooks.
iam:read / iam:writeMember and invitation aliases under /workspaces/{id}. Organization keys without a folder lock; only an owner or admin can add them.

Error codes

StatusCodeMeaning
400invalid_jsonThe body isn't valid JSON.
400invalid_allow_download / invalid_allow_edit / invalid_people_tabThat field must be true or false.
400dynamic_albumItems can't be added to or removed from a person album.
400variousValidation failures, listed with each endpoint above.
401missing_authorizationNo Authorization: Bearer … header.
401invalid_token_format / invalid_tokenMalformed or unknown key.
401token_revoked / token_expiredThe key was revoked or has expired.
401token_orphanedThe key's creator no longer belongs to its workspace.
401account_disabledThe key's creator has been disabled.
402subscription_required / plan_upgrade_requiredThe key's creator has no active subscription for Files.
403wrong_serviceThe key is for another service (e.g. an iam key on /v1/files).
403insufficient_scopeMissing scope; see details.required.
403origin_blocked / origin_required / ip_blockedThe key's origin restrictions rejected the request.
403out_of_scopeThe write would land outside a folder-scoped key's folder, or the endpoint (albums, tag management, members, webhooks, workspace settings) isn't available to folder-scoped keys.
403not_admin / cross_workspaceAdmin rights needed, or a different workspace than the key's.
404not_found / folder_not_foundNo such item in this workspace (or outside the key's folder).
405method_not_allowedThe path exists but not for this method.
409incomplete_upload / webhook_limit_reachedThe resource isn't in the right state yet.
410upload_goneUpload session unknown, finished, aborted or expired.
413quota_exceededNot enough storage left in the workspace.
413body_too_large / too_large / too_many_itemsRequest body over 1 MB, or a compress / unzip / copy over the API limits.
429rate_limited / upload_queue_full / invite_rate_limitedSlow down; retry later (see Retry-After when present).
500internal_errorUnexpected failure; include details.request_id when reporting it.
502—The gateway couldn't reach the Files backend; retry.