{"openapi":"3.1.0","info":{"title":"StageBuilder Pro API","version":"1.0.0","description":"Read and edit your StageBuilder Pro stage plots. Authenticate with a personal API key (Account → Agents & API) sent as \"Authorization: Bearer sbp_…\". Included with Pro and Elite. The same operations are available as an MCP server at /mcp."},"servers":[{"url":"https://stagebuilderpro.com/api/v1"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"Personal API key, sbp_…"}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}},"paths":{"/me":{"get":{"operationId":"whoami","summary":"Who am I","description":"The account this API key belongs to and its plan.","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/catalog":{"get":{"operationId":"search_catalog","summary":"Search the gear catalog","description":"Find item types to place: speakers, consoles, lights, LED walls, risers, drum kits, amps, keyboards, mic stands, people, and so on. Returns the type id add_items needs, real-world size in feet, whether it flies, and the input-list channels it brings. Search by gear words (\"wedge\", \"fender twin\", \"drum riser\"); leave query empty to browse a department.","parameters":[{"name":"query","in":"query","required":false,"schema":{"type":"string","maxLength":80,"description":"Words to match against item names and ids."}},{"name":"department","in":"query","required":false,"schema":{"type":"string","enum":["audio","lighting","video","staging","instruments","people","misc","labels"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"description":"Default 25."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/templates":{"get":{"operationId":"list_templates","summary":"List plot templates","description":"Ready-made starting plots (3/4/5-piece band, DJ…) that create_plot can copy.","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/plots":{"get":{"operationId":"list_plots","summary":"List my plots","description":"Stage plots this account owns or collaborates on, most recently edited first, with your role on each (owner, editor or viewer).","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"create_plot","summary":"Create a plot","description":"Start a new stage plot: an empty stage of the given size, or a copy of a template from list_templates. Returns the new plot.","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"stage":{"type":"object","description":"Stage deck size in feet. Default 32 × 24, 2 ft high. Ignored when a template is given.","properties":{"width":{"type":"number"},"depth":{"type":"number"},"height":{"type":"number"}},"additionalProperties":false},"template":{"type":"string","maxLength":64,"description":"Template id from list_templates."}},"required":["name"],"additionalProperties":false}}}}}},"/plots/{plot_id}":{"get":{"operationId":"get_plot","summary":"Get a plot","description":"A plot's stage size, named stage positions, and every item with its id, type, label, position, rotation and size. All distances are feet. Origin is centre stage. +x = stage left (performer's left), −x = stage right, −z = upstage, +z = downstage toward the audience. Rotation is degrees about the vertical axis. Heights are worked out automatically: gear rests on whatever is under it (decks, risers, tables); flown items stay at trim height unless you give an elevation.","parameters":[{"name":"plot_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"detail","in":"query","required":false,"schema":{"type":"string","enum":["full","summary"],"description":"\"summary\" omits the item list. Default \"full\"."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"update_plot","summary":"Rename or resize a plot","description":"Change a plot's name or description, or resize its main stage deck. Gear standing on the deck follows its new height.","parameters":[{"name":"plot_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","maxLength":5000},"stage":{"type":"object","properties":{"width":{"type":"number"},"depth":{"type":"number"},"height":{"type":"number"}},"additionalProperties":false}},"required":[],"additionalProperties":false}}}}},"delete":{"operationId":"delete_plot","summary":"Delete a plot","description":"Move a plot you own to Trash. It can be restored from the editor's Trash for 30 days.","parameters":[{"name":"plot_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/plots/{plot_id}/items":{"post":{"operationId":"add_items","summary":"Add gear to a plot","description":"Place one or more items. Each needs a catalog \"type\" (from search_catalog) and a \"position\". Input-list and output-list rows are added for instruments, mics and speakers just as the editor does. All distances are feet. Origin is centre stage. +x = stage left (performer's left), −x = stage right, −z = upstage, +z = downstage toward the audience. Rotation is degrees about the vertical axis. Heights are worked out automatically: gear rests on whatever is under it (decks, risers, tables); flown items stay at trim height unless you give an elevation. Returns the new items with their ids.","parameters":[{"name":"plot_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","properties":{"type":{"type":"string","maxLength":80,"description":"Catalog type id, e.g. \"wedge_monitor\", \"drum_riser\", \"guitar_amp_fender_twin\"."},"position":{"description":"Where to put it: a stage position name — upstage_left, upstage_center, upstage_right, stage_left, center, stage_right, downstage_left, downstage_center, downstage_right, foh, house_left, house_right (or USL/USC/USR/SL/CS/SR/DSL/DSC/DSR) — laid over the plot's stage, or exact coordinates { \"x\": ft, \"z\": ft }.","anyOf":[{"type":"string","maxLength":40},{"type":"object","properties":{"x":{"type":"number"},"z":{"type":"number"}},"required":["x","z"],"additionalProperties":false}]},"size":{"type":"object","description":"Feet. Only staging (decks, risers, rugs, runways) and walls/drapes/LED walls are resizable — search_catalog marks them \"resizable\".","properties":{"width":{"type":"number"},"height":{"type":"number"},"depth":{"type":"number"}},"additionalProperties":false},"label":{"type":"string","maxLength":120,"description":"Display label, e.g. \"Gtr 1 amp\". Input-list rows follow it."},"notes":{"type":"string","maxLength":2000},"color":{"type":["string","null"],"description":"Hex colour like \"#1a1a1a\"; null restores the default."},"rotation":{"type":"number","description":"Degrees about the vertical axis (absolute, not relative). Wedges default to 180 so they face the performer."},"elevation":{"type":["number","null"],"description":"Feet above the floor to hold the item at (pins its height). null lets it rest on whatever is under it again."},"visible":{"type":"boolean"},"add_to_input_list":{"type":"boolean","description":"false to keep it off the input list. Default true."}},"required":["type","position"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}}},"patch":{"operationId":"update_items","summary":"Move or edit gear","description":"Move, rotate, relabel, recolour, resize, hide or re-note items by id. Only the fields you send change. Items locked in the editor can be relabelled but not moved.","parameters":[{"name":"plot_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"updates":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","properties":{"id":{"type":"string","description":"Item id from get_plot."},"position":{"description":"Where to put it: a stage position name — upstage_left, upstage_center, upstage_right, stage_left, center, stage_right, downstage_left, downstage_center, downstage_right, foh, house_left, house_right (or USL/USC/USR/SL/CS/SR/DSL/DSC/DSR) — laid over the plot's stage, or exact coordinates { \"x\": ft, \"z\": ft }.","anyOf":[{"type":"string","maxLength":40},{"type":"object","properties":{"x":{"type":"number"},"z":{"type":"number"}},"required":["x","z"],"additionalProperties":false}]},"size":{"type":"object","description":"Feet. Only staging (decks, risers, rugs, runways) and walls/drapes/LED walls are resizable — search_catalog marks them \"resizable\".","properties":{"width":{"type":"number"},"height":{"type":"number"},"depth":{"type":"number"}},"additionalProperties":false},"label":{"type":"string","maxLength":120,"description":"Display label, e.g. \"Gtr 1 amp\". Input-list rows follow it."},"notes":{"type":"string","maxLength":2000},"color":{"type":["string","null"],"description":"Hex colour like \"#1a1a1a\"; null restores the default."},"rotation":{"type":"number","description":"Degrees about the vertical axis (absolute, not relative). Wedges default to 180 so they face the performer."},"elevation":{"type":["number","null"],"description":"Feet above the floor to hold the item at (pins its height). null lets it rest on whatever is under it again."},"visible":{"type":"boolean"}},"required":["id"],"additionalProperties":false}}},"required":["updates"],"additionalProperties":false}}}}},"delete":{"operationId":"remove_items","summary":"Remove gear","description":"Delete items by id, along with their input/output-list rows. Anything resting on a removed item drops to what is under it.","parameters":[{"name":"plot_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string"}}},"required":["ids"],"additionalProperties":false}}}}}},"/plots/{plot_id}/inputs":{"get":{"operationId":"get_input_list","summary":"Get the input list","description":"The plot's input list (channel, source, mic/DI, stand, stage position, phantom) and output list (mains, monitors, fills).","parameters":[{"name":"plot_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"update_input_list","summary":"Edit input-list rows","description":"Change input-list rows by channel number: source description, mic/DI, stand, position, phantom power, carried-by-band. Rows you edit stop following their item's label.","parameters":[{"name":"plot_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","minItems":1,"maxItems":200,"items":{"type":"object","properties":{"ch":{"type":"integer","minimum":1},"desc":{"type":"string","maxLength":200},"micDI":{"type":"string","maxLength":200,"description":"Mic or DI, e.g. \"SM57\", \"Beta 52A\", \"Stereo DI\"."},"standNotes":{"type":"string","maxLength":200,"description":"e.g. \"Tall Boom\", \"Short Boom\", \"Clip\"."},"pos":{"type":"string","maxLength":200},"phantom":{"type":"boolean"},"carried":{"type":"boolean","description":"The band brings this mic/DI."}},"required":["ch"],"additionalProperties":false}}},"required":["rows"],"additionalProperties":false}}}}}}}}