{ "openapi": "3.1.0", "info": { "title": "Fun API Playground — full catalog", "version": "1.0", "description": "Every one of the 39 mock REST APIs on funapi.dev in one document, 337 endpoints in total. Bearer tokens: qa-admin-token (full access), qa-viewer-token (403 on DELETE)." }, "servers": [ { "url": "https://funapi.dev/api" } ], "tags": [ { "name": "Friends API: characters", "description": "the six of them, and more" }, { "name": "Friends API: episodes", "description": "ten fan favorites" }, { "name": "Friends API: quotes", "description": "could this API BE any more quotable?" }, { "name": "Friends API: graphql", "description": "one POST endpoint, query-shaped" }, { "name": "Superhero API: heroes", "description": "capes, powers and their sworn enemies" }, { "name": "Pizza Orders API: menu", "description": "six pizzas, one controversial" }, { "name": "Pizza Orders API: orders", "description": "received → baking → out-for-delivery → delivered" }, { "name": "Pizza Orders API: oven", "description": "do not trust the oven" }, { "name": "Coffee Shop API: drinks", "description": "hot and cold" }, { "name": "Coffee Shop API: orders", "description": "name on the cup" }, { "name": "Coffee Shop API: rush", "description": "hammer it and watch the 429s" }, { "name": "Coffee Shop API: teapot", "description": "RFC 2324 compliance" }, { "name": "Football API: teams", "description": "six fictional clubs" }, { "name": "Football API: league", "description": "standings and matches" }, { "name": "Movies API: movies", "description": "now showing: Edge Case (2024)" }, { "name": "Movies API: uploads", "description": "simulated multipart file uploads" }, { "name": "Harry Potter API: houses", "description": "four houses, four elements" }, { "name": "Harry Potter API: students", "description": "sorted, patronus and all" }, { "name": "Harry Potter API: spells", "description": "charms, jinxes, and one unforgivable" }, { "name": "Star Wars API: planets", "description": "five worlds, one swamp" }, { "name": "Star Wars API: characters", "description": "rebels, empire, and neutral parties" }, { "name": "Star Wars API: starships", "description": "freighters to capital ships" }, { "name": "Sherlock Holmes API: cases", "description": "five cases, two still open" }, { "name": "Sherlock Holmes API: suspects", "description": "alibis included, guilt undisclosed" }, { "name": "Sherlock Holmes API: clues", "description": "physical, document, and testimony" }, { "name": "Pokémon API: pokemon", "description": "eight starters and friends" }, { "name": "Pokémon API: trainers", "description": "three trainers, their rosters" }, { "name": "Pokémon API: battles", "description": "simulate a fight, get a random winner" }, { "name": "Middle-earth API: fellowship", "description": "six companions, six races" }, { "name": "Middle-earth API: quests", "description": "one ring, several detours" }, { "name": "Middle-earth API: artifacts", "description": "each bound to a bearer" }, { "name": "Auth Playground API: oauth", "description": "client demo-client / secret demo-secret" }, { "name": "Auth Playground API: real tokens", "description": "log in for a token that works on the 🔒 endpoints site-wide" }, { "name": "Webhooks API: subscriptions", "description": "who gets notified, and for what" }, { "name": "Webhooks API: deliveries", "description": "attempts, replays, and signature checks" }, { "name": "The Office API: employees", "description": "eight desks, one regional manager" }, { "name": "The Office API: pranks", "description": "mostly aimed at one assistant (to the) regional manager" }, { "name": "The Office API: quotes", "description": "that's what she said" }, { "name": "Dino Park API: dinosaurs", "description": "seven residents, one very hungry rex" }, { "name": "Dino Park API: enclosures", "description": "capacity matters" }, { "name": "Dino Park API: incidents", "description": "breach reports, growing list" }, { "name": "Marvel API: heroes", "description": "six Avengers across two teams" }, { "name": "Marvel API: villains", "description": "threat levels, some defeated" }, { "name": "Marvel API: missions", "description": "assign heroes, then complete them" }, { "name": "Game of Thrones API: houses", "description": "four great houses" }, { "name": "Game of Thrones API: nobles", "description": "not all of them survive" }, { "name": "Game of Thrones API: dragons", "description": "two are still unclaimed" }, { "name": "Game of Thrones API: battles", "description": "Westeros conflict simulator" }, { "name": "Game of Thrones API: quotes", "description": "memorable lines" }, { "name": "Rick and Morty API: characters", "description": "eight characters, one dead" }, { "name": "Rick and Morty API: locations", "description": "planets, stations, and a dimension" }, { "name": "Rick and Morty API: episodes", "description": "five picks across seven seasons" }, { "name": "Bank API: accounts", "description": "who owns the money" }, { "name": "Bank API: transactions", "description": "cursor-based pagination" }, { "name": "Bank API: transfers", "description": "idempotent money movement" }, { "name": "Bank API: premium", "description": "pay up — 402 on demand" }, { "name": "Airline API: flights", "description": "where the planes pretend to go" }, { "name": "Airline API: bookings", "description": "a state machine with conflicts" }, { "name": "Protocol Lab API: jobs", "description": "202 Accepted + poll to completion" }, { "name": "Protocol Lab API: redirects", "description": "301, 302 and a chain to follow" }, { "name": "Protocol Lab API: outages", "description": "503 & 504 on demand" }, { "name": "Protocol Lab API: documents", "description": "HATEOAS, JSON Patch, 406 & 410" }, { "name": "Shop API: products", "description": "things you do not need" }, { "name": "Shop API: carts", "description": "add, remove, regret" }, { "name": "Shop API: checkout", "description": "where the money pretends to move" }, { "name": "Cargo Tracking API: tracking", "description": "where is my package" }, { "name": "Cargo Tracking API: operations", "description": "writes, gated by X-API-Key" }, { "name": "Space Agency API: launches", "description": "countdowns and scrubs" }, { "name": "Space Agency API: crew", "description": "astronauts on the roster" }, { "name": "Space Agency API: probes", "description": "deep space, slow answers" }, { "name": "Starfleet API: ships", "description": "the fleet, mostly functional" }, { "name": "Starfleet API: crew", "description": "rosters and redshirts" }, { "name": "Starfleet API: tribbles", "description": "do NOT keep GETting" }, { "name": "World Cup 2026 API: teams", "description": "national squads and groups" }, { "name": "World Cup 2026 API: matches", "description": "fixtures, simulation and VAR" }, { "name": "World Cup 2026 API: venues", "description": "2026 host stadiums" }, { "name": "World Cup 2026 API: players", "description": "Golden Boot race" }, { "name": "World Cup 2026 API: tickets", "description": "limited seats, real conflicts" }, { "name": "World Cup 2026 API: fanzone", "description": "mascots and predictions" }, { "name": "FIBA World Cup API: teams", "description": "the 32 qualified nations" }, { "name": "FIBA World Cup API: games", "description": "simulation, box scores and reviews" }, { "name": "FIBA World Cup API: arenas", "description": "the Doha host courts" }, { "name": "FIBA World Cup API: players", "description": "stat leaders and the MVP race" }, { "name": "FIBA World Cup API: tickets", "description": "limited seats, real conflicts" }, { "name": "GTA API: characters", "description": "heroes and contacts" }, { "name": "GTA API: vehicles", "description": "cars and Pay-n-Spray" }, { "name": "GTA API: weapons", "description": "the ammu-nation catologue" }, { "name": "GTA API: missions", "description": "story jobs with prereqs" }, { "name": "GTA API: wanted", "description": "stars, bribes and police chases" }, { "name": "GTA API: radio", "description": "in-game stations" }, { "name": "Dragon Ball API: fighters", "description": "warriors and power levels" }, { "name": "Dragon Ball API: tournaments", "description": "battle simulation" }, { "name": "Formula 1 API: grid", "description": "drivers and constructors" }, { "name": "Formula 1 API: races", "description": "events and results" }, { "name": "Formula 1 API: telemetry", "description": "laps and pit stops" }, { "name": "Voxel Worlds API: worlds", "description": "procedural block worlds" }, { "name": "Voxel Worlds API: players", "description": "survival stats and inventory" }, { "name": "Anime Tournament API: fighters", "description": "heroes and rivals" }, { "name": "Anime Tournament API: matches", "description": "tournament battles" }, { "name": "Retro Quest API: heroes", "description": "pixel adventurers" }, { "name": "Retro Quest API: quests", "description": "bugs disguised as monsters" }, { "name": "Object Storage API: objects", "description": "stored test files" }, { "name": "Object Storage API: uploads", "description": "resumable sessions" }, { "name": "Modern Identity API: discovery", "description": "provider metadata" }, { "name": "Modern Identity API: tokens", "description": "PKCE and lifecycle" }, { "name": "Event Streams API: events", "description": "stream and replay" }, { "name": "Fault Injection API: control", "description": "fault profile" }, { "name": "Fault Injection API: target", "description": "endpoint under test" }, { "name": "Search & Facets API: search", "description": "query and discover" }, { "name": "Fun Data Bridge API: generate", "description": "schemas and fixtures" } ], "paths": { "/friends/v1/characters": { "get": { "tags": [ "Friends API: characters" ], "summary": "List all characters (paginated) — v1, deprecated", "operationId": "fr-list", "responses": { "200": { "description": "Paginated character list, with Deprecation/Sunset/Link headers pointing at v2", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid page parameter, or an unknown query parameter (strict mode)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Page out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, default 1. Out of range → 404, non-integer → 400.", "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "job", "in": "query", "required": false, "description": "Filter by occupation, e.g. chef, actor, barista.", "schema": { "type": "string" } } ], "deprecated": true }, "post": { "tags": [ "Friends API: characters" ], "summary": "Create a character", "operationId": "fr-post", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing name / invalid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat the same key on retry to get the original response instead of a duplicate.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "job": { "type": "string" }, "catchphrase": { "type": "string" } }, "required": [ "name", "job", "catchphrase" ], "additionalProperties": false }, "example": { "name": "Gunther Jr.", "job": "barista", "catchphrase": "More coffee?" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/friends/v1/characters/{id}": { "get": { "tags": [ "Friends API: characters" ], "summary": "Get one character", "operationId": "fr-get", "responses": { "200": { "description": "The character", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Character id. Try 999 for a 404.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] }, "put": { "tags": [ "Friends API: characters" ], "summary": "Update a character", "operationId": "fr-put", "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Empty body / invalid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Character id to update.", "schema": { "type": "integer", "format": "int32" }, "example": 7 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency: pass a prior etag (e.g. v1). Mismatch → 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "job": { "type": "string" } }, "required": [ "job" ], "additionalProperties": false }, "example": { "job": "coffee shop owner" } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Friends API: characters" ], "summary": "Delete a character", "operationId": "fr-del", "responses": { "204": { "description": "Deleted, empty body" }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Character id. Viewer token → 403.", "schema": { "type": "integer", "format": "int32" }, "example": 12 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency check. Mismatch → 412.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ] } }, "/friends/v1/characters/bulk": { "post": { "tags": [ "Friends API: characters" ], "summary": "Batch-create characters (array body, per-item validation)", "operationId": "fr-bulk", "responses": { "201": { "description": "All items created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "207": { "description": "Partial success — some items failed validation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Body is not a JSON array", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "job": { "type": "string" } }, "required": [ "name", "job" ], "additionalProperties": false } }, "example": [ { "name": "Gunther Jr.", "job": "barista" }, { "name": "Estelle II", "job": "agent" } ] } } }, "security": [ { "bearerAuth": [] } ] } }, "/friends/v1/characters/bulk-delete": { "post": { "tags": [ "Friends API: characters" ], "summary": "Bulk-delete characters by id (partial success supported)", "operationId": "fr-bulk-del", "responses": { "200": { "description": "All ids existed and were deleted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "207": { "description": "Partial success — some ids did not exist", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "\"ids\" is missing, empty, or not an array of integers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer" } } }, "required": [ "ids" ], "additionalProperties": false }, "example": { "ids": [ 11, 12, 999 ] } } } }, "security": [ { "bearerAuth": [] } ] } }, "/friends/v1/episodes": { "get": { "tags": [ "Friends API: episodes" ], "summary": "List episodes, filter by season", "operationId": "fr-eps", "responses": { "200": { "description": "Episode list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Non-integer season", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "season", "in": "query", "required": false, "description": "Season 1–10. Try \"five\" for a 400.", "schema": { "type": "integer", "format": "int32" }, "example": 5 } ] } }, "/friends/v1/quotes/random": { "get": { "tags": [ "Friends API: quotes" ], "summary": "A random quote", "operationId": "fr-quote", "responses": { "200": { "description": "One random quote", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/friends/v1/characters/{id}/quotes": { "get": { "tags": [ "Friends API: characters" ], "summary": "Get a character's quotes (nested resource)", "operationId": "fr-char-quotes", "responses": { "200": { "description": "Matching quotes", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown character", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Character id.", "schema": { "type": "integer", "format": "int32" }, "example": 2 } ] } }, "/friends/v1/friends/v2/characters": { "get": { "tags": [ "Friends API: characters" ], "summary": "List characters — v2 (breaking change: job → occupation, re-wrapped)", "operationId": "fr-v2-list", "responses": { "200": { "description": "v2 shape: { apiVersion, data: { items, count } }, occupation replaces job", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid page parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Page out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, default 1.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "servers": [ { "url": "https://funapi.dev/api" } ] } }, "/friends/v1/friends/version": { "get": { "tags": [ "Friends API: characters" ], "summary": "Discover supported API versions", "operationId": "fr-version", "responses": { "200": { "description": "Current, supported and deprecated versions", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "servers": [ { "url": "https://funapi.dev/api" } ] } }, "/friends/v1/friends/characters": { "get": { "tags": [ "Friends API: characters" ], "summary": "Content-negotiated version via Accept header (406 if unsupported)", "operationId": "fr-negotiate", "responses": { "200": { "description": "Shape depends on negotiated version", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "406": { "description": "Accept header requests an unsupported media type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Accept", "in": "header", "required": false, "description": "application/vnd.friends.v1+json or application/vnd.friends.v2+json (default: v2). Anything else → 406.", "schema": { "type": "string" }, "example": "application/vnd.friends.v2+json" } ], "servers": [ { "url": "https://funapi.dev/api" } ] } }, "/friends/v1/graphql": { "post": { "tags": [ "Friends API: graphql" ], "summary": "Run a query or mutation over character data", "operationId": "gq-post", "responses": { "200": { "description": "GraphQL convention: always 200, with data and/or an errors array", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Missing \"query\" string, or completely unrecognized syntax", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" } }, "required": [ "query" ], "additionalProperties": false }, "example": { "query": "{ characters { id name job } }" } } } } } }, "/superheroes/v1/heroes": { "get": { "tags": [ "Superhero API: heroes" ], "summary": "List heroes (paginated, filterable)", "operationId": "sh-list", "responses": { "200": { "description": "Paginated hero list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Page out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, default 1.", "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "power", "in": "query", "required": false, "description": "Filter by power, e.g. light.", "schema": { "type": "string" } }, { "name": "team", "in": "query", "required": false, "description": "Filter by team, e.g. Alpha Squad.", "schema": { "type": "string" } } ] }, "post": { "tags": [ "Superhero API: heroes" ], "summary": "Register a new hero", "operationId": "sh-post", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing name or power", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat the same key on retry to get the original response instead of a duplicate.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "power": { "type": "string" }, "team": { "type": "string" } }, "required": [ "name", "power", "team" ], "additionalProperties": false }, "example": { "name": "Query Queen", "power": "finding anything", "team": "Freelance" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/superheroes/v1/heroes/{id}": { "get": { "tags": [ "Superhero API: heroes" ], "summary": "Get one hero", "operationId": "sh-get", "responses": { "200": { "description": "The hero", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Hero id 1–8.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] }, "delete": { "tags": [ "Superhero API: heroes" ], "summary": "Retire a hero", "operationId": "sh-del", "responses": { "204": { "description": "Retired" }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Hero id. Viewer token → 403.", "schema": { "type": "integer", "format": "int32" }, "example": 4 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency check. Mismatch → 412.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ] } }, "/superheroes/v1/heroes/{id}/nemesis": { "get": { "tags": [ "Superhero API: heroes" ], "summary": "Get a hero's nemesis (nested resource)", "operationId": "sh-nem", "responses": { "200": { "description": "The nemesis", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown hero or no nemesis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Try 3 — Aqua Comet has no nemesis → 404.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/superheroes/v1/heroes/versus": { "post": { "tags": [ "Superhero API: heroes" ], "summary": "Simulate a fight between two heroes", "operationId": "sh-versus", "responses": { "201": { "description": "Fight resolved, random winner", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Same hero twice or unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "heroAId": { "type": "integer" }, "heroBId": { "type": "integer" } }, "required": [ "heroAId", "heroBId" ], "additionalProperties": false }, "example": { "heroAId": 1, "heroBId": 3 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/pizza/v1/menu": { "delete": { "tags": [ "Pizza Orders API: menu" ], "summary": "Delete the menu — always 405, the menu is read-only", "operationId": "pz-menu-del", "responses": { "405": { "description": "Always. GET is the only supported method on /menu.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Pizza Orders API: menu" ], "summary": "Get the menu", "operationId": "pz-menu", "responses": { "200": { "description": "The menu", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid vegetarian value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "vegetarian", "in": "query", "required": false, "description": "true / false to filter. Anything else → 400.", "schema": { "type": "string" } } ] } }, "/pizza/v1/orders": { "post": { "tags": [ "Pizza Orders API: orders" ], "summary": "Place an order (validated)", "operationId": "pz-post", "responses": { "201": { "description": "Order placed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Unknown pizzaId, bad size, or missing address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat the same key on retry to get the original response instead of a duplicate.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pizzaId": { "type": "integer" }, "size": { "type": "string" }, "address": { "type": "string" } }, "required": [ "pizzaId", "size", "address" ], "additionalProperties": false }, "example": { "pizzaId": 3, "size": "L", "address": "Central Perk, New York" } } } } } }, "/pizza/v1/orders/{id}": { "get": { "tags": [ "Pizza Orders API: orders" ], "summary": "Track an order", "operationId": "pz-get", "responses": { "200": { "description": "The order", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Try 101 or 102 (seeded), or your own from POST /orders.", "schema": { "type": "integer", "format": "int32" }, "example": 101 } ] }, "patch": { "tags": [ "Pizza Orders API: orders" ], "summary": "Partially update an order (address or size)", "operationId": "pz-patch", "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Empty body, invalid JSON, or bad size", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id.", "schema": { "type": "integer", "format": "int32" }, "example": 101 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string" } }, "required": [ "address" ], "additionalProperties": false }, "example": { "address": "90 Bedford St, New York, Apt 2" } } } } }, "delete": { "tags": [ "Pizza Orders API: orders" ], "summary": "Cancel an order (409 if already delivered)", "operationId": "pz-cancel", "responses": { "204": { "description": "Cancelled" }, "404": { "description": "Unknown order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Order already delivered — cannot cancel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id. Try 101 (seeded, delivered) for a 409.", "schema": { "type": "integer", "format": "int32" }, "example": 102 } ] } }, "/pizza/v1/orders/{id}/status": { "put": { "tags": [ "Pizza Orders API: orders" ], "summary": "Update order status", "operationId": "pz-put", "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid status value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id.", "schema": { "type": "integer", "format": "int32" }, "example": 102 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency: pass a prior etag (e.g. v1). Mismatch → 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ], "additionalProperties": false }, "example": { "status": "out-for-delivery" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/pizza/v1/oven/status": { "get": { "tags": [ "Pizza Orders API: oven" ], "summary": "Always returns 500 — for negative tests", "operationId": "pz-oven", "responses": { "500": { "description": "Always. The oven is on fire.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pizza/v1/oven/preheat": { "get": { "tags": [ "Pizza Orders API: oven" ], "summary": "Preheat the oven — always takes ~3s", "operationId": "pz-preheat", "responses": { "200": { "description": "Preheated, after a deliberate ~3s delay", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/coffee/v1/drinks": { "get": { "tags": [ "Coffee Shop API: drinks" ], "summary": "List drinks, filter by type", "operationId": "cf-list", "responses": { "200": { "description": "Drink list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "type", "in": "query", "required": false, "description": "\"hot\" or \"cold\". Anything else → 400.", "schema": { "type": "string" }, "example": "hot" } ] } }, "/coffee/v1/drinks/{id}": { "get": { "tags": [ "Coffee Shop API: drinks" ], "summary": "Get one drink", "operationId": "cf-get", "responses": { "200": { "description": "The drink", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Drink id 1–8.", "schema": { "type": "integer", "format": "int32" }, "example": 8 } ] } }, "/coffee/v1/orders": { "post": { "tags": [ "Coffee Shop API: orders" ], "summary": "Order a drink", "operationId": "cf-post", "responses": { "201": { "description": "Order placed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Unknown drinkId or missing name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat the same key on retry to get the original response instead of a duplicate.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "drinkId": { "type": "integer" }, "size": { "type": "string" }, "name": { "type": "string" } }, "required": [ "drinkId", "size", "name" ], "additionalProperties": false }, "example": { "drinkId": 2, "size": "grande", "name": "Rachel" } } } } } }, "/coffee/v1/rush-hour": { "get": { "tags": [ "Coffee Shop API: rush" ], "summary": "Rush hour special — max 3 requests per 10s", "operationId": "cf-rush", "responses": { "200": { "description": "Got a spot in line", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "Too many requests — wait for Retry-After seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } } }, "/coffee/v1/teapot": { "get": { "tags": [ "Coffee Shop API: teapot" ], "summary": "Try to brew coffee in a teapot", "operationId": "cf-teapot", "responses": { "418": { "description": "Always. It is, in fact, a teapot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/coffee/v1/orders/{id}/ready": { "put": { "tags": [ "Coffee Shop API: orders" ], "summary": "Mark an order ready (409 if already ready)", "operationId": "cf-ready", "responses": { "200": { "description": "Marked ready", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Order is already ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id from a prior POST /orders.", "schema": { "type": "integer", "format": "int32" }, "example": 501 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency: pass a prior etag (e.g. v1). Mismatch → 412.", "schema": { "type": "string" } } ] } }, "/football/v1/teams": { "get": { "tags": [ "Football API: teams" ], "summary": "List teams (paginated)", "operationId": "fb-teams", "responses": { "200": { "description": "Paginated team list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Page out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, 4 per page.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/football/v1/teams/{id}": { "get": { "tags": [ "Football API: teams" ], "summary": "Get one team", "operationId": "fb-team", "responses": { "200": { "description": "The team", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id 1–6.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] }, "delete": { "tags": [ "Football API: teams" ], "summary": "Remove a team (409 if it has played matches)", "operationId": "fb-team-del", "responses": { "204": { "description": "Removed" }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Team has played matches", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id. Viewer token → 403.", "schema": { "type": "integer", "format": "int32" }, "example": 5 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency check. Mismatch → 412.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ] } }, "/football/v1/teams/{id}/players": { "get": { "tags": [ "Football API: teams" ], "summary": "Get a team's squad (nested)", "operationId": "fb-players", "responses": { "200": { "description": "Player list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id 1–6.", "schema": { "type": "integer", "format": "int32" }, "example": 2 } ] } }, "/football/v1/teams/{id}/matches": { "get": { "tags": [ "Football API: teams" ], "summary": "Get a team's match history (nested resource)", "operationId": "fb-team-matches", "responses": { "200": { "description": "Match list for the team", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Team id 1–6. Empty until you POST /matches.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/football/v1/standings": { "get": { "tags": [ "Football API: league" ], "summary": "League table — cacheable (ETag / If-None-Match / 304)", "operationId": "fb-standings", "responses": { "200": { "description": "Current standings, with ETag + Cache-Control headers", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "304": { "description": "Not Modified — If-None-Match matched the current etag", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "If-None-Match", "in": "header", "required": false, "description": "Pass a prior etag; if unchanged, get 304 with no body instead of re-downloading the table.", "schema": { "type": "string" } } ] } }, "/football/v1/matches": { "post": { "tags": [ "Football API: league" ], "summary": "Simulate a match", "operationId": "fb-match", "responses": { "201": { "description": "Match played, random score", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Same team twice or unknown team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat the same key on retry to get the original response instead of a duplicate.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "homeTeamId": { "type": "integer" }, "awayTeamId": { "type": "integer" } }, "required": [ "homeTeamId", "awayTeamId" ], "additionalProperties": false }, "example": { "homeTeamId": 1, "awayTeamId": 2 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/movies/v1/movies": { "get": { "tags": [ "Movies API: movies" ], "summary": "List movies (filter, sort, paginate)", "operationId": "mv-list", "responses": { "200": { "description": "Paginated movie list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid sort or page, or an unknown query parameter (strict mode)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Page out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "genre", "in": "query", "required": false, "description": "thriller, drama, comedy, horror, action, documentary.", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "Exact release year.", "schema": { "type": "integer", "format": "int32" } }, { "name": "sort", "in": "query", "required": false, "description": "\"rating\" or \"year\". Anything else → 400.", "schema": { "type": "string" }, "example": "rating" }, { "name": "page", "in": "query", "required": false, "description": "Page number, 5 per page.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] }, "post": { "tags": [ "Movies API: movies" ], "summary": "Add a movie", "operationId": "mv-post", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing title", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat the same key on retry to get the original response instead of a duplicate.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "genre": { "type": "string" }, "year": { "type": "integer" }, "rating": { "type": "integer" } }, "required": [ "title", "genre", "year", "rating" ], "additionalProperties": false }, "example": { "title": "Merge Conflict", "genre": "drama", "year": 2026, "rating": 8 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/movies/v1/movies/{id}": { "get": { "tags": [ "Movies API: movies" ], "summary": "Get one movie", "operationId": "mv-get", "responses": { "200": { "description": "The movie", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Movie id 1–10.", "schema": { "type": "integer", "format": "int32" }, "example": 9 } ] }, "delete": { "tags": [ "Movies API: movies" ], "summary": "Remove a movie", "operationId": "mv-del", "responses": { "204": { "description": "Removed" }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Movie id. Viewer token → 403.", "schema": { "type": "integer", "format": "int32" }, "example": 7 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency check. Mismatch → 412.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ] } }, "/movies/v1/search": { "get": { "tags": [ "Movies API: movies" ], "summary": "Full-text search movie titles", "operationId": "mv-search", "responses": { "200": { "description": "Matching movies", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Case-insensitive substring match against the title.", "schema": { "type": "string" }, "example": "edge" } ] } }, "/movies/v1/search/fuzzy": { "get": { "tags": [ "Movies API: movies" ], "summary": "Typo-tolerant search (fuzzy match, \"did you mean\")", "operationId": "mv-fuzzy-search", "responses": { "200": { "description": "Ranked matches with an editDistance and score; empty data + suggestion if nothing is close enough", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Missing \"q\" or invalid maxDistance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Try a misspelling, e.g. \"eg case\" or \"productoin down\".", "schema": { "type": "string" }, "example": "edge cse" }, { "name": "maxDistance", "in": "query", "required": false, "description": "Max edit distance to accept as a match, default 2. Try 0 to require exact spelling.", "schema": { "type": "integer", "format": "int32" }, "example": 2 } ] } }, "/movies/v1/movies/{id}/rating": { "put": { "tags": [ "Movies API: movies" ], "summary": "Rate a movie (0–10 inclusive)", "operationId": "mv-rate", "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Rating outside the inclusive 0–10 range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Movie id.", "schema": { "type": "integer", "format": "int32" }, "example": 7 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency: pass a prior etag (e.g. v1). Mismatch → 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rating": { "type": "number" } }, "required": [ "rating" ], "additionalProperties": false }, "example": { "rating": 6.5 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/movies/v1/movies/{id}/similar": { "get": { "tags": [ "Movies API: movies" ], "summary": "Get movies with the same genre (recommendation)", "operationId": "mv-similar", "responses": { "200": { "description": "Similar movies", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Movie id.", "schema": { "type": "integer", "format": "int32" }, "example": 8 } ] } }, "/movies/v1/movies/{id}/poster": { "post": { "tags": [ "Movies API: uploads" ], "summary": "Upload a movie poster (simulated multipart file upload)", "operationId": "mv-poster", "responses": { "201": { "description": "Uploaded", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing filename or sizeBytes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown movie", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "sizeBytes over the 5 MB limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "contentType is not an accepted image type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Movie id.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" } }, "required": [ "filename", "contentType", "sizeBytes" ], "additionalProperties": false }, "example": { "filename": "poster.jpg", "contentType": "image/jpeg", "sizeBytes": 2400000 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/wizarding/v1/houses": { "get": { "tags": [ "Harry Potter API: houses" ], "summary": "List all houses", "operationId": "hp-houses", "responses": { "200": { "description": "All four houses", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/wizarding/v1/houses/{id}": { "get": { "tags": [ "Harry Potter API: houses" ], "summary": "Get one house", "operationId": "hp-house", "responses": { "200": { "description": "The house", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "House id 1–4.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/wizarding/v1/students": { "get": { "tags": [ "Harry Potter API: students" ], "summary": "List students (paginated, filter by house)", "operationId": "hp-students", "responses": { "200": { "description": "Paginated student list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid page or houseId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Page out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, default 1.", "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "houseId", "in": "query", "required": false, "description": "Filter by house id 1–4.", "schema": { "type": "integer", "format": "int32" } } ] }, "post": { "tags": [ "Harry Potter API: students" ], "summary": "Enroll a student", "operationId": "hp-post", "responses": { "201": { "description": "Enrolled", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing name or unknown houseId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat the same key on retry to get the original response instead of a duplicate.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "houseId": { "type": "integer" }, "year": { "type": "integer" } }, "required": [ "name", "houseId", "year" ], "additionalProperties": false }, "example": { "name": "Rowan Ashby", "houseId": 1, "year": 1 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/wizarding/v1/students/{id}": { "get": { "tags": [ "Harry Potter API: students" ], "summary": "Get one student", "operationId": "hp-student", "responses": { "200": { "description": "The student", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Student id. Try 999 for a 404.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] }, "put": { "tags": [ "Harry Potter API: students" ], "summary": "Update a student", "operationId": "hp-put", "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Empty body / invalid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Student id to update.", "schema": { "type": "integer", "format": "int32" }, "example": 2 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency: pass a prior etag (e.g. v1). Mismatch → 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "year": { "type": "integer" }, "patronus": { "type": "string" } }, "required": [ "year", "patronus" ], "additionalProperties": false }, "example": { "year": 7, "patronus": "wolf" } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Harry Potter API: students" ], "summary": "Expel a student", "operationId": "hp-del", "responses": { "204": { "description": "Expelled" }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Student id. Viewer token → 403.", "schema": { "type": "integer", "format": "int32" }, "example": 8 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency check. Mismatch → 412.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ] } }, "/wizarding/v1/spells": { "get": { "tags": [ "Harry Potter API: spells" ], "summary": "List spells, filter by type", "operationId": "hp-spells", "responses": { "200": { "description": "Spell list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "type", "in": "query", "required": false, "description": "charm, jinx, or unforgivable.", "schema": { "type": "string" } } ] } }, "/wizarding/v1/spells/random": { "get": { "tags": [ "Harry Potter API: spells" ], "summary": "A random spell", "operationId": "hp-spell-random", "responses": { "200": { "description": "One random spell", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/wizarding/v1/sorting-hat": { "post": { "tags": [ "Harry Potter API: houses" ], "summary": "The Sorting Hat assigns you a house (stateless, random)", "operationId": "hp-sorting-hat", "responses": { "200": { "description": "Your assigned house", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/galaxy/v1/planets": { "get": { "tags": [ "Star Wars API: planets" ], "summary": "List all planets", "operationId": "sw-planets", "responses": { "200": { "description": "All planets", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/galaxy/v1/planets/{id}": { "get": { "tags": [ "Star Wars API: planets" ], "summary": "Get one planet", "operationId": "sw-planet", "responses": { "200": { "description": "The planet", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Planet id 1–5.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/galaxy/v1/characters": { "get": { "tags": [ "Star Wars API: characters" ], "summary": "List characters (paginated, filter by affiliation)", "operationId": "sw-characters", "responses": { "200": { "description": "Paginated character list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Page out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, default 1.", "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "affiliation", "in": "query", "required": false, "description": "Rebellion, Empire, or neutral.", "schema": { "type": "string" } } ] }, "post": { "tags": [ "Star Wars API: characters" ], "summary": "Add a character", "operationId": "sw-post", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing name or unknown homeworldId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat the same key on retry to get the original response instead of a duplicate.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "species": { "type": "string" }, "affiliation": { "type": "string" }, "homeworldId": { "type": "integer" } }, "required": [ "name", "species", "affiliation", "homeworldId" ], "additionalProperties": false }, "example": { "name": "Zeta Corvain", "species": "human", "affiliation": "Rebellion", "homeworldId": 1 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/galaxy/v1/characters/{id}": { "get": { "tags": [ "Star Wars API: characters" ], "summary": "Get one character", "operationId": "sw-character", "responses": { "200": { "description": "The character", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Character id. Try 999 for a 404.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] }, "put": { "tags": [ "Star Wars API: characters" ], "summary": "Update a character", "operationId": "sw-put", "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Empty body / invalid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Character id to update.", "schema": { "type": "integer", "format": "int32" }, "example": 5 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency: pass a prior etag (e.g. v1). Mismatch → 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "affiliation": { "type": "string" } }, "required": [ "affiliation" ], "additionalProperties": false }, "example": { "affiliation": "Rebellion" } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Star Wars API: characters" ], "summary": "Remove a character", "operationId": "sw-del", "responses": { "204": { "description": "Removed" }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Character id. Viewer token → 403.", "schema": { "type": "integer", "format": "int32" }, "example": 7 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency check. Mismatch → 412.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ] } }, "/galaxy/v1/characters/{id}/homeworld": { "get": { "tags": [ "Star Wars API: characters" ], "summary": "Get a character's homeworld (nested resource)", "operationId": "sw-homeworld", "responses": { "200": { "description": "The homeworld", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown character or planet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Character id.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/galaxy/v1/starships": { "get": { "tags": [ "Star Wars API: starships" ], "summary": "List starships, filter by class", "operationId": "sw-ships", "responses": { "200": { "description": "Starship list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "class", "in": "query", "required": false, "description": "freighter, capital ship, cruiser, starfighter.", "schema": { "type": "string" } } ] } }, "/galaxy/v1/starships/random": { "get": { "tags": [ "Star Wars API: starships" ], "summary": "A random starship", "operationId": "sw-ship-random", "responses": { "200": { "description": "One random starship", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/galaxy/v1/starships/{id}": { "get": { "tags": [ "Star Wars API: starships" ], "summary": "Get one starship", "operationId": "sw-ship-get", "responses": { "200": { "description": "The starship", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Starship id 1–5.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/holmes/v1/cases": { "get": { "tags": [ "Sherlock Holmes API: cases" ], "summary": "List all cases", "operationId": "hl-cases", "responses": { "200": { "description": "Case list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid status value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "status", "in": "query", "required": false, "description": "\"open\" or \"solved\".", "schema": { "type": "string" } } ] } }, "/holmes/v1/cases/{id}": { "get": { "tags": [ "Sherlock Holmes API: cases" ], "summary": "Get one case", "operationId": "hl-case", "responses": { "200": { "description": "The case", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Case id 1–5.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] }, "patch": { "tags": [ "Sherlock Holmes API: cases" ], "summary": "Update a case status (409 if unchanged)", "operationId": "hl-case-patch", "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "status must be \"open\" or \"solved\"", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Case is already in that status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Case id.", "schema": { "type": "integer", "format": "int32" }, "example": 3 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ], "additionalProperties": false }, "example": { "status": "solved" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/holmes/v1/cases/{id}/suspects": { "get": { "tags": [ "Sherlock Holmes API: cases" ], "summary": "Get all suspects for a case (nested resource)", "operationId": "hl-case-suspects", "responses": { "200": { "description": "Suspect list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown case", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Case id.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/holmes/v1/suspects/{id}": { "get": { "tags": [ "Sherlock Holmes API: suspects" ], "summary": "Get one suspect", "operationId": "hl-suspect", "responses": { "200": { "description": "The suspect", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Suspect id. Try 999 for a 404.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] }, "put": { "tags": [ "Sherlock Holmes API: suspects" ], "summary": "Update a suspect", "operationId": "hl-put", "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Empty body / invalid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Suspect id to update.", "schema": { "type": "integer", "format": "int32" }, "example": 6 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency: pass a prior etag (e.g. v1). Mismatch → 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "alibi": { "type": "string" }, "guilty": { "type": "boolean" } }, "required": [ "alibi", "guilty" ], "additionalProperties": false }, "example": { "alibi": "confirmed by three witnesses", "guilty": false } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Sherlock Holmes API: suspects" ], "summary": "Clear a suspect", "operationId": "hl-del", "responses": { "204": { "description": "Cleared" }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Suspect id. Viewer token → 403.", "schema": { "type": "integer", "format": "int32" }, "example": 5 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency check. Mismatch → 412.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ] } }, "/holmes/v1/suspects": { "post": { "tags": [ "Sherlock Holmes API: suspects" ], "summary": "Add a suspect to a case", "operationId": "hl-post", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing name or unknown caseId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat the same key on retry to get the original response instead of a duplicate.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "alibi": { "type": "string" }, "caseId": { "type": "integer" } }, "required": [ "name", "alibi", "caseId" ], "additionalProperties": false }, "example": { "name": "Mr. Hartley", "alibi": "claims he was asleep", "caseId": 3 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/holmes/v1/clues": { "get": { "tags": [ "Sherlock Holmes API: clues" ], "summary": "List clues, filter by case or type", "operationId": "hl-clues", "responses": { "200": { "description": "Clue list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "caseId", "in": "query", "required": false, "description": "Filter by case id.", "schema": { "type": "integer", "format": "int32" } }, { "name": "type", "in": "query", "required": false, "description": "physical, document, or testimony.", "schema": { "type": "string" } } ] } }, "/holmes/v1/clues/random": { "get": { "tags": [ "Sherlock Holmes API: clues" ], "summary": "A random clue", "operationId": "hl-clue-random", "responses": { "200": { "description": "One random clue", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/pokemon/v1/pokemon": { "get": { "tags": [ "Pokémon API: pokemon" ], "summary": "List Pokémon (paginated, filter by type)", "operationId": "pk-list", "responses": { "200": { "description": "Paginated Pokémon list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Page out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, default 1.", "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "type", "in": "query", "required": false, "description": "electric, grass, fire, water, normal, rock, psychic, ghost.", "schema": { "type": "string" } } ] }, "post": { "tags": [ "Pokémon API: pokemon" ], "summary": "Catch a new Pokémon (create)", "operationId": "pk-post", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing name or type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat the same key on retry to get the original response instead of a duplicate.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "level": { "type": "integer" }, "hp": { "type": "integer" } }, "required": [ "name", "type", "level", "hp" ], "additionalProperties": false }, "example": { "name": "Eevee", "type": "normal", "level": 5, "hp": 55 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/pokemon/v1/pokemon/{id}": { "get": { "tags": [ "Pokémon API: pokemon" ], "summary": "Get one Pokémon", "operationId": "pk-get", "responses": { "200": { "description": "The Pokémon", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Pokémon id. Try 999 for a 404.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] }, "put": { "tags": [ "Pokémon API: pokemon" ], "summary": "Update a Pokémon (level up, heal, etc.)", "operationId": "pk-put", "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Empty body / invalid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Pokémon id to update.", "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency: pass a prior etag (e.g. v1). Mismatch → 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "level": { "type": "integer" }, "hp": { "type": "integer" } }, "required": [ "level", "hp" ], "additionalProperties": false }, "example": { "level": 13, "hp": 65 } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Pokémon API: pokemon" ], "summary": "Release a Pokémon", "operationId": "pk-del", "responses": { "204": { "description": "Released" }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Pokémon id. Viewer token → 403.", "schema": { "type": "integer", "format": "int32" }, "example": 8 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency check. Mismatch → 412.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ] } }, "/pokemon/v1/pokemon/random": { "get": { "tags": [ "Pokémon API: pokemon" ], "summary": "A random Pokémon (wild encounter)", "operationId": "pk-random", "responses": { "200": { "description": "One random Pokémon", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/pokemon/v1/trainers": { "get": { "tags": [ "Pokémon API: trainers" ], "summary": "List all trainers", "operationId": "pk-trainers", "responses": { "200": { "description": "Trainer list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/pokemon/v1/trainers/{id}/pokemon": { "get": { "tags": [ "Pokémon API: trainers" ], "summary": "Get a trainer's roster (nested resource)", "operationId": "pk-trainer-roster", "responses": { "200": { "description": "Roster", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown trainer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Trainer id 1–3.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/pokemon/v1/battles": { "post": { "tags": [ "Pokémon API: battles" ], "summary": "Simulate a battle between two Pokémon", "operationId": "pk-battle", "responses": { "201": { "description": "Battle resolved, random winner", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Same Pokémon twice or unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat the same key on retry to get the original response instead of a duplicate.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pokemonAId": { "type": "integer" }, "pokemonBId": { "type": "integer" } }, "required": [ "pokemonAId", "pokemonBId" ], "additionalProperties": false }, "example": { "pokemonAId": 1, "pokemonBId": 4 } } } }, "security": [ { "bearerAuth": [] } ] }, "get": { "tags": [ "Pokémon API: battles" ], "summary": "List battle history (empty until you POST one)", "operationId": "pk-battles-list", "responses": { "200": { "description": "Battle history", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/middleearth/v1/fellowship": { "get": { "tags": [ "Middle-earth API: fellowship" ], "summary": "List fellowship members (paginated, filter by race)", "operationId": "me-list", "responses": { "200": { "description": "Paginated member list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Page out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, default 1.", "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "race", "in": "query", "required": false, "description": "hobbit, dwarf, elf, human, wizard.", "schema": { "type": "string" } } ] }, "post": { "tags": [ "Middle-earth API: fellowship" ], "summary": "Recruit a new member", "operationId": "me-post", "responses": { "201": { "description": "Recruited", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing name or race", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat the same key on retry to get the original response instead of a duplicate.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "race": { "type": "string" }, "skill": { "type": "string" } }, "required": [ "name", "race", "skill" ], "additionalProperties": false }, "example": { "name": "Fenwick Longstride", "race": "human", "skill": "tracking" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/middleearth/v1/fellowship/{id}": { "get": { "tags": [ "Middle-earth API: fellowship" ], "summary": "Get one fellowship member", "operationId": "me-get", "responses": { "200": { "description": "The member", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Member id. Try 999 for a 404.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] }, "put": { "tags": [ "Middle-earth API: fellowship" ], "summary": "Update a fellowship member", "operationId": "me-put", "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Empty body / invalid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Member id to update.", "schema": { "type": "integer", "format": "int32" }, "example": 6 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency: pass a prior etag (e.g. v1). Mismatch → 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "skill": { "type": "string" } }, "required": [ "skill" ], "additionalProperties": false }, "example": { "skill": "diplomacy" } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Middle-earth API: fellowship" ], "summary": "Remove a member from the fellowship", "operationId": "me-del", "responses": { "204": { "description": "Removed" }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Member id. Viewer token → 403.", "schema": { "type": "integer", "format": "int32" }, "example": 6 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency check. Mismatch → 412.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ] } }, "/middleearth/v1/fellowship/{id}/artifact": { "get": { "tags": [ "Middle-earth API: fellowship" ], "summary": "Get the artifact carried by a member (nested resource)", "operationId": "me-artifact", "responses": { "200": { "description": "The artifact", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown member or no artifact carried", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Try 4 — Halberd of Gondor carries nothing → 404.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/middleearth/v1/quests": { "get": { "tags": [ "Middle-earth API: quests" ], "summary": "List quests, filter by status", "operationId": "me-quests", "responses": { "200": { "description": "Quest list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid status value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "status", "in": "query", "required": false, "description": "not-started, in-progress, or complete.", "schema": { "type": "string" } } ] } }, "/middleearth/v1/quests/random": { "get": { "tags": [ "Middle-earth API: quests" ], "summary": "A random quest", "operationId": "me-quest-random", "responses": { "200": { "description": "One random quest", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/middleearth/v1/artifacts": { "get": { "tags": [ "Middle-earth API: artifacts" ], "summary": "List all artifacts", "operationId": "me-artifacts", "responses": { "200": { "description": "Artifact list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/auth/v1/login": { "post": { "tags": [ "Auth Playground API: real tokens" ], "summary": "Log in as a demo user and get a working token (roles: admin / viewer)", "operationId": "auth-login", "responses": { "200": { "description": "Token issued — use it as Authorization: Bearer ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Missing username or password", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unknown user or wrong password", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string" }, "password": { "type": "string" } }, "required": [ "username", "password" ], "additionalProperties": false }, "example": { "username": "admin", "password": "admin123" } } } } } }, "/auth/v1/firebase-token": { "post": { "tags": [ "Auth Playground API: real tokens" ], "summary": "Mint a simulated Firebase-style token whose role claim grants admin or viewer", "operationId": "auth-firebase", "responses": { "200": { "description": "Token minted — use it as Authorization: Bearer ", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "role must be \"admin\" or \"viewer\"", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string" } }, "required": [ "role" ], "additionalProperties": false }, "example": { "role": "viewer" } } } } } }, "/auth/v1/me": { "get": { "tags": [ "Auth Playground API: real tokens" ], "summary": "Inspect the token you are sending (role, kind, subject)", "operationId": "auth-me", "responses": { "200": { "description": "Who the playground thinks you are", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/auth/v1/oauth/authorize": { "post": { "tags": [ "Auth Playground API: oauth" ], "summary": "Step 1: request an authorization code", "operationId": "oa-authorize", "responses": { "200": { "description": "Authorization code issued (valid 60s, single use)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "invalid_client — unknown clientId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "redirectUri": { "type": "string" } }, "required": [ "clientId", "redirectUri" ], "additionalProperties": false }, "example": { "clientId": "demo-client", "redirectUri": "https://example.com/callback" } } } } } }, "/auth/v1/oauth/token": { "post": { "tags": [ "Auth Playground API: oauth" ], "summary": "Step 2: exchange for a token (client_credentials / authorization_code / refresh_token)", "operationId": "oa-token", "responses": { "200": { "description": "Token issued", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "invalid_request (missing grantType), invalid_client, or invalid_grant (bad/expired/used code, wrong clientId for the code, or bad refresh token)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grantType": { "type": "string" }, "clientId": { "type": "string" }, "clientSecret": { "type": "string" } }, "required": [ "grantType", "clientId", "clientSecret" ], "additionalProperties": false }, "example": { "grantType": "client_credentials", "clientId": "demo-client", "clientSecret": "demo-secret" } } } } } }, "/auth/v1/oauth/protected-resource": { "get": { "tags": [ "Auth Playground API: oauth" ], "summary": "A resource protected by a token from this flow (not the site-wide Authorize button)", "operationId": "oa-protected", "responses": { "200": { "description": "Protected data", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "invalid_token — missing, malformed, unknown, or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Pass \"Bearer \" from a /oauth/token response.", "schema": { "type": "string" }, "example": "Bearer " } ] } }, "/webhooks/v1/subscriptions": { "post": { "tags": [ "Webhooks API: subscriptions" ], "summary": "Register a webhook subscription", "operationId": "wh-sub-post", "responses": { "201": { "description": "Registered, includes a signingSecret", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing/invalid url or empty events array", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "events" ], "additionalProperties": false }, "example": { "url": "https://example.com/webhook-receiver", "events": [ "order.created", "order.delivered" ] } } } }, "security": [ { "bearerAuth": [] } ] }, "get": { "tags": [ "Webhooks API: subscriptions" ], "summary": "List webhook subscriptions (secrets redacted)", "operationId": "wh-sub-list", "responses": { "200": { "description": "Subscription list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/webhooks/v1/subscriptions/{id}": { "delete": { "tags": [ "Webhooks API: subscriptions" ], "summary": "Unsubscribe", "operationId": "wh-sub-del", "responses": { "204": { "description": "Unsubscribed" }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Subscription id. Viewer token → 403.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "security": [ { "bearerAuth": [] } ] } }, "/webhooks/v1/trigger": { "post": { "tags": [ "Webhooks API: deliveries" ], "summary": "Fire an event to all matching subscriptions (~70% simulated success)", "operationId": "wh-trigger", "responses": { "200": { "description": "No subscriptions matched this event", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "201": { "description": "Delivered to one or more subscriptions", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string" }, "payload": { "type": "object", "properties": { "orderId": { "type": "integer" } }, "required": [ "orderId" ], "additionalProperties": false } }, "required": [ "event", "payload" ], "additionalProperties": false }, "example": { "event": "order.created", "payload": { "orderId": 501 } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/webhooks/v1/deliveries": { "get": { "tags": [ "Webhooks API: deliveries" ], "summary": "List delivery attempts, filter by status or subscription", "operationId": "wh-deliveries-list", "responses": { "200": { "description": "Delivery list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid status value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "status", "in": "query", "required": false, "description": "\"delivered\" or \"failed\".", "schema": { "type": "string" } }, { "name": "subscriptionId", "in": "query", "required": false, "description": "Filter by subscription id.", "schema": { "type": "integer", "format": "int32" } } ], "security": [ { "bearerAuth": [] } ] } }, "/webhooks/v1/deliveries/{id}/replay": { "post": { "tags": [ "Webhooks API: deliveries" ], "summary": "Replay a delivery attempt (409 after 3 attempts)", "operationId": "wh-replay", "responses": { "200": { "description": "Replayed, status re-rolled", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Max attempts (3) already reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Delivery id from POST /trigger.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "security": [ { "bearerAuth": [] } ] } }, "/webhooks/v1/verify-signature": { "post": { "tags": [ "Webhooks API: deliveries" ], "summary": "Verify a payload signature (simulated scheme, not real HMAC)", "operationId": "wh-verify", "responses": { "200": { "description": "Whether the signature matches", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Missing secret", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payload": { "type": "object", "properties": { "orderId": { "type": "integer" } }, "required": [ "orderId" ], "additionalProperties": false }, "signature": { "type": "string" }, "secret": { "type": "string" } }, "required": [ "payload", "signature", "secret" ], "additionalProperties": false }, "example": { "payload": { "orderId": 501 }, "signature": "sha256-sim=00000000", "secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxx" } } } } } }, "/office/v1/employees": { "get": { "tags": [ "The Office API: employees" ], "summary": "List employees (paginated, filter by department)", "operationId": "of-list", "responses": { "200": { "description": "Paginated employee list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Page out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, default 1.", "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "department", "in": "query", "required": false, "description": "Sales, Accounting, Management, Reception, Warehouse.", "schema": { "type": "string" } } ] }, "post": { "tags": [ "The Office API: employees" ], "summary": "Hire a new employee", "operationId": "of-post", "responses": { "201": { "description": "Hired", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing name or role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat the same key on retry to get the original response instead of a duplicate.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "department": { "type": "string" } }, "required": [ "name", "role", "department" ], "additionalProperties": false }, "example": { "name": "Holly Flax-son", "role": "HR Representative", "department": "Human Resources" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/office/v1/employees/{id}": { "get": { "tags": [ "The Office API: employees" ], "summary": "Get one employee", "operationId": "of-get", "responses": { "200": { "description": "The employee", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Employee id. Try 999 for a 404.", "schema": { "type": "integer", "format": "int32" }, "example": 2 } ] }, "put": { "tags": [ "The Office API: employees" ], "summary": "Update an employee", "operationId": "of-put", "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Empty body / invalid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Employee id to update.", "schema": { "type": "integer", "format": "int32" }, "example": 6 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency: pass a prior etag (e.g. v1). Mismatch → 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string" } }, "required": [ "role" ], "additionalProperties": false }, "example": { "role": "Senior Accountant" } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "The Office API: employees" ], "summary": "Fire an employee", "operationId": "of-del", "responses": { "204": { "description": "Fired" }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Employee id. Viewer token → 403.", "schema": { "type": "integer", "format": "int32" }, "example": 8 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency check. Mismatch → 412.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ] } }, "/office/v1/employees/{id}/pranks": { "get": { "tags": [ "The Office API: employees" ], "summary": "Get pranks involving an employee (nested resource)", "operationId": "of-pranks-on", "responses": { "200": { "description": "Matching pranks", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown employee", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Try 2 for Dwight's long list.", "schema": { "type": "integer", "format": "int32" }, "example": 2 } ] } }, "/office/v1/pranks": { "get": { "tags": [ "The Office API: pranks" ], "summary": "List pranks, filter by severity", "operationId": "of-pranks", "responses": { "200": { "description": "Prank list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid severity value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "severity", "in": "query", "required": false, "description": "mild, classic, or severe.", "schema": { "type": "string" } } ] } }, "/office/v1/quotes/random": { "get": { "tags": [ "The Office API: quotes" ], "summary": "A random quote", "operationId": "of-quote-random", "responses": { "200": { "description": "One random quote", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/dinopark/v1/dinosaurs": { "get": { "tags": [ "Dino Park API: dinosaurs" ], "summary": "List dinosaurs (paginated, filter by diet)", "operationId": "dp-list", "responses": { "200": { "description": "Paginated dinosaur list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid page or diet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Page out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, default 1.", "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "diet", "in": "query", "required": false, "description": "\"carnivore\" or \"herbivore\".", "schema": { "type": "string" } } ] }, "post": { "tags": [ "Dino Park API: dinosaurs" ], "summary": "Add a dinosaur (409 if enclosure is at capacity)", "operationId": "dp-post", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing name/species or unknown enclosureId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Enclosure is at capacity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat the same key on retry to get the original response instead of a duplicate.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "species": { "type": "string" }, "diet": { "type": "string" }, "enclosureId": { "type": "integer" }, "dangerLevel": { "type": "string" } }, "required": [ "name", "species", "diet", "enclosureId", "dangerLevel" ], "additionalProperties": false }, "example": { "name": "Indominus", "species": "Indominus rex", "diet": "carnivore", "enclosureId": 1, "dangerLevel": "extreme" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/dinopark/v1/dinosaurs/{id}": { "get": { "tags": [ "Dino Park API: dinosaurs" ], "summary": "Get one dinosaur", "operationId": "dp-get", "responses": { "200": { "description": "The dinosaur", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Dinosaur id. Try 999 for a 404.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] }, "put": { "tags": [ "Dino Park API: dinosaurs" ], "summary": "Update a dinosaur", "operationId": "dp-put", "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Empty body / invalid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Dinosaur id to update.", "schema": { "type": "integer", "format": "int32" }, "example": 5 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency: pass a prior etag (e.g. v1). Mismatch → 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "dangerLevel": { "type": "string" } }, "required": [ "dangerLevel" ], "additionalProperties": false }, "example": { "dangerLevel": "high" } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Dino Park API: dinosaurs" ], "summary": "Relocate a dinosaur off-site", "operationId": "dp-del", "responses": { "204": { "description": "Relocated" }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Dinosaur id. Viewer token → 403.", "schema": { "type": "integer", "format": "int32" }, "example": 6 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency check. Mismatch → 412.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ] } }, "/dinopark/v1/dinosaurs/{id}/enclosure": { "get": { "tags": [ "Dino Park API: dinosaurs" ], "summary": "Get a dinosaur's enclosure (nested resource)", "operationId": "dp-enclosure", "responses": { "200": { "description": "The enclosure", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown dinosaur", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Dinosaur id.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/dinopark/v1/enclosures": { "get": { "tags": [ "Dino Park API: enclosures" ], "summary": "List all enclosures with current occupancy", "operationId": "dp-enclosures", "responses": { "200": { "description": "Enclosure list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/dinopark/v1/incidents/breach": { "post": { "tags": [ "Dino Park API: incidents" ], "summary": "Simulate a containment breach (random dinosaur & severity)", "operationId": "dp-breach", "responses": { "201": { "description": "Incident logged", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/dinopark/v1/incidents": { "get": { "tags": [ "Dino Park API: incidents" ], "summary": "List incident history (empty until you POST a breach)", "operationId": "dp-incidents", "responses": { "200": { "description": "Incident list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/marvel/v1/heroes": { "get": { "tags": [ "Marvel API: heroes" ], "summary": "List heroes (paginated, filter by team)", "operationId": "al-list", "responses": { "200": { "description": "Paginated hero list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Page out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, default 1.", "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "team", "in": "query", "required": false, "description": "\"Avengers\" or \"Avengers Reserve\".", "schema": { "type": "string" } } ] }, "post": { "tags": [ "Marvel API: heroes" ], "summary": "Recruit a new hero", "operationId": "al-post", "responses": { "201": { "description": "Recruited", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing name or power", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat the same key on retry to get the original response instead of a duplicate.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "power": { "type": "string" }, "team": { "type": "string" } }, "required": [ "name", "power", "team" ], "additionalProperties": false }, "example": { "name": "Scarlet Witch", "power": "chaos magic", "team": "Avengers Reserve" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/marvel/v1/heroes/{id}": { "get": { "tags": [ "Marvel API: heroes" ], "summary": "Get one hero", "operationId": "al-get", "responses": { "200": { "description": "The hero", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Hero id. Try 999 for a 404.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] }, "put": { "tags": [ "Marvel API: heroes" ], "summary": "Update a hero", "operationId": "al-put", "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Empty body / invalid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Hero id to update.", "schema": { "type": "integer", "format": "int32" }, "example": 6 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency: pass a prior etag (e.g. v1). Mismatch → 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "team": { "type": "string" } }, "required": [ "team" ], "additionalProperties": false }, "example": { "team": "Avengers" } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Marvel API: heroes" ], "summary": "Retire a hero", "operationId": "al-del", "responses": { "204": { "description": "Retired" }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Hero id. Viewer token → 403.", "schema": { "type": "integer", "format": "int32" }, "example": 6 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency check. Mismatch → 412.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ] } }, "/marvel/v1/heroes/{id}/missions": { "get": { "tags": [ "Marvel API: heroes" ], "summary": "Get a hero's assigned missions (nested resource)", "operationId": "al-hero-missions", "responses": { "200": { "description": "Matching missions", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown hero", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Hero id.", "schema": { "type": "integer", "format": "int32" }, "example": 2 } ] } }, "/marvel/v1/villains": { "get": { "tags": [ "Marvel API: villains" ], "summary": "List villains, filter by threat level", "operationId": "al-villains", "responses": { "200": { "description": "Villain list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid threatLevel value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "threatLevel", "in": "query", "required": false, "description": "medium, high, or extreme.", "schema": { "type": "string" } } ] } }, "/marvel/v1/missions": { "post": { "tags": [ "Marvel API: missions" ], "summary": "Assign heroes to a new mission", "operationId": "al-mission-post", "responses": { "201": { "description": "Mission created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing title or unknown heroIds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "heroIds": { "type": "array", "items": { "type": "integer" } } }, "required": [ "title", "heroIds" ], "additionalProperties": false }, "example": { "title": "Stop Thanos from acquiring the last Infinity Stone", "heroIds": [ 1, 3 ] } } } }, "security": [ { "bearerAuth": [] } ] } }, "/marvel/v1/missions/{id}": { "get": { "tags": [ "Marvel API: missions" ], "summary": "Get one mission", "operationId": "al-mission-get", "responses": { "200": { "description": "The mission", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Mission id from POST /missions.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/marvel/v1/missions/{id}/complete": { "post": { "tags": [ "Marvel API: missions" ], "summary": "Mark a mission complete (409 if already complete)", "operationId": "al-mission-complete", "responses": { "200": { "description": "Marked complete", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Mission is already complete", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Mission id.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "security": [ { "bearerAuth": [] } ] } }, "/got/v1/houses": { "get": { "tags": [ "Game of Thrones API: houses" ], "summary": "List all houses", "operationId": "rl-houses", "responses": { "200": { "description": "All houses", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/got/v1/houses/{id}": { "get": { "tags": [ "Game of Thrones API: houses" ], "summary": "Get one house", "operationId": "rl-house", "responses": { "200": { "description": "The house", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "House id 1–4.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/got/v1/houses/{id}/nobles": { "get": { "tags": [ "Game of Thrones API: houses" ], "summary": "Get all nobles of a house (nested resource)", "operationId": "rl-house-nobles", "responses": { "200": { "description": "Nobles of the house", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown house", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "House id.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/got/v1/nobles/{id}": { "get": { "tags": [ "Game of Thrones API: nobles" ], "summary": "Get one noble", "operationId": "rl-noble", "responses": { "200": { "description": "The noble", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Noble id. Try 999 for a 404.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] }, "put": { "tags": [ "Game of Thrones API: nobles" ], "summary": "Update a noble", "operationId": "rl-put", "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Empty body / invalid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Noble id to update.", "schema": { "type": "integer", "format": "int32" }, "example": 6 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency: pass a prior etag (e.g. v1). Mismatch → 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" } }, "required": [ "title" ], "additionalProperties": false }, "example": { "title": "Lord Commander of the Night's Watch" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/got/v1/nobles": { "post": { "tags": [ "Game of Thrones API: nobles" ], "summary": "Add a noble to a house", "operationId": "rl-post", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing name or unknown houseId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat the same key on retry to get the original response instead of a duplicate.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "houseId": { "type": "integer" }, "title": { "type": "string" } }, "required": [ "name", "houseId", "title" ], "additionalProperties": false }, "example": { "name": "Sansa Stark", "houseId": 1, "title": "Queen in the North" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/got/v1/nobles/{id}/kill": { "post": { "tags": [ "Game of Thrones API: nobles" ], "summary": "Kill off a noble (409 if already dead)", "operationId": "rl-kill", "responses": { "200": { "description": "The noble has died", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Noble is already dead", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Noble id. Try 4 (already dead) for a 409. Viewer token → 403.", "schema": { "type": "integer", "format": "int32" }, "example": 5 } ], "security": [ { "bearerAuth": [] } ] } }, "/got/v1/dragons": { "get": { "tags": [ "Game of Thrones API: dragons" ], "summary": "List dragons, filter by size", "operationId": "rl-dragons", "responses": { "200": { "description": "Dragon list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid size value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "size", "in": "query", "required": false, "description": "young, large, or massive.", "schema": { "type": "string" } } ] } }, "/got/v1/dragons/random": { "get": { "tags": [ "Game of Thrones API: dragons" ], "summary": "A random dragon", "operationId": "rl-dragon-random", "responses": { "200": { "description": "One random dragon", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/got/v1/quotes/random": { "get": { "tags": [ "Game of Thrones API: quotes" ], "summary": "Get a random Westeros quote", "operationId": "rl-quote-random", "responses": { "200": { "description": "A random quote", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/got/v1/battles": { "post": { "tags": [ "Game of Thrones API: battles" ], "summary": "Simulate a battle between two houses", "operationId": "rl-battle-create", "responses": { "201": { "description": "Battle resolved", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Invalid houses", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A house cannot fight itself", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "attackerHouseId": { "type": "integer" }, "defenderHouseId": { "type": "integer" }, "location": { "type": "string" } }, "required": [ "attackerHouseId", "defenderHouseId", "location" ], "additionalProperties": false }, "example": { "attackerHouseId": 1, "defenderHouseId": 3, "location": "The Trident" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/got/v1/battles/{id}": { "get": { "tags": [ "Game of Thrones API: battles" ], "summary": "Get a battle result", "operationId": "rl-battle-get", "responses": { "200": { "description": "Battle", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown battle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/rickandmorty/v1/characters": { "get": { "tags": [ "Rick and Morty API: characters" ], "summary": "List characters (paginated, filter by status)", "operationId": "rm-list", "responses": { "200": { "description": "Paginated character list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Page out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "page", "in": "query", "required": false, "description": "Page number, default 1.", "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "status", "in": "query", "required": false, "description": "Alive, Dead, or Unknown.", "schema": { "type": "string" } } ] }, "post": { "tags": [ "Rick and Morty API: characters" ], "summary": "Add a character", "operationId": "rm-post", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing name or species", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat the same key on retry to get the original response instead of a duplicate.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "species": { "type": "string" }, "status": { "type": "string" }, "locationId": { "type": "integer" } }, "required": [ "name", "species", "status", "locationId" ], "additionalProperties": false }, "example": { "name": "Evil Morty", "species": "Human", "status": "Alive", "locationId": 2 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/rickandmorty/v1/characters/{id}": { "get": { "tags": [ "Rick and Morty API: characters" ], "summary": "Get one character", "operationId": "rm-get", "responses": { "200": { "description": "The character", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Character id. Try 999 for a 404.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] }, "put": { "tags": [ "Rick and Morty API: characters" ], "summary": "Update a character", "operationId": "rm-put", "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Empty body / invalid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Character id to update.", "schema": { "type": "integer", "format": "int32" }, "example": 8 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency: pass a prior etag (e.g. v1). Mismatch → 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ], "additionalProperties": false }, "example": { "status": "Dead" } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Rick and Morty API: characters" ], "summary": "Remove a character (portal them out of existence)", "operationId": "rm-del", "responses": { "204": { "description": "Removed" }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Character id. Viewer token → 403.", "schema": { "type": "integer", "format": "int32" }, "example": 8 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency check. Mismatch → 412.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ] } }, "/rickandmorty/v1/characters/{id}/location": { "get": { "tags": [ "Rick and Morty API: characters" ], "summary": "Get a character's current location (nested resource)", "operationId": "rm-location", "responses": { "200": { "description": "The location", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown character", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Character id.", "schema": { "type": "integer", "format": "int32" }, "example": 6 } ] } }, "/rickandmorty/v1/locations": { "get": { "tags": [ "Rick and Morty API: locations" ], "summary": "List locations, filter by dimension", "operationId": "rm-locations", "responses": { "200": { "description": "Location list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "dimension", "in": "query", "required": false, "description": "e.g. \"C-137\" or \"unknown\".", "schema": { "type": "string" } } ] } }, "/rickandmorty/v1/episodes": { "get": { "tags": [ "Rick and Morty API: episodes" ], "summary": "List episodes, filter by episode code", "operationId": "rm-episodes", "responses": { "200": { "description": "Episode list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "episodeCode", "in": "query", "required": false, "description": "e.g. S01E01.", "schema": { "type": "string" } } ] } }, "/rickandmorty/v1/episodes/random": { "get": { "tags": [ "Rick and Morty API: episodes" ], "summary": "A random episode", "operationId": "rm-episode-random", "responses": { "200": { "description": "One random episode", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/bank/v1/accounts": { "get": { "tags": [ "Bank API: accounts" ], "summary": "List accounts", "operationId": "bk-accounts", "responses": { "200": { "description": "Account list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] }, "post": { "tags": [ "Bank API: accounts" ], "summary": "Open a new account", "operationId": "bk-create", "responses": { "201": { "description": "Account opened", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing owner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Negative opening deposit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat the same key on retry to get the original response instead of a duplicate account.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "owner": { "type": "string" }, "currency": { "type": "string" }, "deposit": { "type": "integer" } }, "required": [ "owner", "currency", "deposit" ], "additionalProperties": false }, "example": { "owner": "Phoebe Buffay", "currency": "USD", "deposit": 100 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/bank/v1/accounts/{id}": { "get": { "tags": [ "Bank API: accounts" ], "summary": "Get one account", "operationId": "bk-account", "responses": { "200": { "description": "The account", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Account id 1–4 (or one you created).", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "security": [ { "bearerAuth": [] } ] } }, "/bank/v1/accounts/{id}/transactions": { "get": { "tags": [ "Bank API: transactions" ], "summary": "List transactions (cursor pagination)", "operationId": "bk-txs", "responses": { "200": { "description": "A page of transactions, newest first, plus \"nextCursor\" while more remain", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid cursor or limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Account id. Account 1 has enough history for several pages.", "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from a previous response’s \"nextCursor\". Omit for the first page. An unknown cursor → 400.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size 1–20, default 3.", "schema": { "type": "integer", "format": "int32" }, "example": 3 } ], "security": [ { "bearerAuth": [] } ] } }, "/bank/v1/transfers": { "post": { "tags": [ "Bank API: transfers" ], "summary": "Transfer money between accounts", "operationId": "bk-transfer", "responses": { "201": { "description": "Transfer executed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Same account on both sides", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Insufficient funds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "An account is frozen", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Amount is not a positive number", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Strongly recommended for money movement — repeat the same key on retry and the original transfer is replayed instead of double-charging.", "schema": { "type": "string" }, "example": "transfer-2026-001" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fromId": { "type": "integer" }, "toId": { "type": "integer" }, "amount": { "type": "number" }, "note": { "type": "string" } }, "required": [ "fromId", "toId", "amount", "note" ], "additionalProperties": false }, "example": { "fromId": 1, "toId": 2, "amount": 25.5, "note": "pizza night" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/bank/v1/transfers/{id}": { "get": { "tags": [ "Bank API: transfers" ], "summary": "Look up a transfer", "operationId": "bk-transfer-get", "responses": { "200": { "description": "The transfer", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown transfer id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Transfer id from POST /transfers (5001+).", "schema": { "type": "integer", "format": "int32" }, "example": 5001 } ], "security": [ { "bearerAuth": [] } ] } }, "/bank/v1/accounts/{id}/freeze": { "post": { "tags": [ "Bank API: accounts" ], "summary": "Freeze an account (admin only)", "operationId": "bk-freeze", "responses": { "200": { "description": "Account frozen", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already frozen", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Account to freeze. Account 4 is already frozen → 409.", "schema": { "type": "integer", "format": "int32" }, "example": 2 } ], "security": [ { "bearerAuth": [] } ] } }, "/bank/v1/exchange-rates": { "get": { "tags": [ "Bank API: accounts" ], "summary": "Exchange rates (cacheable, ETag + If-None-Match → 304)", "operationId": "bk-rates", "responses": { "200": { "description": "Rates, with Cache-Control and a stable ETag", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "304": { "description": "On the live API: repeat with If-None-Match: \"rates-v1\"", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/bank/v1/premium/statements": { "get": { "tags": [ "Bank API: premium" ], "summary": "Premium statements — always 402", "operationId": "bk-premium", "responses": { "402": { "description": "Always. Payment Required on demand, like the pizza oven’s 500.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/airline/v1/flights": { "get": { "tags": [ "Airline API: flights" ], "summary": "List flights, filter by route", "operationId": "al-flights", "responses": { "200": { "description": "Flight list with seat availability", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Origin code, e.g. NYC.", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "Destination code, e.g. LON.", "schema": { "type": "string" } } ] } }, "/airline/v1/flights/{id}": { "get": { "tags": [ "Airline API: flights" ], "summary": "Get one flight", "operationId": "al-flight", "responses": { "200": { "description": "The flight", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown flight", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Flight id, e.g. FN101. FN999 → 404.", "schema": { "type": "string" }, "example": "FN101" } ] } }, "/airline/v1/flights/{id}/seats": { "get": { "tags": [ "Airline API: flights" ], "summary": "Seat map with availability", "operationId": "al-seats", "responses": { "200": { "description": "Seat map", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown flight", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Flight id.", "schema": { "type": "string" }, "example": "FN101" } ] } }, "/airline/v1/flights/{id}/status": { "get": { "tags": [ "Airline API: flights" ], "summary": "Live-ish flight status (random delays)", "operationId": "al-status", "responses": { "200": { "description": "Status — sometimes delayed. Deterministic mode makes it repeatable.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown flight", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Flight id.", "schema": { "type": "string" }, "example": "FN202" } ] } }, "/airline/v1/bookings": { "post": { "tags": [ "Airline API: bookings" ], "summary": "Book a seat (409 on conflicts & overbooking)", "operationId": "al-book", "responses": { "201": { "description": "Booked", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing passenger or unknown seat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown flight", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Seat taken, flight cancelled, or flight full (overbooked)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat the same key on retry to replay the original booking instead of double-booking.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "flightId": { "type": "string" }, "passenger": { "type": "string" }, "seat": { "type": "string" } }, "required": [ "flightId", "passenger", "seat" ], "additionalProperties": false }, "example": { "flightId": "FN101", "passenger": "Phoebe Buffay", "seat": "1A" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/airline/v1/bookings/{id}": { "get": { "tags": [ "Airline API: bookings" ], "summary": "Get a booking (410 if cancelled)", "operationId": "al-booking", "responses": { "200": { "description": "The booking", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Never existed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Existed once, cancelled since — Gone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Booking id. 9001 exists; 8999 was cancelled → 410.", "schema": { "type": "integer", "format": "int32" }, "example": 9001 } ], "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Airline API: bookings" ], "summary": "Cancel a booking (admin only, then 410)", "operationId": "al-cancel", "responses": { "204": { "description": "Cancelled — subsequent GETs return 410" }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown booking", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cannot cancel after check-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Booking id to cancel.", "schema": { "type": "integer", "format": "int32" }, "example": 9001 } ], "security": [ { "bearerAuth": [] } ] } }, "/airline/v1/bookings/{id}/seat": { "put": { "tags": [ "Airline API: bookings" ], "summary": "Change seat (If-Match concurrency)", "operationId": "al-seat-change", "responses": { "200": { "description": "Seat changed, version bumped", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Unknown seat", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown booking", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Seat taken or booking checked-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Booking id.", "schema": { "type": "integer", "format": "int32" }, "example": 9001 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency: pass the booking’s current version (e.g. v1). A stale value → 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "seat": { "type": "string" } }, "required": [ "seat" ], "additionalProperties": false }, "example": { "seat": "1C" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/airline/v1/bookings/{id}/checkin": { "post": { "tags": [ "Airline API: bookings" ], "summary": "Check in (state machine)", "operationId": "al-checkin", "responses": { "200": { "description": "Checked in", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown booking", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already checked-in, or the flight is cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Booking id. 9002 is already checked-in → 409.", "schema": { "type": "integer", "format": "int32" }, "example": 9001 } ], "security": [ { "bearerAuth": [] } ] } }, "/protocol/v1/jobs": { "post": { "tags": [ "Protocol Lab API: jobs" ], "summary": "Start an async job — 202 Accepted", "operationId": "pl-job-create", "responses": { "202": { "description": "Accepted. Poll the Location header until status is \"done\".", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Unknown job type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "pages": { "type": "integer" } }, "required": [ "type", "pages" ], "additionalProperties": false }, "example": { "type": "report", "pages": 3 } } } } } }, "/protocol/v1/jobs/{id}": { "get": { "tags": [ "Protocol Lab API: jobs" ], "summary": "Poll a job — progresses on every poll", "operationId": "pl-job-get", "responses": { "200": { "description": "queued → running → done, advancing each time you poll", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Job id from POST /jobs (7001+).", "schema": { "type": "integer", "format": "int32" }, "example": 7001 } ] } }, "/protocol/v1/moved/old-dashboard": { "get": { "tags": [ "Protocol Lab API: redirects" ], "summary": "Permanently moved — 301", "operationId": "pl-redirect-301", "responses": { "301": { "description": "Always. Follow the Location header — real HTTP clients do it automatically.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/protocol/v1/moved/new-dashboard": { "get": { "tags": [ "Protocol Lab API: redirects" ], "summary": "Where the 301 leads", "operationId": "pl-redirect-new", "responses": { "200": { "description": "You made it", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/protocol/v1/hop": { "get": { "tags": [ "Protocol Lab API: redirects" ], "summary": "A 302 redirect chain — follow it down", "operationId": "pl-redirect-chain", "responses": { "200": { "description": "End of the chain (hops ≤ 1)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "302": { "description": "Redirects to /hop?hops=n-1", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "hops out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "hops", "in": "query", "required": false, "description": "Chain length 1–5, default 3. Each hop 302-redirects to hops-1 until 1.", "schema": { "type": "integer", "format": "int32" }, "example": 3 } ] } }, "/protocol/v1/maintenance": { "get": { "tags": [ "Protocol Lab API: outages" ], "summary": "Scheduled maintenance — 503 + Retry-After", "operationId": "pl-maintenance", "responses": { "503": { "description": "Always, with a Retry-After header. Good retry/backoff practice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } } }, "/protocol/v1/gateway-timeout": { "get": { "tags": [ "Protocol Lab API: outages" ], "summary": "Slow upstream — waits ~3s, then 504", "operationId": "pl-slow", "responses": { "504": { "description": "Always, after ~3 seconds. Pair it with a 2s client timeout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/protocol/v1/export/documents": { "get": { "tags": [ "Protocol Lab API: documents" ], "summary": "Content negotiation via Accept (406 on anything else)", "operationId": "pl-export", "responses": { "200": { "description": "Documents in the negotiated format (see \"contentType\" + \"payload\")", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "406": { "description": "Unsupported Accept value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Accept", "in": "header", "required": false, "description": "application/json (default), text/csv or application/xml. Anything else → 406.", "schema": { "type": "string" }, "example": "text/csv" } ] } }, "/protocol/v1/documents": { "get": { "tags": [ "Protocol Lab API: documents" ], "summary": "List documents (HATEOAS links)", "operationId": "pl-docs", "responses": { "200": { "description": "Documents, each carrying _links to discover related actions", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/protocol/v1/documents/{id}": { "get": { "tags": [ "Protocol Lab API: documents" ], "summary": "Get a document (410 after deletion)", "operationId": "pl-doc", "responses": { "200": { "description": "The document with _links and an ETag", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Never existed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Deleted — Gone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Document id 1–3.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] }, "patch": { "tags": [ "Protocol Lab API: documents" ], "summary": "RFC 6902 JSON Patch (op/path/value)", "operationId": "pl-patch", "responses": { "200": { "description": "Patched document, version bumped", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Body is not a patch array, or unsupported op/path", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A \"test\" operation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Document id.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string" }, "path": { "type": "string" }, "value": { "type": "string" } }, "required": [ "op", "path", "value" ], "additionalProperties": false } }, "example": [ { "op": "replace", "path": "/title", "value": "Sharper regression checklist" }, { "op": "add", "path": "/tags/-", "value": "patched" } ] } } } }, "delete": { "tags": [ "Protocol Lab API: documents" ], "summary": "Delete a document (admin only, then 410)", "operationId": "pl-doc-del", "responses": { "204": { "description": "Deleted — subsequent GETs return 410" }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Never existed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Already deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Document id to delete.", "schema": { "type": "integer", "format": "int32" }, "example": 2 } ], "security": [ { "bearerAuth": [] } ] } }, "/shop/v1/products": { "get": { "tags": [ "Shop API: products" ], "summary": "List products, filter by category", "operationId": "sh-products", "responses": { "200": { "description": "Product list with live stock counts", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "category", "in": "query", "required": false, "description": "office, fashion, food or decor.", "schema": { "type": "string" } } ] } }, "/shop/v1/products/{id}": { "get": { "tags": [ "Shop API: products" ], "summary": "Get one product", "operationId": "sh-product", "responses": { "200": { "description": "The product", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Product id 1–6. Product 3 is permanently sold out.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/shop/v1/coupons/{code}": { "get": { "tags": [ "Shop API: checkout" ], "summary": "Validate a coupon (410 when expired)", "operationId": "sh-coupon", "responses": { "200": { "description": "Coupon is valid", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Never existed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Existed once, expired since", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "code", "in": "path", "required": true, "description": "WELCOME10 works, EXPIRED50 is gone, anything else → 404.", "schema": { "type": "string" }, "example": "WELCOME10" } ] } }, "/shop/v1/carts": { "post": { "tags": [ "Shop API: carts" ], "summary": "Create an empty cart", "operationId": "sh-cart-create", "responses": { "201": { "description": "Cart created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer": { "type": "string" } }, "required": [ "customer" ], "additionalProperties": false }, "example": { "customer": "Rachel Green" } } } } } }, "/shop/v1/carts/{id}": { "get": { "tags": [ "Shop API: carts" ], "summary": "Get a cart with its running total", "operationId": "sh-cart", "responses": { "200": { "description": "The cart, items and total", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Cart id from POST /carts (301+).", "schema": { "type": "integer", "format": "int32" }, "example": 301 } ] } }, "/shop/v1/carts/{id}/items": { "post": { "tags": [ "Shop API: carts" ], "summary": "Add a product (409 when out of stock)", "operationId": "sh-cart-add", "responses": { "200": { "description": "Item added, cart returned", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Bad qty", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown cart or product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not enough stock (product 3 is always out)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Cart id.", "schema": { "type": "integer", "format": "int32" }, "example": 301 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "integer" }, "qty": { "type": "integer" } }, "required": [ "productId", "qty" ], "additionalProperties": false }, "example": { "productId": 2, "qty": 1 } } } } } }, "/shop/v1/carts/{id}/items/{productId}": { "delete": { "tags": [ "Shop API: carts" ], "summary": "Remove a product from the cart", "operationId": "sh-cart-remove", "responses": { "200": { "description": "Item removed, cart returned", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown cart, or product not in cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Cart id.", "schema": { "type": "integer", "format": "int32" }, "example": 301 }, { "name": "productId", "in": "path", "required": true, "description": "Product to remove.", "schema": { "type": "integer", "format": "int32" }, "example": 2 } ] } }, "/shop/v1/carts/{id}/checkout": { "post": { "tags": [ "Shop API: checkout" ], "summary": "Check out (idempotent, coupon-aware)", "operationId": "sh-checkout", "responses": { "201": { "description": "Order placed, stock decremented", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Empty cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Cart already checked out, or stock ran out since adding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Coupon invalid or expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Cart id.", "schema": { "type": "integer", "format": "int32" }, "example": 301 }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Repeat the same key on retry and the original order is replayed — no double charge.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "coupon": { "type": "string" } }, "required": [ "coupon" ], "additionalProperties": false }, "example": { "coupon": "WELCOME10" } } } } } }, "/shop/v1/orders/{id}": { "get": { "tags": [ "Shop API: checkout" ], "summary": "Get an order", "operationId": "sh-order", "responses": { "200": { "description": "The order", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Order id from checkout (8001+).", "schema": { "type": "integer", "format": "int32" }, "example": 8001 } ] } }, "/cargo/v1/shipments": { "get": { "tags": [ "Cargo Tracking API: tracking" ], "summary": "List shipments, filter by status", "operationId": "cg-list", "responses": { "200": { "description": "Shipment list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Unknown status value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "status", "in": "query", "required": false, "description": "label-created, picked-up, in-transit, out-for-delivery, delivered or returned-to-sender.", "schema": { "type": "string" } } ] }, "post": { "tags": [ "Cargo Tracking API: operations" ], "summary": "Create a shipping label (X-API-Key)", "operationId": "cg-create", "responses": { "201": { "description": "Label created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing sender/recipient/destination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or wrong X-API-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "X-API-Key", "in": "header", "required": true, "description": "API key auth — a different scheme than Bearer. The only valid key is cargo-key-123; anything else → 401.", "schema": { "type": "string" }, "example": "cargo-key-123" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sender": { "type": "string" }, "recipient": { "type": "string" }, "destination": { "type": "string" } }, "required": [ "sender", "recipient", "destination" ], "additionalProperties": false }, "example": { "sender": "Acme Corp", "recipient": "R. Runner", "destination": "Somewhere fast, Arizona" } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/cargo/v1/shipments/{id}": { "get": { "tags": [ "Cargo Tracking API: tracking" ], "summary": "Track one shipment", "operationId": "cg-get", "responses": { "200": { "description": "The shipment with its ETag (version)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown tracking id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tracking id, e.g. TRK123456. Unknown ids are presumed lost in the warehouse.", "schema": { "type": "string" }, "example": "TRK123456" } ] } }, "/cargo/v1/shipments/{id}/events": { "get": { "tags": [ "Cargo Tracking API: tracking" ], "summary": "Tracking history", "operationId": "cg-events", "responses": { "200": { "description": "Event list, oldest first", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown tracking id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tracking id.", "schema": { "type": "string" }, "example": "TRK777777" } ] } }, "/cargo/v1/shipments/{id}/eta": { "get": { "tags": [ "Cargo Tracking API: tracking" ], "summary": "Estimated delivery (deterministic-mode friendly)", "operationId": "cg-eta", "responses": { "200": { "description": "An ETA of questionable accuracy", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown tracking id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tracking id.", "schema": { "type": "string" }, "example": "TRK123456" } ] } }, "/cargo/v1/shipments/{id}/advance": { "post": { "tags": [ "Cargo Tracking API: operations" ], "summary": "Advance the state machine one step (X-API-Key)", "operationId": "cg-advance", "responses": { "200": { "description": "Moved to the next state", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or wrong X-API-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown tracking id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Shipment is in a terminal state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tracking id.", "schema": { "type": "string" }, "example": "TRK000001" }, { "name": "X-API-Key", "in": "header", "required": true, "description": "cargo-key-123", "schema": { "type": "string" }, "example": "cargo-key-123" } ], "security": [ { "apiKeyAuth": [] } ] } }, "/cargo/v1/shipments/{id}/attempt-delivery": { "post": { "tags": [ "Cargo Tracking API: operations" ], "summary": "Attempt delivery — may fail, 3 strikes returns it (X-API-Key)", "operationId": "cg-attempt", "responses": { "200": { "description": "Delivered, or recipient not home (attempt logged); third failed attempt returns to sender", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or wrong X-API-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown tracking id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not out-for-delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tracking id — must be out-for-delivery.", "schema": { "type": "string" }, "example": "TRK123456" }, { "name": "X-API-Key", "in": "header", "required": true, "description": "cargo-key-123", "schema": { "type": "string" }, "example": "cargo-key-123" } ], "security": [ { "apiKeyAuth": [] } ] } }, "/cargo/v1/shipments/{id}/address": { "put": { "tags": [ "Cargo Tracking API: operations" ], "summary": "Redirect a parcel (X-API-Key + If-Match)", "operationId": "cg-address", "responses": { "200": { "description": "Address updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Missing destination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or wrong X-API-Key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown tracking id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already delivered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Tracking id.", "schema": { "type": "string" }, "example": "TRK123456" }, { "name": "X-API-Key", "in": "header", "required": true, "description": "cargo-key-123", "schema": { "type": "string" }, "example": "cargo-key-123" }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency — pass the current version (e.g. v1). Stale → 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "destination": { "type": "string" } }, "required": [ "destination" ], "additionalProperties": false }, "example": { "destination": "Top of the mesa, Arizona" } } } }, "security": [ { "apiKeyAuth": [] } ] } }, "/cargo/v1/rates": { "get": { "tags": [ "Cargo Tracking API: tracking" ], "summary": "Shipping quote by weight", "operationId": "cg-rates", "responses": { "200": { "description": "Quote for standard and express", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid weight", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "weight", "in": "query", "required": true, "description": "Parcel weight in kg (0.1–1000). Non-numeric or out of range → 400.", "schema": { "type": "string" }, "example": "2.5" } ] } }, "/space/v1/launches": { "get": { "tags": [ "Space Agency API: launches" ], "summary": "List launches, filter by status", "operationId": "sp-launches", "responses": { "200": { "description": "Launch list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Unknown status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "status", "in": "query", "required": false, "description": "scheduled, launched or scrubbed.", "schema": { "type": "string" } } ] }, "post": { "tags": [ "Space Agency API: launches" ], "summary": "Schedule a launch", "operationId": "sp-schedule", "responses": { "201": { "description": "Launch scheduled", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing mission or vehicle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mission": { "type": "string" }, "vehicle": { "type": "string" }, "window": { "type": "string" } }, "required": [ "mission", "vehicle", "window" ], "additionalProperties": false }, "example": { "mission": "Lunar Coffee Delivery", "vehicle": "Kestrel IX", "window": "2026-09-15T06:00:00Z" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/space/v1/launches/{id}": { "get": { "tags": [ "Space Agency API: launches" ], "summary": "Get one launch", "operationId": "sp-launch", "responses": { "200": { "description": "The launch", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Launch id 1–3.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/space/v1/launches/{id}/scrub": { "post": { "tags": [ "Space Agency API: launches" ], "summary": "Scrub a scheduled launch", "operationId": "sp-scrub", "responses": { "200": { "description": "Scrubbed, count incremented", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already launched or already scrubbed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Launch id — must be scheduled.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "security": [ { "bearerAuth": [] } ] } }, "/space/v1/launches/{id}/launch": { "post": { "tags": [ "Space Agency API: launches" ], "summary": "Light the candle — slow & occasionally aborts (admin only)", "operationId": "sp-ignite", "responses": { "200": { "description": "Liftoff (after a ~3s hold-down)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token cannot push the big red button", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not scheduled, or an auto-abort at T-0 (~25% chance)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Launch id — must be scheduled (re-schedule a scrubbed one by scrubbing… no wait, just use launch 1).", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "security": [ { "bearerAuth": [] } ] } }, "/space/v1/launches/{id}/countdown": { "get": { "tags": [ "Space Agency API: launches" ], "summary": "T-minus for a scheduled launch", "operationId": "sp-countdown", "responses": { "200": { "description": "T-minus seconds (random-ish; deterministic mode pins it)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Launch is not scheduled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Launch id.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/space/v1/astronauts": { "get": { "tags": [ "Space Agency API: crew" ], "summary": "List astronauts", "operationId": "sp-astronauts", "responses": { "200": { "description": "Astronaut roster", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "role", "in": "query", "required": false, "description": "Filter by role, e.g. pilot.", "schema": { "type": "string" } } ] } }, "/space/v1/astronauts/{id}": { "get": { "tags": [ "Space Agency API: crew" ], "summary": "Get one astronaut", "operationId": "sp-astronaut", "responses": { "200": { "description": "The astronaut", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Astronaut id 1–5.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/space/v1/probes/{id}/ping": { "get": { "tags": [ "Space Agency API: probes" ], "summary": "Ping a deep-space probe — takes ~3s", "operationId": "sp-ping", "responses": { "200": { "description": "Pong, eventually. Great for testing client timeouts.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown probe", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Probe id 1–3. Light is slow; this endpoint is slower.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/starfleet/v1/ships": { "get": { "tags": [ "Starfleet API: ships" ], "summary": "List ships, filter by class or status", "operationId": "sf-ships", "responses": { "200": { "description": "Fleet list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "class", "in": "query", "required": false, "description": "Constitution, Miranda, Excelsior or Defiant.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "active or in-refit.", "schema": { "type": "string" } } ] }, "post": { "tags": [ "Starfleet API: ships" ], "summary": "Commission a new ship", "operationId": "sf-commission", "responses": { "201": { "description": "Ship commissioned", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing name or unknown class", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A ship with that name already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "class": { "type": "string" } }, "required": [ "name", "class" ], "additionalProperties": false }, "example": { "name": "USS Unsinkable II", "class": "Miranda" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/starfleet/v1/ships/{id}": { "get": { "tags": [ "Starfleet API: ships" ], "summary": "Get one ship", "operationId": "sf-ship", "responses": { "200": { "description": "The ship", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ship id 1–4. Ship 4 has a breached warp core.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/starfleet/v1/ships/{id}/warp": { "put": { "tags": [ "Starfleet API: ships" ], "summary": "Set warp factor (physics says no above 9.9)", "operationId": "sf-warp", "responses": { "200": { "description": "Warp factor set", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Factor not between 0 and 9.9", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown ship", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Warp core breached or ship in refit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Ship id. Ship 4’s core is breached → 409.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "factor": { "type": "integer" } }, "required": [ "factor" ], "additionalProperties": false }, "example": { "factor": 5 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/starfleet/v1/crew": { "get": { "tags": [ "Starfleet API: crew" ], "summary": "List crew, filter by species or ship", "operationId": "sf-crew", "responses": { "200": { "description": "Crew roster", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "species", "in": "query", "required": false, "description": "human, vulcan, klingon, bolian…", "schema": { "type": "string" } }, { "name": "shipId", "in": "query", "required": false, "description": "Filter by assigned ship.", "schema": { "type": "integer", "format": "int32" } } ] }, "post": { "tags": [ "Starfleet API: crew" ], "summary": "Enlist a crew member", "operationId": "sf-enlist", "responses": { "201": { "description": "Welcome aboard", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Missing name/rank", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown shipId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "rank": { "type": "string" }, "species": { "type": "string" }, "shipId": { "type": "integer" } }, "required": [ "name", "rank", "species", "shipId" ], "additionalProperties": false }, "example": { "name": "Ens. Nova Reyes", "rank": "ensign", "species": "human", "shipId": 1 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/starfleet/v1/crew/{id}": { "get": { "tags": [ "Starfleet API: crew" ], "summary": "Get one crew member", "operationId": "sf-crewman", "responses": { "200": { "description": "The crew member", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Crew id 1–6.", "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] }, "delete": { "tags": [ "Starfleet API: crew" ], "summary": "Discharge a crew member (admin only)", "operationId": "sf-discharge", "responses": { "204": { "description": "Beamed home safely" }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Crew id. Statistically risky for ensigns in red.", "schema": { "type": "integer", "format": "int32" }, "example": 6 } ], "security": [ { "bearerAuth": [] } ] } }, "/starfleet/v1/tribbles": { "get": { "tags": [ "Starfleet API: tribbles" ], "summary": "Count tribbles — doubles on EVERY read", "operationId": "sf-tribbles", "responses": { "200": { "description": "The count, which just doubled. A GET with side effects — find it with your contract tests.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/starfleet/v1/tribbles/purge": { "post": { "tags": [ "Starfleet API: tribbles" ], "summary": "Beam the tribbles away (admin only)", "operationId": "sf-purge", "responses": { "200": { "description": "Population reset to 1", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/worldcup/v1/teams": { "get": { "tags": [ "World Cup 2026 API: teams" ], "summary": "List qualified teams (filter by group, confederation or hosts)", "operationId": "wc-teams", "responses": { "200": { "description": "Team list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Unknown query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "group", "in": "query", "required": false, "schema": { "type": "string" }, "example": "A" }, { "name": "confederation", "in": "query", "required": false, "schema": { "type": "string" }, "example": "UEFA" }, { "name": "host", "in": "query", "required": false, "schema": { "type": "string" }, "example": "false" } ] } }, "/worldcup/v1/teams/{id}": { "get": { "tags": [ "World Cup 2026 API: teams" ], "summary": "Get one national team", "operationId": "wc-team", "responses": { "200": { "description": "Team", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Team not qualified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 6 } ] } }, "/worldcup/v1/groups/{letter}/standings": { "get": { "tags": [ "World Cup 2026 API: teams" ], "summary": "Live group standings computed from finished matches", "operationId": "wc-standings", "responses": { "200": { "description": "Standings", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid group letter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Group not seeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "letter", "in": "path", "required": true, "schema": { "type": "string" }, "example": "B" } ] } }, "/worldcup/v1/venues": { "get": { "tags": [ "World Cup 2026 API: venues" ], "summary": "List 2026 host stadiums, filter by country", "operationId": "wc-venues", "responses": { "200": { "description": "Venues", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Canada" } ] } }, "/worldcup/v1/venues/{id}": { "get": { "tags": [ "World Cup 2026 API: venues" ], "summary": "Get a stadium with its scheduled matches", "operationId": "wc-venue", "responses": { "200": { "description": "Venue", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown venue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 2 } ] } }, "/worldcup/v1/matches": { "get": { "tags": [ "World Cup 2026 API: matches" ], "summary": "List fixtures (filter by stage, status, group or team)", "operationId": "wc-matches", "responses": { "200": { "description": "Fixtures", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Unknown query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "stage", "in": "query", "required": false, "schema": { "type": "string" }, "example": "group" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "example": "scheduled" }, { "name": "group", "in": "query", "required": false, "schema": { "type": "string" }, "example": "A" }, { "name": "teamId", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/worldcup/v1/matches/{id}": { "get": { "tags": [ "World Cup 2026 API: matches" ], "summary": "Get one fixture with team and venue details", "operationId": "wc-match", "responses": { "200": { "description": "Fixture", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 2 } ] } }, "/worldcup/v1/matches/{id}/simulate": { "post": { "tags": [ "World Cup 2026 API: matches" ], "summary": "Kick off and simulate a match — updates score, goal events and standings (admin only)", "operationId": "wc-simulate", "responses": { "200": { "description": "Full-time result", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Match already played", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Knockout pairing not decided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 2 }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "example": "wc26-group-b-opener" } ], "security": [ { "bearerAuth": [] } ] } }, "/worldcup/v1/matches/{id}/events": { "get": { "tags": [ "World Cup 2026 API: matches" ], "summary": "Goal timeline of a played match (409 before kickoff)", "operationId": "wc-match-events", "responses": { "200": { "description": "Events", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Match not played yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 2 } ] } }, "/worldcup/v1/matches/{id}/var-review": { "get": { "tags": [ "World Cup 2026 API: matches" ], "summary": "Request a VAR review — the check takes ~3 seconds", "operationId": "wc-var", "responses": { "200": { "description": "VAR decision", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/worldcup/v1/players/top-scorers": { "get": { "tags": [ "World Cup 2026 API: players" ], "summary": "Golden Boot race — top scorers so far", "operationId": "wc-scorers", "responses": { "200": { "description": "Top scorers", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "Invalid limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 5 } ] } }, "/worldcup/v1/tickets": { "post": { "tags": [ "World Cup 2026 API: tickets" ], "summary": "Buy match tickets — limited seats, 409 when sold out", "operationId": "wc-ticket-create", "responses": { "201": { "description": "Tickets confirmed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Unknown match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not enough seats left", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid category or quantity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "example": "wc26-order-1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "matchId": { "type": "integer" }, "category": { "type": "string" }, "quantity": { "type": "integer" } }, "required": [ "matchId", "category", "quantity" ], "additionalProperties": false }, "example": { "matchId": 4, "category": "category-2", "quantity": 2 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/worldcup/v1/tickets/{id}": { "get": { "tags": [ "World Cup 2026 API: tickets" ], "summary": "Get a ticket order (410 after cancellation)", "operationId": "wc-ticket", "responses": { "200": { "description": "Ticket order", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Order cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "World Cup 2026 API: tickets" ], "summary": "Cancel a ticket order and release the seats (admin only)", "operationId": "wc-ticket-cancel", "responses": { "204": { "description": "Cancelled" }, "404": { "description": "Unknown order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Already cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "security": [ { "bearerAuth": [] } ] } }, "/worldcup/v1/predictions": { "post": { "tags": [ "World Cup 2026 API: fanzone" ], "summary": "Predict the 2026 world champion", "operationId": "wc-predict", "responses": { "201": { "description": "Prediction saved", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "422": { "description": "Unknown team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nickname": { "type": "string" }, "championTeamId": { "type": "integer" }, "finalScore": { "type": "string" } }, "required": [ "nickname", "championTeamId", "finalScore" ], "additionalProperties": false }, "example": { "nickname": "qa_gu", "championTeamId": 6, "finalScore": "2-1" } } } } } }, "/worldcup/v1/predictions/leaderboard": { "get": { "tags": [ "World Cup 2026 API: fanzone" ], "summary": "Most-predicted champions", "operationId": "wc-leaderboard", "responses": { "200": { "description": "Leaderboard", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/worldcup/v1/fanzone/mascots": { "get": { "tags": [ "World Cup 2026 API: fanzone" ], "summary": "Meet Maple, Zayu and Clutch — the official 2026 mascots", "operationId": "wc-mascots", "responses": { "200": { "description": "Mascots", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/fiba/v1/teams": { "get": { "tags": [ "FIBA World Cup API: teams" ], "summary": "List qualified teams (filter by group, FIBA zone or hosts)", "operationId": "fiba-teams", "responses": { "200": { "description": "Team list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Unknown query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "group", "in": "query", "required": false, "schema": { "type": "string" }, "example": "A" }, { "name": "zone", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Europe" }, { "name": "host", "in": "query", "required": false, "schema": { "type": "string" }, "example": "false" } ] } }, "/fiba/v1/teams/{id}": { "get": { "tags": [ "FIBA World Cup API: teams" ], "summary": "Get one national team — carries the ETag its staff update needs", "operationId": "fiba-team", "responses": { "200": { "description": "Team, with an ETag", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Team not qualified", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 32 } ] } }, "/fiba/v1/teams/{id}/staff": { "put": { "tags": [ "FIBA World Cup API: teams" ], "summary": "Name the head coach and captain — optimistic concurrency via If-Match", "operationId": "fiba-team-staff", "responses": { "200": { "description": "Staff updated, etag bumped", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "412": { "description": "If-Match does not match current version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Missing coach, or a captain from another squad", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 32 }, { "name": "If-Match", "in": "header", "required": false, "description": "Optimistic concurrency: pass the etag from GET /teams/{id} (e.g. v1). Mismatch → 412.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "headCoach": { "type": "string" }, "captainPlayerId": { "type": "integer" } }, "required": [ "headCoach", "captainPlayerId" ], "additionalProperties": false }, "example": { "headCoach": "Ergin Ataman", "captainPlayerId": 63 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/fiba/v1/groups/{letter}/standings": { "get": { "tags": [ "FIBA World Cup API: teams" ], "summary": "Group table computed from finished games — cacheable (ETag / If-None-Match / 304)", "operationId": "fiba-standings", "responses": { "200": { "description": "Standings, with ETag + Cache-Control", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "304": { "description": "Not Modified — If-None-Match matched", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid group letter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Group not seeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "letter", "in": "path", "required": true, "schema": { "type": "string" }, "example": "A" }, { "name": "If-None-Match", "in": "header", "required": false, "description": "Pass a prior etag; if no game has finished since, get 304 with no body.", "schema": { "type": "string" } } ] } }, "/fiba/v1/arenas": { "get": { "tags": [ "FIBA World Cup API: arenas" ], "summary": "List the Qatar host arenas, filter by city", "operationId": "fiba-arenas", "responses": { "200": { "description": "Arenas", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "city", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Doha" } ] } }, "/fiba/v1/arenas/{id}": { "get": { "tags": [ "FIBA World Cup API: arenas" ], "summary": "Get one arena with the games it hosts", "operationId": "fiba-arena", "responses": { "200": { "description": "Arena", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown arena", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/fiba/v1/games": { "get": { "tags": [ "FIBA World Cup API: games" ], "summary": "List games (filter by stage, status, group or team)", "operationId": "fiba-games", "responses": { "200": { "description": "Games", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "stage", "in": "query", "required": false, "schema": { "type": "string" }, "example": "group" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "example": "scheduled" }, { "name": "group", "in": "query", "required": false, "schema": { "type": "string" }, "example": "A" }, { "name": "teamId", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" } } ] } }, "/fiba/v1/games/{id}": { "get": { "tags": [ "FIBA World Cup API: games" ], "summary": "Get one game with team and arena names resolved", "operationId": "fiba-game", "responses": { "200": { "description": "Game", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown game", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/fiba/v1/games/{id}/simulate": { "post": { "tags": [ "FIBA World Cup API: games" ], "summary": "Tip off — four quarters plus overtime until somebody wins (admin only)", "operationId": "fiba-simulate", "responses": { "200": { "description": "Final score, quarter by quarter", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Viewer token not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown game", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already played", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Knockout pairing not decided yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "example": "fiba-game-1" } ], "security": [ { "bearerAuth": [] } ] } }, "/fiba/v1/games/{id}/boxscore": { "get": { "tags": [ "FIBA World Cup API: games" ], "summary": "Per-player box score, derived from the play-by-play", "operationId": "fiba-boxscore", "responses": { "200": { "description": "Box score", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown game", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Game not played yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/fiba/v1/games/{id}/play-by-play": { "get": { "tags": [ "FIBA World Cup API: games" ], "summary": "Cursor-paged play-by-play — follow nextCursor to the final buzzer", "operationId": "fiba-plays", "responses": { "200": { "description": "A page of plays and the next cursor", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Cursor or limit out of range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown game", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Game not played yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 0 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 10 } ] } }, "/fiba/v1/games/{id}/challenge": { "post": { "tags": [ "FIBA World Cup API: games" ], "summary": "Coach's challenge — a slow (~3s) replay review, one per team", "operationId": "fiba-challenge", "responses": { "200": { "description": "Review decision", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown game", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Game not played, or that bench already challenged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "team must be home or away", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "team": { "type": "string" }, "play": { "type": "string" } }, "required": [ "team", "play" ], "additionalProperties": false }, "example": { "team": "home", "play": "Ball out of bounds at 2:14 of Q4" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/fiba/v1/games/{id}/highlights": { "post": { "tags": [ "FIBA World Cup API: games" ], "summary": "Queue a highlight reel — 202 Accepted, then poll the job", "operationId": "fiba-highlights", "responses": { "202": { "description": "Render job accepted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown game", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Game not played yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "seconds must be 60, 120 or 300", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "seconds": { "type": "integer" } }, "required": [ "seconds" ], "additionalProperties": false }, "example": { "seconds": 120 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/fiba/v1/highlights/{id}": { "get": { "tags": [ "FIBA World Cup API: games" ], "summary": "Poll a highlight job until it is ready", "operationId": "fiba-highlight-job", "responses": { "200": { "description": "Job state", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/fiba/v1/players": { "get": { "tags": [ "FIBA World Cup API: players" ], "summary": "List players (filter by team or position)", "operationId": "fiba-players", "responses": { "200": { "description": "Players", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "teamId", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "position", "in": "query", "required": false, "schema": { "type": "string" }, "example": "C" } ] } }, "/fiba/v1/players/{id}": { "get": { "tags": [ "FIBA World Cup API: players" ], "summary": "Get one player with their running tournament totals", "operationId": "fiba-player", "responses": { "200": { "description": "Player", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown player", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 63 } ] } }, "/fiba/v1/players/leaders": { "get": { "tags": [ "FIBA World Cup API: players" ], "summary": "Tournament leaders for points, rebounds or assists", "operationId": "fiba-leaders", "responses": { "200": { "description": "Leaderboard", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "Unknown stat, or limit outside 1–20", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "stat", "in": "query", "required": false, "schema": { "type": "string" }, "example": "points" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 5 } ] } }, "/fiba/v1/players/{id}/advanced": { "get": { "tags": [ "FIBA World Cup API: players" ], "summary": "Tracking data — always 402, it is on the paid analytics tier", "operationId": "fiba-advanced", "responses": { "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown player", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 63 } ] } }, "/fiba/v1/fanzone/mvp": { "get": { "tags": [ "FIBA World Cup API: players" ], "summary": "The MVP race, ranked by a simplified efficiency index", "operationId": "fiba-mvp", "responses": { "200": { "description": "Top five by efficiency", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/fiba/v1/tickets": { "post": { "tags": [ "FIBA World Cup API: tickets" ], "summary": "Buy tickets — seats are limited, so 409 when the game sells out", "operationId": "fiba-ticket-create", "responses": { "201": { "description": "Order confirmed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Unknown gameId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not enough seats left", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid tier or quantity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "example": "fiba-order-1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "gameId": { "type": "integer" }, "tier": { "type": "string" }, "quantity": { "type": "integer" } }, "required": [ "gameId", "tier", "quantity" ], "additionalProperties": false }, "example": { "gameId": 1, "tier": "lower", "quantity": 2 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/fiba/v1/tickets/{id}": { "get": { "tags": [ "FIBA World Cup API: tickets" ], "summary": "Get a ticket order — 410 once it has been cancelled", "operationId": "fiba-ticket", "responses": { "200": { "description": "Order", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Order was cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] }, "delete": { "tags": [ "FIBA World Cup API: tickets" ], "summary": "Cancel an order and release the seats", "operationId": "fiba-ticket-cancel", "responses": { "204": { "description": "Cancelled" }, "401": { "description": "Missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Already cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "security": [ { "bearerAuth": [] } ] } }, "/gta/v1/characters": { "get": { "tags": [ "GTA API: characters" ], "summary": "List characters (filter by city or affiliation)", "operationId": "gta-characters", "responses": { "200": { "description": "Character list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "city", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Vice City" }, { "name": "affiliation", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Vercetti Gang" } ] } }, "/gta/v1/characters/{id}": { "get": { "tags": [ "GTA API: characters" ], "summary": "Get one character", "operationId": "gta-character", "responses": { "200": { "description": "Character", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown character", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 4 } ] } }, "/gta/v1/vehicles": { "get": { "tags": [ "GTA API: vehicles" ], "summary": "List vehicles (filter by class)", "operationId": "gta-vehicles", "responses": { "200": { "description": "Vehicles", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "class", "in": "query", "required": false, "schema": { "type": "string" }, "example": "sports" } ] } }, "/gta/v1/vehicles/{id}": { "get": { "tags": [ "GTA API: vehicles" ], "summary": "Get one vehicle", "operationId": "gta-vehicle", "responses": { "200": { "description": "Vehicle", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown vehicle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 3 } ] } }, "/gta/v1/vehicles/{id}/respray": { "post": { "tags": [ "GTA API: vehicles" ], "summary": "Respray a vehicle at Pay-n-Spray — spends cash (402 when broke)", "operationId": "gta-respray", "responses": { "200": { "description": "Respray done", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "402": { "description": "Not enough cash", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown vehicle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Missing color", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "color": { "type": "string" } }, "required": [ "color" ], "additionalProperties": false }, "example": { "color": "matte black" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/gta/v1/weapons": { "get": { "tags": [ "GTA API: weapons" ], "summary": "Browse the ammu-nation catologue (filter by category)", "operationId": "gta-weapons", "responses": { "200": { "description": "Weapons", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "example": "automatic" } ] } }, "/gta/v1/weapons/{id}/buy": { "post": { "tags": [ "GTA API: weapons" ], "summary": "Buy a weapon — spends cash (402 when broke, 409 if already owned)", "operationId": "gta-weapon-buy", "responses": { "200": { "description": "Weapon purchased", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "402": { "description": "Not enough cash", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown weapon", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already owned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 3 } ], "security": [ { "bearerAuth": [] } ] } }, "/gta/v1/missions": { "get": { "tags": [ "GTA API: missions" ], "summary": "List missions (filter by status or city)", "operationId": "gta-missions", "responses": { "200": { "description": "Missions", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "example": "available" }, { "name": "city", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Los Santos" } ] } }, "/gta/v1/missions/{id}": { "get": { "tags": [ "GTA API: missions" ], "summary": "Get one mission with its prereq", "operationId": "gta-mission", "responses": { "200": { "description": "Mission", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown mission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 2 } ] } }, "/gta/v1/missions/{id}/start": { "post": { "tags": [ "GTA API: missions" ], "summary": "Start a mission (409 if one is active, 422 if prereq not completed)", "operationId": "gta-mission-start", "responses": { "200": { "description": "Mission started", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown mission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A mission is already active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Prerequisite not completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "security": [ { "bearerAuth": [] } ] } }, "/gta/v1/missions/{id}/complete": { "post": { "tags": [ "GTA API: missions" ], "summary": "Complete the active mission — pays out the reward", "operationId": "gta-mission-complete", "responses": { "200": { "description": "Mission completed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown mission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not the active mission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "example": "gta-mission-1" } ], "security": [ { "bearerAuth": [] } ] } }, "/gta/v1/heists": { "post": { "tags": [ "GTA API: missions" ], "summary": "Plan a heist — choose an approach (admin only)", "operationId": "gta-heist-plan", "responses": { "201": { "description": "Heist planned", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "422": { "description": "Invalid approach or crew size", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "example": "gta-heist-1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "approach": { "type": "string" }, "crewSize": { "type": "integer" } }, "required": [ "name", "approach", "crewSize" ], "additionalProperties": false }, "example": { "name": "The Jewelry Store Job", "approach": "stealth", "crewSize": 3 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/gta/v1/heists/{id}": { "get": { "tags": [ "GTA API: missions" ], "summary": "Get a planned heist", "operationId": "gta-heist", "responses": { "200": { "description": "Heist", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown heist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/gta/v1/wanted": { "get": { "tags": [ "GTA API: wanted" ], "summary": "Current wanted level (0–5 stars)", "operationId": "gta-wanted", "responses": { "200": { "description": "Wanted level", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "delete": { "tags": [ "GTA API: wanted" ], "summary": "Bribe the LSPD to clear wanted level — costs $1000/star (402 when broke)", "operationId": "gta-wanted-clear", "responses": { "200": { "description": "Wanted cleared", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "402": { "description": "Not enough cash", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already clean", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/gta/v1/wanted/increase": { "post": { "tags": [ "GTA API: wanted" ], "summary": "Commit a crime — inflates wanted level after a ~2s police chase", "operationId": "gta-wanted-increase", "responses": { "200": { "description": "Wanted increased", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "Already at max stars", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/gta/v1/radio": { "get": { "tags": [ "GTA API: radio" ], "summary": "List in-game radio stations", "operationId": "gta-radio", "responses": { "200": { "description": "Stations", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/dragonball/v1/fighters": { "get": { "tags": [ "Dragon Ball API: fighters" ], "summary": "List fighters by race or minimum power", "operationId": "db-fighters", "responses": { "200": { "description": "Fighter list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "race", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Saiyan" }, { "name": "minPower", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 8000 } ] } }, "/dragonball/v1/fighters/{id}": { "get": { "tags": [ "Dragon Ball API: fighters" ], "summary": "Get one fighter", "operationId": "db-fighter", "responses": { "200": { "description": "Fighter", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown fighter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/dragonball/v1/fighters/{id}/transformations": { "get": { "tags": [ "Dragon Ball API: fighters" ], "summary": "List a fighter’s transformations", "operationId": "db-transformations", "responses": { "200": { "description": "Transformations", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown fighter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/dragonball/v1/fighters/{id}/power-up": { "post": { "tags": [ "Dragon Ball API: fighters" ], "summary": "Increase a fighter’s power level", "operationId": "db-power-up", "responses": { "200": { "description": "Power increased", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "Invalid amount", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 3 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "integer" } }, "required": [ "amount" ], "additionalProperties": false }, "example": { "amount": 500 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/dragonball/v1/tournaments": { "post": { "tags": [ "Dragon Ball API: tournaments" ], "summary": "Resolve a tournament match", "operationId": "db-tournament", "responses": { "201": { "description": "Match resolved", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Invalid fighters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Same fighter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "example": "db-match-1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fighterAId": { "type": "integer" }, "fighterBId": { "type": "integer" }, "arena": { "type": "string" } }, "required": [ "fighterAId", "fighterBId", "arena" ], "additionalProperties": false }, "example": { "fighterAId": 1, "fighterBId": 4, "arena": "World Martial Arts Tournament" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/dragonball/v1/tournaments/{id}": { "get": { "tags": [ "Dragon Ball API: tournaments" ], "summary": "Get a tournament match", "operationId": "db-tournament-get", "responses": { "200": { "description": "Match", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/formula1/v1/drivers": { "get": { "tags": [ "Formula 1 API: grid" ], "summary": "List drivers by team", "operationId": "f1-drivers", "responses": { "200": { "description": "Drivers", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "teamId", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 2 } ] } }, "/formula1/v1/constructors": { "get": { "tags": [ "Formula 1 API: grid" ], "summary": "List constructors with drivers", "operationId": "f1-teams", "responses": { "200": { "description": "Constructors", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/formula1/v1/races": { "get": { "tags": [ "Formula 1 API: races" ], "summary": "List races by status", "operationId": "f1-races", "responses": { "200": { "description": "Races", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "example": "scheduled" } ] } }, "/formula1/v1/races/{id}/start": { "post": { "tags": [ "Formula 1 API: races" ], "summary": "Run and finish a race", "operationId": "f1-race-start", "responses": { "200": { "description": "Race finished", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown race", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already finished", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "example": "istanbul-2026" } ], "security": [ { "bearerAuth": [] } ] } }, "/formula1/v1/races/{id}/results": { "get": { "tags": [ "Formula 1 API: races" ], "summary": "Get classified race results", "operationId": "f1-results", "responses": { "200": { "description": "Results", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "Race not finished", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/formula1/v1/races/{id}/telemetry": { "get": { "tags": [ "Formula 1 API: telemetry" ], "summary": "Read lap telemetry after a race", "operationId": "f1-telemetry", "responses": { "200": { "description": "Telemetry", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "afterLap", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 5 } ] } }, "/formula1/v1/races/{id}/pit-stops": { "post": { "tags": [ "Formula 1 API: telemetry" ], "summary": "Record a pit stop", "operationId": "f1-pitstop", "responses": { "201": { "description": "Pit stop recorded", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "422": { "description": "Invalid pit stop", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "driverId": { "type": "integer" }, "lap": { "type": "integer" }, "durationMs": { "type": "integer" }, "compound": { "type": "string" } }, "required": [ "driverId", "lap", "durationMs", "compound" ], "additionalProperties": false }, "example": { "driverId": 2, "lap": 21, "durationMs": 2430, "compound": "soft" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/voxel/v1/worlds": { "get": { "tags": [ "Voxel Worlds API: worlds" ], "summary": "List worlds", "operationId": "vx-worlds", "responses": { "200": { "description": "World list", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "post": { "tags": [ "Voxel Worlds API: worlds" ], "summary": "Generate a world from a seed", "operationId": "vx-world-create", "responses": { "201": { "description": "World generated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Invalid world", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Token required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "example": "world-42" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "seed": { "type": "integer" }, "biome": { "type": "string" }, "difficulty": { "type": "string" } }, "required": [ "name", "seed", "biome", "difficulty" ], "additionalProperties": false }, "example": { "name": "Redstone Ridge", "seed": 8675309, "biome": "mountains", "difficulty": "hard" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/voxel/v1/worlds/{id}": { "get": { "tags": [ "Voxel Worlds API: worlds" ], "summary": "Get a world", "operationId": "vx-world", "responses": { "200": { "description": "World", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Unknown world", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/voxel/v1/worlds/{id}/blocks/{x}/{y}/{z}": { "get": { "tags": [ "Voxel Worlds API: worlds" ], "summary": "Inspect a block at coordinates", "operationId": "vx-block", "responses": { "200": { "description": "Block", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "World not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 }, { "name": "x", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 4 }, { "name": "y", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 4 }, { "name": "z", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 4 } ] } }, "/voxel/v1/players": { "get": { "tags": [ "Voxel Worlds API: players" ], "summary": "List players", "operationId": "vx-players", "responses": { "200": { "description": "Players", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/voxel/v1/players/{id}/inventory": { "post": { "tags": [ "Voxel Worlds API: players" ], "summary": "Add an inventory item (409 on duplicate)", "operationId": "vx-inventory", "responses": { "200": { "description": "Item added", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Player missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Already owned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "type": "string" } }, "required": [ "item" ], "additionalProperties": false }, "example": { "item": "diamond_pickaxe" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/anime/v1/fighters": { "get": { "tags": [ "Anime Tournament API: fighters" ], "summary": "List fighters, filter by rank", "operationId": "an-fighters", "responses": { "200": { "description": "Fighters", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "rank", "in": "query", "required": false, "schema": { "type": "string" }, "example": "S" } ] } }, "/anime/v1/fighters/{id}": { "get": { "tags": [ "Anime Tournament API: fighters" ], "summary": "Get fighter power profile", "operationId": "an-fighter", "responses": { "200": { "description": "Fighter", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Missing fighter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } }, "/anime/v1/fighters/{id}/transform": { "post": { "tags": [ "Anime Tournament API: fighters" ], "summary": "Transform a fighter and increase power", "operationId": "an-transform", "responses": { "200": { "description": "Transformed", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "Invalid multiplier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 2 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "form": { "type": "string" }, "multiplier": { "type": "number" } }, "required": [ "form", "multiplier" ], "additionalProperties": false }, "example": { "form": "Ultra Debug Mode", "multiplier": 1.5 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/anime/v1/matches": { "post": { "tags": [ "Anime Tournament API: matches" ], "summary": "Run a deterministic tournament match", "operationId": "an-match", "responses": { "201": { "description": "Match complete", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Invalid fighters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "example": "final-1" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fighterAId": { "type": "integer" }, "fighterBId": { "type": "integer" } }, "required": [ "fighterAId", "fighterBId" ], "additionalProperties": false }, "example": { "fighterAId": 1, "fighterBId": 2 } } } }, "security": [ { "bearerAuth": [] } ] }, "get": { "tags": [ "Anime Tournament API: matches" ], "summary": "List match history", "operationId": "an-matches", "responses": { "200": { "description": "Matches", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/retro/v1/heroes": { "get": { "tags": [ "Retro Quest API: heroes" ], "summary": "List pixel heroes", "operationId": "rq-heroes", "responses": { "200": { "description": "Heroes", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "post": { "tags": [ "Retro Quest API: heroes" ], "summary": "Create a hero", "operationId": "rq-hero", "responses": { "201": { "description": "Hero created", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Name required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "class": { "type": "string" } }, "required": [ "name", "class" ], "additionalProperties": false }, "example": { "name": "Lin the Linter", "class": "ranger" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/retro/v1/quests": { "get": { "tags": [ "Retro Quest API: quests" ], "summary": "List quests by status", "operationId": "rq-quests", "responses": { "200": { "description": "Quests", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "example": "open" } ] } }, "/retro/v1/quests/{id}/accept": { "post": { "tags": [ "Retro Quest API: quests" ], "summary": "Accept a quest (409 if already accepted)", "operationId": "rq-accept", "responses": { "200": { "description": "Quest accepted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "Wrong state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "heroId": { "type": "integer" } }, "required": [ "heroId" ], "additionalProperties": false }, "example": { "heroId": 1 } } } }, "security": [ { "bearerAuth": [] } ] } }, "/retro/v1/quests/{id}/complete": { "post": { "tags": [ "Retro Quest API: quests" ], "summary": "Complete an active quest", "operationId": "rq-complete", "responses": { "200": { "description": "Quest complete", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "409": { "description": "Not active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ], "security": [ { "bearerAuth": [] } ] } }, "/storage/v1/objects": { "get": { "tags": [ "Object Storage API: objects" ], "summary": "List stored objects", "operationId": "st-list", "responses": { "200": { "description": "Objects", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/storage/v1/objects/{key}": { "put": { "tags": [ "Object Storage API: objects" ], "summary": "Upload a base64 object with checksum", "operationId": "st-put", "responses": { "201": { "description": "Stored", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }, "headers": { "Location": { "schema": { "type": "string", "format": "uri-reference" } } } }, "412": { "description": "ETag mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid base64", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "example": "fixtures/users.json" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contentBase64": { "type": "string" }, "contentType": { "type": "string" }, "checksum": { "type": "string" } }, "required": [ "contentBase64", "contentType", "checksum" ], "additionalProperties": false }, "example": { "contentBase64": "SGVsbG8sIHRlc3RlciE=", "contentType": "text/plain", "checksum": "demo-checksum" } } } }, "security": [ { "bearerAuth": [] } ] }, "get": { "tags": [ "Object Storage API: objects" ], "summary": "Download object metadata/content; accepts Range", "operationId": "st-get", "responses": { "200": { "description": "Whole object", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "206": { "description": "Partial content", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "416": { "description": "Invalid range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "example": "fixtures/users.json" }, { "name": "Range", "in": "header", "required": false, "schema": { "type": "string" }, "example": "bytes=0-9" } ] }, "delete": { "tags": [ "Object Storage API: objects" ], "summary": "Delete an object", "operationId": "st-delete", "responses": { "204": { "description": "Deleted" }, "404": { "description": "Missing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "example": "fixtures/users.json" } ], "security": [ { "bearerAuth": [] } ] } }, "/identity/v1/.well-known/openid-configuration": { "get": { "tags": [ "Modern Identity API: discovery" ], "summary": "OIDC discovery document", "operationId": "id-discovery", "responses": { "200": { "description": "Provider metadata", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/identity/v1/jwks": { "get": { "tags": [ "Modern Identity API: discovery" ], "summary": "Demo JSON Web Key Set", "operationId": "id-jwks", "responses": { "200": { "description": "JWKS", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/identity/v1/authorize": { "post": { "tags": [ "Modern Identity API: tokens" ], "summary": "Issue an authorization code with real PKCE (S256)", "operationId": "id-authorize", "responses": { "200": { "description": "Code issued", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid client, unsupported code_challenge_method, or missing codeChallenge", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clientId": { "type": "string" }, "redirectUri": { "type": "string" }, "codeChallenge": { "type": "string" }, "codeChallengeMethod": { "type": "string" }, "scope": { "type": "string" } }, "required": [ "clientId", "redirectUri", "codeChallenge", "codeChallengeMethod", "scope" ], "additionalProperties": false }, "example": { "clientId": "fun-client", "redirectUri": "https://example.com/callback", "codeChallenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", "codeChallengeMethod": "S256", "scope": "openid profile" } } } } } }, "/identity/v1/token": { "post": { "tags": [ "Modern Identity API: tokens" ], "summary": "Exchange a PKCE code for scoped tokens — verifies BASE64URL(SHA256(codeVerifier)) against the stored codeChallenge", "operationId": "id-token", "responses": { "200": { "description": "Tokens issued", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "invalid_grant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "codeVerifier": { "type": "string" } }, "required": [ "code", "codeVerifier" ], "additionalProperties": false }, "example": { "code": "code_from_authorize", "codeVerifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk" } } } } } }, "/identity/v1/introspect": { "post": { "tags": [ "Modern Identity API: tokens" ], "summary": "Introspect an access token", "operationId": "id-introspect", "responses": { "200": { "description": "Token state", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ], "additionalProperties": false }, "example": { "token": "oidc_xxx" } } } } } }, "/identity/v1/revoke": { "post": { "tags": [ "Modern Identity API: tokens" ], "summary": "Revoke an access token", "operationId": "id-revoke", "responses": { "204": { "description": "Revoked or already absent" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" } }, "required": [ "token" ], "additionalProperties": false }, "example": { "token": "oidc_xxx" } } } } } }, "/streams/v1/events": { "get": { "tags": [ "Event Streams API: events" ], "summary": "Read events as JSON or text/event-stream", "operationId": "es-events", "responses": { "200": { "description": "JSON batch or SSE stream", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "Last-Event-ID", "in": "header", "required": false, "schema": { "type": "string" }, "example": "5" } ] }, "post": { "tags": [ "Event Streams API: events" ], "summary": "Publish a custom event", "operationId": "es-publish", "responses": { "202": { "description": "Event accepted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "data": { "type": "object", "properties": { "buildId": { "type": "integer" } }, "required": [ "buildId" ], "additionalProperties": false } }, "required": [ "type", "data" ], "additionalProperties": false }, "example": { "type": "build.completed", "data": { "buildId": 42 } } } } }, "security": [ { "bearerAuth": [] } ] } }, "/streams/v1/events/{id}": { "get": { "tags": [ "Event Streams API: events" ], "summary": "Replay one event by id", "operationId": "es-replay", "responses": { "200": { "description": "Event", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Missing event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 3 } ] } }, "/faults/v1/config": { "get": { "tags": [ "Fault Injection API: control" ], "summary": "Read fault profile", "operationId": "ft-config-get", "responses": { "200": { "description": "Profile", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } }, "put": { "tags": [ "Fault Injection API: control" ], "summary": "Configure fault profile", "operationId": "ft-config-put", "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "Invalid profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "latencyMs": { "type": "integer" }, "status": { "type": "integer" }, "malformed": { "type": "boolean" }, "failureRate": { "type": "number" } }, "required": [ "latencyMs", "status", "malformed", "failureRate" ], "additionalProperties": false }, "example": { "latencyMs": 750, "status": 503, "malformed": false, "failureRate": 0.25 } } } }, "security": [ { "bearerAuth": [] } ] }, "delete": { "tags": [ "Fault Injection API: control" ], "summary": "Reset fault profile", "operationId": "ft-reset", "responses": { "204": { "description": "Reset" } }, "security": [ { "bearerAuth": [] } ] } }, "/faults/v1/target": { "get": { "tags": [ "Fault Injection API: target" ], "summary": "Call the configured flaky target", "operationId": "ft-target", "responses": { "200": { "description": "Healthy response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "500": { "description": "Configured failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Configured outage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" } } } } } } }, "/search/v1/items": { "get": { "tags": [ "Search & Facets API: search" ], "summary": "Search items with facets and cursor", "operationId": "sr-search", "responses": { "200": { "description": "Results and facets", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "example": "dragon" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" }, "example": "score" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 0 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 2 } ] } }, "/search/v1/suggest": { "get": { "tags": [ "Search & Facets API: search" ], "summary": "Autocomplete suggestions", "operationId": "sr-suggest", "responses": { "200": { "description": "Suggestions", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "example": "mo" } ] } }, "/data/v1/types": { "get": { "tags": [ "Fun Data Bridge API: generate" ], "summary": "List supported field types", "operationId": "dg-types", "responses": { "200": { "description": "Types", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/data/v1/generate": { "post": { "tags": [ "Fun Data Bridge API: generate" ], "summary": "Generate deterministic JSON rows", "operationId": "dg-generate", "responses": { "200": { "description": "Generated rows", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "Invalid schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "seed": { "type": "integer" }, "rows": { "type": "integer" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } }, "required": [ "name", "type" ], "additionalProperties": false } } }, "required": [ "seed", "rows", "fields" ], "additionalProperties": false }, "example": { "seed": 42, "rows": 5, "fields": [ { "name": "id", "type": "row" }, { "name": "email", "type": "email" } ] } } } } } }, "/data/v1/jobs": { "post": { "tags": [ "Fun Data Bridge API: generate" ], "summary": "Queue a large fixture job", "operationId": "dg-job", "responses": { "202": { "description": "Job accepted", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "422": { "description": "Invalid job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "integer" }, "format": { "type": "string" } }, "required": [ "rows", "format" ], "additionalProperties": false }, "example": { "rows": 100000, "format": "csv" } } } }, "security": [ { "bearerAuth": [] } ] } }, "/data/v1/jobs/{id}": { "get": { "tags": [ "Fun Data Bridge API: generate" ], "summary": "Poll fixture job", "operationId": "dg-job-get", "responses": { "200": { "description": "Job state", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "description": "Missing job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" }, "example": 1 } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Use qa-admin-token / qa-viewer-token, or a JWT from POST /auth/v1/login." }, "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Cargo demo key: cargo-key-123." } }, "schemas": { "Error": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" } }, "additionalProperties": true } } } }