Shows

Overview

The Shows API lets you read, create and update the shows in a Confirmed production over HTTP. Every endpoint returns JSON.

Pass your API token as a bearer token. Reading takes either kind of key; creating and updating need a read-write one.

GET /shows

Returns the shows starting inside a date window, as an array.

curl "https://your-host/api/v1/spectrum/shows?ts_from=2026-07-01&ts_to=2026-07-31" \
  -H "Authorization: Bearer <token>"

GET /shows/{show_id}

Returns one show. An id that matches nothing comes back as a 404.

curl https://your-host/api/v1/spectrum/shows/nan3 \
  -H "Authorization: Bearer <token>"

The show object

The read endpoints and both update endpoints return shows in this shape. Spots arrive split into hosts, lineup and production, each in running order.

Each spot carries the Slot fields, with whoever is booked under act_id. A spot that has gone into a settlement reads settled: true.

POST /shows

Creates one show per date in dates. They all share the same type, venue, lineup and contacts, so this is how you put a run or a residency in at once.

Leave all three spot lists out and the show arrives with a standard running order: one host, three acts and one production spot. Act spots run ten minutes unless you say otherwise.

curl -X POST https://your-host/api/v1/spectrum/shows \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "dates": ["2026-07-21"],
    "time": "21:00",
    "type": "dmx-madness",
    "production_contacts": ["ejcs"],
    "hosts":  [ { "role": "MC" } ],
    "lineup": [ { "actID": "b9b4" }, {}, {} ],
    "production": [ {}, {} ]
  }'

{ "created": 1, "ids": ["nan3"] }

The slot object

One spot on a show. You use this shape both when you create shows and when you patch spots through spot_updates. A field name we don't recognise comes back as an error rather than being ignored.

PUT /shows

Updates several shows in one call. We check the whole request before writing anything, so if one show in the batch has a problem, none of them change.

{
  "updates": [
    { "id": "<show id>", "changes": { ... } }
  ]
}

Editing spots

spot_updates takes a map of { spot_id: { field: value } }. Each spot you name merges in place: the fields you send land, the rest of that spot stays as it was, and the spots you didn't mention stay as they were. This never replaces the running order. A spot id that isn't on the show comes back as an error.

curl -X PUT https://your-host/api/v1/spectrum/shows \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {
        "id": "nan3",
        "changes": {
          "ts": "2026-07-21 20:00",
          "venue_id": "5c9g",
          "room_id": "bpjj",
          "spot_updates": {
            "a1b2": { "actID": "b9b4", "fee": "150", "status": "confirmed" },
            "c3d4": { "order": 2 }
          }
        }
      }
    ]
  }'

You get the updated shows back as an array.

PUT /shows/{show_id}

Updates one show. The id comes from the path, so the body is the changes themselves, without the updates wrapper. An id that matches nothing comes back as a 404.

curl -X PUT https://your-host/api/v1/spectrum/shows/nan3 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "ts": "2026-07-21 20:00",
    "venue_id": "5c9g",
    "spot_updates": {
      "a1b2": { "fee": "150", "status": "confirmed" }
    }
  }'

You get the updated show back.

Show meta

Every show carries a meta object holding its ticket link and its promotional assets. You can read it from any show endpoint and set it through either update endpoint.

The built-in fields below mean the same thing in every production, so you can rely on their names. A production can add fields of its own under Data & API, and those sit in the same object alongside the built-ins.

Image, video and file fields hold a URL rather than the file itself. Uploading a file below covers how to get one.

A production can switch a built-in off to keep it off the show card. That only changes what the card shows you, and the API goes on reading and writing the field either way.

Reading meta

Every show object carries meta. A show with nothing set on it gives you an empty object rather than leaving the key out.

{
  "id": "nan3",
  "type": "dmx-madness",
  "ts": "2026-07-21 21:00",
  "meta": {
    "tickets_url": "https://tickets.example.com/nan3",
    "promo_image": "https://st.confirmed.show/uploads/spectrum/shows/nan3/A1B2C3-promo.webp",
    "promo_blurb": "One night only."
  }
}

Setting a ticket link

Fields merge one at a time, so naming tickets_url leaves the promo image and everything else on the show untouched. There is no way to replace the whole object at once, which means a ticketing integration can own the link without ever touching the artwork.

curl -X PUT https://your-host/api/v1/spectrum/shows/nan3 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "meta": {
      "tickets_url": "https://tickets.example.com/nan3"
    }
  }'

You can set links across a run of shows in one call:

curl -X PUT https://your-host/api/v1/spectrum/shows \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      { "id": "nan3", "changes": { "meta": { "tickets_url": "https://tickets.example.com/nan3" } } },
      { "id": "p4rt", "changes": { "meta": { "tickets_url": "https://tickets.example.com/p4rt" } } }
    ]
  }'

Send null to clear a field:

{ "meta": { "tickets_url": null } }

Meta can travel alongside any other change in the same call, so you can publish a show and give it its link together:

{
  "public": true,
  "meta": { "tickets_url": "https://tickets.example.com/nan3" }
}

What the values have to be

• Every name has to be a built-in or a field the production has added. We reject anything else rather than creating a field for you, so a typo comes back as an error instead of quietly becoming a new field.

• url, image, video and file fields take a string starting http:// or https://. We trim the whitespace.

• number fields take a number, and boolean fields take true or false.

• Everything else takes text.

Uploading a file

Image, video and file fields store a URL. To put your own file behind one, ask for an upload slot, send the bytes to it, then save the URL you get back. You need a read-write key.

1. Ask for the slot.

curl -X POST "https://your-host/api/v1/spectrum/upload-file?filename=promo.png" \
  -H "Authorization: Bearer <token>"

{
  "upload_url": "https://storage.googleapis.com/...<signed>",
  "file_url": "https://st.confirmed.show/uploads/spectrum/api-uploads/A1B2C3-promo.png"
}

2. Send the file to upload_url. The link lasts fifteen minutes.

curl -X PUT "<upload_url>" \
  -H "Content-Type: image/png" \
  --upload-file promo.png

3. Save file_url on the show.

curl -X PUT https://your-host/api/v1/spectrum/shows/nan3 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "meta": { "promo_image": "https://st.confirmed.show/uploads/spectrum/api-uploads/A1B2C3-promo.png" } }'

Anyone holding the URL can open the file, so treat these as public. We store a picture as it arrives: the preferred dimensions a production sets under Data & API shape the crop box inside Confirmed, and nothing crops on your behalf here, so send the file at the size you want it.

Errors

A 422 covers a field we don't recognise, a venue, act or spot id that doesn't exist, a room that isn't in the venue you named, and a meta value of the wrong sort. These are the ones you're most likely to meet while working with meta:

If something here doesn't behave the way this page describes, write to [email protected] and we'll sort it out.