The Caesura API
Caesura is a trip planner for a group going somewhere together. The REST API under /api/v1 reads and changes your own trips, days, stops, notebook pages and playbooks, as you.
A token acts as the person who made it. It holds only the scopes you give it, it always expires, and it can never do more than you can.
From nothing to a first call
Create your account
Go to Create an account and continue with Google — anyone can sign up. If somebody sent you an invite code, paste it into Invite code so they get the credit; otherwise leave it empty. Already have an account? Sign in.
Be on the Premium plan
API tokens are on the Premium plan. On any other plan the API tokens section shows an upgrade prompt instead of the form, and a token stops working if its owner’s plan no longer includes the API — restarting the subscription turns it back on.
Make a token
Account → Profile → API tokens → New token. Name it, tick what it may do (the scopes below), choose all your trips or only some, and pick how long it lives: 30 days, 90 days or a year. Every token expires.
The secret is shown once. Copy it then — nothing can show it again. Lose it and you revoke it and make another. Tokens start with tc_.
Discover, then call
Start from /.well-known/api-catalog: its service-desc is /api/v1/openapi, which describes every endpoint, its scope and its shapes. Its paths begin /v1/ and are served under /api. Send the token on every request:
curl https://<host>/api/v1/account \ -H "Authorization: Bearer tc_..."
Collections take ?limit= (1–200) and an opaque ?cursor=; read nextCursor until it is null. Every error is { "error": { "code", "message", "details" } } — read the code.
Scopes
Nothing implies anything else: trips:write does not include trips:read. Ask for both if you need both.
| Scope | What a token holding it may do |
|---|---|
| trips:read | See your trips, their days and stops, costs, history, and existing share links. |
| trips:write | Create, change and delete trips, days and stops; undo, redo and revert. |
| notebook:read | Read the Notebook pages on a trip. |
| notebook:write | Create, change and delete the Notebook pages on a trip. |
| library:read | Read your saved-days library and your Playbooks (a Playbook is a view over saved days), and browse published Playbooks. |
| library:write | Create, edit, import and delete saved days and Playbooks, and publish or unpublish them to Discover. |
| sharing:write | Invite people to a trip and revoke invites, and create or revoke share links. |
| account:read | See who you are and what plan you hold. |
| places:read | Look up real places by name, outside any trip. Every search counts against your daily geocoding allowance (the one the app's own place search uses) and a daily budget shared by every account; one token may make at most 100 a day. |
The reference
- API reference
The OpenAPI document, drawn for reading, with a request runner.
- /api/v1/openapi
The OpenAPI 3.0 document itself. No token.
- /.well-known/api-catalog
RFC 9727 linkset pointing at both of the above. No token.
- /llms.txt
This page's summary, for a model to read first.