# API reference

This is the complete reference for the TicketConnect White-Label API. Every
endpoint lives under the `/v1` prefix and is automatically scoped to your
account. The API is a plain REST + JSON service modeled closely on Stripe, so if
you have integrated Stripe before this will feel familiar.

## Base URL

```text
https://api.ticketconnect.example/v1
```

Replace the host with the environment you were issued. All paths below include
the `/v1` prefix.

## Authentication

Send your secret key as a bearer token on every request except the public meta
endpoints (`/v1/health`, `/v1/openapi.json`, `/v1/docs`):

```text
Authorization: Bearer sk_test_your_key_here
```

The key is also accepted in an `x-api-key` header as a fallback. Use
`sk_test_…` keys against the sandbox and `sk_live_…` keys against
production; the two are fully isolated. Keys are **scoped** — each endpoint
documents the scope it requires (for example `events:read`). A wildcard `*`
scope satisfies any check. Calling an endpoint without the required scope
returns a `403` with type `authorization_error` and code `forbidden`. See
[Authentication](#authentication) for how to manage keys
and scopes. Hosted-checkout endpoints are the one exception to the secret-key
rule: they authenticate with browser-safe publishable `pk_…` keys instead (see
[Payments](#api-payments)).

## Response & error envelope

Successful responses return the resource object directly. Most resources carry
an `object` discriminator (for example `"object": "payout"`).

Errors always use one consistent envelope:

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "name is required.",
    "param": "name"
  }
}
```

| Field | Description |
| --- | --- |
| `type` | High-level category: `invalid_request_error`, `authentication_error`, `authorization_error`, `rate_limit_error`, `idempotency_error`, or `api_error`. |
| `code` | Machine-readable code, e.g. `parameter_missing`, `resource_missing`, `insufficient_balance`. |
| `message` | Human-readable explanation. |
| `param` | The offending request field, when applicable. |
| `request_id` | Request correlation id, when available — quote it in support requests. |

See [Errors](#errors) for the full catalog of codes and statuses.

## Pagination

List endpoints are cursor-based and return a Stripe-style list envelope:

```json
{
  "object": "list",
  "data": [ { "...": "..." } ],
  "has_more": true
}
```

| Query param | Type | Description |
| --- | --- | --- |
| `limit` | integer | Page size, `1`–`100`. Defaults to `20`. |
| `starting_after` | string | An object id; returns items created before it. |

To page forward, pass the `id` of the last item in `data` as `starting_after` on
the next request. Keep paging while `has_more` is `true`.

## Idempotency

Mutating `POST` requests accept an `Idempotency-Key` header. If you retry a
request with the same key, the API returns the original response instead of
performing the action twice. Replays are honored for 24 hours. See
[Idempotency](#idempotency).

```text
Idempotency-Key: a1b2c3d4-...
```

## Money

All amounts are in your account's settlement currency (fiat) and are expressed
in **major units** (for example `49.99`, not `4999`). Prices are always computed
server-side from the event/tier; a client-supplied amount is never trusted. See
[Money and currencies](#money-and-currencies).

## Resource groups

| Group | Endpoints |
| --- | --- |
| [Meta](#api-meta) | Health probe, OpenAPI document (public). |
| [Account](#api-account) | Retrieve the authenticated account; mint, list, and revoke API keys. |
| [Events](#api-events) | Create, list, and update events, tiers, media, and organizations; on-sale waiting room (queue). |
| [Tickets](#api-tickets) | Issue, list, transfer, refund, revoke, and upgrade tickets; hosted delivery links. |
| [Customers](#api-customers) | Create and retrieve customers. |
| [Segments](#api-segments) | Behavioral customer segments — repeat buyers, attendees, no-shows. |
| [Comps](#api-comps) | Complimentary tickets and per-event guest lists. |
| [Reserved seating](#api-seating) | Seat maps, atomic seat holds, seat-bound issuance. |
| [Similar events](#api-similar) | Closest matches from your own catalog, scored. |
| [Payments](#api-payments) | Create and retrieve payment intents. |
| [Marketplace](#api-marketplace) | List and retrieve resale listings. |
| [Reports](#api-reports) | Per-tier sales and attendance reports, with CSV download. |
| [Scanning](#api-scanning) | Validate tickets and record check-in. |
| [Discounts](#api-discounts) | Manage discount codes. |
| [Webhooks](#api-webhooks) | Manage endpoints, ping them, and inspect deliveries. |
| [Payouts](#api-payouts) | Connect onboarding, balance, and payouts. |

## Interactive reference

A live, try-it-out Swagger UI is hosted at **`/v1/docs`**, backed by the
machine-readable OpenAPI 3.0 document at **`/v1/openapi.json`**. Import the
OpenAPI document into Postman or use it for client/SDK code generation.