# 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. - [Going live](https://developers.grofomo.com/going-live.md): The launch order that works, whatever the site is built with. ## 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. - [Photo gallery](https://developers.grofomo.com/reference/events/gallery.md): Curated photos the organiser picked for their website. - [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. - [Quote a cart](https://developers.grofomo.com/reference/tickets/quote.md): Price a cart and check a promo code, without holding anything. - [Reserve tickets](https://developers.grofomo.com/reference/tickets/reserve.md): Hold the cart for 15 minutes and create the order. - [Buyer details and consent](https://developers.grofomo.com/reference/tickets/details.md): Attach the buyer's email, name, phone and marketing consent to a reserved order. - [Start payment](https://developers.grofomo.com/reference/tickets/pay.md): Get the Stripe client secret to take the card on your page. - [Complete a free order](https://developers.grofomo.com/reference/tickets/complete-free.md): Issue the tickets for a zero-total order, with no card step. - [Order status](https://developers.grofomo.com/reference/tickets/order.md): Where the order is, its lines and totals, and what the buyer earned. - [Funnel beacon](https://developers.grofomo.com/reference/tickets/funnel.md): Tell the organiser's sales report that a visitor viewed or selected tickets. - [Merch catalogue](https://developers.grofomo.com/reference/events/merch.md): Garments, colours, sizes, print zones and prices. - [Ambassador programme](https://developers.grofomo.com/reference/events/ambassadors.md): The reward tiers, rules and partner form status for an event's Ambassador page. ## 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. - [Prelaunch form](https://developers.grofomo.com/reference/prelaunch/form.md): The published prelaunch registration form, so you can render it yourself. - [Prelaunch registration](https://developers.grofomo.com/reference/prelaunch/register.md): Register interest in the event from your own prelaunch form. - [Prelaunch verification](https://developers.grofomo.com/reference/prelaunch/verify.md): Type back the SMS code, or ask for the email or code again. - [Apply to be a partner](https://developers.grofomo.com/reference/events/ambassadors-apply.md): Send a promoter's application for a cash rate into the organiser's review queue. - [Carer tickets](https://developers.grofomo.com/reference/events/carer-tickets.md): Whether the event offers free carer tickets, and the words the application form needs. - [Match a carer to an order](https://developers.grofomo.com/reference/events/carer-match.md): Find the attendee's ticket from the order number and their email or surname. - [Upload carer proof](https://developers.grofomo.com/reference/events/carer-proof-upload.md): Somewhere to put the document that shows the applicant is a carer. - [Apply for a carer ticket](https://developers.grofomo.com/reference/events/carer-apply.md): Send a carer's application into the organiser's review queue. - [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): Drop checkout.js into your page, or run the purchase flow yourself. - [Ambassador page](https://developers.grofomo.com/ambassadors.md): Show the reward tiers, rules and partner form live on your own site with ambassadors.js. - [For AI agents](https://developers.grofomo.com/ai.md): Machine-readable entry points: llms.txt, markdown twins and an OpenAPI document. - [MCP server](https://developers.grofomo.com/mcp.md): Add the public event directory to Claude, ChatGPT or Cursor as a tool. - [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.