Quick start · Playbook · Raw JSON
{
"openapi": "3.1.0",
"info": {
"title": "MAGTOPIA（麦托邦）Agent API",
"version": "1.0.0",
"description": "Private multi-city construction API for municipal Agents building living magic cities."
},
"servers": [
{
"url": "https://magtopia.city/api/v1"
}
],
"security": [
{
"bearerAuth": []
}
],
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
},
"schemas": {
"Error": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
},
"Endpoint": {
"oneOf": [
{
"type": "object",
"required": [
"kind",
"id"
],
"properties": {
"kind": {
"const": "building"
},
"id": {
"type": "string"
},
"entrance": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"kind",
"id"
],
"properties": {
"kind": {
"const": "cell"
},
"id": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"kind",
"id"
],
"properties": {
"kind": {
"const": "node"
},
"id": {
"type": "string"
}
}
}
]
},
"BuildingDesignConstructionRequest": {
"type": "object",
"additionalProperties": false,
"required": [
"expected_city_version",
"design_id",
"design_revision",
"design_hash"
],
"properties": {
"expected_city_version": {
"type": "integer",
"minimum": 0
},
"district_id": {
"type": "string",
"description": "Named development district this building contributes to"
},
"design_id": {
"type": "string"
},
"design_revision": {
"type": "integer",
"minimum": 1
},
"design_hash": {
"type": "string",
"description": "Exact hash returned when the design revision was confirmed"
},
"actor_note": {
"type": "string",
"description": "Optional factual construction reason. Site, footprint, entrance, program, asset, functional area, and exact cost are derived by the server from the confirmed BuildingDesign."
}
}
},
"GatewayUpgradeRequest": {
"type": "object",
"additionalProperties": false,
"required": [
"expected_city_version"
],
"properties": {
"expected_city_version": {
"type": "integer",
"minimum": 0
},
"actor_note": {
"type": "string",
"description": "Optional factual reason for upgrading the fixed railway gateway."
}
}
},
"Site": {
"type": "object",
"required": [
"anchor_cell_id",
"footprint",
"entrance"
],
"properties": {
"anchor_cell_id": {
"type": "string",
"description": "anchor_cell_id returned by POST /site-searches"
},
"footprint": {
"enum": [
"1x1",
"1x2",
"1x3",
"2x1",
"2x2",
"2x3",
"3x1",
"3x2",
"3x3"
]
},
"entrance": {
"enum": [
"north",
"east",
"south",
"west"
]
}
}
},
"BuildingIntent": {
"type": "object",
"description": "Semantic and visual building brief. Choose purpose first, then composition/frontage/access/style/prominence. magic_level controls visual intensity only; use the sibling gameplay_profile to author wizard capacity, Arcane Energy production, and magical exposure. The x-agent-catalog below explains how each option changes the generated architecture; use it as the design vocabulary rather than guessing from enum names.",
"required": [
"name",
"purpose"
],
"properties": {
"name": {
"type": "string",
"minLength": 1,
"description": "Human-readable building name."
},
"purpose": {
"type": "string",
"minLength": 1,
"description": "What the building is for. Free text is also used to infer public program families such as residential, library, academy, greenhouse, workshop, civic, or generic_public."
},
"description": {
"type": "string",
"description": "Optional concrete architectural or functional brief. Prefer observable requirements over generic adjectives."
},
"sign_text": {
"type": "string",
"description": "Optional semantic sign wording. Decorative sign geometry is controlled separately through decorations."
},
"composition": {
"enum": [
"street",
"court",
"hall",
"tower",
"yard"
],
"description": "Overall spatial organization. court/hall/tower/yard automatically favor urban_massing; street is the normal compact street-building composition."
},
"frontage": {
"enum": [
"residential",
"display",
"workshop",
"institutional",
"large_bay"
],
"description": "Street-facing functional character. This changes ground-floor program, glazing/opening ratio, entrance treatment, and generation-mode recommendations."
},
"access": {
"enum": [
"private",
"public",
"service",
"ceremonial"
],
"description": "How the primary entrance should read. Public and ceremonial access strengthen entrance emphasis and can make an urban-massing building count as public architecture."
},
"style": {
"enum": [
"victorian_domestic",
"victorian_gothic",
"civic_classical",
"industrial_iron",
"alchemical_glass"
],
"description": "Architectural language. For public buildings this changes massing, roof families, facade rhythm, and constrained materials, not only color."
},
"prominence": {
"enum": [
"ordinary",
"important",
"landmark"
],
"description": "Urban hierarchy. Higher prominence increases default scale and height; landmark always favors urban_massing."
},
"magic_level": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Continuous magical intensity. Higher values increase generated variation/detail and night-light contribution; keep ordinary background fabric restrained and reserve high values for intentional magical emphasis."
},
"district_style": {
"type": "string",
"description": "Optional district-level style cue to preserve. For housing, use this with district_context so nearby buildings share a family."
},
"variation_intent": {
"type": "string",
"description": "Optional high-level structural variation cue such as narrow_corner_house, stepped_frontage, hip_roof, or corner. Use one or two cues to vary a house without destroying district coherence."
}
},
"x-agent-catalog": {
"version": "1.0",
"decisionOrder": [
"purpose",
"composition",
"frontage",
"access",
"style",
"prominence",
"magic_level",
"district_style",
"variation_intent"
],
"generationModeRules": {
"floor_stack": "Recommended for a 1x1 ordinary street building such as a house, shop, or small workshop.",
"urban_massing": "Recommended for multi-cell sites, institutional frontage, landmarks, and court/hall/tower/yard compositions.",
"auto": "Prefer auto unless the Agent has a specific reason to force a mode. Multi-cell footprint, institutional frontage, landmark prominence, or court/hall/tower/yard composition selects urban_massing."
},
"composition": {
"street": {
"meaning": "Compact building organized primarily around the street frontage.",
"bestFor": [
"residential",
"shop",
"small_workshop",
"mixed_use"
],
"effects": [
"Normally compatible with floor_stack on 1x1 sites.",
"Uses a street-oriented roof unless another cue overrides it."
]
},
"court": {
"meaning": "Multiple masses or wings organized around an internal court.",
"bestFor": [
"academy",
"inn",
"archive",
"institutional_compound"
],
"effects": [
"Selects urban_massing in auto mode.",
"Useful when the interior open space is part of the identity."
]
},
"hall": {
"meaning": "A dominant broad public or productive hall.",
"bestFor": [
"civic_hall",
"market",
"library_reading_hall",
"workshop"
],
"effects": [
"Selects urban_massing in auto mode.",
"In street adaptation it favors a cross-gable roof; in massing it favors hall-like presets/components."
]
},
"tower": {
"meaning": "Vertical silhouette organized around a tower or crown.",
"bestFor": [
"landmark",
"academy_tower",
"clocktower",
"magical_observatory"
],
"effects": [
"Selects urban_massing in auto mode.",
"Encourages a strong crown/spire and taller silhouette."
]
},
"yard": {
"meaning": "Building masses arranged with a working or communal open yard.",
"bestFor": [
"workshop",
"industrial",
"service_compound",
"greenhouse_complex"
],
"effects": [
"Selects urban_massing in auto mode.",
"Best when an external work/open area is intentional rather than leftover space."
]
}
},
"frontage": {
"residential": {
"meaning": "Domestic street face with moderate openings and private-scale rhythm.",
"groundProgram": "home",
"approximateGroundWindowRatio": 0.38,
"bestFor": [
"house",
"residential_mixed_use"
],
"effects": [
"Ordinary/default frontage.",
"Residential guidance asks the Agent to preserve district grammar and vary only one or two structural cues."
]
},
"display": {
"meaning": "Retail/display frontage with large ground-floor glazing.",
"groundProgram": "shop",
"approximateGroundWindowRatio": 0.86,
"bestFor": [
"shop",
"cafe",
"potion_store",
"wand_shop"
],
"effects": [
"Second floor may receive a selective balcony.",
"A custom semantic_grid_sign is recommended before construction."
]
},
"workshop": {
"meaning": "Craft or production frontage with visibly productive openings.",
"groundProgram": "workshop",
"approximateGroundWindowRatio": 0.58,
"bestFor": [
"artisan_workshop",
"small_factory",
"repair_shop"
],
"effects": [
"Upper floors default toward storage rather than home in floor_stack."
]
},
"institutional": {
"meaning": "Formal public/institutional frontage with controlled large openings and clear entrance hierarchy.",
"groundProgram": "home in floor_stack adapter; public program is expressed primarily through urban_massing",
"approximateGroundWindowRatio": 0.5,
"bestFor": [
"library",
"academy",
"civic",
"museum"
],
"effects": [
"Selects urban_massing in auto mode.",
"Defaults style to civic_classical when style is omitted."
]
},
"large_bay": {
"meaning": "Wide-span productive frontage for large doors/windows or loading-like openings.",
"groundProgram": "workshop",
"approximateGroundWindowRatio": 0.7,
"bestFor": [
"industrial_hall",
"large_workshop",
"depot"
],
"effects": [
"Favors a cross-gable roof in street adaptation.",
"Upper floors default toward storage in floor_stack."
]
}
},
"access": {
"private": {
"meaning": "Resident/staff-oriented entrance with restrained emphasis.",
"effects": [
"Urban-massing entrance emphasis may be reduced.",
"Street adaptation can keep a less exposed corner-facade treatment unless variation_intent requests a corner condition."
]
},
"public": {
"meaning": "Clearly readable everyday public entrance.",
"effects": [
"Strengthens entrance emphasis.",
"Can classify a non-residential urban-massing design for public architecture review."
]
},
"service": {
"meaning": "Operational/service access rather than ceremonial frontage.",
"effects": [
"Use for workshops, yards, and back-of-house functions when the entrance should read utilitarian."
]
},
"ceremonial": {
"meaning": "Formal civic or landmark arrival.",
"effects": [
"Strengthens entrance emphasis.",
"Can classify a non-residential urban-massing design for public architecture review."
]
}
},
"style": {
"victorian_domestic": {
"meaning": "Dense London domestic fabric: narrow plots, brick, varied gables/mansards and chimney rhythm.",
"bestFor": [
"housing",
"shops",
"background_street_fabric"
],
"effects": [
"Street palette maps to london_brick.",
"Public massing uses narrow-unit/stepped domestic grammar rather than a simple recolor."
]
},
"victorian_gothic": {
"meaning": "Vertical Gothic Victorian language with narrow tall openings, pointed details, steep roofs, buttress/spire cues.",
"bestFor": [
"academy",
"library",
"occult_shop",
"important_residence"
],
"effects": [
"Street palette maps to violet_alchemist.",
"Public massing uses gothic facade/roof grammar."
]
},
"civic_classical": {
"meaning": "Formal civic language with broad symmetry, stone hierarchy, colonnade/pediment and restrained dome/crown accents.",
"bestFor": [
"civic",
"library",
"museum",
"institution"
],
"effects": [
"Default for institutional frontage or landmark when style is omitted.",
"Public buildings use full civic massing grammar."
]
},
"industrial_iron": {
"meaning": "Victorian industrial language with dark brick/iron, asymmetry, sawtooth or utilitarian roofs, large windows, canopies and chimney stacks.",
"bestFor": [
"factory",
"workshop",
"depot",
"infrastructure"
],
"effects": [
"Street ridge position shifts off-center.",
"Public massing uses industrial form/material grammar."
]
},
"alchemical_glass": {
"meaning": "Magical research/greenhouse language using patinated metal, teal glass, glass halls, arched greenhouse roofs and distillation-tower cues.",
"bestFor": [
"greenhouse",
"alchemical_lab",
"research_building"
],
"effects": [
"Framed masses prefer tealGlass panels.",
"Public massing uses glass-and-patina architectural grammar."
]
}
},
"prominence": {
"ordinary": {
"meaning": "Background fabric; should not compete with anchors.",
"defaultSiteCells": [
2,
2
],
"floorStackDefaultFloors": 2,
"effects": [
"Smallest default urban hierarchy."
]
},
"important": {
"meaning": "Block/district anchor that deserves extra height or presence without becoming a city landmark.",
"defaultSiteCells": [
3,
2
],
"floorStackDefaultFloors": 3,
"effects": [
"Floor-stack upper levels can receive a small setback.",
"Non-residential urban_massing is reviewed as public architecture when applicable."
]
},
"landmark": {
"meaning": "City/district landmark with a deliberately dominant silhouette.",
"defaultSiteCells": [
5,
3
],
"floorStackDefaultFloors": 4,
"effects": [
"Always selects urban_massing in auto mode.",
"Defaults style to civic_classical when style is omitted."
]
}
},
"magicLevel": {
"range": [
0,
1
],
"bands": [
{
"range": [
0,
0.3
],
"meaning": "restrained/background magical character"
},
{
"range": [
0.3,
0.7
],
"meaning": "normal MAGTOPIA magical London character"
},
{
"range": [
0.7,
1
],
"meaning": "strong magical emphasis; use intentionally for special buildings"
}
],
"effects": {
"nightLighting": "default = magic_level * 0.18",
"floorStackVariation": "default = clamp(0.48 + magic_level * 0.35, 0, 1)",
"floorStackDetailDensity": "default = clamp(0.70 + magic_level * 0.25, 0, 1)",
"urbanMassingDetailDensity": "solid masses default = clamp(0.72 + magic_level * 0.25, 0, 1)"
}
},
"districtStyle": {
"meaning": "Named/shared district architecture cue. Preserve it across nearby housing instead of making every house globally unique."
},
"variationIntent": {
"meaning": "One or two high-level structural changes relative to the district family.",
"examples": [
"narrow_corner_house",
"stepped_frontage",
"hip_roof",
"corner"
],
"effects": [
"Words containing hip or corner favor a hip roof in floor_stack.",
"corner also requests a more explicit corner-facade condition."
]
},
"publicBuildingReview": "For public urban_massing, inspect actualArchitecture and architectureReview after generation. Correct one or two components with update_mass; regenerate_from_intent when the overall scheme is wrong.",
"residentialGuidance": "For residential floor_stack, read nearby buildings and district purpose, pass district_context, preserve two or three shared cues, and vary one or two structural cues."
}
},
"BuildingGameplayProfile": {
"type": "object",
"additionalProperties": false,
"required": [
"purpose",
"magic_ratio"
],
"description": "Authoritative gameplay semantics applied to every system-derived floor of this confirmed design. The server owns floor count and functional area. magic_ratio is the wizard-world share, not visual magic strength: residential creates wizard housing capacity; commercial/production/greenhouse can produce Arcane Energy and add concealment pressure.",
"properties": {
"purpose": {
"enum": [
"residential",
"commercial",
"public_service",
"production",
"greenhouse"
]
},
"magic_ratio": {
"type": "number",
"enum": [
0,
0.25,
0.5,
0.75,
1
],
"description": "Use 0 for entirely Muggle-facing space and a positive discrete value for magical use. A wizard residence needs residential plus magic_ratio > 0."
}
},
"examples": [
{
"purpose": "residential",
"magic_ratio": 0.5
},
{
"purpose": "greenhouse",
"magic_ratio": 1
}
]
},
"Decoration": {
"type": "object",
"required": [
"id",
"type",
"anchor"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"enum": [
"hanging_sign",
"semantic_grid_sign",
"facade_lamp",
"magic_lamp",
"roof_finial"
]
},
"anchor": {
"type": "string",
"description": "Use an anchor pattern returned in availableOperations"
},
"parameters": {
"type": "object",
"additionalProperties": true
}
}
},
"BuildingDesignCreateRequest": {
"type": "object",
"required": [
"generation_mode",
"site",
"intent"
],
"properties": {
"generation_mode": {
"enum": [
"auto",
"floor_stack",
"urban_massing"
],
"description": "Prefer auto. See BuildingIntent.x-agent-catalog.generationModeRules for the exact recommendation rules."
},
"site": {
"$ref": "#/components/schemas/Site"
},
"intent": {
"$ref": "#/components/schemas/BuildingIntent"
},
"gameplay_profile": {
"$ref": "#/components/schemas/BuildingGameplayProfile"
},
"requirements": {
"type": "object",
"properties": {
"preferred_floors": {
"type": "integer",
"minimum": 1,
"maximum": 8,
"description": "Optional initial floor count for floor_stack; defaults are derived from prominence."
},
"variant_id": {
"type": "string",
"description": "Optional public-building variant from the generated catalog returned by the design response."
}
}
},
"district_context": {
"type": "object",
"description": "Optional district context used to keep residential buildings coherent while varying one or two structural cues",
"additionalProperties": true,
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"purpose": {
"type": "string"
},
"style": {
"type": "string"
},
"district_style": {
"type": "string"
},
"character": {
"type": "string"
},
"preserve": {
"type": "array",
"items": {
"type": "string"
}
},
"vary": {
"type": "array",
"items": {
"type": "string"
}
},
"change": {
"type": "array",
"items": {
"type": "string"
}
},
"existing_features": {
"type": "array",
"items": {
"type": "string"
}
},
"notes": {
"type": "string"
}
}
},
"decorations": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Decoration"
}
}
}
},
"locks": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"BuildingDesignRevisionRequest": {
"type": "object",
"required": [
"expected_revision",
"operations"
],
"properties": {
"expected_revision": {
"type": "integer",
"minimum": 1
},
"operations": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"required": [
"op"
],
"properties": {
"op": {
"enum": [
"set_intent",
"regenerate_from_intent",
"set_roof",
"set_material",
"add_decoration",
"update_decoration",
"remove_decoration",
"add_floor",
"set_floor_program",
"add_mass",
"update_mass",
"remove_mass"
]
},
"decoration": {
"$ref": "#/components/schemas/Decoration"
}
},
"additionalProperties": true
}
}
}
},
"BuildingDesignConfirmRequest": {
"type": "object",
"required": [
"expected_revision"
],
"properties": {
"expected_revision": {
"type": "integer",
"minimum": 1
}
}
},
"BuildingDesignUpgradeRequest": {
"type": "object",
"description": "Accepted inputs for creating an editable upgrade design from a built voxel design. The design id and actor are server-owned and always assigned by the runtime; clients only provide the upgrade goal.",
"properties": {
"goal": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"enum": [
"add_floor",
"add_floors"
],
"description": "add_floor is the canonical operation; add_floors is accepted as an alias."
},
"count": {
"type": "integer",
"minimum": 1,
"default": 1,
"description": "Number of storeys to add to the existing building."
}
}
}
}
},
"DistrictCreateRequest": {
"type": "object",
"required": [
"expected_city_version",
"name",
"purpose",
"bounds"
],
"properties": {
"expected_city_version": {
"type": "integer",
"minimum": 0
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"purpose": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"actor_note": {
"type": "string"
},
"bounds": {
"description": "Spatial work package. The response contains a soft 24–48-cell scale reference and derived block observations; unusual or larger shapes remain legal.",
"type": "object",
"required": [
"minColumn",
"minRow",
"maxColumn",
"maxRow"
],
"properties": {
"minColumn": {
"type": "integer"
},
"minRow": {
"type": "integer"
},
"maxColumn": {
"type": "integer"
},
"maxRow": {
"type": "integer"
}
}
}
}
},
"DistrictCancelRequest": {
"type": "object",
"required": [
"expected_city_version"
],
"properties": {
"expected_city_version": {
"type": "integer",
"minimum": 0
},
"reason": {
"type": "string",
"maxLength": 160,
"description": "Why this planning context is being released; existing roads and buildings are preserved."
},
"actor_note": {
"type": "string",
"maxLength": 160
}
}
},
"SiteSearchRequest": {
"type": "object",
"required": [
"footprint"
],
"properties": {
"footprint": {
"enum": [
"1x1",
"1x2",
"1x3",
"2x1",
"2x2",
"2x3",
"3x1",
"3x2",
"3x3"
]
},
"district_id": {
"type": "string",
"description": "Use the persisted spatial layout and advisory observations of this named development district"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
}
},
"ConnectionRequest": {
"type": "object",
"required": [
"from",
"to"
],
"properties": {
"expected_city_version": {
"type": "integer",
"minimum": 0
},
"from": {
"$ref": "#/components/schemas/Endpoint"
},
"to": {
"$ref": "#/components/schemas/Endpoint"
},
"mode": {
"const": "road"
},
"actor_note": {
"type": "string"
}
}
},
"StrategyIncident": {
"type": "object",
"required": [
"id",
"building_id",
"type",
"attribute",
"dc",
"severity",
"summary",
"status"
],
"properties": {
"id": {
"type": "string"
},
"building_id": {
"type": "string"
},
"building_name": {
"type": [
"string",
"null"
]
},
"type": {
"enum": [
"investigation",
"suppression",
"cover_up"
]
},
"attribute": {
"enum": [
"investigation",
"suppression",
"coverUp"
]
},
"dc": {
"type": "integer",
"enum": [
10,
14,
18
]
},
"difficulty_tier": {
"enum": [
"normal",
"hard",
"severe"
]
},
"severity": {
"type": "integer",
"minimum": 1,
"maximum": 5
},
"exposure_at_creation": {
"type": "number"
},
"historical_risk_at_creation": {
"type": "integer",
"minimum": 0,
"maximum": 4
},
"historical_risk": {
"type": "integer",
"minimum": 0,
"maximum": 4
},
"source_risk": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"summary": {
"type": "string"
},
"status": {
"enum": [
"open",
"assigned",
"resolved",
"failed",
"escalated"
]
},
"created_at_turn": {
"type": "integer"
}
}
},
"CardDefinition": {
"type": "object",
"required": [
"card_id",
"type",
"title",
"description",
"decision_mode",
"duration",
"choice_kind",
"family",
"unique",
"free_placement",
"placement_required",
"choice_required",
"recommended_action",
"available_decision_modes",
"effect_summary",
"skip_consequence"
],
"properties": {
"card_id": {
"type": "string"
},
"type": {
"enum": [
"special_structure",
"resource",
"personnel",
"policy",
"building",
"people"
]
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"decision_mode": {
"enum": [
"immediate",
"player_place",
"delegate_to_agent"
],
"description": "player_place and delegate_to_agent are two resolution choices of the same special structure card, never two separate cards."
},
"choice_kind": {
"enum": [
"ordinary",
"special",
null
]
},
"family": {
"type": [
"string",
"null"
]
},
"unique": {
"type": "boolean"
},
"free_placement": {
"type": "boolean",
"description": "System-owned entitlement; special structures are free to place."
},
"placement_required": {
"type": "boolean"
},
"choice_required": {
"const": true,
"description": "The player must make this choice; the Agent never chooses a card."
},
"recommended_action": {
"type": "string"
},
"available_decision_modes": {
"type": "array",
"items": {
"enum": [
"immediate",
"player_place",
"delegate_to_agent"
]
}
},
"effect_summary": {
"type": "string",
"description": "Compact server-owned consequences so the choice is understandable without reading another catalog."
},
"effect_preview": {
"type": [
"object",
"null"
],
"additionalProperties": true,
"description": "Authoritative current-state projection of an immediate effect. Check projected_grant before choosing a capacity-limited population card."
},
"skip_consequence": {
"type": "string"
},
"duration": {
"oneOf": [
{
"type": "string",
"const": "instant"
},
{
"type": "object",
"properties": {
"type": {
"type": "string"
},
"turns": {
"type": "integer"
}
}
}
]
},
"structure": {
"type": "object",
"nullable": true,
"description": "System-owned placement spec for special structure cards."
},
"effect": {
"type": "object",
"additionalProperties": true
}
}
},
"CardOffer": {
"type": "object",
"required": [
"offer_id",
"turn",
"choice_kind",
"eligibility_audit",
"cards"
],
"properties": {
"offer_id": {
"type": "string"
},
"turn": {
"type": "integer"
},
"choice_kind": {
"enum": [
"ordinary",
"special"
]
},
"eligibility_audit": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"cards": {
"type": "array",
"minItems": 3,
"maxItems": 3,
"items": {
"$ref": "#/components/schemas/CardDefinition"
}
}
}
},
"CardChoice": {
"type": "object",
"required": [
"status"
],
"properties": {
"offer_id": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"pending",
"selected",
"skipped",
"resolved",
"not_applicable"
],
"description": "not_applicable is authoritative for the turn-0 bootstrap no-card state."
},
"choice_kind": {
"enum": [
"ordinary",
"special",
null
]
},
"selected_card_id": {
"type": [
"string",
"null"
]
},
"decision_mode": {
"type": [
"string",
"null"
]
},
"choice_resolved_at": {
"type": [
"string",
"null"
]
},
"card_effects": {
"type": "object",
"additionalProperties": true
}
}
},
"CardSelectRequest": {
"type": "object",
"required": [
"expected_city_version",
"offer_id",
"selected_card_id"
],
"properties": {
"expected_city_version": {
"type": "integer",
"minimum": 0
},
"offer_id": {
"type": "string",
"description": "offer_id returned by GET /cards/current"
},
"selected_card_id": {
"type": "string",
"description": "one of the offered card ids; the player may select exactly one card per turn"
},
"decision_mode": {
"enum": [
"player_place",
"delegate_to_agent"
],
"description": "required for special structure cards; must never carry effect values or balance parameters"
},
"actor_note": {
"type": "string"
}
}
},
"CardSelectResponse": {
"type": "object",
"required": [
"command_id",
"status",
"city_version_before",
"city_version_after",
"turn",
"selected_card_id"
],
"properties": {
"command_id": {
"type": "string"
},
"status": {
"const": "selected"
},
"city_version_before": {
"type": "integer"
},
"city_version_after": {
"type": "integer"
},
"turn": {
"type": "integer"
},
"selected_card_id": {
"type": "string"
},
"card_effects": {
"type": "object",
"additionalProperties": true
},
"choice": {
"$ref": "#/components/schemas/CardChoice"
}
}
},
"CardPlaceRequest": {
"type": "object",
"required": [
"expected_city_version",
"card_id"
],
"properties": {
"expected_city_version": {
"type": "integer",
"minimum": 0
},
"card_id": {
"type": "string",
"description": "the selected special structure card with a pending placement"
},
"placement_id": {
"type": "string",
"description": "stable placement id from the strategy context. Required when the city holds several pending delegated placements so an older mandate is never shadowed."
},
"lot_id": {
"type": "string",
"description": "legal lot id for the structure footprint; validated through the authoritative cell system"
},
"footprint": {
"type": "string",
"description": "defaults to the system-owned structure footprint"
},
"entrance": {
"enum": [
"north",
"east",
"south",
"west"
],
"description": "defaults to south"
},
"actor_note": {
"type": "string"
}
}
},
"CardPlaceResponse": {
"type": "object",
"required": [
"command_id",
"status",
"city_version_before",
"city_version_after",
"turn",
"building_id"
],
"properties": {
"command_id": {
"type": "string"
},
"status": {
"const": "placed"
},
"city_version_before": {
"type": "integer"
},
"city_version_after": {
"type": "integer"
},
"turn": {
"type": "integer"
},
"building_id": {
"type": "string"
},
"placement": {
"type": "object",
"additionalProperties": true
},
"choice": {
"$ref": "#/components/schemas/CardChoice"
}
}
},
"CardCancelRequest": {
"type": "object",
"required": [
"expected_city_version",
"placement_id"
],
"properties": {
"expected_city_version": {
"type": "integer",
"minimum": 0
},
"placement_id": {
"type": "string"
},
"actor_note": {
"type": "string"
}
}
},
"ActivePolicy": {
"type": "object",
"required": [
"policy_id",
"source_card_id",
"duration_type",
"duration_turns",
"remaining_turns"
],
"properties": {
"policy_id": {
"type": "string"
},
"source_card_id": {
"type": "string"
},
"started_at_turn": {
"type": "integer"
},
"duration_type": {
"enum": [
"instant",
"turns",
"until_replaced"
]
},
"duration_turns": {
"type": "integer"
},
"remaining_turns": {
"type": "integer"
},
"effects": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
}
},
"PendingPlacement": {
"type": "object",
"required": [
"placement_id",
"card_id",
"mode",
"status"
],
"properties": {
"placement_id": {
"type": "string"
},
"card_id": {
"type": "string"
},
"mode": {
"enum": [
"player_place",
"delegate_to_agent"
]
},
"status": {
"enum": [
"pending",
"deferred",
"completed",
"cancelled"
]
},
"delegated_at_turn": {
"type": "integer"
},
"card": {
"type": "object",
"additionalProperties": true
}
}
},
"StrategyCards": {
"type": "object",
"required": [
"offer",
"choice",
"active_policies",
"pending_placements"
],
"properties": {
"offer": {
"$ref": "#/components/schemas/CardOffer"
},
"choice": {
"$ref": "#/components/schemas/CardChoice"
},
"active_policies": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ActivePolicy"
}
},
"pending_placements": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PendingPlacement"
}
}
}
},
"ArcaneOfficer": {
"type": "object",
"required": [
"id",
"name",
"archetype",
"appearance_seed",
"visual_ref",
"investigation",
"suppression",
"cover_up",
"specialty",
"specialties",
"status",
"hired_at_turn",
"history"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"appearance_seed": {
"type": [
"string",
"null"
]
},
"visual_ref": {
"type": [
"string",
"null"
]
},
"archetype": {
"type": "string"
},
"investigation": {
"type": "integer",
"minimum": 0,
"maximum": 5
},
"suppression": {
"type": "integer",
"minimum": 0,
"maximum": 5
},
"cover_up": {
"type": "integer",
"minimum": 0,
"maximum": 5
},
"specialty": {
"enum": [
"residential",
"commercial",
"public_service",
"production",
"greenhouse",
null
]
},
"specialties": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"enum": [
"available",
"assigned",
"unavailable"
]
},
"hired_at_turn": {
"type": "integer"
},
"history": {
"type": "array",
"maxItems": 50,
"items": {
"$ref": "#/components/schemas/ArcaneOfficerHistoryEntry"
}
}
}
},
"ArcaneOfficerHistoryEntry": {
"type": "object",
"additionalProperties": false,
"required": [
"turn",
"incident_id",
"building_id",
"source_purpose",
"attribute",
"outcome",
"growth_roll",
"growth_chance",
"before",
"after",
"gained"
],
"properties": {
"turn": {
"type": "integer"
},
"incident_id": {
"type": "string"
},
"building_id": {
"type": "string"
},
"source_purpose": {
"type": [
"string",
"null"
]
},
"attribute": {
"type": "string"
},
"outcome": {
"type": "string"
},
"growth_roll": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"growth_chance": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"before": {
"type": "integer",
"minimum": 0,
"maximum": 5
},
"after": {
"type": "integer",
"minimum": 0,
"maximum": 5
},
"gained": {
"type": "integer",
"minimum": 0,
"maximum": 1
}
}
},
"ArcaneOfficerCandidate": {
"type": "object",
"additionalProperties": false,
"required": [
"candidate_id",
"identity",
"cost_coins",
"window"
],
"properties": {
"candidate_id": {
"type": "string"
},
"identity": {
"$ref": "#/components/schemas/ArcaneOfficer"
},
"cost_coins": {
"type": "integer",
"minimum": 120,
"maximum": 180
},
"window": {
"type": "integer",
"minimum": 0
}
}
},
"ArcaneOfficerRecruitment": {
"type": "object",
"additionalProperties": false,
"required": [
"unlocked",
"status",
"capacity",
"roster_size",
"config",
"pool_window",
"candidates"
],
"properties": {
"unlocked": {
"type": "boolean"
},
"status": {
"enum": [
"available",
"locked",
"capacity_reached",
"insufficient_coins"
]
},
"capacity": {
"type": "integer",
"minimum": 0,
"description": "A governance facility supplies the first slot; each capacity_divisor wizard residents add one more."
},
"roster_size": {
"type": "integer",
"minimum": 0
},
"next_capacity_at_wizards": {
"type": "integer",
"minimum": 0
},
"config": {
"type": "object",
"additionalProperties": false,
"required": [
"refresh_interval_turns",
"candidate_count",
"hire_cost_coins",
"maintenance_coins_per_turn",
"capacity_divisor",
"growth_chance",
"critical_growth_chance",
"attribute_cap"
],
"properties": {
"refresh_interval_turns": {
"type": "integer"
},
"candidate_count": {
"type": "integer",
"minimum": 2,
"maximum": 3
},
"hire_cost_coins": {
"type": "integer",
"minimum": 120,
"maximum": 180
},
"maintenance_coins_per_turn": {
"type": "integer",
"minimum": 8,
"maximum": 12
},
"capacity_divisor": {
"type": "integer"
},
"growth_chance": {
"type": "number"
},
"critical_growth_chance": {
"type": "number"
},
"attribute_cap": {
"type": "integer",
"maximum": 5
}
}
},
"pool_window": {
"type": [
"integer",
"null"
]
},
"candidates": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ArcaneOfficerCandidate"
}
}
}
},
"OfficerRecruitmentRequest": {
"type": "object",
"additionalProperties": false,
"required": [
"candidate_id",
"expected_city_version"
],
"properties": {
"candidate_id": {
"type": "string",
"minLength": 1
},
"expected_city_version": {
"type": "integer",
"minimum": 0
},
"actor_note": {
"type": "string"
}
}
},
"OfficerRecruitmentResponse": {
"type": "object",
"additionalProperties": true,
"required": [
"command_id",
"status",
"city_version_before",
"city_version_after",
"officer",
"cost_coins",
"strategy"
],
"properties": {
"command_id": {
"type": "string"
},
"status": {
"const": "accepted"
},
"city_version_before": {
"type": "integer"
},
"city_version_after": {
"type": "integer"
},
"officer": {
"$ref": "#/components/schemas/ArcaneOfficer"
},
"cost_coins": {
"type": "integer"
},
"strategy": {
"$ref": "#/components/schemas/StrategyPayload"
},
"idempotent_replay": {
"type": "boolean"
}
}
},
"StrategyAssignment": {
"type": "object",
"description": "A dispatch instruction. Only these fields are accepted; the system owns every numeric balance parameter.",
"required": [
"incident_id",
"arcane_officer_id"
],
"properties": {
"incident_id": {
"type": "string"
},
"arcane_officer_id": {
"type": "string"
},
"rationale": {
"type": "string",
"description": "Optional advisory dispatch reason. Never affects the roll, outcome, or balance."
}
}
},
"StrategyAssignmentsRequest": {
"type": "object",
"required": [
"expected_city_version",
"assignments"
],
"properties": {
"expected_city_version": {
"type": "integer",
"minimum": 0
},
"assignments": {
"type": "array",
"maxItems": 20,
"items": {
"$ref": "#/components/schemas/StrategyAssignment"
}
},
"actor_note": {
"type": "string"
}
}
},
"StrategyResolveRequest": {
"type": "object",
"required": [
"expected_city_version"
],
"properties": {
"expected_city_version": {
"type": "integer",
"minimum": 0
},
"actor_note": {
"type": "string"
}
}
},
"TurnFacts": {
"type": "object",
"description": "Immutable system-generated settlement record. Agents read rolls, outcomes, and state changes here; they never author them.",
"required": [
"turn",
"turnKind",
"bootstrapProgress",
"resourceDelta",
"netResourceDelta",
"resourceBefore",
"resourceAfter",
"officerMaintenance",
"populationDelta",
"populationBefore",
"populationAfter",
"publicService",
"buildingsStarted",
"buildingsCompleted",
"buildingFactRefs",
"constructionRefs",
"exposureChanges",
"incidents",
"incidentRolls",
"unaddressedIncidents",
"historicalRiskChanges",
"assignments",
"rolls",
"outcomes",
"sealedBuildings",
"nextRisks",
"choiceKind",
"offerChoiceKind",
"specialCadence",
"eligibilityAudit"
],
"properties": {
"turn": {
"type": "integer"
},
"turnKind": {
"enum": [
"bootstrap",
"normal"
]
},
"choiceKind": {
"enum": [
"ordinary",
"special",
null
]
},
"offerChoiceKind": {
"enum": [
"ordinary",
"special",
null
]
},
"specialCadence": {
"type": "boolean"
},
"eligibilityAudit": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"bootstrapProgress": {
"oneOf": [
{
"$ref": "#/components/schemas/BootstrapProgress"
},
{
"type": "null"
}
]
},
"wallClock": {
"type": "object",
"nullable": true,
"additionalProperties": true
},
"resourceDelta": {
"type": "object",
"properties": {
"coins": {
"type": "integer",
"minimum": 0
},
"arcaneEnergy": {
"type": "number",
"minimum": 0
}
},
"required": [
"coins",
"arcaneEnergy"
],
"additionalProperties": false
},
"netResourceDelta": {
"type": "object",
"properties": {
"coins": {
"type": "integer"
},
"arcaneEnergy": {
"type": "number"
}
},
"required": [
"coins",
"arcaneEnergy"
],
"additionalProperties": false
},
"resourceBefore": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"resourceAfter": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"officerMaintenance": {
"type": "object",
"additionalProperties": false,
"required": [
"count",
"rate",
"total",
"charged",
"unpaid"
],
"properties": {
"count": {
"type": "integer"
},
"rate": {
"type": "integer"
},
"total": {
"type": "integer"
},
"charged": {
"type": "integer"
},
"unpaid": {
"type": "integer"
}
}
},
"populationDelta": {
"type": "object",
"additionalProperties": true
},
"populationBefore": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"populationAfter": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"publicService": {
"type": "object",
"description": "System-derived spatial public-service coverage and supported population target for this settlement.",
"properties": {
"radius": {
"type": "number",
"minimum": 0
},
"residentialFunctionalArea": {
"type": "number",
"minimum": 0
},
"residentialCapacity": {
"type": "number",
"minimum": 0
},
"serviceCapacity": {
"type": "number",
"minimum": 0
},
"serviceCoverage": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"supportedOccupancy": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"supportedTarget": {
"type": "object",
"additionalProperties": true
},
"migrationRate": {
"type": "object",
"additionalProperties": true
},
"outboundMigrationRate": {
"type": "object",
"properties": {
"muggles": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"wizards": {
"type": "number",
"minimum": 0,
"maximum": 1
}
},
"required": [
"muggles",
"wizards"
],
"additionalProperties": false
},
"details": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
},
"required": [
"radius",
"serviceCoverage",
"supportedTarget",
"migrationRate",
"outboundMigrationRate"
]
},
"exposureChanges": {
"type": "object",
"additionalProperties": true
},
"incidents": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StrategyIncident"
}
},
"incidentRolls": {
"type": "array",
"description": "System-owned independent threshold roll for every eligible canonical MagicLoad building.",
"items": {
"type": "object",
"required": [
"buildingId",
"finalIncidentChance",
"thresholdRoll",
"hit",
"sourcePurpose",
"purposeWeights"
],
"properties": {
"buildingId": {
"type": "string"
},
"finalIncidentChance": {
"type": "number"
},
"thresholdRoll": {
"type": "number"
},
"hit": {
"type": "boolean"
},
"magicLoad": {
"type": "number"
},
"baseRisk": {
"type": "number"
},
"spatialModifier": {
"type": "number"
},
"historicalRisk": {
"type": "integer"
},
"sourcePurpose": {
"type": [
"string",
"null"
]
},
"purposeWeights": {
"type": "object",
"additionalProperties": {
"type": "number"
}
}
}
}
},
"historicalRiskChanges": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"buildingId": {
"type": "string"
},
"before": {
"type": "integer"
},
"after": {
"type": "integer"
},
"delta": {
"type": "integer"
},
"incidentIds": {
"type": "array",
"items": {
"type": "string"
}
},
"sealed": {
"type": "boolean"
}
}
}
},
"unaddressedIncidents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"incidentId": {
"type": "string"
},
"buildingId": {
"type": "string"
},
"type": {
"type": "string"
},
"severity": {
"type": "number"
},
"status": {
"const": "failed"
},
"outcome": {
"const": "failure"
},
"resolution": {
"const": "unaddressed"
},
"historicalRiskBefore": {
"type": "integer"
},
"historicalRiskAfter": {
"type": "integer"
},
"historicalRiskDelta": {
"type": "integer"
},
"sealed": {
"type": "boolean"
},
"createdAtTurn": {
"type": "number"
}
}
},
"description": "Incidents left unassigned are settled once through the conservative failure path and recorded as failed."
},
"assignments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"incidentId": {
"type": "string"
},
"arcaneOfficerId": {
"type": "string"
}
}
}
},
"rolls": {
"type": "array",
"items": {
"type": "object",
"properties": {
"incidentId": {
"type": "string"
},
"arcaneOfficerId": {
"type": "string"
},
"attribute": {
"type": "string"
},
"rawRoll": {
"type": "integer",
"minimum": 1,
"maximum": 20
},
"attributeValue": {
"type": "integer"
},
"specialtyBonus": {
"type": "integer"
},
"otherModifiers": {
"type": "integer"
},
"total": {
"type": "integer"
},
"dc": {
"type": "integer",
"enum": [
10,
14,
18
]
},
"margin": {
"type": "integer"
},
"outcome": {
"enum": [
"critical_success",
"success",
"failure",
"critical_failure"
]
},
"historicalRiskBefore": {
"type": "integer"
},
"historicalRiskAfter": {
"type": "integer"
},
"historicalRiskDelta": {
"type": "integer"
},
"sealed": {
"type": "boolean"
}
}
}
},
"outcomes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"incidentId": {
"type": "string"
},
"buildingId": {
"type": "string"
},
"arcaneOfficerId": {
"type": "string"
},
"outcome": {
"enum": [
"critical_success",
"success",
"failure",
"critical_failure"
]
},
"exposureDelta": {
"type": "number"
},
"historicalRiskBefore": {
"type": "integer"
},
"historicalRiskAfter": {
"type": "integer"
},
"historicalRiskDelta": {
"type": "integer"
},
"sealed": {
"type": "boolean"
},
"resolution": {
"enum": [
"assigned",
"unaddressed"
]
},
"incidentStatus": {
"type": "string"
},
"arcaneOfficerStatus": {
"type": "string"
},
"growth": {
"type": "object",
"additionalProperties": false,
"required": [
"attribute",
"roll",
"chance",
"before",
"after",
"gained"
],
"properties": {
"attribute": {
"type": "string"
},
"roll": {
"type": "number"
},
"chance": {
"type": "number"
},
"before": {
"type": "integer"
},
"after": {
"type": "integer"
},
"gained": {
"type": "integer"
}
}
}
}
}
},
"sealedBuildings": {
"type": "array",
"items": {
"type": "string"
}
},
"buildingsStarted": {
"type": "array",
"items": {
"type": "string"
},
"description": "System-derived ids of authoritative buildings first represented by accepted construction events in this turn."
},
"buildingsCompleted": {
"type": "array",
"items": {
"type": "string"
},
"description": "System-derived ids of authoritative buildings completed by accepted construction events in this turn."
},
"buildingFactRefs": {
"type": "array",
"items": {
"type": "string"
}
},
"constructionRefs": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"factRef",
"kind",
"reservationId",
"proposalId",
"buildingId",
"eventType"
],
"properties": {
"factRef": {
"type": "string"
},
"kind": {
"enum": [
"reservation",
"completion"
]
},
"reservationId": {
"type": [
"string",
"null"
]
},
"proposalId": {
"type": [
"string",
"null"
]
},
"buildingId": {
"type": [
"string",
"null"
]
},
"eventType": {
"type": "string"
}
}
}
},
"nextRisks": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
}
},
"BootstrapProgress": {
"type": "object",
"additionalProperties": false,
"required": [
"gatewayConnected",
"gatewayNodeId",
"gatewayCellId",
"gatewayLocation",
"roadsConnected",
"roadsConnectedCount",
"buildingsStarted",
"buildingsCompleted",
"residentialBuildings",
"commercialBuildings",
"publicServiceBuildings",
"totalBuildings",
"milestones",
"recommendedBeforeResolve",
"missingRecommendedMilestones",
"readyForMeaningfulFirstResolve"
],
"properties": {
"gatewayConnected": {
"type": "boolean"
},
"gatewayNodeId": {
"type": [
"string",
"null"
]
},
"gatewayCellId": {
"type": [
"string",
"null"
]
},
"gatewayLocation": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"required": [
"cell_id",
"column",
"row"
],
"properties": {
"cell_id": {
"type": "string"
},
"column": {
"type": "integer"
},
"row": {
"type": "integer"
},
"center": {
"type": "object",
"additionalProperties": true
}
}
},
{
"type": "null"
}
]
},
"roadsConnected": {
"type": "array",
"items": {
"type": "string"
}
},
"roadsConnectedCount": {
"type": "integer",
"minimum": 0
},
"buildingsStarted": {
"type": "array",
"items": {
"type": "string"
}
},
"buildingsCompleted": {
"type": "array",
"items": {
"type": "string"
}
},
"residentialBuildings": {
"type": "array",
"items": {
"type": "string"
}
},
"commercialBuildings": {
"type": "array",
"items": {
"type": "string"
}
},
"publicServiceBuildings": {
"type": "array",
"items": {
"type": "string"
}
},
"totalBuildings": {
"type": "integer",
"minimum": 0
},
"milestones": {
"type": "object",
"additionalProperties": false,
"required": [
"gateway",
"road",
"housing",
"income",
"publicService"
],
"properties": {
"gateway": {
"type": "boolean"
},
"road": {
"type": "boolean"
},
"housing": {
"type": "boolean"
},
"income": {
"type": "boolean"
},
"publicService": {
"type": "boolean"
}
}
},
"recommendedBeforeResolve": {
"type": "array",
"items": {
"enum": [
"gateway",
"housing",
"income"
]
}
},
"missingRecommendedMilestones": {
"type": "array",
"items": {
"enum": [
"gateway",
"housing",
"income"
]
}
},
"readyForMeaningfulFirstResolve": {
"type": "boolean"
}
}
},
"BootstrapState": {
"type": "object",
"additionalProperties": false,
"required": [
"progress",
"guidance"
],
"properties": {
"progress": {
"$ref": "#/components/schemas/BootstrapProgress"
},
"guidance": {
"type": "string"
}
}
},
"StrategyPayload": {
"type": "object",
"required": [
"turn_kind",
"bootstrap",
"incidents",
"arcane_officers",
"arcane_officer_recruitment",
"pending_assignments",
"cards"
],
"properties": {
"turn_kind": {
"enum": [
"bootstrap",
"normal"
]
},
"bootstrap": {
"oneOf": [
{
"$ref": "#/components/schemas/BootstrapState"
},
{
"type": "null"
}
]
},
"incidents": {
"type": "array",
"items": {
"$ref": "#/components/schemas/StrategyIncident"
}
},
"arcane_officers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ArcaneOfficer"
}
},
"arcane_officer_recruitment": {
"$ref": "#/components/schemas/ArcaneOfficerRecruitment"
},
"pending_assignments": {
"type": "array",
"items": {
"type": "object"
}
},
"cards": {
"$ref": "#/components/schemas/StrategyCards"
}
}
},
"StrategyContext": {
"type": "object",
"required": [
"city_id",
"city_version",
"turn",
"turn_kind",
"turn_status",
"bootstrap",
"strategy"
],
"properties": {
"city_id": {
"type": "string"
},
"city_version": {
"type": "integer"
},
"turn": {
"type": "integer"
},
"turn_kind": {
"enum": [
"bootstrap",
"normal"
]
},
"turn_status": {
"type": "string"
},
"bootstrap": {
"oneOf": [
{
"$ref": "#/components/schemas/BootstrapState"
},
{
"type": "null"
}
]
},
"turn_opened_at": {
"type": [
"string",
"null"
]
},
"turn_deadline_at": {
"type": [
"string",
"null"
],
"description": "Deprecated legacy field, always null. Turns no longer have a deadline that auto-settles; it is kept only for API compatibility and never drives settlement."
},
"next_turn_unlock_at": {
"type": [
"string",
"null"
],
"description": "Server-owned cooldown gate. While the current turn is active it is the earliest wall-clock time the Agent may resolve the turn (POST /strategy/resolve is rejected with TURN_NOT_UNLOCKED before it); once the turn is settled it is the earliest time the next turn may open. Agents cannot change it."
},
"settled_by": {
"type": [
"string",
"null"
],
"description": "Which authority settled the last turn: agent, or deadline (historical only; deadline settlement no longer exists)."
},
"gameplay_guidance": {
"type": "array",
"items": {
"type": "string"
},
"description": "Short progressive-disclosure hints (1-3) for the current context, derived from card/placement/incident/turn-lock state. Advisory only; the authoritative contract is the playbook."
},
"playbook_url": {
"type": "string",
"description": "Stable URL of the authoritative MAGTOPIA Agent Playbook."
},
"agent_turn_plan": {
"type": "object",
"additionalProperties": true,
"description": "A compact current-version next action intended to minimize exploratory calls and stale retries."
},
"strategy": {
"$ref": "#/components/schemas/StrategyPayload",
"properties": {
"incidents": {
"type": "array"
},
"arcane_officers": {
"type": "array"
},
"arcane_officer_recruitment": {
"$ref": "#/components/schemas/ArcaneOfficerRecruitment"
},
"pending_assignments": {
"type": "array"
},
"cards": {
"$ref": "#/components/schemas/StrategyCards"
}
}
},
"last_turn_facts": {
"oneOf": [
{
"$ref": "#/components/schemas/TurnFacts"
},
{
"type": "null"
}
]
}
}
},
"StrategyResolveResponse": {
"type": "object",
"required": [
"command_id",
"status",
"city_version_before",
"city_version_after",
"turn",
"facts",
"strategy"
],
"properties": {
"command_id": {
"type": "string"
},
"status": {
"const": "resolved"
},
"city_version_before": {
"type": "integer"
},
"city_version_after": {
"type": "integer"
},
"turn": {
"type": "integer"
},
"facts": {
"$ref": "#/components/schemas/TurnFacts"
},
"strategy": {
"$ref": "#/components/schemas/StrategyPayload",
"properties": {
"cards": {
"$ref": "#/components/schemas/StrategyCards"
}
}
}
}
},
"ReportContext": {
"type": "object",
"description": "SYSTEM-owned immutable newspaper source for one resolved turn. A deterministic projection of the frozen TurnFacts plus read-only city metadata. Never contains prose and never recomputes gameplay. The Agent edits an OwlReport from it and references facts through factRefs.",
"required": [
"schemaVersion",
"cityId",
"turn",
"turnKind",
"choiceKind",
"offerChoiceKind",
"specialCadence",
"eligibilityAudit",
"bootstrapProgress",
"worldDay",
"factsDigest",
"settlement",
"resourceDelta",
"resources",
"populationDelta",
"population",
"publicService",
"buildingsStarted",
"buildingsCompleted",
"buildingFactRefs",
"constructionRefs",
"incidents",
"incidentRolls",
"historicalRiskChanges",
"factRefs"
],
"properties": {
"schemaVersion": {
"type": "integer"
},
"cityId": {
"type": "string"
},
"turn": {
"type": "integer"
},
"turnKind": {
"enum": [
"bootstrap",
"normal"
]
},
"choiceKind": {
"enum": [
"ordinary",
"special",
null
]
},
"offerChoiceKind": {
"enum": [
"ordinary",
"special",
null
]
},
"specialCadence": {
"type": "boolean"
},
"eligibilityAudit": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"bootstrapProgress": {
"oneOf": [
{
"$ref": "#/components/schemas/BootstrapProgress"
},
{
"type": "null"
}
]
},
"worldDay": {
"type": "integer",
"description": "One resolved turn is one city day; worldDay equals turn."
},
"factsDigest": {
"type": "string",
"description": "Stable digest of the frozen TurnFacts; an OwlReport must bind to it."
},
"settlement": {
"type": "object",
"properties": {
"settledBy": {
"enum": [
"agent",
"deadline",
null
]
},
"openedAt": {
"type": [
"string",
"null"
]
},
"resolvedAt": {
"type": [
"string",
"null"
]
},
"turnDeadlineAt": {
"type": [
"string",
"null"
]
},
"nextTurnUnlockAt": {
"type": [
"string",
"null"
]
}
}
},
"resourceDelta": {
"type": "object",
"properties": {
"factRef": {
"type": "string"
},
"coins": {
"type": "integer",
"minimum": 0
},
"arcaneEnergy": {
"type": "number",
"minimum": 0
}
},
"required": [
"coins",
"arcaneEnergy"
]
},
"resources": {
"type": "object",
"properties": {
"factRef": {
"type": "string"
},
"before": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"after": {
"type": [
"object",
"null"
],
"additionalProperties": true
}
},
"required": [
"factRef",
"before",
"after"
]
},
"populationDelta": {
"type": "object",
"additionalProperties": true
},
"population": {
"type": "object",
"properties": {
"factRef": {
"type": "string"
},
"before": {
"type": [
"object",
"null"
],
"additionalProperties": true
},
"after": {
"type": [
"object",
"null"
],
"additionalProperties": true
}
},
"required": [
"factRef",
"before",
"after"
]
},
"publicService": {
"type": "object",
"additionalProperties": true
},
"buildingsStarted": {
"type": "array",
"items": {
"type": "object",
"properties": {
"factRef": {
"type": "string"
},
"buildingId": {
"type": "string"
},
"name": {
"type": "string"
},
"archetype": {
"type": [
"string",
"null"
]
},
"purpose": {
"type": [
"string",
"null"
]
}
}
}
},
"buildingsCompleted": {
"type": "array",
"items": {
"type": "object",
"properties": {
"factRef": {
"type": "string"
},
"buildingId": {
"type": "string"
},
"name": {
"type": "string"
},
"archetype": {
"type": [
"string",
"null"
]
},
"purpose": {
"type": [
"string",
"null"
]
}
}
}
},
"buildingFactRefs": {
"type": "array",
"items": {
"type": "string"
}
},
"constructionRefs": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"factRef",
"kind",
"reservationId",
"proposalId",
"buildingId",
"eventType"
],
"properties": {
"factRef": {
"type": "string"
},
"kind": {
"enum": [
"reservation",
"completion"
]
},
"reservationId": {
"type": [
"string",
"null"
]
},
"proposalId": {
"type": [
"string",
"null"
]
},
"buildingId": {
"type": [
"string",
"null"
]
},
"eventType": {
"type": "string"
}
}
}
},
"exposureChanges": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"factRef": {
"type": "string"
},
"buildingId": {
"type": "string"
},
"name": {
"type": "string"
},
"from": {
"type": "number"
},
"to": {
"type": "number"
},
"delta": {
"type": "number"
},
"pressure": {
"type": "number"
},
"concealment": {
"type": "number"
},
"sealed": {
"type": "boolean"
}
}
}
},
"incidents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"factRef": {
"type": "string"
},
"id": {
"type": "string"
},
"buildingId": {
"type": "string"
},
"buildingName": {
"type": "string"
},
"type": {
"type": "string"
},
"dc": {
"type": "number",
"enum": [
10,
14,
18
]
},
"severity": {
"type": "number"
},
"summary": {
"type": "string"
},
"status": {
"type": "string"
},
"createdAtTurn": {
"type": "number"
}
}
}
},
"incidentRolls": {
"type": "array",
"items": {
"type": "object",
"properties": {
"buildingId": {
"type": "string"
},
"finalIncidentChance": {
"type": "number"
},
"thresholdRoll": {
"type": "number"
},
"hit": {
"type": "boolean"
},
"sourcePurpose": {
"type": [
"string",
"null"
]
},
"purposeWeights": {
"type": "object",
"additionalProperties": {
"type": "number"
}
}
}
}
},
"historicalRiskChanges": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"buildingId": {
"type": "string"
},
"before": {
"type": "integer"
},
"after": {
"type": "integer"
},
"delta": {
"type": "integer"
},
"incidentIds": {
"type": "array",
"items": {
"type": "string"
}
},
"sealed": {
"type": "boolean"
}
}
}
},
"unresolvedIncidents": {
"type": "array",
"items": {
"type": "object"
}
},
"unaddressedIncidents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"factRef": {
"type": "string"
},
"incidentId": {
"type": "string"
},
"buildingId": {
"type": "string"
},
"buildingName": {
"type": "string"
},
"type": {
"type": "string"
},
"severity": {
"type": "number"
},
"status": {
"const": "failed"
},
"outcome": {
"const": "failure"
},
"historicalRiskBefore": {
"type": "integer"
},
"historicalRiskAfter": {
"type": "integer"
},
"historicalRiskDelta": {
"type": "integer"
},
"sealed": {
"type": "boolean"
},
"createdAtTurn": {
"type": "number"
}
}
}
},
"assignments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"factRef": {
"type": "string"
},
"incidentId": {
"type": "string"
},
"arcaneOfficerId": {
"type": "string"
},
"arcaneOfficerName": {
"type": "string"
},
"rationale": {
"type": [
"string",
"null"
]
}
}
}
},
"rolls": {
"type": "array",
"items": {
"type": "object",
"properties": {
"factRef": {
"type": "string"
},
"incidentId": {
"type": "string"
},
"arcaneOfficerId": {
"type": "string"
},
"arcaneOfficerName": {
"type": "string"
},
"attribute": {
"type": "string"
},
"rawRoll": {
"type": "integer",
"minimum": 1,
"maximum": 20
},
"attributeValue": {
"type": "integer"
},
"specialtyBonus": {
"type": "integer"
},
"otherModifiers": {
"type": "integer"
},
"total": {
"type": "integer"
},
"dc": {
"type": "integer",
"enum": [
10,
14,
18
]
},
"margin": {
"type": "integer"
},
"outcome": {
"type": "string"
},
"historicalRiskBefore": {
"type": "integer"
},
"historicalRiskAfter": {
"type": "integer"
},
"historicalRiskDelta": {
"type": "integer"
},
"sealed": {
"type": "boolean"
}
}
}
},
"outcomes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"factRef": {
"type": "string"
},
"incidentId": {
"type": "string"
},
"buildingId": {
"type": "string"
},
"arcaneOfficerId": {
"type": "string"
},
"arcaneOfficerName": {
"type": "string"
},
"outcome": {
"type": "string"
},
"exposureDelta": {
"type": "number"
},
"historicalRiskBefore": {
"type": "integer"
},
"historicalRiskAfter": {
"type": "integer"
},
"historicalRiskDelta": {
"type": "integer"
},
"sealed": {
"type": "boolean"
},
"resolution": {
"enum": [
"assigned",
"unaddressed"
]
},
"incidentStatus": {
"type": "string"
},
"arcaneOfficerStatus": {
"type": "string"
}
}
}
},
"sealedBuildings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"factRef": {
"type": "string"
},
"buildingId": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
},
"nextRisks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"factRef": {
"type": "string"
},
"buildingId": {
"type": "string"
},
"name": {
"type": "string"
},
"exposure": {
"type": "number"
},
"pressure": {
"type": "number"
},
"concealment": {
"type": "number"
}
}
}
},
"card": {
"type": "object",
"description": "Card and policy facts projected strictly from the frozen TurnFacts of this turn.",
"required": [
"offerId",
"turn",
"choiceKind",
"offerChoiceKind",
"specialCadence",
"eligibilityAudit",
"offeredCards",
"choice",
"policy",
"placement"
],
"properties": {
"factRef": {
"type": "string"
},
"offerId": {
"type": [
"string",
"null"
]
},
"turn": {
"type": "integer"
},
"choiceKind": {
"enum": [
"ordinary",
"special",
null
]
},
"offerChoiceKind": {
"enum": [
"ordinary",
"special",
null
]
},
"specialCadence": {
"type": "boolean"
},
"eligibilityAudit": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"offeredCards": {
"type": "array",
"items": {
"type": "object",
"properties": {
"cardId": {
"type": "string"
},
"type": {
"type": [
"string",
"null"
]
},
"title": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
},
"decisionMode": {
"type": [
"string",
"null"
]
}
}
}
},
"choice": {
"type": "object",
"properties": {
"factRef": {
"type": "string"
},
"status": {
"type": "string"
},
"selectedCardId": {
"type": [
"string",
"null"
]
},
"selectedCardTitle": {
"type": [
"string",
"null"
]
},
"choiceResolvedAt": {
"type": [
"string",
"null"
]
},
"cardEffects": {
"type": "object"
}
}
},
"policy": {
"type": "object",
"properties": {
"factRef": {
"type": "string"
},
"started": {
"type": "array",
"items": {
"type": "string"
}
},
"refreshed": {
"type": "array",
"items": {
"type": "string"
}
},
"expired": {
"type": "array",
"items": {
"type": "string"
}
},
"active": {
"type": "array",
"items": {
"type": "object",
"properties": {
"factRef": {
"type": "string"
},
"policyId": {
"type": "string"
},
"event": {
"type": "string"
}
}
}
}
}
},
"placement": {
"type": "object",
"properties": {
"factRef": {
"type": "string"
},
"mandate": {
"type": [
"object",
"null"
],
"properties": {
"cardId": {
"type": "string"
},
"mode": {
"type": "string"
},
"status": {
"type": "string"
},
"placementId": {
"type": "string"
}
}
},
"completed": {
"type": "array",
"items": {
"type": "object",
"properties": {
"placementId": {
"type": "string"
},
"cardId": {
"type": "string"
},
"buildingId": {
"type": "string"
},
"mode": {
"type": "string"
},
"cardTitle": {
"type": [
"string",
"null"
]
}
}
},
"description": "Attributed completions: each entry ties a completed mandate to its placement, card, and building so the Owl Daily never misattributes an older delegated completion to the current selection."
}
}
}
}
},
"factRefs": {
"type": "array",
"items": {
"type": "string"
},
"description": "Every stable fact ref valid for this turn's ReportContext."
}
}
},
"OwlReportMasthead": {
"type": "object",
"required": [
"title"
],
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"subtitle": {
"type": "string",
"maxLength": 200
}
}
},
"OwlReportArticle": {
"type": "object",
"required": [
"id",
"headline",
"body"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 80,
"description": "Stable author-chosen id, unique within the edition."
},
"headline": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"dek": {
"type": "string",
"maxLength": 400
},
"body": {
"type": "string",
"minLength": 1,
"maxLength": 12000
},
"category": {
"type": "string",
"maxLength": 60,
"description": "Suggested: development, exposure, arcane_officer, population, economy, community, other. Any short label is accepted."
},
"importance": {
"enum": [
"front_page",
"secondary",
"brief"
]
},
"relatedFactRefs": {
"type": "array",
"maxItems": 40,
"items": {
"type": "string"
},
"description": "Stable fact refs from this turn's ReportContext that this article is based on. Unknown refs are rejected."
}
}
},
"OwlReportBrief": {
"type": "object",
"required": [
"id",
"text"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 2000
},
"category": {
"type": "string",
"maxLength": 60
},
"relatedFactRefs": {
"type": "array",
"maxItems": 40,
"items": {
"type": "string"
}
}
}
},
"OwlReportActionBoxEntry": {
"type": "object",
"description": "A featured Arcane Officer action. The Agent selects which incident to highlight and writes the reason; roll/outcome/consequence are rendered from the referenced system fact refs, never authored.",
"required": [
"id",
"incidentRef"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"incidentRef": {
"type": "string",
"description": "A fact-incident-* ref from this turn's ReportContext."
},
"factRefs": {
"type": "array",
"maxItems": 40,
"items": {
"type": "string"
},
"description": "System facts surfaced by the box, for example fact-roll-* and fact-outcome-* refs."
},
"reason": {
"type": "string",
"maxLength": 2000,
"description": "Authored dispatch explanation. The frozen assignment rationale stays authoritative in the ReportContext."
}
}
},
"OwlReportTomorrowWatchEntry": {
"type": "object",
"required": [
"id",
"text"
],
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"factRefs": {
"type": "array",
"maxItems": 40,
"items": {
"type": "string"
},
"description": "Unresolved or risky facts this plan responds to, e.g. fact-unaddressed-* or fact-risk-* refs."
}
}
},
"OwlReport": {
"type": "object",
"description": "AGENT-owned newspaper composition edited from a ReportContext. The Agent owns news value and narration; every gameplay value it mentions must be referenced through a fact ref rather than re-authored.",
"required": [
"masthead",
"edition",
"headline",
"lead",
"articles",
"briefs"
],
"properties": {
"schemaVersion": {
"type": "integer"
},
"masthead": {
"$ref": "#/components/schemas/OwlReportMasthead"
},
"edition": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"headline": {
"type": "string",
"minLength": 1,
"maxLength": 240
},
"subheadline": {
"type": "string",
"maxLength": 320
},
"lead": {
"type": "string",
"minLength": 1,
"maxLength": 4000
},
"articles": {
"type": "array",
"maxItems": 20,
"items": {
"$ref": "#/components/schemas/OwlReportArticle"
}
},
"briefs": {
"type": "array",
"maxItems": 40,
"items": {
"$ref": "#/components/schemas/OwlReportBrief"
}
},
"actionBox": {
"type": "array",
"maxItems": 10,
"items": {
"$ref": "#/components/schemas/OwlReportActionBoxEntry"
}
},
"tomorrowWatch": {
"type": "array",
"maxItems": 10,
"items": {
"$ref": "#/components/schemas/OwlReportTomorrowWatchEntry"
}
}
}
},
"OwlReportSubmitRequest": {
"type": "object",
"required": [
"turn",
"facts_digest",
"report"
],
"properties": {
"turn": {
"type": "integer",
"minimum": 1,
"description": "The resolved turn this edition reports on."
},
"facts_digest": {
"type": "string",
"description": "factsDigest returned by GET /report-context for this turn. A stale digest is rejected."
},
"report": {
"$ref": "#/components/schemas/OwlReport"
}
}
},
"OwlReportResponse": {
"type": "object",
"required": [
"report_id",
"city_id",
"turn",
"facts_digest",
"status",
"edition",
"report"
],
"properties": {
"report_id": {
"type": "string"
},
"city_id": {
"type": "string"
},
"turn": {
"type": "integer"
},
"facts_digest": {
"type": "string"
},
"status": {
"const": "published"
},
"edition": {
"type": "string"
},
"report": {
"$ref": "#/components/schemas/OwlReport"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"idempotent_replay": {
"type": "boolean",
"description": "true when an identical Idempotency-Key submission replays the original published report."
}
}
},
"OwlReportSummary": {
"type": "object",
"required": [
"report_id",
"city_id",
"turn",
"facts_digest",
"status",
"edition",
"headline"
],
"properties": {
"report_id": {
"type": "string"
},
"city_id": {
"type": "string"
},
"turn": {
"type": "integer"
},
"facts_digest": {
"type": "string"
},
"status": {
"const": "published"
},
"edition": {
"type": "string"
},
"masthead_title": {
"type": [
"string",
"null"
]
},
"headline": {
"type": "string"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
}
}
},
"CityDayPresentation": {
"type": "object",
"description": "Pure presentation projection of the authoritative turn/workflow state. Visual time-of-day is an output of workflow, never a second simulation clock or realtime economy.",
"required": [
"city_id",
"city_version",
"phase",
"turn",
"turnKind",
"turnStatus",
"settled",
"bootstrap",
"report",
"card",
"agent",
"incident"
],
"properties": {
"city_id": {
"type": "string"
},
"city_version": {
"type": "integer"
},
"phase": {
"enum": [
"dawn",
"early_morning",
"morning",
"day",
"night"
]
},
"turn": {
"type": "integer"
},
"turnKind": {
"enum": [
"bootstrap",
"normal"
]
},
"turnStatus": {
"type": "string"
},
"settled": {
"type": "boolean"
},
"bootstrap": {
"oneOf": [
{
"type": "object",
"required": [
"progress"
],
"properties": {
"progress": {
"$ref": "#/components/schemas/BootstrapProgress"
}
}
},
{
"type": "null"
}
]
},
"report": {
"type": "object",
"properties": {
"turn": {
"type": [
"integer",
"null"
]
},
"ready": {
"type": "boolean"
},
"dismissed": {
"type": "boolean"
},
"report_id": {
"type": [
"string",
"null"
]
},
"edition": {
"type": [
"string",
"null"
]
},
"masthead_title": {
"type": [
"string",
"null"
]
},
"headline": {
"type": [
"string",
"null"
]
}
}
},
"card": {
"type": "object",
"properties": {
"choiceStatus": {
"type": "string"
},
"choicePending": {
"type": "boolean"
},
"choiceKind": {
"type": [
"string",
"null"
]
},
"offerChoiceKind": {
"type": [
"string",
"null"
]
},
"specialCadence": {
"type": "boolean"
},
"eligibilityAudit": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"selectedCardId": {
"type": [
"string",
"null"
]
},
"decisionMode": {
"type": [
"string",
"null"
]
},
"playerPlacementPending": {
"type": "boolean"
},
"pendingPlacements": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PendingPlacement"
}
}
}
},
"agent": {
"type": "object",
"properties": {
"workStarted": {
"type": "boolean"
}
}
},
"incident": {
"type": "object",
"properties": {
"phaseActive": {
"type": "boolean"
}
}
},
"nextTurnUnlockAt": {
"type": [
"string",
"null"
]
},
"turnDeadlineAt": {
"type": [
"string",
"null"
],
"description": "Deprecated legacy field, always null. Never drives settlement."
}
}
},
"ReportDismissRequest": {
"type": "object",
"required": [
"report_turn"
],
"properties": {
"report_turn": {
"type": "integer",
"minimum": 1,
"description": "The completed day's report turn, matching the latest city-day presentation report.turn."
}
}
},
"ReportDismissResponse": {
"type": "object",
"required": [
"city_id",
"city_version",
"report_turn",
"dismissed"
],
"properties": {
"city_id": {
"type": "string"
},
"city_version": {
"type": "integer"
},
"report_turn": {
"type": "integer"
},
"dismissed": {
"const": true
}
}
}
}
},
"paths": {
"/players": {
"post": {
"summary": "Create a development player account",
"tags": [
"public"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"security": [],
"parameters": []
}
},
"/cities": {
"get": {
"summary": "List the authenticated player's cities",
"tags": [
"cities"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": []
},
"post": {
"summary": "Create a private city",
"tags": [
"cities"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"parameters": []
}
},
"/cities/{city_id}": {
"get": {
"summary": "Read a city summary",
"tags": [
"cities"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/snapshot": {
"get": {
"summary": "Read the Agent decision snapshot",
"tags": [
"queries"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/render-state": {
"get": {
"summary": "Read the authenticated city state for the visual viewer",
"tags": [
"queries"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/render-artifacts/manifest": {
"get": {
"summary": "Read optional versioned baked voxel building artifact metadata",
"tags": [
"queries"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/render-artifacts/pack": {
"get": {
"summary": "Read one immutable Brotli-compressed city building artifact pack",
"tags": [
"queries"
],
"responses": {
"200": {
"description": "Binary MTBA artifact",
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "query",
"name": "version",
"schema": {
"type": "integer",
"minimum": 0
},
"description": "Expected city version for the immutable pack."
},
{
"in": "query",
"name": "manifest",
"schema": {
"type": "string",
"pattern": "^[a-fA-F0-9]{64}$"
},
"description": "Expected artifact manifest digest for the immutable pack."
},
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/render-artifacts/{building_id}": {
"get": {
"summary": "Read one immutable baked voxel building mesh artifact",
"tags": [
"queries"
],
"responses": {
"200": {
"description": "Binary MTBA artifact",
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "query",
"name": "revision",
"schema": {
"type": "integer",
"minimum": 0
},
"description": "Required design revision; the server rejects stale artifact requests."
},
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "building_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/events": {
"get": {
"summary": "Read incremental city events",
"tags": [
"queries"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "query",
"name": "after_version",
"schema": {
"type": "integer",
"default": 0
},
"description": "Read events after this city version. Use the last seen city_version to incrementally sync what happened."
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"default": 100
},
"description": "Maximum number of events to return (runtime clamps to 200)."
},
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/spatial": {
"get": {
"summary": "Query cells and occupants in a bounded grid rectangle",
"tags": [
"queries"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "query",
"name": "min_col",
"schema": {
"type": "integer",
"default": 0
},
"description": "Inclusive left/start column. Bounds are inclusive; reversed bounds are invalid; the maximum requested area is 400 logical cells; omitting all bounds returns the default 10×10 window. Example: ?min_col=20&min_row=10&max_col=29&max_row=19."
},
{
"in": "query",
"name": "min_row",
"schema": {
"type": "integer",
"default": 0
},
"description": "Inclusive start row. Bounds are inclusive; reversed bounds are invalid; the maximum requested area is 400 logical cells."
},
{
"in": "query",
"name": "max_col",
"schema": {
"type": "integer"
},
"description": "Inclusive right/end column; defaults to min_col + 9. Changing these four values is how an Agent inspects another area of the city."
},
{
"in": "query",
"name": "max_row",
"schema": {
"type": "integer"
},
"description": "Inclusive end row; defaults to min_row + 9. Changing these four values is how an Agent inspects another area of the city."
},
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/cells/{cell_id}": {
"get": {
"summary": "Read one expanded logical cell after it was discovered through /spatial or another response",
"tags": [
"queries"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "cell_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/buildings": {
"get": {
"summary": "Find buildings by name, archetype, purpose, or bounding box",
"tags": [
"queries"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "query",
"name": "query",
"schema": {
"type": "string"
},
"description": "Free-text search over building name, archetype, purpose, and description."
},
{
"in": "query",
"name": "archetype",
"schema": {
"type": "string"
},
"description": "Exact archetype filter."
},
{
"in": "query",
"name": "purpose",
"schema": {
"type": "string"
},
"description": "Exact purpose filter."
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"default": 20,
"maximum": 100
},
"description": "Maximum number of buildings to return."
},
{
"in": "query",
"name": "min_col",
"schema": {
"type": "integer",
"default": 0
},
"description": "Inclusive left/start column. Bounds are inclusive; reversed bounds are invalid; the maximum requested area is 400 logical cells; omitting all bounds returns the default 10×10 window. Example: ?min_col=20&min_row=10&max_col=29&max_row=19. The bounding-box filter matches buildings with at least one footprint cell inside the requested rectangle."
},
{
"in": "query",
"name": "min_row",
"schema": {
"type": "integer",
"default": 0
},
"description": "Inclusive start row. Bounds are inclusive; reversed bounds are invalid; the maximum requested area is 400 logical cells."
},
{
"in": "query",
"name": "max_col",
"schema": {
"type": "integer"
},
"description": "Inclusive right/end column; defaults to min_col + 9. Changing these four values is how an Agent inspects another area of the city."
},
{
"in": "query",
"name": "max_row",
"schema": {
"type": "integer"
},
"description": "Inclusive end row; defaults to min_row + 9. Changing these four values is how an Agent inspects another area of the city."
},
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/buildings/{building_id}": {
"get": {
"summary": "Read one full building after it was discovered through /buildings, /spatial, district data, events, or strategy/report facts",
"tags": [
"queries"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "building_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/districts": {
"get": {
"summary": "List named development districts with block, road, and spatially computed building progress",
"tags": [
"districts"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"post": {
"summary": "Name and designate a spatial development district with advisory block guidance",
"tags": [
"districts"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DistrictCreateRequest"
}
}
}
},
"parameters": [
{
"in": "header",
"name": "Idempotency-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "If-Match",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/districts/{district_id}/cancel": {
"post": {
"summary": "Release a district's planning context while preserving existing roads and buildings",
"tags": [
"districts"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DistrictCancelRequest"
}
}
}
},
"parameters": [
{
"in": "header",
"name": "Idempotency-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "If-Match",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "district_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/building-designs": {
"get": {
"summary": "List versioned building designs",
"tags": [
"building-designs"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"post": {
"summary": "Create a recommended editable design using floor-stack or urban-massing generation",
"tags": [
"building-designs"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BuildingDesignCreateRequest"
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/building-designs/{design_id}": {
"get": {
"summary": "Read the current building design revision",
"tags": [
"building-designs"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "design_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/building-designs/{design_id}/revisions": {
"post": {
"summary": "Apply structured operations and create an immutable design revision",
"tags": [
"building-designs"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BuildingDesignRevisionRequest"
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "design_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/building-designs/{design_id}/confirm": {
"post": {
"summary": "Lock the current design revision for construction",
"tags": [
"building-designs"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BuildingDesignConfirmRequest"
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "design_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/buildings/{building_id}/upgrade-designs": {
"post": {
"summary": "Create an editable upgrade design from a built voxel design",
"tags": [
"building-designs"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BuildingDesignUpgradeRequest"
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "building_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/site-searches": {
"get": {
"summary": "List legal construction sites with query parameters (low-friction read fallback; POST remains canonical for structured bounds)",
"tags": [
"construction"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "query",
"name": "district_id",
"schema": {
"type": "string"
},
"description": "Optional named district id."
},
{
"in": "query",
"name": "footprint",
"schema": {
"enum": [
"1x1",
"1x2",
"1x3",
"2x1",
"2x2",
"2x3",
"3x1",
"3x2",
"3x3"
],
"default": "1x1"
},
"description": "Requested logical footprint."
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 12
},
"description": "Maximum candidate count."
},
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"post": {
"summary": "List legal construction sites and objective road-frontage facts inside a named district",
"tags": [
"construction"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SiteSearchRequest"
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/construction-previews": {
"post": {
"summary": "Preview one confirmed BuildingDesign",
"tags": [
"construction"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BuildingDesignConstructionRequest"
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/construction-orders": {
"get": {
"summary": "List construction orders",
"tags": [
"construction"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"post": {
"summary": "Submit one idempotent confirmed-BuildingDesign construction order",
"tags": [
"construction"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BuildingDesignConstructionRequest"
}
}
}
},
"parameters": [
{
"in": "header",
"name": "Idempotency-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "If-Match",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/construction-orders/{order_id}": {
"get": {
"summary": "Read a construction order",
"tags": [
"construction"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "order_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/connection-previews": {
"post": {
"summary": "Preview a building/cell/node road connection",
"tags": [
"roads"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConnectionRequest"
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/connections": {
"post": {
"summary": "Submit an idempotent road connection",
"tags": [
"roads"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConnectionRequest"
}
}
}
},
"parameters": [
{
"in": "header",
"name": "Idempotency-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "If-Match",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/gateways/{node_id}/upgrade": {
"post": {
"summary": "Upgrade the fixed railway station gateway without changing its footprint; levels are capped at three",
"tags": [
"construction"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GatewayUpgradeRequest"
}
}
}
},
"parameters": [
{
"in": "header",
"name": "Idempotency-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "If-Match",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "node_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/time-advances": {
"post": {
"summary": "Manual time advance is disabled: income and turn progression flow through the cooldown-gated strategy resolve instead",
"tags": [
"simulation"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"parameters": [
{
"in": "header",
"name": "Idempotency-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "If-Match",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/strategy": {
"get": {
"summary": "Read the strategy context: open incidents, Arcane Officers, player card state, and the last frozen settlement facts",
"tags": [
"strategy"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StrategyContext"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/strategy/assignments": {
"post": {
"summary": "Submit the Arcane Officer dispatch plan for the strategy phase",
"tags": [
"strategy"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StrategyAssignmentsRequest"
}
}
}
},
"parameters": [
{
"in": "header",
"name": "Idempotency-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "If-Match",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/strategy/resolve": {
"post": {
"summary": "Request the single authoritative system settlement of the strategy phase",
"tags": [
"strategy"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/StrategyResolveRequest"
}
}
}
},
"parameters": [
{
"in": "header",
"name": "Idempotency-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "If-Match",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/strategy/recruit-officer": {
"post": {
"summary": "Recruit one current system-generated Arcane Officer candidate",
"tags": [
"strategy"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OfficerRecruitmentResponse"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OfficerRecruitmentRequest"
}
}
}
},
"parameters": [
{
"in": "header",
"name": "Idempotency-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "If-Match",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cards": {
"get": {
"summary": "Read the system-owned daily card catalog",
"tags": [
"cards"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CardDefinition"
}
}
}
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": []
}
},
"/cities/{city_id}/cards/current": {
"get": {
"summary": "Read the canonical three-card offer and all pending placement mandates for the current turn",
"tags": [
"cards"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"city_id": {
"type": "string"
},
"city_version": {
"type": "integer"
},
"turn": {
"type": "integer"
},
"turn_status": {
"type": "string"
},
"offer": {
"$ref": "#/components/schemas/CardOffer"
},
"choice": {
"$ref": "#/components/schemas/CardChoice"
},
"pending_placements": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PendingPlacement"
}
}
}
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/cards/select": {
"post": {
"summary": "The player selects exactly one offered card for this turn",
"tags": [
"cards"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CardSelectResponse"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CardSelectRequest"
}
}
}
},
"parameters": [
{
"in": "header",
"name": "Idempotency-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "If-Match",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/cards/place": {
"post": {
"summary": "Place a pending special structure at a legal location (player placement or delegated Agent placement)",
"tags": [
"cards"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CardPlaceResponse"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CardPlaceRequest"
}
}
}
},
"parameters": [
{
"in": "header",
"name": "Idempotency-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "If-Match",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/cards/cancel": {
"post": {
"summary": "Cancel an unplaced special structure entitlement; cancelled unique cards may reappear on a later Special Choice",
"tags": [
"cards"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CardCancelRequest"
}
}
}
},
"parameters": [
{
"in": "header",
"name": "Idempotency-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "If-Match",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/report-context": {
"get": {
"summary": "Read the immutable SYSTEM newspaper source facts for a resolved turn",
"tags": [
"reports"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReportContext"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "query",
"name": "turn",
"schema": {
"type": "integer",
"minimum": 1
},
"description": "The resolved turn to read. Omit to select the latest resolved turn that has frozen facts."
},
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/reports": {
"get": {
"summary": "Read the Owl Daily report history for this city",
"tags": [
"reports"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OwlReportSummary"
}
}
}
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
},
"post": {
"summary": "Publish the canonical Owl Daily newspaper for a resolved turn",
"tags": [
"reports"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OwlReportSubmitRequest"
}
}
}
},
"parameters": [
{
"in": "header",
"name": "Idempotency-Key",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "If-Match",
"required": false,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/reports/{report_id}": {
"get": {
"summary": "Read one published Owl Daily report",
"tags": [
"reports"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OwlReportResponse"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "report_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/city-day": {
"get": {
"summary": "Read the player-facing city-day presentation projection for the current turn",
"tags": [
"city-day"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CityDayPresentation"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/city-day/report-dismissed": {
"post": {
"summary": "Record that the player dismissed the completed day's Owl Daily so it is never replayed",
"tags": [
"city-day"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReportDismissResponse"
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReportDismissRequest"
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/agent-links": {
"post": {
"summary": "Create a one-time Agent connection link",
"tags": [
"credentials"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/agent-credentials": {
"get": {
"summary": "List Agent credentials",
"tags": [
"credentials"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
},
"/cities/{city_id}/agent-credentials/{credential_id}": {
"delete": {
"summary": "Revoke an Agent credential",
"tags": [
"credentials"
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"400": {
"description": "Invalid request",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"401": {
"description": "Authentication failed",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"409": {
"description": "Version or idempotency conflict",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"422": {
"description": "Request is valid but incompatible with city or asset state",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
},
"428": {
"description": "City version precondition is required",
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"code",
"message",
"retryable"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object",
"additionalProperties": true
}
}
}
}
}
}
},
"parameters": [
{
"in": "path",
"name": "city_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "credential_id",
"required": true,
"schema": {
"type": "string"
}
}
]
}
}
}
}