# 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.

---

<!-- source: https://developers.grofomo.com/ -->

# Grofomo API

Build an event website on live festival data.

Organisers run their festival in Grofomo — lineup, stages, set times, FAQs, news, tickets, merch. This API hands you that same data as JSON, already published and already public, so the site you build stays right without anyone re-typing a running order into a CMS.

## One request

```bash
curl -sS \
  -H 'X-Grofomo-Key: pk_live_YOUR_PUBLISHABLE_KEY' \
  'https://api.grofomo.com/v1/events/summer-fest/lineup?surface=web'
```

## Where to go next

- [Quickstart](/quickstart.md): Your first request, and a working lineup page in about ten minutes.
- [For organisers](/organisers.md): Give your web developer a key, and choose which domains may use it.
- [Authentication](/concepts/authentication.md): Publishable and secret keys, where each one belongs, and the two failure codes.
- [Surfaces](/concepts/surfaces.md): Why every website request needs `?surface=web`, and what happens without it.
- [Responses and errors](/concepts/responses.md): The response envelope, the error shape, and how to tell them apart.
- [Caching and rate limits](/concepts/caching.md): How long each feed is cached, and how to poll cheaply.
- [CORS and allowed domains](/concepts/cors.md): What the domain allowlist does, and the thing it deliberately does not do.
- [Webhooks](/webhooks.md): Receive ticket sales and signups on your own endpoint, with signature verification.
- [Selling tickets](/checkout.md): How to sell from your own site today, and the embed that is coming.
- [For AI agents](/ai.md): Machine-readable entry points: llms.txt, markdown twins and an OpenAPI document.
- [Changelog](/changelog.md): What changed, and how versioning works.
- [API reference](/reference.md): every documented endpoint, grouped.

---

<!-- source: https://developers.grofomo.com/quickstart -->

# Quickstart

Your first request, and a working lineup page in about ten minutes.

You need two things before you start: an **event slug** and a **publishable key**. Both come from the organiser — if you are the organiser, see [For organisers](/organisers).

The slug is the last part of the event's Grofomo link. For `grfm.to/e/summer-fest` the slug is `summer-fest`.

## Your first request

```bash
curl -sS \
  -H 'X-Grofomo-Key: pk_live_YOUR_PUBLISHABLE_KEY' \
  'https://api.grofomo.com/v1/events/summer-fest/lineup?surface=web'
```

Two details in that command do real work:

- **`X-Grofomo-Key`** identifies the organisation. Most organisers now require it; some older ones do not yet. Send it either way — see [Authentication](/concepts/authentication).
- **`?surface=web`** tells the API you are a website. Leave it off and you get the mobile-app surface, which is gated on a *different* visibility setting, so a perfectly live event can answer `404`. This trips up nearly everyone once. See [Surfaces](/concepts/surfaces).

## What comes back

Every response is wrapped in the same envelope:

```json
{
  "apiVersion": 1,
  "data": { "eventSlug": "summer-fest", "slots": [] }
}
```

Errors use the same envelope with `error` instead of `data`:

```json
{
  "apiVersion": 1,
  "error": { "code": "unauthorized", "message": "A valid API key is required" }
}
```

So the check is always: look at `res.ok`, then read `body.data` or `body.error`. Nothing else varies.

## A lineup page

This is a complete Next.js server component. It runs on your server, so it uses the **secret** key and lets the framework cache the result — a busy festival page then costs you one API call a minute, not one per visitor.

```javascript
async function getLineup() {
  const res = await fetch(
    'https://api.grofomo.com/v1/events/summer-fest/lineup?surface=web',
    {
      headers: { 'X-Grofomo-Key': process.env.GROFOMO_SECRET_KEY },
      next: { revalidate: 60 },
    },
  );

  const body = await res.json();
  if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
  return body.data;
}

export default async function LineupPage() {
  const lineup = await getLineup();

  return (
    <ol>
      {lineup.slots.map((slot) => (
        <li key={slot.id}>
          <strong>{slot.artist?.name ?? slot.placeholderLabel}</strong>
          {' — '}
          {slot.stage} · {slot.day} · {slot.startTime}
        </li>
      ))}
    </ol>
  );
}
```

Note `slot.artist?.name ?? slot.placeholderLabel`. An unannounced set has no artist yet, and rendering "undefined" on a public festival page is a bad afternoon.

## Free SEO

On the web surface the lineup, FAQ and news responses each carry a ready-made schema.org block in `schemaOrg`. Drop it into the page and search engines can read your running order without you modelling any of it:

```javascript
<script
  type="application/ld+json"
  dangerouslySetInnerHTML={{ __html: JSON.stringify(lineup.schemaOrg) }}
/>
```

## What to build next

- [Event detail](/reference/events/detail) — dates, venue, stages and brand colours. Usually the first call a site makes.
- [FAQs](/reference/events/faq) — answers arrive as sanitised HTML, ready to inject.
- [News](/reference/events/news) — announcement posts, newest first.
- [Ticket availability](/reference/events/tickets) — live prices and what is sold out.
- [Content version](/reference/events/version) — a cheap probe so you can poll for changes without re-pulling the lineup.

---

<!-- source: https://developers.grofomo.com/organisers -->

# For organisers

Give your web developer a key, and choose which domains may use it.

Your event data belongs to you. This page is how you hand a web developer the parts they need — and nothing else.

Everything here lives in **EventOS → Settings → Developers**.

## Give your developer a key

Two kinds of key exist, and the difference matters:

| | Publishable (`pk_live_…`) | Secret (`sk_live_…`) |
|---|---|---|
| Where it belongs | A website's front-end code | A server, or a build pipeline |
| Visible to the public? | Yes, by design | Never |
| Shown to you | Any time | Once, at creation |

**Hand over a publishable key.** It is meant to be readable in your website's page source: it identifies your organisation, lets us rate-limit and attribute traffic, and can be revoked the moment you want it to stop working. What it is *not* is a password. Anyone who views source can copy it — which is exactly why it can only ever read the data you have already chosen to publish.

A secret key is for a developer whose site fetches on their server. Treat it like a password.

## Choose which domains may use it

Add your developer's domains to **Allowed domains** — the live site, and their staging URL if they have one. Entries can be:

- `https://www.yourfestival.com` — that exact site
- `https://*.yourfestival.com` — any subdomain of it
- `*` — any site at all

This stops someone lifting your publishable key out of your page source and using it to power *their* site's festival listing. It is a browser-level control, so it does not affect calls made from a server.

## Two access modes

Under **Public API access** you have two settings:

- **Open** — the feeds answer without a key. This is where every organisation created before we introduced keys still sits, so nothing broke.
- **Key required** — every request must carry one of your keys. **New organisations start here**, with a publishable key already minted for you.

If you are on **Open** and want to move: mint a key, give it to whoever builds your site, confirm their site works with it, *then* switch. The order matters — flipping first will break a live site mid-sentence.

One side effect worth knowing: once you require a key, your feeds stop being cached on our shared CDN (a cached copy could otherwise be replayed to someone without a key). Your site will do slightly more work; your developer can cache on their side, and [we explain how](/concepts/caching).

## What to send your developer

Copy this:

```text
Event slug:      summer-fest
API base:        https://api.grofomo.com
Publishable key: pk_live_… (from Settings → Developers)
Docs:            https://developers.grofomo.com
```

## Turning a key off

Revoke it in the same place. Revocation is immediate — the next request using it gets a `401`. Mint the replacement, get it deployed, then revoke the old one, so there is no gap.

---

<!-- source: https://developers.grofomo.com/concepts/authentication -->

# Authentication

Publishable and secret keys, where each one belongs, and the two failure codes.

Requests are authenticated with a key in the `X-Grofomo-Key` header.

```bash
curl -H 'X-Grofomo-Key: pk_live_YOUR_PUBLISHABLE_KEY' \
  'https://api.grofomo.com/v1/events/summer-fest/lineup?surface=web'
```

## Two kinds of key

**Publishable — `pk_live_…`**
Safe to ship in browser code. Buys you attribution, a rate-limit budget of its own, optional scoping to a single event, and instant revocation. It buys you **no secrecy at all**: it is visible in page source, and that is the design, not a leak. It can only read what the organiser has already published.

**Secret — `sk_live_…`**
For a server or a build step. Stored as a hash, so it is shown once at creation and never again. If it ends up in a browser bundle, treat it as compromised and rotate it.

Which to use is decided by *where the code runs*, not by how sensitive the data feels. Front-end fetch → publishable. Server-side fetch, static build, or a scheduled job → secret.

## Passing the key

- `X-Grofomo-Key: <key>` — the header. Always works, for both kinds.
- `?key=<key>` — the query string. **Publishable keys only.** A secret key sent this way is refused outright, because query strings end up in access logs, `Referer` headers and browser history. The refusal is deliberate: silently accepting it would leak the key while looking like it worked.

## When a key is required

Each organisation is in one of two modes:

- **`open`** — requests without a key are answered. Organisations that predate keys are still here.
- **`key_required`** — a valid key is mandatory. Every new organisation starts here.

You cannot tell which mode an organisation is in from the outside, and you should not try. **Always send a key.** In `open` mode it is accepted and ignored; the day the organiser switches, your integration is already correct.

## Failures

**`401 unauthorized`** — no key was sent and one is required, or the key is invalid, revoked, belongs to a different organisation, or is scoped to a different event. All of these return the same code on purpose: distinguishing them would let anyone probe which keys exist.

**`403 origin_not_allowed`** — the browser's `Origin` is not on the organiser's allowed-domains list. Only browsers can hit this; a server sends no `Origin` header. See [CORS and allowed domains](/concepts/cors).

Neither is retryable. Both mean a configuration conversation with the organiser, not a backoff loop.

## Rotation

Keys do not expire. When one needs replacing: mint the new key, deploy it, confirm traffic has moved, then revoke the old one. Revocation takes effect on the next request, so revoking first means downtime.

---

<!-- source: https://developers.grofomo.com/concepts/surfaces -->

# Surfaces

Why every website request needs `?surface=web`, and what happens without it.

Almost every endpoint takes a `surface` parameter. Websites must send `?surface=web`.

```bash
https://api.grofomo.com/v1/events/summer-fest/lineup?surface=web
```

## Why it exists

The same feeds serve two very different consumers: the Grofomo mobile app, and websites like yours. Organisers control those independently — an event can be live in the app while its website content is still being prepared, or the reverse. `surface` says which of those two visibility settings applies to your request.

## Why omitting it bites

**The parameter defaults to `app`, not `web`.** So a request without it is not "unscoped", it is a mobile-app request. If the organiser has published the event to the web but not to the app, that request gets `404 not_found` — for an event you can see is live, with a key you know is valid, at a URL you know is right.

If a call 404s and you cannot see why, check for `?surface=web` before checking anything else.

## Where it is not needed

A few endpoints are web-only by nature and ignore the parameter — the news feeds, for instance, always serve web content. Each reference page states whether `surface` is required. Sending it where it is not needed is harmless, so the simplest correct habit is to send it every time.

---

<!-- source: https://developers.grofomo.com/concepts/responses -->

# Responses and errors

The response envelope, the error shape, and how to tell them apart.

Every endpoint — success or failure — returns the same envelope.

## Success

```json
{
  "apiVersion": 1,
  "data": { }
}
```

## Failure

```json
{
  "apiVersion": 1,
  "error": {
    "code": "not_found",
    "message": "Event not found"
  }
}
```

`code` is a stable, machine-readable string — branch on it. `message` is written for a developer reading a log, and its wording may change; never parse it.

## Handling both

Because the shape is uniform, one helper covers the whole API:

```javascript
async function grofomo(path) {
  const res = await fetch(`https://api.grofomo.com${path}`, {
    headers: { 'X-Grofomo-Key': process.env.GROFOMO_SECRET_KEY },
  });

  const body = await res.json();
  if (!res.ok) {
    throw new Error(`${body.error.code}: ${body.error.message}`);
  }
  return body.data;
}
```

Read the body once. `res.json()` consumes the stream, so calling it in both branches throws on the second call.

## Status codes

| Status | Code | What it means |
|---|---|---|
| 200 | — | Fine. |
| 400 | `bad_request` | The request body or a parameter did not validate. |
| 400 | `turnstile_failed` | The bot-check token was missing or invalid. |
| 401 | `unauthorized` | No key, or a key that is invalid, revoked, or out of scope. |
| 403 | `origin_not_allowed` | The browser's domain is not on the organiser's allowlist. |
| 404 | `not_found` | No such event on this surface. Check `?surface=web`. |
| 429 | — | Rate limited. Honour `Retry-After`. |
| 500 | `fetch_failed` | Our fault. Safe to retry. |

Retry `429` and `5xx`. Never retry `401`, `403` or `404` — they mean something is configured wrong, and a retry loop just turns one problem into a traffic problem.

## Versioning

`apiVersion` is `1` and will stay `1` while changes are additive. New fields can appear at any time, so **ignore fields you do not recognise** rather than validating strictly against a fixed shape.

A breaking change would arrive as a new version, announced in the [changelog](/changelog) before it lands.

---

<!-- source: https://developers.grofomo.com/concepts/caching -->

# Caching and rate limits

How long each feed is cached, and how to poll cheaply.

## How long responses live

Most read endpoints are cached at our edge for 60 seconds, with a 5-minute stale-while-revalidate window:

```text
Cache-Control: public, s-maxage=60, stale-while-revalidate=300
```

So a lineup publish can take up to a minute to appear on your site. That is the trade for a feed that survives an on-sale.

Some endpoints differ and say so on their own page — [content version](/reference/events/version) is 15 seconds, and anything that changes by the second (merch stock, announcements, any write) is `no-store`.

## The one that surprises people

**When an organiser is in `key_required` mode, their responses are `no-store`.** Not slower — uncached entirely.

The reason is that a shared CDN keys on URL, not on credentials. If a key-holder's `200` were cached, the next anonymous caller would be served that cached copy and the key gate would be worth nothing.

The practical consequence: your own caching does the work. In Next.js, `next: { revalidate: 60 }`; anywhere else, a small in-process cache or a scheduled build. This is why the [quickstart](/quickstart) fetches on the server rather than from the browser — one cached server fetch serves every visitor, and a per-visitor browser fetch cannot be cached at all.

## Polling without the cost

Do not poll the lineup. Poll the version probe instead — it is tiny, and it moves whenever the event or its lineup is edited:

```javascript
const { data } = await fetch(
  'https://api.grofomo.com/v1/events/summer-fest/version',
).then((r) => r.json());

