Upload a media asset

curl --request POST \
  --url https://api.paigeme.dev/v1/media \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "source_url": "<string>",
  "name": "<string>",
  "caption": "<string>",
  "filename": "<string>",
  "mime": "<string>",
  "describe_image": true
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    source_url: '<string>',
    name: '<string>',
    caption: '<string>',
    filename: '<string>',
    mime: '<string>',
    describe_image: true
  })
};

fetch('https://api.paigeme.dev/v1/media', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.paigeme.dev/v1/media"

payload = {
    "source_url": "<string>",
    "name": "<string>",
    "caption": "<string>",
    "filename": "<string>",
    "mime": "<string>",
    "describe_image": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "success": true,
  "data": {
    "asset": {
      "slug": "<string>",
      "media_id": "<string>",
      "meta_status": "registered",
      "meta_uploaded_at": "<string>",
      "mime": "<string>",
      "bytes": 123,
      "filename": "<string>",
      "kind": "image",
      "caption": "<string>",
      "source": "chat_upload",
      "created_at": "<string>"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "details": {}
  },
  "request_id": "<string>"
}

Upload a media asset

Stores one file against the project, registers it with Meta for sending, and returns the slug your bot resolves it by at runtime (sendMedia(to, "<slug>") / getMediaId("<slug>")). Write the slug into a table row with POST /v1/tables/{table}/rows and the bot can send the asset later without ever touching the dashboard.

Three transports, pick one. Every one of them needs the file itself:

multipart/form-data with a single part named file, plus optional name and caption text fields. Up to 20 MB.
JSON { "source_url": "https://..." } — Paige downloads it for you. Up to 20 MB. Only public http(s) URLs: private, loopback, link-local and other reserved addresses are refused (400 blocked_source_url), redirects are re-checked at every hop and capped, and a non-http(s) scheme is 400 invalid_source_url. Add filename / mime to override what the remote server declares.
JSON { "data": "<base64>", "filename": "...", "mime": "..." } — inline bytes, capped at 8 MB decoded, lower than the other two on purpose: base64 costs about 4/3 in transit and is buffered whole in memory, so large files belong on multipart or source_url. A data: URI prefix is accepted and stripped.

name is the slug. Send it to choose the bot-facing name; omit it and the filename is used. It is normalized to lowercase letters, digits and hyphens. A slug that already exists is 409 SLUG_EXISTS — it is never overwritten, because the existing asset may already be referenced by deployed code or a published flow.

Meta registration is best-effort, and the response tells you the truth about it. media_id is null and meta_status is "pending" when the file was stored but not registered (typically because no WhatsApp number is connected). The asset is still usable and Paige retries registration on a schedule; a failed register is never reported as a success. meta_status is "expired" once the id passes Meta’s 30-day lifetime.

Size and type. Oversize is 413 file_too_large; a type Paige cannot ingest is 415; an empty file is 400. Images, video, audio, PDF, DOCX, plain text and markdown are accepted.

Uploading an image costs credits. Paige runs one AI vision call per image to write the knowledge description your bot answers from, and that call is billed to the project like any other AI usage — it shows up in Usage alongside builds. Out of credits is 402 insufficient_credits. Send describe_image: false to skip it: the file is still stored, still registered with Meta and still usable, it just gets no AI-written description and costs nothing. Non-image uploads (PDF, DOCX, text) use no AI at all and are always free.

Two limits apply beyond the per-request throttle. Uploads are metered by BYTES as well as by request count, so a burst of large files can return 429 rate_limited even while you are inside the request-per-minute budget — retry after the window or upload in smaller batches. And each project has a total media storage ceiling: an upload that would exceed it is refused with 413 storage_limit_exceeded rather than quietly succeeding. GET /v1/media reports storage.used_bytes / storage.remaining_bytes so you can check before you push.

Send an Idempotency-Key header to make a retry safe. The fingerprint covers the file bytes, so retrying the same upload replays the original response, while reusing the key for a different file is 409 idempotency_key_mismatch rather than a silently-dropped upload.

Required scope: media:write

POST

media

Upload a media asset

curl --request POST \
  --url https://api.paigeme.dev/v1/media \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "source_url": "<string>",
  "name": "<string>",
  "caption": "<string>",
  "filename": "<string>",
  "mime": "<string>",
  "describe_image": true
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    source_url: '<string>',
    name: '<string>',
    caption: '<string>',
    filename: '<string>',
    mime: '<string>',
    describe_image: true
  })
};

