List the project's media assets

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

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

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

{
  "success": true,
  "data": {
    "storage": {
      "used_bytes": 123,
      "asset_count": 123,
      "limit_bytes": 123,
      "remaining_bytes": 123,
      "by_source": {
        "chat_upload": {
          "bytes": 123,
          "count": 123
        },
        "conversation_inbound": {
          "bytes": 123,
          "count": 123
        }
      },
      "enforced_for": "<string>"
    },
    "assets": [
      {
        "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>",
        "preview_url": "<string>",
        "used_in": [
          {
            "kind": "flow",
            "path": "<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>"
}

List the project's media assets

Newest first. Each image also carries a short-lived preview_url; other kinds have null there, so fetch their bytes through GET /v1/media/{slug}.

Only your own uploads by default. Media that CUSTOMERS sent in over WhatsApp is a separate class of data (source: "conversation_inbound") and is excluded. Pass include_inbound=true to include it — that additionally requires the conversations:read scope, and a key without it gets 403 rather than a quietly-filtered list.

include_usage=true adds used_in, the flows and code files referencing each slug. It costs one read per project file, so it is off by default.

Every response also carries storage: how many bytes this project is storing, the ceiling, and the headroom left. An upload past the ceiling is refused with 413 storage_limit_exceeded, so read this before a bulk sync. Media customers sent in over WhatsApp counts toward the total even when it is filtered out of assets.

Required scope: media:read

GET

media

List the project's media assets

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

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

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

{
  "success": true,
  "data": {
    "storage": {
      "used_bytes": 123,
      "asset_count": 123,
      "limit_bytes": 123,
      "remaining_bytes": 123,
      "by_source": {
        "chat_upload": {
          "bytes": 123,
          "count": 123
        },
        "conversation_inbound": {
          "bytes": 123,
          "count": 123
        }
      },
      "enforced_for": "<string>"
    },
    "assets": [
      {
        "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>",
        "preview_url": "<string>",
        "used_in": [
          {
            "kind": "flow",
            "path": "<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).

Query Parameters

include_usage

enum<string>

Also return used_in for each asset — the flows and code files referencing its slug. Costs one read per project file, so it is off by default.

Available options:

true,

false,

1,

0,

include_inbound

enum<string>

Also return media customers sent in over WhatsApp. Requires the conversations:read scope as well.

Available options:

true,

false,

1,

0,

Response

Success.

success

enum<boolean>

required

Available options:

true

data

object

required

Hide child attributes

data.storage

object

required

Hide child attributes

data.storage.used_bytes

number

required

Total bytes of media stored for this project, across every source.

data.storage.asset_count

number

required

How many media assets that is.

data.storage.limit_bytes

number | null

required

The per-project storage ceiling in bytes, or null when no ceiling is configured.

data.storage.remaining_bytes

number | null

required

Headroom left before an upload is refused, or null when there is no ceiling.

data.storage.by_source

object

required

The total split by where the media came from. Both halves count toward used_bytes.

Hide child attributes

data.storage.by_source.chat_upload

object

required

The project's own uploads.

Hide child attributes

data.storage.by_source.chat_upload.bytes

number

required

data.storage.by_source.chat_upload.count

number

required

data.storage.by_source.conversation_inbound

object

required

Media customers sent in over WhatsApp. Counts toward the total.

Hide child attributes

data.storage.by_source.conversation_inbound.bytes

number

required

data.storage.by_source.conversation_inbound.count

number

required

data.storage.enforced_for

string

required

Who the ceiling is enforced against. Always "api_key" — dashboard uploads are never refused for storage.

data.assets

object[]

required

Hide child attributes

data.assets.slug

string

required

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

data.assets.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.assets.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.assets.meta_uploaded_at

string | null

required

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

data.assets.mime

string | null

required

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

data.assets.bytes

number | null

required

Size of the stored original.

data.assets.filename

string | null

required

The original filename it was uploaded under.

data.assets.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.assets.caption

string | null

required

The caption supplied at upload, if any.

data.assets.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.assets.created_at

string | null

required

When the asset was created (ISO 8601).

data.assets.preview_url

string | null

required

Short-lived signed URL, images only. Null for every other kind.

data.assets.used_in

object[]

Present only when include_usage=true.

Hide child attributes

data.assets.used_in.kind

enum<string>

required

Whether a flow embeds the asset or code resolves its slug.

Available options:

flow,

code

data.assets.used_in.path

string

required

The project file, e.g. flows/booking.json.

Getting started

Endpoints

List the project's media assets

Authorizations

Headers

Query Parameters

Response