if (data.scheduleVersion !== lastSeenVersion) {
  // Only now pull the heavy feeds.
}
```

## Rate limits

Read endpoints allow roughly 60 requests per minute; writes (signups, form submissions) roughly 30. Over the limit you get `429` with a `Retry-After` header.

Two honest caveats:

- **These are guidance, not a contract.** The limiter is per-server-instance, so the effective ceiling in production is higher and not exactly predictable. Do not design something that depends on the precise number.
- **A key gets its own budget.** Without one, you share a bucket with everyone on your IP — which, behind a corporate proxy or a serverless egress pool, may not be only you.

If you cache as described above, you will not come near any of this.

---

<!-- source: https://developers.grofomo.com/concepts/cors -->

# CORS and allowed domains

What the domain allowlist does, and the thing it deliberately does not do.

Organisers keep a list of domains allowed to call their feeds from a browser. A request whose `Origin` is not on that list is refused with `403 origin_not_allowed`.

## Entries

- `https://www.yourfestival.com` — exact origin
- `https://*.yourfestival.com` — any subdomain, same scheme
- `*` — any origin (an explicit opt-in)

The header we echo back is always the concrete request origin, never the pattern, so credential-less cross-origin reads work in every browser.

## What it does

It stops a lifted publishable key from working somewhere else. Your key is in your page source by design; the allowlist means someone who copies it still cannot use it to power their own site's festival listing from a browser.

## What it does not do

**CORS is not access control.** It is a rule browsers agree to follow. `curl` does not follow it, and neither does anything else outside a browser:

```bash
# No Origin header, so no CORS decision to make.
curl 'https://api.grofomo.com/v1/events/summer-fest/lineup?surface=web'
```

That is not a hole — it is what CORS is. It is also the reason API keys exist: the allowlist is the second layer, and the key is the first. An organiser who wants their feeds genuinely closed sets `key_required`; the allowlist alone would only inconvenience browsers.

## Server-side calls

A server sends no `Origin` header, so the allowlist never applies to it. If your site fetches during build or render, allowed domains are irrelevant to you — only your key matters.

## Preflight

`OPTIONS` preflight requests are never gated. A browser must be able to complete the handshake before it can send the credential the handshake is about.

---

<!-- source: https://developers.grofomo.com/reference -->

# API reference

Every documented endpoint on the Grofomo public API, grouped by resource.

## Event

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

## Lineup

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

## Content

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

## Tickets & merch

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

## Forms & signups

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

## Discovery

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

## Deliberately not documented

The mobile app's device endpoints, the door scanner's check-in surface, wallet passes, ticket capability links and the raw checkout flow (quote, reserve, pay) are internal. Selling tickets from your own site will arrive as a drop-in embed rather than a documented write API. These are omissions by decision, not gaps.

---

<!-- source: https://developers.grofomo.com/reference/events/lineup -->

# Event lineup

`GET /v1/events/{slug}/lineup`

The published lineup for an event — every set, with its stage, start and end time.

Slots arrive as one flat `slots` array rather than pre-grouped, so you can group by `day`, by `stage`, or by both, depending on how your page is laid out. A back-to-back set carries its full roster in `artists`, with the lead act repeated in `artist`; an unannounced slot has `artist: null` and a `placeholderLabel` to render instead.

This reads the organiser's **published** snapshot, never their working draft. A lineup being rearranged in the console will not appear here until it is published, which is what makes it safe to render straight onto a public page.

On the web surface the response also carries `schemaOrg`: a ready-made `MusicEvent` JSON-LD block you can drop into a `<script type="application/ld+json">` tag for rich search results.

> **Send `?surface=web`.** Omitted, the request is treated as coming from the mobile app, which is gated on a different visibility setting — so a live event can return `404 not_found`.

## Request

### curl

```bash
curl -sS \
  -H 'X-Grofomo-Key: pk_live_YOUR_PUBLISHABLE_KEY' \
  'https://api.grofomo.com/v1/events/summer-fest/lineup?surface=web'
```

### Browser

```javascript
// Publishable keys are meant to be visible in page source. They identify
// the organisation and can be revoked — they are not a secret.
const res = await fetch('https://api.grofomo.com/v1/events/summer-fest/lineup?surface=web', {
  headers: { 'X-Grofomo-Key': 'pk_live_YOUR_PUBLISHABLE_KEY' },
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const lineup = body.data;
```

### Server

```javascript
// Server-side, so the SECRET key never reaches the browser.
const res = await fetch('https://api.grofomo.com/v1/events/summer-fest/lineup?surface=web', {
  headers: { 'X-Grofomo-Key': process.env.GROFOMO_SECRET_KEY },
  next: { revalidate: 60 },
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const lineup = body.data;
```

## Path parameters

- `slug` (string, required) — The event's URL slug. Globally unique, and fixed once the event is created. Example: `summer-fest`.

## Query parameters

- `surface` ('web', required) — Must be `web` for a website. Omit it and you get the mobile-app surface, which is gated on a different visibility setting — so a perfectly live event can return 404. Example: `web`.

## Response

```json
{
  "apiVersion": 1,
  "data": {
    "eventId": "6f1c8e2a-4b3d-4c9e-9f21-8a7d5e0b1c34",
    "eventSlug": "summer-fest",
    "surface": "web",
    "slots": [
      {
        "id": "3e5a7c9b-0d2f-4e6a-9b8c-1d3f5a7e9c02",
        "stage": "Main Stage",
        "day": "2026-07-17",
        "startTime": "21:30",
        "endTime": "23:00",
        "durationMinutes": 90,
        "billingTier": "headliner",
        "isPlaceholder": false,
        "placeholderLabel": null,
        "placeholderDescription": null,
        "featured": true,
        "createdAtIso": "2026-04-02T11:20:00.000Z",
        "artist": {
          "id": "9c7e5a3b-1f0d-4b2e-8a6c-4d2f0b8e6a13",
          "name": "Nala Vex",
          "imageUrl": "https://cdn.grofomo.com/summer-fest/artists/nala-vex.jpg",
          "genres": [
            "House",
            "Breaks"
          ],
          "hometown": "Manchester",
          "region": "England",
          "country": "GB",
          "locationLabel": "Manchester, England, United Kingdom"
        },
        "artists": [
          {
            "id": "9c7e5a3b-1f0d-4b2e-8a6c-4d2f0b8e6a13",
            "name": "Nala Vex",
            "imageUrl": "https://cdn.grofomo.com/summer-fest/artists/nala-vex.jpg",
            "genres": [
              "House",
              "Breaks"
            ],
            "hometown": "Manchester",
            "region": "England",
            "country": "GB",
            "locationLabel": "Manchester, England, United Kingdom"
          }
        ]
      },
      {
        "id": "47a9e1c3-5b8d-4f20-9c6e-3a1b7d5f9e02",
        "stage": "The Orchard",
        "day": "2026-07-18",
        "startTime": "23:00",
        "endTime": "01:00",
        "durationMinutes": 120,
        "billingTier": "special guest",
        "isPlaceholder": false,
        "placeholderLabel": null,
        "placeholderDescription": null,
        "featured": false,
        "createdAtIso": "2026-04-02T11:22:00.000Z",
        "artist": {
          "id": "d1f3b5a7-9c2e-4d80-8b6f-5a3c1e7d9b04",
          "name": "Sonny Delrey",
          "imageUrl": "https://cdn.grofomo.com/summer-fest/artists/sonny-delrey.jpg",
          "genres": [
            "Disco",
            "Italo"
          ],
          "hometown": "Bristol",
          "region": "England",
          "country": "GB",
          "locationLabel": "Bristol, England, United Kingdom"
        },
        "artists": [
          {
            "id": "d1f3b5a7-9c2e-4d80-8b6f-5a3c1e7d9b04",
            "name": "Sonny Delrey",
            "imageUrl": "https://cdn.grofomo.com/summer-fest/artists/sonny-delrey.jpg",
            "genres": [
              "Disco",
              "Italo"
            ],
            "hometown": "Bristol",
            "region": "England",
            "country": "GB",
            "locationLabel": "Bristol, England, United Kingdom"
          },
          {
            "id": "5b8d2f4a-6c0e-4a13-9d7b-8f2a6c4e0d15",
            "name": "Kiruna",
            "imageUrl": null,
            "genres": [
              "Ambient"
            ],
            "hometown": "Gothenburg",
            "region": null,
            "country": "SE",
            "locationLabel": "Gothenburg, Sweden"
          }
        ]
      },
      {
        "id": "a3c5e7d9-2b4f-4061-8e9a-7c5d3b1f9a26",
        "stage": "Main Stage",
        "day": "2026-07-19",
        "startTime": "22:00",
        "endTime": "23:30",
        "durationMinutes": 90,
        "billingTier": "headliner",
        "isPlaceholder": true,
        "placeholderLabel": "Sunday headliner",
        "placeholderDescription": "Announced 1 June.",
        "featured": true,
        "createdAtIso": "2026-04-02T11:25:00.000Z",
        "artist": null,
        "artists": []
      }
    ],
    "schemaOrg": {
      "@context": "https://schema.org",
      "@type": "MusicEvent",
      "name": "Summer Fest",
      "startDate": "2026-07-17T12:00:00+01:00",
      "endDate": "2026-07-19T23:59:00+01:00",
      "location": {
        "@type": "Place",
        "name": "Ashton Court",
        "address": "Ashton Court Estate, Bristol BS41 9JN, United Kingdom"
      },
      "performer": [
        {
          "@type": "MusicGroup",
          "name": "Nala Vex"
        },
        {
          "@type": "MusicGroup",
          "name": "Sonny Delrey"
        }
      ],
      "dateModified": "2026-06-01T09:15:00.000Z"
    },
    "lastUpdatedAt": "2026-06-01T09:15:00.000Z"
  }
}
```

### Fields

- `eventId` (uuid)
- `eventSlug` (string)
- `surface` ("app" | "web") — Echo of the surface this response was built for.
- `slots` (object[]) — Every published set, as one flat list. Group by `day` or `stage` yourself, depending on how your page is laid out.
- `slots[].id` (uuid) — Stable id for this set. Use it as a render key.
- `slots[].stage` (string | null) — Stage name. Null before a stage is assigned.
- `slots[].day` (string | null) — Festival day this set belongs to, as `YYYY-MM-DD`. An after-midnight set is attributed to the day it started, so a 01:00 slot sits under the previous date.
- `slots[].startTime` (string | null) — Local start time as `HH:MM`, in the event timezone.
- `slots[].endTime` (string | null) — Local end time as `HH:MM`, in the event timezone.
- `slots[].durationMinutes` (number | null) — Set length in minutes.
- `slots[].billingTier` (string | null) — Organiser's billing label, e.g. "headliner". Free text; do not switch on it.
- `slots[].isPlaceholder` (boolean) — True for an unannounced set. Render `placeholderLabel` instead of an artist name.
- `slots[].placeholderLabel` (string | null) — What to show in place of a name, e.g. "Sunday headliner".
- `slots[].placeholderDescription` (string | null) — Longer copy for a placeholder, e.g. when it will be announced.
- `slots[].featured` (boolean) — The organiser has flagged this set as a highlight.
- `slots[].createdAtIso` (string | null) — When the slot was first created.
- `slots[].artist` (object | null) — The lead artist, and the first entry of `artists`. Null on a placeholder slot.
- `slots[].artist.id` (uuid) — Pass this to the artist-detail endpoint for the full profile.
- `slots[].artist.name` (string) — Billed name, as the organiser wants it displayed.
- `slots[].artist.imageUrl` (string | null) — Press shot. Null when the artist has none.
- `slots[].artist.genres` (string[]) — Free-text genre tags. May be empty.
- `slots[].artist.hometown` (string | null) — City.
- `slots[].artist.region` (string | null) — State or province.
- `slots[].artist.country` (string | null) — Raw ISO 3166-1 alpha-2 code, e.g. "GB".
- `slots[].artist.locationLabel` (string | null) — Pre-formatted location for display, e.g. "Bristol, England, United Kingdom". Render this rather than joining the parts yourself.
- `slots[].artists` (object[]) — Every artist on the slot, in billing order. A back-to-back set has two or more; a normal set has exactly one; a placeholder has none.
- `slots[].artists[].id` (uuid) — Pass this to the artist-detail endpoint for the full profile.
- `slots[].artists[].name` (string) — Billed name, as the organiser wants it displayed.
- `slots[].artists[].imageUrl` (string | null) — Press shot. Null when the artist has none.
- `slots[].artists[].genres` (string[]) — Free-text genre tags. May be empty.
- `slots[].artists[].hometown` (string | null) — City.
- `slots[].artists[].region` (string | null) — State or province.
- `slots[].artists[].country` (string | null) — Raw ISO 3166-1 alpha-2 code, e.g. "GB".
- `slots[].artists[].locationLabel` (string | null) — Pre-formatted location for display, e.g. "Bristol, England, United Kingdom". Render this rather than joining the parts yourself.
- `schemaOrg` (object | null) — A ready-made schema.org `MusicEvent` block. Serialise it into a `<script type="application/ld+json">` tag. Null on the app surface.
- `lastUpdatedAt` (string | null) — Latest edit across the event and every set here. Good for a "last updated" line.

