API Documentation

Create a token in your panel under Settings → API tokens. Send it on every request in the Authorization header. Tokens are shown once at creation — store them securely. Each token acts on behalf of your account and only ever sees your own files.

Authorization: Bearer f2s_YOUR_TOKEN

Errors use standard HTTP status codes and return a JSON body with an error message. Common codes: 401 (missing/invalid token), 403 (quota or plan limit), 404 (file not found), 409 (conflict — e.g. the file is already in your account, see POST /v1/uploads), 422 (bad request body), 503 (no storage server available).

{
  "error": "Invalid or revoked API token."
}

Returns the token owner’s account, active plan and current storage usage.

curl https://api.fast2share.com/v1/user \
  -H "Authorization: Bearer f2s_YOUR_TOKEN"

{
  "id": 42,
  "email": "[email protected]",
  "display_name": "You",
  "plan": {
    "name": "premium-monthly",
    "max_file_size": 5368709120,
    "storage_quota": 107374182400
  },
  "usage": {
    "used_bytes": 2147483648,
    "file_count": 12,
    "remaining_bytes": 105226698752
  }
}

Lists your completed files, newest first. Cursor-paginated: pass the returned next_before as ?before= for the next page. Filter by name with ?q=.

curl "https://api.fast2share.com/v1/files?before=0&q=report" \
  -H "Authorization: Bearer f2s_YOUR_TOKEN"

{
  "data": [
    {
      "uuid": "3f1c…-…-…",
      "name": "report.pdf",
      "size": 184320,
      "mime": "application/pdf",
      "sha256": "9f86d0…",
      "status": "completed",
      "downloads": 3,
      "share_url": "https://…/f/3f1c…",
      "created_at": "2026-07-01T10:00:00+00:00",
      "expires_at": null
    }
  ],
  "next_before": 1057
}

Finds your files by name. ?q= is required and matches anywhere in the filename, case-insensitively. Same cursor pagination as the listing (?before=), and the search spans every folder unless you scope it with ?folder_id= (0 = files sitting at the root).

curl "https://api.fast2share.com/v1/files/search?q=invoice" \
  -H "Authorization: Bearer f2s_YOUR_TOKEN"

{
  "query": "invoice",
  "data": [
    {
      "uuid": "3f1c…-…-…",
      "name": "invoice-2026-07.pdf",
      "size": 184320,
      "mime": "application/pdf",
      "status": "completed",
      "share_url": "https://…/f/3f1c…",
      "created_at": "2026-07-01T10:00:00+00:00"
    }
  ],
  "next_before": null
}

Every folder on your account, top-level folders first. Use the id as the folder_id when moving or copying a file.

curl https://api.fast2share.com/v1/folders \
  -H "Authorization: Bearer f2s_YOUR_TOKEN"

{
  "data": [
    { "id": 12, "name": "Invoices", "parent_id": null, "created_at": "2026-06-02T09:12:00+00:00" },
    { "id": 19, "name": "2026",     "parent_id": 12,   "created_at": "2026-06-02T09:13:00+00:00" }
  ]
}

Creates a folder. name is required and must be unique on your account (case-insensitive) — a clash answers 409. Pass parent_id to nest it: folders go one level deep only, and a parent holds at most one sub-folder, so a parent that is itself nested (or already has a child) answers 422.

curl -X POST https://api.fast2share.com/v1/folders \
  -H "Authorization: Bearer f2s_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Invoices","parent_id":null}'

{
  "id": 12,
  "name": "Invoices",
  "parent_id": null,
  "created_at": "2026-07-31T08:20:00+00:00"
}

Upload walkthrough — uploads are two steps because bytes go straight to the storage server (via the resumable tus protocol); they never pass through this API. This call validates your plan/quota and returns a tus endpoint plus a signed upload_token.

1. POST /v1/uploads with the filename and size → returns upload_url, upload_token and uuid (this endpoint).
2. Perform a tus upload to upload_url, adding the metadata token <upload_token>. Any tus client works (e.g. tus-js-client, tusc). Send the bytes in chunks (8 MB recommended): a single tus request carrying the whole file is rejected with 413 by the storage CDN once the body exceeds ~100 MB.
3. Poll GET /v1/files/{uuid}/status until it reports completed, then use the returned share_url.

Skip the transfer with dedup (optional). If the same bytes are already stored, the file can be created instantly — nothing is uploaded:
• fingerprint = SHA-256 of the first 8 MB concatenated with the last 8 MB (reads ≤16 MB; if the file is ≤8 MB it is simply the SHA-256 of the whole file, and between 8 and 16 MB the two ranges cover it once, without overlapping). Always send this when you want dedup — it is how the API knows you really hold the file, so bytes owned by another account are never shared on a bare checksum.
• sha256 = full-file SHA-256, hex. Send it together with the fingerprint and the answer is immediate: if your account already has that file nothing is created and you get 409 with {"status":"exists","uuid":…,"share_url":…} pointing at your existing copy; if another account owns the bytes they are shared with you instantly: {"status":"completed","deduped":true,"share_url":…} — done, nothing uploaded.
• For big files hash lazily instead: send only the fingerprint. A reply of {"status":"need_hash"} means a possible match exists — full-hash the file and call POST /v1/uploads/{uuid}/confirm. Any other reply is a normal ticket; upload as usual.
Omit both fields to always upload.

