# Caesura

> Put the best day on repeat. 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 → Profile → API tokens → New token, and the secret is shown once.

## API

- [API catalog](https://caesura.today/.well-known/api-catalog): RFC 9727 linkset; its `service-desc` is the OpenAPI document. No token
- [OpenAPI document](https://caesura.today/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://caesura.today/api/v1): a small JSON pointer to the OpenAPI document and how to authenticate. No token
- [API reference](https://caesura.today/developers/reference): the OpenAPI document rendered for a person to read

## Getting a token

- [Developers](https://caesura.today/developers): how a person gets in (an invite code or a trip invite link), signs in, and mints a token — scopes, lifetime, and where the secret is shown

## Scopes

- [trips:read](https://caesura.today/developers#scopes): See your trips, their days and stops, costs, history, and existing share links.
- [trips:write](https://caesura.today/developers#scopes): Create, change and delete trips, days and stops; undo, redo and revert.
- [notebook:read](https://caesura.today/developers#scopes): Read the Notebook pages on a trip.
- [notebook:write](https://caesura.today/developers#scopes): Create, change and delete the Notebook pages on a trip.
- [library:read](https://caesura.today/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://caesura.today/developers#scopes): Create, edit, import and delete saved days and Playbooks, and publish or unpublish them to Discover.
- [sharing:write](https://caesura.today/developers#scopes): Invite people to a trip and revoke invites, and create or revoke share links.
- [account:read](https://caesura.today/developers#scopes): See who you are and what plan you hold.
- [places:read](https://caesura.today/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://caesura.today/): the landing page
- [An example trip](https://caesura.today/demo): a real trip board, read-only, no account needed