Quickstart

The development API creates a private upload target, processes the uploaded bytes asynchronously, and makes a policy-approved file temporarily retrievable.

1. Create a project key

Log in to the development dashboard, create a test project, and create an API key. Save the complete sp_test_... value when it is shown; Safeput stores only its digest and cannot reveal it again. Keep the key on your backend.

2. Request an upload target

curl https://dev.safeput.dev/v1/uploads \
  --request POST \
  --header "Authorization: Bearer $SAFEPUT_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: invoice-2026-08-15" \
  --data '{"filename":"invoice.pdf","content_type":"application/pdf","size":12480}'

The response contains an upload record and an upload_target. The maximum declared file size is 52,428,800 bytes (50 MiB).

3. Upload the bytes

Use the returned URL within 10 minutes and preserve every returned header:

curl "$UPLOAD_URL" \
  --request PUT \
  --header "Authorization: $UPLOAD_AUTHORIZATION" \
  --header "Content-Type: application/pdf" \
  --upload-file invoice.pdf

Set UPLOAD_AUTHORIZATION to the returned upload_target.headers.Authorization value, not your project key. The target is single-use, including after rejection or deletion. Send a known-length file/Blob, not an unbounded chunked stream; the byte length must exactly match the declared size. A completed transfer returns 204 and does not yet mean the file is clean. The R2 bucket remains private.

4. Wait for inspection

curl "https://dev.safeput.dev/v1/uploads/$UPLOAD_ID" \
  --header "Authorization: Bearer $SAFEPUT_API_KEY"

Poll until status reaches clean, rejected, failed, or expired. Only a clean record with download_available: true can be retrieved.

5. Retrieve a clean file

curl "https://dev.safeput.dev/v1/uploads/$UPLOAD_ID/download-url" \
  --request POST \
  --header "Authorization: Bearer $SAFEPUT_API_KEY"

Use the returned download.url within five minutes. Safeput streams the file with a sanitized attachment filename, its detected content type, and no-store headers. Read Retrieving files for retention and security details.