File Upload Chunked upload flow, web upload (URL import), status polling, and upload management.

Overview

Fastio supports four upload flows:

1. Small files (< 4 MB) — Single-request upload. Send the file as a multipart chunk in the session creation request. Optionally auto-add to storage in the same call.
2. Large files (≥ 4 MB) — Chunked upload. Create a session, upload chunks (up to 3 in parallel), trigger assembly, poll until complete.
3. Stream upload — Upload a file of unknown size in a single request. Create a session with stream=true, then POST the raw file body to the stream endpoint.
4. Web upload (URL import) — Import files from a public HTTPS URL. The server downloads and uploads the file asynchronously.

All direct upload flows produce an upload session with a unique id (OpaqueId). Once the upload reaches complete status, the file is ready to use.

Upload Constraints

Org access policy. When an organization has restricted access by location or network (see Access Policy (Geo / IP Restrictions) in the Organizations reference), every upload endpoint for a target owned by that org refuses a blocked caller with 403 geo_restricted — session create, chunk, stream, complete, and both the per-session upload/{id}/details and web_upload/{id}/details reads. An MCP-classified caller blocked by the org’s mcp_access policy gets 403 mcp_access_denied instead. The session itself is not deleted or cancelled by the refusal. A session that is dropped from an upload list for this reason still returns 403 geo_restricted from its own details call, never 404 — so a 404 there still means the session itself is gone, not that it was hidden by policy. If a session’s own target cannot itself be read to resolve the policy, the call fails 503 access_policy_unavailable (retryable) rather than passing through unchecked — this applies to the two details reads above and to the upload/web_upload session lists: a list request whose row-level policy check hits an unreadable target fails 503 for the whole request rather than silently including or excluding that row.

Upload Status Values

Terminal states: complete, assembly_failed, store_failed. Stop polling when you reach one of these. Every successful path ends at complete.

State machine branches

A session takes one of two branches based on how it was created:

• Target path — request supplies a storage target (action + instance_id). Path: uploading → assemble → assembling → storing → complete. Terminal: complete, with new_file_id set; the file is accessible for download and preview. May instead end at assembly_failed or store_failed.
• No-target path — no instance_id provided. Path: uploading → complete (it may pass through assemble / assembling). Terminal: complete. File is held for a later addfile call.

Transition-Tracking Fields

Each session object carries three fields for distinguishing "still moving" from "stuck" when polling:

A short-lived assemble → assembling → storing → complete sequence can finish in well under a second for small chunk-based uploads, so a single poll can catch a session mid-transition. Do not treat a non-terminal status on the first poll as a failure.

Integrity Checksums (CRC-32C)

CRC-32C (Castagnoli) is the recommended integrity checksum for uploads. It is fast to compute, and per-chunk values can be combined into the whole-file value without reading the file a second time. md5, sha1, sha256 and sha384 keep working exactly as before.

• Format. hash_algo=crc32c with hash set to exactly 8 lowercase hex digits, in the standard big-endian rendering: the CRC-32C of the ASCII bytes 123456789 is e3069283, and of empty input 00000000. Uppercase digits, a 0x prefix, or a decimal value are rejected as an invalid hash.
• Per chunk. Send hash_algo=crc32c&hash={crc32c_hex} with each POST /current/upload/{upload_id}/chunk/. A chunk whose bytes do not match is rejected the same way as with any other algorithm ("The chunk failed to hash properly..."); re-send that chunk.
• Whole body. On a single-call upload, a stream body, or a batch entry, hash_algo=crc32c + hash is the CRC-32C of the whole body and is checked against the bytes received.
• Whole file (chunked). Declare the CRC-32C of the entire file either at session creation (hash_algo=crc32c + hash) or with the optional file_crc32c parameter on POST /current/upload/{upload_id}/chunk/ (only there — single-call, stream and batch uploads already carry a whole-body hash). Compute it by combining your per-chunk CRCs in chunk order with the zlib crc32_combine method, using the CRC-32C polynomial (reflected 0x82F63B78); no second pass over the file is needed.
• Which chunk carries file_crc32c. Send it on the first send of the chunk whose CRC you finish computing last — for a client that uploads chunks one after another, the last chunk — and on retries of that same chunk only. Never move it to a different chunk. The server must hold the value before the session has received every byte, so a file_crc32c that arrives after that is refused. Resending the same value is harmless; a different value is refused with 10779 (HTTP 409). If you know the whole-file CRC-32C before you start, you can instead declare it at session creation.
• Validation. When the upload is finalized, the server combines the CRC-32Cs of the chunks it stored and compares the result with your value, without re-reading the file. On a match the file is stored as normal. On a mismatch nothing is stored and the session ends assembly_failed. The mismatch is reported in one of three shapes: (a) the completing chunk, the stream body, the single-call upload, or /complete fails with an HTTP 406 error, code 10778 — as does any later chunk, stream or /complete call on that session; (b) a batch entry fails inline: the batch still returns HTTP 200, and that entry carries status: "error" with error_code 10778; (c) session details still succeed, showing status: "assembly_failed" and integrity_failure.error_code 10778. The session can still be deleted. A mismatch is terminal — do not retry the session; create a new one and upload the file again.
• A legacy whole-file hash still works alongside it. A session created with a sha256 (or other legacy) whole-file hash can also receive a file_crc32c; each is checked on its own, and a legacy mismatch behaves as it always has.
• Stored on the file. Every newly stored file records its whole-file CRC-32C, returned as crc32c on node and version details next to the unchanged hash (see the Storage reference). Compare it with your local value to confirm what was stored. Files stored before the platform began recording it report null. An upload that was already in progress when the server was updated may complete without the whole-file check, and its stored crc32c may be null.

