API Reference

The CMS Builder Pro REST API

A predictable, resource-oriented API over HTTPS. All requests use bearer authentication, accept and return JSON, and are versioned under /v1.

http

BASE URL
https://api.cmsbuilderpro.com/v1

AUTH HEADER
Authorization: Bearer $CMSBP_TOKEN

Pagination

List endpoints accept limit (1–100) and cursor, and return next_cursor until the last page.

Rate limits

1,000 requests per minute per project. Exceeding it returns 429 with a Retry-After header.

Error shape

Every failure returns the same envelope. Include request_id when contacting support.

json

{
  "error": {
    "type": "invalid_request",
    "message": "slug must be unique within the project",
    "field": "slug",
    "request_id": "req_5ad2c1"
  }
}

Authentication

Every request is authenticated with a project token sent as a bearer header. Read tokens are safe for server-side rendering; write tokens must never reach the browser.

POST/auth/token

Exchange an API key for a short-lived token

Trades a long-lived project API key for a 60-minute access token. Use this in CI or when you cannot store a write token at the edge.

Body parameters

Name	Type	Description
api_key*	string	Project API key from Settings → API Keys.
scope	string	Space separated scopes, e.g. `content:read content:write`.

bash

curl -X POST https://api.cmsbuilderpro.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key":"'"$CMSBP_API_KEY"'","scope":"content:read content:write"}'

GET/auth/whoami

Inspect the current token

Returns the project, environment and scopes attached to the presented token. Useful for debugging 403s.

bash

curl https://api.cmsbuilderpro.com/v1/auth/whoami -H "Authorization: Bearer $CMSBP_TOKEN"

Pages

Pages are the routable documents rendered by the builder. List endpoints are paginated with `limit` and `cursor` and always return a `next_cursor`.

GET/pages

List pages

Returns pages ordered by last update. Filter by status, template or search term.

Query & path parameters

Name	Type	Description
status	enum	`draft`, `published`, `scheduled` or `archived`.
q	string	Full-text search across title, slug and SEO fields.
limit	integer	1–100, defaults to 25.
cursor	string	Opaque cursor returned as `next_cursor`.

bash

curl -G https://api.cmsbuilderpro.com/v1/pages \
  -H "Authorization: Bearer $CMSBP_TOKEN" \
  -d status=published -d limit=25

GET/pages/{page_id}

Retrieve a page

Fetches a single page including its SEO block and the serialised builder layout.

Query & path parameters

Name	Type	Description
page_id*	string	Page id or `slug:pricing`.
include	string	Comma separated: `layout`, `revisions`, `seo`.

bash

curl "https://api.cmsbuilderpro.com/v1/pages/pg_92f1?include=layout,seo" \
  -H "Authorization: Bearer $CMSBP_TOKEN"

POST/pages

Create a page

Creates a draft page. Provide a layout to publish content programmatically in one call.

Body parameters

Name	Type	Description
title*	string	Human readable page title.
slug	string	Defaults to a slugified title.
status	enum	`draft` (default), `published` or `scheduled`.
publish_at	string	ISO 8601 timestamp, required when scheduled.
layout	object	Builder tree of sections, columns and widgets.

bash

curl -X POST https://api.cmsbuilderpro.com/v1/pages \
  -H "Authorization: Bearer $CMSBP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Changelog","status":"draft"}'

PATCH/pages/{page_id}

Update or publish a page

Partial update. Every write creates a revision, so you can roll back from the dashboard or the revisions endpoint.

Body parameters

Name	Type	Description
title	string	New title.
status	enum	Set to `published` to go live immediately.
seo	object	`title`, `description`, `og_image`, `no_index`.
layout	object	Replaces the builder tree.

bash

curl -X PATCH https://api.cmsbuilderpro.com/v1/pages/pg_b41a \
  -H "Authorization: Bearer $CMSBP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"published"}'

DELETE/pages/{page_id}

Delete a page

Soft deletes a page and removes it from the edge cache. Revisions are retained for 30 days.

bash

curl -X DELETE https://api.cmsbuilderpro.com/v1/pages/pg_b41a -H "Authorization: Bearer $CMSBP_TOKEN"

GET/pages/{page_id}/revisions

List revisions

Returns the revision history with the author and a diff summary for each entry.

bash

curl https://api.cmsbuilderpro.com/v1/pages/pg_92f1/revisions -H "Authorization: Bearer $CMSBP_TOKEN"

Templates

Templates are reusable builder layouts. Apply one to a page to replace its section tree in a single request.

GET/templates

List templates

Returns page and section templates saved from the visual builder.

Query & path parameters

Name	Type	Description
kind	enum	`page` or `section`.

bash

curl -G https://api.cmsbuilderpro.com/v1/templates -H "Authorization: Bearer $CMSBP_TOKEN" -d kind=page

POST/templates/{template_id}/apply

Apply a template

Overwrites the target page layout with the template tree and records a revision.

Body parameters

Name	Type	Description
page_id*	string	Page receiving the layout.

bash

curl -X POST https://api.cmsbuilderpro.com/v1/templates/tpl_11c4/apply \
  -H "Authorization: Bearer $CMSBP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"page_id":"pg_b41a"}'

