Create a file (presigned upload)
Create a file record and get a presigned URL to upload the bytes directly to storage.
Flow:
- Compute the file’s SHA-256 hash and base64-encode it.
- Call this endpoint with the filename, MIME type, size, and checksum. You receive a
fileIdand a presigneduploadUrl. PUTthe raw bytes touploadUrlwith headersContent-Type: <mimeType>andx-amz-checksum-sha256: <checksum>. S3 verifies the checksum on write.- (Recommended) Call
POST /api/v1/files/:id/confirmto verify the upload and flip the record toCONFIRMEDimmediately. Otherwise it is confirmed automatically the first time it is fetched viaGET /api/v1/files/:id.
Why: the bytes go straight to storage, so there is no API-server size limit.
Authorizations
Personal API key, e.g. Authorization: Bearer sajn_sk_.... Not scope-limited — acts as the issuing user.
Headers
Bearer token for API authentication
Makes retries safe. A retry with the same key and the same request replays the stored response for 24 hours (header Idempotent-Replayed: true); the same key with a different request returns 400.
255Body
Body
Request a presigned upload URL and create a pending file record
Original filename including its extension
1 - 255MIME type of the file
application/pdf, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation, video/mp4, video/quicktime, video/x-msvideo, video/webm, image/jpeg, image/png, image/gif, image/webp, image/svg+xml File size in bytes (max 25 MB)
0 < x <= 26214400Base64-encoded SHA-256 checksum of the file. S3 enforces it on upload, so a mismatch rejects the bytes.
1File visibility (default PRIVATE)
PRIVATE, PUBLIC Response
Presigned upload details
Presigned upload details
The created file record id. Status is PENDING until the upload is confirmed on first access.
The S3 object key the file will be stored under
Presigned PUT URL (valid 1 hour). Upload the bytes here with headers Content-Type: and x-amz-checksum-sha256: .