Workflow: Small File Upload (< 4 MB)

A single request creates the session and uploads the file. Optionally auto-adds to storage.

Step 1: Upload in one request

Content-Type: multipart/form-data

Parameters

Example (small file with auto-add to workspace)

curl -X POST "https://api.fast.io/current/upload/" \
  -H "Authorization: Bearer {jwt_token}" \
  -F "name=notes.txt" \
  -F "size=1024" \
  -F "action=create" \
  -F "instance_id=1234567890123456789" \
  -F "folder_id=root" \
  -F "creator=my-web-client" \
  -F "chunk=@notes.txt"

Response (201 Created)

{
  "result": true,
  "id": "5uhlp-zzcds-g2ba5-rqnbo-s5ytn-geda",
  "creator": "my-web-client",
  "new_file_id": null
}

Response fields

When instance_id and folder_id are provided, the file is automatically added to storage — no addfile step is needed. Because storage completes asynchronously, get the new node id by long-polling GET /current/upload/{id}/details/?wait=60 until the session reaches a terminal status, then read session.new_file_id. Skip the poll only when the create response already carried a non-null new_file_id.

Response (without instance_id, 201 Created)

{
  "result": true,
  "id": "5uhlp-zzcds-g2ba5-rqnbo-s5ytn-geda"
}

Without a target, only the upload session id is returned. Use addfile to place the file in storage after the upload completes.

Error responses

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.

Workflow: Large File Upload (Chunked)

Step 1: Create upload session

Content-Type: application/x-www-form-urlencoded

Parameters

Example

curl -X POST "https://api.fast.io/current/upload/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "name=annual-report.pdf" \
  -d "size=52428800" \
  -d "action=create" \
  -d "instance_id=1234567890123456789" \
  -d "hash_algo=sha256" \
  -d "hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

Response (201 Created)

{
  "result": true,
  "id": "5uhlp-zzcds-g2ba5-rqnbo-s5ytn-geda"
}

When instance_id names a workspace or share owned by an organization restricting access by location or network, session creation refuses a blocked caller with 403 geo_restricted — see Org access policy above.

Step 2: Upload chunks

Content-Type: multipart/form-data

Path parameters

Query parameters

Request body (multipart/form-data)

Upload up to 3 chunks in parallel. The last chunk may be smaller. Only 1 undersized chunk is allowed per session.

When all chunks have been uploaded (total bytes equal the declared file size), auto-finalization triggers automatically. You can still call the complete endpoint explicitly.

Example

curl -X POST "https://api.fast.io/current/upload/5uhlp-zzcds-g2ba5-rqnbo-s5ytn-geda/chunk/?order=1&size=5242880&hash_algo=sha256&hash=abc123def456..." \
  -H "Authorization: Bearer {jwt_token}" \
  -F "chunk=@chunk_001.bin"

Example (last chunk with CRC-32C, carrying the whole-file file_crc32c)

curl -X POST "https://api.fast.io/current/upload/5uhlp-zzcds-g2ba5-rqnbo-s5ytn-geda/chunk/?order=5&size=5242880&hash_algo=crc32c&hash={chunk_crc32c_hex}&file_crc32c={file_crc32c_hex}" \
  -H "Authorization: Bearer {jwt_token}" \
  -F "chunk=@chunk_005.bin"

Response (202 Accepted)

{
  "result": true
}

Error responses

Step 3: Trigger assembly

Path parameters

Query parameters (optional)

No body parameters required. If the session is already in a completed or processing state (complete, assemble, assembling, store, storing, stored), the endpoint returns 200 OK immediately without error.

Example

curl -X POST "https://api.fast.io/current/upload/5uhlp-zzcds-g2ba5-rqnbo-s5ytn-geda/complete/" \
  -H "Authorization: Bearer {jwt_token}"

Response (202 Accepted)

{
  "result": true
}

Error responses

Step 4: Poll for completion

Path parameters

Query parameters

The server detects status changes efficiently during long-poll. Maximum wait is 590 seconds. A single wait call replaces polling: when it returns with status complete, the node ID is already in session.new_file_id.

Example

curl -X GET "https://api.fast.io/current/upload/5uhlp-zzcds-g2ba5-rqnbo-s5ytn-geda/details/?wait=60" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "session": {
    "status": "complete",
    "id": "5uhlp-zzcds-g2ba5-rqnbo-s5ytn-geda",
    "updated": "2025-01-20 10:35:00 UTC",
    "created": "2025-01-20 10:30:00 UTC",
    "updated_ms": 1737369300412,
    "state_epoch": 4,
    "size": 52428800,
    "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "hash_algo": "sha256",
    "filename": "annual-report.pdf",
    "org": "1234567890123456789",
    "target": {
      "action": "create",
      "instance_id": "1234567890123456789",
      "folder_id": "root",
      "relative_path": null,
      "relative_id": null
    },
    "new_file_id": "2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4",
    "chunks": {
      "1": 10485760,
      "2": 10485760,
      "3": 10485760,
      "4": 10485760,
      "5": 10485760
    }
  }
}

Response fields

Exit condition: Stop polling when status is a terminal state — complete, assembly_failed, or store_failed. See "State machine branches" above.

Whole-file CRC-32C mismatch. A session whose stored bytes did not match its file_crc32c ends like this; nothing was stored, so upload the file again in a new session:

{
  "result": true,
  "session": {
    "status": "assembly_failed",
    "id": "5uhlp-zzcds-g2ba5-rqnbo-s5ytn-geda",
    "size": 26214400,
    "file_crc32c": "7a3c19e4",
    "filename": "presentation.pptx",
    "status_message": "The uploaded file did not match its whole-file CRC-32C. Please upload it again.",
    "integrity_failure": {
      "reason": "file_crc32c_mismatch",
      "expected_crc32c": "7a3c19e4",
      "computed_crc32c": "1c2f9a07",
      "error_code": 10778
    }
  }
}

