Prepare a local file upload

Creates an upload job and returns signed credentials so you can POST a local file directly to the returned uploadUrl. After preparing, POST the file to uploadUrl as multipart form data with the returned params, signature, and file fields, then poll GET /uploads/{id} until status is ready.

See File uploads for a full walkthrough and curl examples.

Supported file types:

Images: JPEG, PNG, GIF, WebP
Videos: MP4, QuickTime (MOV)

File size limits:

Images: 10 MB max
GIFs: 15 MB max
Videos: 350 MB max

The returned credentials are short-lived. Upload the file before expiresAt.

POST/uploads/prepare

Authorization

AuthorizationBearer token · headerrequired

API key authentication. Generate an API key from your workspace settings.

Request body

requiredapplication/json

filenamestringrequired

Original filename, including extension.

min length 1

mimetypestringrequired

MIME type of the file (e.g., image/jpeg, video/mp4).

min length 1

sizeintegerrequired

File size in bytes.

Responses

200

Signed credentials for uploading the file

idstring<uuid>required

Upload job ID. Use this to poll GET /uploads/{id}.

statusstringrequired

Initial status while Ordinal waits for the file POST.

Allowed:awaiting_upload

uploadUrlstring<uri>required

URL to POST the file to as multipart form data.

paramsstringrequired

Signed upload params. Include verbatim as the params form field.

signaturestringrequired

Signature for the params. Include verbatim as the signature form field.

expiresAtstring<date-time>required

Time after which the signed credentials are no longer valid.

createdAtstring<date-time>required

400

Bad Request - Invalid input parameters

codestring

messagestring

dataobject

Show properties

errorsobject

401

Unauthorized - Missing or invalid API key

codestring

messagestring

429

Too Many Requests - Rate limit exceeded

codestring

messagestring

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Bodyapplication/json

filenamestring*Original filename, including extension.mimetypestring*MIME type of the file (e.g., image/jpeg, video/mp4).sizeinteger*File size in bytes.

Request

curl -X POST 'https://app.tryordinal.com/api/v1/uploads/prepare' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "filename": "product-photo.jpg",
  "mimetype": "image/jpeg",
  "size": 245678
}'

const response = await fetch("https://app.tryordinal.com/api/v1/uploads/prepare", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"filename\": \"product-photo.jpg\",\n  \"mimetype\": \"image/jpeg\",\n  \"size\": 245678\n}"
});

import requests

response = requests.post(
    "https://app.tryordinal.com/api/v1/uploads/prepare",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"filename\": \"product-photo.jpg\",\n  \"mimetype\": \"image/jpeg\",\n  \"size\": 245678\n}",
)

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "awaiting_upload",
  "uploadUrl": "https://upload.example.com",
  "params": "{\"auth\":{...},\"template_id\":\"...\"}",
  "signature": "sha384:...",
  "expiresAt": "2026-02-04T11:30:00.000Z",
  "createdAt": "2026-02-04T10:30:00.000Z"
}

{
  "code": "BAD_REQUEST",
  "message": "Bad Request",
  "data": {
    "errors": {
      "publishAt": [
        "Invalid date format"
      ],
      "status": [
        "Invalid enum value"
      ]
    }
  }
}

{
  "code": "UNAUTHORIZED",
  "message": "Invalid or unauthorized API key"
}

{
  "code": "TOO_MANY_REQUESTS",
  "message": "Rate limit of 100 requests per 60s exceeded. Quota resets in 45 seconds"
}