{ "openapi": "3.1.0", "info": { "title": "Real Sounds Agent API", "version": "1.2.0", "description": "Public Real Sounds event discovery and a signed, 15-minute checkout handoff for human review and payment. Live commercial responses are search=yes, ai-input=yes, ai-train=no. Creating a checkout link does not reserve inventory, create an order, or charge a card." }, "servers": [ { "url": "https://realsounds.com" } ], "externalDocs": { "description": "Agent and MCP usage policy", "url": "https://realsounds.com/llms.txt" }, "tags": [ { "name": "Discovery", "description": "Public recommendation-ready event information." }, { "name": "Checkout handoff", "description": "Public stateless ticket preselection for human review and payment on realsounds.com." }, { "name": "Delegated purchasing", "description": "Separate release-gated OAuth direct charging under a user's active Real Sounds grant. This is not the anonymous public human-review checkout workflow." }, { "name": "Human authorization", "description": "Grant setup, review, revocation, and secure user-action resumption using a direct Real Sounds account session." }, { "name": "Training corpus", "description": "Public content with all commercial state structurally removed." } ], "x-mcp": { "endpoint": "https://agents.realsounds.com/mcp", "oauthProtectedResourceMetadata": "https://agents.realsounds.com/.well-known/oauth-protected-resource/mcp", "tools": ["search_events", "get_event_details", "get_ticket_options", "create_checkout_link"] }, "x-developer-documentation": "https://realsounds.com/developers/agents", "x-oauth-protected-resource-metadata": "https://realsounds.com/.well-known/oauth-protected-resource", "paths": { "/api/agent/v1/events": { "get": { "operationId": "searchEvents", "tags": ["Discovery"], "x-mcp-tool": "search_events", "summary": "Find upcoming public events", "description": "Returns published events whose public sale window has not ended. The default order is chronological; sort=relevance scores query matches. Unavailable and sold-out events are included only when filters select them. Ticket prices and availability are live as of the response asOf timestamp and do not reserve inventory. Drafts, customer/order data, internal finance, and admin fields are never returned. Rate limit: 600 requests per 10 minutes and 5,000 per day per source IP.", "parameters": [ { "$ref": "#/components/parameters/Query" }, { "$ref": "#/components/parameters/QueryAlias" }, { "$ref": "#/components/parameters/Artist" }, { "$ref": "#/components/parameters/Genre" }, { "$ref": "#/components/parameters/City" }, { "$ref": "#/components/parameters/Venue" }, { "$ref": "#/components/parameters/Category" }, { "$ref": "#/components/parameters/AgePolicy" }, { "$ref": "#/components/parameters/AgePolicyAlias" }, { "$ref": "#/components/parameters/StartsAfter" }, { "$ref": "#/components/parameters/DateFrom" }, { "$ref": "#/components/parameters/DateFromCamel" }, { "$ref": "#/components/parameters/DateFromAlias" }, { "$ref": "#/components/parameters/StartsBefore" }, { "$ref": "#/components/parameters/DateTo" }, { "$ref": "#/components/parameters/DateToCamel" }, { "$ref": "#/components/parameters/DateToAlias" }, { "$ref": "#/components/parameters/MinPriceMinor" }, { "$ref": "#/components/parameters/MinPrice" }, { "$ref": "#/components/parameters/MinPriceAlias" }, { "$ref": "#/components/parameters/MaxPriceMinor" }, { "$ref": "#/components/parameters/MaxPrice" }, { "$ref": "#/components/parameters/MaxPriceAlias" }, { "$ref": "#/components/parameters/Currency" }, { "$ref": "#/components/parameters/Availability" }, { "$ref": "#/components/parameters/Accessibility" }, { "$ref": "#/components/parameters/OnSale" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Sort" } ], "responses": { "200": { "description": "Matching events", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Content-Signal": { "$ref": "#/components/headers/NoTrainContentSignal" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentEventListResponse" } }, "text/markdown": { "schema": { "type": "string" } } } }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "head": { "operationId": "headEvents", "tags": ["Discovery"], "summary": "Read event-search metadata and cache validators", "parameters": [ { "$ref": "#/components/parameters/Query" }, { "$ref": "#/components/parameters/QueryAlias" }, { "$ref": "#/components/parameters/Artist" }, { "$ref": "#/components/parameters/Genre" }, { "$ref": "#/components/parameters/City" }, { "$ref": "#/components/parameters/Venue" }, { "$ref": "#/components/parameters/Category" }, { "$ref": "#/components/parameters/AgePolicy" }, { "$ref": "#/components/parameters/AgePolicyAlias" }, { "$ref": "#/components/parameters/StartsAfter" }, { "$ref": "#/components/parameters/DateFrom" }, { "$ref": "#/components/parameters/DateFromCamel" }, { "$ref": "#/components/parameters/DateFromAlias" }, { "$ref": "#/components/parameters/StartsBefore" }, { "$ref": "#/components/parameters/DateTo" }, { "$ref": "#/components/parameters/DateToCamel" }, { "$ref": "#/components/parameters/DateToAlias" }, { "$ref": "#/components/parameters/MinPriceMinor" }, { "$ref": "#/components/parameters/MinPrice" }, { "$ref": "#/components/parameters/MinPriceAlias" }, { "$ref": "#/components/parameters/MaxPriceMinor" }, { "$ref": "#/components/parameters/MaxPrice" }, { "$ref": "#/components/parameters/MaxPriceAlias" }, { "$ref": "#/components/parameters/Currency" }, { "$ref": "#/components/parameters/Availability" }, { "$ref": "#/components/parameters/Accessibility" }, { "$ref": "#/components/parameters/OnSale" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Sort" } ], "responses": { "200": { "description": "The same headers as GET, without a body" }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/agent/v1/events/{eventRef}": { "get": { "operationId": "getEventDetails", "tags": ["Discovery"], "x-mcp-tool": "get_event_details", "summary": "Get one public event", "description": "Returns one canonical published upcoming event by UUID or slug with live ticket details. Rate limit: 180 requests per 10 minutes for each source-IP/event pair.", "parameters": [ { "$ref": "#/components/parameters/EventRef" } ], "responses": { "200": { "description": "Complete public event details", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Content-Signal": { "$ref": "#/components/headers/NoTrainContentSignal" }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentEventDetailResponse" } }, "text/markdown": { "schema": { "type": "string" } } } }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "head": { "operationId": "headEvent", "tags": ["Discovery"], "summary": "Read event metadata and cache validators", "parameters": [ { "$ref": "#/components/parameters/EventRef" } ], "responses": { "200": { "description": "The same headers as GET, without a body" }, "304": { "description": "Not modified" }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/agent/v1/checkout-links": { "post": { "operationId": "createCheckoutLink", "tags": ["Checkout handoff"], "x-mcp-tool": "create_checkout_link", "summary": "Create a preselected checkout link for human review", "description": "Revalidates the public event, ticket option, quantity, all-in price, and availability, then returns an opaque signed reference and an HTTPS checkout URL whose host is exactly realsounds.com. The link expires after 15 minutes. It does not reserve inventory, create a hold or order, collect payment details, or charge a card. Rate limit: 30 requests per 10 minutes and 150 per day per source IP, plus 15 per 10 minutes for each source-IP/event pair.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCheckoutLinkRequest" }, "examples": { "quantityTwo": { "summary": "Preselect two standard tickets", "value": { "eventRef": "e0284", "ticketTypeId": "73a1d187-5bcb-413f-9068-ad15195c8250", "quantity": 2, "attribution": { "agent": "example-agent", "campaign": "weekend-gigs" } } } } } } }, "responses": { "201": { "description": "A 15-minute stateless checkout handoff was created. No reservation, order, or payment exists.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCheckoutLinkResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The requested ticket selection is not currently available.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCheckoutSelectionError" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/agent/v1/checkout-links/resolve": { "post": { "operationId": "resolveCheckoutLink", "tags": ["Checkout handoff"], "summary": "Verify a checkout reference and refresh its live selection", "description": "Browser support for the Real Sounds checkout page. Agents normally create the link and send its checkoutUrl rather than calling this endpoint. The route verifies signature and expiry, refreshes live price and availability, and returns ready or unavailable without customer/order correlation. Rate limit: 180 requests per 10 minutes and 1,000 per day per source IP.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["checkoutReference"], "properties": { "checkoutReference": { "type": "string", "minLength": 1, "description": "Opaque signed reference returned by checkout-link creation. Treat as an ephemeral bearer value and do not log it." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The current ready or unavailable selection. This is not an order or payment status.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCheckoutResolveResponse" } } } }, "400": { "description": "Invalid JSON input or checkout reference.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/AgentCheckoutReferenceError" } ] } } } }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/agent/v1/grants": { "get": { "operationId": "listAgentGrants", "tags": ["Human authorization"], "summary": "List the signed-in user's agent grants and recent purchase activity", "description": "Requires a direct Real Sounds account session. OAuth agent access tokens cannot inspect or create their own grants.", "security": [ { "realSoundsAccount": [] } ], "responses": { "200": { "description": "Agent grants and the 20 most recent delegated purchase attempts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentGrantListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "post": { "operationId": "createAgentGrant", "tags": ["Human authorization"], "summary": "Create or replace a delegated ticket-purchase grant", "description": "Called from the Real Sounds authorization screen after the user reviews and accepts the limits, age requirements, ticket policy, and purchase notifications. The preselected grant is one ticket per order, GBP 50/EUR 60/USD 65 per order, GBP 100/EUR 120/USD 130 per rolling 30 days, and 12 months. Limits are expressed in currency minor units.", "security": [ { "realSoundsAccount": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentGrantCreateRequest" } } } }, "responses": { "201": { "description": "Grant created or replaced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentGrantCreateResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/agent/v1/grants/{grantId}": { "delete": { "operationId": "revokeAgentGrant", "tags": ["Human authorization"], "summary": "Immediately revoke one agent grant", "description": "Requires a direct Real Sounds account session and also attempts to revoke the corresponding OAuth grant.", "security": [ { "realSoundsAccount": [] } ], "parameters": [ { "$ref": "#/components/parameters/GrantId" } ], "responses": { "200": { "description": "Local grant revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentGrantRevokeResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/agent/v1/purchases": { "post": { "operationId": "buyTicket", "tags": ["Delegated purchasing"], "x-mcp-tool": "buy_ticket", "summary": "Buy tickets with delegated user authority", "description": "Revalidates inventory and all-in price, creates a hold, charges the user's saved card off-session, and leaves fulfilment to the Stripe webhook. The request must carry a current or standing instruction to buy; a recommendation-only request is prohibited. Quantity defaults to one. When ticketTypeId is omitted, Real Sounds selects the lowest-priced currently available publicly eligible standard option. Concessions, child tickets, accessibility allocations, group offers, memberships, VIP, and age-band tickets are never selected implicitly. This endpoint never substitutes a different event. For an open-ended find-and-buy request, the caller may try a different qualifying event only after receiving unavailable; when the user named an event, substitution is prohibited.", "security": [ { "agentOAuth": ["email", "profile"] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPurchaseRequest" } } } }, "responses": { "200": { "description": "The same existing purchase result returned for an idempotent retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPurchaseResponse" } } } }, "201": { "description": "Purchase accepted. The response is always complete, user_action_required, processing, or unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPurchaseResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/agent/v1/purchases/{purchaseId}": { "get": { "operationId": "getAgentPurchase", "tags": ["Delegated purchasing"], "summary": "Read the current result of a delegated purchase", "description": "Bound to the same authenticated user, OAuth client, and active grant that created the purchase. Poll only when buyTicket returned processing or after the user completed an action URL.", "security": [ { "agentOAuth": ["email", "profile"] } ], "parameters": [ { "$ref": "#/components/parameters/PurchaseId" } ], "responses": { "200": { "description": "Current purchase result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPurchaseResponse" } } } }, "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" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/agent/v1/purchases/{purchaseId}/resume": { "post": { "operationId": "resumeAgentPurchaseAfterSetup", "tags": ["Human authorization"], "summary": "Resume a purchase after the user securely saves a card", "description": "Used by the Real Sounds account flow after the user completes first-time payment setup. It requires the ticket recipient's direct Real Sounds account session, not an OAuth agent token.", "security": [ { "realSoundsAccount": [] } ], "parameters": [ { "$ref": "#/components/parameters/PurchaseId" } ], "responses": { "200": { "description": "Resumed purchase result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentPurchaseResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "503": { "$ref": "#/components/responses/Unavailable" } } } }, "/api/agent/v1/training/events": { "get": { "operationId": "getTrainingSafeEvents", "tags": ["Training corpus"], "summary": "Get the current training-safe public event corpus", "description": "Includes current and past published public events. Structurally omits ticket prices, allocations, inventory, availability, sale status, sold-out status, and checkout status.", "responses": { "200": { "description": "Training-safe public event facts and editorial content", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Content-Signal": { "$ref": "#/components/headers/TrainContentSignal" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTrainingResponse" } } } }, "304": { "description": "Not modified" }, "503": { "$ref": "#/components/responses/Unavailable" } } }, "head": { "operationId": "headTrainingSafeEvents", "tags": ["Training corpus"], "summary": "Read training-corpus metadata and cache validators", "responses": { "200": { "description": "The same headers as GET, without a body" }, "304": { "description": "Not modified" }, "503": { "$ref": "#/components/responses/Unavailable" } } } } }, "components": { "securitySchemes": { "agentOAuth": { "type": "oauth2", "description": "Supabase OAuth 2.1 authorization-code flow with PKCE. A protected purchase also requires an active, unexpired Real Sounds agent grant for the same user and OAuth client. Real Sounds enforces the tickets:purchase capability in its private grant record because the authorization server exposes only the standard email and profile scopes.", "flows": { "authorizationCode": { "authorizationUrl": "https://dixckgsgvnyeisypbwnq.supabase.co/auth/v1/oauth/authorize", "tokenUrl": "https://dixckgsgvnyeisypbwnq.supabase.co/auth/v1/oauth/token", "scopes": { "email": "Identify the ticket recipient's Real Sounds account.", "profile": "Identify the user and registered OAuth client for delegated purchasing." } } } }, "realSoundsAccount": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "A direct Real Sounds account session. OAuth agent access tokens with a client_id claim are rejected for grant management and human-only purchase resumption." } }, "parameters": { "Query": { "name": "query", "in": "query", "description": "Case-insensitive text across title, copy, lineup, artist, genre, venue, and city.", "schema": { "type": "string", "minLength": 1 } }, "QueryAlias": { "name": "q", "in": "query", "description": "Alias for query. query takes precedence when both are supplied.", "schema": { "type": "string", "minLength": 1 } }, "Artist": { "name": "artist", "in": "query", "description": "Case-insensitive artist-name substring.", "schema": { "type": "string", "minLength": 1 } }, "Genre": { "name": "genre", "in": "query", "description": "Case-insensitive artist-genre substring.", "schema": { "type": "string", "minLength": 1 } }, "City": { "name": "city", "in": "query", "description": "Case-insensitive city substring.", "schema": { "type": "string", "minLength": 1 } }, "Venue": { "name": "venue", "in": "query", "description": "Case-insensitive venue-name substring.", "schema": { "type": "string", "minLength": 1 } }, "Category": { "name": "category", "in": "query", "description": "Case-insensitive public category or genre substring.", "schema": { "type": "string", "minLength": 1 } }, "AgePolicy": { "name": "agePolicy", "in": "query", "description": "Case-insensitive public age-policy substring. Takes precedence over age_policy.", "schema": { "type": "string", "minLength": 1 } }, "AgePolicyAlias": { "name": "age_policy", "in": "query", "description": "Alias for agePolicy.", "schema": { "type": "string", "minLength": 1 } }, "DateFrom": { "name": "from", "in": "query", "description": "Inclusive ISO-8601 date or date-time lower bound. Takes precedence over date_from.", "schema": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } }, "DateFromCamel": { "name": "dateFrom", "in": "query", "description": "Alias for from.", "schema": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } }, "DateFromAlias": { "name": "date_from", "in": "query", "description": "Alias for from.", "schema": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } }, "DateTo": { "name": "to", "in": "query", "description": "Exclusive ISO-8601 date or date-time upper bound. Takes precedence over date_to.", "schema": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } }, "DateToCamel": { "name": "dateTo", "in": "query", "description": "Alias for to.", "schema": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } }, "DateToAlias": { "name": "date_to", "in": "query", "description": "Alias for to.", "schema": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } }, "MinPrice": { "name": "minPrice", "in": "query", "description": "Minimum current all-in unit price in the currency's minor unit. currency is required. Takes precedence over min_price.", "schema": { "type": "integer", "minimum": 0 } }, "MinPriceAlias": { "name": "min_price", "in": "query", "description": "Alias for minPrice.", "schema": { "type": "integer", "minimum": 0 } }, "MaxPrice": { "name": "maxPrice", "in": "query", "description": "Maximum current all-in unit price in the currency's minor unit. currency is required. Takes precedence over max_price.", "schema": { "type": "integer", "minimum": 0 } }, "MaxPriceAlias": { "name": "max_price", "in": "query", "description": "Alias for maxPrice.", "schema": { "type": "integer", "minimum": 0 } }, "StartsAfter": { "name": "startsAfter", "in": "query", "description": "Inclusive ISO-8601 lower bound.", "schema": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } }, "StartsBefore": { "name": "startsBefore", "in": "query", "description": "Exclusive ISO-8601 upper bound.", "schema": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } }, "MinPriceMinor": { "name": "minPriceMinor", "in": "query", "description": "Minimum current all-in unit price in the currency's minor unit. currency is required. Takes precedence over minPrice and min_price.", "schema": { "type": "integer", "minimum": 0 } }, "MaxPriceMinor": { "name": "maxPriceMinor", "in": "query", "description": "Maximum all-in unit price in the currency's minor unit, applied only to currently available agent-purchasable standard options. currency is required with this filter.", "schema": { "type": "integer", "minimum": 0 } }, "Currency": { "name": "currency", "in": "query", "description": "Required ticket currency when filtering by price.", "schema": { "type": "string", "enum": ["GBP", "EUR", "USD"] } }, "Availability": { "name": "availability", "in": "query", "description": "Filter by the event's current public ticket availability.", "schema": { "type": "string", "enum": ["available", "unavailable", "sold_out", "off_sale", "temporarily_unavailable"] } }, "Page": { "name": "page", "in": "query", "description": "One-based result page.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "Accessibility": { "name": "accessibility", "in": "query", "description": "When true, require published accessibility information. False applies no accessibility constraint.", "schema": { "type": "boolean" } }, "OnSale": { "name": "onSale", "in": "query", "description": "Filter by whether an agent-purchasable standard ticket is available now.", "schema": { "type": "boolean" } }, "Limit": { "name": "limit", "in": "query", "description": "Maximum matches returned after filtering.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 12 } }, "Sort": { "name": "sort", "in": "query", "description": "Chronological date order or relevance scored from query matches.", "schema": { "type": "string", "enum": ["date", "relevance"], "default": "date" } }, "EventRef": { "name": "eventRef", "in": "path", "required": true, "description": "Stable event UUID, canonical e#### slug, or public custom slug.", "schema": { "type": "string", "minLength": 1 } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "A caller-generated key, unique per intended purchase and stable across retries. Real Sounds binds the key to the OAuth client and a hash of the request. Repeating the same key and request returns the same purchase; reusing it for different request content returns 409. Retries never create another hold, charge, order, notification, or ticket set.", "schema": { "type": "string", "minLength": 8, "maxLength": 160 } }, "GrantId": { "name": "grantId", "in": "path", "required": true, "description": "Real Sounds delegated grant UUID.", "schema": { "type": "string", "format": "uuid" } }, "PurchaseId": { "name": "purchaseId", "in": "path", "required": true, "description": "Delegated purchase UUID returned by buyTicket.", "schema": { "type": "string", "format": "uuid" } } }, "headers": { "ETag": { "description": "Weak response validator accepted through If-None-Match.", "schema": { "type": "string" } }, "RequestId": { "description": "Opaque request correlation identifier. Include it in support reports; do not include signed checkout references or private data.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "NoTrainContentSignal": { "description": "Live commercial data permission signal.", "schema": { "type": "string", "const": "search=yes, ai-input=yes, ai-train=no" } }, "TrainContentSignal": { "description": "Training-safe corpus permission signal.", "schema": { "type": "string", "const": "search=yes, ai-input=yes, ai-train=yes" } } }, "responses": { "BadRequest": { "description": "Invalid filter or event reference", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "The requested public event, grant, or purchase was not found or is not owned by the authenticated principal.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unavailable": { "description": "The requested service or data is temporarily unavailable", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "A valid account or OAuth bearer token is required. The WWW-Authenticate header links to protected-resource metadata.", "headers": { "WWW-Authenticate": { "description": "OAuth protected-resource challenge.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The OAuth client is not registered, or its delegated purchase grant is missing, expired, revoked, or insufficient.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" } } } }, "Conflict": { "description": "The requested state transition cannot be performed.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "IdempotencyConflict": { "description": "The same OAuth client reused an idempotency key with different request content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "The client, user, event, or network rate limit was exceeded.", "headers": { "Retry-After": { "description": "Seconds until this request scope can be retried.", "schema": { "type": "integer", "minimum": 1 } }, "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Gone": { "description": "The signed checkout reference expired. Search again and create a new checkout link.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCheckoutReferenceError" } } } }, "PayloadTooLarge": { "description": "The JSON request body exceeds 4,096 bytes.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "UnsupportedMediaType": { "description": "Content-Type must be application/json.", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "AgentCheckoutReferenceError": { "type": "object", "required": ["error", "state"], "properties": { "error": { "type": "string" }, "state": { "type": "string", "enum": ["expired", "invalid"] } }, "additionalProperties": false }, "AgentCheckoutSelectionError": { "type": "object", "required": ["error", "availability", "maxPurchasableQuantity"], "properties": { "error": { "type": "string" }, "availability": { "type": "string", "enum": ["available", "off_sale", "sold_out", "temporarily_unavailable", "unavailable"] }, "maxPurchasableQuantity": { "type": "integer", "minimum": 0, "maximum": 9 } }, "additionalProperties": false }, "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string" } }, "additionalProperties": false }, "OAuthError": { "type": "object", "required": ["error"], "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "additionalProperties": false }, "CurrencyCaps": { "type": "object", "description": "Positive limits in each currency's minor unit. Include every currency listed in allowedCurrencies.", "minProperties": 1, "properties": { "GBP": { "type": "integer", "minimum": 1, "maximum": 500000 }, "EUR": { "type": "integer", "minimum": 1, "maximum": 500000 }, "USD": { "type": "integer", "minimum": 1, "maximum": 500000 } }, "additionalProperties": false }, "AgentGrantCreateRequest": { "type": "object", "required": ["clientId", "allowedCurrencies", "maxTicketsPerOrder", "maxAmountPerOrderByCurrency", "maxAmountPer30DaysByCurrency", "expiresInMonths", "ageRequirementsAccepted", "ticketPolicyAccepted", "purchaseNotificationsEnabled"], "properties": { "clientId": { "type": "string", "minLength": 8, "maxLength": 255, "description": "OAuth client ID from the active authorization request. It must already be registered with the Real Sounds authorization server." }, "allowedCurrencies": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": ["GBP", "EUR", "USD"] } }, "maxTicketsPerOrder": { "type": "integer", "minimum": 1, "maximum": 10 }, "maxAmountPerOrderByCurrency": { "$ref": "#/components/schemas/CurrencyCaps" }, "maxAmountPer30DaysByCurrency": { "allOf": [ { "$ref": "#/components/schemas/CurrencyCaps" } ], "description": "Rolling limits. Each value must be at least the matching per-order limit." }, "expiresInMonths": { "type": "integer", "minimum": 1, "maximum": 12 }, "ageRequirementsAccepted": { "type": "boolean", "const": true }, "ticketPolicyAccepted": { "type": "boolean", "const": true }, "purchaseNotificationsEnabled": { "type": "boolean", "const": true } }, "additionalProperties": false, "examples": [ { "clientId": "registered-agent-client-id", "allowedCurrencies": ["GBP", "EUR", "USD"], "maxTicketsPerOrder": 1, "maxAmountPerOrderByCurrency": { "GBP": 5000, "EUR": 6000, "USD": 6500 }, "maxAmountPer30DaysByCurrency": { "GBP": 10000, "EUR": 12000, "USD": 13000 }, "expiresInMonths": 12, "ageRequirementsAccepted": true, "ticketPolicyAccepted": true, "purchaseNotificationsEnabled": true } ] }, "AgentClientSummary": { "type": ["object", "null"], "required": ["id", "name", "uri"], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "uri": { "type": ["string", "null"], "format": "uri" } }, "additionalProperties": false }, "AgentGrantLimits": { "type": "object", "required": ["allowedCurrencies", "maxAmountPer30DaysByCurrency", "maxAmountPerOrderByCurrency", "maxTicketsPerOrder"], "properties": { "allowedCurrencies": { "type": "array", "items": { "type": "string", "enum": ["GBP", "EUR", "USD"] } }, "maxAmountPer30DaysByCurrency": { "$ref": "#/components/schemas/CurrencyCaps" }, "maxAmountPerOrderByCurrency": { "$ref": "#/components/schemas/CurrencyCaps" }, "maxTicketsPerOrder": { "type": "integer", "minimum": 1, "maximum": 10 } }, "additionalProperties": false }, "AgentGrant": { "type": "object", "required": ["client", "createdAt", "expiresAt", "id", "lastUsedAt", "limits", "purchaseNotificationsEnabled", "status"], "properties": { "client": { "$ref": "#/components/schemas/AgentClientSummary" }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "lastUsedAt": { "type": ["string", "null"], "format": "date-time" }, "limits": { "$ref": "#/components/schemas/AgentGrantLimits" }, "purchaseNotificationsEnabled": { "type": "boolean", "const": true }, "status": { "type": "string", "enum": ["active", "expired", "revoked"] } }, "additionalProperties": false }, "AgentGrantCreateResponse": { "type": "object", "required": ["grant"], "properties": { "grant": { "$ref": "#/components/schemas/AgentGrant" } }, "additionalProperties": false }, "AgentGrantRevokeResponse": { "type": "object", "required": ["grant", "oauthRevocation"], "properties": { "grant": { "type": "object", "required": ["id", "revokedAt", "status"], "properties": { "id": { "type": "string", "format": "uuid" }, "revokedAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "const": "revoked" } }, "additionalProperties": false }, "oauthRevocation": { "type": "object", "required": ["ok"], "properties": { "ok": { "type": "boolean" } }, "additionalProperties": false } }, "additionalProperties": false }, "AgentPurchaseActivity": { "type": "object", "required": ["client", "createdAt", "currency", "error", "eventSlug", "id", "quantity", "state", "totalMinor", "updatedAt"], "properties": { "client": { "$ref": "#/components/schemas/AgentClientSummary" }, "createdAt": { "type": "string", "format": "date-time" }, "currency": { "type": ["string", "null"], "enum": ["GBP", "EUR", "USD", null] }, "error": { "oneOf": [ { "$ref": "#/components/schemas/AgentPurchaseError" }, { "type": "null" } ] }, "eventSlug": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "quantity": { "type": "integer", "minimum": 1 }, "state": { "type": "string", "enum": ["pending", "user_action_required", "processing", "complete", "unavailable"] }, "totalMinor": { "type": ["integer", "null"], "minimum": 0 }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "AgentGrantListResponse": { "type": "object", "required": ["activity", "grants"], "properties": { "activity": { "type": "array", "items": { "$ref": "#/components/schemas/AgentPurchaseActivity" } }, "grants": { "type": "array", "items": { "$ref": "#/components/schemas/AgentGrant" } } }, "additionalProperties": false }, "AgentUserIntent": { "type": "object", "description": "Concise evidence of a current or standing user instruction to buy. Send a summary, never the raw conversation.", "required": ["kind", "issuedAt", "summary"], "properties": { "kind": { "type": "string", "enum": ["explicit_purchase", "standing_purchase_instruction"] }, "issuedAt": { "type": "string", "format": "date-time" }, "summary": { "type": "string", "minLength": 1, "maxLength": 240 } }, "additionalProperties": false }, "AgentPurchaseRequest": { "type": "object", "required": ["eventSlug", "userIntent"], "properties": { "eventSlug": { "type": "string", "minLength": 1, "description": "The exact event selected by the agent or named by the user. This operation never substitutes another event." }, "ticketTypeId": { "type": ["string", "null"], "format": "uuid", "description": "Omit to select the lowest-priced currently available publicly eligible standard option. Supply only when the user explicitly requested a particular option." }, "artistInterestArtistProfileId": { "type": ["string", "null"], "format": "uuid", "description": "Record artist interest only when it is clear from the user's instruction. Otherwise omit." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 }, "maxTotalMinor": { "type": ["integer", "null"], "minimum": 0, "description": "Optional all-in maximum for this request, in the event ticket currency's minor unit. The user's grant limits still apply." }, "userIntent": { "$ref": "#/components/schemas/AgentUserIntent" } }, "additionalProperties": false }, "AgentPurchaseError": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": false }, "AgentPurchase": { "type": "object", "required": ["id", "eventSlug", "ticketTypeId", "quantity", "currency", "totalMinor", "orderId", "orderCode", "ticketCount", "error", "createdAt", "updatedAt", "completedAt"], "properties": { "id": { "type": "string", "format": "uuid" }, "eventSlug": { "type": "string" }, "ticketTypeId": { "type": ["string", "null"], "format": "uuid" }, "quantity": { "type": "integer", "minimum": 1 }, "currency": { "type": ["string", "null"], "enum": ["GBP", "EUR", "USD", null] }, "totalMinor": { "type": ["integer", "null"], "minimum": 0 }, "orderId": { "type": ["string", "null"], "format": "uuid" }, "orderCode": { "type": ["string", "null"] }, "ticketCount": { "type": ["integer", "null"], "minimum": 0 }, "error": { "oneOf": [ { "$ref": "#/components/schemas/AgentPurchaseError" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": ["string", "null"], "format": "date-time" } }, "additionalProperties": false }, "AgentPurchaseCompleteResponse": { "type": "object", "required": ["state", "purchase"], "properties": { "state": { "type": "string", "const": "complete" }, "purchase": { "$ref": "#/components/schemas/AgentPurchase" } }, "additionalProperties": false }, "AgentPurchaseActionRequiredResponse": { "type": "object", "required": ["state", "purchase", "actionUrl"], "properties": { "state": { "type": "string", "const": "user_action_required" }, "purchase": { "$ref": "#/components/schemas/AgentPurchase" }, "actionUrl": { "type": "string", "format": "uri", "description": "One secure Real Sounds or Stripe-backed URL for first-time card setup or bank authentication. Do not ask conversational follow-up questions; send the user here once." } }, "additionalProperties": false }, "AgentPurchaseProcessingResponse": { "type": "object", "required": ["state", "purchase"], "properties": { "state": { "type": "string", "const": "processing" }, "purchase": { "$ref": "#/components/schemas/AgentPurchase" } }, "additionalProperties": false }, "AgentPurchaseUnavailableResponse": { "type": "object", "required": ["state", "purchase", "alternatives"], "properties": { "state": { "type": "string", "const": "unavailable" }, "purchase": { "$ref": "#/components/schemas/AgentPurchase" }, "alternatives": { "type": "array", "maxItems": 3, "description": "Freshly revalidated qualifying alternatives. An open-ended find-and-buy instruction may try the next one; substitution is prohibited when the user named the event.", "items": { "$ref": "#/components/schemas/AgentPurchaseAlternative" } } }, "additionalProperties": false }, "AgentPurchaseAlternative": { "type": "object", "required": ["id", "eventSlug", "title", "canonicalUrl", "startsAt", "venue", "ticketOption", "asOf"], "properties": { "id": { "type": "string", "format": "uuid" }, "eventSlug": { "type": "string" }, "title": { "type": "string" }, "canonicalUrl": { "type": "string", "format": "uri" }, "startsAt": { "type": "string", "format": "date-time" }, "venue": { "type": "object", "required": ["name", "city"], "properties": { "name": { "type": ["string", "null"] }, "city": { "type": ["string", "null"] } }, "additionalProperties": false }, "ticketOption": { "type": "object", "required": ["id", "name", "currency", "unitPriceMinor", "availableQuantity"], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "currency": { "type": "string", "enum": ["GBP", "EUR", "USD"] }, "unitPriceMinor": { "type": "integer", "minimum": 0 }, "availableQuantity": { "type": "integer", "minimum": 1 } }, "additionalProperties": false }, "asOf": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "AgentPurchaseResponse": { "description": "Exactly one of four stable outcomes. A complete result includes the order and issued ticket count; user_action_required includes one action URL; processing should be polled; unavailable includes a machine-readable error and current alternatives.", "oneOf": [ { "$ref": "#/components/schemas/AgentPurchaseCompleteResponse" }, { "$ref": "#/components/schemas/AgentPurchaseActionRequiredResponse" }, { "$ref": "#/components/schemas/AgentPurchaseProcessingResponse" }, { "$ref": "#/components/schemas/AgentPurchaseUnavailableResponse" } ], "discriminator": { "propertyName": "state" } }, "AgentCheckoutAttribution": { "type": "object", "description": "Optional aggregate attribution labels. Never send a person's name, email, prompt, or other personal data.", "properties": { "agent": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9][a-z0-9_-]*$" }, "campaign": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z0-9][a-z0-9_-]*$" } }, "additionalProperties": false }, "AgentCheckoutLinkRequest": { "type": "object", "required": ["eventRef", "ticketTypeId", "quantity"], "properties": { "eventRef": { "type": "string", "minLength": 1, "description": "A current public event UUID or canonical slug." }, "ticketTypeId": { "type": "string", "format": "uuid", "description": "The exact currently eligible ticket option selected from event discovery." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 9 }, "attribution": { "$ref": "#/components/schemas/AgentCheckoutAttribution" } }, "additionalProperties": false }, "AgentCheckoutEvent": { "type": "object", "required": ["id", "slug", "title", "startsAt", "venue", "canonicalUrl"], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "title": { "type": "string" }, "startsAt": { "type": "string", "format": "date-time" }, "venue": { "$ref": "#/components/schemas/AgentVenue" }, "canonicalUrl": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "AgentCheckoutFees": { "type": ["object", "null"], "description": "Per-ticket fee decomposition where known. unitPriceMinor remains the all-in price for one ticket and totalPriceMinor is the all-in selection total.", "required": ["totalMinor", "bookingFeeMinor", "processingFeeMinor"], "properties": { "totalMinor": { "type": "integer", "minimum": 0 }, "bookingFeeMinor": { "type": ["integer", "null"], "minimum": 0 }, "processingFeeMinor": { "type": ["integer", "null"], "minimum": 0 } }, "additionalProperties": false }, "AgentCheckoutTicketSelection": { "type": "object", "required": ["ticketTypeId", "ticketTypeName", "quantity", "currency", "unitPriceMinor", "totalPriceMinor", "fees"], "properties": { "ticketTypeId": { "type": "string", "format": "uuid" }, "ticketTypeName": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 9 }, "currency": { "type": "string", "enum": ["GBP", "EUR", "USD"] }, "unitPriceMinor": { "type": "integer", "minimum": 0 }, "totalPriceMinor": { "type": "integer", "minimum": 0 }, "fees": { "$ref": "#/components/schemas/AgentCheckoutFees" } }, "additionalProperties": false }, "AgentCheckoutLinkResponse": { "type": "object", "required": ["schemaVersion", "asOf", "checkoutReference", "checkoutUrl", "expiresAt", "event", "ticketSelection", "reservationCreated", "availability", "warning"], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "asOf": { "type": "string", "format": "date-time" }, "checkoutReference": { "type": "string", "minLength": 1, "description": "Opaque signed reference. Treat as an ephemeral bearer value and do not log it." }, "checkoutUrl": { "type": "string", "format": "uri", "pattern": "^https://realsounds\\.com/", "description": "Same-origin human-review URL. Send it to the human once; do not open it in an agent-side fetcher." }, "expiresAt": { "type": "string", "format": "date-time" }, "event": { "$ref": "#/components/schemas/AgentCheckoutEvent" }, "ticketSelection": { "$ref": "#/components/schemas/AgentCheckoutTicketSelection" }, "reservationCreated": { "type": "boolean", "const": false }, "availability": { "type": "object", "required": ["state", "availableQuantity", "maxPurchasableQuantity"], "properties": { "state": { "type": "string", "enum": ["available", "off_sale", "sold_out", "temporarily_unavailable", "unavailable"] }, "availableQuantity": { "type": "integer", "minimum": 0 }, "maxPurchasableQuantity": { "type": "integer", "minimum": 0, "maximum": 9 } }, "additionalProperties": false }, "warning": { "type": "string" } }, "additionalProperties": false }, "AgentCheckoutResolveReadyResponse": { "type": "object", "required": ["schemaVersion", "state", "event", "ticketSelection", "expiresAt", "priceChanged", "warning", "asOf"], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "state": { "type": "string", "const": "ready" }, "event": { "$ref": "#/components/schemas/AgentCheckoutEvent" }, "ticketSelection": { "$ref": "#/components/schemas/AgentCheckoutTicketSelection" }, "expiresAt": { "type": "string", "format": "date-time" }, "priceChanged": { "type": "boolean" }, "warning": { "type": "string" }, "asOf": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "AgentCheckoutResolveUnavailableResponse": { "type": "object", "required": ["schemaVersion", "state", "expiresAt", "availability", "maxPurchasableQuantity", "priceChanged", "warning", "asOf"], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "state": { "type": "string", "const": "unavailable" }, "event": { "$ref": "#/components/schemas/AgentCheckoutEvent" }, "expiresAt": { "type": "string", "format": "date-time" }, "availability": { "type": "string", "enum": ["available", "off_sale", "sold_out", "temporarily_unavailable", "unavailable"] }, "maxPurchasableQuantity": { "type": "integer", "minimum": 0, "maximum": 9 }, "priceChanged": { "type": "boolean" }, "warning": { "type": "string" }, "asOf": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "AgentCheckoutResolveResponse": { "description": "Current browser handoff resolution. This is not a checkout, order, or payment status.", "oneOf": [ { "$ref": "#/components/schemas/AgentCheckoutResolveReadyResponse" }, { "$ref": "#/components/schemas/AgentCheckoutResolveUnavailableResponse" } ], "discriminator": { "propertyName": "state" } }, "AgentArtist": { "type": "object", "required": ["id", "slug", "name", "billingRole", "genre", "bio", "musicUrl"], "properties": { "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "name": { "type": "string" }, "billingRole": { "type": "string", "enum": ["headline", "support"] }, "genre": { "type": ["string", "null"] }, "bio": { "type": ["string", "null"] }, "musicUrl": { "type": ["string", "null"], "format": "uri" } }, "additionalProperties": false }, "AgentVenue": { "type": "object", "required": ["id", "name", "address", "city", "countryCode", "latitude", "longitude"], "properties": { "id": { "type": ["string", "null"] }, "name": { "type": ["string", "null"] }, "address": { "type": ["string", "null"] }, "city": { "type": ["string", "null"] }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$" }, "latitude": { "type": ["number", "null"], "minimum": -90, "maximum": 90 }, "longitude": { "type": ["number", "null"], "minimum": -180, "maximum": 180 } }, "additionalProperties": false }, "AgentTicketOption": { "type": "object", "description": "Live commercial data. unitPriceMinor is the complete all-in amount charged for one ticket.", "required": ["id", "name", "isStandard", "agentPurchasable", "currency", "unitPriceMinor", "faceValueMinor", "fees", "priceIncludesFees", "availability", "availableQuantity", "maxPurchasableQuantity", "saleStartsAt", "saleEndsAt"], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "isStandard": { "type": "boolean" }, "agentPurchasable": { "type": "boolean", "description": "False for concessions, children, accessibility allocations, groups, memberships, VIP, age bands, and any option explicitly disabled by metadata." }, "currency": { "type": "string", "enum": ["GBP", "EUR", "USD"] }, "unitPriceMinor": { "type": "integer", "minimum": 0 }, "faceValueMinor": { "type": ["integer", "null"], "minimum": 0 }, "fees": { "$ref": "#/components/schemas/AgentCheckoutFees" }, "priceIncludesFees": { "type": "boolean", "const": true }, "availability": { "type": "string", "enum": ["available", "off_sale", "sold_out", "temporarily_unavailable", "unavailable"] }, "availableQuantity": { "type": "integer", "minimum": 0 }, "maxPurchasableQuantity": { "type": "integer", "minimum": 0, "maximum": 9 }, "saleStartsAt": { "type": ["string", "null"], "format": "date-time" }, "saleEndsAt": { "type": ["string", "null"], "format": "date-time" } }, "additionalProperties": false }, "AgentEvent": { "type": "object", "required": ["schemaVersion", "id", "slug", "canonicalUrl", "title", "subtitle", "description", "shortDescription", "startsAt", "doorsAt", "endsAt", "timezone", "venue", "artists", "categories", "genres", "lineupText", "agePolicy", "accessibility", "image", "musicUrl", "musicPreviewUrl", "ticketOptions", "recommendedTicketOptionId", "checkoutTicketOptionId", "availability", "eventStatus", "onSale", "checkoutUrl", "asOf", "updatedAt"], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "canonicalUrl": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "subtitle": { "type": ["string", "null"] }, "description": { "type": ["string", "null"] }, "shortDescription": { "type": ["string", "null"] }, "startsAt": { "type": "string", "format": "date-time" }, "doorsAt": { "type": ["string", "null"], "format": "date-time" }, "endsAt": { "type": ["string", "null"], "format": "date-time" }, "timezone": { "type": "string" }, "venue": { "$ref": "#/components/schemas/AgentVenue" }, "artists": { "type": "array", "items": { "$ref": "#/components/schemas/AgentArtist" } }, "categories": { "type": "array", "items": { "type": "string" } }, "genres": { "type": "array", "items": { "type": "string" } }, "lineupText": { "type": ["string", "null"] }, "agePolicy": { "type": ["string", "null"] }, "accessibility": { "type": "object", "required": ["information"], "properties": { "information": { "type": ["string", "null"] } }, "additionalProperties": false }, "image": { "type": "object", "required": ["url", "alt"], "properties": { "url": { "type": ["string", "null"], "format": "uri" }, "alt": { "type": ["string", "null"] } }, "additionalProperties": false }, "musicUrl": { "type": ["string", "null"], "format": "uri" }, "musicPreviewUrl": { "type": ["string", "null"], "format": "uri" }, "ticketOptions": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTicketOption" } }, "recommendedTicketOptionId": { "type": ["string", "null"] }, "checkoutTicketOptionId": { "type": ["string", "null"], "format": "uuid", "description": "The public event-page ticket option eligible for a checkout handoff, or null when no checkout selection can be created." }, "availability": { "type": "string", "enum": ["available", "off_sale", "sold_out", "temporarily_unavailable", "unavailable"] }, "eventStatus": { "type": "string", "const": "scheduled" }, "onSale": { "type": "boolean" }, "checkoutUrl": { "type": "string", "format": "uri" }, "asOf": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "AgentEventListResponse": { "type": "object", "required": ["schemaVersion", "asOf", "page", "limit", "count", "totalMatching", "hasMore", "nextPage", "events"], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "asOf": { "type": "string", "format": "date-time" }, "page": { "type": "integer", "minimum": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "count": { "type": "integer", "minimum": 0 }, "totalMatching": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" }, "nextPage": { "type": ["integer", "null"], "minimum": 1 }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/AgentEvent" } } }, "additionalProperties": false }, "AgentEventDetailResponse": { "type": "object", "required": ["schemaVersion", "asOf", "event"], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "asOf": { "type": "string", "format": "date-time" }, "event": { "$ref": "#/components/schemas/AgentEvent" } }, "additionalProperties": false }, "AgentTrainingEvent": { "type": "object", "required": ["schemaVersion", "id", "slug", "canonicalUrl", "title", "subtitle", "description", "shortDescription", "startsAt", "doorsAt", "endsAt", "timezone", "venue", "artists", "categories", "genres", "lineupText", "agePolicy", "accessibility", "image", "musicUrl", "musicPreviewUrl", "updatedAt"], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "id": { "type": "string", "format": "uuid" }, "slug": { "type": "string" }, "canonicalUrl": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "subtitle": { "type": ["string", "null"] }, "description": { "type": ["string", "null"] }, "shortDescription": { "type": ["string", "null"] }, "startsAt": { "type": "string", "format": "date-time" }, "doorsAt": { "type": ["string", "null"], "format": "date-time" }, "endsAt": { "type": ["string", "null"], "format": "date-time" }, "timezone": { "type": "string" }, "venue": { "$ref": "#/components/schemas/AgentVenue" }, "artists": { "type": "array", "items": { "$ref": "#/components/schemas/AgentArtist" } }, "categories": { "type": "array", "items": { "type": "string" } }, "genres": { "type": "array", "items": { "type": "string" } }, "lineupText": { "type": ["string", "null"] }, "agePolicy": { "type": ["string", "null"] }, "accessibility": { "type": "object", "required": ["information"], "properties": { "information": { "type": ["string", "null"] } }, "additionalProperties": false }, "image": { "type": "object", "required": ["url", "alt"], "properties": { "url": { "type": ["string", "null"], "format": "uri" }, "alt": { "type": ["string", "null"] } }, "additionalProperties": false }, "musicUrl": { "type": ["string", "null"], "format": "uri" }, "musicPreviewUrl": { "type": ["string", "null"], "format": "uri" }, "updatedAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "AgentTrainingResponse": { "type": "object", "required": ["schemaVersion", "generatedAt", "events"], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "generatedAt": { "type": "string", "format": "date-time" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTrainingEvent" } } }, "additionalProperties": false } } } }