#Overview

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

The examples send the API token as a bearer token, one of the ways Authentication lists. Creating and updating shows needs a read-write key.

#GET /shows

This endpoint returns the shows that start inside a date window, as an array.

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

#GET /shows/{show_id}

This endpoint returns one show. If no show has that id, you get a 404.

curl https://confirmed.show/api/v1/spectrum/shows/nan3 \
  -H "Authorization: Bearer <token>"

#The show object

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

Each spot has the slot fields, with the id of the person booked in act_id. A spot that's part of a settlement has settled: true.

#POST /shows

This endpoint creates one show for each date in dates. The shows all share the same type, venue, lineup and contacts, so you can add a whole run or residency in one call.

Without any of the three spot lists, the show gets a standard running order: one host, three acts and one production spot. Act spots run ten minutes unless you set a length.

curl -X POST https://confirmed.show/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

A slot is 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

This endpoint 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 is a map of { spot_id: { field: value } }. We merge each spot you name in place, updating the fields you send and leaving the rest of that spot, and every spot you didn't mention, as they were. It never replaces the running order. A spot id that isn't on the show comes back as an error.

curl -X PUT https://confirmed.show/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}

This endpoint updates one show. The id comes from the path, so the body is just the changes, without the updates wrapper. If no show has that id, you get a 404.

curl -X PUT https://confirmed.show/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 has a meta object with its ticket link and 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, which appear in the same object alongside the built-ins. Meta fields lists every field your production has, with its name and type.

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

A production can switch off a built-in field to hide it from the show card. That only changes the show card, and the API still reads and writes the field.

#Reading meta

Every show object has meta. On a show with nothing set, it's an empty object.

{
  "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

We merge meta fields one at a time, so setting tickets_url leaves the promo image and everything else on the show as it was. You can't replace the whole object at once, so a ticketing integration can look after the link without ever touching the artwork.

curl -X PUT https://confirmed.show/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://confirmed.show/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 } }

You can send meta alongside any other change in the same call, for example to publish a show and give it its ticket link at once:

{
  "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 need a string starting http:// or https://. We trim any whitespace.
• number fields need a number, and boolean fields need true or false.
• Everything else accepts text.

#Uploading a file

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

1. Ask for the slot.

curl -X POST "https://confirmed.show/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://confirmed.show/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 with the URL can open the file, so these files are effectively public. Confirmed stores each picture exactly as it arrives and doesn't crop it for you, so it's best to send it at the size you want. The preferred dimensions you set under Data & API only shape the crop box inside Confirmed.

#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 support@confirmed.show and we'll sort it out.