API for partners#
The CoolCMS REST interface. It serves mobile apps, partner systems and custom clients.
Where to start#
- Getting started — your first request in five minutes. You need an application key first.
- Authentication — the application key and the user token.
- Response format — 🔴 read this before writing a parser.
- CRUD pattern — reading and writing.
- Error codes.
Address shape#
Optionally with a language prefix: /en/api/…. The default language is Czech.
Modules and their resources are in the reference.
Every request carries an X-API-Key header with the application key issued by the website
administrator. Without it the API returns 401. A signed-in user is added with a token in the
Authorization header. See Authentication.
🔴 Three things that surprise everybody#
Read them now rather than finding them in a debugger.
1. Parameters go in the URL, not in the request body
Writes included. A POST with a JSON body reads as "missing data". The
exceptions are the authentication endpoints, which conversely read a form body,
and the password actions, which read them only from the body. See the
CRUD pattern.
2. Reads and writes return different shapes
A read returns items and _references without a success field. A write
returns an envelope with success. A single parser keyed on success is not
possible. See Response format.
3. Errors arrive with HTTP 200
Data validation, "not found" and conflicts alike. Only 400 (a malformed request), 401, 403, 429 and 204 are distinguished by status code. See Error codes.
What the API offers#
| Group | Actions |
|---|---|
| Reading | get, get-by, get-all |
| Writing | save, update-columns |
| Deleting | delete, delete-all |
| Trees | move-up, move-down, move-subtree, delete-node |
| Events | register-event |
The specification#
The machine-readable specification is at /api-docs.json, the browser at
/api-docs/. Every operation requires the apiKeyAuth scheme (the application key) and
optionally bearerAuth (the user token).
The specification currently covers only the auth endpoints
Five paths (sign-in, refresh, sign-out, profile and token check) out of several hundred. The rest is described by this manual. Do not rely on a generated client.