​

Uploads

1. POST /v1/uploads → returns { id: "upl_...", uploadUrl, ... }.
2. PUT <uploadUrl> with your file bytes (no auth needed; the signed URL carries it). The S3 service receives the bytes directly.
3. POST /v1/media / POST /v1/sources / POST /v1/knowledge with uploadId: "upl_...".

• File payloads bypass the API edge entirely — Vercel and Cloudflare function tiers cap request bodies at ~4 MB, so a single-shot upload would not work for podcasts or PDFs.
• The content type is part of the signature, so S3 rejects a PUT that sends a different one.
• The PUT can be resumed (S3 multi-part) without coordinating with Scripe’s API.

MCP hosts don’t need this flow for small files (≤ ~3 MB decoded) — the create_source_file and add_to_knowledge_base tools accept file bytes inline as base64. Anything larger MUST come through this flow: bigger inline payloads are rejected at the platform edge as a bare HTTP 413.

​

POST /v1/uploads

curl -i https://api.scripe.io/v1/uploads \
  -X POST \
  -H "Authorization: Bearer $SCRIPE_OAUTH_TOKEN" \
  -H "Scripe-Api-Version: 2026-08-10" \
  -H "Content-Type: application/json" \
  -d '{
    "contentType": "audio/mpeg",
    "maxSizeBytes": 104857600
  }'

​

Request body

​

Allowed content types and size caps

​

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "id": "upl_9f2c4b7ae1d06835--3f9a1c7e2b5d40a8",
    "uploadUrl": "https://scripe-uploads.s3.amazonaws.com/api-uploads/9f2c4b7ae1d06835/3f9a1c7e2b5d40a8?X-Amz-Algorithm=…",
    "method": "PUT",
    "contentType": "audio/mpeg",
    "maxSizeBytes": 104857600,
    "expiresAt": "2026-05-15T08:36:00.000Z"
  }
}

​

Semantics

• id is the handle you pass as uploadId — to POST /v1/media, POST /v1/sources, or POST /v1/knowledge.
• Do not send an Authorization header on the PUT — the signature is already in uploadUrl, and an extra header breaks it.
• contentType and maxSizeBytes echo what you signed for. maxSizeBytes is not enforced by the signature; see the caps section above for where it actually is enforced.
• id is upl_<workspaceId>--<uploadId>. Both halves are bare ids with no prefix of their own: the workspace half is the internal 16-hex id for an API-key caller or an org_… id for an OAuth caller, and the upload half is a 16-hex id. Treat the whole string as opaque rather than splitting it.
• Past expiresAt the URL fails the signature check rather than returning a friendly error.

​

Doing the PUT

curl -i -X PUT "$UPLOAD_URL" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @./episode-12.mp3

• The Content-Type header on the PUT must match contentType from the response — S3 enforces it as part of the signature.
• The body must be the raw file bytes. No multipart/form-data wrapping.
• A successful PUT returns 200 OK with an empty body.
• A 403 with SignatureDoesNotMatch usually means the Content-Type header diverged or the URL was URL-decoded somewhere in your client.

​

Errors

​

What’s NOT here (yet)

• Listing or deleting upload handles. Handles expire after 15 minutes if not redeemed, and a successful ingest job deletes the underlying S3 object. There’s no surface to list pending uploads — treat them as fire-and-forget.
• Resumable / multi-part uploads. Use the underlying AWS multi-part signing if your client library supports it; the URL we return is still a single-PUT signed URL.
• GET on uploads. We do not expose the file once it’s uploaded; the download path is through the resource that consumed it (Source surfaces a transcript preview, KnowledgeDocument surfaces summary metadata).