BetterTicketsAPI Docs

#Authentication & Keys

Every request needs an API key, sent as a Bearer token:

HTTP
GET /api/partner/v1/events HTTP/1.1
Host: app.bettertickets.com
Authorization: Bearer btk_live_…

#Getting a key

Ask your BetterTickets contact for an API key.

  • A key belongs to one BetterTickets account and only ever sees that account's data.
  • Keys start with btk_live_ (live) or btk_test_ (test). Anything else is refused. See Test vs Live.
  • The full key is shown once, when it is issued. Store it in a secret manager or an environment variable on your server, and never commit it to source control.
  • If a key leaks, ask your BetterTickets contact to revoke it and issue a new one.

#Server-to-server only

The API is built for your backend. It does not allow cross-origin browser requests (no Access-Control-Allow-Origin header), so a browser cannot call it, and a key must never ship in a web page, browser extension or mobile app.

For the same reason these docs have no "Try It" console. Use the generated cURL, Node, Python or PHP samples on each operation page from your own server or terminal.

#Scopes

Each operation needs one scope. A key without it gets 403 insufficient_scope, and the required field names the missing scope.

ScopeAllows
events:readGET /events, GET /events/{id}, GET /events/{id}/locations, GET /locations/{id}/availability. Every key has it.
lists:readGET /lists/{id}/rows
lists:writePOST /lists/{id}/rows

List scopes are added to a key on request; ask your BetterTickets contact.

JSON
{ "error": "insufficient_scope", "required": "lists:write" }

#Account access

  • API access must be turned on for your account; otherwise every call answers 403 partner_api_disabled.
  • Custom Lists calls also need Custom Lists enabled on your account (403 partner_lists_disabled) and API Access turned on in that list's settings (403 list_api_disabled). See Custom Lists.
  • If BetterTickets cannot confirm these settings for a moment, the call answers 503 FEATURE_GATE_UNAVAILABLE. Wait Retry-After seconds (5 if the header is missing) and retry. See Retrying.

#Bad keys

A missing key gets 401 missing_api_key. A key that is unknown, revoked, expired or has the wrong prefix gets the same 401 invalid_api_key for every case, so you cannot tell them apart from the response.

401 invalid_api_key always means the key was checked and refused. Do not retry it; ask your BetterTickets contact for a new key.

#When the Key Check Is Unavailable

If BetterTickets cannot check your key for a moment, the call answers 503 auth_unavailable instead of 401. Your key has not been judged invalid, so retry:

HTTP
HTTP/1.1 503 Service Unavailable
Retry-After: 5
Content-Type: application/json

{
  "error": "auth_unavailable",
  "message": "API key check is temporarily unavailable. Retry after Retry-After seconds.",
  "retryable": true,
  "retry_after_seconds": 5
}

Wait Retry-After seconds between attempts and cap the number of attempts. Retrying faster gets 429 partner_rate_limited. See Retrying.