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, press Have an invite code? and paste it there so they get the credit. 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 → Security → 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, because 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.
Connect Claude
Claude can plan in Caesura as you: read your trips and your library, write and publish playbooks, set and frame the cover photo of a playbook or a trip, and search for places. In Claude, add a custom connector with this URL:
https://caesura.today/api/mcp
There is no token to copy. Claude sends you to Caesura to sign in and allow it, which needs the Premium plan, as API tokens do. The page you allow it on lists what it asks for in the words of the scopes below, and you can untick any of them. Notebook access starts unticked.
Every app you connect is listed in Account → Security → Connected apps, where Disconnect stops it at once.
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. Reading or listing any of your trips needs this scope; without it, your trips stay hidden, though public Discover playbooks can still be browsed. |
| trips:write | Create, change and delete trips, days and stops; undo, redo and revert. Creating or changing a trip needs this scope; without it, trips can only be read. |
| notebook:read | Read the Notebook pages on a trip. Opening a Notebook page needs this scope; without it, trip tasks still work but Notebook content stays hidden. |
| notebook:write | Create, change and delete the Notebook pages on a trip. Writing a Notebook page needs this scope; without it, Notebook pages can only be read. |
| library:read | Read your saved-days library and your Playbooks (a Playbook is a view over saved days), and browse published Playbooks. Reading your saved days or your Playbooks needs this scope; without it, trip tasks still work, and only published Playbooks can be browsed. |
| library:write | Create, edit, import and delete saved days and Playbooks, and publish or unpublish them to Discover. Changing the library needs this scope; without it, saved days and Playbooks can only be read. |
| sharing:write | Invite people to a trip and revoke invites, and create or revoke share links. Inviting someone or sharing a trip needs this scope; without it, trips can be managed but not shared. |
| account:read | See who you are and what plan you hold. Checking your account or plan needs this scope; without it, trip and library tasks still work. |
| 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. Finding a place by name needs this scope; without it, stops can still be added with coordinates, but not found by name. |
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.