## Structured data

The response carries a ready-made `MusicEvent` JSON-LD block in `schemaOrg`. Emitted on the web surface — paste straight into a JSON-LD script tag.

## Errors

- `unauthorized` (HTTP 401) — No key was sent and the organiser requires one — or the key is invalid, revoked, belongs to another organisation, or is scoped to a different event.
- `origin_not_allowed` (HTTP 403) — Your site's domain is not on the organiser's allowed list. Browser calls only: a server sends no Origin header and is unaffected.
- `not_found` (HTTP 404) — No event with that slug is published on this surface. Check the slug, and check you sent `?surface=web`.

## Notes

- Rate limited to roughly 60 requests per minute per caller (guidance, not a contract).
- Cached for 60 seconds at the edge, so a publish can take up to a minute to appear.

---

<!-- source: https://developers.grofomo.com/reference/events/artist -->

# Artist detail

`GET /v1/events/{slug}/artists/{artistId}`

An artist's full profile — biography, image and social links — together with every set they play at this event.

Use it for an artist page linked from the lineup.

> **No key is required today, but send one anyway.** The Grofomo mobile app still calls this endpoint without a credential, so it cannot be locked down yet — it will be. A key sent now is accepted and ignored, so the integration keeps working when enforcement lands.

## Request

### curl

```bash
curl -sS \
  -H 'X-Grofomo-Key: pk_live_YOUR_PUBLISHABLE_KEY' \
  'https://api.grofomo.com/v1/events/summer-fest/artists/9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d'
```

### Browser

```javascript
// Publishable keys are meant to be visible in page source. They identify
// the organisation and can be revoked — they are not a secret.
const res = await fetch('https://api.grofomo.com/v1/events/summer-fest/artists/9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d', {
  headers: { 'X-Grofomo-Key': 'pk_live_YOUR_PUBLISHABLE_KEY' },
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const artist = body.data;
```

### Server

```javascript
// Server-side, so the SECRET key never reaches the browser.
const res = await fetch('https://api.grofomo.com/v1/events/summer-fest/artists/9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d', {
  headers: { 'X-Grofomo-Key': process.env.GROFOMO_SECRET_KEY },
  next: { revalidate: 60 },
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const artist = body.data;
```

## Path parameters

- `slug` (string, required) — The event's URL slug. Globally unique, and fixed once the event is created. Example: `summer-fest`.
- `artistId` (uuid, required) — From the lineup response. Example: `9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d`.

## Response

```json
{
  "apiVersion": 1,
  "data": {
    "id": "9c7e5a3b-1f0d-4b2e-8a6c-4d2f0b8e6a13",
    "name": "Nala Vex",
    "realName": null,
    "bioShort": "Manchester house producer with a decade of dancefloor edits behind her.",
    "bioLong": "Nala Vex has spent ten years turning warehouse rooms inside out, first through the Low Ceiling parties and later on her own Vexed imprint. Her sets move between rolling house, UK breaks and whatever record she found on Thursday.",
    "imageUrl": "https://cdn.grofomo.com/summer-fest/artists/nala-vex.jpg",
    "genres": [
      "House",
      "Breaks"
    ],
    "website": "https://nalavex.example",
    "socials": {
      "instagram": "https://instagram.com/nalavex",
      "soundcloud": "https://soundcloud.com/nalavex"
    },
    "hometown": "Manchester",
    "region": "England",
    "country": "GB",
    "locationLabel": "Manchester, England, United Kingdom",
    "sets": [
      {
        "lineupId": "3e5a7c9b-0d2f-4e6a-9b8c-1d3f5a7e9c02",
        "stage": "Main Stage",
        "day": "2026-07-17",
        "startTime": "21:30",
        "endTime": "23:00"
      }
    ]
  }
}
```

### Fields

- `id` (uuid)
- `name` (string) — Billed name.
- `realName` (string | null) — Legal name, when the artist has published one.
- `bioShort` (string | null) — One or two sentences, for a lineup card.
- `bioLong` (string | null) — Full biography, for an artist page.
- `imageUrl` (string | null) — Press shot.
- `genres` (string[]) — Free-text genre tags. May be empty.
- `website` (string | null) — The artist's own site.
- `socials` (object) — Profile URLs keyed by platform slug (`instagram`, `spotify`, `soundcloud`, …). Blank entries are stripped server-side, so every value here is a real URL.
- `hometown` (string | null) — City.
- `region` (string | null) — State or province.
- `country` (string | null) — Raw ISO 3166-1 alpha-2 code, e.g. "GB".
- `locationLabel` (string | null) — Pre-formatted location for display. Render this rather than joining the parts.
- `sets` (object[]) — Every set this artist plays at this event.
- `sets[].lineupId` (uuid) — Matches the `id` of the corresponding lineup slot.
- `sets[].stage` (string | null)
- `sets[].day` (string | null) — Festival day as `YYYY-MM-DD`.
- `sets[].startTime` (string | null) — Local start time as `HH:MM`.
- `sets[].endTime` (string | null) — Local end time as `HH:MM`.

## Errors

- `not_found` (HTTP 404) — No event with that slug is published on this surface. Check the slug, and check you sent `?surface=web`.

---

<!-- source: https://developers.grofomo.com/reference/events/faq -->

# Event FAQs

`GET /v1/events/{slug}/faq`

The event's FAQs, in the organiser's own categories and order.

Answers arrive as **pre-rendered, sanitised HTML** in `answerHtml`, so you can inject them directly without running a rich-text renderer of your own.

On the web surface the response carries an `FAQPage` JSON-LD block.

> **Send `?surface=web`.** Omitted, the request is treated as coming from the mobile app, which is gated on a different visibility setting — so a live event can return `404 not_found`.

## Request

### curl

```bash
curl -sS \
  -H 'X-Grofomo-Key: pk_live_YOUR_PUBLISHABLE_KEY' \
  'https://api.grofomo.com/v1/events/summer-fest/faq?surface=web'
```

### Browser

```javascript
// Publishable keys are meant to be visible in page source. They identify
// the organisation and can be revoked — they are not a secret.
const res = await fetch('https://api.grofomo.com/v1/events/summer-fest/faq?surface=web', {
  headers: { 'X-Grofomo-Key': 'pk_live_YOUR_PUBLISHABLE_KEY' },
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const faq = body.data;
```

### Server

```javascript
// Server-side, so the SECRET key never reaches the browser.
const res = await fetch('https://api.grofomo.com/v1/events/summer-fest/faq?surface=web', {
  headers: { 'X-Grofomo-Key': process.env.GROFOMO_SECRET_KEY },
  next: { revalidate: 60 },
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const faq = body.data;
```

## Path parameters

- `slug` (string, required) — The event's URL slug. Globally unique, and fixed once the event is created. Example: `summer-fest`.

## Query parameters

- `surface` ('web', required) — Must be `web` for a website. Omit it and you get the mobile-app surface, which is gated on a different visibility setting — so a perfectly live event can return 404. Example: `web`.

## Response

```json
{
  "apiVersion": 1,
  "data": {
    "eventId": "6f1c8e2a-4b3d-4c9e-9f21-8a7d5e0b1c34",
    "surface": "web",
    "categories": [
      {
        "id": "getting-there",
        "name": "Getting there",
        "faqs": [
          {
            "id": "72e4c6a8-3d5f-4b90-9a1c-6e8d0f2b4a37",
            "question": "Is there parking on site?",
            "answerDoc": {
              "type": "doc",
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "Yes, but it must be booked in advance through the "
                    },
                    {
                      "type": "text",
                      "text": "ticket store",
                      "marks": [
                        {
                          "type": "link",
                          "attrs": {
                            "href": "https://grfm.to/e/summer-fest"
                          }
                        }
                      ]
                    },
                    {
                      "type": "text",
                      "text": ". Gates open at 10:00 each day."
                    }
                  ]
                }
              ]
            },
            "answerPlain": "Yes, but it must be booked in advance through the ticket store. Gates open at 10:00 each day.",
            "answerHtml": "<p>Yes, but it must be booked in advance through the <a href=\"https://grfm.to/e/summer-fest\">ticket store</a>. Gates open at 10:00 each day.</p>",
            "updatedAt": "2026-05-14T16:02:00.000Z"
          }
        ]
      },
      {
        "id": null,
        "name": "On the day",
        "faqs": [
          {
            "id": "e8a0c2d4-7f9b-4d51-8c3e-9b7f5d1a3c48",
            "question": "Can I bring my own drinks?",
            "answerDoc": {
              "type": "doc",
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "Sealed water only, up to 500ml. Everything else is available on site."
                    }
                  ]
                }
              ]
            },
            "answerPlain": "Sealed water only, up to 500ml. Everything else is available on site.",
            "answerHtml": "<p>Sealed water only, up to 500ml. Everything else is available on site.</p>",
            "updatedAt": "2026-05-14T16:04:00.000Z"
          }
        ]
      }
    ],
    "schemaOrg": {
      "@context": "https://schema.org",
      "@type": "FAQPage",
      "mainEntity": [
        {
          "@type": "Question",
          "name": "Is there parking on site?",
          "acceptedAnswer": {
            "@type": "Answer",
            "text": "Yes, but it must be booked in advance through the ticket store."
          }
        }
      ]
    },
    "lastUpdatedAt": "2026-05-14T16:04:00.000Z",
    "generatedAt": "2026-06-01T09:15:00.000Z"
  }
}
```

### Fields

- `groups[]` (array, may be absent) — FAQ categories, in the organiser's order.
- `groups[].name` (string, may be absent) — Category heading, e.g. "Getting there".
- `groups[].items[]` (array, may be absent) — The questions in that category.
- `groups[].items[].question` (string, may be absent) — The question text.
- `groups[].items[].answerHtml` (string, may be absent) — Sanitised HTML — safe to inject directly.

## Structured data

The response carries a ready-made `FAQPage` JSON-LD block in `schemaOrg`. Emitted on the web surface.

## Errors

- `unauthorized` (HTTP 401) — No key was sent and the organiser requires one — or the key is invalid, revoked, belongs to another organisation, or is scoped to a different event.
- `origin_not_allowed` (HTTP 403) — Your site's domain is not on the organiser's allowed list. Browser calls only: a server sends no Origin header and is unaffected.
- `not_found` (HTTP 404) — No event with that slug is published on this surface. Check the slug, and check you sent `?surface=web`.

## Notes

- Rate limited to roughly 60 requests per minute per caller (guidance, not a contract).

---

<!-- source: https://developers.grofomo.com/reference/events/news -->

# News index

`GET /v1/events/{slug}/news`

The event's published news articles, newest first. Each entry is a summary — fetch a single article for its body.

Drafts and articles scheduled for later never appear.

## Request

### curl

```bash
curl -sS \
  -H 'X-Grofomo-Key: pk_live_YOUR_PUBLISHABLE_KEY' \
  'https://api.grofomo.com/v1/events/summer-fest/news'
```

### Browser

```javascript
// Publishable keys are meant to be visible in page source. They identify
// the organisation and can be revoked — they are not a secret.
const res = await fetch('https://api.grofomo.com/v1/events/summer-fest/news', {
  headers: { 'X-Grofomo-Key': 'pk_live_YOUR_PUBLISHABLE_KEY' },
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const news = body.data;
```

### Server

```javascript
// Server-side, so the SECRET key never reaches the browser.
const res = await fetch('https://api.grofomo.com/v1/events/summer-fest/news', {
  headers: { 'X-Grofomo-Key': process.env.GROFOMO_SECRET_KEY },
  next: { revalidate: 60 },
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const news = body.data;
```

## Path parameters

- `slug` (string, required) — The event's URL slug. Globally unique, and fixed once the event is created. Example: `summer-fest`.

## Response

```json
{
  "apiVersion": 1,
  "data": {
    "eventId": "6f1c8e2a-4b3d-4c9e-9f21-8a7d5e0b1c34",
    "articles": [
      {
        "slug": "second-wave-announced",
        "title": "Second wave announced",
        "excerpt": "Twelve more names join the bill, including a Sunday close on the Main Stage.",
        "heroImageUrl": "https://cdn.grofomo.com/summer-fest/news/second-wave.jpg",
        "tags": [
          "lineup"
        ],
        "author": "Riot Promotions",
        "publishedAt": "2026-05-28T09:00:00.000Z",
        "updatedAt": "2026-05-28T09:00:00.000Z"
      },
      {
        "slug": "travel-and-parking",
        "title": "Travel and parking, explained",
        "excerpt": "Shuttle times from Temple Meads, and how the pre-book car park works.",
        "heroImageUrl": null,
        "tags": [
          "travel",
          "practical"
        ],
        "author": null,
        "publishedAt": "2026-05-12T08:30:00.000Z",
        "updatedAt": "2026-05-19T14:10:00.000Z"
      }
    ],
    "lastUpdatedAt": "2026-05-28T09:00:00.000Z",
    "generatedAt": "2026-06-01T09:15:00.000Z"
  }
}
```

