API Reference

All routes below are injected by @caretcms/core when you add caret() to your Astro config. The base path defaults to /api/cms and is configurable via apiBasePath.

Conventions

Tip

• All requests are JSON unless noted (POST /api/cms/upload is multipart/form-data).
• Mutating routes (POST to /mutate, /upload, /history) require:
  • A valid editor session cookie (caret_session)
  • The x-caret-request: 1 request header (CSRF defense — see Authentication & Security)
• Errors return JSON { error, detail? } with the HTTP status code reflecting the failure mode.

HTTP status codes

Status	Meaning
200	Success
400	Validation error (bad payload, prototype-pollution attempt, malformed field)
401	No session cookie or session expired
403	Missing CSRF header or insufficient permissions
404	Entry / collection not found
409	Optimistic-locking conflict (expectedRevision mismatch)
429	Too many failed logins (rate limit) — POST /api/cms/auth/login only, with Retry-After
500	Server error

Auth

Route	Method	Purpose
/api/cms/auth/login	POST	Log in with CARET_EDIT_PASSWORD
/api/cms/auth/session	GET	Check whether the current editor session is authenticated
/api/cms/auth/logout	POST	Clear the editor session

Login

POST /api/cms/auth/login
Content-Type: application/json

{ "password": "your-password" }

Sets caret_session cookie on success (HttpOnly; SameSite=Lax; Secure on HTTPS).

Session check

GET /api/cms/auth/session

→ { "authenticated": true }

Used by the inline editor bootstrap to decide whether to load editor JS.

Logout

POST /api/cms/auth/logout

Clears the cookie. Returns { ok: true }. (No CSRF header required — logout only clears state.)

Content

Route	Method	Purpose
/api/cms/entries	GET	List entries by collection
/api/cms/schema	GET	Collection schema (registered, dynamic, or inferred)
/api/cms/collections-metadata	GET	List metadata for all dynamic collections
/api/cms/mutate	POST	Execute a mutation command
/api/cms/publish	POST	Flush the current editor’s draft overlay into base storage
/api/cms/draft	DELETE	Discard draft overlay without publishing
/api/cms/history	GET / POST	Read or restore from revision history
/api/cms/upload	POST	Upload a file (multipart/form-data)

GET /api/cms/entries

GET /api/cms/entries?collection=pages

→ {
  "collection": "pages",
  "entries": [
    { "id": "home", "data": { "headline": "..." }, "revision": 7 },
    { "id": "about", "data": { "title": "..." }, "revision": 2 }
  ]
}

GET /api/cms/schema

GET /api/cms/schema?collection=pages

→ {
  "collection": "pages",
  "source": "registered",      // or "dynamic" or "inferred"
  "schema": { /* JSON Schema */ },
  "template": { /* default value */ },
  "metadata": {                  // present when source is "dynamic"
    "label": "Pages",
    "icon": "📄",
    "creatable": true,
    "orderable": false
  }
}

See Schemas for the resolution order and supported features.

GET /api/cms/collections-metadata

GET /api/cms/collections-metadata

→ {
  "collections": [
    {
      "id": "products",
      "label": "Products",
      "icon": "📦",
      "creatable": true,
      "orderable": true,
      "schema": { /* JSON Schema */ },
      "created_at": 1714225200000,
      "updated_at": 1714225200000
    }
  ]
}

Note

Returns metadata for dynamic collections only. Registered collections aren’t included here — read those from the schemas config or /api/cms/schema?collection=....

POST /api/cms/mutate

All writes go through here.

POST /api/cms/mutate
Content-Type: application/json
x-caret-request: 1
Cookie: caret_session=...

{ "type": "save_field", "collection": "pages", "id": "home", "field": "headline", "value": "New" }

→ { "ok": true, "revision": 8 }

Mutation command types

type	Purpose
save_field	Update one field on one entry
put_entry	Create or replace an entry’s full data
delete_entry	Delete an entry
reorder_entries	Reorder entries within a collection
update_page_layout	Update section composer state
create_collection	Create a dynamic collection (schema + metadata)
delete_collection	Delete a dynamic collection (and all its entries + history)

