Upload API

Authentication

1. Open Settings and sign in.
2. Your upload API token is generated automatically. Use Show or Copy token to retrieve it.
3. Send the token in the Authorization header on every v1 API request.

Authorization: Bearer <FILECAST_TOKEN>

Tokens have the fixed uploads:own scope. They can create, resume, inspect and forward files belonging to your account, using your saved host credentials. They cannot read those credentials, access administration or manage other tokens. Session cookies do not authenticate v1 requests.

Each account has one token that never expires. Use Regenerate in Settings to replace it; the previous token immediately becomes invalid. Update your scripts with the new token. Store tokens in an environment variable or a secret manager, never in a URL or client-side application.

Quick start with Python

The client uses the Python 3.9+ standard library, with no additional packages. Download it, set your token, and choose your host IDs.

# Paste your Filecast token at the hidden prompt.
read -rsp 'Filecast token: ' FILECAST_TOKEN; printf '\n'
export FILECAST_TOKEN

python3 filecast-upload.py ./example.zip --hosts vikingfile,gofile

# To continue an interrupted upload, reuse its printed upload ID.
python3 filecast-upload.py ./example.zip --hosts vikingfile,gofile --resume UPLOAD_ID

unset FILECAST_TOKEN

The client checks received chunk hashes before skipping them, sends missing chunks and queues your chosen hosts. It prints the Filecast share URL. Host forwarding runs in the background; the client does not wait for all hosts to finish.

Supported IDs: buzzheavier, vikingfile, gofile, pixeldrain, 1fichier, rapidgator, k2s. Use GET /hosts for enabled hosts and credential requirements. Configure host accounts in Settings before using hosts that require them.

The upload flow

1. Create a session. Send the filename and exact byte size to POST /uploads. Keep the returned id.
2. Send the bytes. Split the file into 8 MiB chunks. PUT each chunk to uploadUrl?part=N using the session token. Parts start at 1. Keep every returned receipt.
3. Complete the file. Send all receipts in part order to POST /uploads/{id}/complete. Filecast verifies the parts and calculates a full-file SHA-256 checksum.
4. Choose destinations. Call POST /uploads/{id}/transfers once per selected host. Each call returns a jobId and shareUrl.
5. Track progress. Poll GET /uploads/{id} for jobs. Statuses are queued, uploading, success or error. Successful host links appear on the same Filecast share page.

Every part is exactly 8,388,608 bytes except the last. Its receipt contains partNumber and etag; the etag is the SHA-256 of that part. Always use the returned upload URL rather than constructing one: byte transfers may use a different hostname.

set -euo pipefail
BASE='https://fileca.st/api/v1'
printf 'test' > filecast-api-example.txt

SESSION=$(curl --fail-with-body -sS "$BASE/uploads" \
  -H "Authorization: Bearer $FILECAST_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"name":"filecast-api-example.txt","size":4}')

UPLOAD_ID=$(printf '%s' "$SESSION" | jq -r '.id')
UPLOAD_URL=$(printf '%s' "$SESSION" | jq -r '.uploadUrl')
UPLOAD_TOKEN=$(printf '%s' "$SESSION" | jq -r '.token')
printf 'Upload ID: %s\n' "$UPLOAD_ID"

RECEIPT=$(curl --fail-with-body -sS -X PUT "$UPLOAD_URL?part=1" \
  -H "Authorization: Bearer $UPLOAD_TOKEN" \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @filecast-api-example.txt)

PARTS=$(jq -nc --argjson receipt "$RECEIPT" '{parts:[$receipt]}')
curl --fail-with-body -sS "$BASE/uploads/$UPLOAD_ID/complete" \
  -H "Authorization: Bearer $FILECAST_TOKEN" \
  -H 'Content-Type: application/json' --data "$PARTS"

curl --fail-with-body -sS "$BASE/uploads/$UPLOAD_ID/transfers" \
  -H "Authorization: Bearer $FILECAST_TOKEN" \
  -H 'Content-Type: application/json' --data '{"host":"vikingfile"}'

# Repeat this request to check asynchronous host transfer progress.
curl --fail-with-body -sS "$BASE/uploads/$UPLOAD_ID" \
  -H "Authorization: Bearer $FILECAST_TOKEN"

unset UPLOAD_TOKEN SESSION FILECAST_TOKEN

Resume & retries

Keep the upload ID after an interruption. Fetch GET /uploads/{id} to check its state and metadata, then GET /uploads/{id}/parts for received receipts, the upload URL and a session token. Confirm that the local filename, size and chunk hashes match before sending only missing parts.

• Expiry stays fixed: resuming does not extend the 24-hour lifetime.
• Completed files: if the state is ready, compare the full SHA-256 and proceed to host transfers.
• Safe retries: completion is idempotent. A repeated transfer request returns an existing active or successful job for the same upload and host. Serialize requests for the same host. Failed jobs can be retried while the staged file is available.
• Session creation is not idempotent: a timed-out creation may have succeeded. An unused session expires automatically.
• Keep resumable sessions: do not call DELETE if you intend to continue uploading.

Technical file metadata

After upload completion, Filecast reads technical details in the background while host transfers continue. GET /uploads/{id} includes metadataStatus, metadataCheckedAt and metadata.

Status is pending, processing, ready, partial, failed or unavailable. Metadata contains version: 1, detected mime/format, kind, short summary strings, technical groups with named label/value rows, and limited. Available fields depend on the file type.

Selected technical details appear on the public share page and remain after staging cleanup. Personal tags, archive paths and file contents are excluded. Values describe the uploaded source and do not constitute a safety or full-file validation result. A completed source released after transfer may remain staged for up to ten minutes while metadata is read, within the original session expiry.

Endpoint reference

All paths below are relative to https://fileca.st/api/v1. Every endpoint requires your Filecast API token. JSON request bodies use Content-Type: application/json. Successful v1 operations return HTTP 200.

{"name":"example.zip","size":12345}

{"parts":[{"partNumber":1,"etag":"<SHA-256 of part 1>"}]}

{"host":"vikingfile"}

Byte transfer endpoint

PUT {uploadUrl}?part=N accepts raw bytes with Content-Type: application/octet-stream and the session token. It returns {partNumber, etag}. Do not send the long-lived API token here, and do not forward authorization headers to unexpected redirect destinations.

Errors & limits

Error bodies use {"error":"message"}. Always check the HTTP status before interpreting the response as a successful result. Poll conservatively, for example every 5–10 seconds, and respect Retry-After on HTTP 429.

The API applies a 60-request-per-minute client-IP limit. Files must be 1–1,073,741,824 bytes, JSON bodies are limited to 64 KiB, and staged files expire 24 hours after creation. Active host jobs retain their source until they finish. Storage capacity and individual host quotas may impose additional limits.

Revoking access

Regenerating your Filecast token immediately blocks subsequent v1 requests using the previous token. A previously issued session token may still accept file bytes until its expiry; cancel that session to stop new parts. A revoked API token cannot complete the upload or queue transfers. Already queued transfers finish independently.

Identical Buzzheavier files

For authenticated Buzzheavier transfers, Filecast checks earlier successful links from your account with the same filename and size. A link is reused only after fresh host metadata confirms file identity and the exact SHA-256. This avoids sending the bytes again. Such jobs return reused: true; other jobs return false. Missing, inaccessible or different files are never silently substituted.

Share links

Anyone with a Filecast share URL can view its host links. Share pages are unlisted and marked noindex. Availability checks run on the server and are cached for 15 minutes; “Unknown” means the host did not confirm availability, not that the file was deleted.