### Fields

- `eventId` (uuid)
- `articles` (object[]) — Published articles, newest first. Drafts and scheduled posts never appear.
- `articles[].slug` (string) — Pass this to the single-article endpoint for the body.
- `articles[].title` (string)
- `articles[].excerpt` (string) — Short standfirst, for a listing card.
- `articles[].heroImageUrl` (string | null)
- `articles[].tags` (string[]) — Free-text tags, e.g. "lineup". May be empty.
- `articles[].author` (string | null)
- `articles[].publishedAt` (string) — Publication time. The index is sorted newest first on this.
- `articles[].updatedAt` (string)
- `lastUpdatedAt` (string | null) — Most recent change across these articles. Null when there are none.
- `generatedAt` (string) — When this response was built. Useful for a cache debug line.

## Errors

- `unauthorized` (HTTP 401) — No key was sent and the organiser requires one — or the key is invalid, revoked, belongs to another organisation, or is scoped to a different event.
- `origin_not_allowed` (HTTP 403) — Your site's domain is not on the organiser's allowed list. Browser calls only: a server sends no Origin header and is unaffected.
- `not_found` (HTTP 404) — No event with that slug is published on this surface. Check the slug, and check you sent `?surface=web`.

## Notes

- Rate limited to roughly 60 requests per minute per caller (guidance, not a contract).
- Always served from the web surface, whatever `?surface=` says.

---

<!-- source: https://developers.grofomo.com/reference/events/news-article -->

# News article

`GET /v1/events/{slug}/news/{articleSlug}`

One published article, including its body as sanitised HTML.

On the web surface the response carries a `NewsArticle` JSON-LD block.

## Request

### curl

```bash
curl -sS \
  -H 'X-Grofomo-Key: pk_live_YOUR_PUBLISHABLE_KEY' \
  'https://api.grofomo.com/v1/events/summer-fest/news/first-wave-announced'
```

### Browser

```javascript
// Publishable keys are meant to be visible in page source. They identify
// the organisation and can be revoked — they are not a secret.
const res = await fetch('https://api.grofomo.com/v1/events/summer-fest/news/first-wave-announced', {
  headers: { 'X-Grofomo-Key': 'pk_live_YOUR_PUBLISHABLE_KEY' },
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const newsArticle = body.data;
```

### Server

```javascript
// Server-side, so the SECRET key never reaches the browser.
const res = await fetch('https://api.grofomo.com/v1/events/summer-fest/news/first-wave-announced', {
  headers: { 'X-Grofomo-Key': process.env.GROFOMO_SECRET_KEY },
  next: { revalidate: 60 },
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const newsArticle = body.data;
```

## Path parameters

- `slug` (string, required) — The event's URL slug. Globally unique, and fixed once the event is created. Example: `summer-fest`.
- `articleSlug` (string, required) — The article's slug, from the news index. Example: `first-wave-announced`.

## Response

```json
{
  "apiVersion": 1,
  "data": {
    "slug": "second-wave-announced",
    "title": "Second wave announced",
    "excerpt": "Twelve more names join the bill, including a Sunday close on the Main Stage.",
    "heroImageUrl": "https://cdn.grofomo.com/summer-fest/news/second-wave.jpg",
    "tags": [
      "lineup"
    ],
    "author": "Riot Promotions",
    "publishedAt": "2026-05-28T09:00:00.000Z",
    "updatedAt": "2026-05-28T09:00:00.000Z",
    "bodyMarkdown": "## Twelve more names\n\nThe second wave lands today, and it fills out both the Friday night Orchard programme and Sunday on the Main Stage.\n\nTickets for all three days are on sale now.",
    "bodyHtml": "<h2>Twelve more names</h2>\n<p>The second wave lands today, and it fills out both the Friday night Orchard programme and Sunday on the Main Stage.</p>\n<p>Tickets for all three days are on sale now.</p>",
    "seoTitle": "Summer Fest 2026: second wave announced",
    "seoDescription": "Twelve more names join the Summer Fest bill, including a Sunday Main Stage close.",
    "schemaOrg": {
      "@context": "https://schema.org",
      "@type": "NewsArticle",
      "headline": "Second wave announced",
      "datePublished": "2026-05-28T09:00:00.000Z",
      "dateModified": "2026-05-28T09:00:00.000Z",
      "author": {
        "@type": "Organization",
        "name": "Riot Promotions"
      }
    }
  }
}
```

### Fields

- `slug` (string) — Pass this to the single-article endpoint for the body.
- `title` (string)
- `excerpt` (string) — Short standfirst, for a listing card.
- `heroImageUrl` (string | null)
- `tags` (string[]) — Free-text tags, e.g. "lineup". May be empty.
- `author` (string | null)
- `publishedAt` (string) — Publication time. The index is sorted newest first on this.
- `updatedAt` (string)
- `bodyMarkdown` (string) — The canonical body, in markdown.
- `bodyHtml` (string | null) — The same body pre-rendered to sanitised HTML, so you need no markdown renderer.
- `seoTitle` (string | null) — Override for the page `<title>`, when the organiser set one.
- `seoDescription` (string | null) — Override for the meta description.
- `schemaOrg` (object | null) — A ready-made schema.org `NewsArticle` block for a JSON-LD script tag.

## Structured data

The response carries a ready-made `NewsArticle` JSON-LD block in `schemaOrg`. Emitted on the web surface.

## Errors

- `unauthorized` (HTTP 401) — No key was sent and the organiser requires one — or the key is invalid, revoked, belongs to another organisation, or is scoped to a different event.
- `origin_not_allowed` (HTTP 403) — Your site's domain is not on the organiser's allowed list. Browser calls only: a server sends no Origin header and is unaffected.
- `not_found` (HTTP 404) — No event with that slug is published on this surface. Check the slug, and check you sent `?surface=web`.

## Notes

- Rate limited to roughly 60 requests per minute per caller (guidance, not a contract).

---

<!-- source: https://developers.grofomo.com/reference/events/broadcasts -->

# Announcements

`GET /v1/events/{slug}/broadcasts`

Announcements the organiser has pushed to attendees — stage changes, weather notices, running-order updates.

Good for a live "latest updates" strip during the event itself. Never cached, so it is safe to poll.

> **No key is required today, but send one anyway.** The Grofomo mobile app still calls this endpoint without a credential, so it cannot be locked down yet — it will be. A key sent now is accepted and ignored, so the integration keeps working when enforcement lands.

## Request

### curl

```bash
curl -sS \
  -H 'X-Grofomo-Key: pk_live_YOUR_PUBLISHABLE_KEY' \
  'https://api.grofomo.com/v1/events/summer-fest/broadcasts'
```

### Browser

```javascript
// Publishable keys are meant to be visible in page source. They identify
// the organisation and can be revoked — they are not a secret.
const res = await fetch('https://api.grofomo.com/v1/events/summer-fest/broadcasts', {
  headers: { 'X-Grofomo-Key': 'pk_live_YOUR_PUBLISHABLE_KEY' },
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const broadcasts = body.data;
```

### Server

```javascript
// Server-side, so the SECRET key never reaches the browser.
const res = await fetch('https://api.grofomo.com/v1/events/summer-fest/broadcasts', {
  headers: { 'X-Grofomo-Key': process.env.GROFOMO_SECRET_KEY },
  cache: 'no-store',
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const broadcasts = body.data;
```

## Path parameters

- `slug` (string, required) — The event's URL slug. Globally unique, and fixed once the event is created. Example: `summer-fest`.

## Response

```json
{
  "apiVersion": 1,
  "data": {
    "broadcasts": [
      {
        "id": "0d2f4a6c-8e0b-4c73-9f5a-2c4e6a8d0b59",
        "title": "Main Stage running 20 minutes late",
        "body": "Weather delay this morning. Everything from 18:00 shifts back by 20 minutes.",
        "category": "update",
        "sentAt": "2026-07-18T16:42:00.000Z",
        "deepLink": "https://grfm.to/e/summer-fest"
      },
      {
        "id": "4a6c8e0d-2f4b-4e95-8a7c-1f3d5b7e9c60",
        "title": "Last entry is 21:00",
        "body": "Gates close for good at 21:00 tonight. Plan your arrival.",
        "category": "reminder",
        "sentAt": "2026-07-17T14:00:00.000Z",
        "deepLink": null
      }
    ]
  }
}
```

### Fields

- `broadcasts` (object[])
- `broadcasts[].id` (uuid)
- `broadcasts[].title` (string)
- `broadcasts[].body` (string)
- `broadcasts[].category` ("reminder" | "update" | "marketing") — What kind of announcement this was. Mirrors the push opt-in it was sent under.
- `broadcasts[].sentAt` (string) — When it went out. Newest first.
- `broadcasts[].deepLink` (string | null) — Where the announcement pointed, when it pointed anywhere.

## Errors

- `not_found` (HTTP 404) — No event with that slug is published on this surface. Check the slug, and check you sent `?surface=web`.

## Notes

- Rate limited to roughly 60 requests per minute per caller (guidance, not a contract).
- `Cache-Control: no-store`

---

<!-- source: https://developers.grofomo.com/reference/events/tickets -->

# Ticket availability

`GET /v1/events/{slug}/tickets`

The ticket types and release tiers a visitor is allowed to see, with live availability.

Visibility is resolved **server-side**, so this only ever returns what the public should see: time-gated tiers appear when they open, and hidden sold-out tiers stay hidden.

Read `soldOut` rather than inferring from `available`. `available` is `null` both when a tier is unlimited **and** when the organiser has chosen not to publish counts — `soldOut` is always authoritative.

Selling tickets from your own site is not part of this API yet. Use this feed to show prices and availability, and link to the Grofomo ticket page to sell; an embeddable checkout is coming.

> **Send `?surface=web`.** Omitted, the request is treated as coming from the mobile app, which is gated on a different visibility setting — so a live event can return `404 not_found`.

## Request

### curl

```bash
curl -sS \
  -H 'X-Grofomo-Key: pk_live_YOUR_PUBLISHABLE_KEY' \
  'https://api.grofomo.com/v1/events/summer-fest/tickets?surface=web'
```

### Browser

```javascript
// Publishable keys are meant to be visible in page source. They identify
// the organisation and can be revoked — they are not a secret.
const res = await fetch('https://api.grofomo.com/v1/events/summer-fest/tickets?surface=web', {
  headers: { 'X-Grofomo-Key': 'pk_live_YOUR_PUBLISHABLE_KEY' },
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const tickets = body.data;
```

### Server

```javascript
// Server-side, so the SECRET key never reaches the browser.
const res = await fetch('https://api.grofomo.com/v1/events/summer-fest/tickets?surface=web', {
  headers: { 'X-Grofomo-Key': process.env.GROFOMO_SECRET_KEY },
  next: { revalidate: 60 },
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const tickets = body.data;
```

## Path parameters

- `slug` (string, required) — The event's URL slug. Globally unique, and fixed once the event is created. Example: `summer-fest`.

## Query parameters

- `surface` ('web', required) — Must be `web` for a website. Omit it and you get the mobile-app surface, which is gated on a different visibility setting — so a perfectly live event can return 404. Example: `web`.
- `promo` (string, optional) — A live unlock code, to reveal promo-gated ticket types.

## Response

```json
{
  "apiVersion": 1,
  "data": {
    "categories": [
      {
        "id": "6f1c8e2a-4b3d-4c9e-9f21-8a7d5e0b1c35",
        "title": "Weekend",
        "description": "All three days, with camping."
      }
    ],
    "types": [
      {
        "id": "b2d4a6f8-1c3e-4a5b-8d7f-2e9c0a1b3d46",
        "categoryId": "6f1c8e2a-4b3d-4c9e-9f21-8a7d5e0b1c35",
        "title": "Weekend camping ticket",
        "description": "Entry Friday to Sunday, plus a camping pitch from Friday 10:00.",
        "descriptionDoc": {
          "type": "doc",
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Entry Friday to Sunday, plus a camping pitch from Friday 10:00."
                }
              ]
            }
          ]
        },
        "ticketsPerGroup": 1,
        "minPerOrder": 1,
        "maxPerOrder": 6,
        "isHighlighted": true,
        "highlightMessage": "Most popular",
        "paymentPlan": {
          "depositBps": 2500,
          "installments": 3
        },
        "releases": [
          {
            "id": "3e5a7c9b-0d2f-4e6a-9b8c-1d3f5a7e9c03",
            "label": "Tier 1",
            "pricePennies": 9500,
            "currency": "GBP",
            "available": null,
            "capacity": null,
            "closesAt": null,
            "opensAt": null,
            "upcoming": false,
            "soldOut": true,
            "closed": false
          },
          {
            "id": "9c7e5a3b-1f0d-4b2e-8a6c-4d2f0b8e6a14",
            "label": "Tier 2",
            "pricePennies": 11000,
            "currency": "GBP",
            "available": 340,
            "capacity": 1500,
            "closesAt": "2026-07-10T22:59:00.000Z",
            "opensAt": null,
            "upcoming": false,
            "soldOut": false,
            "closed": false
          },
          {
            "id": "47a9e1c3-5b8d-4f20-9c6e-3a1b7d5f9e03",
            "label": "Final release",
            "pricePennies": 12500,
            "currency": "GBP",
            "available": null,
            "capacity": null,
            "closesAt": null,
            "opensAt": "2026-07-11T09:00:00.000Z",
            "upcoming": true,
            "soldOut": false,
            "closed": false
          }
        ]
      }
    ],
    "quantityDiscounts": [
      {
        "id": "d1f3b5a7-9c2e-4d80-8b6f-5a3c1e7d9b05",
        "name": "Group of four",
        "kind": "tiered_percent",
        "applicableReleaseIds": [
          "9c7e5a3b-1f0d-4b2e-8a6c-4d2f0b8e6a14"
        ],
        "tiers": [
          {
            "minQuantity": 4,
            "value": 1000
          }
        ],
        "combinableWithPromo": false
      }
    ]
  }
}
```