Common fields

Field	Required by	Notes
type	all	One of the values above
collection	most	Lowercase, alphanumeric, - / _
id	most	Entry ID
field	save_field	Dot-path (hero.title); rejects __proto__ etc.
value	save_field	New value for the field
data	put_entry	Full entry data object (creates or replaces)
expectedRevision	optional on writes	Pass for optimistic locking; returns 409 on mismatch

Conflict response

{ "error": "Revision conflict", "currentRevision": 9 }

with HTTP 409. Re-read the entry, re-apply the user’s intent, and retry with the new currentRevision.

GET /api/cms/history

GET /api/cms/history?collection=pages&id=home

→ {
  "history": [
    { "ts": 1714225200000, "data": {...}, "action": "save" }
  ]
}

Capped at the last 50 revisions per entry. action is one of save, put, delete, reorder, or restore (the operation that produced the snapshot, not the mutation type).

POST /api/cms/history

Restore an entry to a previous revision:

POST /api/cms/history
x-caret-request: 1
Cookie: caret_session=...

{ "collection": "pages", "id": "home", "ts": 1714225200000 }

The corresponding history entry is re-applied as a put_entry mutation.

POST /api/cms/upload

Multipart form with a single file field:

curl

curl -X POST http://localhost:4321/api/cms/upload \
  -H 'x-caret-request: 1' \
  -H 'Cookie: caret_session=...' \
  -F file=@./hero.jpg

→ { "url": "/uploads/abc123.jpg" }

POST /api/cms/publish

Flush the authenticated editor’s draft overlay into base storage. Optional body scopes the flush:

POST /api/cms/publish
Content-Type: application/json
x-caret-request: 1
Cookie: caret_session=...

{}                                    → publish all draft entries
{ "collection": "pages" }             → one collection
{ "collection": "pages", "id": "home" } → one entry

→ {
  "ok": true,
  "published": [{ "collection": "pages", "id": "home", "revision": 8, "deleted": false }],
  "commit": "abc1234",          // when CARET_GIT_ON_PUBLISH=true and git repo present
  "rebuild": { "triggered": true, "ok": true }
}

When delivery.publish.webhookUrl is configured, a successful publish POSTs a rebuild payload to CI. See Static delivery.

DELETE /api/cms/draft

Drop draft state without writing to base storage:

DELETE /api/cms/draft
x-caret-request: 1
Cookie: caret_session=...

DELETE /api/cms/draft?collection=pages&id=home   → scoped discard

→ { "ok": true, "cleared": ["pages/home"] }

Admin pages

Route	Purpose
/admin	Login / redirect
/admin/cms	Content Studio dashboard
/admin/cms/[collection]	Collection list view
/admin/cms/[collection]/[id]	Entry editor

These mount at ${mountPath} (default /admin). Disable with enableAdmin: false.

Editor assets

Route	Purpose
/__caret/editor.js	Inline editor runtime
/__caret/editor.css	Editor styles

Loaded automatically when an editor session cookie is present. Disable with enableInlineEditor: false.

Hosted cloud API Coming soon

The hosted version of CaretCMS exposes a separate API surface for cloud mode clients. These routes are served by the hosted control plane, not by your Astro site.

Route	Method	Purpose
/content	GET	Fetch entries for a project
/content/mutate	POST	Write mutations
/content/schema	GET	Project schema
/content/history	GET	Entry history
/content/upload	POST	File upload
/content/auth/login	POST	Editor login (Better Auth)
/content/auth/logout	POST	Editor logout

Cloud routes use bearer token authentication (Authorization: Bearer ...) instead of cookies. Project membership is verified on every request. These docs will be expanded once the hosted service launches.

Next steps

Authentication & Security Sessions, CSRF, password setup.

Configuration apiBasePath, mountPath, all options.

Troubleshooting Common API errors and fixes.