API

Use personal API keys to read and change PagePot projects from scripts and other tools.

The PagePot API lets your own scripts and tools read and change projects: for example, a script that keeps product pages in step with Jenny's stock system, or a dashboard that shows how many pages are complete. It's on the Team and Agency plans, with the same access on both.

Create an API key

Open Settings → API and AI agents. Everyone in the workspace can create their own keys.

Settings: API keys

  • Name the key after what uses it, such as "Stock sync".
  • Access: Read only, or Read and write.
  • Projects: all the projects you can access (including new ones), or only the ones you pick.

Click Create key and copy it: it's shown only once. Keys start with ppk_ and don't expire.

A key acts as you. It can only do what your project roles allow, in this workspace. If you are an Editor on a project, a key can write content there but not change the sitemap. The project history shows changes made with a key as yours, "via API".

Keep keys secret, like a password. Revoke a key you no longer need, or that may have leaked. Keys stop working when you leave the workspace, and while the workspace's plan doesn't include the API. Workspace admins see everyone's keys and can revoke them.

Make a request

Send the key in the Authorization header. The API is at /api/v1 on your PagePot address.

curl https://pagepot.io/api/v1/projects \
  -H "Authorization: Bearer ppk_your_key"

Responses are JSON: { "data": … }, or { "error": { "code": "…", "message": "…" } } when something goes wrong. The full description of every endpoint, in OpenAPI format, is at /api/v1/openapi.json; tools such as Postman can import it.

What you can do

ResourceEndpoints
You and your keyGET /me
ProjectsGET /projects, GET /projects/{id}, PATCH /projects/{id}
SitemapGET /projects/{id}/sitemap; add, change, move, delete and restore pages under /projects/{id}/pages
Page contentGET /projects/{id}/pages/{pageId} (blocks, SEO, metadata, status); add, save and remove blocks; save SEO and metadata; start translations
WorkflowSet a page's status, assignees and due-date
CommentsList, add, reply, edit and resolve
ReferenceTemplates, statuses, metadata schemas and members
FilesList, upload and download
ActivityThe project's history, newest first
WebhooksAdd, change, test and delete webhooks

Content endpoints take ?language= for other languages. Rich text is returned both as JSON (the editor's format) and as HTML. To save rich text, send either: value with the JSON, or html. HTML keeps what the editor supports (headings, lists, links, tables, bold and italic, images from the project and YouTube or Vimeo videos); anything else keeps only its text.

curl -X PUT https://pagepot.io/api/v1/projects/{id}/pages/{pageId}/blocks/{blockId} \
  -H "Authorization: Bearer ppk_your_key" -H "Content-Type: application/json" \
  -d '{"html": "<h2>Delivery</h2><p>Free over <strong>$60</strong>.</p>", "expectedRevision": 3}'

Suggest instead of edit

Add "mode": "suggest" when saving a rich-text block to propose the change as tracked suggestions, like Suggesting mode in the editor (Team plan and above). Editors then accept or reject it in the page editor. A block that already has pending suggestions answers 409 (SUGGESTIONS_PENDING); ask someone to review them first.

Not available through the API yet: the AI assistant, diagrams, share links, and changing templates, statuses or team members.

The same rules as the app

  • Page locks: if someone has the page open in the editor, content changes answer 423 (locked). Try again later.
  • Changes since you read: when you save a block, send the revision you read as expectedRevision. If someone changed the block since, you get 409 with the current value, so you never overwrite their work.
  • Statuses that lock editing, required fields before approval, and your plan's limits apply as usual.

Safe retries

If a request times out, you can't always tell whether the change happened. Send an Idempotency-Key header (any unique string, such as a UUID) on writes: if you send the same request with the same key again within 24 hours, PagePot doesn't repeat the change; it returns the first answer, with the header Idempotent-Replayed: true. Using the key for a different request answers 422, and retrying while the first request is still running answers 409.

Limits

Each key can make 600 reads and 120 changes a minute. Beyond that you get 429 with a Retry-After header. Each person can have up to 25 keys.

Common errors

StatusMeaning
401Missing, unknown or revoked key
403Your role or the key's access doesn't allow it, or the plan doesn't include the API
404Not found, or not in the key's projects
409Changed since you read it
422The request isn't valid; error.issues says what's wrong
423Someone is editing the page, or its status locks editing
429Too many requests