### Fields

- `categories` (object[]) — Optional grouping for the types below.
- `categories[].id` (uuid) — Referenced by `categoryId` on a ticket type.
- `categories[].title` (string) — Section heading, e.g. "Weekend".
- `categories[].description` (string | null)
- `types` (object[]) — Only what this caller is allowed to see. Hidden and promo-gated types are filtered server-side.
- `types[].id` (uuid)
- `types[].categoryId` (uuid | null) — Groups this type under a category. Null when ungrouped.
- `types[].title` (string)
- `types[].description` (string | null) — Plain-text description, for clients that render no rich text.
- `types[].descriptionDoc` (object | null) — The same description as a ProseMirror document. Render this when present, otherwise `description`.
- `types[].descriptionDoc.type` ("doc")
- `types[].descriptionDoc.content` (object | object | object | object | object | object[], may be absent)
- `types[].ticketsPerGroup` (number) — Admissions issued per unit bought. 1 is a single ticket; higher means a table or group ticket.
- `types[].minPerOrder` (number) — Fewest units one order may contain.
- `types[].maxPerOrder` (number) — Most units one order may contain.
- `types[].isHighlighted` (boolean) — The organiser wants this type visually promoted.
- `types[].highlightMessage` (string | null) — Badge text for a highlighted type, e.g. "Most popular".
- `types[].paymentPlan` (object | null) — Set when this type can be bought on a payment plan. Null otherwise.
- `types[].paymentPlan.depositBps` (number) — Deposit as basis points of the total, so 2500 is 25%.
- `types[].paymentPlan.installments` (number) — Number of payments after the deposit.
- `types[].releases` (object[]) — Price tiers, in sale order. Only tiers this caller is allowed to see are included.
- `types[].releases[].id` (uuid)
- `types[].releases[].label` (string) — Release name, e.g. "Tier 2" or "Final release".
- `types[].releases[].pricePennies` (number) — Price in minor units, so 9500 is £95.00.
- `types[].releases[].currency` (string) — ISO 4217 code, e.g. "GBP".
- `types[].releases[].available` (number | null) — Tickets left. Null means EITHER unlimited OR the organiser has chosen not to publish counts — so this can never gate a buy button on its own. Use `soldOut`.
- `types[].releases[].capacity` (number | null, may be absent) — Total allocation, hidden under the same rule as `available`. With it you can show percent sold.
- `types[].releases[].closesAt` (string | null, may be absent) — When this release stops selling. Null means no cut-off.
- `types[].releases[].opensAt` (string | null, may be absent) — When this release starts selling. Set alongside `upcoming`, and the target for a countdown.
- `types[].releases[].upcoming` (boolean, may be absent) — A teaser: listed but not yet purchasable. Takes precedence over `soldOut` and `closed`, which are both false while it holds.
- `types[].releases[].soldOut` (boolean) — Authoritative. Gate your buy button on this, never on `available`.
- `types[].releases[].closed` (boolean) — The sale window has ended. Still shown, no longer purchasable.
- `quantityDiscounts` (object[], may be absent) — Automatic discounts, in enough detail to advertise ("Buy 4+ and save 10%") and preview locally. The server stays authoritative at checkout.
- `quantityDiscounts[].id` (uuid)
- `quantityDiscounts[].name` (string) — Organiser-facing name, e.g. "Group of four".
- `quantityDiscounts[].kind` ("tiered_percent" | "tiered_fixed" | "buy_n_get_m" | "bundle_price") — Which of the fields below apply, and how `tiers[].value` should be read.
- `quantityDiscounts[].applicableReleaseIds` (uuid[]) — Releases this rule applies to. Empty means the whole order.
- `quantityDiscounts[].tiers` (object[], may be absent) — Present for the two tiered kinds.
- `quantityDiscounts[].tiers[].minQuantity` (number) — Quantity at which this tier starts applying.
- `quantityDiscounts[].tiers[].value` (number) — Basis points off for `tiered_percent` (1000 = 10%), or pennies off per ticket for `tiered_fixed`.
- `quantityDiscounts[].buyQuantity` (number, may be absent) — The "buy N" of a `buy_n_get_m` rule.
- `quantityDiscounts[].freeQuantity` (number, may be absent) — The "get M free" of a `buy_n_get_m` rule.
- `quantityDiscounts[].bundleSize` (number, may be absent) — Tickets per bundle, for `bundle_price`.
- `quantityDiscounts[].bundlePricePennies` (number, may be absent) — Price of one whole bundle, for `bundle_price`.
- `quantityDiscounts[].combinableWithPromo` (boolean) — Whether a promo code can stack on top of this discount.

## Errors

- `unauthorized` (HTTP 401) — No key was sent and the organiser requires one — or the key is invalid, revoked, belongs to another organisation, or is scoped to a different event.
- `origin_not_allowed` (HTTP 403) — Your site's domain is not on the organiser's allowed list. Browser calls only: a server sends no Origin header and is unaffected.
- `not_found` (HTTP 404) — No event with that slug is published on this surface. Check the slug, and check you sent `?surface=web`.

## Notes

- Rate limited to roughly 60 requests per minute per caller (guidance, not a contract).

---

<!-- source: https://developers.grofomo.com/reference/events/merch -->

# Merch catalogue

`GET /v1/events/{slug}/merch`

The event's merch catalogue: each product with its colours, sizes, print zones and price.

Products carry the plain garment image plus the event logo to overlay, so you can render a preview without anyone shipping you mock-ups.

> **Send `?surface=web`.** Omitted, the request is treated as coming from the mobile app, which is gated on a different visibility setting — so a live event can return `404 not_found`.

## Request

### curl

```bash
curl -sS \
  -H 'X-Grofomo-Key: pk_live_YOUR_PUBLISHABLE_KEY' \
  'https://api.grofomo.com/v1/events/summer-fest/merch?surface=web'
```

### Browser

```javascript
// Publishable keys are meant to be visible in page source. They identify
// the organisation and can be revoked — they are not a secret.
const res = await fetch('https://api.grofomo.com/v1/events/summer-fest/merch?surface=web', {
  headers: { 'X-Grofomo-Key': 'pk_live_YOUR_PUBLISHABLE_KEY' },
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const merch = body.data;
```

### Server

```javascript
// Server-side, so the SECRET key never reaches the browser.
const res = await fetch('https://api.grofomo.com/v1/events/summer-fest/merch?surface=web', {
  headers: { 'X-Grofomo-Key': process.env.GROFOMO_SECRET_KEY },
  cache: 'no-store',
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const merch = body.data;
```

## Path parameters

- `slug` (string, required) — The event's URL slug. Globally unique, and fixed once the event is created. Example: `summer-fest`.

## Query parameters

- `surface` ('web', required) — Must be `web` for a website. Omit it and you get the mobile-app surface, which is gated on a different visibility setting — so a perfectly live event can return 404. Example: `web`.

## Response

```json
{
  "apiVersion": 1,
  "data": {
    "eventSlug": "summer-fest",
    "logoUrl": "https://cdn.grofomo.com/summer-fest/brand/logo.svg",
    "deliveryPennies": 495,
    "items": [
      {
        "value": "8e0d2f4a-6c8b-4f17-9e2a-3b5d7f9c1e71",
        "name": "Summer Fest 2026 Tee",
        "garmentType": "Heavyweight cotton t-shirt",
        "description": "Organic cotton, boxy fit, printed in Bristol.",
        "pricePennies": 2500,
        "currency": "GBP",
        "sizes": [
          "S",
          "M",
          "L",
          "XL",
          "XXL"
        ],
        "colours": [
          {
            "label": "Bone",
            "hex": "#FAFAF7",
            "frontImageUrl": "https://cdn.grofomo.com/summer-fest/merch/tee-bone-front.png",
            "backImageUrl": "https://cdn.grofomo.com/summer-fest/merch/tee-bone-back.png",
            "logoColor": "black",
            "outOfStock": false
          },
          {
            "label": "Carbon",
            "hex": "#080808",
            "frontImageUrl": "https://cdn.grofomo.com/summer-fest/merch/tee-carbon-front.png",
            "backImageUrl": "https://cdn.grofomo.com/summer-fest/merch/tee-carbon-back.png",
            "logoColor": "white",
            "outOfStock": true
          }
        ],
        "printZones": [
          {
            "side": "front",
            "x": 0.5,
            "y": 0.34,
            "scale": 0.32,
            "recolor": true,
            "logoColor": "auto",
            "clip": true
          },
          {
            "side": "back",
            "x": 0.5,
            "y": 0.28,
            "scale": 0.55,
            "recolor": true,
            "logoColor": "auto",
            "clip": true
          }
        ]
      }
    ]
  }
}
```

### Fields

- `eventSlug` (string)
- `logoUrl` (string | null) — The logo to overlay on each print zone — so you can render previews without any mock-ups.
- `deliveryPennies` (number) — Flat delivery fee in minor units, for shipped orders. 0 means free, or collection only.
- `items` (object[])
- `items[].value` (string) — Product id. Matches the option value on a `merch_items` form field.
- `items[].name` (string)
- `items[].garmentType` (string) — What the garment is, e.g. "Heavyweight cotton t-shirt".
- `items[].description` (string | null)
- `items[].pricePennies` (number) — Unit price in minor units, so 2500 is £25.00.
- `items[].currency` (string) — ISO 4217 code, e.g. "GBP".
- `items[].sizes` (string[]) — Available sizes, in display order.
- `items[].colours` (object[]) — Colourways. Each carries the PLAIN garment image; overlay the event logo yourself.
- `items[].colours[].label` (string) — Colourway name, e.g. "Bone".
- `items[].colours[].hex` (string | null) — Swatch colour, for a colour picker.
- `items[].colours[].frontImageUrl` (string | null) — Plain garment front, with no logo applied.
- `items[].colours[].backImageUrl` (string | null) — Plain garment back, with no logo applied.
- `items[].colours[].logoColor` (string | null, may be absent) — How to treat the logo on this colourway: `auto`, `brand`, `white` or `black`.
- `items[].colours[].outOfStock` (boolean, may be absent) — Show the colourway, but do not let anyone buy it.
- `items[].printZones` (object[]) — Where to place the logo on each side. All coordinates are 0–1 fractions, so a preview scales freely.
- `items[].printZones[].side` ("front" | "back")
- `items[].printZones[].x` (number) — Centre of the logo, as a 0–1 fraction of the garment image width.
- `items[].printZones[].y` (number) — Centre of the logo, as a 0–1 fraction of the garment image height.
- `items[].printZones[].scale` (number) — Logo width, as a 0–1 fraction of the garment image width.
- `items[].printZones[].recolor` (boolean, may be absent)
- `items[].printZones[].logoUrl` (string | null, may be absent) — A logo specific to this placement. Absent means use the event logo.
- `items[].printZones[].logoColor` (string | null, may be absent) — `auto`, `brand`, `white` or `black`.
- `items[].printZones[].clip` (boolean, may be absent) — Mask the logo to the garment silhouette, so a wide placement does not bleed off the edge.
- `items[].outline` (object[], may be absent) — Traced garment silhouette (0–1 points) driving the `clip` mask. Absent means use a default tee shape.
- `items[].outline[].x` (number)
- `items[].outline[].y` (number)

## Errors

- `unauthorized` (HTTP 401) — No key was sent and the organiser requires one — or the key is invalid, revoked, belongs to another organisation, or is scoped to a different event.
- `origin_not_allowed` (HTTP 403) — Your site's domain is not on the organiser's allowed list. Browser calls only: a server sends no Origin header and is unaffected.
- `not_found` (HTTP 404) — No event with that slug is published on this surface. Check the slug, and check you sent `?surface=web`.

## Notes

- Rate limited to roughly 60 requests per minute per caller (guidance, not a contract).
- `Cache-Control: no-store`
- Never cached, so stock and price changes are immediate.

---

<!-- source: https://developers.grofomo.com/reference/events/subscribe -->

# Mailing-list signup

`POST /v1/events/{slug}/subscribe`

Post an email address straight into the organiser's mailing list, so your site can host its own signup block rather than embedding a hosted form.

**Consent is the organiser's to collect.** Only submit an address when the visitor has actively asked to hear from them — this endpoint records a signup, it does not make one lawful.

Requires a Cloudflare Turnstile token, so it is not usable from a script.