Uploaded chunks no longer available. A session whose uploaded chunks were no longer available when it was finalized normally ends like this; nothing was stored, and the chunk, stream and /complete calls on it normally return the same 162098. Do not retry the session or re-send its chunks; upload the whole file again in a new session:

{
  "result": true,
  "session": {
    "status": "assembly_failed",
    "status_message": "The uploaded chunks of this session are no longer available. Please upload the file again.",
    "integrity_failure": {
      "reason": "chunk_references_released",
      "error_code": 162098
    }
  }
}

If the target org restricts access by location or network and the caller is currently blocked, this read refuses with 403 geo_restricted instead of returning session — the session itself is not deleted or cancelled by the refusal. A genuine 404 (Not Found) on this route still means the session is gone, never that it was hidden by policy. If the session’s own target cannot itself be read to resolve the policy, this read fails 503 access_policy_unavailable (retryable) instead of passing through unchecked.

Step 5 (if no instance_id): Add file to storage manually

Or for shares:

Path parameters

• {workspace_id} or {share_id} — Profile ID (19-digit numeric string)
• {folder_id} — OpaqueId of the target folder, or "root" for the storage root

Body parameters

from format

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

Example

curl -X POST "https://api.fast.io/current/workspace/1234567890123456789/storage/root/addfile/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'name=annual-report.pdf' \
  -d 'from={"type":"upload","upload":{"id":"5uhlp-zzcds-g2ba5-rqnbo-s5ytn-geda"}}'

Step 6 (optional): Clean up session

Complete Chunked Upload Example

1. Create session (25 MB file, 5 chunks)

curl -X POST "https://api.fast.io/current/upload/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "name=presentation.pptx" \
  -d "size=26214400" \
  -d "action=create" \
  -d "instance_id=1234567890123456789" \
  -d "folder_id=root"

Response:

{"result": true, "id": "5uhlp-zzcds-g2ba5-rqnbo-s5ytn-geda"}

2. Upload 5 chunks (3 in parallel, then 2 more)

# Chunks 1-3 in parallel
curl -X POST "https://api.fast.io/current/upload/5uhlp-.../chunk/?order=1&size=5242880" \
  -H "Authorization: Bearer {jwt_token}" -F "chunk=@chunk1.bin" &

curl -X POST "https://api.fast.io/current/upload/5uhlp-.../chunk/?order=2&size=5242880" \
  -H "Authorization: Bearer {jwt_token}" -F "chunk=@chunk2.bin" &

curl -X POST "https://api.fast.io/current/upload/5uhlp-.../chunk/?order=3&size=5242880" \
  -H "Authorization: Bearer {jwt_token}" -F "chunk=@chunk3.bin" &
wait

# Chunks 4-5
curl -X POST ".../chunk/?order=4&size=5242880" \
  -H "Authorization: Bearer {jwt_token}" -F "chunk=@chunk4.bin" &
curl -X POST ".../chunk/?order=5&size=5242880" \
  -H "Authorization: Bearer {jwt_token}" -F "chunk=@chunk5.bin" &
wait

3. Trigger assembly

curl -X POST "https://api.fast.io/current/upload/5uhlp-.../complete/" \
  -H "Authorization: Bearer {jwt_token}"

4. Poll until complete

curl -X GET "https://api.fast.io/current/upload/5uhlp-.../details/?wait=60" \
  -H "Authorization: Bearer {jwt_token}"

Response: {"result": true, "session": {"status": "assembling", ...}} — keep polling

curl -X GET "https://api.fast.io/current/upload/5uhlp-.../details/?wait=60" \
  -H "Authorization: Bearer {jwt_token}"

Response: {"result": true, "session": {"status": "complete", "new_file_id": "2ltsu-...", ...}} — done

5. Clean up session

curl -X DELETE "https://api.fast.io/current/upload/5uhlp-zzcds-g2ba5-rqnbo-s5ytn-geda" \
  -H "Authorization: Bearer {jwt_token}"

Resume a Disconnected Upload

If an upload is interrupted (network failure, client crash), resume it without re-uploading completed chunks.

Steps

1. Get session status:

   curl -X GET "https://api.fast.io/current/upload/{upload_id}/details/" \
     -H "Authorization: Bearer {jwt_token}"

2. Read the chunks map in the response. Keys are chunk numbers already uploaded, values are byte sizes.
3. Upload only missing chunks. Compare the chunks map against the expected chunk list. Upload any chunks not present. If session.file_crc32c is already set, do not send a different value; if it is not set and you use one, send file_crc32c with the missing chunk whose CRC you finish last.
4. Trigger assembly:

   curl -X POST "https://api.fast.io/current/upload/{upload_id}/complete/" \
     -H "Authorization: Bearer {jwt_token}"

5. Poll for completion as normal.

File Update (New Version)

To upload a new version of an existing file:

1. Create session with action=update, instance_id, and file_id (OpaqueId of the file to replace).
2. Upload chunks and complete as normal. The existing file receives a new version.

curl -X POST "https://api.fast.io/current/upload/" \
  -H "Authorization: Bearer {jwt_token}" \
  -F "name=report-v2.pdf" \
  -F "size=1024" \
  -F "action=update" \
  -F "instance_id=1234567890123456789" \
  -F "file_id=2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4" \
  -F "chunk=@report-v2.pdf"

The instance_id for an update target may be a workspace, a share, or a File Share (see below).

Optional Compare-and-Swap (if_version_id)

