--- title: "Ticket Fairy Developers | Public API, MCP and Agent Docs" description: "Read live public events with no API key, connect an AI agent over MCP, A2A or NLWeb, and get a credential for your own events. Endpoints, limits and example requests." canonical: "https://www.ticketfairy.com/developers" --- # Ticket Fairy Developers | Public API, MCP and Agent Docs Ticket Fairy developer documentation # Build with Ticket Fairy Read live public events with no API key, connect an AI agent to event search, or manage your own events after you sign in. This page lists every public endpoint, its limits and an example request. [Read the event API](#public-api) [Open the OpenAPI description](https://www.ticketfairy.com/api/v1/openapi.json) Public reads need no account. Changes to events need a credential, described under Authentication. Your first request ``` $ curl 'https://www.ticketfairy.com/api/v1/events/listing?search=festival§ion_type=upcoming&sort=start_date&order=asc&size=20' ``` No key, no sign-in. The response is JSON. ## Public event API `GET https://www.ticketfairy.com/api/v1/events/listing` returns live public events. It needs no credential. Every parameter is optional. ### Example response 200 OK, application/json ``` { "data": { "events": [ { "url": "https://www.ticketfairy.com/event/sunset-festival", "displayName": "Sunset Festival", "startDate": "2027-01-10T12:00:00+11:00", "timezone": "Australia/Melbourne", "startingPrice": { "amount": "49.00", "currency": "AUD" }, "venue": { "name": "Beach Park", "city": "Melbourne", "country": "au" } } ], "pagination": { "page": 1, "size": 20, "totalCount": 48, "totalPages": 3, "nextCursor": "eyJ2Ijox..." } }, "success": true, "error": false, "message": "Events successfully fetched.", "status": 200 } ``` ### Parameters | Parameter | What it does | Allowed values | | --- | --- | --- | | `search` | Words to match against event names and descriptions. | string | | `country` | Only events in this country, as an ISO 3166-1 alpha-2 code. | string | | `state` | Only events in this region, state or province. | string | | `from` | Only events starting on or after this date. | string | | `to` | Only events starting on or before this date. | string | | `section_type` | Which listing section to read. | upcoming, current, slider, past, none | | `timezone` | Interpret the date window and report dates in this IANA timezone. | string | | `sort` | The field to order by. | created\_at, updated\_at, start\_date. Default: start\_date | | `order` | Ascending or descending. | asc, desc. Default: desc | | `brandId` | Only events from this brand. | integer | | `include` | Which kinds of event to include, comma separated. All kinds when omitted. | Comma-separated values from: activities, paid\_events, free\_events, external\_events. Default: paid\_events,activities,free\_events,external\_events | | `page` | Which page of results, starting at 1. For reading page after page, prefer `cursor`. | integer. Default: 1 | | `size` | How many events per page. | integer from 1 to 200. Default: 100 | | `cursor` | The `pagination.nextCursor` value from the previous response, to read the next page. Send it with the same filters as that request. It sets the page and the page size, so `page` and `size` are ignored. | string | ### Pagination Each response has a `pagination` object. To get the next page, send its `nextCursor` value as the `cursor` parameter, with the same filters. When `nextCursor` is null, there are no more pages. Next page ``` $ curl 'https://www.ticketfairy.com/api/v1/events/listing?search=festival§ion_type=upcoming&sort=start_date&order=asc&cursor=NEXT_CURSOR' ``` ### Rate limits Each client address can send 120 requests a minute to the event API. Every response has the `RateLimit-Policy` header, for example `"default";q=120;w=60`, and the `RateLimit` header, for example `"default";r=119;t=60`. `r` is the number of requests left and `t` is the number of seconds until the limit resets. When the limit is used up, the response is 429 with a `Retry-After` header. ### Errors An error response has `success` false, a plain-language `message`, and a `code` to branch on. | Status | code | What to do | | --- | --- | --- | | 422 | `invalid_parameter` | A parameter is out of range or not an allowed value. The parameter field names it, and message says what to change. | | 429 | `rate_limited` | Too many requests from your address. Wait for the number of seconds in the Retry-After header, then send the request again. | | 500 | `listing_unavailable` | The events could not be fetched. Wait a minute, then send the same request again. | | 404 | `not_found` | No API endpoint answers at that address. | ### Versions The version is in the path. Version 1 changes only by addition, so your client must ignore response fields that it does not know. Read the [versioning and deprecation policy](https://www.ticketfairy.com/api/v1/versioning.md) to see how we announce a retirement. ## Ask in plain language `https://www.ticketfairy.com/ask` answers a question about upcoming events with the NLWeb protocol, version 0.55. It needs no credential. Each client address can send 60 questions a minute. ### Get the answer as JSON Terminal ``` $ curl 'https://www.ticketfairy.com/ask?query=jazz+in+Melbourne' ``` Words such as *tonight*, *this weekend* or *next month* limit the answer to events running then. Send `timezone`, for example `timezone=America/New_York`, to read those dates in your timezone. Ask about at most 6 things at once. The answer has `_meta` and a `results` list. Each result has the event's `url`, `name`, a short `description` and a schema.org Event in `schema_object`. ### Get the answer as a stream Set `prefer.streaming` to true, or send `streaming=true`. The answer comes as Server-Sent Events: one `start` event, one `result` event for each event found, and one `complete` event. Terminal ``` $ curl -N 'https://www.ticketfairy.com/ask' \ -H 'Content-Type: application/json' \ -d '{"query": {"text": "jazz in Melbourne"}, "prefer": {"streaming": true}, "meta": {"version": "0.55"}}' event: start data: {"_meta": {"response_type": "answer", "version": "0.55", ...}, "streaming": true} event: result data: {"index": 0, "item": {"url": "...", "name": "...", "schema_object": {"@type": "Event", ...}}} event: complete data: {"_meta": {"version": "0.55"}, "count": 1} ``` ## Connect an AI agent AI agents can search public events over the Model Context Protocol and Agent2Agent. Neither needs a credential. Both use the same filters as the event API. ### Public MCP server `https://www.ticketfairy.com/agentic/mcp` is an MCP server over Streamable HTTP. It has one tool, `search_events`, and a view that shows the results as event cards in clients that support MCP Apps. Each client address can send 120 requests a minute. Your AI client's config ``` { "mcpServers": { "ticketfairy-events": { "type": "http", "url": "https://www.ticketfairy.com/agentic/mcp" } } } ``` ### Agent2Agent The [agent card](https://www.ticketfairy.com/.well-known/agent-card.json) describes the A2A endpoint and its event search skill. ### Manage your own events from an AI assistant To let an assistant create events, change ticket types or read your orders, use the [Ticket Fairy MCP server](https://www.ticketfairy.com/mcp-server) in the [command-line tool](https://www.ticketfairy.com/cli). It runs on your own computer and signs in as you. ## Authentication The event API, the NLWeb endpoint and the public MCP server need no credential. Reads of a person's data and every change need one. ### For your own scripts Create a Personal Access Token in [your account settings](https://manage.ticketfairy.com/account). Send it in the `Authorization: Bearer` header to the organiser API at `https://www.theticketfairy.com/api/`. The token carries your role, so it can reach only the brands you can reach. ### For an AI agent that acts for a person The agent asks the person to approve it in their browser, then gets an OAuth token. [auth.md](https://www.ticketfairy.com/auth.md) describes each step. The OAuth metadata is at `/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource`. ### From the command line Install the CLI with `npm install -g ticketfairy`, then run `ticketfairy login`. Read more on the [CLI page](https://www.ticketfairy.com/cli). ## Machine-readable documents Tools and agents can read these files directly. - [`OpenAPI description`](https://www.ticketfairy.com/api/v1/openapi.json) Every parameter, response field, error and header of the public event API, in OpenAPI 3.1. - [`Versioning and deprecation policy`](https://www.ticketfairy.com/api/v1/versioning.md) What stays stable in v1, and how a retirement is announced with the Deprecation and Sunset headers. - [`API catalog`](https://www.ticketfairy.com/.well-known/api-catalog) The RFC 9727 list of the APIs this site serves. - [`MCP server card`](https://www.ticketfairy.com/.well-known/mcp/server-card.json) The public MCP server, its tool and its event cards view. - [`A2A agent card`](https://www.ticketfairy.com/.well-known/agent-card.json) The Agent2Agent card for public event search. - [`Agent skills`](https://www.ticketfairy.com/.well-known/agent-skills/index.json) Ready-made instructions for finding event tickets and for starting to organise events. - [`auth.md`](https://www.ticketfairy.com/auth.md) How an agent registers and gets a credential for anything beyond public reads. - [`llms.txt`](https://www.ticketfairy.com/llms.txt) A short index of the platform for language models. Ticket Fairy in full: [ticketing platform](https://www.ticketfairy.com/event-ticketing/), with the features, pricing and support behind this page. ## Further Reading [**Best Event Ticketing Software Compared**](https://www.ticketfairy.com/blog/the-best-event-ticketing-software-of-2023-price-and-feature-comparison) [**Early Bird & Tiered Pricing Strategies**](https://www.ticketfairy.com/blog/tiered-pricing-and-early-bird-strategies-for-festivals) [**Using Ticketing Data to Improve Your Events**](https://www.ticketfairy.com/blog/how-to-use-ticketing-data-and-analytics-to-improve-your-festival) ## Questions about the API? Email [support@theticketfairy.com](mailto:support@theticketfairy.com) with the request you sent and the response you got. [Open the OpenAPI description](https://www.ticketfairy.com/api/v1/openapi.json) [Create a free account](https://manage.ticketfairy.com/welcome) --- This page is on Ticket Fairy, a ticketing, marketing and operations platform for live events and the venues that host them: festivals, club nights, concerts, conferences and tours, and night clubs, beach clubs and concert venues. It grows revenue with fan rewards that turn an audience into a sales channel, and runs the money side with payments and payouts, Vault business banking, and working capital advanced against ticket sales. [How Ticket Fairy ticketing works](https://www.ticketfairy.com/event-ticketing) ยท [Ticket Fairy for AI assistants](https://www.ticketfairy.com/llms.txt)