> **Send `?surface=web`.** Omitted, the request is treated as coming from the mobile app, which is gated on a different visibility setting — so a live event can return `404 not_found`.

> **Requires a Cloudflare Turnstile token**, so it cannot be driven from a script.

## Request

### curl

```bash
curl -sS \
  -X POST \
  -H 'X-Grofomo-Key: pk_live_YOUR_PUBLISHABLE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"email":"fan@example.com","name":"Alex Doe","turnstileToken":"<token from the Turnstile widget>"}' \
  'https://api.grofomo.com/v1/events/summer-fest/subscribe?surface=web'
```

### Browser

```javascript
// Publishable keys are meant to be visible in page source. They identify
// the organisation and can be revoked — they are not a secret.
const res = await fetch('https://api.grofomo.com/v1/events/summer-fest/subscribe?surface=web', {
  method: 'POST',
  headers: {
    'X-Grofomo-Key': 'pk_live_YOUR_PUBLISHABLE_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "email": "fan@example.com",
  "name": "Alex Doe",
  "turnstileToken": "<token from the Turnstile widget>"
}),
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const subscribe = body.data;
```

### Server

```javascript
// Server-side, so the SECRET key never reaches the browser.
const res = await fetch('https://api.grofomo.com/v1/events/summer-fest/subscribe?surface=web', {
  method: 'POST',
  headers: {
    'X-Grofomo-Key': process.env.GROFOMO_SECRET_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "email": "fan@example.com",
  "name": "Alex Doe",
  "turnstileToken": "<token from the Turnstile widget>"
}),
  cache: 'no-store',
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const subscribe = body.data;
```

## Path parameters

- `slug` (string, required) — The event's URL slug. Globally unique, and fixed once the event is created. Example: `summer-fest`.

## Query parameters

- `surface` ('web', required) — Must be `web` for a website. Omit it and you get the mobile-app surface, which is gated on a different visibility setting — so a perfectly live event can return 404. Example: `web`.

## Response

```json
{
  "apiVersion": 1,
  "data": {
    "ok": true,
    "submissionId": "a7b8c9d0-e1f2-4345-8678-9abcdef01234"
  }
}
```

### Fields

- `ok` (boolean, may be absent) — Always `true` on success.
- `submissionId` (uuid, may be absent) — Identifies this signup, so a second step can attach a phone number within the hour.

## Errors

- `unauthorized` (HTTP 401) — No key was sent and the organiser requires one — or the key is invalid, revoked, belongs to another organisation, or is scoped to a different event.
- `origin_not_allowed` (HTTP 403) — Your site's domain is not on the organiser's allowed list. Browser calls only: a server sends no Origin header and is unaffected.
- `not_found` (HTTP 404) — No event with that slug is published on this surface. Check the slug, and check you sent `?surface=web`.
- `turnstile_failed` (HTTP 400) — The bot-check token was missing or invalid.
- `bad_request` (HTTP 400) — The email address was not valid.

## Notes

- Rate limited to roughly 30 requests per minute per caller (guidance, not a contract).
- `Cache-Control: no-store`

---

<!-- source: https://developers.grofomo.com/reference/forms/definition -->

# Form definition

`GET /v1/forms/{key}`

A published form's definition — its fields, types, labels and validation — so you can render it in your own design instead of embedding a hosted page.

Artist-picker fields arrive with their options already filled in from the event's lineup.

> **Send `?surface=web`.** Omitted, the request is treated as coming from the mobile app, which is gated on a different visibility setting — so a live event can return `404 not_found`.

## Request

### curl

```bash
curl -sS \
  -H 'X-Grofomo-Key: pk_live_YOUR_PUBLISHABLE_KEY' \
  'https://api.grofomo.com/v1/forms/volunteer-signup?surface=web'
```

### Browser

```javascript
// Publishable keys are meant to be visible in page source. They identify
// the organisation and can be revoked — they are not a secret.
const res = await fetch('https://api.grofomo.com/v1/forms/volunteer-signup?surface=web', {
  headers: { 'X-Grofomo-Key': 'pk_live_YOUR_PUBLISHABLE_KEY' },
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const definition = body.data;
```

### Server

```javascript
// Server-side, so the SECRET key never reaches the browser.
const res = await fetch('https://api.grofomo.com/v1/forms/volunteer-signup?surface=web', {
  headers: { 'X-Grofomo-Key': process.env.GROFOMO_SECRET_KEY },
  next: { revalidate: 60 },
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const definition = body.data;
```

## Path parameters

- `key` (string, required) — The form's key, from the organiser's console. Example: `volunteer-signup`.

## Query parameters

- `surface` ('web', required) — Must be `web` for a website. Omit it and you get the mobile-app surface, which is gated on a different visibility setting — so a perfectly live event can return 404. Example: `web`.

## Response

```json
{
  "apiVersion": 1,
  "data": {
    "key": "volunteer-signup",
    "kind": "contact",
    "eventId": "6f1c8e2a-4b3d-4c9e-9f21-8a7d5e0b1c34",
    "eventSlug": "summer-fest",
    "title": "Volunteer with us",
    "version": 3,
    "surface": "web",
    "fields": [
      {
        "id": "full_name",
        "type": "text",
        "label": "Your name",
        "required": true
      },
      {
        "id": "email",
        "type": "email",
        "label": "Email address",
        "required": true,
        "role": "email"
      },
      {
        "id": "shifts",
        "type": "checkbox",
        "label": "Which shifts can you cover?",
        "help": "Pick as many as you like.",
        "required": true,
        "options": [
          {
            "value": "friday-evening",
            "label": "Friday evening"
          },
          {
            "value": "saturday-morning",
            "label": "Saturday morning"
          },
          {
            "value": "sunday-close",
            "label": "Sunday close"
          }
        ]
      },
      {
        "id": "favourite_act",
        "type": "artist_multiselect",
        "label": "Anyone you would love to work near?",
        "required": false,
        "source": "lineup",
        "options": [
          {
            "value": "9c7e5a3b-1f0d-4b2e-8a6c-4d2f0b8e6a13",
            "label": "Nala Vex"
          },
          {
            "value": "d1f3b5a7-9c2e-4d80-8b6f-5a3c1e7d9b04",
            "label": "Sonny Delrey"
          }
        ]
      }
    ]
  }
}
```

### Fields

- `key` (string) — The form key. Post submissions back to this same key.
- `kind` ("feedback" | "mailing_list" | "contact" | "merch_enquiry") — What the form is for.
- `eventId` (uuid | null) — Null for an organisation-wide form not tied to one event.
- `eventSlug` (string | null)
- `title` (string)
- `version` (number) — Definition version. Send it back with the submission so the answers can be audited against it.
- `surface` ("app" | "web")
- `fields` (object[]) — The questions, in the organiser's order.
- `fields[].id` (string) — Key this answer under this id when you submit.
- `fields[].type` ("rating" | "radio" | "checkbox" | "select" | …) — Which control to render.
- `fields[].label` (string) — The question, as the organiser wrote it.
- `fields[].help` (string, may be absent) — Hint text to show under the control.
- `fields[].required` (boolean, may be absent) — Absent means optional.
- `fields[].role` ("overall_rating" | "venue_rating" | "would_return" | "favourite_artist" | … | null, may be absent) — What the answer means to Grofomo, e.g. `email` promotes it to the contact address.
- `fields[].options` (object[], may be absent) — Choices for a radio, checkbox, select or artist picker. Submit the `value`, display the `label`.
- `fields[].options[].value` (string)
- `fields[].options[].label` (string)
- `fields[].min` (number, may be absent) — Lower bound of a rating.
- `fields[].max` (number, may be absent) — Upper bound of a rating.
- `fields[].source` ("lineup" | "stages" | "merch_items", may be absent)
- `merchCatalog` (object[], may be absent)
- `merchCatalog[].value` (string) — Product id. Matches the option value on a `merch_items` form field.
- `merchCatalog[].name` (string)
- `merchCatalog[].garmentType` (string) — What the garment is, e.g. "Heavyweight cotton t-shirt".
- `merchCatalog[].description` (string | null)
- `merchCatalog[].pricePennies` (number) — Unit price in minor units, so 2500 is £25.00.
- `merchCatalog[].currency` (string) — ISO 4217 code, e.g. "GBP".
- `merchCatalog[].sizes` (string[]) — Available sizes, in display order.
- `merchCatalog[].colours` (object[]) — Colourways. Each carries the PLAIN garment image; overlay the event logo yourself.
- `merchCatalog[].colours[].label` (string) — Colourway name, e.g. "Bone".
- `merchCatalog[].colours[].hex` (string | null) — Swatch colour, for a colour picker.
- `merchCatalog[].colours[].frontImageUrl` (string | null) — Plain garment front, with no logo applied.
- `merchCatalog[].colours[].backImageUrl` (string | null) — Plain garment back, with no logo applied.
- `merchCatalog[].colours[].logoColor` (string | null, may be absent) — How to treat the logo on this colourway: `auto`, `brand`, `white` or `black`.
- `merchCatalog[].colours[].outOfStock` (boolean, may be absent) — Show the colourway, but do not let anyone buy it.
- `merchCatalog[].printZones` (object[]) — Where to place the logo on each side. All coordinates are 0–1 fractions, so a preview scales freely.
- `merchCatalog[].printZones[].side` ("front" | "back")
- `merchCatalog[].printZones[].x` (number) — Centre of the logo, as a 0–1 fraction of the garment image width.
- `merchCatalog[].printZones[].y` (number) — Centre of the logo, as a 0–1 fraction of the garment image height.
- `merchCatalog[].printZones[].scale` (number) — Logo width, as a 0–1 fraction of the garment image width.
- `merchCatalog[].printZones[].recolor` (boolean, may be absent)
- `merchCatalog[].printZones[].logoUrl` (string | null, may be absent) — A logo specific to this placement. Absent means use the event logo.
- `merchCatalog[].printZones[].logoColor` (string | null, may be absent) — `auto`, `brand`, `white` or `black`.
- `merchCatalog[].printZones[].clip` (boolean, may be absent) — Mask the logo to the garment silhouette, so a wide placement does not bleed off the edge.
- `merchCatalog[].outline` (object[], may be absent) — Traced garment silhouette (0–1 points) driving the `clip` mask. Absent means use a default tee shape.
- `merchCatalog[].outline[].x` (number)
- `merchCatalog[].outline[].y` (number)

## Errors

- `unauthorized` (HTTP 401) — No key was sent and the organiser requires one — or the key is invalid, revoked, belongs to another organisation, or is scoped to a different event.
- `origin_not_allowed` (HTTP 403) — Your site's domain is not on the organiser's allowed list. Browser calls only: a server sends no Origin header and is unaffected.
- `not_found` (HTTP 404) — No event with that slug is published on this surface. Check the slug, and check you sent `?surface=web`.

## Notes

- Rate limited to roughly 60 requests per minute per caller (guidance, not a contract).

---

<!-- source: https://developers.grofomo.com/reference/forms/submit -->

# Submit a form

`POST /v1/forms/{key}/submissions`

Submit answers for a published form. Answers are validated against the form's own definition, so fetch the definition first and post back matching field ids.

Requires a Turnstile token.

> **Send `?surface=web`.** Omitted, the request is treated as coming from the mobile app, which is gated on a different visibility setting — so a live event can return `404 not_found`.

> **Requires a Cloudflare Turnstile token**, so it cannot be driven from a script.

## Request

### curl

```bash
curl -sS \
  -X POST \
  -H 'X-Grofomo-Key: pk_live_YOUR_PUBLISHABLE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"answers":{"full_name":"Alex Doe","email":"alex@example.com","shifts":["friday-evening","saturday-morning"]},"turnstileToken":"<token from the Turnstile widget>"}' \
  'https://api.grofomo.com/v1/forms/volunteer-signup/submissions?surface=web'
```

### Browser

```javascript
// Publishable keys are meant to be visible in page source. They identify
// the organisation and can be revoked — they are not a secret.
const res = await fetch('https://api.grofomo.com/v1/forms/volunteer-signup/submissions?surface=web', {
  method: 'POST',
  headers: {
    'X-Grofomo-Key': 'pk_live_YOUR_PUBLISHABLE_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "answers": {
    "full_name": "Alex Doe",
    "email": "alex@example.com",
    "shifts": [
      "friday-evening",
      "saturday-morning"
    ]
  },
  "turnstileToken": "<token from the Turnstile widget>"
}),
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const submit = body.data;
```

### Server

```javascript
// Server-side, so the SECRET key never reaches the browser.
const res = await fetch('https://api.grofomo.com/v1/forms/volunteer-signup/submissions?surface=web', {
  method: 'POST',
  headers: {
    'X-Grofomo-Key': process.env.GROFOMO_SECRET_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "answers": {
    "full_name": "Alex Doe",
    "email": "alex@example.com",
    "shifts": [
      "friday-evening",
      "saturday-morning"
    ]
  },
  "turnstileToken": "<token from the Turnstile widget>"
}),
  cache: 'no-store',
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const submit = body.data;
```

## Path parameters

- `key` (string, required) — The form's key. Example: `volunteer-signup`.

## Query parameters

- `surface` ('web', required) — Must be `web` for a website. Omit it and you get the mobile-app surface, which is gated on a different visibility setting — so a perfectly live event can return 404. Example: `web`.

## Response

```json
{
  "apiVersion": 1,
  "data": {
    "ok": true
  }
}
```

