REST API — Total CMS 3

Total CMS exposes a REST API at your site's /api root. Same-origin requests — the admin's own JavaScript, a browser tool on the same domain — authenticate with the session cookie in every edition. External access is a Pro feature: API keys are Pro, and so is the external REST API gate, so a headless front end, a mobile app or a third-party integration calling in from another host needs a Pro license.

The shape is what you would expect. GET /api/collections lists collections; GET /api/collections/{collection} returns objects with limit, offset, sort, order, filter and search; POST creates, PUT replaces, PATCH merges, DELETE removes. There is a clone endpoint, HEAD requests that answer “does this exist” without a body, and GET /api/collections/{collection}/schema so a client can discover the fields instead of hard-coding them.

Below the object level it gets more useful than most CMS APIs. You can PUT, PATCH or DELETE a single property without sending the whole object, increment or decrement a numeric property atomically (a view counter is one POST), edit the metadata on one gallery image, and add, update or remove individual deck items. File properties have their own endpoints handling direct multipart uploads, Dropzone-style chunked uploads, and URL uploads where you POST a link and the server fetches it.

Reading in bulk is covered too: a query endpoint with pagination metadata and include/exclude field selection that can return JSON, CSV or HTML, plus report endpoints that export a chosen set of fields as a CSV or JSON download, expanding deck fields into one row per item.

Access is scoped, not all-or-nothing. An API key carries a set of HTTP methods and a set of allowed path prefixes, so a key can be GET-only on /api/collections/blog and nothing else. Keys are shown once, track their own last-used timestamp, and are revoked by deleting them. One rule worth knowing before you design an integration: an API key bypasses access-group checks and reaches exactly as far as its scope, whereas an OAuth Bearer token is checked against the approving user's access groups on every request.

What you get

CRUD on every collection

List, read, create, replace, merge, clone and delete objects, with filtering, search, sorting and offset pagination on the read side.

Write one property, not the object

PUT, PATCH or DELETE a single property, atomically increment a counter, or edit one deck item — without round-tripping the whole record.

Uploads that match the admin

The same endpoints the admin uses behind every image, file, gallery and depot field: multipart, chunked, or POST a URL and let the server fetch it.

Scoped API keys

Each key allows a set of HTTP methods and a set of path prefixes. Prefix matching means /api/collections/blog covers every object under it — no wildcards to write. API keys are a Pro feature.

Reports and exports built in

Query with include/exclude field selection in JSON, CSV or HTML, or hit the report endpoints for a CSV or JSON download of exactly the fields you name.

In practice

One snippet

# Read a collection
curl -H "X-API-Key: tcms_1234567890abcdef1234567890abcdef" \
     https://yoursite.com/api/collections/blog

# Publish one post without sending the rest of it
curl -X PATCH https://yoursite.com/api/collections/blog/my-first-post \
  -H "X-API-Key: tcms_1234567890abcdef1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{"status": "published"}'

# Bump a view counter atomically
curl -X POST https://yoursite.com/api/collections/blog/my-first-post/views/increment

Keys travel in the X-API-Key or Authorization: Bearer header only — there is no query-parameter authentication.

FAQ

Common questions

Which parts of the API need Pro?

API keys and external REST access are Pro features. Session-authenticated same-origin requests — the admin, and browser code on your own domain — work in every edition. If an external service, mobile app or headless front end will call the API, that is Pro.

How do I limit what a key can reach?

A key carries allowed HTTP methods and allowed path prefixes, and both must match for a request to be authorised. Matching is by prefix, so /api/collections/blog already covers /api/collections/blog/123 — no trailing wildcard is needed or wanted.

Do API keys respect access groups?

No — an API key bypasses access-group checks entirely and reaches as far as its configured scope, whoever created it. OAuth Bearer tokens behave differently: they are checked against the approving user's access groups on every request. Scope an API key tightly.

Can I upload files through the API?

Yes. Image, file, gallery and depot properties have upload endpoints that accept a direct multipart upload, a chunked Dropzone-style upload, or a JSON body containing a URL for the server to download. The response is the updated object, so you see the new file in context.

Related features

Want the details? Read the REST API documentation →

Or keep browsing: every Total CMS feature →

Start Your Free 45-Day Trial

Every collection you model is an API the moment you save it