To avoid clobbering a concurrent edit, supply an optional if_version_id precondition on the update session. The replace is applied only if the target file's current version equals that id. This is accepted and enforced on every update target — workspace, share, and File Share alike.

Pass if_version_id at session creation (action=update) — the complete/ finalize call does not read it.

Version Conflict Surfacing

This is an asynchronous upload session, not the synchronous storage-update endpoints (POST .../storage/{node_id}/update/, which answer a 409 with error.params[] — see the Storage reference). Here, when if_version_id does not match the current version, the session ends terminally instead: status becomes assembly_failed and session.status_message carries CONFLICT_VERSION_MISMATCH:{current_version_id}. There is no 409 on this path. A polling client can parse the current version id off that prefix, re-read the file, and retry with the fresh if_version_id. This terminal state is not retried by the server — the client decides whether to re-attempt.

Read the file before concluding nothing was written. This status means the write was refused on the attempt that reported it. It is not a guarantee that the session as a whole wrote nothing: an internal retry can re-run the write against the base you supplied after an earlier attempt in the same session already applied it, and the conflict is then reported against your own committed version. Rebasing onto the returned id and re-uploading in that situation stores your content a second time. So on a conflict, fetch the file and compare it against what you intended to write; re-upload only if the content is not already there.

{
  "result": true,
  "session": {
    "id": "57m2t-rba7h-bjv5m-yxi6q-lhb24-jexy",
    "status": "assembly_failed",
    "status_message": "CONFLICT_VERSION_MISMATCH:3dcdvao5jdflim47gxa5lygwotenm"
  }
}

⚠️ STATUS (2026-08-26): the persistence defect is FIXED in code and covered by tests that re-read the stored row, but the fix is NOT yet confirmed on a live conflict. Until it is, treat status_message as the reliable conflict signal and the fields below as the intended contract rather than a measured one. This note is removed the moment a real conflict on a deployed build is observed to carry them.

Read session.conflict, not the status string. The same terminal conflict is also persisted as a structured object, and that is what a new client should consume:

"conflict": {
  "type": "CONFLICT_VERSION_MISMATCH",
  "base_version_id": "33qhg-tbqyj-wrmr2-ssdmv-ht4lr-hal5",
  "current_version_id": "3dcdv-ao5jd-flim4-7gxa5-lygwo-tenm",
  "candidate_id": "4itaflutlgy3jnwfck7v5lf62cujg",
  "expires_at": "2026-08-27 04:00:00 UTC",
  "permitted_actions": ["rebase", "discard"]
}

base_version_id is what you asserted; current_version_id is what the node actually moved to. You need both to decide whether to rebase or surface the conflict, and the colon-delimited status_message carries only the second. status_message is kept for clients already parsing it and is not going away, but it is a string with a separator, not a protocol — prefer conflict.

current_version_id is optional. When the store could not supply the current version — the target row was gone by the time the write was refused — the key is absent entirely rather than empty, because an empty string is not "unknown", it is an id you might send back. Test for the key before reading it; when it is missing, re-read the file to find out what state it is actually in. The same applies to candidate_id and expires_at, which are present only when content was retained.

conflict.candidate_download_url is deliberately absent. The only way to address content with no node attached is internal-network-only and unsupported for chunked uploads — which is exactly the large file you would most want back — so a key that could not be fetched is not emitted. candidate_id plus expires_at is what is real today.

Your upload MAY be recoverable — branch on the fields, never assume them. A conflicted session CAN carry candidate_phy_id and candidate_retained_until, meaning the bytes you sent are retained rather than discarded. They are frequently absent, and absent is the ordinary case. When the server can tell your if_version_id is stale before it has written anything, it refuses early and there is nothing to retain — no content was ever stored, so there is nothing lost either. The fields carry a value only when the write had already progressed far enough to store your content before losing the race.

⚠ permitted_actions is the signal to branch on, not the presence of the keys. It contains "discard" only when there is genuinely something to discard; a conflict with ["rebase"] alone means re-read and resend. candidate_retained_until is a real deadline when present — after it the content is reclaimed — but do not build a recovery flow that assumes it will be there.

The candidate is exposed on the SESSION, which belongs to whoever created the upload. That ownership is the authorization: nobody else can read these fields, including users with write access to the target file. It is your unaccepted draft, not the file's.

⚠ Ids appear in TWO renderings in this payload, and the hyphenated set is an allowlist. session.id, session.new_file_id, and the two version ids inside session.conflict (base_version_id, current_version_id) are emitted in the canonical hyphenated form (29 characters grouped in fives, 34 characters total). Every other OpaqueId in the session payload is emitted RAW — 29 lowercase alphanumeric characters, no hyphens — including session.target.file_id, session.candidate_phy_id, conflict.candidate_id, and any id carried inside status_message.

The two version ids are hyphenated because they are compare-and-swap tokens: current_version_id is what you hand back as the next if_version_id, and it reads exactly like the version field you took it from. conflict.candidate_id stays raw because it is the same value as session.candidate_phy_id, and one id must not read two ways within one response.

So the same node can appear both ways in one response (new_file_id hyphenated, target.file_id raw), and the same version appears hyphenated in conflict.current_version_id but raw in the status_message prefix.

⇒ Do not write a parser that requires either shape. Strip non-alphanumerics and lowercase before comparing or storing an id; the API accepts either form on input and canonicalises it, so an id read in one rendering can be sent back in the other. A new field added to the session payload defaults to RAW unless it is listed above.

