Uploads

Safeput keeps file bytes out of your application server while placing them in private quarantine storage.

Upload flow

1. Your trusted backend calls POST /v1/uploads with a project API key.
2. Safeput reserves account-wide capacity and returns a 10-minute, single-use target.
3. Your client sends a known-length file to that target with PUT and every returned header.
4. Your backend can read the record with GET /v1/uploads/:id.

Use a unique Idempotency-Key for each logical upload attempt. Retrying the same request is safe; changing the body while reusing the key is rejected.

Trust boundary

Treat every uploaded object as untrusted. A successful PUT (204) means the Worker accepted exactly the declared bytes and durably published the private object for inspection. It does not mean the file has passed inspection.

The queue consumer validates the object metadata and runs the isolated scanner. Only a later clean status may make a file eligible for retrieval.

Limits

• Declared size: 1 byte through 52,428,800 bytes (50 MiB)
• Upload URL lifetime: 10 minutes
• Started transfer deadline: 5 minutes
• Storage: private R2; clients receive no R2 write credential
• API key scope: one project and one test or live environment

Targets use a scoped Authorization header; never replace it with the project key or put it in a URL/log. A file or browser Blob supplies Content-Length; omitting it returns 411. Content-Encoding is not accepted. Short bodies, oversized bodies and size mismatches cannot publish partial objects.

Once a transfer starts, its capability is consumed, even if the connection fails or the file is later rejected/deleted. Poll the existing upload after an uncertain response. Do not blindly create a duplicate: publication may be recovering. Use a new Idempotency-Key only when a new logical attempt is appropriate.

Admission limits are shared across an account’s projects and keys, including test keys. 429 admission_limit_exceeded means its file, byte, outstanding or issuance budget is exhausted. These operational limits are separate from scanned-byte billing; a failed pre-scan transfer has zero billable scanned bytes.

See the API reference for request and response fields.