Skip to main content
POST
Add your own image to the media library

Authorizations

Authorization
string
header
required

Pass Authorization: Bearer scripe_sk_live_<...> (or scripe_sk_test_<...> for test keys) on every request. Keys are scoped to a single workspace and can be revoked from the Scripe dashboard.

The same header also accepts an OAuth 2.1 access token (scripe_oat_*); both credentials share one scope vocabulary and every operation below documents the scope it requires. An API key can hold every scope named on this surface except webhooks:manage, which is grantable to OAuth tokens only today — the webhook-endpoint operations answer 403 scope_missing to every API key. Operations that name no scope accept any valid token of the workspace.

Headers

Scripe-Api-Version
string

Pin the API version. Format YYYY-MM-DD. Omit to receive the currently rolling default. Unknown versions return 400 version_unsupported.

Example:

"2026-08-10"

Body

application/json

Exactly one of content_base64 or uploadId is required.

projectId
string

Project whose library receives the image. Optional for an OAuth principal with a default project pinned at consent time.

Example:

"proj_a1b2c3d4e5f6g7h8"

content_base64
string

Base64-encoded image bytes, ≤ ~3 MB decoded (larger request bodies are rejected at the platform edge as a bare HTTP 413 — use the uploadId path instead). Mutually exclusive with uploadId.

sha256
string

Optional hex SHA-256 of the DECODED image bytes (inline path only; refused beside uploadId). Strongly recommended when the caller can compute it — base64 relayed through model output corrupts silently, and a digest mismatch is rejected naming both digests instead of storing the wrong bytes.

uploadId
string

upl_… handle from POST /v1/uploads, after the bytes have been PUT to its signed URL. Mutually exclusive with content_base64. A handle whose object does not exist is a 422, not a 404 — the handle is valid, the upload never happened.

Example:

"upl_org_2aSH--30e8e643de8b4f01"

fileName
string

Original filename. On the inline path it is also how the content type is inferred when mimeType is omitted.

Maximum string length: 200
Example:

"keynote-stage.jpg"

mimeType
string

Image MIME type for the inline path. Ignored on the uploadId path, where the stored object's own content type (bound into the signature at mint time) is authoritative.

Maximum string length: 200
Example:

"image/png"

alt
string

Alt text, carried onto the post at attach time.

Maximum string length: 1000
title
string
Maximum string length: 120

Response

The created (or already-existing) asset.

data
object
required