# Gotobeat — the full agent orientation file

> Gotobeat (https://gotobeat.com) is a live-music ticketing platform and promoter. It lists concerts across the UK and Europe and sells the tickets itself: no resale, no markup. This file holds everything an agent needs to find a gig and buy a ticket, in one fetch. The short form is https://gotobeat.com/llms.txt.

## Entry points

- Human listing: https://gotobeat.com/gig/ (upcoming), https://gotobeat.com/gig/in/ (by city), https://gotobeat.com/gig/archive/ (past)
- Sitemap index: https://gotobeat.com/sitemap.xml (sections: events-upcoming, events-archive, artists, venues, content)
- Agent manual: https://gotobeat.com/docs/agents/
- OpenAPI 3.1: https://gotobeat.com/openapi/agents.json
- MCP server: https://mcp.gotobeat.com (OAuth 2.1). Anonymous read-only tier: POST https://mcp.gotobeat.com/public
- robots.txt allows exactly these API paths: /api/events, /api/search/, /api/artists/search, /api/venues/search, /api/checkout_sessions. Every other /api/ path is internal.
- Every page URL carries a trailing slash. A URL without one answers a 301.

## The public event shape

Every event object that the JSON API returns is an allowlist. It carries:

- eventId, slug, url (the canonical gig page), title, description (visible text, markup deleted), status (always PUBLISHED on the public surface)
- date (YYYY-MM-DD), untilDate for a multi-day event, startTime, endTime, doorTime (HH:MM, venue local time); an event that hides its date omits them
- hideDateTime, hideVenue (booleans)
- genres[], image, ageLimit
- artists[]: name, slug, image, genres[], spotifyUrl
- venue: name, address, city, postcode, country, googleMapsUrl; an event that hides its venue omits it
- tickets[]: sku, ticketTypeId, name, price (decimal string), currency (ISO 4217), availability (InStock | SoldOut | PreSale), releaseDate, minQuantity, maxQuantity
- externalTickets[]: name, url — sellers outside Gotobeat, when the event sells through one

Sales counts, revenue, coupons and operational fields never appear. Only an upcoming PUBLISHED event is visible. An unlisted event and an unknown slug answer the same 404, so the response discloses no existence signal.

## Read endpoints (no authentication)

GET https://gotobeat.com/api/events?search=<text>&cursor=<opaque>&limit=<n>
  Returns { events, cursor, hasMore, search?, fallbackType? }. Without search: upcoming events in date order. With search: keyword matches; when there are none the response widens to the matched artists' events, then genre matches, then top sellers, and names the widening in fallbackType (artist_events | artist_no_events | top_events). A fallback response is never paginated.

GET https://gotobeat.com/api/events/<slug>
  Returns { event, how_to_buy }. how_to_buy is the next step in prose.

GET https://gotobeat.com/api/search/event/<keyword>
  Returns a bare array of public event objects. Empty keyword or failed lookup → [] with status 200.

GET https://gotobeat.com/api/artists/search?keyword=<text>
  Returns { success, data: [{ id, label }] }. A keyword under two characters returns an empty array.

GET https://gotobeat.com/api/venues/search?keyword=<text>
  Returns { success, data: [{ id, label, venueId, venueName, city, country, hiringOptionsCount }] }.

## Structured data on a gig page

Each https://gotobeat.com/gig/<slug>/ embeds a schema.org MusicEvent in a <script type="application/ld+json"> block: name, startDate, endDate, doorTime, eventStatus, location (Place with PostalAddress), performer (PerformingGroup with url and sameAs), image, typicalAgeRange, isAccessibleForFree, and one Offer per ticket tier: url, sku, name, price (decimal string), priceCurrency, availability (https://schema.org/InStock | SoldOut | PreSale), validFrom.

- Offer.sku is <eventId>:<ticketTypeId>. Use it as items[].id in an ACP checkout session. An event id never contains a colon, so split on the first one.
- A cancelled event reads eventStatus EventCancelled and every offer SoldOut. A past event keeps EventScheduled (schema.org has no past state) and every offer SoldOut, with no sku.
- An event that sells through another ticketer carries an Offer whose url is that seller's page and no sku.
- A past event with durable content stays indexable as a historical record. It carries no product tags and no sku.

## Buying — Agentic Commerce Protocol (ACP)

All four mutating calls need an Idempotency-Key header (255 characters or fewer). A replay inside one hour returns the first response verbatim. The same key with a different body answers 409 request_not_idempotent.

POST https://gotobeat.com/api/checkout_sessions            Create. items[].id = sku, quantity a positive integer. Answers 201.
GET  https://gotobeat.com/api/checkout_sessions/:id        Read the session.
POST https://gotobeat.com/api/checkout_sessions/:id        Update items, buyer, fulfilment address or fulfilment option.
POST https://gotobeat.com/api/checkout_sessions/:id/complete   Pay with a token or a Stripe shared payment token. Produces the order.
POST https://gotobeat.com/api/checkout_sessions/:id/cancel     Abandon and release the held seats.

Status lifecycle: not_ready_for_payment (read messages[]) → ready_for_payment → completed (order.permalink_url is /orders/<checkoutId>) | canceled.

Every checkout request carries: Authorization: Bearer <credential> (issued at onboarding), API-Version: 2025-09-12, Request-Id, Accept-Language, User-Agent, Content-Type: application/json on a POST, a Timestamp header (an RFC 3339 date-time within five minutes of the server clock), and a Signature header: HMAC-SHA256 over the raw body with the signing secret, base64, in the sig1=:<base64>: form (a bare base64 value is accepted; a GET signs the empty string). A stale timestamp or a bad signature answers 401. The credential and the signing secret come from Gotobeat: write to us through https://gotobeat.com/docs/agents/. Without them a person buys the same tickets at the event url.

The server always re-prices the cart; a posted unit_amount is ignored and a mismatch returns an info message. HIDDEN, past, password-gated and zero-total carts are refused.

## MCP

https://mcp.gotobeat.com publishes RFC 9728 protected-resource metadata at /.well-known/oauth-protected-resource, supports RFC 7591 dynamic client registration and S256 PKCE. The anonymous tier at POST /public exposes public_search_events, public_get_event (tiers with sku and a how_to_buy recipe) and public_list_upcoming_events. The authenticated surface is scoped to the promoter who owns the token.

## Etiquette

- Respect robots.txt. Cache the sitemap sections; each is edge cached for six hours.
- Read one event with GET /api/events/<slug> instead of scraping the page.
- Rate limits are per warm instance and best effort. Back off on 429.
- Security contact: https://gotobeat.com/.well-known/security.txt