Upload the sample file a media header needs

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

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

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

import requests

url = "https://api.paigeme.dev/v1/templates/header-sample"

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

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

print(response.text)

{
  "success": true,
  "data": {
    "handle": "<string>",
    "format": "<string>",
    "filename": "<string>",
    "mime_type": "<string>",
    "size": 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>"
}

{
  "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 the sample file a media header needs

Meta will not review an IMAGE, VIDEO or DOCUMENT header without an EXAMPLE of the media it will carry, so a media-header template cannot be created until you have one of these handles. Upload the sample here, then put the returned handle into the header component as example.header_handle: ["<handle>"] when you call POST /v1/templates. Creating a media header without it is 400, not a Meta error.

Two transports, pick one.

JSON { "format": "DOCUMENT", "source_url": "https://..." } — Paige downloads it. Only public http(s) URLs: private, loopback and link-local addresses are refused and redirects are re-checked at every hop. Add filename / mime to override what the remote server declares.
JSON { "format": "IMAGE", "data": "<base64>", "filename": "...", "mime": "..." } — inline bytes, capped at 5 MB decoded, lower than the per-format ceilings because the body is buffered whole in memory. A data: URI prefix is accepted and stripped.

Size and type are per FORMAT. IMAGE takes image/jpeg or image/png up to 5 MB; VIDEO takes video/mp4 or video/3gpp up to 16 MB; DOCUMENT takes PDF, Word, Excel, PowerPoint or plain text up to 100 MB. Oversize is 413 file_too_large and a type WhatsApp will not take is 415.

The declared mime type is not trusted. The bytes are checked against their own signature, and a file whose contents disagree with its mime is 415 — sending a video as image/png to slip past the image size cap does not work.

A handle is not a media id. media_id from POST /v1/media addresses a file Meta can SEND and is useless as a header_handle; the reverse is also true. The handle is short-lived and single-purpose: get one, create the template with it, and do not store it.

Uploads are metered by BYTES as well as by request count, against the same per-key budget POST /v1/media charges. A burst of large samples can therefore return 429 rate_limited even while you are inside the request-per-minute budget — retry after the window. A source_url download is also aborted mid-stream once it passes that budget, so a sample bigger than a whole minute of it can never be fetched.

Required scope: templates:manage

POST

templates

header-sample

Upload the sample file a media header needs

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

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

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

import requests

url = "https://api.paigeme.dev/v1/templates/header-sample"

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

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

print(response.text)

{
  "success": true,
  "data": {
    "handle": "<string>",
    "format": "<string>",
    "filename": "<string>",
    "mime_type": "<string>",
    "size": 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>"
}

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

application/json

Option 1
Option 2

format

enum<string>

required

The header format this sample is for. IMAGE takes JPEG/PNG up to 5 MB, VIDEO takes MP4/3GP up to 16 MB, DOCUMENT takes PDF/Office/plain text up to 100 MB. The declared type is checked against the file own magic bytes, so a mislabelled file is refused here rather than forwarded to Meta.

Available options:

IMAGE,

VIDEO,

DOCUMENT

source_url

string<uri>

required

Public http(s) URL Paige downloads the sample from. Private, loopback and link-local addresses are refused and redirects are re-checked at every hop. The download is aborted mid-stream at the smaller of this format ceiling and the API key remaining per-minute upload byte budget, so a sample larger than that budget can never be fetched.

filename

string

Overrides the filename derived from the URL.

Required string length: 1 - 255

mime

string

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

Required string length: 1 - 255

Response

Success.

success

enum<boolean>

required

Available options:

true

data

object

required

Hide child attributes

data.handle

string

required

Meta's opaque upload handle. Goes straight into the HEADER component as example.header_handle: [handle].

data.format

string

required

IMAGE | VIDEO | DOCUMENT — the format the sample was validated against.

data.filename

string

required

data.mime_type

string

required

The mime type Paige verified against the bytes, not necessarily the one you declared.

data.size

number

required

Decoded size in bytes.

Getting started

Endpoints

Upload the sample file a media header needs

Authorizations

Headers

Body

Response