> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fesutibaru.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Read the schedule, then propose a change.

Every festival has its own address: `https://<festival>.fesutibaru.com/api/v1`. The examples use `demo`.

## 1. Sign in

The full API is used signed in as a person, with OAuth. An agent that supports it finds the sign-in on its own: a request without a sign-in is answered `401` with a `WWW-Authenticate` header pointing at `/.well-known/oauth-protected-resource`, which names the sign-in server and the two permissions:

| Permission | Lets the agent |
| - | - |
| `planner:read` | Read the festival records the person can see |
| `planner:propose` | Propose changes for the person to accept |

The person signs in to Planner and agrees. From then on the agent sends `Authorization: Bearer <token>`.

## 2. Read

```bash theme={null}
curl https://demo.fesutibaru.com/api/v1/events?per_page=5&include=venue,authors \
  -H "Authorization: Bearer $TOKEN"
```

Events, travel and stays belong to an edition (a year). Reads default to the current edition; add `?edition=2026` for another.

```bash theme={null}
curl "https://demo.fesutibaru.com/api/v1/schedule?date=2027-08-21" \
  -H "Authorization: Bearer $TOKEN"
```

The schedule lists one day by venue, with clashes: events too close together in a venue, and anyone booked onto two events at once.

## 3. Propose a change

```bash theme={null}
curl -X POST https://demo.fesutibaru.com/api/v1/proposals \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rename-opening-1" \
  -d '{
    "title": "Rename the opening event",
    "note": "Asked to match the printed programme.",
    "changes": [
      { "op": "update", "table": "event", "id": "<event id>", "data": { "title": "Grand Opening" } }
    ]
  }'
```

The reply is `201` with the proposal's id. The person now sees it in their inbox, with the field's value now and what you proposed, and accepts or rejects it. Check what happened with `GET /api/v1/proposals/<id>`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.