--- title: "Ticket Fairy Developers | API, SDK, 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 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. Start with an example request you can copy, then find every public endpoint and its limits. [Read the event API](#public-api) [Open the OpenAPI description](https://www.ticketfairy.com/api/v1/openapi.json) You can read public events without an account. To change events, you need a credential, described under Authentication. Your first request ```sh $ curl 'https://www.ticketfairy.com/api/v1/events/listing?search=festival§ion_type=upcoming&sort=start_date&order=asc&size=20' ``` You need no key or sign-in, and you get JSON back. ## Developer documentation Start with the page for what you are building. - [Public event API](#public-api) Read live public events with no key, and get several at once. - [What AI agents can do](https://www.ticketfairy.com/agents) Every agent capability in one list, from event search to ticket checkout over ACP, UCP, MPP and x402, with its status. - [AI agents](https://www.ticketfairy.com/developers/ai-agents) Connect an agent with MCP servers, Agent2Agent, NLWeb, WebMCP, agent skills, Markdown pages and discovery files. - [Authentication](https://www.ticketfairy.com/developers/authentication) Get the right credential: a Personal Access Token, agent approval, OAuth with PKCE or application credentials for agent platforms. - [Ticket Fairy API](https://www.ticketfairy.com/developers/organiser-api) Create events with safe retries, read sales, copy an event's setup, hand a draft event to an event organizer and sign up new event organizers. - [Agent checkout](https://www.ticketfairy.com/developers/agent-checkout) Let a shopping agent sell tickets and take payment over ACP or UCP, then help the buyer with their order. - [Order webhooks](https://www.ticketfairy.com/developers/webhooks) Receive every order at your own address as it changes. - [Ticket Fairy CLI](https://www.ticketfairy.com/cli) Manage events from the terminal or a script. - [MCP server for your account](https://www.ticketfairy.com/mcp-server) Let the AI assistant you use manage your own events. ## Public event API Get live public events from `GET https://www.ticketfairy.com/api/v1/events/listing` with no credential. Every parameter is optional. ### Example response 200 OK, application/json ```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 find. With the default sort by start date, the words are matched as whole words, with tolerance for typos, in the event name, brand, venue, city and short description. With `sort=created_at` or `sort=updated_at`, or while the search index cannot answer, any part of the event, brand or venue name matches. | 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 ```sh $ curl 'https://www.ticketfairy.com/api/v1/events/listing?search=festival§ion_type=upcoming&sort=start_date&order=asc&cursor=NEXT_CURSOR' ``` ### Get several events in one request To read events you already have links for, send up to 25 links or slugs in one request to `POST https://www.ticketfairy.com/api/v1/events/batch`, instead of one request for each. Each link gets its own result, in the order you sent them: `found` with the event, `not_found` or `invalid_link`. You need no credential. If your app opens one native event link at a time, call `GET https://www.ticketfairy.com/api/v1/events/resolve-link` with the decoded slug. It returns the same public event details as the listing API. Several events ```sh $ curl -X POST 'https://www.ticketfairy.com/api/v1/events/batch' -H 'Content-Type: application/json' -d '{"events": ["summer-festival", "https://www.ticketfairy.com/event/winter-ball"]}' ``` ### 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 Your integration stays compatible as version 1 grows. The version is in the path, and 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. ## Sandbox / test environment Try API requests with synthetic data before connecting an agent to your live events. No account or API key is needed. You can test without touching live events at . You get sample event listings and a simulated draft, and your requests never read or change live business data. Drafts are discarded, so you can repeat a request as often as you like and never need to reset anything. ```sh curl 'https://www.ticketfairy.com/sandbox/api/v1/events/listing' ``` For a draft request and validation-error examples, follow the [sandbox instructions](https://www.ticketfairy.com/sandbox/) or use the [sandbox OpenAPI document](https://www.ticketfairy.com/sandbox/openapi.json). You can use the sandbox to check the format of your requests and responses. It does not simulate stored events, authentication, permissions, full production validation, setup copies, checkout, payments or webhook delivery. Keep `/sandbox` in the base URL for every test. ## Ask in plain language You can ask a question about upcoming events in plain language and get matching events back from `https://www.ticketfairy.com/ask`, with the NLWeb protocol, version 0.55. You need no credential, and each client address can send 60 questions a minute. ### Get the answer as JSON Terminal ```sh $ curl 'https://www.ticketfairy.com/ask?query=jazz+in+Melbourne' ``` When your question includes words such as *tonight*, *this weekend* or *next month*, the answer lists only 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 ```text $ 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} ``` ## Ticket Fairy SDKs You can sell tickets on your own website or in your own app with the two Ticket Fairy checkout SDKs on npm, and work with your events from Python and Go with the API clients. ### React checkout SDK You can add a checkout with no Ticket Fairy branding to your own React website. Install it with `npm install tf-checkout-react`. See the [tf-checkout-react package on npm](https://www.npmjs.com/package/tf-checkout-react). ### React Native checkout SDK You can sell tickets inside your own iOS or Android app. Payments go through Stripe, with the Stripe React Native SDK. Install it with `npm install tf-checkout-react-native`. The [React Native SDK documentation](https://github.com/theticketfairy/tf-checkout-react-native#readme) lists the setup for each platform. See also the [tf-checkout-react-native package on npm](https://www.npmjs.com/package/tf-checkout-react-native). ### Python API client Read public event listings from Python with no account. With a personal access token, create events, read an event's sales and copy another event's setup. Install it with `pip install ticketfairy`. See the [ticketfairy package on PyPI](https://pypi.org/project/ticketfairy/). ### Go API client Read public event listings from Go with no account. With a personal access token, create events, read an event's sales and copy another event's setup. Install it with `go get github.com/theticketfairy/ticketfairy-go`. See the [Go package documentation](https://pkg.go.dev/github.com/theticketfairy/ticketfairy-go). ## Connect an AI agent You can let AI agents search public events over the Model Context Protocol and Agent2Agent, with no credential and the same filters as the event API. See [everything an AI agent can do on Ticket Fairy](https://www.ticketfairy.com/agents) in one list, with the status of each capability. ### Public MCP server You can give an AI client event search with `https://www.ticketfairy.com/agentic/mcp`, an MCP server over Streamable HTTP. It has three read-only tools, `search_events`, `get_event` and `ask_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 ```json { "mcpServers": { "ticketfairy-events": { "type": "http", "url": "https://www.ticketfairy.com/agentic/mcp" } } } ``` ### Documentation MCP server You can let your agent answer questions about how to use Ticket Fairy with `https://www.ticketfairy.com/docs/mcp`, a second MCP server. `search_guides` finds the [guides](https://www.ticketfairy.com/guides) for a task, and `get_guide` reads one guide: every step and the common questions. You need no credential, and each client address can send 120 requests a minute. In a client that supports MCP Apps, you can search the guides, select a result and read the complete instructions in the conversation. Text-only clients keep the same tool answers. You can also browse the published catalog with `resources/list` and read a guide as Markdown with `resources/read`. Your AI client's config ```json { "mcpServers": { "ticketfairy-docs": { "type": "http", "url": "https://www.ticketfairy.com/docs/mcp" } } } ``` ### Agent2Agent Read the [agent card](https://www.ticketfairy.com/.well-known/agent-card.json) to connect to the A2A endpoint and its event search skill. ### Agent skills and rules for AI coding agents You can give your coding agent ready-made instructions. The [Ticket Fairy agent skills repository](https://github.com/theticketfairy/agent-skills) on GitHub holds skills for finding event tickets, organizing events and every area of the guides, and an AGENTS.md file that tells Claude Code, Cursor, Codex and other coding agents how to use the API, the MCP server and the command-line tool. Install the skills with `npx skills add theticketfairy/agent-skills`. ### Manage your own events from an AI assistant To let an assistant create events, change ticket types or read your orders, add the hosted event organizer MCP server from the official MCP registry and sign in, or use the [Ticket Fairy MCP server](https://www.ticketfairy.com/mcp-server) in the [command-line tool](https://www.ticketfairy.com/cli), which runs on your own computer. Both sign in as you. Choose the Performance sections and filters you need, or browse one page of orders by status or dispute. The [AI agent documentation](https://www.ticketfairy.com/developers/ai-agents) shows the tool arguments. For event review, sales and orders, or show day, choose a [focused read-only event organizer App](https://www.ticketfairy.com/mcp-server#focused-apps). ### Sell tickets from a shopping agent Your buyers can buy tickets without leaving your shopping agent. It holds their tickets in a checkout, takes payment with a Stripe payment token or within an AP2 mandate, and helps them with refunds and transfers afterwards, over the Agentic Commerce Protocol or the Universal Commerce Protocol. Read the [agent checkout documentation](https://www.ticketfairy.com/developers/agent-checkout). ### Help a ticket buyer with their own tickets You can build an assistant that reads a ticket buyer's own orders and tickets and talks to Ticket Fairy's assistant for them, over the Personal Agent Protocol. The buyer signs in to Ticket Fairy and approves read access. Read the [personal agent section](https://www.ticketfairy.com/developers/ai-agents#personal-agents) of the AI agent documentation. Read the [AI agent documentation](https://www.ticketfairy.com/developers/ai-agents) for every way an agent connects, including WebMCP in the browser, Markdown pages and the discovery files. ## Authentication You need no credential for the event API, the NLWeb endpoint and the public MCP servers. You need one to read a person's data or to change anything. ### For your own scripts You can create a Personal Access Token in [your account settings](https://manage.ticketfairy.com/account). Send it in the `Authorization: Bearer` header to the Ticket Fairy API at `https://www.theticketfairy.com/api/`. The token carries your role, so your script reaches only the brands you can reach. The [Ticket Fairy API description](https://www.theticketfairy.com/api/openapi.json) shows how to create an event and read its sales. Send an `Idempotency-Key` header when you create an event, so a retry after a network error does not create it twice. ### For an AI agent that acts for a person Your 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). Read the [authentication documentation](https://www.ticketfairy.com/developers/authentication) to find out how to get a credential, rotate a token or end an agent's access, and the [Ticket Fairy API documentation](https://www.ticketfairy.com/developers/organiser-api) for every operation. ## Order webhooks You get the whole order at your own URL each time it changes: the buyer, every ticket, table and add-on, the money and the checkout answers. You can use it to keep your CRM, access control or reporting up to date. Read the [order webhook documentation](https://www.ticketfairy.com/developers/webhooks) to set up a webhook for a brand, tour or event, check the signature and see every field in the payload, with an example. ## Machine-readable documents Point your tools and agents at these files to read them directly. You can find every discovery file in the [AI agent documentation](https://www.ticketfairy.com/developers/ai-agents#documents). - [`AI catalog`](https://www.ticketfairy.com/.well-known/ai-catalog.json) The Agentic Resource Discovery manifest of the main agent resources, such as the MCP servers, the A2A card and the OpenAPI description. - [`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. - [`Ticket Fairy API description`](https://www.theticketfairy.com/api/openapi.json) Create an event with an Idempotency-Key for safe retries and read its sales, in OpenAPI 3.1. You need a Bearer token. - [`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. - [`Guides MCP server card`](https://www.ticketfairy.com/docs/mcp/server-card) The documentation MCP server, which searches and reads the guides. - [`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, starting to organize events, connecting an event organizer account, using the command-line tool, answering how-to questions, and each area of the guides. - [`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. See how the Ticket Fairy [ticketing platform](https://www.ticketfairy.com/event-ticketing/) helps you sell more tickets, with every feature, the pricing and the support you get. ## Further Reading [**AI agents** MCP servers, Agent2Agent, WebMCP, agent skills and discovery files.](https://www.ticketfairy.com/developers/ai-agents) [**Authentication** Personal Access Tokens, agent approval and OAuth.](https://www.ticketfairy.com/developers/authentication) [**Ticket Fairy API** Create events, read sales and copy an event's setup.](https://www.ticketfairy.com/developers/organiser-api) ## 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)