HTTP API
Every endpoint TachyonCMS v0.1.0 serves. This page covers what they share and lists them all. Each area has its own page with a section per endpoint: Sign-in and keys, Users and roles, Content types and Documents.
The guides explain the ideas behind them: Sign-in, API keys, Roles, Content types, Querying and Access rules.
Requests and responses
Section titled “Requests and responses”- Every path starts with
/api. The examples calllocalhost:3000and send$TOKEN, the Admin’s bearer token fromPOST /api/auth/login, or$AUTHOR_TOKEN, an Author’s. - Request bodies are JSON with
content-type: application/json, up to 10 MB. - Responses are JSON. Errors are
application/problem+json; see Errors. - Every response carries an
x-request-idheader. - A request that runs for more than 30 seconds is stopped with a
503. - Documents come back with
id,createdAt,updatedAtandstatus(always"published"in v0.1.0) besides their fields. Keys are in alphabetical order.
Credentials
Section titled “Credentials”Send one of these, or nothing:
| Credential | How | Notes |
|---|---|---|
| Session cookie | __Host-tachyon_session, set by sign-in |
For browsers. A change (any method but GET, HEAD or OPTIONS) must also send an Origin matching public_url or allowed_origins, or it’s a 403. An expired cookie counts as signed out. |
| Session token | authorization: Bearer tcs_… |
From sign-in with "bearer": true. An ended session is a 401. |
| API key | authorization: Bearer tcy_… |
From POST /api/auth/keys. Acts as its owner, narrowed by its scopes. |
Who can call what
Section titled “Who can call what”The Who row of each endpoint uses these terms:
| Term | Means |
|---|---|
| Anyone | No credentials needed. Read rules still decide what comes back. |
| Signed in | A session, or an API key with the admin scope. Other keys get a 403. |
| Session | A session only. API keys are refused. |
users ability |
A role with users: true (Admin by default). Keys also need the admin scope. A role with this ability can do everything an Admin can. |
schemas ability |
A role with schemas: true (Admin by default). Keys also need the admin scope. |
| Content | The role’s content ability, the collection’s access rules and, for a key, its scopes: collection:read, collection:write, *:read, *:write or admin. |
Signed out, a refusal is a 401 Sign in first.; signed in, it’s a 403.
Any endpoint can also return 400 for a body that isn’t JSON, 401 for credentials that don’t work, 413, 500 and 503. The Errors rows list the rest.
All endpoints
Section titled “All endpoints”| Method and path | Does | Who |
|---|---|---|
GET /api/setup |
Says whether setup is needed. | Anyone |
POST /api/setup |
Creates the first Admin. | Anyone, once |
POST /api/auth/login |
Signs in. | Anyone |
POST /api/auth/logout |
Signs out. | Session |
GET /api/auth/me |
Returns your account. | Signed in |
GET /api/auth/sessions |
Lists your sessions. | Signed in |
DELETE /api/auth/sessions/{id} |
Ends one of your sessions. | Signed in |
POST /api/auth/password |
Changes your password. | Session |
GET /api/auth/keys |
Lists your API keys. | Session |
POST /api/auth/keys |
Makes an API key. | Session |
DELETE /api/auth/keys/{id} |
Revokes an API key. | Session |
POST /api/auth/keys/{id}/rotate |
Replaces an API key. | Session |
GET /api/users |
Lists users. | users ability |
POST /api/users |
Creates a user. | users ability |
GET /api/users/{id} |
Reads a user. | Yourself, or users ability |
PATCH /api/users/{id} |
Changes a user. | Yourself, or users ability |
DELETE /api/users/{id} |
Deletes a user. | users ability |
GET /api/admin/roles |
Lists roles. | Signed in |
POST /api/admin/roles |
Adds a role. | users ability |
PUT /api/admin/roles/{slug} |
Changes a custom role. | users ability |
DELETE /api/admin/roles/{slug} |
Removes a custom role. | users ability |
GET /api/admin/collections |
Lists content types. | Signed in |
POST /api/admin/collections |
Creates a content type. | schemas ability |
GET /api/admin/collections/{slug} |
Reads a content type. | Signed in |
PUT /api/admin/collections/{slug} |
Changes a content type. | schemas ability |
POST /api/admin/collections/{slug}/preview |
Previews a change. | schemas ability |
GET /api/access |
Says what you may do. | Anyone |
GET /api/globals/{slug} |
Reads a global. | Content |
PATCH /api/globals/{slug} |
Changes a global. | Content |
GET /api/{collection} |
Lists documents. | Content |
POST /api/{collection} |
Creates a document. | Content |
GET /api/{collection}/{id} |
Reads a document. | Content |
PATCH /api/{collection}/{id} |
Changes a document. | Content |
DELETE /api/{collection}/{id} |
Deletes a document. | Content |
GET /api/{collection}/{id}/references |
Lists documents that link here. | Content |