⚠️ Migrating from status_message to conflict changes the rendering you display. The same version is raw in the status_message prefix and hyphenated in conflict.current_version_id, so a client that switches sources starts showing a different-looking id for the same version — and a user comparing today's output to yesterday's will reasonably conclude something moved. Two consequences worth planning for: normalise before you compare across the two sources (a direct string compare of the parsed status_message id against conflict.current_version_id returns false on a match, which is exactly the signal a compare-and-swap client acts on), and decide deliberately which rendering you show a human, rather than inheriting whichever source you happen to read. Both are correct ids for the same version.

File Share External Edit (Write-Back)

A holder of an edit grant on a durable File Share can replace the shared file's content — even without being a member of the owning workspace — by using the File Share id as the instance_id of an action=update upload session. The session targets the File Share's single bound file node; the bytes land in (and are metered to) the owning workspace's storage.

1. Create session with action=update, instance_id={fileshare_id} (the File Share's numeric id or its opaque id_alt), and file_id={bound_node_id} (the File Share's bound file, available as bound_node_id from the management list, or file.id from the public details endpoint).
2. Upload chunks and complete as normal. The bound file receives a new version, and a file_share_content_updated event is emitted.

curl -X POST "https://api.fast.io/current/upload/" \
  -H "Authorization: Bearer {jwt_token}" \
  -F "name=report-v2.pdf" \
  -F "size=1024" \
  -F "action=update" \
  -F "instance_id=1234567890123456789" \
  -F "file_id=2ltsu-q4mja-cuv7p-gc5yd-lxnsj-wee4" \
  -F "chunk=@report-v2.pdf"

Authorization. The write requires a named edit grant on the File Share (or an equivalent scope token) — workspace/org membership is not required, and no access tier alone confers write. In addition to the edit grant, the same access gate that governs reads still applies to the write: if the File Share is password-protected, the editor must present the link password via the x-ve-password request header, and the File Share's access tier (anyone_with_link / any_registered / named_people) is enforced. The file_id you supply must canonicalize to the File Share's bound node; any other node id resolves to 404 (siblings cannot be probed). The optional if_version_id compare-and-swap precondition documented above applies here the same as on any other update target.

Sign Envelope Target (Draft Documents)

A Sign Envelope in draft status is also an accepted upload target: pass the Sign Envelope id as instance_id on POST /current/upload/ — with action=create to add a draft document, or action=update to replace one. Uploads are permitted only while the envelope is a draft and require membership in the envelope's owning workspace with view access to the envelope; once the envelope leaves draft it no longer accepts document uploads. See the Signing reference for the envelope lifecycle and its document-management endpoints — the details here are limited to noting that the upload API accepts this target.

Stream Upload (Unknown File Size)

For clients that don't know the exact file size upfront (piped output, generated content, compressed streams). The client declares a maximum size ceiling, streams the file in a single request, and the system records actual bytes.

Step 1: Create stream session

Parameters

Example

curl -X POST "https://api.fast.io/current/upload/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "name=output.tar.gz" \
  -d "stream=true" \
  -d "max_size=52428800" \
  -d "action=create" \
  -d "instance_id=1234567890123456789"

Response (201 Created)

{
  "result": true,
  "id": "5uhlp-zzcds-g2ba5-rqnbo-s5ytn-geda"
}

Step 2: Stream file body

Send the raw file bytes as the request body with Content-Type: application/octet-stream. No size or order parameters needed.

Path parameters

Query parameters (optional)

Example

curl -X POST "https://api.fast.io/current/upload/5uhlp-zzcds-g2ba5-rqnbo-s5ytn-geda/stream/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @myfile.tar.gz

Response (201 Created)

{
  "result": true
}

The session auto-finalizes after the stream completes. The session's size field is updated to reflect the actual bytes received.

Error responses

Notes

• The max_size parameter is used for quota validation at session creation. If omitted, defaults to the organization's maximum file size.
• The actual uploaded bytes must not exceed max_size.
• Stream mode sessions produce exactly one chunk and finalize automatically — no /complete/ call is needed. With a target, the session still moves through assemble / assembling / storing to complete; long-poll GET /current/upload/{upload_id}/details/?wait=60 for new_file_id.
• If you know the exact file size, you can still provide size instead of max_size (or both).
• Stream upload is a single-shot operation: you cannot stream to the same session twice.
• Stream mode sessions cannot use the chunk endpoint — attempting to upload chunks to a stream session will return an error. Use the /stream/ endpoint instead.
• Only one concurrent stream upload is allowed per session; concurrent requests to the same session are rejected.

Batch Upload (Many Small Files)

Submit 1–200 small files in a single request. Returns a per-file result array, so partial success is legible and does not abort the batch. Use this when you have many small files destined for the same workspace or share — one rate-limit cost instead of one per file. For files over 4 MB, keep using the standard chunked POST /current/upload/ flow.

Batch Limits

Create batch (multipart)

Content-Type: multipart/form-data

Authentication: Required. Anonymous callers are not supported on this endpoint — use POST /current/upload/ for anonymous public-receive / public-exchange share uploads.

Batch-level fields

Manifest entry schema

Hash validation is opt-in per entry: supply both hash_algo and hash, or neither. A mismatch errors only that entry; the batch still returns 200.

Example

curl -X POST "https://api.fast.io/current/upload/batch/" \
  -H "Authorization: Bearer {jwt_token}" \
  -F "instance_id=1234567890123456789" \
  -F "creator=my-importer" \
  -F 'manifest=[{"index":0,"filename":"doc-001.txt"},{"index":1,"filename":"doc-002.txt"}]' \
  -F "file_0=@doc-001.txt" \
  -F "file_1=@doc-002.txt"

Create batch (JSON)

Content-Type: application/json

Base64 inflation adds ~33% to the wire size and forces the server to hold decoded bytes in memory while parsing; prefer multipart (which streams directly to disk) for non-trivial payloads.

Body schema