fetch('https://api.paigeme.dev/v1/media', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.paigeme.dev/v1/media"

payload = {
    "source_url": "<string>",
    "name": "<string>",
    "caption": "<string>",
    "filename": "<string>",
    "mime": "<string>",
    "describe_image": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "success": true,
  "data": {
    "asset": {
      "slug": "<string>",
      "media_id": "<string>",
      "meta_status": "registered",
      "meta_uploaded_at": "<string>",
      "mime": "<string>",
      "bytes": 123,
      "filename": "<string>",
      "kind": "image",
      "caption": "<string>",
      "source": "chat_upload",
      "created_at": "<string>"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body",
    "details": {}
  },
  "request_id": "<string>"
}

Authorizations

Authorization

string

header

required

Project API key issued in Settings → API keys. Send it as Authorization: Bearer pk_live_….

Headers

X-Paige-Project

string

Target project id, for an MCP OAuth bearer (mcp_at_…) attached to more than one project — get ids from GET /v1/projects. Matched case-insensitively.

Omit it and a READ falls back to the connection's default project; a mutation (any non-GET) on a connection with 2+ projects is rejected with 400 project_required — a write is never defaulted to a guessed project. A connection with exactly one project never needs the header.

Scopes are checked against the SELECTED project only, never a union across the connection.

For a pk_ API key the header selects nothing — one key is one project's context — but it IS validated: omit it and the key's own project is used, send it and it must name that project, otherwise the call is rejected with 403 project_not_attached (a blank value is 400 invalid_project_header, as above).

Body

Option 1
Option 2

source_url

string<uri>

required

Public http(s) URL Paige downloads the file from. Private, loopback and link-local addresses are refused, redirects are re-checked at every hop.

name

string

Optional bot-facing name for the asset. Normalized to a slug; blank falls back to the filename.

caption

string | null

Maximum string length: 2000

filename

string

Overrides the filename derived from the URL. The slug still comes from name when you send one.

Required string length: 1 - 255

mime

string

Overrides the server's Content-Type. Use it when the host serves the file as application/octet-stream.

Required string length: 1 - 255

describe_image

Run the AI vision description on an image upload (default true). It costs credits, so set false to store and register the file without it. Ignored for non-image files. Accepts a boolean, or true/false/1/0 as a multipart form field.

Response

Success.

success

enum<boolean>

required

Available options:

true

data

object

required

Hide child attributes

data.asset

object

required

Hide child attributes

data.asset.slug

string

required

The bot-facing name. sendMedia(to, "<slug>") and getMediaId("<slug>") resolve by this.

data.asset.media_id

string | null

required

Meta's id for the registered copy, used when the bot sends the file. Null when registration did not happen (usually no WhatsApp number connected) — the asset is still stored and Paige retries on a schedule.

data.asset.meta_status

enum<string>

required

registered — ready to send. pending — stored but not registered with Meta yet. expired — the id passed Meta's 30-day lifetime and is being refreshed.

Available options:

registered,

pending,

expired

data.asset.meta_uploaded_at

string | null

required

When the file was registered with Meta (ISO 8601), or null.

data.asset.mime

string | null

required

Stored mime type, e.g. image/png.

data.asset.bytes

number | null

required

Size of the stored original.

data.asset.filename

string | null

required

The original filename it was uploaded under.

data.asset.kind

enum<string>

required

What Paige did with it. knowledge means it was text-extracted into the bot's knowledge base (PDF, DOCX, text, markdown).

Available options:

image,

video,

audio,

knowledge

data.asset.caption

string | null

required

The caption supplied at upload, if any.

data.asset.source

enum<string>

required

chat_upload is your own upload. conversation_inbound is a file a customer sent in over WhatsApp — only ever returned to a key that also holds conversations:read.

Available options:

chat_upload,

conversation_inbound

data.asset.created_at

string | null

required

When the asset was created (ISO 8601).

Getting started

Endpoints

Upload a media asset

Authorizations

Headers

Body

Response