The Paige API

The Paige API is a plain REST API over HTTPS: send a WhatsApp message, read a conversation, update a contact’s tags, create a template, assemble a broadcast, read and edit your bot’s code and flows, deploy, or register a webhook. It covers the day-to-day operational surface rather than every screen in the dashboard. Project setup and account administration stay in the app — there are no endpoints for the database tab, secrets, logs, storage uploads, scheduled tasks, or billing, and broadcasts are assembled by API but approved and sent from the dashboard on purpose.

Prefer to let an AI agent do the work instead of writing HTTP calls yourself? Paige also runs an MCP server — see Connect an AI agent. Both routes sit behind the same keys and the same permissions.

Base URL

All endpoints live under /v1:

https://api.paigeme.dev

Your key carries the project

There is no project id in any path. An API key belongs to exactly one project, so POST /v1/messages sends from that project’s WhatsApp number and GET /v1/conversations reads that project’s conversations. Nothing to pass, nothing to get wrong. See Authentication for how to mint a key, and how this works for an AI agent connected to several projects at once.

Try it in 60 seconds

Create a key under Settings → API, then check it works:

curl https://api.paigeme.dev/v1/ping \
  -H "Authorization: Bearer pk_live_your_key_here"

const res = await fetch('https://api.paigeme.dev/v1/ping', {
  headers: { Authorization: `Bearer ${process.env.PAIGE_API_KEY}` },
});
console.log(await res.json());

import os, requests

res = requests.get(
    "https://api.paigeme.dev/v1/ping",
    headers={"Authorization": f"Bearer {os.environ['PAIGE_API_KEY']}"},
)
print(res.json())

You’ll get back the project the key resolved to and exactly what it’s allowed to do:

{
  "success": true,
  "data": {
    "ok": true,
    "projectId": "a3f62fcb-…",
    "scopes": ["messages:send", "conversations:read"]
  }
}

That’s the fastest way to confirm a key is live and correctly scoped before you write anything else.

The response envelope

Every response uses one of two shapes. On success:

{ "success": true, "data": {} }

On failure:

{
  "success": false,
  "error": { "code": "insufficient_scope", "message": "…" },
  "request_id": "8f1c…"
}

Branch your code on error.code, never on error.message. Codes are stable; wording isn’t.

Responses also carry an X-Request-Id header — the same value that appears as request_id in an error body. Log it. If you ever need help with a specific failed call, that id is what identifies it. See Errors for the full list of codes.

Paging through results

Paging isn’t identical everywhere, so check the endpoint you’re calling. Conversations and their messages use an opaque keyset cursor: pass limit (max 100, default 50), then feed the nextCursor from the response back as cursor to get the next page. Broadcast recipients instead use limit and offset, and return a total so you know how far there is to go.

What you’ll need next

Authentication

Mint a key, keep it safe, and target the right project.

Scopes

The 17 permissions a key can carry, and what each unlocks.

Errors

Status codes, error codes, and what to do about each.

Rate limits

The per-key throttle, and the separate daily send quota.

Idempotency

Retry a send safely without messaging a customer twice.

Webhooks

Get events pushed to you, and verify they’re really from Paige.

Building with an AI coding agent

If you’re having Claude, Codex, or Cursor write the integration for you, hand it the ready-made skill file rather than pasting docs at it:

https://api.paigeme.dev/v1/skill.md

It points the agent at the live OpenAPI document — https://api.paigeme.dev/v1/openapi.json, public and unauthenticated — as its source of truth, and gives it working recipes for the common tasks. You’ll find the same file in the app under Settings → API → Integration skill, with copy and download buttons.

Getting started

Endpoints

The Paige API

Base URL

Your key carries the project

Try it in 60 seconds

The response envelope

Paging through results

What you’ll need next

Authentication

Scopes

Errors

Rate limits

Idempotency

Webhooks

Building with an AI coding agent

​Base URL

​Your key carries the project

​Try it in 60 seconds

​The response envelope

​Paging through results

​What you’ll need next

Authentication

Scopes

Errors

Rate limits

Idempotency

Webhooks

​Building with an AI coding agent

Base URL

Your key carries the project

Try it in 60 seconds

The response envelope

Paging through results

What you’ll need next

Building with an AI coding agent