# Grofomo API

> Build an event website on live festival data. Read-only JSON feeds for an event's published lineup, FAQs, news, announcements, ticket availability and merch, plus light writes for mailing-list signups and forms.

Three things to get right before writing any code:

- Send `?surface=web` on every request. It defaults to the mobile-app surface, which is gated on a different visibility setting, so omitting it can return `404` for a live event.
- Authenticate with an `X-Grofomo-Key` header. Publishable keys (`pk_live_…`) are safe in browser code; secret keys (`sk_live_…`) are server-only. Choose by where the code runs.
- Every response is `{ "apiVersion": 1, "data": … }`, or `{ "apiVersion": 1, "error": { "code", "message" } }` on failure. Branch on `code`, never on `message`.

Every page below is also available as HTML at the same path without `.md`.

## Start here

- [Overview](https://developers.grofomo.com/index.md): What this API is, and what you can build with it.
- [Quickstart](https://developers.grofomo.com/quickstart.md): Your first request, and a working lineup page in about ten minutes.
- [For organisers](https://developers.grofomo.com/organisers.md): Give your web developer a key, and choose which domains may use it.

## Concepts

- [Authentication](https://developers.grofomo.com/concepts/authentication.md): Publishable and secret keys, where each one belongs, and the two failure codes.
- [Surfaces](https://developers.grofomo.com/concepts/surfaces.md): Why every website request needs `?surface=web`, and what happens without it.
- [Responses and errors](https://developers.grofomo.com/concepts/responses.md): The response envelope, the error shape, and how to tell them apart.
- [Caching and rate limits](https://developers.grofomo.com/concepts/caching.md): How long each feed is cached, and how to poll cheaply.
- [CORS and allowed domains](https://developers.grofomo.com/concepts/cors.md): What the domain allowlist does, and the thing it deliberately does not do.

## API reference

- [All endpoints](https://developers.grofomo.com/reference.md): Index of every documented endpoint.

## Event

- [Event detail](https://developers.grofomo.com/reference/events/detail.md): Core event info: dates, venue, stages and brand.
- [Content version](https://developers.grofomo.com/reference/events/version.md): A cheap probe for "has anything changed?".
- [Organiser profile](https://developers.grofomo.com/reference/organisers/detail.md): Organiser bio, branding and their upcoming events.

## Lineup

- [Event lineup](https://developers.grofomo.com/reference/events/lineup.md): Published lineup: artists, stages and set times.
- [Artist detail](https://developers.grofomo.com/reference/events/artist.md): Full artist profile, plus their sets at this event.

## Content

- [Event FAQs](https://developers.grofomo.com/reference/events/faq.md): Categorised FAQs, with answers pre-rendered to HTML.
- [News index](https://developers.grofomo.com/reference/events/news.md): Published news articles, newest first.
- [News article](https://developers.grofomo.com/reference/events/news-article.md): A single published article, with its full body.
- [Announcements](https://developers.grofomo.com/reference/events/broadcasts.md): Announcements the organiser has sent, newest first.

## Tickets & merch

- [Ticket availability](https://developers.grofomo.com/reference/events/tickets.md): Visible ticket types and release tiers, with live availability.
- [Merch catalogue](https://developers.grofomo.com/reference/events/merch.md): Garments, colours, sizes, print zones and prices.

## Forms & signups

- [Mailing-list signup](https://developers.grofomo.com/reference/events/subscribe.md): Add an email to the organiser's mailing list from your own form.
- [Form definition](https://developers.grofomo.com/reference/forms/definition.md): The fields of a published form, so you can render it yourself.
- [Submit a form](https://developers.grofomo.com/reference/forms/submit.md): Send answers back for a published form.

## Discovery

- [Event search](https://developers.grofomo.com/reference/events/search.md): Search public events across all organisers.

## More

- [Webhooks](https://developers.grofomo.com/webhooks.md): Receive ticket sales and signups on your own endpoint, with signature verification.
- [Selling tickets](https://developers.grofomo.com/checkout.md): How to sell from your own site today, and the embed that is coming.
- [For AI agents](https://developers.grofomo.com/ai.md): Machine-readable entry points: llms.txt, markdown twins and an OpenAPI document.
- [Changelog](https://developers.grofomo.com/changelog.md): What changed, and how versioning works.

## Optional

- [https://developers.grofomo.com/llms-full.txt](https://developers.grofomo.com/llms-full.txt): every page above, concatenated into one file.
- [https://developers.grofomo.com/openapi.json](https://developers.grofomo.com/openapi.json): OpenAPI 3.1 for every documented endpoint.