{
  "instance_id": "1234567890123456789",
  "folder_id": "{folder_opaque_id}",
  "creator": "my-importer",
  "files": [
    {"filename": "doc-001.txt", "content_b64": "SGVsbG8sIHdvcmxkIQ=="},
    {"filename": "doc-002.txt", "relative_path": "2026/q1/", "content_b64": "U2Vjb25kIGZpbGU="}
  ]
}

Each files entry accepts the same optional relative_path, hash_algo, and hash fields as the multipart manifest. The array position is the entry's logical index. folder_id (batch-level) and relative_path (per-entry) follow the same semantics as on POST /current/upload/.

Example

curl -X POST "https://api.fast.io/current/upload/batch/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "1234567890123456789",
    "creator": "my-importer",
    "files": [
      {"filename": "doc-001.txt", "content_b64": "SGVsbG8sIHdvcmxkIQ=="},
      {"filename": "doc-002.txt", "content_b64": "U2Vjb25kIGZpbGU="}
    ]
  }'

Response (200 OK)

Always 200 OK on a well-formed batch. Inspect count_errored to detect per-file failures.

{
  "result": true,
  "batch_id": "{batch_id}",
  "count_total": 2,
  "count_succeeded": 1,
  "count_errored": 1,
  "creator": "my-importer",
  "results": [
    {
      "index": 0,
      "filename": "doc-001.txt",
      "status": "ok",
      "upload_id": "{upload_id}",
      "node_id": "{node_id}"
    },
    {
      "index": 1,
      "filename": "doc-002.txt",
      "status": "error",
      "error_code": 196420,
      "error_message": "hash_algo and hash must both be provided for a manifest entry."
    }
  ]
}

Response fields

Per-file errors are reported inline on each entry — the batch itself returns HTTP 200 even if every file errored; check count_errored. The per-file shape is {error_code, error_message} and is intentionally flat (one error per file). It does not carry the envelope-level params array used by whole-batch validation rejections; the per-file error_code is a unique 6-digit diagnostic code specific to the batch endpoint, not one of the platform error-reference codes — except 10778 (whole-file CRC-32C mismatch) and 162098 (uploaded data no longer available), which are the same codes the other upload endpoints return.

Whole-batch error responses

These are returned in the standard error envelope (no results[]).

Per-file error causes

Recorded in results[] with status: "error"; the batch returns 200 OK.

• Missing / empty file_{index} part (multipart) or missing / empty content_b64 (JSON).
• Base64 decode failure (JSON path).
• File over the 4 MB per-file bound — use POST /current/upload/ instead.
• File type (extension or MIME) restricted for the organization (only while extension enforcement is on).
• hash_algo not supported or hash length wrong for the declared algorithm.
• hash_algo supplied without hash (or vice versa).
• Uploaded bytes do not match the declared hash.
• The stored file did not match the entry’s crc32c hash when it was finalized. This entry carries error_code 10778 (the same code as the single-file and chunked endpoints) and nothing was stored for it; resubmit the file.
• The entry’s uploaded data was no longer available when it was finalized. This entry carries error_code 162098 (the same code as the single-file and chunked endpoints) and nothing was stored for it; resubmit the file.
• Internal storage / finalization failure for the single entry.
• The request reached the server’s per-request processing budget before this entry was started (large batches only). These entries carry error_code 190079, and the error_message asks you to resubmit the file; it was not stored.

Fetch batch status

Authentication is not required for this endpoint — the opaque batch_id is the only credential. Treat batch_id as bearer-equivalent; transport over HTTPS and do not log alongside identifiers.

Path parameters

Example

curl -X GET "https://api.fast.io/current/upload/batch/{batch_id}/"

Response (200 OK)

{
  "result": true,
  "batch_id": "{batch_id}",
  "creator": "my-importer",
  "count_total": 2,
  "count_succeeded": 1,
  "count_errored": 1,
  "results": [
    { "index": 0, "filename": "doc-001.txt", "status": "ok", "upload_id": "{upload_id}", "node_id": "{node_id}" },
    { "index": 1, "filename": "doc-002.txt", "status": "error", "error_code": 196420, "error_message": "hash_algo and hash must both be provided for a manifest entry." }
  ],
  "created_ts": 1745000000
}

Error responses

Notes

• The batch endpoint is rate-limited in an independent bucket from POST /current/upload/. A client doing bulk uploads and then a chunked upload is not double-charged.
• Each successful file produces an upload_session_created event — downstream consumers (search indexing, AI pipelines) see the same event stream as N independent POST /current/upload/ calls.
• Partial success is the documented contract. A failure on file 37 does not roll back files 0–36; they are already persisted.
• Files over 4 MB in the batch return per-file errors pointing back to POST /current/upload/ — the rest of the batch still processes.
• A large batch can stop early when the request reaches the server’s per-request processing budget. Entries already processed keep their results; every entry that was not started comes back with status: "error" and a retryable message asking you to resubmit that file. Match on error_code 190079 (not the message text) to find them, and resubmit only those entries in a new batch — do not resend the whole batch, since entries reported ok are already stored. Re-number the resubmitted entries’ index from 0 in the new manifest, with matching file_{index} parts, because indices must be contiguous from 0.

Web Upload (URL Import)

Import files from a public HTTPS URL. Supports OAuth-protected URLs (Google Drive, OneDrive, Dropbox, Box, iCloud). The server downloads the file in the background and streams it through the standard upload pipeline.

Create web upload job

Content-Type: application/x-www-form-urlencoded

Parameters

Example

curl -X POST "https://api.fast.io/current/web_upload/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "source_url=https://example.com/files/document.pdf" \
  -d "file_name=document.pdf" \
  -d "profile_id=1234567890123456789" \
  -d "profile_type=workspace" \
  -d "folder_id=root"