curl -X POST https://api.fast2share.com/v1/uploads \
  -H "Authorization: Bearer f2s_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filename":"report.pdf","size":184320,"type":"application/pdf","fingerprint":"5b41e3…","sha256":"9f86d0…"}'

{
  "uuid": "3f1c…-…-…",
  "status": "pending",
  "upload_url": "https://storage1.example.com/files/",
  "upload_token": "eyJ1d….<sig>",
  "protocol": "tus",
  "metadata_key": "token"
}

// deduped instead — the bytes were already stored, nothing to upload:
{
  "uuid": "3f1c…-…-…",
  "status": "completed",
  "deduped": true,
  "size": 184320,
  "sha256": "9f86d0…",
  "share_url": "https://…/f/3f1c…"
}

Second step of the fingerprint flow: call this only after POST /v1/uploads answered {"status":"need_hash"}, with the full-file sha256. The fingerprint and size are the ones you sent when the upload was created — they are not re-read from this request. Same three outcomes as above: already in your account → 409 exists (nothing stored); owned elsewhere → completes right away (deduped); otherwise the fingerprint merely collided and you get the normal upload_url / upload_token ticket — upload as in step 2 above.

curl -X POST https://api.fast2share.com/v1/uploads/3f1c…-…-…/confirm \
  -H "Authorization: Bearer f2s_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sha256":"9f86d0…"}'

{
  "uuid": "3f1c…-…-…",
  "status": "completed",
  "deduped": true,
  "size": 184320,
  "sha256": "9f86d0…",
  "share_url": "https://…/f/3f1c…"
}

Returns metadata for a single file you own.

curl https://api.fast2share.com/v1/files/3f1c…-…-… \
  -H "Authorization: Bearer f2s_YOUR_TOKEN"

{
  "uuid": "3f1c…-…-…",
  "name": "report.pdf",
  "size": 184320,
  "mime": "application/pdf",
  "sha256": "9f86d0…",
  "status": "completed",
  "downloads": 3,
  "share_url": "https://…/f/3f1c…",
  "created_at": "2026-07-01T10:00:00+00:00",
  "expires_at": null
}

Lightweight probe for an upload’s state: pending, completed or failed. Once completed it also returns the share_url.

curl https://api.fast2share.com/v1/files/3f1c…-…-…/status \
  -H "Authorization: Bearer f2s_YOUR_TOKEN"

{
  "uuid": "3f1c…-…-…",
  "status": "completed",
  "size": 184320,
  "share_url": "https://…/f/3f1c…"
}

Mints a ready-to-use direct download URL for a file you own. The link streams the bytes straight away with no browser session required (use it from a script/curl) and expires after ~5 minutes. Requires an active Premium subscription (admins always allowed).

curl https://api.fast2share.com/v1/files/3f1c…-…-…/download \
  -H "Authorization: Bearer f2s_YOUR_TOKEN"

{
  "uuid": "3f1c…-…-…",
  "name": "report.pdf",
  "size": 184320,
  "download_url": "https://…/d/9xA2…",
  "expires_in": 300
}

Changes the display name of a file you own. The share link (uuid) does not change, so links you already handed out keep working — only the name shown on the share page and sent with the download changes. Path separators and control characters are stripped; the name is capped at 512 characters.

curl -X POST https://api.fast2share.com/v1/files/3f1c…-…-…/rename \
  -H "Authorization: Bearer f2s_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"invoice-july.pdf"}'

{
  "uuid": "3f1c…-…-…",
  "name": "invoice-july.pdf",
  "size": 184320,
  "status": "completed",
  "share_url": "https://…/f/3f1c…"
}

Files a file you own into one of your folders. Send {"folder_id": 0} (or omit it) to move it back to the root. The folder must be yours, otherwise 404.

curl -X POST https://api.fast2share.com/v1/files/3f1c…-…-…/move \
  -H "Authorization: Bearer f2s_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder_id":12}'

{
  "uuid": "3f1c…-…-…",
  "name": "invoice-july.pdf",
  "status": "completed",
  "share_url": "https://…/f/3f1c…",
  "folder_id": 12
}

Puts a file somebody else shared with you into your own account, with your own share link — here {uuid} is the source file's share slug, not one of yours. No bytes are transferred: the copy points at the same stored object, so it completes instantly and counts against your storage quota like any other file.

The source must be public, finished, and its owner must allow copying — otherwise you get 403. 409 means it is already your file (or already in your account), and 403 also covers "not enough storage left". Optional body fields: folder_id, is_public (default true) and free_download (default false).

curl -X POST https://api.fast2share.com/v1/files/3f1c…-…-…/copy \
  -H "Authorization: Bearer f2s_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folder_id":12,"is_public":true}'

{
  "uuid": "8b2e…-…-…",
  "name": "report.pdf",
  "size": 184320,
  "status": "completed",
  "share_url": "https://…/f/8b2e…",
  "copied": true
}

Soft-deletes a file you own; it stops being downloadable immediately and its bytes are reclaimed shortly after.

curl -X POST https://api.fast2share.com/v1/files/3f1c…-…-…/delete \
  -H "Authorization: Bearer f2s_YOUR_TOKEN"

{ "ok": true, "uuid": "3f1c…-…-…" }