### Fields

- `ok` (true)

## Errors

- `unauthorized` (HTTP 401) — No key was sent and the organiser requires one — or the key is invalid, revoked, belongs to another organisation, or is scoped to a different event.
- `origin_not_allowed` (HTTP 403) — Your site's domain is not on the organiser's allowed list. Browser calls only: a server sends no Origin header and is unaffected.
- `not_found` (HTTP 404) — No event with that slug is published on this surface. Check the slug, and check you sent `?surface=web`.
- `turnstile_failed` (HTTP 400) — The bot-check token was missing or invalid.
- `bad_request` (HTTP 400) — An answer did not match the form definition.

## Notes

- Rate limited to roughly 30 requests per minute per caller (guidance, not a contract).
- `Cache-Control: no-store`

---

<!-- source: https://developers.grofomo.com/reference/events/detail -->

# Event detail

`GET /v1/events/{slug}`

Everything that describes the event itself — name, dates, timezone, venue, stages and the organiser's brand settings.

Usually the first call a site makes.

> **No key is required today, but send one anyway.** The Grofomo mobile app still calls this endpoint without a credential, so it cannot be locked down yet — it will be. A key sent now is accepted and ignored, so the integration keeps working when enforcement lands.

## Request

### curl

```bash
curl -sS \
  -H 'X-Grofomo-Key: pk_live_YOUR_PUBLISHABLE_KEY' \
  'https://api.grofomo.com/v1/events/summer-fest'
```

### Browser

```javascript
// Publishable keys are meant to be visible in page source. They identify
// the organisation and can be revoked — they are not a secret.
const res = await fetch('https://api.grofomo.com/v1/events/summer-fest', {
  headers: { 'X-Grofomo-Key': 'pk_live_YOUR_PUBLISHABLE_KEY' },
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const detail = body.data;
```

### Server

```javascript
// Server-side, so the SECRET key never reaches the browser.
const res = await fetch('https://api.grofomo.com/v1/events/summer-fest', {
  headers: { 'X-Grofomo-Key': process.env.GROFOMO_SECRET_KEY },
  next: { revalidate: 60 },
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const detail = body.data;
```

## Path parameters

- `slug` (string, required) — The event's URL slug. Globally unique, and fixed once the event is created. Example: `summer-fest`.

## Response

```json
{
  "apiVersion": 1,
  "data": {
    "id": "6f1c8e2a-4b3d-4c9e-9f21-8a7d5e0b1c34",
    "slug": "summer-fest",
    "name": "Summer Fest",
    "description": "Three days of house, disco and breaks across two stages on the edge of Bristol, with camping from Friday morning.",
    "summary": "Three days, two stages, Ashton Court.",
    "ticketUrl": "https://grfm.to/e/summer-fest",
    "capacity": 8000,
    "familyFriendly": true,
    "musicGenres": [
      "House",
      "Disco",
      "Breaks"
    ],
    "timezone": "Europe/London",
    "dates": {
      "startDate": "2026-07-17",
      "endDate": "2026-07-19",
      "doorsOpen": "12:00",
      "doorsClose": "02:00",
      "timezone": "Europe/London",
      "singleDay": false
    },
    "venue": {
      "name": "Ashton Court",
      "address": "Ashton Court Estate",
      "city": "Bristol",
      "region": "England",
      "postcode": "BS41 9JN",
      "country": "GB",
      "indoorOutdoor": "outdoor"
    },
    "stages": [
      {
        "id": "main-stage",
        "name": "Main Stage",
        "type": "outdoor",
        "description": "The big one, in the meadow.",
        "imageUrl": "https://cdn.grofomo.com/summer-fest/stages/main.jpg"
      },
      {
        "id": "the-orchard",
        "name": "The Orchard",
        "type": "tent",
        "description": null,
        "imageUrl": null
      }
    ],
    "brand": {
      "brandColors": [
        "#FFEA00",
        "#080808"
      ],
      "logoUrl": "https://cdn.grofomo.com/summer-fest/brand/logo.png",
      "logoVectorUrl": "https://cdn.grofomo.com/summer-fest/brand/logo.svg",
      "artworkUrl": "https://cdn.grofomo.com/summer-fest/brand/poster.jpg",
      "coverArtUrl": "https://cdn.grofomo.com/summer-fest/brand/cover.jpg",
      "backgroundColor": "#080808",
      "textColor": "#FAFAF7",
      "accentColor": "#FFEA00",
      "fontFamily": "Syne",
      "socialLinks": {
        "instagram": "https://instagram.com/summerfest",
        "spotify": "https://open.spotify.com/playlist/summerfest"
      },
      "mapImageUrl": "https://cdn.grofomo.com/summer-fest/brand/site-map.png",
      "themeMode": "brand",
      "fonts": {
        "headline": {
          "family": "Syne",
          "url": "https://fonts.gstatic.com/s/syne/v22/8vIS7w4qzmVxsWxjBZRjr0FKM_04uT6kR47NCV5Z.ttf",
          "weight": 700
        },
        "body": null
      }
    },
    "community": {
      "chatUrl": "https://chat.whatsapp.com/summerfest",
      "chatPlatform": "whatsapp",
      "chatLabel": "Summer Fest group chat"
    },
    "organiser": {
      "id": "b2d4a6f8-1c3e-4a5b-8d7f-2e9c0a1b3d45",
      "name": "Riot Promotions",
      "slug": "riot-promotions",
      "logoUrl": "https://cdn.grofomo.com/riot-promotions/logo.png"
    }
  }
}
```

### Fields

- `id` (uuid)
- `slug` (string) — The URL slug, fixed once the event is created.
- `name` (string)
- `description` (string | null) — Long-form event copy.
- `summary` (string | null) — One line, for a card or a meta description.
- `ticketUrl` (string | null) — Where to send someone to buy. Null when no tickets are on sale.
- `capacity` (number | null)
- `familyFriendly` (boolean | null)
- `musicGenres` (string[]) — Free-text genre tags for the event as a whole.
- `timezone` (string) — IANA zone, e.g. "Europe/London". Every local time in the API is in it.
- `dates` (object)
- `dates.startDate` (string | null) — First day, as `YYYY-MM-DD`.
- `dates.endDate` (string | null) — Last day, as `YYYY-MM-DD`. Equal to `startDate` for a one-day event.
- `dates.doorsOpen` (string | null) — Local opening time as `HH:MM`.
- `dates.doorsClose` (string | null) — Local closing time as `HH:MM`. May be after midnight.
- `dates.timezone` (string | null) — IANA zone, e.g. "Europe/London". Every `HH:MM` here is local to it.
- `dates.singleDay` (boolean | null)
- `venue` (object)
- `venue.name` (string | null)
- `venue.address` (string | null) — Street address, without city or postcode.
- `venue.city` (string | null)
- `venue.region` (string | null) — State, province or county.
- `venue.postcode` (string | null)
- `venue.country` (string | null) — Raw ISO 3166-1 alpha-2 code, e.g. "GB".
- `venue.indoorOutdoor` (string | null) — Free text, e.g. "outdoor".
- `stages` (object[]) — Every stage. A lineup slot names its stage by `name`, not by `id`.
- `stages[].id` (string) — Stable within the event. Matches `stage` on a lineup slot by name, not by id.
- `stages[].name` (string)
- `stages[].type` (string | null) — Free text, e.g. "tent".
- `stages[].description` (string | null)
- `stages[].imageUrl` (string | null)
- `brand` (object) — The organiser's colours, logos and fonts, so your site can match the event's identity.
- `brand.brandColors` (string[])
- `brand.logoUrl` (string | null)
- `brand.logoVectorUrl` (string | null)
- `brand.artworkUrl` (string | null)
- `brand.coverArtUrl` (string | null)
- `brand.backgroundColor` (string | null)
- `brand.textColor` (string | null)
- `brand.accentColor` (string | null)
- `brand.fontFamily` (string | null)
- `brand.socialLinks` (object)
- `brand.mapImageUrl` (string | null)
- `brand.themeMode` ("neutral" | "brand" | "brand-full")
- `brand.fonts` (object)
- `brand.fonts.headline` (object | null)
- `brand.fonts.headline.family` (string)
- `brand.fonts.headline.url` (string)
- `brand.fonts.headline.weight` (number)
- `brand.fonts.body` (object | null)
- `brand.fonts.body.family` (string)
- `brand.fonts.body.url` (string)
- `brand.fonts.body.weight` (number)
- `community` (object)
- `community.chatUrl` (string | null) — Invite link to the attendee group chat, when the organiser runs one.
- `community.chatPlatform` ("whatsapp" | "telegram" | "discord" | "signal" | … | null) — Which platform the chat is on, so you can show the right icon.
- `community.chatLabel` (string | null) — Call-to-action text, e.g. "Summer Fest group chat".
- `organiser` (object | null) — Present only when the organiser has opted into a public profile — i.e. only when there is a page to link to.
- `organiser.id` (uuid)
- `organiser.name` (string)
- `organiser.slug` (string)
- `organiser.logoUrl` (string | null)

## Errors

- `not_found` (HTTP 404) — No event with that slug is published on this surface. Check the slug, and check you sent `?surface=web`.

---

<!-- source: https://developers.grofomo.com/reference/events/version -->

# Content version

`GET /v1/events/{slug}/version`

A single timestamp that moves whenever the event or its lineup is edited.

Poll this instead of re-fetching the lineup. It is small and cached for 15 seconds, so you can check often and only pull the heavy feeds when the version actually changes.

> **No key is required today, but send one anyway.** The Grofomo mobile app still calls this endpoint without a credential, so it cannot be locked down yet — it will be. A key sent now is accepted and ignored, so the integration keeps working when enforcement lands.

## Request

### curl

```bash
curl -sS \
  -H 'X-Grofomo-Key: pk_live_YOUR_PUBLISHABLE_KEY' \
  'https://api.grofomo.com/v1/events/summer-fest/version'
```

### Browser

```javascript
// Publishable keys are meant to be visible in page source. They identify
// the organisation and can be revoked — they are not a secret.
const res = await fetch('https://api.grofomo.com/v1/events/summer-fest/version', {
  headers: { 'X-Grofomo-Key': 'pk_live_YOUR_PUBLISHABLE_KEY' },
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const version = body.data;
```

### Server

```javascript
// Server-side, so the SECRET key never reaches the browser.
const res = await fetch('https://api.grofomo.com/v1/events/summer-fest/version', {
  headers: { 'X-Grofomo-Key': process.env.GROFOMO_SECRET_KEY },
  next: { revalidate: 15 },
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const version = body.data;
```

## Path parameters

- `slug` (string, required) — The event's URL slug. Globally unique, and fixed once the event is created. Example: `summer-fest`.

## Response

```json
{
  "apiVersion": 1,
  "data": {
    "eventId": "6f1c8e2a-4b3d-4c9e-9f21-8a7d5e0b1c34",
    "eventSlug": "summer-fest",
    "scheduleVersion": "2026-06-01T09:15:00.000Z",
    "updatedAt": "2026-06-01T09:15:00.000Z"
  }
}
```

### Fields

- `eventId` (uuid)
- `eventSlug` (string)
- `scheduleVersion` (string) — Opaque token that changes whenever the event or its lineup is edited. Compare it with the last one you saw; only pull the heavy feeds when it differs.
- `updatedAt` (string) — When that last edit happened.

## Errors

- `not_found` (HTTP 404) — No event with that slug is published on this surface. Check the slug, and check you sent `?surface=web`.

## Notes

- `Cache-Control: public, s-maxage=15, stale-while-revalidate=60`

---

<!-- source: https://developers.grofomo.com/reference/organisers/detail -->

# Organiser profile

`GET /v1/organisers/{slug}`

An organiser's public profile and their upcoming public events.

Only returned when the organiser has opted in to a public profile; otherwise this is a 404.

> **No key is required today, but send one anyway.** The Grofomo mobile app still calls this endpoint without a credential, so it cannot be locked down yet — it will be. A key sent now is accepted and ignored, so the integration keeps working when enforcement lands.

## Request

### curl

```bash
curl -sS \
  -H 'X-Grofomo-Key: pk_live_YOUR_PUBLISHABLE_KEY' \
  'https://api.grofomo.com/v1/organisers/riot-promotions'
```

### Browser

```javascript
// Publishable keys are meant to be visible in page source. They identify
// the organisation and can be revoked — they are not a secret.
const res = await fetch('https://api.grofomo.com/v1/organisers/riot-promotions', {
  headers: { 'X-Grofomo-Key': 'pk_live_YOUR_PUBLISHABLE_KEY' },
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const detail = body.data;
```

### Server

```javascript
// Server-side, so the SECRET key never reaches the browser.
const res = await fetch('https://api.grofomo.com/v1/organisers/riot-promotions', {
  headers: { 'X-Grofomo-Key': process.env.GROFOMO_SECRET_KEY },
  next: { revalidate: 60 },
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const detail = body.data;
```

## Path parameters

- `slug` (string, required) — The organiser's slug. Example: `riot-promotions`.

## Response

