{ "openapi": "3.1.0", "info": { "title": "Muzeek HTTP API", "summary": "Discovery documents plus the authenticated Muzeek Events and Tours APIs. No public unauthenticated write surface.", "description": "Machine-readable discovery (`/llms.txt`, `/sitemap.xml`, this spec) is unauthenticated.\n\nProduct data APIs require an `X-API-Key` (`mzk_live_…`) created in Settings → API & MCP. Named scopes are `read:events`, `write:events`, `read:tours`, and `write:tours`. Write Events includes schedule items on a show.\n\n`POST /mcp` is authenticated Streamable HTTP (Clerk OAuth Connect or API key). Tools are account-scoped. Unauthenticated requests return 401.\n\nEvents, event catalogs, event schedule items, tour catalogs, and tours are the documented resource APIs and the MCP allowlist (plus whoami). GET /api/me returns the same account and connection as whoami, with no catalogue scope.\n\nVersion 1.0.0. URLs are unversioned (`/api/events`). Additive fields are not breaking. A breaking change will use a new version (path or `X-Api-Version`) with Sunset/Deprecation headers and a documented window.\n\nHuman docs: https://muzeek.ai/developers", "version": "1.0.0", "contact": { "name": "Muzeek", "url": "https://muzeek.ai/contact" } }, "servers": [ { "url": "https://muzeek.ai", "description": "Muzeek production" } ], "tags": [ { "name": "Discovery", "description": "Unauthenticated files agents should fetch first." }, { "name": "Events", "description": "Authenticated Events API (`read:events` / `write:events`). Macro shows, not schedule rows." }, { "name": "Event items", "description": "Authenticated Event items API (`read:events` / `write:events`). Rows on an event. List types this Account still has before create. `write:events` covers delete and complete." }, { "name": "Tours", "description": "Authenticated Tours API (`read:tours` / `write:tours`). `write:tours` covers delete." }, { "name": "MCP", "description": "Authenticated Muzeek MCP. Clerk OAuth or API key. Account-scoped tools." } ], "paths": { "/llms.txt": { "get": { "operationId": "getLlmsTxt", "tags": [ "Discovery" ], "summary": "Muzeek llms.txt (when to use, docs links)", "description": "Markdown index for agents: when to use Muzeek, how to call the Events API, MCP, and OpenAPI.", "security": [], "responses": { "200": { "description": "llms.txt markdown", "content": { "text/markdown": { "schema": { "type": "string" } } } } } } }, "/sitemap.xml": { "get": { "operationId": "getSitemapXml", "tags": [ "Discovery" ], "summary": "XML sitemap of indexable marketing/docs URLs", "description": "Does not enumerate tenant calendars or authenticated app routes.", "security": [], "responses": { "200": { "description": "URL set", "content": { "application/xml": { "schema": { "type": "string" } } } } } } }, "/openapi.json": { "get": { "operationId": "getOpenApiSpec", "tags": [ "Discovery" ], "summary": "This OpenAPI 3.1 document", "security": [], "responses": { "200": { "description": "OpenAPI 3.1 JSON", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/mcp": { "get": { "operationId": "getMcpStreamableHttp", "tags": [ "MCP" ], "summary": "Muzeek MCP Streamable HTTP (authenticated)", "description": "Account-scoped MCP. Requires a Clerk OAuth access token (Connect) or an API key. Unauthenticated requests return 401 with WWW-Authenticate pointing at protected-resource metadata. Not a public discovery server.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Streamable HTTP session or JSON-RPC result", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "postMcpStreamableHttp", "tags": [ "MCP" ], "summary": "Muzeek MCP Streamable HTTP JSON-RPC (authenticated)", "description": "Account tools are whoami plus events, event catalogs, schedule items, tour catalogs, and tours. Event and tour tools check read/write scopes. Catalog and schedule-item tools use the same events or tours scopes. whoami has no scope and matches GET /api/me. Clerk OAuth (`*`) or API key. Unauthenticated requests return 401.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" } } } }, "responses": { "200": { "description": "JSON-RPC or Streamable HTTP response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/me": { "get": { "operationId": "getCurrentConnection", "tags": [ "MCP" ], "summary": "Current account and connection (same JSON as MCP whoami)", "description": "Returns the authenticated account UUID and name, connection type and name, the API client UUID when the caller is an API key, and that connection's permissions. Session or API key. No catalogue scope. GET /api/users/me is the signed-in person and stays session-only. OAuth whoami uses connection.type oauth; this HTTP route returns api_key or session.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Current connection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CurrentConnection" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/api/events": { "get": { "operationId": "listEvents", "tags": [ "Events" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "List events in the authenticated account", "description": "Paginated event list. Requires `read:events`. Pass tourId to list shows on a tour. Public IDs are UUIDs. See /developers.", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Page size (max 100 for list views)." }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "startDate", "title", "createdAt" ] } }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Free-text search across event title." }, { "name": "types", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": true, "description": "Repeatable event type keys, e.g. types=show." }, { "name": "tourId", "in": "query", "schema": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." }, "description": "Limit the list to shows on this tour." }, { "name": "include", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated includes: venue, venue.full, tour, tour.full, account, account.full, eventItems. financials, tickets, tickets.full, tickets.live, and lineup are ignored for API keys." } ], "responses": { "200": { "description": "Event list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createEvent", "tags": [ "Events" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Create an event", "description": "Requires `write:events`. `eventType` defaults to `show`; `status` defaults to `private`. Optional `forAccountId` creates the event for a roster member.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventCreateRequest" } } } }, "responses": { "201": { "description": "Created event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/events/{id}": { "get": { "operationId": "getEvent", "tags": [ "Events" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Get one event by UUID", "description": "Requires `read:events`. Same `include` query as list, including `eventItems`. `financials`, `tickets`, and `lineup` includes are session-only and are not attached for API keys.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." } }, { "name": "include", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "updateEvent", "tags": [ "Events" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Partial-update an event", "description": "Requires `write:events`. Send only fields to change.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventUpdateRequest" } } } }, "responses": { "200": { "description": "Updated event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteEvent", "tags": [ "Events" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Permanently delete an event", "description": "Requires `write:events`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventDeleteResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/event-statuses": { "get": { "operationId": "listEventStatuses", "tags": [ "Events" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "List event statuses for this Account", "description": "Selectable statuses for new shows. Hidden and removed rows are omitted. Apply `statusKey` on createEvent and updateEvent. Status and published are separate switches. Requires `read:events`. MCP `listEventStatuses` returns the same JSON.", "responses": { "200": { "description": "event status list", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventStatusCatalog" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createEventStatus", "tags": [ "Events" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Create a event status", "description": "Requires `write:events`. The server allocates a stable key from the name.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventStatusCatalogCreate" } } } }, "responses": { "201": { "description": "Created event status", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EventStatusCatalog" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/event-statuses/{id}": { "get": { "operationId": "getEventStatus", "tags": [ "Events" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Get one event status", "description": "Requires `read:events`. Pass the UUID or the catalog key.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Persisted uniqueId, or the catalog key for a built-in that has no saved row yet." } } ], "responses": { "200": { "description": "event status", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EventStatusCatalog" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "updateEventStatus", "tags": [ "Events" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Update a event status", "description": "Requires `write:events`. Keys are immutable.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Persisted uniqueId, or the catalog key for a built-in that has no saved row yet." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventStatusCatalogUpdate" } } } }, "responses": { "200": { "description": "Updated event status", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EventStatusCatalog" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteEventStatus", "tags": [ "Events" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Remove a event status from new picks", "description": "Requires `write:events`. Existing rows keep the key until edited. Custom rows are removed; built-ins are tombstoned.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Persisted uniqueId, or the catalog key for a built-in that has no saved row yet." } } ], "responses": { "200": { "description": "Removed from new picks", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/event-labels": { "get": { "operationId": "listEventLabels", "tags": [ "Events" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "List event labels for this Account", "description": "Selectable event labels for new shows (not tour types). Apply `labelKeys` on createEvent and updateEvent; the list replaces the set. Requires `read:events`. MCP `listEventLabels` returns the same JSON.", "responses": { "200": { "description": "event label list", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventLabelCatalog" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createEventLabel", "tags": [ "Events" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Create a event label", "description": "Requires `write:events`. The server allocates a stable key from the name.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogNameCreate" } } } }, "responses": { "201": { "description": "Created event label", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EventLabelCatalog" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/event-labels/{id}": { "get": { "operationId": "getEventLabel", "tags": [ "Events" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Get one event label", "description": "Requires `read:events`. Pass the UUID or the catalog key.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Persisted uniqueId, or the catalog key for a built-in that has no saved row yet." } } ], "responses": { "200": { "description": "event label", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EventLabelCatalog" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "updateEventLabel", "tags": [ "Events" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Update a event label", "description": "Requires `write:events`. Keys are immutable.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Persisted uniqueId, or the catalog key for a built-in that has no saved row yet." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogNameUpdate" } } } }, "responses": { "200": { "description": "Updated event label", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EventLabelCatalog" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteEventLabel", "tags": [ "Events" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Remove a event label from new picks", "description": "Requires `write:events`. Existing rows keep the key until edited. Custom rows are removed; built-ins are tombstoned.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Persisted uniqueId, or the catalog key for a built-in that has no saved row yet." } } ], "responses": { "200": { "description": "Removed from new picks", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/event-types": { "get": { "operationId": "listEventTypes", "tags": [ "Events" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "List macro event types for this Account", "description": "Selectable macro event types for shows (not schedule-item types). Apply `eventType` on createEvent and updateEvent. Requires `read:events`. MCP `listEventTypes` returns the same JSON.", "responses": { "200": { "description": "macro event type list", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventTypeCatalog" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createEventType", "tags": [ "Events" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Create a macro event type", "description": "Requires `write:events`. The server allocates a stable key from the name.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeCatalogCreate" } } } }, "responses": { "201": { "description": "Created macro event type", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EventTypeCatalog" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/event-types/{id}": { "get": { "operationId": "getEventType", "tags": [ "Events" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Get one macro event type", "description": "Requires `read:events`. Pass the UUID or the catalog key.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Persisted uniqueId, or the catalog key for a built-in that has no saved row yet." } } ], "responses": { "200": { "description": "macro event type", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EventTypeCatalog" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "updateEventType", "tags": [ "Events" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Update a macro event type", "description": "Requires `write:events`. Keys are immutable.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Persisted uniqueId, or the catalog key for a built-in that has no saved row yet." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeCatalogUpdate" } } } }, "responses": { "200": { "description": "Updated macro event type", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EventTypeCatalog" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteEventType", "tags": [ "Events" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Remove a macro event type from new picks", "description": "Requires `write:events`. Existing rows keep the key until edited. Custom rows are removed; built-ins are tombstoned.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Persisted uniqueId, or the catalog key for a built-in that has no saved row yet." } } ], "responses": { "200": { "description": "Removed from new picks", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/tour-types": { "get": { "operationId": "listTourTypes", "tags": [ "Tours" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "List tour types for this Account", "description": "Selectable tour types (not event labels). Apply `type` on createTour and updateTour. Writes need the Tours add-on. Requires `read:tours`. MCP `listTourTypes` returns the same JSON.", "responses": { "200": { "description": "tour type list", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TourTypeCatalog" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createTourType", "tags": [ "Tours" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Create a tour type", "description": "Requires `write:tours`. The server allocates a stable key from the name.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogNameCreate" } } } }, "responses": { "201": { "description": "Created tour type", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TourTypeCatalog" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/tour-types/{id}": { "get": { "operationId": "getTourType", "tags": [ "Tours" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Get one tour type", "description": "Requires `read:tours`. Pass the UUID or the catalog key.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Persisted uniqueId, or the catalog key for a built-in that has no saved row yet." } } ], "responses": { "200": { "description": "tour type", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TourTypeCatalog" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "updateTourType", "tags": [ "Tours" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Update a tour type", "description": "Requires `write:tours`. Keys are immutable.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Persisted uniqueId, or the catalog key for a built-in that has no saved row yet." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogNameUpdate" } } } }, "responses": { "200": { "description": "Updated tour type", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TourTypeCatalog" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteTourType", "tags": [ "Tours" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Remove a tour type from new picks", "description": "Requires `write:tours`. Existing rows keep the key until edited. Custom rows are removed; built-ins are tombstoned.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Persisted uniqueId, or the catalog key for a built-in that has no saved row yet." } } ], "responses": { "200": { "description": "Removed from new picks", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/tour-statuses": { "get": { "operationId": "listTourStatuses", "tags": [ "Tours" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "List tour statuses for this Account", "description": "Selectable tour statuses. Apply `status` on createTour and updateTour. Writes need the Tours add-on. Requires `read:tours`. MCP `listTourStatuses` returns the same JSON.", "responses": { "200": { "description": "tour status list", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TourStatusCatalog" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createTourStatus", "tags": [ "Tours" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Create a tour status", "description": "Requires `write:tours`. The server allocates a stable key from the name.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogNameCreate" } } } }, "responses": { "201": { "description": "Created tour status", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TourStatusCatalog" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/tour-statuses/{id}": { "get": { "operationId": "getTourStatus", "tags": [ "Tours" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Get one tour status", "description": "Requires `read:tours`. Pass the UUID or the catalog key.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Persisted uniqueId, or the catalog key for a built-in that has no saved row yet." } } ], "responses": { "200": { "description": "tour status", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TourStatusCatalog" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "updateTourStatus", "tags": [ "Tours" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Update a tour status", "description": "Requires `write:tours`. Keys are immutable.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Persisted uniqueId, or the catalog key for a built-in that has no saved row yet." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogNameUpdate" } } } }, "responses": { "200": { "description": "Updated tour status", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TourStatusCatalog" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteTourStatus", "tags": [ "Tours" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Remove a tour status from new picks", "description": "Requires `write:tours`. Existing rows keep the key until edited. Custom rows are removed; built-ins are tombstoned.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Persisted uniqueId, or the catalog key for a built-in that has no saved row yet." } } ], "responses": { "200": { "description": "Removed from new picks", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/tour-labels": { "get": { "operationId": "listTourLabels", "tags": [ "Tours" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "List tour labels for this Account", "description": "Selectable tour labels (not event labels). Apply `labelKeys` on createTour and updateTour. Writes need the Tours add-on. Requires `read:tours`. MCP `listTourLabels` returns the same JSON.", "responses": { "200": { "description": "tour label list", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TourLabelCatalog" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createTourLabel", "tags": [ "Tours" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Create a tour label", "description": "Requires `write:tours`. The server allocates a stable key from the name.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogNameCreate" } } } }, "responses": { "201": { "description": "Created tour label", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TourLabelCatalog" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/tour-labels/{id}": { "get": { "operationId": "getTourLabel", "tags": [ "Tours" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Get one tour label", "description": "Requires `read:tours`. Pass the UUID or the catalog key.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Persisted uniqueId, or the catalog key for a built-in that has no saved row yet." } } ], "responses": { "200": { "description": "tour label", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TourLabelCatalog" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "updateTourLabel", "tags": [ "Tours" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Update a tour label", "description": "Requires `write:tours`. Keys are immutable.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Persisted uniqueId, or the catalog key for a built-in that has no saved row yet." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogNameUpdate" } } } }, "responses": { "200": { "description": "Updated tour label", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/TourLabelCatalog" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteTourLabel", "tags": [ "Tours" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Remove a tour label from new picks", "description": "Requires `write:tours`. Existing rows keep the key until edited. Custom rows are removed; built-ins are tombstoned.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Persisted uniqueId, or the catalog key for a built-in that has no saved row yet." } } ], "responses": { "200": { "description": "Removed from new picks", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/event-item-types": { "get": { "operationId": "listEventItemTypes", "tags": [ "Event items" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "List event-item types for this Account", "description": "Requires `read:events`. Returns the selectable schedule-item types on this Account, including labels, field definitions for `typeSpecificData`, and `id` for catalog writes. Accounts can rename or delete system-provided types; call this instead of assuming keys such as `set_time` or `drive` exist. MCP `listEventItemTypes` returns the same JSON. Clock times stay on `startDate` / `endDate`. Extra per-item fields (not on the type) use `typeSpecificData.custom` plus `typeSpecificData._ui.customFields`.", "responses": { "200": { "description": "Event-item types", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventItemTypeListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createEventItemType", "tags": [ "Event items" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Create a schedule-item type", "description": "Requires `write:events`. Adds a custom schedule-item type (not a show type). Then pass its typeKey as itemType on createEventItem.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeCatalogCreate" } } } }, "responses": { "201": { "description": "Created schedule-item type", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EventTypeCatalog" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/event-item-types/{id}": { "get": { "operationId": "getEventItemType", "tags": [ "Event items" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Get one schedule-item type", "description": "Requires `read:events`. Pass the UUID or the typeKey.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Persisted uniqueId, or the catalog key for a built-in that has no saved row yet." } } ], "responses": { "200": { "description": "Schedule-item type", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EventTypeCatalog" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "updateEventItemType", "tags": [ "Event items" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Update a schedule-item type", "description": "Requires `write:events`. Keys are immutable.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Persisted uniqueId, or the catalog key for a built-in that has no saved row yet." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeCatalogUpdate" } } } }, "responses": { "200": { "description": "Updated schedule-item type", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EventTypeCatalog" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteEventItemType", "tags": [ "Event items" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Remove a schedule-item type from new picks", "description": "Requires `write:events`. Existing items keep the key until edited.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Persisted uniqueId, or the catalog key for a built-in that has no saved row yet." } } ], "responses": { "200": { "description": "Removed from new picks", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/event-items": { "get": { "operationId": "listEventItems", "tags": [ "Event items" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "List schedule items", "description": "Requires `read:events`. Pass eventId to list items on one event. Schedule items are rows on a show (every built-in and custom item type, tasks, and custom fields).", "parameters": [ { "name": "eventId", "in": "query", "schema": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." }, "description": "Parent event UUID." }, { "name": "tourId", "in": "query", "schema": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." } }, { "name": "itemType", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "endDate", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "isTask", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "isCompleted", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } } ], "responses": { "200": { "description": "Schedule item list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventItemListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createEventItem", "tags": [ "Event items" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Create a schedule item on an event", "description": "Requires `write:events`. Attach the item to an existing event UUID. Times use ISO startDate and endDate. itemType must be a typeKey from GET /api/event-item-types for this Account. Accounts can rename or delete system-provided types. Set typeSpecificData using that list's field keys.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventItemCreateRequest" } } } }, "responses": { "201": { "description": "Created schedule item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventItemResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/event-items/{id}": { "get": { "operationId": "getEventItem", "tags": [ "Event items" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Get one schedule item by UUID", "description": "Requires `read:events`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." } } ], "responses": { "200": { "description": "Schedule item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventItemResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "updateEventItem", "tags": [ "Event items" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Update a schedule item", "description": "Requires `write:events`. Partial update.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventItemUpdateRequest" } } } }, "responses": { "200": { "description": "Updated schedule item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventItemResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteEventItem", "tags": [ "Event items" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Delete a schedule item", "description": "Requires `write:events`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventItemDeleteResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/event-items/{id}/complete": { "post": { "operationId": "completeEventItemTask", "tags": [ "Event items" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Complete or reopen a schedule-item task", "description": "Requires `write:events`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventItemCompleteRequest" } } } }, "responses": { "200": { "description": "Updated schedule item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventItemResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/tours": { "get": { "operationId": "listTours", "tags": [ "Tours" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "List tours in the authenticated account", "description": "Paginated tour list. Requires `read:tours`. Public IDs are UUIDs.", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 } }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "startDate", "endDate", "name", "createdAt", "updatedAt", "type", "category", "status" ] } }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "Tour type filter. Comma-separated values are accepted." }, { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "include", "in": "query", "schema": { "type": "string" }, "description": "Comma-separated includes: account, account.full, parentTour, parentTour.full, subTours, subTours.full." } ], "responses": { "200": { "description": "Tour list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TourListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "createTour", "tags": [ "Tours" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Create a tour", "description": "Requires `write:tours`. Required fields are name, startDate, and endDate. type, status, and labelKeys are optional catalog keys; omit them to use the account defaults for new tours. endDate must be after startDate. Shows are attached later with PUT /api/events/{id} tourId.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TourCreateRequest" } } } }, "responses": { "201": { "description": "Created tour", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TourResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/tours/{id}": { "get": { "operationId": "getTour", "tags": [ "Tours" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Get one tour by UUID", "description": "Requires `read:tours`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." } }, { "name": "include", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tour", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TourResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "updateTour", "tags": [ "Tours" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Partial-update a tour", "description": "Requires `write:tours`. Send only fields to change. When both dates are sent, endDate must be after startDate.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TourUpdateRequest" } } } }, "responses": { "200": { "description": "Updated tour", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TourResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "delete": { "operationId": "deleteTour", "tags": [ "Tours" ], "security": [ { "ApiKeyAuth": [] } ], "summary": "Delete a tour", "description": "Requires `write:tours`. There is no separate delete:tours scope.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TourDeleteResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Muzeek API key (`mzk_live_…`) from Settings → API & MCP. `Authorization: Bearer` is also accepted. There is no OAuth token endpoint for this HTTP API. Named scopes: `read:events` and `write:events` for events and schedule items, `read:tours` and `write:tours` for tours. Write covers create, update, and delete." } }, "schemas": { "Uuid": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." }, "ApiError": { "type": "object", "additionalProperties": false, "required": [ "error" ], "properties": { "error": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "examples": [ "UNAUTHORIZED", "FORBIDDEN", "NOT_FOUND", "RATE_LIMITED" ] }, "message": { "type": "string" }, "details": {} } } } }, "CurrentConnection": { "type": "object", "additionalProperties": false, "required": [ "account", "connection", "permissions" ], "description": "Shared by GET /api/me and MCP whoami. Public UUIDs only. connection.id is present only for an API key.", "properties": { "account": { "type": "object", "additionalProperties": false, "required": [ "id", "name" ], "properties": { "id": { "$ref": "#/components/schemas/Uuid" }, "name": { "type": [ "string", "null" ] } } }, "connection": { "type": "object", "additionalProperties": false, "required": [ "type", "name" ], "properties": { "type": { "type": "string", "enum": [ "api_key", "oauth", "session" ] }, "name": { "type": "string" }, "id": { "$ref": "#/components/schemas/Uuid", "description": "API client UUID. Only when type is api_key." } } }, "permissions": { "type": "array", "items": { "type": "string" } } } }, "McpManifest": { "type": "object", "additionalProperties": true, "required": [ "protocolVersion", "serverInfo" ], "properties": { "protocolVersion": { "type": "string" }, "capabilities": { "type": "object", "additionalProperties": true }, "serverInfo": { "type": "object", "required": [ "name", "version" ], "properties": { "name": { "type": "string" }, "title": { "type": "string" }, "version": { "type": "string" } } }, "instructions": { "type": "string" } } }, "JsonRpcRequest": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": {}, "method": { "type": "string" }, "params": { "type": "object", "additionalProperties": true } } }, "JsonRpcResponse": { "type": "object", "required": [ "jsonrpc" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": {}, "result": { "additionalProperties": true }, "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } } } } }, "Event": { "type": "object", "additionalProperties": true, "required": [ "id", "title", "startDate", "endDate", "timezone", "isAllDay" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "eventType": { "type": "string", "description": "Macro type key (e.g. show)." }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "timezone": { "type": "string", "description": "IANA timezone." }, "isAllDay": { "type": "boolean" }, "isPublished": { "type": "boolean" }, "status": { "type": "string" }, "capacity": { "type": [ "integer", "null" ] }, "imageUrl": { "type": [ "string", "null" ] }, "venueId": { "type": [ "string", "null" ], "format": "uuid" }, "tourId": { "type": [ "string", "null" ], "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "venue": { "type": [ "object", "null" ], "additionalProperties": true }, "tour": { "type": [ "object", "null" ], "additionalProperties": true }, "eventItems": { "type": "array", "items": { "$ref": "#/components/schemas/EventItem" }, "description": "Present when include=eventItems." } } }, "EventCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "title", "startDate", "endDate", "timezone", "isAllDay" ], "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "eventType": { "type": "string" }, "forAccountId": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "isAllDay": { "type": "boolean" }, "venueId": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." }, "tourId": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." }, "status": { "type": "string" }, "isPublished": { "type": "boolean" }, "labelKeys": { "type": "array", "items": { "type": "string" }, "description": "Labels on the show. Sending the list replaces the set. An empty list clears them." }, "capacity": { "type": "integer", "minimum": 1 }, "imageUrl": { "type": [ "string", "null" ] } } }, "EventUpdateRequest": { "type": "object", "additionalProperties": true, "description": "Partial update; omit fields to leave them unchanged. Send null to clear description, venueId, tourId, capacity, or taxRateId.", "properties": { "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "eventType": { "type": "string" }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "isAllDay": { "type": "boolean" }, "venueId": { "type": [ "string", "null" ], "format": "uuid", "description": "Public UUID; null clears the venue." }, "tourId": { "type": [ "string", "null" ], "format": "uuid", "description": "Public UUID; null clears the tour." }, "status": { "type": "string" }, "isPublished": { "type": "boolean" }, "labelKeys": { "type": "array", "items": { "type": "string" }, "description": "Labels on the show. Sending the list replaces the set. An empty list clears them." }, "capacity": { "type": [ "integer", "null" ], "minimum": 1 }, "imageUrl": { "type": [ "string", "null" ] }, "taxRateId": { "type": [ "string", "null" ], "format": "uuid", "description": "Public UUID; null clears the tax rate." } } }, "EventResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Event" } } }, "EventListResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "ListMeta": { "type": "object", "additionalProperties": true, "properties": { "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1 }, "total": { "type": "integer", "minimum": 0 }, "pages": { "type": "integer", "minimum": 0 } } }, "includes": { "type": "array", "items": { "type": "string" } } } }, "EventDeleteResponse": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "EventItemTypeField": { "type": "object", "required": [ "key", "label", "type" ], "properties": { "key": { "type": "string", "description": "Path on typeSpecificData. Dot paths nest objects (for example venue.loadInInstructions)." }, "label": { "type": "string" }, "type": { "type": "string" }, "numbered": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "string" } } } }, "EventItemType": { "type": "object", "required": [ "typeKey", "label", "fields" ], "properties": { "id": { "type": [ "string", "null" ], "description": "Persisted uniqueId, or null when a built-in has no saved row yet." }, "typeKey": { "type": "string" }, "label": { "type": "string" }, "color": { "type": "string" }, "icon": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "isCustom": { "type": "boolean" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/EventItemTypeField" } }, "defaultFieldValues": { "type": [ "object", "null" ], "additionalProperties": true } } }, "EventItemTypeListResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventItemType" } } } }, "CatalogNameCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "color": { "type": [ "string", "null" ] } } }, "CatalogNameUpdate": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": [ "string", "null" ] } } }, "EventStatusCatalog": { "type": "object", "required": [ "statusKey", "name", "isCustom" ], "properties": { "id": { "type": [ "string", "null" ] }, "statusKey": { "type": "string" }, "name": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "isCustom": { "type": "boolean" }, "publishesEvent": { "type": "boolean" }, "showOnEventList": { "type": "boolean" } } }, "EventStatusCatalogCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "publishesEvent": { "type": "boolean" }, "showOnEventList": { "type": "boolean" } } }, "EventStatusCatalogUpdate": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "publishesEvent": { "type": "boolean" }, "showOnEventList": { "type": "boolean" } } }, "EventLabelCatalog": { "type": "object", "required": [ "labelKey", "name", "isCustom" ], "properties": { "id": { "type": [ "string", "null" ] }, "labelKey": { "type": "string" }, "name": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "isCustom": { "type": "boolean" } } }, "EventTypeCatalog": { "type": "object", "required": [ "typeKey", "name", "isCustom" ], "properties": { "id": { "type": [ "string", "null" ] }, "typeKey": { "type": "string" }, "name": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "isCustom": { "type": "boolean" } } }, "EventTypeCatalogCreate": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "defaultFieldDescriptors": { "type": [ "array", "null" ] }, "defaultFieldValues": { "type": [ "object", "null" ] } } }, "EventTypeCatalogUpdate": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "icon": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "defaultFieldDescriptors": { "type": [ "array", "null" ] }, "defaultFieldValues": { "type": [ "object", "null" ] } } }, "TourTypeCatalog": { "type": "object", "required": [ "typeKey", "name", "isCustom" ], "properties": { "id": { "type": [ "string", "null" ] }, "typeKey": { "type": "string" }, "name": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "isCustom": { "type": "boolean" } } }, "TourStatusCatalog": { "type": "object", "required": [ "statusKey", "name", "isCustom" ], "properties": { "id": { "type": [ "string", "null" ] }, "statusKey": { "type": "string" }, "name": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "isCustom": { "type": "boolean" } } }, "TourLabelCatalog": { "type": "object", "required": [ "labelKey", "name", "isCustom" ], "properties": { "id": { "type": [ "string", "null" ] }, "labelKey": { "type": "string" }, "name": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "isCustom": { "type": "boolean" } } }, "EventItem": { "type": "object", "additionalProperties": true, "required": [ "id", "eventId", "itemType" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." }, "eventId": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." }, "itemType": { "type": "string", "description": "typeKey from GET /api/event-item-types for this Account." }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "startDate": { "type": [ "string", "null" ], "format": "date-time" }, "endDate": { "type": [ "string", "null" ], "format": "date-time" }, "timezone": { "type": [ "string", "null" ] }, "isAllDay": { "type": "boolean" }, "timingMode": { "type": [ "string", "null" ] }, "relativeAnchor": { "type": [ "string", "null" ] }, "relativeEndAnchor": { "type": [ "string", "null" ] }, "startOffsetMinutes": { "type": [ "integer", "null" ] }, "endOffsetMinutes": { "type": [ "integer", "null" ] }, "isTask": { "type": "boolean" }, "isCompleted": { "type": "boolean" }, "typeSpecificData": { "type": "object", "additionalProperties": true, "description": "Values for the type's field keys (dot paths nest objects). Clock times stay on startDate and endDate. Extra per-item fields: custom[key] plus _ui.customFields." } } }, "EventItemCreateRequest": { "type": "object", "additionalProperties": true, "required": [ "eventId", "itemType" ], "properties": { "eventId": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." }, "itemType": { "type": "string", "description": "typeKey from GET /api/event-item-types for this Account." }, "title": { "type": [ "string", "null" ] }, "startDate": { "type": [ "string", "null" ], "format": "date-time" }, "endDate": { "type": [ "string", "null" ], "format": "date-time" }, "timezone": { "type": [ "string", "null" ] }, "isAllDay": { "type": "boolean" }, "timingMode": { "type": [ "string", "null" ] }, "relativeAnchor": { "type": [ "string", "null" ] }, "relativeEndAnchor": { "type": [ "string", "null" ] }, "startOffsetMinutes": { "type": [ "integer", "null" ] }, "endOffsetMinutes": { "type": [ "integer", "null" ] }, "typeSpecificData": { "type": "object", "additionalProperties": true, "description": "Values for the type's field keys (dot paths nest objects). Clock times stay on startDate and endDate. Extra per-item fields: custom[key] plus _ui.customFields." }, "isTask": { "type": "boolean" }, "isCompleted": { "type": "boolean" }, "tourId": { "type": [ "string", "null" ], "format": "uuid" }, "bookingId": { "type": [ "string", "null" ], "format": "uuid" } } }, "EventItemUpdateRequest": { "type": "object", "additionalProperties": true, "properties": { "eventId": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." }, "itemType": { "type": "string", "description": "typeKey from GET /api/event-item-types for this Account." }, "title": { "type": [ "string", "null" ] }, "startDate": { "type": [ "string", "null" ], "format": "date-time" }, "endDate": { "type": [ "string", "null" ], "format": "date-time" }, "timezone": { "type": [ "string", "null" ] }, "timingMode": { "type": [ "string", "null" ] }, "typeSpecificData": { "type": "object", "additionalProperties": true, "description": "Values for the type's field keys (dot paths nest objects). Clock times stay on startDate and endDate. Extra per-item fields: custom[key] plus _ui.customFields." }, "isTask": { "type": "boolean" }, "isCompleted": { "type": "boolean" } } }, "EventItemCompleteRequest": { "type": "object", "additionalProperties": false, "required": [ "isCompleted" ], "properties": { "isCompleted": { "type": "boolean" } } }, "EventItemResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EventItem" } } }, "EventItemListResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventItem" } }, "meta": { "$ref": "#/components/schemas/ListMeta" } } }, "EventItemDeleteResponse": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean" } } }, "Tour": { "type": "object", "additionalProperties": true, "required": [ "id", "name", "type", "category", "status", "startDate", "endDate" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string", "description": "Tour type key from the account catalog." }, "category": { "type": "string", "enum": [ "domestic", "international" ] }, "status": { "type": "string", "description": "Tour status key from the account catalog." }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "parentTourId": { "type": [ "string", "null" ], "format": "uuid" }, "forAccountId": { "type": [ "string", "null" ], "format": "uuid" } } }, "TourCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "startDate", "endDate" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "description": "Tour type key from the account catalog. Omit to use the account default." }, "category": { "type": "string", "enum": [ "domestic", "international" ] }, "status": { "type": "string", "description": "Tour status key from the account catalog. Omit to use the account default." }, "labelKeys": { "type": "array", "items": { "type": "string" }, "description": "Tour label keys. Omit to use the account default. Sending the list replaces the set." }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "parentTourId": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." }, "forAccountId": { "type": [ "string", "null" ], "format": "uuid" } } }, "TourUpdateRequest": { "type": "object", "additionalProperties": false, "description": "Partial update. When both dates are sent, endDate must be after startDate.", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string", "description": "Tour type key from the account catalog." }, "category": { "type": "string", "enum": [ "domestic", "international" ] }, "status": { "type": "string", "description": "Tour status key from the account catalog." }, "labelKeys": { "type": "array", "items": { "type": "string" }, "description": "Tour label keys. Sending the list replaces the set." }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "timezone": { "type": "string" }, "parentTourId": { "type": "string", "format": "uuid", "description": "Public UUID (never an internal numeric database id)." }, "forAccountId": { "type": [ "string", "null" ], "format": "uuid" } } }, "TourResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Tour" } } }, "TourListMeta": { "type": "object", "additionalProperties": true, "description": "Pagination plus the parsed include object from GET /api/tours. includes is not a list of strings.", "properties": { "pagination": { "type": "object", "properties": { "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1 }, "total": { "type": "integer", "minimum": 0 }, "pages": { "type": "integer", "minimum": 0 } } }, "includes": { "type": "object", "additionalProperties": true, "description": "Parsed include flags, for example { \"account\": true, \"parentTour\": \"full\" }.", "properties": { "account": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "full" ] } ] }, "parentTour": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "full" ] } ] }, "subTours": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "full" ] } ] }, "tickets": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "report" ] } ] } } } } }, "TourListResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tour" } }, "meta": { "$ref": "#/components/schemas/TourListMeta" } } }, "TourDeleteResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } } } } }, "responses": { "Unauthorized": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "Forbidden": { "description": "Authenticated but not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "NotFound": { "description": "Event not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "BadRequest": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "TooManyRequests": { "description": "Rate limited. Honor Retry-After and X-RateLimit-Reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "InternalError": { "description": "Unexpected server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }