# Caesura

> Plan the trip together. Caesura is a trip planner built on playbooks: real days from real trips, saved by the people who lived them.

Caesura is collaborative trip planning for a group going somewhere together: one shared trip of days and stops, with costs, a notebook and the whole change history, and playbooks — days worth repeating, saved by the people who lived them — to borrow from. Anyone can sign up.

It has a public REST API under `/api/v1`. A token acts as the person who minted it, holds only the scopes it was given, and can never do more than that person can. Send it on every request as `Authorization: Bearer tc_...`. Tokens are on the Premium plan; a person mints one in Account → Security → API tokens → New token, and the secret is shown once.

## API

- [API catalog](https://0.0.0.0:3000/.well-known/api-catalog): RFC 9727 linkset; its `service-desc` is the OpenAPI document. No token
- [OpenAPI document](https://0.0.0.0:3000/api/v1/openapi): OpenAPI 3.0, generated from the route declarations — every endpoint, its scope, request and response. Paths are relative to `/api`. No token
- [API index](https://0.0.0.0:3000/api/v1): a small JSON pointer to the OpenAPI document and how to authenticate. No token
- [API reference](https://0.0.0.0:3000/developers/reference): the OpenAPI document rendered for a person to read
- [MCP connector](https://0.0.0.0:3000/api/mcp): Streamable HTTP MCP server for Claude and other MCP clients. Signs in with OAuth 2.1 as the person who allows it (Premium); discovery at `/.well-known/oauth-protected-resource/api/mcp`

## Getting a token

- [Developers](https://0.0.0.0:3000/developers): how to sign up, sign in, and mint a token — scopes, lifetime, and where the secret is shown

## Scopes

- [trips:read](https://0.0.0.0:3000/developers#scopes): See your trips, their days and stops, costs, history, and existing share links.
- [trips:write](https://0.0.0.0:3000/developers#scopes): Create, change and delete trips, days and stops; undo, redo and revert.
- [notebook:read](https://0.0.0.0:3000/developers#scopes): Read the Notebook pages on a trip.
- [notebook:write](https://0.0.0.0:3000/developers#scopes): Create, change and delete the Notebook pages on a trip.
- [library:read](https://0.0.0.0:3000/developers#scopes): Read your saved-days library and your Playbooks (a Playbook is a view over saved days), and browse published Playbooks.
- [library:write](https://0.0.0.0:3000/developers#scopes): Create, edit, import and delete saved days and Playbooks, and publish or unpublish them to Discover.
- [sharing:write](https://0.0.0.0:3000/developers#scopes): Invite people to a trip and revoke invites, and create or revoke share links.
- [account:read](https://0.0.0.0:3000/developers#scopes): See who you are and what plan you hold.
- [places:read](https://0.0.0.0:3000/developers#scopes): 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.

## Optional

- [Caesura](https://0.0.0.0:3000/): the landing page
- [Example trips](https://0.0.0.0:3000/demo): real trip boards, read-only, no account needed