Headless API

The ClearCMS REST API provides programmatic access to your site's pages, content items, and global settings.

Try it — API Explorer

Enter your site URL and API key to test endpoints live. Public endpoints work without a key.

API Explorer

Parameters

type*

page

per_page

search

sort

order

Show cURL

curl \
  "https://your-site.clearcms.app/api/v1/public/collections/"

Authentication

Include your API key as a Bearer token in every request:

Authorization: Bearer YOUR_API_KEY

Generate API keys under Settings > Developer > API Keys.

Base URL

https://your-site.clearcms.app/api/v1

---

Endpoints

Pages

List pages

GET /pages

cURL:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://your-site.clearcms.app/api/v1/pages

Returns all published pages.

Query parameters:

Parameter	Type	Description
draft	boolean	Set true to include draft pages (requires auth)
limit	integer	Number of results per page. Default: 20. Max: 100
offset	integer	Offset for pagination

Response:

{
  "items": [
    {
      "id": "abc123",
      "slug": "about",
      "title": "About Us",
      "isHomepage": false,
      "publishedAt": "2026-03-01T12:00:00Z",
      "updatedAt": "2026-03-15T09:30:00Z"
    }
  ],
  "total": 5,
  "limit": 20,
  "offset": 0
}

Get a page

GET /pages/{slug}

cURL:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://your-site.clearcms.app/api/v1/pages/about

Returns a single page with its full content tree.

Path parameters:

Parameter	Description
slug	Page slug (e.g. about, home)

Query parameters:

Parameter	Type	Description
draft	boolean	Set true to return draft content (requires auth)

Response:

{
  "id": "abc123",
  "slug": "about",
  "title": "About Us",
  "isHomepage": false,
  "sections": [
    {
      "id": "sec_001",
      "type": "hero",
      "order": 0,
      "data": {
        "headline": "We build great software",
        "subheadline": "Based in London",
        "ctaLabel": "Get in touch",
        "ctaUrl": "/contact"
      }
    }
  ],
  "seo": {
    "title": "About Us | Acme Corp",
    "description": "Learn about our team and mission.",
    "ogImage": "https://cdn.clearcms.app/sites/acme/og-about.jpg"
  }
}

---

Content items

Content items are structured records -- blog posts, team members, products, etc.

List content items

GET /content/{type}

cURL:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://your-site.clearcms.app/api/v1/content/posts

Returns all published items of the given content type.

Path parameters:

Parameter	Description
type	Content type slug (e.g. posts, team, products)

Query parameters:

Parameter	Type	Description
draft	boolean	Include drafts (requires auth)
limit	integer	Results per page. Default: 20. Max: 100
offset	integer	Pagination offset
sort	string	Field to sort by, prefix with - for descending. Example: -publishedAt

Response:

{
  "items": [
    {
      "id": "post_001",
      "type": "posts",
      "title": "Hello World",
      "slug": "hello-world",
      "data": {
        "body": "<p>This is my first post.</p>",
        "author": "Jane Smith",
        "tags": ["announcement"],
        "featuredImage": "https://cdn.clearcms.app/sites/acme/hello.jpg",
        "excerpt": "A short introduction."
      },
      "publishedAt": "2026-03-10T08:00:00Z"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Get a content item

GET /content/{type}/{slug}

Returns a single content item by slug.

---

Global settings

GET /globals

cURL:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://your-site.clearcms.app/api/v1/globals

Returns site-wide settings: site name, logo, navigation links, footer content, and social links.

{
  "siteName": "Acme Corp",
  "logoUrl": "https://cdn.clearcms.app/sites/acme/logo.svg",
  "nav": [
    { "label": "Home", "url": "/" },
    { "label": "About", "url": "/about" }
  ],
  "footer": {
    "copyrightText": "© 2026 Acme Corp"
  }
}

---

Pagination

All list endpoints use offset-based pagination:

GET /content/posts?limit=10&offset=20

Responses include total, limit, and offset for page calculation:

const totalPages = Math.ceil(total / limit);
const currentPage = Math.floor(offset / limit) + 1;

---

Draft content

All endpoints return only published content by default. Append ?draft=true to include drafts. Draft requests require a valid API key.

GET /pages/about?draft=true
Authorization: Bearer YOUR_API_KEY

---

Error responses

All errors follow this shape:

{
  "error": "NOT_FOUND",
  "message": "No page found with slug 'missing-page'"
}

Status	Error code	Meaning
400	BAD_REQUEST	Invalid query parameter or request body
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	API key lacks permission for this operation
404	NOT_FOUND	Resource does not exist
429	RATE_LIMITED	Too many requests; see Retry-After header
500	INTERNAL_ERROR	Server error