{"instructions":"Choose the operation needed for the current task, then read its detail_url before calling an unfamiliar operation. Use /openapi.json only as a fallback.","operation_count":54,"operations":[{"operation_id":"post_players","method":"POST","path":"/api/v1/players","summary":"Create a development player account","tags":["public"],"detail_url":"https://magtopia.city/agent/api/operations/post_players"},{"operation_id":"get_cities","method":"GET","path":"/api/v1/cities","summary":"List the authenticated player's cities","tags":["cities"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities"},{"operation_id":"post_cities","method":"POST","path":"/api/v1/cities","summary":"Create a private city","tags":["cities"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities"},{"operation_id":"get_cities_by_city_id","method":"GET","path":"/api/v1/cities/{city_id}","summary":"Read a city summary","tags":["cities"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id"},{"operation_id":"get_cities_by_city_id_snapshot","method":"GET","path":"/api/v1/cities/{city_id}/snapshot","summary":"Read the Agent decision snapshot","tags":["queries"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id_snapshot"},{"operation_id":"get_cities_by_city_id_render_state","method":"GET","path":"/api/v1/cities/{city_id}/render-state","summary":"Read the authenticated city state for the visual viewer","tags":["queries"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id_render_state"},{"operation_id":"get_cities_by_city_id_render_artifacts_manifest","method":"GET","path":"/api/v1/cities/{city_id}/render-artifacts/manifest","summary":"Read optional versioned baked voxel building artifact metadata","tags":["queries"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id_render_artifacts_manifest"},{"operation_id":"get_cities_by_city_id_render_artifacts_pack","method":"GET","path":"/api/v1/cities/{city_id}/render-artifacts/pack","summary":"Read one immutable Brotli-compressed city building artifact pack","tags":["queries"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id_render_artifacts_pack"},{"operation_id":"get_cities_by_city_id_render_artifacts_by_building_id","method":"GET","path":"/api/v1/cities/{city_id}/render-artifacts/{building_id}","summary":"Read one immutable baked voxel building mesh artifact","tags":["queries"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id_render_artifacts_by_building_id"},{"operation_id":"get_cities_by_city_id_events","method":"GET","path":"/api/v1/cities/{city_id}/events","summary":"Read incremental city events","tags":["queries"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id_events"},{"operation_id":"get_cities_by_city_id_spatial","method":"GET","path":"/api/v1/cities/{city_id}/spatial","summary":"Query cells and occupants in a bounded grid rectangle","tags":["queries"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id_spatial"},{"operation_id":"get_cities_by_city_id_cells_by_cell_id","method":"GET","path":"/api/v1/cities/{city_id}/cells/{cell_id}","summary":"Read one expanded logical cell after it was discovered through /spatial or another response","tags":["queries"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id_cells_by_cell_id"},{"operation_id":"get_cities_by_city_id_buildings","method":"GET","path":"/api/v1/cities/{city_id}/buildings","summary":"Find buildings by name, archetype, purpose, or bounding box","tags":["queries"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id_buildings"},{"operation_id":"get_cities_by_city_id_buildings_by_building_id","method":"GET","path":"/api/v1/cities/{city_id}/buildings/{building_id}","summary":"Read one full building after it was discovered through /buildings, /spatial, district data, events, or strategy/report facts","tags":["queries"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id_buildings_by_building_id"},{"operation_id":"get_cities_by_city_id_districts","method":"GET","path":"/api/v1/cities/{city_id}/districts","summary":"List named development districts with block, road, and spatially computed building progress","tags":["districts"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id_districts"},{"operation_id":"post_cities_by_city_id_districts","method":"POST","path":"/api/v1/cities/{city_id}/districts","summary":"Name and designate a spatial development district with advisory block guidance","tags":["districts"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities_by_city_id_districts"},{"operation_id":"post_cities_by_city_id_districts_by_district_id_cancel","method":"POST","path":"/api/v1/cities/{city_id}/districts/{district_id}/cancel","summary":"Release a district's planning context while preserving existing roads and buildings","tags":["districts"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities_by_city_id_districts_by_district_id_cancel"},{"operation_id":"get_cities_by_city_id_building_designs","method":"GET","path":"/api/v1/cities/{city_id}/building-designs","summary":"List versioned building designs","tags":["building-designs"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id_building_designs"},{"operation_id":"post_cities_by_city_id_building_designs","method":"POST","path":"/api/v1/cities/{city_id}/building-designs","summary":"Create a recommended editable design using floor-stack or urban-massing generation","tags":["building-designs"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities_by_city_id_building_designs"},{"operation_id":"get_cities_by_city_id_building_designs_by_design_id","method":"GET","path":"/api/v1/cities/{city_id}/building-designs/{design_id}","summary":"Read the current building design revision","tags":["building-designs"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id_building_designs_by_design_id"},{"operation_id":"get_cities_by_city_id_building_designs_by_design_id_visualization","method":"GET","path":"/api/v1/cities/{city_id}/building-designs/{design_id}/visualization","summary":"Render an optional static building PNG without changing the city","tags":["building-designs"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id_building_designs_by_design_id_visualization"},{"operation_id":"post_cities_by_city_id_building_designs_by_design_id_revisions","method":"POST","path":"/api/v1/cities/{city_id}/building-designs/{design_id}/revisions","summary":"Apply structured operations and create an immutable design revision","tags":["building-designs"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities_by_city_id_building_designs_by_design_id_revisions"},{"operation_id":"post_cities_by_city_id_building_designs_by_design_id_confirm","method":"POST","path":"/api/v1/cities/{city_id}/building-designs/{design_id}/confirm","summary":"Lock the current design revision for construction","tags":["building-designs"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities_by_city_id_building_designs_by_design_id_confirm"},{"operation_id":"post_cities_by_city_id_buildings_by_building_id_upgrade_designs","method":"POST","path":"/api/v1/cities/{city_id}/buildings/{building_id}/upgrade-designs","summary":"Create an editable upgrade design from a built voxel design","tags":["building-designs"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities_by_city_id_buildings_by_building_id_upgrade_designs"},{"operation_id":"get_cities_by_city_id_site_searches","method":"GET","path":"/api/v1/cities/{city_id}/site-searches","summary":"List legal construction sites with query parameters (low-friction read fallback; POST remains canonical for structured bounds)","tags":["construction"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id_site_searches"},{"operation_id":"post_cities_by_city_id_site_searches","method":"POST","path":"/api/v1/cities/{city_id}/site-searches","summary":"List legal construction sites and objective road-frontage facts inside a named district","tags":["construction"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities_by_city_id_site_searches"},{"operation_id":"post_cities_by_city_id_construction_previews","method":"POST","path":"/api/v1/cities/{city_id}/construction-previews","summary":"Preview one confirmed BuildingDesign","tags":["construction"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities_by_city_id_construction_previews"},{"operation_id":"get_cities_by_city_id_construction_orders","method":"GET","path":"/api/v1/cities/{city_id}/construction-orders","summary":"List construction orders","tags":["construction"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id_construction_orders"},{"operation_id":"post_cities_by_city_id_construction_orders","method":"POST","path":"/api/v1/cities/{city_id}/construction-orders","summary":"Submit one idempotent confirmed-BuildingDesign construction order; new buildings operate from the next turn (resource.building_status, ready_at_turn); completed order status means asset fulfillment","tags":["construction"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities_by_city_id_construction_orders"},{"operation_id":"get_cities_by_city_id_construction_orders_by_order_id","method":"GET","path":"/api/v1/cities/{city_id}/construction-orders/{order_id}","summary":"Read a construction order","tags":["construction"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id_construction_orders_by_order_id"},{"operation_id":"post_cities_by_city_id_connection_previews","method":"POST","path":"/api/v1/cities/{city_id}/connection-previews","summary":"Preview a building/cell/node road connection","tags":["roads"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities_by_city_id_connection_previews"},{"operation_id":"post_cities_by_city_id_connections","method":"POST","path":"/api/v1/cities/{city_id}/connections","summary":"Submit an idempotent road connection","tags":["roads"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities_by_city_id_connections"},{"operation_id":"post_cities_by_city_id_demolition_previews","method":"POST","path":"/api/v1/cities/{city_id}/demolition-previews","summary":"Preview one ordinary-building or road-cell demolition and its 50% refund","tags":["demolition"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities_by_city_id_demolition_previews"},{"operation_id":"post_cities_by_city_id_demolitions","method":"POST","path":"/api/v1/cities/{city_id}/demolitions","summary":"Submit one idempotent ordinary-building or road-cell demolition","tags":["demolition"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities_by_city_id_demolitions"},{"operation_id":"post_cities_by_city_id_gateways_by_node_id_upgrade","method":"POST","path":"/api/v1/cities/{city_id}/gateways/{node_id}/upgrade","summary":"Upgrade the fixed railway station gateway without changing its footprint; levels are capped at three","tags":["construction"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities_by_city_id_gateways_by_node_id_upgrade"},{"operation_id":"post_cities_by_city_id_time_advances","method":"POST","path":"/api/v1/cities/{city_id}/time-advances","summary":"Manual time advance is disabled: income and turn progression flow through the cooldown-gated strategy resolve instead","tags":["simulation"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities_by_city_id_time_advances"},{"operation_id":"get_cities_by_city_id_strategy","method":"GET","path":"/api/v1/cities/{city_id}/strategy","summary":"Read the strategy context: open incidents, Arcane Officers, player card state, the last frozen settlement facts, and optional player-update narrative_guidance","tags":["strategy"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id_strategy"},{"operation_id":"post_cities_by_city_id_strategy_assignments","method":"POST","path":"/api/v1/cities/{city_id}/strategy/assignments","summary":"Submit the Arcane Officer dispatch plan for the strategy phase; accepted nonempty plans include narrative_guidance for optional player updates","tags":["strategy"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities_by_city_id_strategy_assignments"},{"operation_id":"post_cities_by_city_id_strategy_resolve","method":"POST","path":"/api/v1/cities/{city_id}/strategy/resolve","summary":"Request the single authoritative system settlement of the strategy phase; incident results include narrative_guidance and every successful settlement includes Owl Daily writing guidance","tags":["strategy"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities_by_city_id_strategy_resolve"},{"operation_id":"post_cities_by_city_id_strategy_recruit_officer","method":"POST","path":"/api/v1/cities/{city_id}/strategy/recruit-officer","summary":"Recruit one current system-generated Arcane Officer candidate","tags":["strategy"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities_by_city_id_strategy_recruit_officer"},{"operation_id":"get_cards","method":"GET","path":"/api/v1/cards","summary":"Read the system-owned daily card catalog","tags":["cards"],"detail_url":"https://magtopia.city/agent/api/operations/get_cards"},{"operation_id":"get_cities_by_city_id_cards_current","method":"GET","path":"/api/v1/cities/{city_id}/cards/current","summary":"Read the canonical three-card offer and all pending placement mandates for the current turn","tags":["cards"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id_cards_current"},{"operation_id":"post_cities_by_city_id_cards_select","method":"POST","path":"/api/v1/cities/{city_id}/cards/select","summary":"The player selects exactly one offered card for this turn","tags":["cards"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities_by_city_id_cards_select"},{"operation_id":"post_cities_by_city_id_cards_place","method":"POST","path":"/api/v1/cities/{city_id}/cards/place","summary":"Place a pending special structure at a legal location (player placement or delegated Agent placement)","tags":["cards"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities_by_city_id_cards_place"},{"operation_id":"post_cities_by_city_id_cards_cancel","method":"POST","path":"/api/v1/cities/{city_id}/cards/cancel","summary":"Cancel an unplaced special structure entitlement; cancelled unique cards may reappear on a later Special Choice","tags":["cards"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities_by_city_id_cards_cancel"},{"operation_id":"get_cities_by_city_id_report_context","method":"GET","path":"/api/v1/cities/{city_id}/report-context","summary":"Read the immutable SYSTEM newspaper source facts for a resolved turn","tags":["reports"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id_report_context"},{"operation_id":"get_cities_by_city_id_reports","method":"GET","path":"/api/v1/cities/{city_id}/reports","summary":"Read the Owl Daily report history for this city","tags":["reports"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id_reports"},{"operation_id":"post_cities_by_city_id_reports","method":"POST","path":"/api/v1/cities/{city_id}/reports","summary":"Publish the canonical Owl Daily newspaper for a resolved turn","tags":["reports"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities_by_city_id_reports"},{"operation_id":"get_cities_by_city_id_reports_by_report_id","method":"GET","path":"/api/v1/cities/{city_id}/reports/{report_id}","summary":"Read one published Owl Daily report","tags":["reports"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id_reports_by_report_id"},{"operation_id":"get_cities_by_city_id_city_day","method":"GET","path":"/api/v1/cities/{city_id}/city-day","summary":"Read the player-facing city-day presentation projection for the current turn","tags":["city-day"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id_city_day"},{"operation_id":"post_cities_by_city_id_city_day_report_dismissed","method":"POST","path":"/api/v1/cities/{city_id}/city-day/report-dismissed","summary":"Record that the player dismissed the completed day's Owl Daily so it is never replayed","tags":["city-day"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities_by_city_id_city_day_report_dismissed"},{"operation_id":"post_cities_by_city_id_agent_links","method":"POST","path":"/api/v1/cities/{city_id}/agent-links","summary":"Create a one-time Agent connection link","tags":["credentials"],"detail_url":"https://magtopia.city/agent/api/operations/post_cities_by_city_id_agent_links"},{"operation_id":"get_cities_by_city_id_agent_credentials","method":"GET","path":"/api/v1/cities/{city_id}/agent-credentials","summary":"List Agent credentials","tags":["credentials"],"detail_url":"https://magtopia.city/agent/api/operations/get_cities_by_city_id_agent_credentials"},{"operation_id":"delete_cities_by_city_id_agent_credentials_by_credential_id","method":"DELETE","path":"/api/v1/cities/{city_id}/agent-credentials/{credential_id}","summary":"Revoke an Agent credential","tags":["credentials"],"detail_url":"https://magtopia.city/agent/api/operations/delete_cities_by_city_id_agent_credentials_by_credential_id"}]}