Response (201 Created)

{
  "result": true,
  "web_upload": {
    "id": "5dpct-ajic7-kyc2q-fpism-fg4xc-2ehf",
    "user_id": "1234567890123456789",
    "profile_id": "1234567890123456789",
    "profile_type": "workspace",
    "source_url": "[redacted]",
    "file_name": "document.pdf",
    "folder_id": null,
    "relative_path": null,
    "status": "queued",
    "status_description": "Queued for processing",
    "bytes_downloaded": 0,
    "expected_size": null,
    "upload_session_id": null,
    "async_job_id": null,
    "creator": null,
    "error_message": null,
    "options": 0,
    "created": "2025-01-26 15:00:00 UTC",
    "updated": "2025-01-26 15:00:00 UTC"
  }
}

Response fields

Error responses

OAuth for protected URLs

For Google Drive, OneDrive, and other OAuth-protected files, include the access token as a query parameter in the source URL:

https://www.googleapis.com/drive/v3/files/{fileId}?alt=media&access_token={oauth_token}

The server extracts the token from the URL, removes it from the query string, and sends it as an Authorization: Bearer header on all HTTP requests. Tokens are never logged or returned in API responses.

List web upload jobs

Query parameters

Example

curl -X GET "https://api.fast.io/current/web_upload/?status=downloading&limit=20" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "web_uploads": [
    {
      "id": "5dpct-ajic7-kyc2q-fpism-fg4xc-2ehf",
      "user_id": "1234567890123456789",
      "profile_id": "1234567890123456789",
      "profile_type": "workspace",
      "source_url": "[redacted]",
      "file_name": "document.pdf",
      "folder_id": null,
      "relative_path": null,
      "status": "downloading",
      "status_description": "Downloading file from URL",
      "bytes_downloaded": 5242880,
      "expected_size": 52428800,
      "progress_percent": 10,
      "upload_session_id": null,
      "error_message": null,
      "created": "2025-01-26 15:00:00 UTC",
      "updated": "2025-01-26 15:01:00 UTC"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Response fields

Get web upload job details

Path parameters

Example

curl -X GET "https://api.fast.io/current/web_upload/5dpct-ajic7-kyc2q-fpism-fg4xc-2ehf/details/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "web_upload": {
    "id": "5dpct-ajic7-kyc2q-fpism-fg4xc-2ehf",
    "user_id": "1234567890123456789",
    "profile_id": "1234567890123456789",
    "profile_type": "workspace",
    "source_url": "[redacted]",
    "file_name": "document.pdf",
    "folder_id": null,
    "relative_path": null,
    "status": "complete",
    "status_description": "Upload complete",
    "bytes_downloaded": 52428800,
    "expected_size": 52428800,
    "upload_session_id": "5uhlp-zzcds-g2ba5-rqnbo-s5ytn-geda",
    "async_job_id": "apkti-6i76h-6o4xr-5aqkj-egxgu-zmrc",
    "creator": null,
    "error_message": null,
    "options": 0,
    "created": "2025-01-26 15:00:00 UTC",
    "updated": "2025-01-26 15:02:00 UTC"
  }
}

Note: Both the details and list endpoints return status as string values (e.g., "pending", "queued", "downloading", "uploading", "complete", "failed", "canceled").

Error responses

Cancel web upload job

Query parameters

Example

curl -X DELETE "https://api.fast.io/current/web_upload/?id=5dpct-ajic7-kyc2q-fpism-fg4xc-2ehf" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "canceled": true,
  "id": "5dpct-ajic7-kyc2q-fpism-fg4xc-2ehf"
}

Error responses

Web Upload Status Values

Web Upload Limits

Upload Management Endpoints

List all upload sessions

Example

curl -X GET "https://api.fast.io/current/upload/details/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "sessions": [
    {
      "id": "5uhlp-zzcds-g2ba5-rqnbo-s5ytn-geda",
      "filename": "document.pdf",
      "size": 52428800,
      "status": "uploading",
      "hash": "e3b0c44298fc1c14...",
      "hash_algo": "sha256",
      "created": "2025-01-20 10:30:00 UTC",
      "updated": "2025-01-20 10:35:00 UTC"
    }
  ]
}

Response fields

Delete/cancel an upload session

Path parameters

Cleans up temporary chunk files and releases session quota. If the session has an associated web upload job, that job is automatically canceled.

Sessions can be deleted in states: ready, uploading, assembly_failed, store_failed, complete. Sessions in assemble, assembling, store, storing, or stored states cannot be deleted.

Example

curl -X DELETE "https://api.fast.io/current/upload/5uhlp-zzcds-g2ba5-rqnbo-s5ytn-geda" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true
}

Error responses

Get upload limits

Query parameters

Example

# General limits (with org context)
curl -X GET "https://api.fast.io/current/upload/limits/?org=1234567890123456789" \
  -H "Authorization: Bearer {jwt_token}"

# Limits for creating a file in a workspace
curl -X GET "https://api.fast.io/current/upload/limits/?action=create&instance_id=1234567890123456789" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "limits": {
    "chunk_size": 262144000,
    "size": 107374182400,
    "chunks": 1000,
    "sessions": 10000,
    "sessions_size_max": 1099511627776
  }
}

Response fields

Get restricted file extensions

Query parameters

Example

curl -X GET "https://api.fast.io/current/upload/limits/extensions/"

# With specific plan
curl -X GET "https://api.fast.io/current/upload/limits/extensions/?plan={plan_id}"

Response (200 OK)

