Read in this order
GET /editions: which edition is current, and its dates. Everything else defaults to it.GET /schedule?date=YYYY-MM-DD: a day by venue, with clashes already worked out.- The records the task needs:
/events,/people,/books,/travel,/stays… with?q=to search and?include=for related records (/events/<id>?include=venue,authors,chairs). GET /events/<id>(or the record you’ll change) just before proposing: propose against what’s there now.
/api/v1/openapi.json on the festival’s address.
Proposing
- One task, one proposal: a clear
title, and anotesaying what you were asked and anything the person should check. - Change only what you were asked to. Send only the fields that change.
- Always send an
Idempotency-Key, so a retry can’t propose twice. - If you get
422, readproblems: each refused change by position, with why. Fix those and send the proposal again. - Afterwards, tell the person what you proposed and that it’s in their inbox. Later,
GET /proposals/<id>tells you what they accepted.
Mistakes to avoid
- Time zones.
start_timeis an instant (…+00:00). When you talk to people, usestart_time_local: the festival’s own clock. When you propose a time, send an instant with its offset. - Editions. Events, travel and stays belong to one edition. A record from last year isn’t in this year’s lists: use
?edition=2026to read it, and propose against the current edition unless asked otherwise. - People and roles.
role_type: participantmeans an author, chair or other speaker, not “anyone involved”. Who is on an event, and how, is in the junctions: authors, chairs, interviewers, intro / wrap, staff. - Names. Two people can share a name. Match by
emailor id, and say in your note if you weren’t sure. - Deleting. A person or book used in another edition is only taken out of this one. Prefer the smallest change that does the job: unlinking someone from an event is usually what’s wanted, not deleting them.
- Custom fields are
cf_<field_key>;metadatacan’t be proposed.