API keys, rate limits, and building a real pipeline

The REST API is the same one the web UI uses. The difference is that a script can be polite about it, and the platform will treat it accordingly.

Keys

• Create and revoke keys under Settings → API keys.
• Scope each key to the task: uploads, reads, or full access.
• Rotate without downtime by running two keys during a deploy.

curl -H "Authorization: Bearer $KEY" \
  -F "[email protected]" \
  https://zerostorage.net/api/files/upload

Rate limits

Limits are per key and per IP, with response headers showing the remaining budget. Back off on 429 using those headers instead of a fixed sleep — the budget refills continuously.

Retry pattern

1. Retry 429 and 5xx with exponential backoff and jitter.
2. Never retry a 401 or 403 — rotate the key instead.
3. Idempotency comes from hashes: re-sending the same file is free.

A pipeline that survives contact

Bulk imports go wrong in predictable ways: the network blips, a key rotates mid-run, and a naive loop hammers a server that is still recovering. The pattern that holds is boring — queue the work, run a handful of workers, and let the response headers pace them. Persist the hash of each finished item so a restart resumes instead of repeating. When a run ends with errors, the useful artefact is a list of hashes and status codes, not a log file you have to read like a novel.

• Cap concurrency first; raise it only while the headers show budget left.
• Checkpoint progress every batch, not every file.
• Alert on the ratio of 429s to successes — that ratio is the real health signal.

None of this is exotic. It is the difference between a script that runs once on your laptop and a pipeline someone else can operate without asking you how it works. Write the runbook while the failure modes are still fresh — which key scopes exist, what the steady-state concurrency is, and what a healthy day of responses looks like — because the person paged at 3am will not read the source first.

Browse the API reference and the playground before wiring anything in production.