Create Upload | Onepin

curl -X POST https://api.onepin.ai/api/v1/uploads \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "filename": "training_script.txt",
  "category": "script"
}'

{
  "data": {
    "upload": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "filename": "training_script.txt",
      "category": "script",
      "content_type": "text/plain",
      "status": "pending",
      "created_at": "2024-01-15T09:30:00Z",
      "updated_at": "2024-01-15T09:30:00Z",
      "workspace_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "format": "txt",
      "size_bytes": 1024,
      "char_count": 850,
      "line_count": 45,
      "download_url": "null",
      "context_type": "null",
      "context_id": "null"
    },
    "upload_url": "https://storage.onepin.ai/upload/3fa85f64-5717-4562-b3fc-2c963f66afa6?signature=abc123&expires=1700000000"
  },
  "meta": {
    "request_id": "req_1234567890abcdef",
    "timestamp": "2024-01-15T09:30:00Z"
  }
}

Request a presigned URL to upload a file to object storage (step 1 of 2).

The two-step upload flow:

POST /uploads — register the file and receive a short-lived upload_url. PUT your file bytes directly to that URL (do not send them to this API).
POST /uploads/{id} — confirm the upload completed and bind the file to a resource (e.g. a workflow). The file is moved to its final location and the upload record transitions from pending to uploaded.

category controls which file formats are accepted:

script — text-based formats (txt, srt, csv, json, xliff, docx)
dictionary — audio formats (mp3, wav, m4a, ogg, webm)

The presigned URL expires within a short window (see upload_url TTL in the response). If the URL expires before the PUT completes, discard this upload record and start over with a fresh POST /uploads call.

X-Workspace-Id is optional but recommended for workspace-scoped storage quota tracking. API keys with a bound workspace attach automatically.

Dual-auth: Bearer JWT or API key (scope uploads:write).

Request a presigned URL to upload a file to object storage (step 1 of 2). The two-step upload flow: 1. `POST /uploads` — register the file and receive a short-lived `upload_url`. PUT your file bytes directly to that URL (do not send them to this API). 2. `POST /uploads/{id}` — confirm the upload completed and bind the file to a resource (e.g. a workflow). The file is moved to its final location and the upload record transitions from `pending` to `uploaded`. `category` controls which file formats are accepted: - `script` — text-based formats (txt, srt, csv, json, xliff, docx) - `dictionary` — audio formats (mp3, wav, m4a, ogg, webm) The presigned URL expires within a short window (see `upload_url` TTL in the response). If the URL expires before the PUT completes, discard this upload record and start over with a fresh `POST /uploads` call. `X-Workspace-Id` is optional but recommended for workspace-scoped storage quota tracking. API keys with a bound workspace attach automatically. Dual-auth: Bearer JWT or API key (scope `uploads:write`).

Authentication

AuthorizationBearer

Clerk JWT token

AuthorizationBearer

Onepin live API key (op_live_...). Test and public keys are reserved in Phase 1.

Request

This endpoint expects an object.

filenamestringRequired1-255 characters

Original filename including extension (e.g. script.txt). Must include a file extension.

categoryenumRequired

File category. Determines which formats are accepted: script for text formats (txt, srt, csv, json, xliff, docx); dictionary for audio formats (mp3, wav, m4a, ogg, webm).

Response

Successful Response

dataobject

metaobject

Errors

422

Unprocessable Entity Error