{
  "result": true,
  "restricted_extensions": [".exe", ".apk", ".jar", ".php"],
  "archive_extensions": [".7z", ".zip", ".rar", ".tar.gz", ".bz2"],
  "enforcement_enabled": false,
  "plan": "unpaid",
  "cache_ttl": 86400
}

Response fields

Clients should call this once on startup and cache the results for 24 hours.

List supported hash algorithms

Example

curl -X GET "https://api.fast.io/current/upload/algos/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true,
  "algos": ["md5", "sha1", "sha256", "sha384", "crc32c"]
}

crc32c is the recommended client integrity checksum — see Integrity Checksums (CRC-32C).

Get chunk information

Query parameters

Example (all chunks)

curl -X GET "https://api.fast.io/current/upload/5uhlp-zzcds-g2ba5-rqnbo-s5ytn-geda/chunk/" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK, all chunks)

{
  "result": true,
  "chunks": {
    "1": 5242880,
    "2": 5242880,
    "3": 2097152
  }
}

To retrieve a specific chunk, you can also append the chunk number to the path:

Path parameters

Example (single chunk by path)

curl -X GET "https://api.fast.io/current/upload/5uhlp-zzcds-g2ba5-rqnbo-s5ytn-geda/chunk/1" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK, single chunk)

{
  "result": true,
  "chunk": {
    "1": 5242880
  }
}

Error responses

Delete a chunk

Query parameters

Example

curl -X DELETE "https://api.fast.io/current/upload/5uhlp-zzcds-g2ba5-rqnbo-s5ytn-geda/chunk/?order=3" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": true
}

Error responses

Quick Reference

Small file (one request, auto-add)

POST /current/upload/
  multipart: name, size, chunk, action=create, instance_id, folder_id
  -> 201: {id, new_file_id}                        # new_file_id usually null (finalization is asynchronous)

GET  /current/upload/{id}/details/?wait=60         # When new_file_id was null
  -> 200: {session: {status, new_file_id}}

Large file (chunked)

POST /current/upload/                              # Create session
  form: name, size, action=create, instance_id, folder_id
  -> 201: {id}

POST /current/upload/{id}/chunk/?order=N&size=N    # Upload chunks (up to 3 parallel)
  multipart: chunk
  query (recommended): hash_algo=crc32c, hash; file_crc32c on the carrier chunk
  -> 202

POST /current/upload/{id}/complete/                # Trigger assembly
  -> 202

GET  /current/upload/{id}/details/?wait=60         # Poll until complete
  -> 200: {session: {status, new_file_id}}

DELETE /current/upload/{id}                        # Clean up session
  -> 200

Stream upload (unknown file size)

POST /current/upload/                              # Create stream session
  form: name, stream=true, max_size, action=create, instance_id
  -> 201: {id}

POST /current/upload/{id}/stream/                  # Stream file body
  body: raw binary (application/octet-stream)
  -> 201 (auto-finalizes)

Manual add to storage (if no instance_id)

POST /current/workspace/{id}/storage/{folder}/addfile/
  form: name, from={"type":"upload","upload":{"id":"{upload_id}"}}
  -> 200

Batch upload (many small files)

POST /current/upload/batch/                        # Submit up to 200 small files
  multipart: instance_id, creator?, manifest (JSON), file_0..file_N
  (or) application/json: {instance_id, creator?, files: [{filename, content_b64, hash_algo?, hash?}]}
  -> 200: {batch_id, count_total, count_succeeded, count_errored, results[]}

GET  /current/upload/batch/{batch_id}/             # Fetch status record (1-hour TTL)
  -> 200: {batch_id, creator?, count_total, count_succeeded, count_errored, results[], created_ts}

Web upload (URL import)

POST /current/web_upload/                          # Create job
  form: source_url, file_name, profile_id, profile_type
  -> 201: {web_upload}

GET  /current/web_upload/                          # List jobs
  query: limit, offset, status
  -> 200: {web_uploads, total}

GET  /current/web_upload/{id}/details/             # Get job details
  -> 200: {web_upload}

DELETE /current/web_upload/?id={id}                # Cancel job
  -> 200: {canceled, id}

Upload management

GET  /current/upload/details/                      # List all sessions
GET  /current/upload/limits/                       # Get upload limits
GET  /current/upload/limits/extensions/            # Get restricted extensions
GET  /current/upload/algos/                        # List hash algorithms
GET  /current/upload/{id}/chunk/                   # Get all chunk info
GET  /current/upload/{id}/chunk/{order}            # Get single chunk info
DELETE /current/upload/{id}/chunk/?order=N          # Delete a chunk

Best Practices

• Check limits first: Query /upload/limits/ and /upload/limits/extensions/ before starting uploads.
• Use hash validation: Always provide chunk and file hashes to detect corruption early.
• Default to CRC-32C: Send hash_algo=crc32c with each chunk’s CRC-32C, and send the whole-file value — your per-chunk CRCs combined in order, no second pass — as file_crc32c on the first send of the chunk whose CRC completes last (sequential clients: the last chunk), and on that chunk’s retries only. Treat 10778 as terminal (re-upload in a new session) and 10779 as a client bug (resend the original value). After completion, compare the file’s crc32c in node details with your local value.
• Implement retry logic: Failed chunk uploads can be retried by re-uploading the same order.
• Track chunks locally: Maintain a local record of successfully uploaded chunks for resumability.
• Long-poll for completion: Use the wait parameter on the details endpoint instead of frequent polling.
• Clean up failures: DELETE failed sessions to free session quota.
• Cache extension restrictions: Call /upload/limits/extensions/ once and cache for 24 hours.
• Use auto-finalization: When all chunks total the declared file size, assembly triggers automatically. Explicit /complete/ is optional but recommended for reliability.
• Omit relative_path when unused: Do NOT send it as an empty string.