Developer Preview. The contract is real and in use; this repository is new.
The API contract for TimTim.Live — the one file that says exactly what the API does — plus things made from it.
Live Demo · Documentation · Sandbox · Developer Access · Community
| Path | What it is | Made how |
|---|---|---|
openapi.yaml |
The contract, OpenAPI 3.1 | Copied byte for byte from TimTim.Live's source of truth (also served at https://timtim.live/partner-api/openapi.yaml) |
schemas/ |
One JSON Schema (2020-12) per object: Event, Category, Location, Earning, Order, TicketType, Offer, Settlement, Problem, Withdrawn |
Generated from openapi.yaml |
examples/ |
Real requests and responses, listed in examples/manifest.json |
live-capture: saved from the live API (calls that need no key). illustrative: hand-written for calls that need a key — the file name says .illustrative. |
postman/timtim-api.postman_collection.json |
A Postman collection | Generated from the contract by scripts/generate.mjs, in folders |
Every example is validated against the contract on every change.
No key needed:
curl "https://api.timtim.live/v1/demo/events?city=Miami&category=music"You get sample events. Every name starts with "TEST EVENT — NO REAL MONEY".
| Ask | Address | Key? |
|---|---|---|
| Events (by city, country, type, dates, artist, near a point) | GET /v1/events |
Yes — or GET /v1/demo/events with no key (sample events) |
| One event, even if cancelled or ended | GET /v1/events/{id} |
Yes |
| Which event types have events | GET /v1/categories |
Yes — or GET /v1/demo/categories |
| Which cities have events | GET /v1/locations |
Yes — or GET /v1/demo/locations |
| Count what visitors saw and clicked (never money) | POST /v1/track |
No |
| Feeds for calendars, RSS, spreadsheets | GET /v1/feeds/{file} |
A website or test key in the address |
| Your results, orders, statements, offers | /v1/earnings, /v1/orders, /v1/settlements, /v1/offers |
A server key or test key |
All at https://api.timtim.live. Every error is plain words in the same shape (application/problem+json).
AI assistants use the same events through an MCP server, not this REST contract: https://api.timtim.live/v1/mcp — steps at https://timtim.live/developers/ai.
- In Postman: Import → choose
postman/timtim-api.postman_collection.json. - Send Start here: sample events (no key). It works with no key.
- Get a free test key (
tt_test_…) at https://timtim.live/partners/dashboard and paste it into the collection variableapiKey. - Work down the folders, top to bottom. They start with Authentication and Search Events, and end with Errors and Earnings.
The Webhooks folder sends correctly signed deliveries to your endpoint (webhookUrl, webhookSecret), so you can test your signature check.
import Ajv2020 from "ajv/dist/2020.js";
import event from "./schemas/Event.schema.json" with { type: "json" };
const validate = new Ajv2020({ strict: false }).compile(event);Each file has an $id. If one schema ever refers to another, it uses a relative $ref like Event.schema.json, so keep the folder together.
npm ci
npm test # = lint + generated files fresh + examples valid
npm run generate # rebuild schemas/ and postman/ after openapi.yaml changes
npm run capture:examples # refresh the live captures (no key needed)
npm run check:contract # is openapi.yaml the one TimTim.Live publishes?Do not edit openapi.yaml here. It is published from TimTim.Live's source of truth. To ask for a change to the API, open an issue — see CONTRIBUTING.md.
- Docs: https://timtim.live/developers/docs
- Quickstart: https://timtim.live/developers/quickstart
- Status: https://timtim.live/developers/status
- SDK: https://github.com/timtimlive/timtim-live-events
- Raw API examples by goal: https://github.com/timtimlive/timtim-api-examples
Report security problems privately: Report a vulnerability on this repository's Security tab. Policy: https://timtim.live/partners/security. See SECURITY.md.
Open-source tools for connecting websites, apps and platforms to TimTim.Live.
SDKs, widgets, adapters, examples and public API specifications.
This code shows events. It does not include TimTim.Live's own servers. Tickets, payments, payouts, fraud checks and everyone's private data stay with TimTim.Live. You reach them through the API.
These tools connect to the hosted TimTim.Live API at:
Open-source licenses for client software do not grant ownership of TimTim.Live event data, API services, commercial rights, certification marks or trademarks.
This description file and everything here: MIT © 2026 timtim-live. Using the API itself is governed by the Partner Terms: https://timtim.live/partners/terms