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

Overview

Fast.io 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 stored.
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 any HTTP/HTTPS URL. The server downloads and uploads the file asynchronously.

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

Upload Constraints

Upload Status Values

Terminal states: stored, assembly_failed, store_failed. Stop polling when you reach one of these.

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=12345678901234567890" \
  -F "folder_id=root" \
  -F "chunk=@notes.txt"

Response (201 Created)

{
  "result": "yes",
  "response": {
    "id": "u1abc-defgh-ijklm-nopqr-stuvw-xyz123",
    "creator": "my-web-client",
    "new_file_id": "f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4"
  },
  "current_api_version": "1.0"
}

Response fields

When instance_id and folder_id are provided, the file is automatically added to storage. No separate polling or addfile step is needed.

Response (without instance_id, 201 Created)

{
  "result": "yes",
  "response": {
    "id": "u1abc-defgh-ijklm-nopqr-stuvw-xyz123"
  },
  "current_api_version": "1.0"
}

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

Error responses

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=12345678901234567890" \
  -d "hash_algo=sha256" \
  -d "hash=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

Response (201 Created)

{
  "result": "yes",
  "response": {
    "id": "u1abc-defgh-ijklm-nopqr-stuvw-xyz123"
  },
  "current_api_version": "1.0"
}

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/u1abc-defgh-ijklm-nopqr-stuvw-xyz123/chunk/?order=1&size=5242880&hash_algo=sha256&hash=abc123def456..." \
  -H "Authorization: Bearer {jwt_token}" \
  -F "chunk=@chunk_001.bin"

Response (202 Accepted)

{
  "result": "yes",
  "current_api_version": "1.0"
}

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/u1abc-defgh-ijklm-nopqr-stuvw-xyz123/complete/" \
  -H "Authorization: Bearer {jwt_token}"

Response (202 Accepted)

{
  "result": "yes",
  "current_api_version": "1.0"
}

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.

Example

curl -X GET "https://api.fast.io/current/upload/u1abc-defgh-ijklm-nopqr-stuvw-xyz123/details/?wait=60" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": "yes",
  "response": {
    "session": {
      "id": "u1abc-defgh-ijklm-nopqr-stuvw-xyz123",
      "name": "annual-report.pdf",
      "size": 52428800,
      "status": "stored",
      "hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "hash_algo": "sha256",
      "created": "2025-01-20 10:30:00",
      "updated": "2025-01-20 10:35:00",
      "chunks": {
        "1": 5242880,
        "2": 5242880,
        "3": 5242880,
        "4": 5242880,
        "5": 5242880
      }
    }
  },
  "current_api_version": "1.0"
}

Response fields

Exit condition: Stop polling when status is stored, assembly_failed, or store_failed.

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/12345678901234567890/storage/root/addfile/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'from={"type":"upload","upload":{"id":"u1abc-defgh-ijklm-nopqr-stuvw-xyz123"}}'

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=12345678901234567890" \
  -d "folder_id=root"

Response:

{"result": "yes", "response": {"id": "u1abc-defgh-ijklm-nopqr-stuvw-xyz123"}, "current_api_version": "1.0"}

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

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

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

curl -X POST "https://api.fast.io/current/upload/u1abc-.../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/u1abc-.../complete/" \
  -H "Authorization: Bearer {jwt_token}"

4. Poll until stored

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

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

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

Response: {"result": "yes", "response": {"session": {"status": "stored", "new_file_id": "f3jm5-...", ...}}} — done

5. Clean up session

curl -X DELETE "https://api.fast.io/current/upload/u1abc-defgh-ijklm-nopqr-stuvw-xyz123" \
  -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.
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}" \
  -d "name=report-v2.pdf" \
  -d "size=1024" \
  -d "action=update" \
  -d "instance_id=12345678901234567890" \
  -d "file_id=f3jm5-zqzfx-pxdr2-dx8z5-bvnb3-rpjfm4" \
  -F "chunk=@report-v2.pdf"

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=12345678901234567890"

Response (201 Created)

{
  "result": "yes",
  "response": {
    "id": "u1abc-defgh-ijklm-nopqr-stuvw-xyz123"
  },
  "current_api_version": "1.0"
}

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/u1abc-defgh-ijklm-nopqr-stuvw-xyz123/stream/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @myfile.tar.gz

Response (201 Created)

{
  "result": "yes",
  "current_api_version": "1.0"
}

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 plan's maximum file size.
• The actual uploaded bytes must not exceed max_size.
• Stream mode sessions produce exactly one chunk — no multi-chunk assembly pipeline is needed.
• 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

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=12345678901234567890" \
  -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": "12345678901234567890",
  "creator": "my-importer",
  "files": [
    {"filename": "doc-001.txt", "content_b64": "SGVsbG8sIHdvcmxkIQ=="},
    {"filename": "doc-002.txt", "content_b64": "U2Vjb25kIGZpbGU="}
  ]
}

Each files entry accepts the same optional hash_algo and hash fields as the multipart manifest. The array position is the entry's logical index.

Example

curl -X POST "https://api.fast.io/current/upload/batch/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "12345678901234567890",
    "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": "yes",
  "response": {
    "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": 1605,
        "error_message": "hash_algo and hash must both be provided for a manifest entry."
      }
    ]
  },
  "current_api_version": "1.0"
}

Response fields

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 account plan.
• 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.
• Internal storage / finalization failure for the single entry.

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": "yes",
  "response": {
    "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": 1605, "error_message": "hash_algo and hash must both be provided for a manifest entry." }
    ],
    "created_ts": 1745000000
  },
  "current_api_version": "1.0"
}

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.

