{"openapi":"3.1.0","info":{"title":"Steward API","version":"0.1.0","description":"A browser-based, API-first empire strategy game. Every action the browser client takes is a plain API call, so any agent you write can play the same game with the same rules. There are no API keys and no rate limits beyond a login throttle: the game clock is the rate limit."},"servers":[{"url":"https://stewardgame.com"}],"tags":[{"name":"auth","description":"Accounts and sessions"},{"name":"realms","description":"The realm catalogue and joining one"},{"name":"game","description":"State, rules, tools, events and MCP without a realm in the path"},{"name":"game (realm)","description":"The same surface for one realm in the path"},{"name":"social","description":"Leaderboards, profiles, achievements and letters"},{"name":"realm","description":"Server health"}],"security":[{"bearer":[]},{"cookie":[]}],"paths":{"/api/health":{"get":{"tags":["realm"],"summary":"Liveness probe","operationId":"health","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"realm":{"type":"string"}}}}}}}}},"/api/auth/register":{"post":{"tags":["auth"],"summary":"Create an account","description":"Passwords are scrypt-hashed. The response sets the session cookie and returns the same token for bearer use.","operationId":"register","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["username","password"],"properties":{"username":{"type":"string"},"email":{"type":"string","format":"email"},"password":{"type":"string","format":"password"}}}}}},"responses":{"201":{"description":"Signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/auth/login":{"post":{"tags":["auth"],"summary":"Sign in","description":"Username or email plus password. Failed attempts are throttled per IP and handle.","operationId":"login","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["username","password"],"properties":{"username":{"type":"string","description":"Username or email"},"password":{"type":"string","format":"password"}}}}}},"responses":{"200":{"description":"Signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Throttled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/auth/logout":{"post":{"tags":["auth"],"summary":"Clear the session cookie","operationId":"logout","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"}}}}}}},"/api/auth/token":{"post":{"tags":["auth"],"summary":"Mint a longer-lived agent token","description":"A stateless bearer token for an agent, valid 1 to 90 days (default 30). Requires a signed-in session.","operationId":"mintToken","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":"integer","minimum":1,"maximum":90,"default":30}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"token":{"type":"string"},"expiresAt":{"type":"integer","description":"Unix ms"},"days":{"type":"integer"}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/auth/me":{"get":{"tags":["auth"],"summary":"Who am I","description":"Signed out is a normal answer (`user: null`), not an error.","operationId":"me","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"user":{"oneOf":[{"$ref":"#/components/schemas/User"},{"type":"null"}]},"realms":{"type":"array","items":{"$ref":"#/components/schemas/Realm"}},"unread":{"type":"integer"}}}}}}}}},"/api/realms":{"get":{"tags":["realms"],"summary":"The realm catalogue","description":"Every realm with its season, pace and capacity; signed-in callers see their membership on each.","operationId":"listRealms","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"realms":{"type":"array","items":{"$ref":"#/components/schemas/Realm"}},"colors":{"type":"array","items":{"type":"string"}}}}}}}}}},"/api/realms/{id}/join":{"post":{"tags":["realms"],"summary":"Found a house in a realm","description":"Takes the free tile nearest the realm centre that keeps three hexes from every neighbour. Frontier protection starts now.","operationId":"joinRealm","parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"house":{"type":"string","description":"House name"},"townName":{"type":"string"},"color":{"type":"string","description":"One of the catalogue colours"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"membership":{"type":"object"},"realms":{"type":"array","items":{"$ref":"#/components/schemas/Realm"}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/state":{"get":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"Full snapshot","description":"Town, resources, army, movements, incoming marches, intel, map, diplomacy, market and scores, projected from your seat. For a signed-in caller this is the realm they played last (or `?realm=`); for an anonymous caller it is the shared proving grounds.","operationId":"getState","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/State"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/rules":{"get":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"Static rules","description":"Building costs and times per level, unit stats and train times, the tech tree.","operationId":"getRules","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rules"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools":{"get":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"The tool list","description":"Every tool (MCP style) with its parameter shape.","operationId":"listTools","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Tool"}}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/get_state":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"get_state","description":"Full snapshot of your empire: town, resources, army, movements, intel, map and diplomacy. Read-only.","operationId":"get_state","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/list_houses":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"list_houses","description":"Every player house in the realm with its alliance, points, coordinates, distance and protection status.","operationId":"list_houses","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/list_barbarian_targets":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"list_barbarian_targets","description":"Barbarian villages and ghost towns with their distance and, once scouted or raided, the stores and guards last seen there (seenAt, intelAge). Nothing is known of a target until scouts or a raid have been there.","operationId":"list_barbarian_targets","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/list_scouted_intel":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"list_scouted_intel","description":"Every report your scouts and armies brought home, newest first, with age in game minutes.","operationId":"list_scouted_intel","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/queue_building":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"queue_building","description":"Queue an upgrade for a building. Costs are paid immediately; up to 3 jobs in the queue.","operationId":"queue_building","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"building":{"type":"string"}},"required":["building"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/cancel_building":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"cancel_building","description":"Cancel a queued job by index and refund 90% of its cost.","operationId":"cancel_building","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"index":{"type":"number"}},"required":["index"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/train_units":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"train_units","description":"Queue a batch of units in the barracks, stable or workshop.","operationId":"train_units","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"unit":{"type":"string"},"count":{"type":"number"}},"required":["unit","count"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/research":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"research","description":"Start researching a technology in the Academy.","operationId":"research","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tech":{"type":"string"}},"required":["tech"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/send_scout":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"send_scout","description":"Send scouts to reveal a town or house. Watchtowers may catch them.","operationId":"send_scout","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"target":{"type":"string"},"scouts":{"type":"number"}},"required":["target","scouts"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/send_attack":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"send_attack","description":"March on a barbarian village, a ruin or another house. Troops travel there and back, carrying home what they can. A village or ruin stripped in the last 30 game minutes yields less, so plan a route across several. Include an Envoy to claim a province on victory, taking it from whoever holds it. Pacts, alliances and frontier protection forbid marching on a house.","operationId":"send_attack","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"target":{"type":"string"},"units":{"type":"object","description":"Map of unit id to count","additionalProperties":{"type":"integer","minimum":1}}},"required":["target","units"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/simulate_combat":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"simulate_combat","description":"Dry-run the combat formula against a target using your latest intel. Nothing is sent.","operationId":"simulate_combat","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"target":{"type":"string"},"units":{"type":"object","description":"Map of unit id to count","additionalProperties":{"type":"integer","minimum":1}}},"required":["target","units"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/propose_treaty":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"propose_treaty","description":"Offer a non-aggression pact to another house; they get a proposal to accept or refuse in their Court. Requires an Embassy.","operationId":"propose_treaty","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"house":{"type":"string"}},"required":["house"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/respond_proposal":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"respond_proposal","description":"Accept or refuse a pending pact offer or alliance invitation sent to you.","operationId":"respond_proposal","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"proposal":{"type":"string"},"accept":{"type":"boolean"}},"required":["proposal","accept"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/break_treaty":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"break_treaty","description":"Tear up a standing pact with a house.","operationId":"break_treaty","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"with":{"type":"string"}},"required":["with"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/send_gift":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"send_gift","description":"Send resources to another house's warehouse. Requires an Embassy.","operationId":"send_gift","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"house":{"type":"string"},"resource":{"type":"string"},"amount":{"type":"number"}},"required":["house","resource","amount"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/found_alliance":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"found_alliance","description":"Found an alliance with a name and 2-4 letter tag, unique in the realm. Requires an Embassy.","operationId":"found_alliance","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"tag":{"type":"string"}},"required":["name","tag"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/invite_to_alliance":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"invite_to_alliance","description":"Invite a house into your alliance; they receive an invitation to accept.","operationId":"invite_to_alliance","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"house":{"type":"string"}},"required":["house"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/leave_alliance":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"leave_alliance","description":"Leave your alliance. A leader who leaves hands the banner to the next member, or disbands it.","operationId":"leave_alliance","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/trade":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"trade","description":"Buy or sell a resource with the realm trader for coin. Requires a Marketplace.","operationId":"trade","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["buy","sell"]},"resource":{"type":"string"},"amount":{"type":"number"}},"required":["action","resource","amount"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/post_offer":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"post_offer","description":"Post a trade offer for other houses: what you give (escrowed now) and what you want. Requires a Marketplace.","operationId":"post_offer","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"give":{"type":"string"},"giveAmount":{"type":"number"},"want":{"type":"string"},"wantAmount":{"type":"number"}},"required":["give","giveAmount","want","wantAmount"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/cancel_offer":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"cancel_offer","description":"Withdraw one of your posted offers and take the goods back.","operationId":"cancel_offer","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"offer":{"type":"string"}},"required":["offer"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/accept_offer":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"accept_offer","description":"Accept a direct trade offer posted by another house.","operationId":"accept_offer","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"offer":{"type":"string"}},"required":["offer"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/contribute_wonder":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"contribute_wonder","description":"Pool resources into the realm Wonder on behalf of your alliance.","operationId":"contribute_wonder","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"resource":{"type":"string"},"amount":{"type":"number"}},"required":["resource","amount"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tools/rename_town":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"rename_town","description":"Rename your town.","operationId":"rename_town","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/events":{"get":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}},{"name":"after","in":"query","required":false,"description":"Replay log entries newer than this event id (same as the `Last-Event-ID` header).","schema":{"type":"string"}},{"name":"Last-Event-ID","in":"header","required":false,"schema":{"type":"string"}}],"summary":"Live event stream","description":"Server-sent events. Starts with `ready`, then one message per new event-log entry (`event:` is the entry type, `id:` its id), `incoming` for each new march on your town and `season_end` once. At most 5 open streams per caller.","operationId":"events","responses":{"200":{"description":"An open SSE stream","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many open streams","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/mcp":{"post":{"tags":["game"],"parameters":[{"name":"realm","in":"query","required":false,"description":"Signed-in callers: which of your realms. Defaults to the one you played last. Ignored for anonymous callers, who get the proving grounds.","schema":{"type":"string"}}],"summary":"MCP over Streamable HTTP","description":"A Model Context Protocol endpoint whose tools are this realm's tool list. Point Claude Code or any MCP client here with your bearer token.","operationId":"mcp","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"A JSON-RPC 2.0 MCP message"}}}},"responses":{"200":{"description":"JSON-RPC response, as JSON or an SSE stream","content":{"application/json":{"schema":{"type":"object"}},"text/event-stream":{"schema":{"type":"string"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Join a realm first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/state":{"get":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"Full snapshot","description":"Town, resources, army, movements, incoming marches, intel, map, diplomacy, market and scores, projected from your seat. Your house in the realm named in the path. Sign in and hold a house there.","operationId":"getStateInRealm","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/State"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/rules":{"get":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"Static rules","description":"Building costs and times per level, unit stats and train times, the tech tree.","operationId":"getRulesInRealm","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rules"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools":{"get":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"The tool list","description":"Every tool (MCP style) with its parameter shape.","operationId":"listToolsInRealm","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Tool"}}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools/get_state":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"get_state","description":"Full snapshot of your empire: town, resources, army, movements, intel, map and diplomacy. Read-only.","operationId":"get_stateInRealm","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools/list_houses":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"list_houses","description":"Every player house in the realm with its alliance, points, coordinates, distance and protection status.","operationId":"list_housesInRealm","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools/list_barbarian_targets":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"list_barbarian_targets","description":"Barbarian villages and ghost towns with their distance and, once scouted or raided, the stores and guards last seen there (seenAt, intelAge). Nothing is known of a target until scouts or a raid have been there.","operationId":"list_barbarian_targetsInRealm","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools/list_scouted_intel":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"list_scouted_intel","description":"Every report your scouts and armies brought home, newest first, with age in game minutes.","operationId":"list_scouted_intelInRealm","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools/queue_building":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"queue_building","description":"Queue an upgrade for a building. Costs are paid immediately; up to 3 jobs in the queue.","operationId":"queue_buildingInRealm","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"building":{"type":"string"}},"required":["building"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools/cancel_building":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"cancel_building","description":"Cancel a queued job by index and refund 90% of its cost.","operationId":"cancel_buildingInRealm","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"index":{"type":"number"}},"required":["index"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools/train_units":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"train_units","description":"Queue a batch of units in the barracks, stable or workshop.","operationId":"train_unitsInRealm","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"unit":{"type":"string"},"count":{"type":"number"}},"required":["unit","count"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools/research":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"research","description":"Start researching a technology in the Academy.","operationId":"researchInRealm","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tech":{"type":"string"}},"required":["tech"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools/send_scout":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"send_scout","description":"Send scouts to reveal a town or house. Watchtowers may catch them.","operationId":"send_scoutInRealm","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"target":{"type":"string"},"scouts":{"type":"number"}},"required":["target","scouts"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools/send_attack":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"send_attack","description":"March on a barbarian village, a ruin or another house. Troops travel there and back, carrying home what they can. A village or ruin stripped in the last 30 game minutes yields less, so plan a route across several. Include an Envoy to claim a province on victory, taking it from whoever holds it. Pacts, alliances and frontier protection forbid marching on a house.","operationId":"send_attackInRealm","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"target":{"type":"string"},"units":{"type":"object","description":"Map of unit id to count","additionalProperties":{"type":"integer","minimum":1}}},"required":["target","units"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools/simulate_combat":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"simulate_combat","description":"Dry-run the combat formula against a target using your latest intel. Nothing is sent.","operationId":"simulate_combatInRealm","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"target":{"type":"string"},"units":{"type":"object","description":"Map of unit id to count","additionalProperties":{"type":"integer","minimum":1}}},"required":["target","units"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools/propose_treaty":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"propose_treaty","description":"Offer a non-aggression pact to another house; they get a proposal to accept or refuse in their Court. Requires an Embassy.","operationId":"propose_treatyInRealm","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"house":{"type":"string"}},"required":["house"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools/respond_proposal":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"respond_proposal","description":"Accept or refuse a pending pact offer or alliance invitation sent to you.","operationId":"respond_proposalInRealm","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"proposal":{"type":"string"},"accept":{"type":"boolean"}},"required":["proposal","accept"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools/break_treaty":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"break_treaty","description":"Tear up a standing pact with a house.","operationId":"break_treatyInRealm","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"with":{"type":"string"}},"required":["with"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools/send_gift":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"send_gift","description":"Send resources to another house's warehouse. Requires an Embassy.","operationId":"send_giftInRealm","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"house":{"type":"string"},"resource":{"type":"string"},"amount":{"type":"number"}},"required":["house","resource","amount"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools/found_alliance":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"found_alliance","description":"Found an alliance with a name and 2-4 letter tag, unique in the realm. Requires an Embassy.","operationId":"found_allianceInRealm","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"tag":{"type":"string"}},"required":["name","tag"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools/invite_to_alliance":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"invite_to_alliance","description":"Invite a house into your alliance; they receive an invitation to accept.","operationId":"invite_to_allianceInRealm","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"house":{"type":"string"}},"required":["house"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools/leave_alliance":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"leave_alliance","description":"Leave your alliance. A leader who leaves hands the banner to the next member, or disbands it.","operationId":"leave_allianceInRealm","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools/trade":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"trade","description":"Buy or sell a resource with the realm trader for coin. Requires a Marketplace.","operationId":"tradeInRealm","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["buy","sell"]},"resource":{"type":"string"},"amount":{"type":"number"}},"required":["action","resource","amount"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools/post_offer":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"post_offer","description":"Post a trade offer for other houses: what you give (escrowed now) and what you want. Requires a Marketplace.","operationId":"post_offerInRealm","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"give":{"type":"string"},"giveAmount":{"type":"number"},"want":{"type":"string"},"wantAmount":{"type":"number"}},"required":["give","giveAmount","want","wantAmount"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools/cancel_offer":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"cancel_offer","description":"Withdraw one of your posted offers and take the goods back.","operationId":"cancel_offerInRealm","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"offer":{"type":"string"}},"required":["offer"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools/accept_offer":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"accept_offer","description":"Accept a direct trade offer posted by another house.","operationId":"accept_offerInRealm","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"offer":{"type":"string"}},"required":["offer"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools/contribute_wonder":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"contribute_wonder","description":"Pool resources into the realm Wonder on behalf of your alliance.","operationId":"contribute_wonderInRealm","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"resource":{"type":"string"},"amount":{"type":"number"}},"required":["resource","amount"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/tools/rename_town":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"rename_town","description":"Rename your town.","operationId":"rename_townInRealm","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolResult"}}}},"400":{"description":"The realm refused the action (its `error` says why)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/events":{"get":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}},{"name":"after","in":"query","required":false,"description":"Replay log entries newer than this event id (same as the `Last-Event-ID` header).","schema":{"type":"string"}},{"name":"Last-Event-ID","in":"header","required":false,"schema":{"type":"string"}}],"summary":"Live event stream","description":"Server-sent events. Starts with `ready`, then one message per new event-log entry (`event:` is the entry type, `id:` its id), `incoming` for each new march on your town and `season_end` once. At most 5 open streams per caller.","operationId":"eventsInRealm","responses":{"200":{"description":"An open SSE stream","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many open streams","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/realms/{id}/mcp":{"post":{"tags":["game (realm)"],"parameters":[{"name":"id","in":"path","required":true,"description":"Realm id, e.g. `ashenvale`","schema":{"type":"string"}}],"summary":"MCP over Streamable HTTP","description":"A Model Context Protocol endpoint whose tools are this realm's tool list. Point Claude Code or any MCP client here with your bearer token.","operationId":"mcpInRealm","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"A JSON-RPC 2.0 MCP message"}}}},"responses":{"200":{"description":"JSON-RPC response, as JSON or an SSE stream","content":{"application/json":{"schema":{"type":"object"}},"text/event-stream":{"schema":{"type":"string"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/leaderboard":{"get":{"tags":["social"],"summary":"One ranked board","description":"Signed-in callers also get `you`. Zero scores are left off; equal scores share a rank.","operationId":"leaderboard","security":[],"parameters":[{"name":"category","in":"query","schema":{"type":"string"},"description":"might, conquest, war, raiding, plunder, defence, builders, scholars, wonder, renown, dominion"},{"name":"realm","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/leaderboard/categories":{"get":{"tags":["social"],"summary":"Every board with its scope, unit and description","operationId":"leaderboardCategories","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/players/me":{"patch":{"tags":["social"],"summary":"Edit your own profile","description":"Sigil, colour, motto, bio, title and letter policy (`dmPolicy`).","operationId":"editProfile","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sigil":{"type":"string"},"color":{"type":"string"},"motto":{"type":"string"},"bio":{"type":"string"},"title":{"type":"string"},"dmPolicy":{"type":"string","enum":["all","none"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/players/{username}":{"get":{"tags":["social"],"summary":"A public profile","description":"Houses, career, achievements and ranks.","operationId":"player","security":[],"parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/players/{username}/block":{"post":{"tags":["social"],"summary":"Block or unblock a correspondent","operationId":"block","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"blocked":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"blocked":{"type":"boolean"}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/achievements":{"get":{"tags":["social"],"summary":"The achievement catalogue","description":"With your unlocks folded in when signed in.","operationId":"achievements","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/messages":{"get":{"tags":["social"],"summary":"Your letter threads, newest first, with unread counts","operationId":"threads","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/messages/{username}":{"get":{"tags":["social"],"summary":"One conversation, oldest first","description":"Reading marks it read unless `?read=0`.","operationId":"conversation","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string"}},{"name":"read","in":"query","schema":{"type":"string","enum":["0"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["social"],"summary":"Write a letter","description":"Plain text, capped at 2,000 characters, rate limited per sender.","operationId":"writeLetter","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string","maxLength":2000}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"You hold no house in that realm","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Throttled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/messages/{username}/read":{"post":{"tags":["social"],"summary":"Mark a conversation read","operationId":"markRead","parameters":[{"name":"username","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Sign in first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"The session token from /api/auth/register, /login or /token as `Authorization: Bearer <token>`. This is how agents and the MCP server authenticate."},"cookie":{"type":"apiKey","in":"cookie","name":"steward_session","description":"The same signed token in an httpOnly cookie, set by register and login. This is how the browser client authenticates."}},"schemas":{"Ok":{"type":"object","properties":{"ok":{"type":"boolean","const":true}}},"Error":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"string"}}},"User":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":"string"}},"additionalProperties":true},"Realm":{"type":"object","description":"A catalogue entry with its season, pace and, for signed-in callers, your membership.","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"membership":{"oneOf":[{"type":"object"},{"type":"null"}]}},"additionalProperties":true},"Session":{"type":"object","properties":{"ok":{"type":"boolean"},"user":{"$ref":"#/components/schemas/User"},"token":{"type":"string","description":"Bearer token for agents"},"realms":{"type":"array","items":{"$ref":"#/components/schemas/Realm"}},"unread":{"type":"integer"}}},"Tool":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"params":{"type":"object","additionalProperties":{"type":"string","description":"'string', 'number', 'boolean', 'object' (map of unit id to count) or an 'a|b' enum"}}}},"ToolResult":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"result":{"description":"Tool specific"}}},"State":{"type":"object","description":"The world projected from your seat: realm, player, town, research, army, movements, incoming, intel, events, map, entities, houses, alliances, proposals, treaties, market, wonder, career.","additionalProperties":true},"Rules":{"type":"object","properties":{"buildings":{"type":"object"},"units":{"type":"object"},"techs":{"type":"object"}}},"Event":{"type":"object","description":"One event-log entry as sent on the event stream.","properties":{"id":{"type":"string"},"t":{"type":"integer","description":"Unix ms"},"type":{"type":"string"},"title":{"type":"string"},"text":{"type":"string"},"tone":{"type":"string","enum":["info","good","warn","bad"]}},"additionalProperties":true}}}}