---
title: "Events"
description: "Create events from published charts, read live counts, update metadata and chart snapshots, and manage the event lifecycle."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.seatlayer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

An event is an immutable seating snapshot plus live inventory. Create it from a
published chart, sell against its event key, and update the snapshot deliberately
when the source chart changes.

> **Chart and event are different resources**
>
> Editing or publishing a chart does not silently change an event that already
> has live state. SeatLayer protects booked and held labels when you request an
> event-map update.

## Create an event

**POST /v1/events** — Authentication: Secret key or dashboard session

```bash title="Create an event"
curl -sX POST "https://api.seatlayer.io/v1/events" \
  -H "authorization: Bearer $SEATLAYER_SECRET_KEY" \
  -H "content-type: application/json" \
  -H "idempotency-key: event_order_8271" \
  -d '{
    "chartId": "chart_abc",
    "name": "Opening Night",
    "slug": "opening-night",
    "startsAt": 1767204000000,
    "venue": "Main Hall",
    "externalRef": "show_8271",
    "currency": "GBP"
  }'
```

The chart must be published and belong to an active workspace. A live event
requires a positive credit balance; test events do not consume credits.

| Field | Type | Required | Behavior |
|---|---|---|---|
| `chartId` | `string` | Yes | Published source chart |
| `name` | `string` | No | Defaults to chart name |
| `slug` | `string` | No | 3–64 lowercase letters, digits, `_`, or `-`; becomes event key |
| `startsAt` | `number` | No | Epoch milliseconds |
| `venue` | `string` | No | Venue label |
| `mode` | `"live" \| "test"` | No | Session calls only; a secret key's mode wins |
| `externalRef` | `string` | No | Host identifier, at most 128 characters |
| `currency` | `string \| null` | No | Three-letter event override; otherwise org currency |

A successful response is `201 {"meta": EventMeta}`. Event creation supports
`Idempotency-Key`; retry the same logical create with the same key and body.

## List and retrieve

**GET /v1/events** — Authentication: Secret key or dashboard session

Use `workspaceId` to select an active workspace and `externalRef` to find the
event belonging to a host record:

```bash
curl -s \
  "https://api.seatlayer.io/v1/events?workspaceId=ws_main&externalRef=show_8271" \
  -H "authorization: Bearer $SEATLAYER_SECRET_KEY"
```

The response includes `events[]`, with cached metadata, `mode`, `sold`, and live
`counts` where available.

**GET /v1/events/:key** — Authentication: Secret key or dashboard session

The detail response contains:

```json
{
  "meta": {
    "key": "opening-night",
    "name": "Opening Night",
    "chartId": "chart_abc",
    "status": "active",
    "seatTotal": 1200,
    "mode": "live",
    "workspaceId": "ws_main",
    "externalRef": "show_8271",
    "currency": "GBP",
    "sold": 412,
    "inventoryModelVersion": 2
  },
  "counts": {
    "free": 760,
    "held": 8,
    "booked": 412,
    "blocked": 20
  },
  "holdTtlMs": null,
  "chartUpdate": {
    "behind": false,
    "canAutoUpdate": false
  }
}
```

`holdTtlMs: null` means the default 15-minute hold window applies.

## Update metadata and section state

**PATCH /v1/events/:key** — Authentication: Secret key or dashboard session

Send only the fields to change:

```json
{
  "name": "Opening Night — Rescheduled",
  "startsAt": 1767290400000,
  "venue": "Main Hall",
  "externalRef": "show_8271",
  "currency": "GBP",
  "sectionStates": {
    "sec-balcony": "hidden",
    "sec-stalls": "open"
  }
}
```

`startsAt`, `venue`, `externalRef`, and `currency` can be cleared with `null`.
Section and zone states are `open`, `closed`, or `hidden`; unknown ids return
`422`. An empty patch returns `400 nothing_to_update`.

For timed and demand-triggered section release, use
[inventory and availability](/server-api/inventory).

## Update an event to the latest chart

Publishing a changed chart reports whether existing events refreshed
automatically or need a manual update. Pristine events can refresh without
inventory risk. Events with live state require the explicit route:

**POST /v1/events/:key/update-chart** — Authentication: Secret key or dashboard session

```bash
curl -sX POST \
  "https://api.seatlayer.io/v1/events/opening-night/update-chart" \
  -H "authorization: Bearer $SEATLAYER_SECRET_KEY"
```

If a booked or held label would disappear, the update fails atomically:

```json
{
  "error": "seats_would_vanish",
  "code": "seats_would_vanish",
  "missingLabels": ["A-12"],
  "message": "The update would remove booked or held seats."
}
```

Archived and deleted events are not mutable. Never work around a conflict by
recreating the event; reconcile the affected chart labels and retry.

## Lifecycle

| Operation | Route | Buyer sales | Organizer reads/actions |
|---|---|---|---|
| Close | `POST /:key/close` | Stopped | Available |
| Reopen | `POST /:key/reopen` | Resumed | Available |
| Archive | `POST /:key/archive` | Stopped | Reports remain available |
| Soft delete | `DELETE /:key` | Stopped | Removed from normal event list |

Use close for a reversible pause. Archive after the event ends; SeatLayer writes
a durable inventory snapshot and keeps the live store for reports. Delete is a
soft delete rather than immediate physical erasure.

Supported application transitions are:

```text
active -> closed -> active
active or closed -> archived
active, closed, or archived -> deleted
```

## Errors to handle

| Status | Code | Action |
|---|---|---|
| `402` | `insufficient_credits` | Top up before creating a new live event |
| `404` | `chart_not_found` / `not_found` | Check org, workspace, and resource id |
| `409` | `event_exists` | Use a new slug or replay the original idempotent request |
| `409` | `seats_would_vanish` | Reconcile protected labels |
| `422` | `chart_not_published` | Publish the chart first |
| `422` | `invalid_event_inventory` | Fix the chart validation issue |
| `422` | `workspace_not_found_or_disabled` | Select or enable the workspace |

## Verification

- [ ] Event creation has a stable idempotency key.
- [ ] Host records store the returned event key and workspace id.
- [ ] Test and live resources use matching secret-key modes.
- [ ] The event's currency, name, start time, and external reference are checked.
- [ ] Chart updates are tested with booked and held inventory.
- [ ] Close, archive, and delete are explicit operator actions.

Continue to [inventory](/server-api/inventory),
[booking](/server-api/booking), and [reports](/server-api/reports).

Source: https://docs.seatlayer.io/server-api/events/index.mdx