Skip to main content
POST
/
v1
/
uploads
Reserve a presigned upload slot
curl --request POST \
  --url https://api.example.com/v1/uploads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "content_type": "chemical/x-pdb",
  "filename": "antigen.pdb",
  "size_bytes": 12345
}
'
{
  "content_type": "chemical/x-pdb",
  "created_at": "2026-04-23T14:15:00+00:00",
  "expires_at": "2026-04-30T14:15:00+00:00",
  "filename": "antigen.pdb",
  "id": "dddd4444-eeee-5555-ffff-666677778888",
  "object": "upload",
  "size_bytes": 12345,
  "storage_path": "aaaa1111-2222-3333-4444-555566667777/dddd4444-eeee-5555-ffff-666677778888/antigen.pdb",
  "token": "eyJhbGciOi...",
  "upload_url": "https://<project>.supabase.co/storage/v1/object/upload/sign/api-uploads/..."
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Body for POST /v1/uploads.

​
filename
string
required

Original filename — used for logging and the Content-Disposition header when the file is re-served. Not used to pick a storage path; paths are opaque UUIDs.

Required string length: 1 - 255
Example:

"antigen.pdb"

​
content_type
string
required

MIME type of the bytes the client will PUT. One of chemical/x-pdb, text/plain, or application/octet-stream.

Example:

"chemical/x-pdb"

​
size_bytes
integer
required

Byte count the client will upload. Must be positive and at most 50 MB. Larger payloads are rejected 400.

Required range: x <= 52428800
Example:

12345

Response

Successful Response

Catalogue entry + presigned URL for one client upload.

​
id
string
required

Opaque upload identifier (UUID). Pass this to downstream submit endpoints.

Example:

"dddd4444-eeee-5555-ffff-666677778888"

​
filename
string
required

Echo of the caller's filename.

​
content_type
string
required

Echo of the caller's declared content type.

​
size_bytes
integer
required

Echo of the caller's declared byte count.

​
upload_url
string
required

Presigned Supabase Storage URL. PUT the file bytes to this URL within the TTL. Include the token field as an Authorization: Bearer header if your HTTP client can't follow the query-string auth baked into the URL.

Example:

"https://<project>.supabase.co/storage/v1/object/upload/sign/api-uploads/..."

​
token
string
required

Bearer token matching upload_url. Only needed by clients that issue the PUT without preserving the URL's query string.

​
storage_path
string
required

Object path within the api-uploads bucket. Stable for the lifetime of this upload; use it if you later need to fetch the bytes server-side.

Example:

"aaaa1111-2222-3333-4444-555566667777/dddd4444-eeee-5555-ffff-666677778888/antigen.pdb"

​
created_at
string
required

ISO-8601 timestamp (UTC) when the upload slot was reserved.

​
expires_at
string
required

ISO-8601 timestamp (UTC) when the unreferenced upload is eligible for deletion (7 days after creation). Once the upload is referenced by a submitted job, it's retained for the job's lifetime.

​
object
string
default:upload

Polymorphic discriminator. Always upload.

Allowed value: "upload"