Agent & API Documentation

This page is written for machines, and for the people who write them. It describes every public surface an autonomous agent needs to find a gig on Gotobeat, read its ticket tiers, and buy them.

Overview

Gotobeat is a live-music ticketing platform. We list concerts across the UK and Europe and sell the tickets ourselves — no resale, no markup. There are four ways in, and you can mix them freely:

Structured data — every event page embeds schema.org JSON-LD. See Discovery.
JSON API — read-only event, artist and venue search. See Events API.
Agentic Commerce Protocol — create a checkout session and complete it. See Checkout.
MCP server — tools over the Model Context Protocol. See MCP.

Three machine-readable entry points sit at the root of the domain:

/llms.txt — the short orientation file, in llmstxt.org format.
/openapi/agents.json — the OpenAPI 3.1 description of the public API.
/sitemap.xml — every indexable event, artist and venue URL.

Every endpoint on this page is explicitly allowed in robots.txt. Everything else under /api/ is internal — please respect it. Page URLs carry a trailing slash; a URL without one answers with a 301 to the slashed form.

Discovery

Every event page at /gig/<slug>/ embeds a schema.org MusicEvent JSON-LD block, rendered as <script type="application/ld+json"> in the body. It carries the venue, the start and end time, the performers, and one Offer per ticket tier.

Each Offer looks like this:

{
  "@type": "Offer",
  "url": "https://gotobeat.com/gig/<slug>/",
  "sku": "<eventId>:<ticketTypeId>",
  "name": "Early Bird",
  "price": "20",
  "priceCurrency": "GBP",
  "availability": "https://schema.org/InStock",
  "validFrom": "2026-01-15T00:00:00.000Z"
}

Offer.sku is the id you pass as items[].id when you create a checkout session. It is the event id and the ticket type id joined by a single colon. An event id never contains a colon, so a parser splits on the first one. This is the only identifier you need to carry from a page read to a purchase.

Availability semantics:

https://schema.org/InStock — the tier is on sale right now.
https://schema.org/SoldOut — the tier is sold out, unreleased, or the event has already happened.
A cancelled event reads eventStatus: EventCancelled and every offer flips to SoldOut. A past event keeps eventStatus: EventScheduled — schema.org has no "past" status — and its offers read SoldOut.

Prices are decimal strings paired with priceCurrency (GBP or EUR). An event that hides its date or its venue omits those fields entirely rather than faking them.

Events API

Four read-only GET endpoints. They need no authentication. Note that they do not share one envelope shape — the two search helpers below were built for the site's own autocomplete and are documented here exactly as they behave.

`GET /api/events`

The main listing. Query parameters:

search — free text. Falls back through artist matches and genre matches before it gives up.
cursor — opaque. Pass back the cursor value from the previous response. Do not construct one.
limit — page size. Defaults to 12.

The response is a bare object with no success/data envelope:

{
  "events": [ /* sanitised public event objects */ ],
  "cursor": "MTI=" | null,
  "hasMore": true | false,
  "search": "oasis",          // echoed back when you sent one
  "fallbackType": "artist_events" | "artist_no_events" | "top_events"
}

fallbackType appears only when the direct search found nothing and we widened it. When it is artist_no_events the matched artists arrive in matchedArtists and the suggestions in genreEvents, while events is empty. A fallback response is never paginated: cursor is null and hasMore is false.

`GET /api/search/event/:keyword`

Keyword event lookup. Returns a bare array of sanitised event objects — no wrapper at all. An empty keyword or a failed lookup returns [], never an error status.

`GET /api/artists/search?keyword=`

Returns { "success": true, "data": [{ "id", "label" }] }. A keyword shorter than two characters returns an empty data array.

`GET /api/venues/search?keyword=`

Returns { "success": true, "data": [...] }. Each row carries id, label, venueId, venueName, city, country and hiringOptionsCount.

Checkout — Agentic Commerce Protocol

Buying is an Agentic Commerce Protocol flow. You create a session, refine it until it is payable, then complete it with a payment token. All four mutating calls require an Idempotency-Key header.

Method & path	Purpose	Idempotency-Key
`POST /api/checkout_sessions`	Create a session from a currency and a list of items. Answers 201.	Required
`GET /api/checkout_sessions/:id`	Read the current session state.	—
`POST /api/checkout_sessions/:id`	Update items, buyer, fulfilment address or fulfilment option.	Required
`POST /api/checkout_sessions/:id/complete`	Pay, with a token or a shared payment token. Produces the order.	Required
`POST /api/checkout_sessions/:id/cancel`	Abandon the session and release the held seats.	Required

Items

Each entry in items[] needs an id and a positive integer quantity. The id is the Offer.sku you read from the event page's JSON-LD: <eventId>:<ticketTypeId>. There is no separate catalogue call — the gig page is the catalogue.

Idempotency

Send a unique Idempotency-Key on every mutating request. It must be 255 characters or fewer. A replay of the same key inside the one-hour cache window returns the first response verbatim, with the original status code, instead of acting twice.

Signatures

Requests are signed with an HMAC over the raw body. Send the digest in the Signature header (the sig1=:<base64>: form is understood, as is a bare value) and the covered fields plus a created=<unix-seconds> timestamp in Signature-Input. A timestamp more than five minutes away from our clock is rejected with a 401. Talk to us to get a signing secret.

Status lifecycle

A session reports its own readiness in status:

not_ready_for_payment — something is still missing. Read messages[] to learn what.
ready_for_payment — call /complete.
completed — paid. The order carries a permalink_url of the form /orders/<checkoutId>, which is the buyer-facing confirmation page.
canceled — done, nothing was charged.

A missing session answers 404, a malformed body 400, and a bad signature or a stale timestamp 401.

MCP

Our Model Context Protocol server lives at https://mcp.gotobeat.com. It speaks OAuth 2.1, and it publishes RFC 9728 protected-resource metadata at /.well-known/oauth-protected-resource. A compliant client reads that document to discover the authorisation server and the supported scopes, so you should not need to hard-code anything.

A public tier at https://mcp.gotobeat.com/public needs no authentication and exposes read-only event search. It ships in this same release. The authenticated surface is much wider, and it is scoped to the promoter who owns the token.

Questions

If something on this page is wrong, or you need a signing secret, write to us. We would rather hear from your agent than debug it from the access logs — and yes, we do take requests.

Browse the gigs