Quick start
The base URL is https://ticketsmart.ai/api/v1. Send your API key in the x-api-key request header.
curl "https://ticketsmart.ai/api/v1/events?limit=5" \
-H "x-api-key: ts_sk_live_your_key"A successful response returns { "events": [...], "pagination": {...} }. Prices are integer cents, so 2500 means $25.00.
Authentication
Create keys per box office
Open Dashboard > Box Offices > Settings > API Keys. A key is shown once when created and starts with ts_sk_. Each box office can have up to 10 active keys.
Keep keys server-side
Do not ship API keys in public browser JavaScript. The v1 API supports CORS for integrations, but the key is still a secret for your box-office data.
Use scopes
events:read can list and inspect events. events:write can create and patch events. New keys default to both scopes unless you choose a narrower set.
Use one workspace at a time
A key is scoped to the box office where it was created. It cannot read or write another box office's events.
Rotate by revoking
Keys can be revoked from the same API Keys screen. Once revoked, a key immediately stops authenticating v1 requests.
Plan retries carefully
GET requests are safe to retry. POST and PATCH requests are not idempotent in v1, so do not blindly retry writes after a timeout without checking the resulting event state.
Endpoints
/api/v1/eventsevents:readList events for the key's box office. Supports status, search, dateFrom, dateTo, liveOnly, page, and limit query parameters. limit is capped at 100.
/api/v1/eventsevents:writeCreate an event, optionally with ticket types in the same request. Status changes are not accepted on this endpoint.
curl -X POST "https://ticketsmart.ai/api/v1/events" \
-H "x-api-key: ts_sk_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"title": "Comedy Night",
"startsAt": "2026-09-01T19:00:00Z",
"timezone": "America/New_York",
"venueName": "Main Room",
"city": "New York",
"country": "US",
"currency": "USD",
"visibility": "PUBLIC",
"category": "COMEDY",
"ticketTypes": [
{ "name": "General Admission", "price": 2500, "quantity": 120 }
]
}'/api/v1/events/{idOrSlug}events:readFetch one event by ID or slug, including ticket types and public URL.
/api/v1/events/{idOrSlug}events:writeUpdate event fields, add one ticket type, or remove an unsold ticket type. Publishing, cancellation, orders, refunds, and status changes are not exposed in v1.
{
"title": "Late Show",
"slug": "late-show",
"addTicketType": { "name": "VIP", "price": 4500, "quantity": 20 }
}/api/v1/events/{idOrSlug}/ticket-typesevents:readList ticket types with prices, quantities, sale windows, per-order limits, hidden state, and current availability.
/api/v1/events/{idOrSlug}/availabilityevents:readReturn the compact live availability shape for external websites and inventory sync jobs.
Payloads and data rules
Required create fields
title and startsAt are required. startsAt, endsAt, and doorsOpen must be ISO-8601 datetimes.
Ticket prices
Ticket type price is stored in cents as an integer. Free tickets use 0. Currency defaults to USD and must be a three-letter code.
Event filters
status accepts DRAFT, PUBLISHED, SOLD_OUT, CANCELLED, COMPLETED, or ARCHIVED. dateFrom and dateTo must be ISO-8601 datetimes.
Event visibility
visibility accepts PUBLIC, UNLISTED, or PRIVATE. category accepts COMEDY, MUSIC, CONFERENCE, WORKSHOP, THEATER, SPORTS, or OTHER.
CORS
The v1 API responds to OPTIONS preflight requests and includes CORS headers for external integrations.
Access-Control-Allow-Origin
*Access-Control-Allow-Methods
GET, POST, PATCH, OPTIONSAccess-Control-Allow-Headers
Content-Type, x-api-keyCORS support does not make API keys safe for browser exposure. Proxy requests through your server when the caller is an end-user browser.
Errors
Error responses include an error message. Validation and authorization responses can include extra fields such as details, hint, missingScopes, or retryAfter.
Invalid JSON, invalid filters, unsupported status changes, or schema validation failure.
{ "error": "Validation failed", "details": [...] }Missing, malformed, revoked, or unknown API key.
{ "error": "Unauthorized", "hint": "Send your API key in the x-api-key request header" }The key is valid but does not have the required scope.
{ "error": "Forbidden", "missingScopes": ["events:write"] }The event was not found in the key's box office.
{ "error": "Event not found" }A requested slug is already in use.
{ "error": "Slug is already taken" }A requested ticket-type removal cannot be completed because tickets have sold.
{ "error": "Cannot remove a ticket type that has sold tickets" }The per-key rate limit was exceeded. Respect the Retry-After header before retrying.
{ "error": "Rate limit exceeded. Try again later.", "retryAfter": 60 }Limits
Per API key rolling 60-second window
60 req / minpage starts at 1; limit accepts 1-100
100 maxMaximum active API keys per box office
10 keysPOST and PATCH do not accept idempotency keys in v1
check firstNeed help or a broader API surface?
The public v1 API currently focuses on event creation, event updates, ticket type reads, and availability sync. Contact support if you need webhooks, checkout/order APIs, SDKs, an OpenAPI schema, higher limits, or early access to additional endpoints.