Skip to content
Foliosodev
Sign in Get started
Menu
On this page

REST API

Authentication and limits

Every API request is authenticated with a personal API token sent as a bearer token. Tokens are bound to one organisation, carry read or read-and-write abilities, and are rate-limited per token and per IP address.

Create a token

Tokens are created in the app, not through the API:

  1. Open Settings in the organisation you want to automate.
  2. Under API tokens, enter a Token name, choose Access (Read only or Read and write) and Expires.
  3. Select Create token and copy it straight away. It's shown only once.

See API tokens for the details. The API needs a plan that includes API access. See the pricing page.

Send the token

Put the token in the Authorization header, with the Bearer scheme:

http
GET /api/v1/spaces HTTP/1.1
Host: acme.folioso.dev
Authorization: Bearer YOUR_TOKEN
Accept: application/json
bash
curl https://acme.folioso.dev/api/v1/spaces \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

A missing, wrong, revoked or expired token gets 401 Unauthenticated.

Use your organisation's address

A token works only at the address of the organisation it was created in. Sending it to another organisation's address gets 404, the same answer as for an organisation that doesn't exist, so a token can't be used to find out which organisations exist.

If your organisation's address changes, see Errors.

Abilities

Each token holds one or both of two abilities:

Token access Abilities Allowed endpoints
Read only read All GET endpoints.
Read and write read, write All GET endpoints, plus POST /pages, PATCH /pages/{slug}, DELETE /pages/{slug}, POST /images and POST /pages/{slug}/snapshots.

A read-only token calling a write endpoint gets 403 with "message": "Invalid ability provided.". Call GET /me to see a token's abilities.

Abilities limit what kind of request a token can make. What it can reach is decided by your own permissions: a read-and-write token still can't edit a page you couldn't edit in the app.

When a valid token is refused

Status Message Why
403 Your plan does not include this feature. The organisation's plan doesn't include API access.
403 You are no longer a member of this organisation. You've left or been removed from the organisation.
403 Your account in this organisation is suspended. Contact an administrator. Your membership is suspended. The token works again if the suspension is lifted.
403 This account must enrol in two-factor authentication before its API tokens can be used. You're an admin or owner of an organisation with other members and haven't set up two-factor authentication.

Rate limits

Two limits apply to every request:

Limit Applies to Allowance
Per token Each token separately 120 requests a minute
Per IP address Every request to the API from one address, signed in or not 300 requests a minute

Each token has its own allowance, so two integrations with different tokens don't share one.

Two kinds of request have a further allowance of their own. These belong to your account, not the token, and are shared with the same actions in the app:

Request Allowance
POST /images 50 images an hour, shared with every image you upload in the app: images in the editor, avatars and logos.
POST /pages/{slug}/snapshots 10 a minute, shared with taking and restoring snapshots in the app.

Responses within the per-token limit carry headers showing your allowance:

http
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117

Going over either limit gets 429 Too Many Requests with a Retry-After header giving the number of seconds to wait:

json
{
  "message": "Too Many Attempts."
}

The per-IP limit answers "message": "Too many requests. Slow down and try again shortly.".

Tip

When you get a 429, wait for the number of seconds in Retry-After before retrying, rather than retrying immediately.

Keeping tokens safe

  • Give each integration its own token, so you can revoke one without breaking the others.
  • Use Read only unless the integration needs to write.
  • Set an expiry where you can, and revoke tokens you no longer use.
  • Never commit a token to a repository. Store it in your platform's secret store or an environment variable.