```json
{
  "apiVersion": 1,
  "data": {
    "id": "b2d4a6f8-1c3e-4a5b-8d7f-2e9c0a1b3d45",
    "name": "Riot Promotions",
    "slug": "riot-promotions",
    "bio": "Bristol promoters since 2011. Warehouse parties, one festival, and a stubborn dislike of queues.",
    "logoUrl": "https://cdn.grofomo.com/riot-promotions/logo.png",
    "logoVectorUrl": null,
    "backgroundColor": "#080808",
    "textColor": "#FAFAF7",
    "website": "https://riotpromotions.example",
    "socials": {
      "instagram": "https://instagram.com/riotpromotions"
    },
    "upcomingEvents": [
      {
        "id": "6f1c8e2a-4b3d-4c9e-9f21-8a7d5e0b1c34",
        "slug": "summer-fest",
        "name": "Summer Fest",
        "startDate": "2026-07-17",
        "endDate": "2026-07-19",
        "venueName": "Ashton Court",
        "city": "Bristol",
        "country": "GB",
        "artworkUrl": "https://cdn.grofomo.com/summer-fest/brand/poster.jpg"
      }
    ]
  }
}
```

### Fields

- `id` (uuid)
- `name` (string)
- `slug` (string)
- `bio` (string | null) — Public "about us" copy.
- `logoUrl` (string | null)
- `logoVectorUrl` (string | null)
- `backgroundColor` (string | null)
- `textColor` (string | null)
- `website` (string | null)
- `socials` (object) — Profile URLs keyed by platform slug. Blank entries are stripped server-side.
- `upcomingEvents` (object[]) — The organiser's public events that have not finished yet, soonest first.
- `upcomingEvents[].id` (uuid)
- `upcomingEvents[].slug` (string) — Pass this to any of the per-event endpoints.
- `upcomingEvents[].name` (string)
- `upcomingEvents[].startDate` (string | null) — First day, as `YYYY-MM-DD`.
- `upcomingEvents[].endDate` (string | null) — Last day, as `YYYY-MM-DD`.
- `upcomingEvents[].venueName` (string | null)
- `upcomingEvents[].city` (string | null)
- `upcomingEvents[].country` (string | null) — Raw ISO 3166-1 alpha-2 code, e.g. "GB".
- `upcomingEvents[].artworkUrl` (string | null) — Poster or key artwork, for a listing card.

## Errors

- `not_found` (HTTP 404) — No such organiser, or they have not enabled a public profile.

---

<!-- source: https://developers.grofomo.com/reference/events/search -->

# Event search

`GET /v1/events/search`

Search events that organisers have opted in to public discovery, across the whole platform.

Cross-organisation, so it is not scoped to any one key and cannot be locked down per organiser. Meant for discovery surfaces rather than a single event's own website.

> **No key is required today, but send one anyway.** The Grofomo mobile app still calls this endpoint without a credential, so it cannot be locked down yet — it will be. A key sent now is accepted and ignored, so the integration keeps working when enforcement lands.

## Request

### curl

```bash
curl -sS \
  -H 'X-Grofomo-Key: pk_live_YOUR_PUBLISHABLE_KEY' \
  'https://api.grofomo.com/v1/events/search'
```

### Browser

```javascript
// Publishable keys are meant to be visible in page source. They identify
// the organisation and can be revoked — they are not a secret.
const res = await fetch('https://api.grofomo.com/v1/events/search', {
  headers: { 'X-Grofomo-Key': 'pk_live_YOUR_PUBLISHABLE_KEY' },
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const search = body.data;
```

### Server

```javascript
// Server-side, so the SECRET key never reaches the browser.
const res = await fetch('https://api.grofomo.com/v1/events/search', {
  headers: { 'X-Grofomo-Key': process.env.GROFOMO_SECRET_KEY },
  next: { revalidate: 60 },
});

const body = await res.json();
if (!res.ok) {
  throw new Error(`${body.error.code}: ${body.error.message}`);
}

const search = body.data;
```

## Query parameters

- `q` (string, optional) — Matched against event name and slug. Empty returns the soonest events. Example: `summer`.
- `limit` (number, optional) — Maximum results. Defaults to 20, capped at 50.

## Response

```json
{
  "apiVersion": 1,
  "data": {
    "query": "summer",
    "results": [
      {
        "id": "6f1c8e2a-4b3d-4c9e-9f21-8a7d5e0b1c34",
        "slug": "summer-fest",
        "name": "Summer Fest",
        "startDate": "2026-07-17",
        "endDate": "2026-07-19",
        "venueName": "Ashton Court",
        "city": "Bristol",
        "country": "GB",
        "artworkUrl": "https://cdn.grofomo.com/summer-fest/brand/poster.jpg"
      }
    ]
  }
}
```

### Fields

- `query` (string)
- `results` (object[])
- `results[].id` (uuid)
- `results[].slug` (string) — Pass this to any of the per-event endpoints.
- `results[].name` (string)
- `results[].startDate` (string | null) — First day, as `YYYY-MM-DD`.
- `results[].endDate` (string | null) — Last day, as `YYYY-MM-DD`.
- `results[].venueName` (string | null)
- `results[].city` (string | null)
- `results[].country` (string | null) — Raw ISO 3166-1 alpha-2 code, e.g. "GB".
- `results[].artworkUrl` (string | null) — Poster or key artwork, for a listing card.

---

<!-- source: https://developers.grofomo.com/webhooks -->

# Webhooks

Receive ticket sales and signups on your own endpoint, with signature verification.

Webhooks push events to you as they happen, so you do not have to poll for a ticket sale.

They are configured by the **organiser**, in EventOS → Settings → Webhooks: your URL, which events to send, and a format. You cannot register one yourself — the organiser owns the data and therefore the decision.

## Formats

- **`json`** — the structured payload plus a rendered `message` string. This is the one to pick for your own endpoint.
- **`slack`** — `{"text": "…"}`, ready to post straight into a Slack incoming webhook.

## Verifying a delivery

Every delivery carries an HMAC-SHA256 signature of the raw request body, keyed on the organiser's signing secret:

```text
X-Eventos-Signature: hmac-sha256=<hex digest>
```

Verify it before trusting anything in the body. Use the **raw** body, not a re-serialised object — `JSON.parse` followed by `JSON.stringify` will not reproduce the same bytes, and the signature will not match.

```javascript
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(rawBody, headerValue, signingSecret) {
  const expected = createHmac('sha256', signingSecret)
    .update(rawBody)
    .digest('hex');

  const received = (headerValue ?? '').replace('hmac-sha256=', '');
  if (received.length !== expected.length) return false;

  // Constant-time compare: a plain === leaks the digest one byte at a time.
  return timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}
```

## Retries

A delivery that fails is retried up to five times with backoff — roughly 1 minute, 5 minutes, 30 minutes, 2 hours, then a final attempt — before being marked dead.

So: **return `2xx` fast.** Acknowledge first and do the work afterwards. A slow handler will be retried while it is still running, and the same event will arrive twice. Make your handler idempotent.

## Events

### `ticket.sale` — Ticket sale

A paid ticket order completes (web, app, or door).

Placeholders: `{{buyer_name}}`, `{{buyer_first_name}}`, `{{buyer_email}}`, `{{event_name}}`, `{{items}}`, `{{ticket_count}}`, `{{order_total}}`, `{{order_number}}`

### `merch.sale` — Merch sale

A merch order is paid via checkout.

Placeholders: `{{buyer_name}}`, `{{buyer_email}}`, `{{event_name}}`, `{{items}}`, `{{item_count}}`, `{{order_total}}`, `{{order_number}}`

### `ticket.refund` — Ticket refund

A ticket order is fully or partially refunded.

Placeholders: `{{buyer_name}}`, `{{event_name}}`, `{{order_number}}`, `{{refund_amount}}`, `{{refund_total}}`, `{{order_total}}`, `{{refund_scope}}`

### `merch.refund` — Merch refund

A merch order is fully or partially refunded.

Placeholders: `{{buyer_name}}`, `{{event_name}}`, `{{order_number}}`, `{{refund_total}}`, `{{order_total}}`, `{{refund_scope}}`

### `comp.issued` — Comps issued

Complimentary tickets are issued by the organiser team.

Placeholders: `{{guest_name}}`, `{{quantity}}`, `{{ticket_type}}`, `{{event_name}}`

### `comp.redeemed` — Artist comp redeemed

An artist sends a comp ticket from their remittance-offer allocation.

Placeholders: `{{artist_name}}`, `{{recipient_name}}`, `{{event_name}}`, `{{remaining}}`

### `prelaunch.registration` — Prelaunch registration

An attendee registers interest on a prelaunch page.

Placeholders: `{{event_name}}`, `{{source_event_name}}`, `{{first_name}}`, `{{contact_email}}`, `{{channels}}`

### `mailing_list.signup` — Mailing list signup

Someone joins the mailing list via a signup form.

Placeholders: `{{event_name}}`, `{{form_title}}`, `{{contact_email}}`

## A note on email placeholders

Several events expose an email placeholder, but **no default template uses one**. That is deliberate: a subscriber's address should not land in a shared Slack channel because nobody thought about it. An organiser who adds `{{contact_email}}` to a template is making that choice on purpose.

---

<!-- source: https://developers.grofomo.com/checkout -->

# Selling tickets

How to sell from your own site today, and the embed that is coming.

**Selling tickets from your own site is not part of this API today.** The quote, reserve and pay endpoints exist, but they are internal, and building against them would tie your site to a contract we intend to change.

## What to build today

Read [ticket availability](/reference/events/tickets), render prices and availability in your own design, and link out to the Grofomo ticket page to complete the purchase.

That gets you the part that matters visually — live prices, sold-out states, "final release" countdowns — without owning a payment flow.

```javascript
const { data } = await fetch(
  'https://api.grofomo.com/v1/events/summer-fest/tickets?surface=web',
  { headers: { 'X-Grofomo-Key': process.env.GROFOMO_SECRET_KEY } },
).then((r) => r.json());

for (const type of data.types) {
  for (const release of type.releases) {
    // soldOut is authoritative. `available` is null both when a tier is
    // unlimited AND when the organiser has chosen not to publish counts,
    // so it can never gate a buy button on its own.
    if (release.upcoming) renderCountdown(type, release);
    else if (release.soldOut) renderSoldOut(type, release);
    else renderBuyLink(type, release);
  }
}
```

## What is coming

An embeddable checkout: a small script you drop into your page, which renders the purchase flow inline and handles payment, card data and compliance on our side. Your design, your domain, none of the liability.

That is why the raw write flow stays undocumented. Publishing it would ask you to build something twice.

## In the meantime

- [Mailing-list signup](/reference/events/subscribe) — host your own signup block and post straight into the organiser's list.
- [Merch catalogue](/reference/events/merch) — garments, colours, sizes and print zones, so you can render previews without anyone shipping you mock-ups.

---

<!-- source: https://developers.grofomo.com/ai -->

# For AI agents

Machine-readable entry points: llms.txt, markdown twins and an OpenAPI document.

These docs are built to be read by coding assistants as well as people. Everything below is public and needs no key.

## Entry points

| URL | What it is |
|---|---|
| [`/llms.txt`](/llms.txt) | A map of the whole site: every page, one line each. Start here. |
| [`/llms-full.txt`](/llms-full.txt) | Every page's full text in one file. |
| [`/openapi.json`](/openapi.json) | OpenAPI 3.1 for every documented endpoint, generated from the same schemas the API uses. |

## Markdown twins

Any page has a plain-markdown version at the same path with `.md` appended:

```bash
curl https://developers.grofomo.com/reference/events/lineup.md
```

Or ask for it by content type at the canonical URL:

```bash
curl -H 'Accept: text/markdown' \
  https://developers.grofomo.com/reference/events/lineup
```

Same document either way — no navigation, no markup, no tokens spent on chrome.

## Pointing an assistant at this

```text
Read https://developers.grofomo.com/llms.txt for the Grofomo event API,
then build a lineup page for the event with slug "summer-fest".

Send the key in an X-Grofomo-Key header, and remember ?surface=web.
```

## Things worth telling it explicitly

Three mistakes we see repeatedly, all easy to state up front:

1. **`?surface=web` is required** on most endpoints. Omitting it silently selects the mobile-app surface and can return `404` for a live event.
2. **Publishable keys (`pk_live_…`) belong in browser code; secret keys (`sk_live_…`) never do.** Choose by where the code runs.
3. **Read `soldOut`, not `available`.** `available` is `null` both for unlimited tiers and for organisers who hide counts.

---

<!-- source: https://developers.grofomo.com/changelog -->

# Changelog

What changed, and how versioning works.

## How versioning works

The API is at `apiVersion: 1`, and stays there while changes are **additive** — new fields, new endpoints, new optional parameters.

Which means: **ignore fields you do not recognise.** A client that validates strictly against today's exact shape will break on a change designed not to break anything.

A genuinely breaking change would ship as a new version, announced here first, with the old one kept alive during the overlap.

## Changes

### These docs

This site is new. It documents the API as it stands today — including the API-key access control, which shipped shortly before it. Changes from here on are listed below as they happen.

## Coming

**Key requirements will extend to the remaining open endpoints.** A handful of reads — [event detail](/reference/events/detail), [content version](/reference/events/version), [artist detail](/reference/events/artist), [announcements](/reference/events/broadcasts) and [organiser profile](/reference/organisers/detail) — currently answer without a key, because the Grofomo mobile app calls them without one. That will change once the app carries a credential.

We are measuring key adoption on those endpoints before making the switch, so it lands as a measured decision rather than a hopeful one. **Send a key to them now**: it is accepted and ignored today, so an integration built that way needs no change on the day.

**An embeddable checkout**, so you can sell from your own site. See [selling tickets](/checkout).