API and MCP reference
Make pages, send them, and see what came back (replies, bookings, payments) from your own scripts, Zapier, or an AI tool.
Keys
Create a key in the app under Settings → Keys and send it on every call as Authorization: Bearer pt_…. A key can do only what its scopes allow, and can be set to stop working on a date. Keys made before scopes existed can do everything.
| Scope | Lets the key |
|---|---|
read | See pages, customers, bookings, money and settings |
write | Make, change and delete pages, customers, bookings and webhooks |
settings | Change the brand, booking settings and embed keys |
payments | Change payment settings and refund payments |
export | Download the customer list |
A call the key isn't allowed to make gets 403 with "code": "insufficient_scope" and the scope it needs. An expired or deleted key gets 401.
Third-party apps (OAuth)
An app other people install (a Zapier, Make or n8n app, or your own) can ask each person to connect their workspace instead of pasting a key. It uses OAuth 2.1: the authorization code flow with PKCE (S256), and tokens bound to the API resource https://programmable.page/api (RFC 8707). The token then works on every call below, exactly like a key with the scopes the person allowed.
1. Register the app
Once, with dynamic client registration (RFC 7591). Leave out token_endpoint_auth_method to get a client_secret (a server-side app); use "none" for an app that can't keep a secret. Redirect URIs must be https, or http to localhost.
curl https://programmable.page/oauth/register -H "content-type: application/json" \
-d '{"client_name": "My Zap", "redirect_uris": ["https://zapier.com/dashboard/auth/oauth/return/App123CLIAPI/"]}'
# → {"client_id": "ppc_…", "client_secret": "pps_…", "token_endpoint_auth_method": "client_secret_basic", …}
2. Send the person to sign in
Make a random code_verifier (43 to 128 characters), and send its base64url SHA-256 as the challenge. resource must be the API; without it the token is for /mcp and the API refuses it.
https://programmable.page/oauth/authorize?response_type=code&client_id=ppc_…
&redirect_uri=https%3A%2F%2Fzapier.com%2F…&state=RANDOM
&code_challenge=BASE64URL_SHA256_OF_VERIFIER&code_challenge_method=S256
&scope=read%20write&resource=https%3A%2F%2Fprogrammable.page%2Fapi
They sign in, pick a workspace and see what the app asks for in plain words; they can untick any of it. Allowing sends them back to your redirect_uri with code, your state and iss. A member (not an admin) can give Read and Write only.
3. Swap the code for tokens
curl https://programmable.page/oauth/token -u "ppc_…:pps_…" \
-d grant_type=authorization_code -d code=CODE -d code_verifier=VERIFIER \
-d redirect_uri=https://zapier.com/… -d resource=https://programmable.page/api
# → {"access_token": "pt_oa…", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "ptr_…", "scope": "read write"}
Call the API with Authorization: Bearer pt_oa…. Access tokens last an hour. Get a new pair with grant_type=refresh_token; every refresh token works once, and using an old one again disconnects the app. Revoke with POST /oauth/revoke.
Scopes
The OAuth scopes are the key scopes above, with the same names: read, write, settings, payments, export. Each call needs the scope in the table below, checked exactly as for a key; without it the answer is 403 insufficient_scope. Each connected app has its own limit of 300 requests a minute.
The token acts for the person who connected it, in that workspace. It stops working when they leave the workspace, lose their account, sign out everywhere, or disconnect the app under Settings → Keys → Connected apps; a workspace admin can disconnect anyone's.
Discovery: authorization server metadata at /.well-known/oauth-authorization-server (RFC 8414), and the API's protected resource metadata at /.well-known/oauth-protected-resource/api (RFC 9728). A 401 from the API points to it in WWW-Authenticate.
Test mode
Make a test key (Settings → Keys → Test key) to build and try an integration without reaching real customers. Test keys start pt_test_, have scopes and limits like any key, and work on the same workspace as live keys. Every response to a test key's call carries Programmable-Page-Livemode: false. What a test key's call does, and everything later that's about a page it made:
| Side effect | In test mode |
|---|---|
| Emails and texts (sending a page, receipts, reminders, notifications) | Not sent. Each is kept in the workspace's Test sends log instead: GET /api/v1/test/sends (newest first; limit up to 200, boardId for one page), and Settings → Keys in the app. Kept 30 days; DELETE /api/v1/test/sends clears it. |
| Outbound webhooks and page callbacks | Delivered as usual, signed the same way, with "livemode": false in the envelope (it's true for everything else). |
| Payments | Use the workspace's Stripe test key (add one as testSecretKey with PUT /api/v1/payments and a live key, or connect a sk_test_ key as the main one). Without one, taking a payment on a test page is refused with 409 test_payments_not_configured. |
| Pages | Marked "test": true and badged in the app; left out of money reports and what's owed, the daily publish and monthly text allowances, view counts and activity counts; moved to the Trash 7 days after they're made. Customers a test key adds are marked "test": true too. |
| Time entries | A test key can track time (by hand or with a timer) for test customers and test pages; the entries are marked "test": true. They never go on a live customer's invoice (409 test_time), and billing them makes a test invoice, left out of money reports like any test page. Time for a live customer, or a live entry, can't be added, changed or billed with a test key (403 live_object). |
| Live pages, customers, bookings and replies | Readable, but not changeable: creating, editing, sending, trashing, restoring, refunding, recording or voiding a payment on, or booking a live one answers 403 live_object ("Test keys can only change test pages"). Making a page from a live one (duplicate, an instance of a template, an invoice from a quote) is fine: the new page is a test page. |
| Workspace settings | Need a live key: webhooks, storage, apps and connections, jobs, payment setup, appearance, embed keys, booking settings, texting setup, notifications, recurring and scheduled sends, and customer imports answer 403 live_key_required. Set your webhooks up with a live key; they then also receive test events, marked "livemode": false. |
AI generations still count toward the daily generation limit: they're real model calls. Live keys (pt_…) are unaffected by any of this.
Limits
Each key may make 300 requests a minute unless it was given its own limit, and each address 120 a minute per part of the API. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (when the window resets, in seconds since 1970). Over the limit, the answer is 429 with Retry-After (seconds): wait that long and try again.
Errors and request ids
Every error is JSON with a plain-words message and a stable code to branch on: {"error": "what went wrong, in plain words", "code": "bad_request"}. Codes include bad_request, unauthorized, insufficient_scope, not_found, unknown_field (with fields), idempotency_conflict, in_progress, rate_limited and internal.
Every response carries X-Request-Id. Send your own (up to 64 letters, digits, . _ : or -) and it's echoed back; otherwise one is made. Quote it when asking for help.
Retrying safely
Every POST takes an Idempotency-Key header: 8–64 letters, digits, - or _, one per thing you mean to do. Within 24 hours, the same key on the same route returns the first call's answer (with Idempotent-Replayed: true) instead of making a second page, sending a second text or recording a second payment. The same key with a different body is 409 idempotency_conflict; a repeat that arrives while the first is still running waits a few seconds, then gets 409 in_progress. Only successful answers are kept, so a key that got an error can be used again for the corrected call. Making a page from a template and refunds also take the key as requestId in the body; that still works but is deprecated (see Deprecations): send the header.
Lists
Page through GET /boards and GET /customers with limit (up to 500): the answer has nextCursor; pass it back as cursor, with the same filters, for the next page (100 at a time if you send only the cursor). It's null on the last one. Cursors are opaque. A cursor marks the last row you got (by the list's sort), not a count, so pages added or removed while you page through don't make you miss or repeat any; a cursor carries its sort, so send the same filters with it. offset, and cursors handed out before November 2026, still work but are deprecated (see Deprecations).
Sending neither limit nor cursor returns the whole list, unpaged, exactly as before pagination, so existing scripts keep working. New clients should page: a large workspace's whole list is slow.
Versions
This is version 1, at https://programmable.page/api/v1. The unversioned https://programmable.page/api/… paths are aliases of v1 and keep working.
Within v1, changes are additive only: new endpoints, new optional fields, new fields in answers, new error codes and new event names. Write clients that ignore fields they don't know. A breaking change (removing or renaming a field or endpoint, changing what one means, or a new required field) comes as /api/v2, announced at least 6 months before v1 changes or stops; a v1 call that will go away answers with Deprecation and Sunset headers in that time.
Deprecations
A call that uses something deprecated still works as before, and its answer says so in headers you can log or alert on:
Deprecation: @1794009600(RFC 9745): since when, in seconds since 1970;Sunset: Tue, 01 Jun 2027 00:00:00 GMT(RFC 8594): when it stops working, once a date is set;Link: <https://programmable.page/docs/api#deprecations>; rel="deprecation": this section.
| Deprecated | Since | Sunset | Use instead |
|---|---|---|---|
offset on GET /boards and GET /customers | 2026-11-07 | 2027-06-01 | cursor (the previous page's nextCursor) |
| Cursors handed out before 2026-11-07 (count-based) | 2026-11-07 | 2027-06-01 | The answer's nextCursor: it's a new-style cursor, so following it moves you over |
requestId in the body of POST /boards/{id}/instances and POST /api/v1/payments/boards/{id}/refunds | 2026-11-07 | Not set | The Idempotency-Key header (no Deprecation header when you send it) |
Changelog
| Date | Change |
|---|---|
| 2026-11-07 | List cursors mark the last row instead of a count, so lists that change while you page don't skip or repeat. offset, count-based cursors and requestId in bodies are deprecated, with Deprecation/Sunset/Link headers (Deprecations). Test keys can track and bill time for test customers. |
| 2026-11 | /api/v1 served (unversioned paths stay as aliases). Idempotency-Key on every POST. X-Request-Id on every response and X-RateLimit-Reset with the other limit headers. Every error has a code. /boards and /customers page with limit/cursor/nextCursor (without either, the whole list as before). PATCH /boards/{id} takes ref, callbackUrl and data, and refuses fields it doesn't know (unknown_field). The spec lists every call. |
Calls
The full description is https://programmable.page/api/openapi.json (OpenAPI 3.1), for code generators and tools like Postman.
curl https://programmable.page/api/v1/publish/boards/TEMPLATE_ID/instances \
-H "Authorization: Bearer pt_…" -H "content-type: application/json" \
-H "Idempotency-Key: order-1042" \
-d '{"data": {"customer": {"name": "Sarah"}, "total": 95}}'
| Call | What it does | Scope |
|---|---|---|
GET /api/v1/publish/me | The workspace this key acts as, and today's usage | read |
POST /api/v1/publish | Publish a finished page (or update one with boardId) | write |
POST /api/v1/publish/generate | Have the server write a page from a prompt | write |
GET /api/v1/publish/boards | List the workspace's pages | read |
GET /api/v1/publish/boards/{id} | One page, with its links | read |
PATCH /api/v1/publish/boards/{id} | Change a page's settings (and data) | write |
DELETE /api/v1/publish/boards/{id} | Delete a page (to the Trash) | write |
POST /api/v1/publish/boards/{id}/restore | Restore a page from the Trash | write |
GET /api/v1/publish/boards/trash | Pages in the Trash | read |
DELETE /api/v1/publish/boards/trash/{id} | Delete a page in the Trash for good, now (admins) | write |
GET /api/v1/publish/boards/{id}/instances | Pages made from this template | read |
POST /api/v1/publish/boards/{id}/instances | Make a page from a template with this data | write |
PUT /api/v1/publish/boards/{id}/data | Replace a page's data (live viewers see it at once) | write |
GET /api/v1/publish/boards/{id}/refs | Which records in other systems this page became | read |
PUT /api/v1/publish/boards/{id}/refs | Attach a record in another system to this page | write |
DELETE /api/v1/publish/boards/{id}/refs | Remove a record attached to this page through the API | write |
GET /api/v1/publish/bookings/{bid}/refs | Which records in other systems this booking became | read |
PUT /api/v1/publish/bookings/{bid}/refs | Attach a record in another system to this booking | write |
DELETE /api/v1/publish/bookings/{bid}/refs | Remove a record attached to this booking through the API | write |
GET /api/v1/publish/boards/{id}/answer | A request page's answer so far | read |
POST /api/v1/publish/boards/{id}/revise | Ask the server to change a page in plain words | write |
GET /api/v1/publish/images/allowance | AI-made images: whether they're on here, and how many this workspace may still make today | read |
POST /api/v1/publish/boards/{id}/build-again | Build a page again after its first build failed (uses one generation) | write |
GET /api/v1/publish/boards/{id}/versions | A page's earlier versions | read |
GET /api/v1/publish/boards/{id}/changes | The changes asked for in words (oldest first, the last 50) and how each went: working, done (with the version it made) or failed | read |
GET /api/v1/publish/customers | List customers | read |
POST /api/v1/publish/customers | Add a customer | write |
GET /api/v1/publish/customers/summary | What customers owe and when you were last in touch | read |
GET /api/v1/publish/customers/{cid} | One customer | read |
PATCH /api/v1/publish/customers/{cid} | Change a customer | write |
DELETE /api/v1/publish/customers/{cid} | Delete a customer (to the Trash) | write |
POST /api/v1/publish/customers/{cid}/restore | Restore a customer from the Trash | write |
GET /api/v1/publish/customers/trash | Customers in the Trash | read |
DELETE /api/v1/publish/customers/trash/{cid} | Delete a customer in the Trash for good, now (admins) | write |
POST /api/v1/publish/customers/bulk | Act on up to 200 customers at once (admins) | write |
GET /api/v1/publish/customers/export.csv | Download the customer list as CSV | export |
POST /api/v1/publish/customers/clear-cant-text | Clear the can't-text mark carriers put on customers' phones (admins) | write |
GET /api/v1/publish/replies | What visitors sent back through pages, newest first | read |
GET /api/v1/publish/requests | Replies, answers and acceptances, and the request pages still waiting | read |
GET /api/v1/publish/page-status | Per page: last sent, first opened, paid and replies | read |
GET /api/v1/publish/money | What's owed, overdue and paid | read |
GET /api/v1/publish/money/paid | Payments received, newest first, 50 at a time | read |
GET /api/v1/publish/money/paid.csv | Payments received as CSV, with each payment's subtotal, tax, tax rates and total | export |
GET /api/v1/publish/money/refunds.csv | Refunds and lost chargebacks as CSV, one dated row each | export |
GET /api/v1/publish/money/disputes | Chargebacks to answer, and the ones closed lately | read |
GET /api/v1/publish/money/reports/tax | Tax collected by rate and currency | read |
GET /api/v1/publish/money/reports/tax.csv | The tax summary as CSV (admins only) | export |
GET /api/v1/publish/money/reports/revenue | Revenue by month and currency | read |
GET /api/v1/publish/money/reports/revenue.csv | Revenue by month as CSV (admins only) | export |
GET /api/v1/publish/money/reports/aging | What's owed by how long past due | read |
GET /api/v1/publish/money/reports/aging.csv | What's owed, one row per unpaid page, as CSV (admins only) | export |
GET /api/v1/publish/money/reports/customers | Top customers by what they paid in a range | read |
GET /api/v1/publish/money/reports/customers.csv | Top customers as CSV (admins only) | export |
GET /api/v1/payments/boards/{id} | One page's payments and refunds (was this invoice paid?) | read |
GET /api/v1/payments/boards/{id}/refunds | Refunds on a page | read |
POST /api/v1/payments/boards/{id}/refunds | Refund a payment on a page, in full or in part | payments |
GET /api/v1/publish/bookings/export.csv | Bookings as CSV, for the same range and filters as the list | export |
GET /api/v1/publish/bookings | Bookings taken through booking pages, soonest first | read |
POST /api/v1/publish/bookings | Add a booking by hand (a phone call, a walk-in) | write |
DELETE /api/v1/publish/bookings/{bid} | Delete a booking for good, with who booked it (admins) | write |
POST /api/v1/publish/bookings/{bid}/cancel | Cancel a booking (the customer is told) | write |
POST /api/v1/publish/bookings/{bid}/move | Move a booking to another time (the customer is told) | write |
PUT /api/v1/publish/bookings/{bid}/assignee | Assign a booking to a workspace member, or to nobody | write |
GET /api/v1/publish/boards/{id}/booking-assignee | The member a booking page is given to | read |
PUT /api/v1/publish/boards/{id}/booking-assignee | Give a booking page to a member (its bookings are assigned to them; their working hours limit its times) | write |
GET /api/v1/publish/sites | Sites: pages grouped under one navigation bar | read |
GET /api/v1/publish/boards/{id}/site | The site a page belongs to (null when it isn't in one) | read |
PUT /api/v1/publish/boards/{id}/site | Reorder and rename a site's pages | write |
DELETE /api/v1/publish/boards/{id}/site | Take a page out of its site (the page itself stays live) | write |
GET /api/v1/publish/member-hours | Members' working hours for bookings (only those set) | read |
PUT /api/v1/publish/member-hours/{uid} | Set a member's working hours (null clears them) | write |
GET /api/v1/publish/booking-settings | Booking settings: change cutoff, reminders, time zone and booking rules | read |
PUT /api/v1/publish/booking-settings | Change booking settings (any field; rules fields merge) | settings |
GET /api/v1/webhooks | Outbound webhooks and the event names | read |
POST /api/v1/webhooks | Add an outbound webhook (the signing secret is returned only here) | write |
GET /api/v1/webhooks/{id} | One webhook | read |
PATCH /api/v1/webhooks/{id} | Change a webhook, or switch it on or off | write |
DELETE /api/v1/webhooks/{id} | Delete a webhook | write |
POST /api/v1/webhooks/{id}/test | Send a ping now (or one event's example) and report the response | write |
GET /api/v1/webhooks/{id}/deliveries | Recent deliveries, newest first | read |
POST /api/v1/triggers/send | Text or email a page to someone (now, or on sendAt) | write |
GET /api/v1/publish/appearance | The workspace's look: brand, default style and libraries, locale, currency, time zone and page options | read |
PUT /api/v1/publish/appearance | Change the workspace's look (admins) | settings |
GET /api/v1/publish/tags | The workspace's tags, most used first | read |
POST /api/v1/publish/boards/bulk | Act on up to 200 pages at once | write |
POST /api/v1/publish/boards/{id}/archive | Archive a page: it closes (no more replies, payments or bookings) but keeps its history | write |
POST /api/v1/publish/boards/{id}/unarchive | Reopen an archived page (its content is checked again) | write |
POST /api/v1/publish/boards/{id}/duplicate | Copy a page (settings, tags and data) as a new page | write |
POST /api/v1/publish/boards/{id}/invoice | Turn a quote into an invoice | write |
POST /api/v1/publish/boards/{id}/refresh | Fetch a page's sourceUrl again now | write |
GET /api/v1/publish/boards/{id}/versions/{version} | One earlier version, with its content | read |
POST /api/v1/publish/boards/{id}/versions/{version}/restore | Make an earlier version current again (the one it replaces stays in the history) | write |
GET /api/v1/publish/boards/{id}/acceptance | Who accepted this quote, and when (404 until someone has) | read |
DELETE /api/v1/publish/boards/{id}/acceptance | Clear the acceptance so the customer can accept again | write |
GET /api/v1/publish/boards/{id}/reports | Visitor reports about this page (what and when, never who) | read |
GET /api/v1/publish/boards/{id}/views | Views per day, oldest first, zero-filled | read |
GET /api/v1/publish/boards/{id}/checkin | A ticket page's ticket, for the door | read |
POST /api/v1/publish/boards/{id}/checkin | Check a ticket in (the first scan wins; already says if it was used) | write |
DELETE /api/v1/publish/boards/{id}/checkin | Undo a check-in | write |
GET /api/v1/publish/boards/{id}/waitlist | A waitlist's line, in position order, with referral counts | read |
GET /api/v1/publish/boards/{id}/waitlist/export.csv | A waitlist's line as CSV, with positions and referrals (admins only) | export |
DELETE /api/v1/publish/boards/{id}/waitlist/{eid} | Take someone off a waitlist (everyone behind moves up) | write |
GET /api/v1/publish/boards/{id}/posts | A page's visitor posts, newest first, held and hidden ones included, and whether visitors can post now | read |
POST /api/v1/publish/boards/{id}/posts | Post on the page as the business (shown to everyone on it, live) | write |
PATCH /api/v1/publish/boards/{id}/posts/{pid} | Approve (status shown) or hide (status hidden) a visitor post | write |
DELETE /api/v1/publish/boards/{id}/posts/{pid} | Delete a post for good | write |
GET /api/v1/publish/boards/{id}/ballots | A poll's voting codes (the same list every time) and how many were used | read |
POST /api/v1/publish/customers/import | Add or update up to 2,000 customers from a spreadsheet's rows | write |
POST /api/v1/publish/customers/{cid}/statement | Make a statement page from a customer's open invoices | write |
GET /api/v1/publish/customers/{cid}/duplicates | Customers who are likely the same person (same name, and the same email or phone) | read |
POST /api/v1/publish/customers/{cid}/merge | Merge this customer into another (admins) | write |
GET /api/v1/publish/customers/{cid}/history | Everything on record for one customer: pages sent and opened, payments, refunds, replies, bookings | read |
POST /api/v1/publish/customers/remember | Save someone who booked or replied as a customer (matched by phone or email first) | write |
GET /api/v1/publish/replies/export.csv | Replies as CSV (the workspace's, or one page's with boardId; admins only) | export |
POST /api/v1/publish/replies/{rid}/customer | Save who sent this reply as a customer | write |
DELETE /api/v1/publish/replies/{rid} | Delete a reply | write |
PUT /api/v1/publish/replies/{rid}/handled | Mark a reply done, or not done again (who and when are kept) | write |
GET /api/v1/publish/requests/unread | How many replies not marked done, answers, acceptances and customers' bookings came in since a time (cheap enough to poll) | read |
GET /api/v1/publish/bookings/new | Bookings customers made since a time that still stand, newest first (up to 20) | read |
GET /api/v1/publish/embed-keys | Embed keys (pk_…) that let a host page start a page's first generation | read |
POST /api/v1/publish/embed-keys | Make an embed key for a page (admins) | settings |
PATCH /api/v1/publish/embed-keys/{id} | Change or revoke an embed key (admins) | settings |
DELETE /api/v1/publish/embed-keys/{id} | Delete an embed key (admins) | settings |
GET /api/v1/publish/bookings/{bid}/times | A booking page's times on one day for moving this booking, each marked free or not | read |
GET /api/v1/publish/time-off | Days off (nothing can be booked), soonest first | read |
POST /api/v1/publish/time-off | Mark days off | write |
DELETE /api/v1/publish/time-off/{tid} | Remove days off | write |
GET /api/v1/publish/booking-feed | The private calendar link (ICS) for the workspace's bookings, or null | export |
POST /api/v1/publish/booking-feed | Make or replace the calendar link (the old one stops working; admins) | export |
DELETE /api/v1/publish/booking-feed | Turn the calendar link off (admins) | export |
GET /api/v1/payments | The workspace's payment account and its 25 latest payments | read |
PUT /api/v1/payments | Connect or change the Stripe account (admins) | payments |
DELETE /api/v1/payments | Disconnect the Stripe account (admins) | payments |
POST /api/v1/payments/boards/{id}/payments | Record a payment made another way (cash, bank transfer, cheque) | payments |
DELETE /api/v1/payments/boards/{id}/payments/{pid} | Remove a payment recorded by hand (card payments are refunded instead) | payments |
POST /api/v1/payments/boards/{id}/void | Cancel the bill on a page: nothing is owed, Pay turns off, reminders stop | payments |
DELETE /api/v1/payments/boards/{id}/void | Restore a cancelled bill | payments |
GET /api/v1/payments/settings | Late fees and tips: the workspace's settings (both off until switched on) | read |
PUT /api/v1/payments/settings | Change late fees or tips (owners and admins) | payments |
POST /api/v1/payments/boards/{id}/late-fee/waive | Waive the late fee on an invoice: its line comes off and none is added again (works before one is added) | payments |
PUT /api/v1/payments/boards/{id}/tips | Tips on one page: on, off, or follow the workspace setting | payments |
PUT /api/v1/payments/boards/{id}/how-to-pay | This page's own payment instructions, shown instead of the workspace's | payments |
POST /api/v1/payments/connect/start | Connect with Stripe: the Stripe address to send the owner to (Stripe Connect, Standard accounts) | payments |
GET /api/v1/payments/disputes | Chargebacks across the workspace, newest first | read |
GET /api/v1/payments/subscriptions | Subscriptions customers started on the workspace's pages | read |
POST /api/v1/payments/subscriptions/{id}/cancel | Cancel a subscription | payments |
GET /api/v1/test/sends | Emails and texts test mode kept instead of sending (pt_test_ keys and the pages they made), newest first | read |
DELETE /api/v1/test/sends | Clear the Test sends log | write |
POST /api/v1/webhooks/callback-secret | The secret that signs every page's callbackUrl deliveries (made on first use) | write |
POST /api/v1/webhooks/callback-secret/rotate | Replace the callbackUrl signing secret | write |
POST /api/v1/webhooks/{id}/rotate | Replace a webhook's signing secret (returned only here) | write |
POST /api/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver | Send a delivery again | write |
GET /api/v1/triggers/sends/{boardId} | Who a page was sent to, when, whether they opened it, and how each text was delivered | read |
PUT /api/v1/triggers/sends/{boardId}/reminders | Turn payment reminders, heads-ups and follow-ups on or off for one page | write |
GET /api/v1/triggers/texts | The text allowance: segments sent in the last 30 days, and the plan's monthly limit | read |
GET /api/v1/triggers/replies/{rid}/text | A reply's thread: what was texted or emailed back (channel), why a text can't go now (blocked) if it can't, and whether it can be answered by email (canEmail) | read |
POST /api/v1/triggers/replies/{rid}/text | Text back to a reply that came by text, from the workspace's number | write |
POST /api/v1/triggers/bookings/{bid}/on-my-way | Tell a booking's customer you're on the way | write |
POST /api/v1/triggers/replies/{rid}/email | Answer a reply (a form or booking lead) by email | write |
GET /api/v1/triggers/leads | New leads (someone new texted, emailed or called the business) with their draft pages, and the lead settings | read |
PUT /api/v1/triggers/leads/settings | Change the lead settings (admins) | write |
POST /api/v1/triggers/leads/{id}/send | Send a lead its draft page | write |
POST /api/v1/triggers/leads/{id}/change | Change a lead's draft page, as a texted change would | write |
POST /api/v1/triggers/leads/{id}/dismiss | Dismiss a lead (its draft is never sent) | write |
GET /api/v1/triggers/texts/health | How the workspace's texts fared over the last 7 days | read |
GET /api/v1/triggers/notifications | Where the owner is told about replies, payments and bookings, and payment-reminder settings | read |
PUT /api/v1/triggers/notifications | Change notification and reminder settings | write |
GET /api/v1/triggers/recurring | Recurring pages (a page from a template every period) | read |
POST /api/v1/triggers/recurring | Make a page from a template every period (and send it) | write |
PATCH /api/v1/triggers/recurring/{id} | Change, pause or resume a recurring page | write |
DELETE /api/v1/triggers/recurring/{id} | Stop a recurring page | write |
GET /api/v1/triggers/scheduled | Sends waiting for their sendAt | read |
DELETE /api/v1/triggers/scheduled/{id} | Cancel a scheduled send | write |
POST /api/v1/triggers/groups/preview | Who a group send would reach, and how (admins) | write |
GET /api/v1/triggers/groups | Group sends, newest first (boardId: one page's) | read |
POST /api/v1/triggers/groups | Send a page to a group of customers (admins): a draft for the owner to approve | write |
GET /api/v1/triggers/groups/{id} | A group send: each customer's status, whether they opened it, answered or paid | read |
GET /api/v1/triggers/groups/{id}/preview | What a draft would do now | read |
POST /api/v1/triggers/groups/{id}/approve | Approve a draft (the owner, in the app only) | write |
POST /api/v1/triggers/groups/{id}/cancel | Cancel a draft, or what hasn't gone yet (admins) | write |
GET /api/v1/triggers/chains | Next steps: the workspace's default for each moment (what happens after a customer accepts, signs, pays, books, or fills in a form), the choices and the pages to send | read |
PUT /api/v1/triggers/chains | Set the workspace's default next step for one moment (admins) | write |
GET /api/v1/triggers/chains/pages/{id} | A page's next steps: its setting for each moment, and steps waiting or done | read |
PUT /api/v1/triggers/chains/pages/{id} | Set one moment's next step for this page, or go back to the workspace's default | write |
DELETE /api/v1/triggers/chains/runs/{id} | Cancel a next step that hasn't happened yet | write |
GET /api/v1/triggers/customer-tags | Customer tags with how many customers have each | read |
POST /api/v1/triggers/customer-tags | Put one tag on several customers | write |
GET /api/v1/triggers/customer-tags/{cid} | A customer's tags | read |
PUT /api/v1/triggers/customer-tags/{cid} | Replace a customer's tags (up to 20) | write |
DELETE /api/v1/triggers/customers/{cid}/email-suppression | Try a customer's bounced email address again (admins) | write |
GET /api/v1/triggers/followups | Automatic follow-ups (e.g. a thank-you after a payment) | read |
PUT /api/v1/triggers/followups | Change automatic follow-ups | write |
GET /api/v1/triggers/portal | The customer portal: whether it's on, and its Find my documents link | read |
PUT /api/v1/triggers/portal | Turn the customer portal on or off (admins; off signs customers out) | settings |
POST /api/v1/triggers/portal/customers/{cid}/send | Send a customer a one-time sign-in link to their portal (email, else a text with their agreement) | write |
GET /api/v1/triggers/reviews | Ask for a review: the settings, and asks sent and opened in the last 30 days | read |
PUT /api/v1/triggers/reviews | Change Ask for a review | write |
GET /api/v1/triggers/reviews/requests | Review requests, newest first: queued, sent (and whether the link was opened) or skipped with why | read |
GET /api/v1/triggers/reviews/customers/{cid} | Whether a customer is never asked for a review, and the asks made to them | read |
PUT /api/v1/triggers/reviews/customers/{cid} | Never ask this customer for a review (off: true), or allow it again | write |
GET /api/v1/publish/time-entries | Time entries, newest day first | read |
POST /api/v1/publish/time-entries | Add time by hand | write |
GET /api/v1/publish/time-entries/running | Timers running now | read |
POST /api/v1/publish/time-entries/timer | Start a timer (the same person's running timer stops first) | write |
POST /api/v1/publish/time-entries/invoice | Put unbilled, billable time for one customer on a new invoice | write |
GET /api/v1/publish/time-entries/{tid} | One time entry | read |
PATCH /api/v1/publish/time-entries/{tid} | Change a time entry (not once it's on an invoice) | write |
DELETE /api/v1/publish/time-entries/{tid} | Delete a time entry (not once it's on an invoice) | write |
POST /api/v1/publish/time-entries/{tid}/stop | Stop a running timer | write |
GET /api/v1/triggers/config | What texting and email can do here (providers, addresses, limits) | read |
GET /api/v1/triggers/contacts | Phones and emails that can make pages by text or email | read |
POST /api/v1/triggers/contacts | Add a phone or email (it gets a code to confirm) | write |
POST /api/v1/triggers/contacts/{id}/verify | Confirm a contact with the code it was sent | write |
POST /api/v1/triggers/contacts/{id}/resend | Send a contact's confirmation code again | write |
PATCH /api/v1/triggers/contacts/{id} | Change a contact | write |
DELETE /api/v1/triggers/contacts/{id} | Remove a contact | write |
POST /api/v1/triggers/contacts/{id}/rotate-mailbox | Give a contact a new inbound email address | write |
GET /api/v1/triggers/keywords | Keywords that make a page from a template when texted or emailed | read |
POST /api/v1/triggers/keywords | Add a keyword for a template | write |
PATCH /api/v1/triggers/keywords/{id} | Change a keyword | write |
DELETE /api/v1/triggers/keywords/{id} | Remove a keyword | write |
GET /api/v1/triggers/endpoints | Inbound webhook endpoints (another app POSTs here to make a page) | read |
POST /api/v1/triggers/endpoints | Add an inbound endpoint (its secret is returned only here) | write |
POST /api/v1/triggers/endpoints/{id}/rotate | Replace an inbound endpoint's secret | write |
PATCH /api/v1/triggers/endpoints/{id} | Change an inbound endpoint | write |
DELETE /api/v1/triggers/endpoints/{id} | Remove an inbound endpoint | write |
GET /api/v1/triggers/log | The 50 latest inbound texts, emails and webhook calls, and what they did | read |
POST /api/v1/triggers/simulate | Run a text or email through the real pipeline without sending (returns the reply) | write |
GET /api/v1/triggers/number | The workspace's own texting number, if it has one | read |
POST /api/v1/triggers/number | Buy a texting number (paid plan) | write |
DELETE /api/v1/triggers/number | Release the texting number | write |
GET /api/v1/triggers/number/options | Numbers available to buy | read |
POST /api/v1/triggers/number/verification | Send the business details carriers need to verify the number | write |
POST /api/v1/triggers/number/refresh | Check the number's verification status again | write |
GET /api/v1/triggers/text-keys | Text keys: codes that let someone else's phone make pages | read |
POST /api/v1/triggers/text-keys | Make a text key (returned once; never replayed for an Idempotency-Key) | write |
DELETE /api/v1/triggers/text-keys/{id} | Revoke a text key | write |
GET /api/v1/triggers/link-keys | Link keys: links that let someone make pages without an account | read |
POST /api/v1/triggers/link-keys | Make a link key (returned once; never replayed for an Idempotency-Key) | write |
DELETE /api/v1/triggers/link-keys/{id} | Revoke a link key | write |
GET /api/v1/storage/status | Which storage backends are available | read |
GET /api/v1/storage/connections | Storage connections (S3, Google Drive) and the pages using each | read |
POST /api/v1/storage/connections/s3 | Connect an S3-compatible bucket | write |
POST /api/v1/storage/connections/mock | Connect test storage (development servers only) | write |
POST /api/v1/storage/connections/drive/session | Start connecting Google Drive (a hosted connect session) | write |
POST /api/v1/storage/connections/drive/finalize | Finish connecting Google Drive | write |
POST /api/v1/storage/connections/{id}/test | Check a storage connection works | write |
DELETE /api/v1/storage/connections/{id} | Remove a storage connection | write |
GET /api/v1/storage/uploads | Files on the workspace's pages, newest first | read |
GET /api/v1/storage/boards/{id}/files | The owner's files on a page | read |
POST /api/v1/storage/boards/{id}/files | Upload a file to a page (multipart form, field file) | write |
DELETE /api/v1/storage/boards/{id}/files/{fid} | Remove a file from a page | write |
GET /api/v1/storage/boards/{id}/uploads | Whether visitors can upload files on a page, and where they go | read |
PUT /api/v1/storage/boards/{id}/uploads | Let visitors upload files on a page, to a storage connection | write |
DELETE /api/v1/storage/boards/{id}/uploads | Stop visitor uploads on a page | write |
GET /api/v1/apps | Connected apps (accounting and others) and their sync status | read |
POST /api/v1/apps/{app}/session | Start connecting an app (a hosted connect session) | write |
POST /api/v1/apps/{app}/finalize | Finish connecting an app | write |
POST /api/v1/apps/{app}/sync-again | Retry an app's failed syncs now (Google Calendar: add upcoming bookings that aren't on it) | write |
POST /api/v1/apps/{app}/send-unpaid | Send unpaid invoices to QuickBooks or Xero | write |
GET /api/v1/apps/google-calendar/calendars | The connected Google account's calendars that bookings can go on | read |
GET /api/v1/apps/books/{boardId} | Where a page stands in the connected books (QuickBooks or Xero) | read |
POST /api/v1/apps/books/{boardId}/retry | Try a page's failed syncs to the books again now, or put it in if it never went | write |
PATCH /api/v1/apps/{app} | Change an app's settings | write |
DELETE /api/v1/apps/{app} | Disconnect an app | write |
GET /api/v1/jobs | Recent jobs, the recipes available and today's usage | read |
POST /api/v1/jobs | Start a job (a PDF of a page, pages from a spreadsheet…) | write |
GET /api/v1/jobs/recipes | The job recipes this workspace can run | read |
GET /api/v1/jobs/local | Commands that run in the desktop app on your own computer | read |
POST /api/v1/jobs/local | Add a local command | write |
PATCH /api/v1/jobs/local/{lid} | Change a local command | write |
DELETE /api/v1/jobs/local/{lid} | Remove a local command | write |
GET /api/v1/jobs/voice-notes | Whether voice notes can be transcribed here, and today's minutes | read |
POST /api/v1/jobs/voice-notes | Transcribe a voice memo (raw audio body, up to 25 MB) | write |
GET /api/v1/jobs/voice-notes/{id} | A voice memo's words, once transcribed | read |
GET /api/v1/jobs/documents | Whether PDF and Word documents can be read here, today's use and the limits | read |
POST /api/v1/jobs/documents | Read a document (raw PDF, DOCX, text, Markdown or CSV body, up to 25 MB): text files at once, PDF and Word as a job | write |
GET /api/v1/jobs/documents/{id} | A document's text, once read; send it as `documents` with /api/generate or a revise | read |
GET /api/v1/jobs/{id} | A job's status and files | read |
GET /api/v1/jobs/{id}/log | A job's log | read |
POST /api/v1/jobs/{id}/cancel | Cancel a job | write |
GET /api/v1/jobs/{id}/files/{fid} | Download a file a job made (kept for an hour) | read |
Pages you write: panel.emit
HTML you publish yourself runs in a sandbox with a global panel. await panel.emit(name, data) sends what the visitor entered to the workspace (kept as a reply, and relayed as the widget.event webhook). It resolves with { ok: true }, or { ok: false, error } when the reply was refused (a time already taken, a request already answered): show your confirmation only on ok.
When the reply took a booking (its data had a date as YYYY-MM-DD, and usually a time), the result also has booking:
const r = await panel.emit("booking", { name, email, date: "2026-11-24", time: "10:00" });
if (r.ok && r.booking) {
link.href = r.booking.manageUrl; // their own link to change or cancel
// "email" | "text" | null: how the confirmation is reaching them; null means none was sent
note.textContent = r.booking.confirmation === "email" ? "We've emailed you a confirmation."
: r.booking.confirmation === "text" ? "We've texted you a confirmation." : "You're booked.";
}
Say a confirmation was sent only when confirmation says so: it is null when there is no email address and no agreement to texts on file, when a text would fall in quiet hours, or when confirmations from that visitor were held back by a rate limit.
Email-marketing consent
A form can ask whether the visitor wants marketing email. Turn the box on in the page's data: "marketingConsent": true shows the standard wording ("Email me news and offers from {business}. I can unsubscribe at any time.", in the page's language), or give your own wording as a string ({business} is filled with your name). The ready-made Instant estimate, Job intake, Questions and answers, Listing and Waitlist forms show it, unticked, when it's on; it's off unless you turn it on.
A page you write sends only whether the box was ticked, under the reserved key _consent: panel.emit("lead", { name, email, _consent: { marketing: box.checked, lang: "en" } }), where lang is the language the page showed the standard wording in. We take the key out of the data, work out the wording from the page's data ourselves, and record { marketing, text, at } with the reply and as data.consent on widget.event. A page whose data has no marketingConsent gets no consent record, whatever it sends. marketing is about email only: it never means agreement to texts.
A sign-up paid for with panel.pay carries the answer in its details instead, as plain strings: marketingConsent: "yes" or "no" and marketingConsentLang. We take both out, and record the consent with the sign-up once it's paid.
When a reply whose box was ticked is saved as a customer, the agreement goes on the customer record too: emailMarketingAt, emailMarketingMethod (form_checkbox), emailMarketingText and emailMarketingRef (the page). Unsubscribing from your emails sets emailMarketingWithdrawnAt, and so does PATCH with emailMarketing: false. A new email address starts with none. Group emails with news or offers skip a customer who withdrew.
Visitor posts: panel.post
On a page whose owner turned on Visitors can post (page options visitorPosts, or the workspace's), visitors can post short public messages everyone on the page sees live: a chat, a job room, questions at an event. panel.canPost says whether they can now; show a composer only then. panel.posts is the page's newest posts, oldest first; panel.on("posts", fn) hears the list change and panel.on("post", fn) each new, changed or removed post (removed: true). panel.viewer is { name } (a first name) when the visitor came through a link the business sent them.
const r = await panel.post("main", { text, name }); // channel: up to 32 of a-z 0-9 _ -
if (r.ok && r.held) note.textContent = "Thanks. It will show once it's been checked.";
else if (!r.ok) note.textContent = r.error; // r.code: posts_off, rate_limited, page_busy, too_long, empty
panel.on("posts", (posts) => draw(posts)); // { id, n, channel, by: "visitor" | "owner", name, text, replyTo, at }
await panel.report(postId); // three reports hide a post until the business looks
Text is up to 1,000 characters, a name 60, and data 1,000 characters of JSON. One visitor can post 5 a minute and 30 an hour on a page; a page takes 120 visitor posts an hour. Posts with links, or that the safety check flags, are held for the business. Each page keeps its newest 500. The business reads, approves, hides, deletes and answers posts at /api/v1/publish/boards/{id}/posts, in the app's Posts tab, or by text.
Webhooks
Add a URL under /api/v1/webhooks and events (pages, replies, bookings, payments, customers) are POSTed to it, signed with programmable-page-signature: t=…,v1=HMAC-SHA256(secret, "t.body"). Delivery is at least once: skip repeats by the event's id. Failed deliveries are retried with backoff; a URL that keeps failing is switched off and can be switched back on. The webhook reference has every event with an example, how to check the signature (Node, Python, PHP), the retry schedule and secret rotation.
MCP (AI tools)
AI tools that speak MCP (Claude, ChatGPT, Cursor and others) connect to https://programmable.page/mcp. Nothing to install.
Connect with just the URL (Claude.ai, ChatGPT)
In Claude.ai, open Settings → Connectors → Add custom connector, and paste https://programmable.page/mcp. Leave the OAuth client fields empty. Claude sends you here to sign in; pick the workspace and what it may do, and press Allow. ChatGPT's connectors and other clients that follow the MCP authorization spec work the same way.
The endpoint uses OAuth 2.1 with PKCE (S256), as the MCP authorization spec asks: protected resource metadata at /.well-known/oauth-protected-resource (a 401 from /mcp points to it in WWW-Authenticate), authorization server metadata at /.well-known/oauth-authorization-server, dynamic client registration at /oauth/register, and tokens bound to https://programmable.page/mcp (RFC 8707). Access tokens last an hour; refresh tokens rotate on every use. The scopes are the API-key scopes above; a workspace member can give an app Read and Write only. The app acts as you in that workspace, and stops when you leave it. See and disconnect apps under Settings → Keys → Connected apps; signing out everywhere disconnects all of yours.
With an API key
claude mcp add --transport http programmable-page https://programmable.page/mcp --header "Authorization: Bearer pt_…"
Or run the stdio server with PROGRAMMABLE_PAGE_URL=https://programmable.page and PROGRAMMABLE_PAGE_TOKEN=pt_…. The tools make, change and send pages, manage customers and recurring pages, list bookings, say what's owed and whether a page was paid (get_money, get_page_payments), manage outbound webhooks and run jobs. They go through the same calls as above, so the key's scopes and limits apply.