These endpoints read the venues in the production, each with its rooms, and let you add venues and update them.

#GET /venues

This endpoint returns every venue, or the ones that match your filter.

curl "https://confirmed.show/api/v1/spectrum/venues?name=cellar" \
  -H "Authorization: Bearer <token>"

You get back an array of venues, each with its rooms.

[
  {
    "id": "5c9g",
    "name": "The Comedy Cellar",
    "country": "United Kingdom",
    "city": "London",
    "address": "1 Funny Street",
    "postcode": "W1 2AB",
    "description": "A basement club a minute from the station",
    "parking": "Pay and display on the next street",
    "public_transport": "Two minutes from the Tube",
    "phone_number": "+44 20 7946 0000",
    "tz": "Europe/London",
    "latitude": 51.5136,
    "longitude": -0.1365,
    "utc_offset_minutes": 60,
    "rooms": [
      {
        "id": "bpjj",
        "name": "Main Room",
        "description": "Basement room off the high street",
        "capacity": 120,
        "wheelchair_access": true,
        "green_room": true,
        "di_box": false,
        "projector_info": "Projector and screen behind the stage"
      }
    ]
  }
]

#GET /venues/{venue_id}

This endpoint returns one venue, in the same shape as the list. If no venue has that id, you get a 404.

curl https://confirmed.show/api/v1/spectrum/venues/5c9g \
  -H "Authorization: Bearer <token>"

#POST /venues

This endpoint adds a venue, the way Add new venue does in Confirmed. It needs a read-write key.

When you add a venue in Confirmed, a map lookup fills in its timezone and coordinates. Through the API you send them yourself, so name, tz, latitude and longitude are all required. Confirmed uses the timezone to put show times in the right place, and the coordinates to warn you when an act is booked at two venues too far apart to make both.

curl -X POST https://confirmed.show/api/v1/spectrum/venues \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "The Comedy Cellar",
    "country": "United Kingdom",
    "city": "London",
    "address": "1 Funny Street",
    "postcode": "W1 2AB",
    "tz": "Europe/London",
    "latitude": 51.5136,
    "longitude": -0.1365,
    "rooms": [
      { "name": "Main Room", "capacity": 120, "wheelchair_access": true },
      { "name": "Studio", "capacity": 40 }
    ]
  }'

You get the new venue back with a 201, rooms and their ids included. A venue you add without rooms gets one room called Performance space, the same as in Confirmed.

Every venue you add this way has created_by_api_key, so you and your team can tell it apart from the ones added in Confirmed. key is the first four characters of the key that made the call, and description is what the key was called at the time.

#Fields you can write

Rooms take name, description, capacity, wheelchair_access, green_room, di_box and projector_info, as listed under Room fields.

A field name we don't recognise comes back as a 422 rather than being ignored.

#PUT /venues/{venue_id}

This endpoint updates a venue. It needs a read-write key, and takes the same fields as POST /venues, apart from rooms. We only change the fields you send, and null clears one.

To change rooms, you have two more fields:

curl -X PUT https://confirmed.show/api/v1/spectrum/venues/5c9g \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "parking": "Free after 6pm on the next street",
    "room_updates": { "bpjj": { "capacity": 140 } },
    "new_rooms": [ { "name": "Bar", "capacity": 30 } ]
  }'

You get the updated venue back. If no venue has that id, you get a 404, and a room id that isn't at the venue comes back as a 422.

You can't remove a room through the API, since shows may be booked into it. You can do that in Confirmed.

#Venue fields

#Room fields

Any field without a value comes back as null.

#Errors