REST API

The REST API lets other software work with your site over HTTP: an integration that adds products, a script that imports posts, a front end built in another framework. It runs the same abilities as the admin, with the same permissions and the same audit log.

There are two parts. The ability API can do anything you can, with a token. The content API reads published content, with no token at all.

#Create a token

A token is a password for one app or script. It acts as you, so keep it secret.

1. Click your name at the bottom of the sidebar and choose Account.
2. Under API & Agents, press New Token.
3. Name it after what will use it, choose its Access and when it Expires, then press Create Token.
4. Copy the token. It's shown only once.

Access limits what the token can do: Full Access, Read Only, or Content Only. Give each token no more than it needs. To stop a token working, choose Revoke in its menu. Anything using it stops at once.

#Make a request

Send the token as a bearer token. This lists the entries of the posts collection:

curl https://your-site.com/api/v1/abilities/entries/list \
  -H "Authorization: Bearer cms_…" -G -d collection=posts

Read-only abilities answer GET with query parameters. Every ability answers POST with a JSON body:

curl https://your-site.com/api/v1/abilities/entries/create \
  -H "Authorization: Bearer cms_…" -H "Content-Type: application/json" \
  -d '{"collection": "posts", "title": "Hello"}'

Every ability on your site, with what it takes, is in the abilities reference.

#Read published content

For a headless front end, published content is readable without a token:

Collections with a route are available unless they set api: false. Collections without a route are available only with api: true. Responses can be cached for a minute, and each visitor can make 120 requests a minute.

#For developers

#Tokens from the command line

php cms token:create you@example.com --scope='entries/*' --days=90

Tokens are shown once and stored hashed. Scopes are ability patterns (entries/*, media/import), read for every read-only ability, or * for everything you can do. In the admin, Read Only is read, Content Only is entries/* and Full Access is *.

#Endpoints

#Responses and limits

Successful calls return { "data": … }. Errors return { "error": { "type", "message", "details" } } with status 422, 403, 401, 404, 409 or 500. Each token can make 240 requests a minute.