Web Upload (URL Import)

Import files from any HTTP/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/json

Parameters

Options bitfield

Example

curl -X POST "https://api.fast.io/current/web_upload/" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://example.com/files/document.pdf",
    "file_name": "document.pdf",
    "profile_id": "12345678901234567890",
    "profile_type": "workspace",
    "folder_id": "root"
  }'

Response (201 Created)

{
  "result": "yes",
  "response": {
    "web_upload": {
      "id": "aBcDeFgHiJkLmNoPqRsT123456",
      "user_id": "12345678901234567890",
      "profile_id": "12345678901234567890",
      "profile_type": "workspace",
      "source_url": "https://example.com/files/document.pdf",
      "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": "12345678901234567890",
      "error_message": null,
      "options": 0,
      "properties": null,
      "created": "2025-01-26 15:00:00",
      "updated": "2025-01-26 15:00:00"
    }
  },
  "current_api_version": "1.0"
}

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": "yes",
  "response": {
    "web_uploads": [
      {
        "id": "aBcDeFgHiJkLmNoPqRsT123456",
        "user_id": "12345678901234567890",
        "profile_id": "12345678901234567890",
        "profile_type": "workspace",
        "source_url": "https://example.com/files/document.pdf",
        "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",
        "updated": "2025-01-26 15:01:00"
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  },
  "current_api_version": "1.0"
}

Response fields

Get web upload job details

Path parameters

Example

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

Response (200 OK)

{
  "result": "yes",
  "response": {
    "web_upload": {
      "id": "aBcDeFgHiJkLmNoPqRsT123456",
      "user_id": "12345678901234567890",
      "profile_id": "12345678901234567890",
      "profile_type": "workspace",
      "source_url": "https://example.com/files/document.pdf",
      "file_name": "document.pdf",
      "status": "complete",
      "status_description": "Upload successfully completed",
      "bytes_downloaded": 52428800,
      "expected_size": 52428800,
      "upload_session_id": "xYzAbCdEfGhIjKlMnOpQ123456",
      "async_job_id": "aBcDeFgHiJkLmNoPqRsT789012",
      "creator": "12345678901234567890",
      "error_message": null,
      "options": 0,
      "created": "2025-01-26 15:00:00",
      "updated": "2025-01-26 15:02:00"
    }
  },
  "current_api_version": "1.0"
}

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=aBcDeFgHiJkLmNoPqRsT123456" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": "yes",
  "response": {
    "canceled": true,
    "id": "aBcDeFgHiJkLmNoPqRsT123456"
  },
  "current_api_version": "1.0"
}

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": "yes",
  "response": {
    "results": 2,
    "sessions": [
      {
        "id": "aBcDeFgHiJkLmNoPqRsT123456",
        "name": "document.pdf",
        "size": 52428800,
        "status": "uploading",
        "hash": "e3b0c44298fc1c14...",
        "hash_algo": "sha256",
        "created": "2025-01-20 10:30:00",
        "updated": "2025-01-20 10:35:00"
      }
    ]
  },
  "current_api_version": "1.0"
}

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/aBcDeFgHiJkLmNoPqRsT123456" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": "yes",
  "current_api_version": "1.0"
}

Error responses

Get upload limits

Query parameters

Example

# General limits (with org context)
curl -X GET "https://api.fast.io/current/upload/limits/?org=12345678901234567890" \
  -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=12345678901234567890" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": "yes",
  "response": {
    "limits": {
      "chunk_size": 104857600,
      "size": 42949672960,
      "chunks": 500,
      "sessions": 7500,
      "sessions_size_max": 214748364800
    }
  },
  "current_api_version": "1.0"
}

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=pro"

Response (200 OK)

{
  "result": "yes",
  "response": {
    "restricted_extensions": [".exe", ".apk", ".jar", ".php"],
    "archive_extensions": [".7z", ".zip", ".rar", ".tar.gz", ".bz2"],
    "enforcement_enabled": true,
    "plan": "free",
    "cache_ttl": 86400
  },
  "current_api_version": "1.0"
}

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": "yes",
  "response": {
    "algos": ["md5", "sha1", "sha256", "sha384"]
  },
  "current_api_version": "1.0"
}

Get chunk information

Query parameters

Example (all chunks)

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

Response (200 OK, all chunks)

{
  "result": "yes",
  "response": {
    "chunks": {
      "1": 5242880,
      "2": 5242880,
      "3": 2097152
    }
  },
  "current_api_version": "1.0"
}

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/aBcDeFgHiJkLmNoPqRsT123456/chunk/1" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK, single chunk)

{
  "result": "yes",
  "response": {
    "chunk": {
      "1": 5242880
    }
  },
  "current_api_version": "1.0"
}

Error responses

Delete a chunk

Query parameters

Example

curl -X DELETE "https://api.fast.io/current/upload/aBcDeFgHiJkLmNoPqRsT123456/chunk/?order=3" \
  -H "Authorization: Bearer {jwt_token}"

Response (200 OK)

{
  "result": "yes",
  "current_api_version": "1.0"
}

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}

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
  -> 202

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

GET  /current/upload/{id}/details/?wait=60         # Poll until stored
  -> 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: from={"type":"upload","upload":{"id":"{upload_id}"}}
  -> 200

Web upload (URL import)

POST /current/web_upload/                          # Create job
  json: 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 plan 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.
• 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.