Media

Uploads use a two-step signed URL flow so files never pass through the API. Derivatives (webp, avif, thumbnails) are generated automatically.

POST/media/uploads

Create a signed upload

Returns a short-lived URL to PUT the binary to, plus the asset record that will be created.

Body parameters

Name	Type	Description
filename*	string	Original file name including extension.
content_type*	string	MIME type, e.g. `image/png`.
folder	string	Media library folder path.

bash

curl -X POST https://api.cmsbuilderpro.com/v1/media/uploads \
  -H "Authorization: Bearer $CMSBP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filename":"hero.png","content_type":"image/png","folder":"marketing"}'

GET/media

List assets

Paginated media library listing with folder and type filters.

Query & path parameters

Name	Type	Description
folder	string	Restrict to a folder path.
type	enum	`image`, `video`, `document`.

bash

curl -G https://api.cmsbuilderpro.com/v1/media -H "Authorization: Bearer $CMSBP_TOKEN" -d type=image

DELETE/media/{asset_id}

Delete an asset

Removes the asset and all derivatives. Fails with 409 when the asset is referenced by a published page.

bash

curl -X DELETE https://api.cmsbuilderpro.com/v1/media/ast_5d20 -H "Authorization: Bearer $CMSBP_TOKEN"

Tickets

The support API mirrors the in-app ticket workflow: create tickets from your product, sync statuses, and stream replies with attachments.

POST/tickets

Create a ticket

Opens a ticket in the workspace inbox and returns the public ticket number your users can quote.

Body parameters

Name	Type	Description
subject*	string	Short summary, 4–140 characters.
description*	string	Full problem description.
requester*	object	`name`, `email`, optional `phone`.
priority	enum	`low`, `medium` (default), `high`, `urgent`.
category	enum	`general`, `bug`, `billing`, `technical`, `feature`, `question`.
attachments	array	Asset ids returned by the media upload flow.

bash

curl -X POST https://api.cmsbuilderpro.com/v1/tickets \
  -H "Authorization: Bearer $CMSBP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Checkout widget not rendering",
    "description": "The pricing widget is blank on Safari 17.",
    "priority": "high",
    "requester": { "name": "Ada Lovelace", "email": "ada@northwind.io" }
  }'

GET/tickets

List tickets

Queue listing with the same filters as the dashboard: status, priority, assignee and search.

Query & path parameters

Name	Type	Description
status	enum	`open`, `pending`, `in_progress`, `resolved`, `closed`.
priority	enum	`low`, `medium`, `high`, `urgent`.
q	string	Search subject, number and requester email.

bash

curl -G https://api.cmsbuilderpro.com/v1/tickets -H "Authorization: Bearer $CMSBP_TOKEN" -d status=open

PATCH/tickets/{ticket_id}

Update status, priority or assignee

Every change is appended to the ticket status history, which the dashboard renders as the audit timeline.

Body parameters

Name	Type	Description
status	enum	Moves the ticket through the workflow.
priority	enum	Re-triage the ticket.
assignee	string	Agent name or member id.

bash

curl -X PATCH https://api.cmsbuilderpro.com/v1/tickets/tkt_2c71 \
  -H "Authorization: Bearer $CMSBP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"in_progress","assignee":"grace@cmsbp.io"}'

POST/tickets/{ticket_id}/messages

Reply to a ticket

Adds an agent reply or an internal note. Internal notes are never emailed to the requester.

Body parameters

Name	Type	Description
body*	string	Message body, up to 4000 characters.
internal	boolean	`true` keeps the note private to agents.
attachments	array	Objects with `name`, `path`, `size` and `type`.

bash

curl -X POST https://api.cmsbuilderpro.com/v1/tickets/tkt_2c71/messages \
  -H "Authorization: Bearer $CMSBP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body":"We shipped a fix — please retry.","internal":false}'

Webhooks

Webhooks are signed with HMAC-SHA256. Compare the `X-CMSBP-Signature` header against the raw body using a timing-safe comparison and reject anything older than five minutes.

POST/webhooks

Register a webhook

Subscribes an HTTPS endpoint to one or more events and returns the signing secret once.

Body parameters

Name	Type	Description
url*	string	HTTPS endpoint that receives POST requests.
events*	array	e.g. `page.published`, `ticket.created`.

bash

curl -X POST https://api.cmsbuilderpro.com/v1/webhooks \
  -H "Authorization: Bearer $CMSBP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/cmsbp","events":["page.published","ticket.created"]}'

POST(your endpoint)

Event payload & signature

Each delivery includes `X-CMSBP-Signature: t=<unix>,v1=<hex>` where the signature is HMAC-SHA256 over `t + '.' + rawBody`.

bash

# Verify in bash for a quick sanity check
printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$WHSEC"

GET/webhooks/{webhook_id}/deliveries

Inspect deliveries & retries

Failed deliveries retry with exponential backoff for 24 hours. Non-2xx responses and timeouts are listed here with the response body.

bash

curl https://api.cmsbuilderpro.com/v1/webhooks/whk_0d3e/deliveries -H "Authorization: Bearer $CMSBP_TOKEN"