Retrieve one media asset and a signed URL

curl --request GET \
  --url https://api.paigeme.dev/v1/media/{slug} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

{
  "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>"
    },
    "url": "<string>",
    "expires_in": 123
  }
}

{
  "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>"
}

Retrieve one media asset and a signed URL

The asset plus a short-lived signed url for its bytes. The URL is unauthenticated once minted, so treat it as a secret and let it expire — expires_in is capped, deliberately, so a scoped read cannot be turned into a permanent public link.

download=true signs it with a download disposition (the browser saves the file) instead of an inline one.

An unknown slug is 404 ASSET_NOT_FOUND. So is a slug that exists but belongs to inbound customer media when the key lacks conversations:read — identical response either way, so probing slugs reveals nothing about what a customer sent in.

Required scope: media:read

GET

media

{slug}

Retrieve one media asset and a signed URL

curl --request GET \
  --url https://api.paigeme.dev/v1/media/{slug} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

{
  "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>"
    },
    "url": "<string>",
    "expires_in": 123
  }
}

{
  "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).

Path Parameters

slug

string

required

The asset's bot-facing slug — the key the runtime getMediaId / sendMedia helpers look it up by.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{0,119}$

Query Parameters

download

enum<string>

Sign the URL with a download disposition instead of an inline one.

Available options:

true,

false,

1,

0,

expires_in

integer

Signed-URL lifetime in seconds (30-3600, default 300).

Required range: 30 <= x <= 3600

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).

data.url

string | null

required

Signed URL for the bytes, or null when the asset has no stored object.

data.expires_in

number

required

Seconds the signed URL stays valid.

Getting started

Endpoints

Retrieve one media asset and a signed URL

Authorizations

Headers

Path Parameters

Query Parameters

Response