{ "openapi": "3.0.3", "info": { "title": "UPSTREAM API", "version": "1.0.0", "description": "Generated by tools/gen-openapi.js from server/routes. Every response carries serverTime; errors use the { error: { code, message, details } } envelope. Codes: bad_request, validation_failed, unauthorized, invalid_credentials, forbidden, not_found, method_not_allowed, conflict, request_in_progress, idempotency_key_reuse, payload_too_large, rate_limited, internal_error, signup_closed, username_taken, world_full, unknown_building, not_buildable, max_level, requirements_not_met, already_queued, queue_full, not_enough_resources, peering_office_required, already_in_alliance, not_in_alliance, alliance_name_taken, alliance_tag_taken, alliance_full, invite_expired, leader_must_transfer, notes_full, diplomacy_invalid, diplomacy_pending, proposal_exists, proposal_expired, unknown_unit, not_researchable, not_enough_units, units_offline, invalid_target, target_protected, protection_active, out_of_range, footprint_too_low, cannot_takeover, recall_expired, capacity_exceeded, no_transport_link, trade_ratio, offer_closed, own_offer, trade_out_of_range, no_room_for_goods, world_ended, backbone_closed" }, "servers": [ { "url": "/api/v1" } ], "paths": { "/alliance-invites": { "get": { "summary": "Open invites addressed to you", "tags": [ "alliances" ], "operationId": "getAllianceinvites", "parameters": [], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceivedInviteList" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/alliance-invites/{id}/accept": { "post": { "summary": "Accept an invite (needs Peering office 1+ and no alliance yet)", "tags": [ "alliances" ], "operationId": "postAllianceinvitesIdAccept", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Changed" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: alliance_full, already_in_alliance, conflict, invite_expired, peering_office_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/alliance-invites/{id}/decline": { "post": { "summary": "Decline an invite", "tags": [ "alliances" ], "operationId": "postAllianceinvitesIdDecline", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Changed" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: alliance_full, already_in_alliance, conflict, invite_expired, peering_office_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/alliances": { "get": { "summary": "Alliance directory of a world, optional name/tag search (cursor: after = last id)", "tags": [ "alliances" ], "operationId": "getAlliances", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 40 } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "worldId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllianceList" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Found an alliance (needs Peering office 1+); you become its leader", "tags": [ "alliances" ], "operationId": "postAlliances", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "tag" ], "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 60 }, "tag": { "type": "string", "minLength": 2, "maxLength": 5 }, "worldId": { "type": "integer", "minimum": 1 } } } } } }, "security": [ { "bearer": [] } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllianceCreated" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: alliance_name_taken, alliance_tag_taken, already_in_alliance, peering_office_required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/alliances/mine": { "get": { "summary": "Your alliance, role and permissions (null alliance when you are not in one)", "tags": [ "alliances" ], "operationId": "getAlliancesMine", "parameters": [ { "name": "worldId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllianceMine" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/alliances/{id}": { "get": { "summary": "Public alliance profile: size, leader, footprint, your role and relation to it", "tags": [ "alliances" ], "operationId": "getAlliancesId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllianceDetail" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/alliances/{id}/diplomacy": { "get": { "summary": "Relations with other alliances (with scheduled changes) and open proposals (members only)", "tags": [ "diplomacy" ], "operationId": "getAlliancesIdDiplomacy", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Diplomacy" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Change the relation to another alliance (needs diplomacy): war applies at once from neutral, pacts need acceptance, cancelling a pact takes 24 h / world speed", "tags": [ "diplomacy" ], "operationId": "postAlliancesIdDiplomacy", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "targetId", "state" ], "properties": { "targetId": { "type": "integer", "minimum": 1 }, "state": { "type": "string", "enum": [ "war", "neutral", "nap", "confed" ] } } } } } }, "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiplomacyResult" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: diplomacy_invalid, diplomacy_pending, proposal_exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/alliances/{id}/diplomacy/{otherId}/pending": { "delete": { "summary": "Take back a scheduled cancel before it takes effect (the alliance that started it, needs diplomacy)", "tags": [ "diplomacy" ], "operationId": "deleteAlliancesIdDiplomacyOtherIdPending", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "otherId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Changed" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/alliances/{id}/disband": { "post": { "summary": "Disband the alliance (leader only)", "tags": [ "alliances" ], "operationId": "postAlliancesIdDisband", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Changed" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/alliances/{id}/invite": { "post": { "summary": "Invite an operator by id or name (needs invite). Repeating it returns the pending invite", "tags": [ "alliances" ], "operationId": "postAlliancesIdInvite", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operatorId": { "type": "integer", "minimum": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 40 } } } } } }, "security": [ { "bearer": [] } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteResult" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: alliance_full, already_in_alliance, conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/alliances/{id}/invites": { "get": { "summary": "Pending invites sent by this alliance (needs viewInvites)", "tags": [ "alliances" ], "operationId": "getAlliancesIdInvites", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllianceInviteList" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/alliances/{id}/invites/{inviteId}": { "delete": { "summary": "Cancel a pending invite (needs cancelInvite)", "tags": [ "alliances" ], "operationId": "deleteAlliancesIdInvitesInviteId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "inviteId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Changed" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/alliances/{id}/kick": { "post": { "summary": "Remove a member you outrank (needs kick)", "tags": [ "alliances" ], "operationId": "postAlliancesIdKick", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "operatorId" ], "properties": { "operatorId": { "type": "integer", "minimum": 1 } } } } } }, "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Changed" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/alliances/{id}/leave": { "post": { "summary": "Leave the alliance. The leader must transfer first unless alone (then it is disbanded)", "tags": [ "alliances" ], "operationId": "postAlliancesIdLeave", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Changed" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: leader_must_transfer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/alliances/{id}/members": { "get": { "summary": "Member list with role, POP count, footprint and last online (members only)", "tags": [ "alliances" ], "operationId": "getAlliancesIdMembers", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllianceMemberList" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/alliances/{id}/notes": { "get": { "summary": "Pinned notes (members only)", "tags": [ "alliances" ], "operationId": "getAlliancesIdNotes", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllianceNoteList" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Pin a note (needs editNotes)", "tags": [ "alliances" ], "operationId": "postAlliancesIdNotes", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 1000 } } } } } }, "security": [ { "bearer": [] } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllianceNoteResponse" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: notes_full", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/alliances/{id}/notes/{noteId}": { "post": { "summary": "Edit a pinned note (needs editNotes)", "tags": [ "alliances" ], "operationId": "postAlliancesIdNotesNoteId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 1000 } } } } } }, "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllianceNoteResponse" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Remove a pinned note (needs editNotes)", "tags": [ "alliances" ], "operationId": "deleteAlliancesIdNotesNoteId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "noteId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Changed" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/alliances/{id}/reports": { "get": { "summary": "The alliance's shared reports, newest first (cursor: after = id of the last report seen; members only)", "tags": [ "reports" ], "operationId": "getAlliancesIdReports", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharedReportList" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/alliances/{id}/reports/{reportId}": { "get": { "summary": "One shared report with its full data (members only)", "tags": [ "reports" ], "operationId": "getAlliancesIdReportsReportId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "reportId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharedReportResponse" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/alliances/{id}/role": { "post": { "summary": "Set a member role: diplomat, officer or member (leader only)", "tags": [ "alliances" ], "operationId": "postAlliancesIdRole", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "operatorId", "role" ], "properties": { "operatorId": { "type": "integer", "minimum": 1 }, "role": { "type": "string", "enum": [ "diplomat", "officer", "member" ] } } } } } }, "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Changed" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/alliances/{id}/transfer": { "post": { "summary": "Hand leadership to another member; you become an officer (leader only)", "tags": [ "alliances" ], "operationId": "postAlliancesIdTransfer", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "operatorId" ], "properties": { "operatorId": { "type": "integer", "minimum": 1 } } } } } }, "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Changed" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/login": { "post": { "summary": "Log in on a device and get a bearer token", "tags": [ "auth" ], "operationId": "postAuthLogin", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "username", "password" ], "properties": { "username": { "type": "string", "minLength": 3, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]+$" }, "password": { "type": "string", "minLength": 8, "maxLength": 128 }, "device": { "type": "string", "maxLength": 40 } } } } } }, "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResult" } } } }, "401": { "description": "Error codes: invalid_credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error codes: rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/logout": { "post": { "summary": "Revoke the token used for this request", "tags": [ "auth" ], "operationId": "postAuthLogout", "parameters": [], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/signup": { "post": { "summary": "Create an account, join the world and get a bearer token", "tags": [ "auth" ], "operationId": "postAuthSignup", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "username", "password" ], "properties": { "invite": { "type": "string", "maxLength": 64 }, "worldId": { "type": "integer", "minimum": 1 }, "username": { "type": "string", "minLength": 3, "maxLength": 20, "pattern": "^[A-Za-z0-9_-]+$" }, "password": { "type": "string", "minLength": 8, "maxLength": 128 }, "device": { "type": "string", "maxLength": 40 } } } } } }, "security": [], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResult" } } } }, "403": { "description": "Error codes: signup_closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: username_taken, world_full", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error codes: rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/tokens": { "get": { "summary": "List this account's active device tokens", "tags": [ "auth" ], "operationId": "getAuthTokens", "parameters": [], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "serverTime", "tokens" ], "properties": { "serverTime": { "type": "integer" }, "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/Token" } } } } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/tokens/{tokenId}": { "delete": { "summary": "Revoke one of this account's tokens", "tags": [ "auth" ], "operationId": "deleteAuthTokensTokenId", "parameters": [ { "name": "tokenId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/backbone/{id}": { "get": { "summary": "One landing site; members of the holding alliance also see the contribution ledger and what they may do", "tags": [ "world" ], "operationId": "getBackboneId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandingSiteResponse" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/backbone/{id}/build": { "post": { "summary": "Start the next Backbone node level on a landing site your alliance holds (paid from the site's stockpile; one level at a time, up to level 100)", "tags": [ "world" ], "operationId": "postBackboneIdBuild", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BackboneBuildStarted" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: already_queued, backbone_closed, max_level, not_enough_resources, world_ended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/backbone/{id}/ship": { "post": { "summary": "Send resources from one of your POPs to a landing site your alliance holds (a transport: Internet exchange links, 1000 each at world speed 1, times the world speed)", "tags": [ "world" ], "operationId": "postBackboneIdShip", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fromTownId", "cargo" ], "properties": { "fromTownId": { "type": "integer", "minimum": 1 }, "cargo": { "type": "object", "additionalProperties": true, "description": "fiber/hardware/capital -> amount" } } } } } }, "security": [ { "bearer": [] } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovementSent" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: backbone_closed, capacity_exceeded, no_transport_link, not_enough_resources, world_ended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/backbone/{id}/withdraw": { "post": { "summary": "Call units of one of your POPs home from a landing site's garrison (default: all of them). Only their owner can; works whoever holds the site now. Station units with POST /movements type reinforce at the site's x,y (members of the holding alliance only)", "tags": [ "world" ], "operationId": "postBackboneIdWithdraw", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fromTownId" ], "properties": { "fromTownId": { "type": "integer", "minimum": 1 }, "units": { "type": "object", "additionalProperties": true, "description": "defaults to the whole group" } } } } } }, "security": [ { "bearer": [] } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GarrisonWithdrawn" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found, unknown_unit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: conflict, not_enough_units, world_ended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diplomacy/proposals/{proposalId}": { "delete": { "summary": "Withdraw a proposal your alliance made (needs diplomacy)", "tags": [ "diplomacy" ], "operationId": "deleteDiplomacyProposalsProposalId", "parameters": [ { "name": "proposalId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Changed" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diplomacy/proposals/{proposalId}/accept": { "post": { "summary": "Accept a diplomatic proposal addressed to your alliance (needs diplomacy)", "tags": [ "diplomacy" ], "operationId": "postDiplomacyProposalsProposalIdAccept", "parameters": [ { "name": "proposalId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Changed" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: conflict, diplomacy_invalid, diplomacy_pending, proposal_expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/diplomacy/proposals/{proposalId}/decline": { "post": { "summary": "Decline a diplomatic proposal addressed to your alliance (needs diplomacy)", "tags": [ "diplomacy" ], "operationId": "postDiplomacyProposalsProposalIdDecline", "parameters": [ { "name": "proposalId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Changed" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: conflict, diplomacy_invalid, diplomacy_pending, proposal_expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/map": { "get": { "summary": "Map viewport: rural areas, incumbent sites and POPs within (x±r, y±r); land tiles are implied", "tags": [ "map" ], "operationId": "getMap", "parameters": [ { "name": "x", "in": "query", "required": true, "schema": { "type": "integer", "minimum": -1000, "maximum": 1000 } }, { "name": "y", "in": "query", "required": true, "schema": { "type": "integer", "minimum": -1000, "maximum": 1000 } }, { "name": "r", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 40 } }, { "name": "worldId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapResponse" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/map/tile": { "get": { "summary": "Public information about one tile for the send dialog: what is there, owner, distance from your POPs, whether you could settle it", "tags": [ "map" ], "operationId": "getMapTile", "parameters": [ { "name": "x", "in": "query", "required": true, "schema": { "type": "integer", "minimum": -1000, "maximum": 1000 } }, { "name": "y", "in": "query", "required": true, "schema": { "type": "integer", "minimum": -1000, "maximum": 1000 } }, { "name": "worldId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TileInfo" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/me": { "get": { "summary": "The current user, their operators and POPs", "tags": [ "me" ], "operationId": "getMe", "parameters": [], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/me/join": { "post": { "summary": "Join a world with this account: creates the operator and its capital POP (default: the first running world)", "tags": [ "me" ], "operationId": "postMeJoin", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "worldId": { "type": "integer", "minimum": 1 } } } } } }, "security": [ { "bearer": [] } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: conflict, world_full", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/messages": { "post": { "summary": "Send a message to an operator (toOperatorId or toName) or to your alliance (toAlliance). Plain text, max 2000 characters, rate-limited", "tags": [ "messages" ], "operationId": "postMessages", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 2000 }, "toOperatorId": { "type": "integer", "minimum": 1 }, "toName": { "type": "string", "minLength": 1, "maxLength": 40 }, "toAlliance": { "type": "boolean" }, "worldId": { "type": "integer", "minimum": 1 } } } } } }, "security": [ { "bearer": [] } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageSent" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: not_in_alliance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error codes: rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/messages/alliance": { "get": { "summary": "Broadcasts of your alliance, newest first", "tags": [ "messages" ], "operationId": "getMessagesAlliance", "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "worldId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageList" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: not_in_alliance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/messages/blocks": { "get": { "summary": "Operators you blocked", "tags": [ "messages" ], "operationId": "getMessagesBlocks", "parameters": [ { "name": "worldId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockList" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Block an operator: their messages are no longer delivered to you (they are not told)", "tags": [ "messages" ], "operationId": "postMessagesBlocks", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "operatorId" ], "properties": { "operatorId": { "type": "integer", "minimum": 1 } } } } } }, "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Changed" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/messages/blocks/{operatorId}": { "delete": { "summary": "Unblock an operator", "tags": [ "messages" ], "operationId": "deleteMessagesBlocksOperatorId", "parameters": [ { "name": "operatorId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Changed" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/messages/inbox": { "get": { "summary": "Received messages, newest first (cursor: after = last id of the previous page); `unread` counts all unread", "tags": [ "messages" ], "operationId": "getMessagesInbox", "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "worldId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "unread", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageList" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/messages/outbox": { "get": { "summary": "Sent messages, newest first", "tags": [ "messages" ], "operationId": "getMessagesOutbox", "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "worldId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageList" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/messages/read": { "post": { "summary": "Mark received messages read: a list of ids (max 100) or all", "tags": [ "messages" ], "operationId": "postMessagesRead", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "maxItems": 100, "items": { "type": "integer", "minimum": 1 } }, "all": { "type": "boolean" }, "worldId": { "type": "integer", "minimum": 1 } } } } } }, "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Changed" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/messages/thread/{operatorId}": { "get": { "summary": "The conversation with one operator, both directions, newest first", "tags": [ "messages" ], "operationId": "getMessagesThreadOperatorId", "parameters": [ { "name": "operatorId", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "worldId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageList" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/messages/{id}": { "get": { "summary": "One message you sent or received", "tags": [ "messages" ], "operationId": "getMessagesId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete your own copy of a message (the other side keeps theirs)", "tags": [ "messages" ], "operationId": "deleteMessagesId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Changed" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/movements": { "post": { "summary": "Send units (scan, raid, attack, takeover, reinforce, settle) or resources (transport) from one of your POPs. Target = toTownId or the tile x,y", "tags": [ "movements" ], "operationId": "postMovements", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fromTownId", "type" ], "properties": { "fromTownId": { "type": "integer", "minimum": 1 }, "type": { "type": "string", "enum": [ "scan", "raid", "attack", "takeover", "reinforce", "settle", "transport" ] }, "toTownId": { "type": "integer", "minimum": 1 }, "x": { "type": "integer", "minimum": -1000, "maximum": 1000 }, "y": { "type": "integer", "minimum": -1000, "maximum": 1000 }, "units": { "type": "object", "additionalProperties": true, "description": "unit id -> count" }, "cargo": { "type": "object", "additionalProperties": true, "description": "transport only: fiber/hardware/capital -> amount" }, "target": { "type": "string", "maxLength": 32, "pattern": "^[a-z0-9_]+$", "description": "exploit kits: the building (f1..f18 or an infrastructure type) to damage on a win" }, "wild": { "type": "array", "maxItems": 2, "items": { "type": "string", "maxLength": 32 }, "description": "settle: the two wild slot field types of the new POP" }, "confirmEndProtection": { "type": "boolean", "description": "raid/attack/takeover from a protected operator: attacking ends beginner protection" } } } } } }, "security": [ { "bearer": [] } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovementSent" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found, unknown_unit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: cannot_takeover, capacity_exceeded, footprint_too_low, invalid_target, no_transport_link, not_enough_resources, not_enough_units, out_of_range, protection_active, target_protected, units_offline", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "Your active movements and other operators' movements heading for your POPs (incoming warnings: origin and ETA only, type hidden)", "tags": [ "movements" ], "operationId": "getMovements", "parameters": [ { "name": "worldId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MovementList" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/movements/{id}/recall": { "post": { "summary": "Turn an outbound movement around within the first 90 seconds", "tags": [ "movements" ], "operationId": "postMovementsIdRecall", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecallResult" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: conflict, recall_expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/notifications": { "get": { "summary": "Notifications for this user (cursor: after = last seen id)", "tags": [ "me" ], "operationId": "getNotifications", "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationList" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rankings/alliances": { "get": { "summary": "Alliances by summed footprint of their members", "tags": [ "rankings" ], "operationId": "getRankingsAlliances", "parameters": [ { "name": "worldId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RankAlliances" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rankings/battles": { "get": { "summary": "Attackers / defenders by battle points (`by`: attack, defense or total). Empty with available=false until the military stage records points", "tags": [ "rankings" ], "operationId": "getRankingsBattles", "parameters": [ { "name": "worldId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "attack", "defense", "total" ] } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RankBattles" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rankings/operators": { "get": { "summary": "Operators by footprint (cursor: after = number of ranks already seen)", "tags": [ "rankings" ], "operationId": "getRankingsOperators", "parameters": [ { "name": "worldId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RankOperators" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports": { "get": { "summary": "Your reports, newest first (cursor: after = id of the last report seen, returns older ones)", "tags": [ "reports" ], "operationId": "getReports", "parameters": [ { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "unread", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportList" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports/read-all": { "post": { "summary": "Mark all your reports as read", "tags": [ "reports" ], "operationId": "postReportsReadall", "parameters": [], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Marked" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports/{id}": { "get": { "summary": "One report with its full data", "tags": [ "reports" ], "operationId": "getReportsId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportResponse" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports/{id}/read": { "post": { "summary": "Mark a report as read", "tags": [ "reports" ], "operationId": "postReportsIdRead", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Marked" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports/{id}/share": { "post": { "summary": "Put one of your reports into your alliance's shared folder (needs shareReport; keeps the report for another 14 days)", "tags": [ "reports" ], "operationId": "postReportsIdShare", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportShared" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: not_in_alliance, world_ended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Take a report out of the alliance folder (whoever shared it, or leader/officer)", "tags": [ "reports" ], "operationId": "deleteReportsIdShare", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportShared" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error codes: forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: world_ended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/towns/{id}": { "get": { "summary": "Full state of one of your POPs: resources, power, buildings, build queue", "tags": [ "towns" ], "operationId": "getTownsId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TownResponse" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/towns/{id}/build": { "post": { "summary": "Build or upgrade a building (fields f1..f18 or an infrastructure building type) by one level", "tags": [ "towns" ], "operationId": "postTownsIdBuild", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "key" ], "properties": { "key": { "type": "string", "maxLength": 32, "pattern": "^[a-z0-9_]+$" } } } } } }, "security": [ { "bearer": [] } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildResult" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found, unknown_building", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: already_queued, max_level, not_buildable, not_enough_resources, queue_full, requirements_not_met", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/towns/{id}/queue/{eventId}": { "delete": { "summary": "Cancel a running build and get 80% of its cost back", "tags": [ "towns" ], "operationId": "deleteTownsIdQueueEventId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "eventId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/towns/{id}/rename": { "post": { "summary": "Rename a POP", "tags": [ "towns" ], "operationId": "postTownsIdRename", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 40 } } } } } }, "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "serverTime", "name" ], "properties": { "serverTime": { "type": "integer" }, "name": { "type": "string" } } } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/towns/{id}/research": { "post": { "summary": "Research +5% attack or defence for one unit type (one research at a time per POP, needs a Research lab)", "tags": [ "units" ], "operationId": "postTownsIdResearch", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "unit", "stat" ], "properties": { "unit": { "type": "string", "maxLength": 32, "pattern": "^[a-z_]+$" }, "stat": { "type": "string", "enum": [ "attack", "defence" ] } } } } } }, "security": [ { "bearer": [] } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchResult" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found, unknown_unit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: max_level, not_enough_resources, not_researchable, queue_full, requirements_not_met", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/towns/{id}/train": { "post": { "summary": "Queue a batch of one unit type. Batches of the same training building run in order; units appear when the batch is done", "tags": [ "units" ], "operationId": "postTownsIdTrain", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "unit", "count" ], "properties": { "unit": { "type": "string", "maxLength": 32, "pattern": "^[a-z_]+$" }, "count": { "type": "integer", "minimum": 1, "maximum": 5000 } } } } } }, "security": [ { "bearer": [] } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrainResult" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found, unknown_unit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: not_enough_resources, queue_full, requirements_not_met", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/towns/{id}/withdraw": { "post": { "summary": "Send reinforcements standing in this POP home (host kicks them out, or the units' owner calls them back)", "tags": [ "movements" ], "operationId": "postTownsIdWithdraw", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ownerTownId" ], "properties": { "ownerTownId": { "type": "integer", "minimum": 1 }, "units": { "type": "object", "additionalProperties": true, "description": "defaults to the whole group" } } } } } }, "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WithdrawResult" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found, unknown_unit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: not_enough_units", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trade/offers": { "get": { "summary": "Open offers you can take: within the offer's max distance and the reach of one of your Internet exchanges (newest first, cursor: after = last id seen)", "tags": [ "trade" ], "operationId": "getTradeOffers", "parameters": [ { "name": "worldId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "townId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "give", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "fiber", "hardware", "capital" ] } }, { "name": "want", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "fiber", "hardware", "capital" ] } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TradeOfferList" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Post an offer from one of your POPs: give X of A for Y of B within a max distance. The offered amount is escrowed and a transport link reserved", "tags": [ "trade" ], "operationId": "postTradeOffers", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "townId", "giveRes", "giveAmount", "wantRes", "wantAmount", "maxDistance" ], "properties": { "townId": { "type": "integer", "minimum": 1 }, "giveRes": { "type": "string", "enum": [ "fiber", "hardware", "capital" ] }, "giveAmount": { "type": "integer", "minimum": 1 }, "wantRes": { "type": "string", "enum": [ "fiber", "hardware", "capital" ] }, "wantAmount": { "type": "integer", "minimum": 1 }, "maxDistance": { "type": "integer", "minimum": 1, "maximum": 300 } } } } } }, "security": [ { "bearer": [] } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TradeOfferResponse" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: capacity_exceeded, no_transport_link, not_enough_resources, trade_ratio, world_ended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trade/offers/mine": { "get": { "summary": "Offers you posted or accepted, any status (newest first)", "tags": [ "trade" ], "operationId": "getTradeOffersMine", "parameters": [ { "name": "worldId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "accepted", "completed", "cancelled", "expired", "void" ] } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TradeOfferList" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trade/offers/{id}": { "get": { "summary": "One offer (open ones to every operator of the world, closed ones to the two parties)", "tags": [ "trade" ], "operationId": "getTradeOffersId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TradeOfferResponse" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Cancel your open offer; the escrow returns to the POP", "tags": [ "trade" ], "operationId": "deleteTradeOffersId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TradeCancelled" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: offer_closed, world_ended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trade/offers/{id}/accept": { "post": { "summary": "Take an open offer with one of your POPs: two transports leave at once (your payment, their goods) and the offer is settled when both arrive", "tags": [ "trade" ], "operationId": "postTradeOffersIdAccept", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "townId" ], "properties": { "townId": { "type": "integer", "minimum": 1 } } } } } }, "security": [ { "bearer": [] } ], "responses": { "201": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TradeAccepted" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error codes: capacity_exceeded, no_room_for_goods, no_transport_link, not_enough_resources, offer_closed, own_offer, trade_out_of_range, world_ended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: idempotency_key_reuse, validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/worlds/{id}/results": { "get": { "summary": "The final ranking snapshot (operators, alliances, attackers, defenders, winner); available once the world has ended", "tags": [ "world" ], "operationId": "getWorldsIdResults", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorldResults" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/worlds/{id}/status": { "get": { "summary": "The state of the world: phase (running, backbone_open, ended), world age, the landing sites with holder, node level, stockpile and build progress, the winner", "tags": [ "world" ], "operationId": "getWorldsIdStatus", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorldStatus" } } } }, "401": { "description": "Error codes: unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error codes: not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error codes: validation_failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error codes: internal_error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Cost": { "type": "object", "properties": { "fiber": { "type": "integer" }, "hardware": { "type": "integer" }, "capital": { "type": "integer" } }, "required": [ "fiber", "hardware", "capital" ], "additionalProperties": true }, "Error": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message", "details" ], "additionalProperties": true } }, "required": [ "serverTime", "error" ], "additionalProperties": true }, "World": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "speed": { "type": "number" }, "mapRadius": { "type": "integer" }, "seed": { "type": "integer" }, "startAt": { "type": "integer" }, "endAt": { "type": "integer", "nullable": true }, "status": { "type": "string" }, "preset": { "type": "string" } }, "required": [ "id", "name", "speed", "mapRadius", "seed", "startAt", "endAt", "status", "preset" ], "additionalProperties": true }, "TownSummary": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "x": { "type": "integer" }, "y": { "type": "integer" }, "isCapital": { "type": "boolean" } }, "required": [ "id", "name", "x", "y", "isCapital" ], "additionalProperties": true }, "Operator": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "asNumber": { "type": "integer" }, "allianceId": { "type": "integer", "nullable": true }, "alliance": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer" }, "tag": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": true }, "protectionUntil": { "type": "integer" }, "world": { "$ref": "#/components/schemas/World" }, "towns": { "type": "array", "items": { "$ref": "#/components/schemas/TownSummary" } } }, "required": [ "id", "name", "asNumber", "allianceId", "alliance", "protectionUntil", "world", "towns" ], "additionalProperties": true }, "Me": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "username": { "type": "string" }, "createdAt": { "type": "integer" } }, "required": [ "id", "username", "createdAt" ], "additionalProperties": true }, "operators": { "type": "array", "items": { "$ref": "#/components/schemas/Operator" } } }, "required": [ "serverTime", "user", "operators" ], "additionalProperties": true }, "AuthResult": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "token": { "type": "string" }, "tokenId": { "type": "integer" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "username": { "type": "string" } }, "required": [ "id", "username" ], "additionalProperties": true }, "operators": { "type": "array", "items": { "$ref": "#/components/schemas/Operator" } } }, "required": [ "serverTime", "token", "tokenId", "user", "operators" ], "additionalProperties": true }, "Token": { "type": "object", "properties": { "id": { "type": "integer" }, "device": { "type": "string" }, "createdAt": { "type": "integer" }, "lastUsedAt": { "type": "integer" }, "current": { "type": "boolean" } }, "required": [ "id", "device", "createdAt", "lastUsedAt", "current" ], "additionalProperties": true }, "BuildPlan": { "type": "object", "properties": { "ok": { "type": "boolean" }, "code": { "type": "string", "nullable": true }, "toLevel": { "type": "integer" }, "cost": { "$ref": "#/components/schemas/Cost" }, "durationMs": { "type": "integer" }, "missing": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "level": { "type": "integer" }, "have": { "type": "integer" } }, "required": [ "type", "level", "have" ], "additionalProperties": true } } }, "required": [ "ok", "code", "toLevel" ], "additionalProperties": true }, "BuildingView": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "type": "string" }, "kind": { "type": "string" }, "level": { "type": "integer" }, "maxLevel": { "type": "integer" }, "next": { "$ref": "#/components/schemas/BuildPlan" } }, "required": [ "key", "type", "kind", "level", "maxLevel", "next" ], "additionalProperties": true }, "QueueEntry": { "type": "object", "properties": { "id": { "type": "integer" }, "key": { "type": "string" }, "type": { "type": "string" }, "toLevel": { "type": "integer" }, "startedAt": { "type": "integer" }, "dueAt": { "type": "integer" } }, "required": [ "id", "key", "type", "toLevel", "startedAt", "dueAt" ], "additionalProperties": true }, "ResourceView": { "type": "object", "properties": { "amount": { "type": "number" }, "rate": { "type": "number" }, "cap": { "type": "number" } }, "required": [ "amount", "rate", "cap" ], "additionalProperties": true }, "Town": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "x": { "type": "integer" }, "y": { "type": "integer" }, "isCapital": { "type": "boolean" }, "ownerId": { "type": "integer" }, "worldId": { "type": "integer" }, "loyalty": { "type": "number" }, "footprint": { "type": "number" }, "footprintPerDay": { "type": "number" }, "resources": { "type": "object", "properties": { "fiber": { "$ref": "#/components/schemas/ResourceView" }, "hardware": { "$ref": "#/components/schemas/ResourceView" }, "capital": { "$ref": "#/components/schemas/ResourceView" } }, "required": [ "fiber", "hardware", "capital" ], "additionalProperties": true }, "power": { "type": "object", "properties": { "out": { "type": "number" }, "draw": { "type": "number" }, "net": { "type": "number" }, "buffer": { "type": "number" }, "bufferCap": { "type": "number" }, "bufferRate": { "type": "number" }, "online": { "type": "boolean" } }, "required": [ "out", "draw", "net", "buffer", "bufferCap", "bufferRate", "online" ], "additionalProperties": true }, "buildings": { "type": "array", "items": { "$ref": "#/components/schemas/BuildingView" } }, "queue": { "type": "array", "items": { "$ref": "#/components/schemas/QueueEntry" } }, "queueSlots": { "type": "integer" }, "bonus": { "type": "object", "properties": { "fiber": { "type": "number" }, "hardware": { "type": "number" }, "capital": { "type": "number" } }, "required": [ "fiber", "hardware", "capital" ], "additionalProperties": true }, "escrow": { "type": "object", "properties": { "fiber": { "type": "number" }, "hardware": { "type": "number" }, "capital": { "type": "number" } }, "required": [ "fiber", "hardware", "capital" ], "additionalProperties": true }, "military": { "$ref": "#/components/schemas/TownMilitary" } }, "required": [ "id", "name", "x", "y", "isCapital", "ownerId", "worldId", "loyalty", "footprint", "footprintPerDay", "resources", "power", "buildings", "queue", "queueSlots", "bonus", "escrow" ], "additionalProperties": true }, "TownResponse": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "town": { "$ref": "#/components/schemas/Town" } }, "required": [ "serverTime", "town" ], "additionalProperties": true }, "MapTown": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "x": { "type": "integer" }, "y": { "type": "integer" }, "isCapital": { "type": "boolean" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "asNumber": { "type": "integer" }, "allianceId": { "type": "integer", "nullable": true }, "alliance": { "type": "object", "nullable": true, "properties": { "id": { "type": "integer" }, "tag": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": true }, "protected": { "type": "boolean" } }, "required": [ "id", "name", "asNumber", "allianceId", "alliance", "protected" ], "additionalProperties": true } }, "required": [ "id", "name", "x", "y", "isCapital", "owner" ], "additionalProperties": true }, "MapSpecial": { "type": "object", "properties": { "x": { "type": "integer" }, "y": { "type": "integer" }, "type": { "type": "string" }, "bonus": { "type": "string", "nullable": true }, "site": { "type": "object", "additionalProperties": true } }, "required": [ "x", "y", "type", "bonus" ], "additionalProperties": true }, "MapResponse": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "world": { "$ref": "#/components/schemas/World" }, "bounds": { "type": "object", "properties": { "x0": { "type": "integer" }, "x1": { "type": "integer" }, "y0": { "type": "integer" }, "y1": { "type": "integer" } }, "required": [ "x0", "x1", "y0", "y1" ], "additionalProperties": true }, "specials": { "type": "array", "items": { "$ref": "#/components/schemas/MapSpecial" } }, "towns": { "type": "array", "items": { "$ref": "#/components/schemas/MapTown" } } }, "required": [ "serverTime", "world", "bounds", "specials", "towns" ], "additionalProperties": true }, "BuildResult": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "eventId": { "type": "integer" }, "key": { "type": "string" }, "type": { "type": "string" }, "toLevel": { "type": "integer" }, "startedAt": { "type": "integer" }, "dueAt": { "type": "integer" }, "cost": { "$ref": "#/components/schemas/Cost" } }, "required": [ "serverTime", "eventId", "key", "type", "toLevel", "startedAt", "dueAt", "cost" ], "additionalProperties": true }, "Notification": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "worldId": { "type": "integer", "nullable": true }, "payload": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "integer" }, "readAt": { "type": "integer", "nullable": true } }, "required": [ "id", "type", "worldId", "payload", "createdAt", "readAt" ], "additionalProperties": true }, "NotificationList": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Notification" } }, "next": { "type": "integer", "nullable": true } }, "required": [ "serverTime", "items", "next" ], "additionalProperties": true }, "AllianceBrief": { "type": "object", "properties": { "id": { "type": "integer" }, "tag": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "tag", "name" ], "additionalProperties": true }, "OperatorBrief": { "type": "object", "properties": { "operatorId": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "operatorId", "name" ], "additionalProperties": true }, "AllianceInfo": { "type": "object", "properties": { "id": { "type": "integer" }, "worldId": { "type": "integer" }, "name": { "type": "string" }, "tag": { "type": "string" }, "sizeCap": { "type": "integer" }, "memberCount": { "type": "integer" }, "leader": { "type": "object", "nullable": true, "additionalProperties": true }, "createdAt": { "type": "integer" } }, "required": [ "id", "worldId", "name", "tag", "sizeCap", "memberCount", "leader", "createdAt" ], "additionalProperties": true }, "AllianceDetail": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "alliance": { "$ref": "#/components/schemas/AllianceInfo" } }, "required": [ "serverTime", "alliance" ], "additionalProperties": true }, "AllianceMine": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "operatorId": { "type": "integer" }, "worldId": { "type": "integer" }, "alliance": { "type": "object", "nullable": true, "additionalProperties": true }, "role": { "type": "string", "nullable": true }, "permissions": { "type": "array", "items": { "type": "string" } }, "peeringLevel": { "type": "integer" } }, "required": [ "serverTime", "operatorId", "worldId", "alliance", "role", "permissions", "peeringLevel" ], "additionalProperties": true }, "AllianceList": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/AllianceInfo" } }, "next": { "type": "integer", "nullable": true } }, "required": [ "serverTime", "items", "next" ], "additionalProperties": true }, "AllianceMember": { "type": "object", "properties": { "operatorId": { "type": "integer" }, "name": { "type": "string" }, "asNumber": { "type": "integer" }, "role": { "type": "string" }, "joinedAt": { "type": "integer" }, "towns": { "type": "integer" }, "footprint": { "type": "number" }, "lastOnline": { "type": "integer", "nullable": true } }, "required": [ "operatorId", "name", "asNumber", "role", "joinedAt", "towns", "footprint", "lastOnline" ], "additionalProperties": true }, "AllianceMemberList": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/AllianceMember" } }, "next": { "type": "integer", "nullable": true } }, "required": [ "serverTime", "items", "next" ], "additionalProperties": true }, "AllianceCreated": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "allianceId": { "type": "integer" }, "name": { "type": "string" }, "tag": { "type": "string" }, "sizeCap": { "type": "integer" }, "role": { "type": "string" } }, "required": [ "serverTime", "allianceId", "name", "tag", "sizeCap", "role" ], "additionalProperties": true }, "AllianceInvite": { "type": "object", "properties": { "id": { "type": "integer" }, "operator": { "$ref": "#/components/schemas/OperatorBrief" }, "invitedBy": { "$ref": "#/components/schemas/OperatorBrief" }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" } }, "required": [ "id", "operator", "invitedBy", "createdAt", "expiresAt" ], "additionalProperties": true }, "AllianceInviteList": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/AllianceInvite" } }, "next": { "type": "integer", "nullable": true } }, "required": [ "serverTime", "items", "next" ], "additionalProperties": true }, "ReceivedInvite": { "type": "object", "properties": { "id": { "type": "integer" }, "operatorId": { "type": "integer" }, "alliance": { "$ref": "#/components/schemas/AllianceBrief" }, "invitedBy": { "$ref": "#/components/schemas/OperatorBrief" }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" } }, "required": [ "id", "operatorId", "alliance", "invitedBy", "createdAt", "expiresAt" ], "additionalProperties": true }, "ReceivedInviteList": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ReceivedInvite" } }, "next": { "type": "integer", "nullable": true } }, "required": [ "serverTime", "items", "next" ], "additionalProperties": true }, "InviteResult": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "inviteId": { "type": "integer" }, "operatorId": { "type": "integer" }, "expiresAt": { "type": "integer" }, "changed": { "type": "boolean" } }, "required": [ "serverTime", "inviteId", "operatorId", "expiresAt", "changed" ], "additionalProperties": true }, "Changed": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "changed": { "type": "boolean" } }, "required": [ "serverTime", "changed" ], "additionalProperties": true }, "AllianceNote": { "type": "object", "properties": { "id": { "type": "integer" }, "authorId": { "type": "integer" }, "text": { "type": "string" }, "createdAt": { "type": "integer" }, "updatedAt": { "type": "integer" } }, "required": [ "id", "authorId", "text", "createdAt", "updatedAt" ], "additionalProperties": true }, "AllianceNoteResponse": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "note": { "$ref": "#/components/schemas/AllianceNote" } }, "required": [ "serverTime", "note" ], "additionalProperties": true }, "AllianceNoteList": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/AllianceNote" } }, "next": { "type": "integer", "nullable": true } }, "required": [ "serverTime", "items", "next" ], "additionalProperties": true }, "Relation": { "type": "object", "properties": { "other": { "type": "object", "additionalProperties": true }, "state": { "type": "string" }, "since": { "type": "integer" }, "pending": { "type": "object", "nullable": true, "additionalProperties": true } }, "required": [ "other", "state", "since", "pending" ], "additionalProperties": true }, "Proposal": { "type": "object", "properties": { "id": { "type": "integer" }, "other": { "type": "object", "additionalProperties": true }, "state": { "type": "string" }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" } }, "required": [ "id", "other", "state", "createdAt", "expiresAt" ], "additionalProperties": true }, "Diplomacy": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "allianceId": { "type": "integer" }, "relations": { "type": "array", "items": { "$ref": "#/components/schemas/Relation" } }, "proposalsIn": { "type": "array", "items": { "$ref": "#/components/schemas/Proposal" } }, "proposalsOut": { "type": "array", "items": { "$ref": "#/components/schemas/Proposal" } } }, "required": [ "serverTime", "allianceId", "relations", "proposalsIn", "proposalsOut" ], "additionalProperties": true }, "DiplomacyResult": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "result": { "type": "string" }, "from": { "type": "string" }, "state": { "type": "string" } }, "required": [ "serverTime", "result", "from", "state" ], "additionalProperties": true }, "Message": { "type": "object", "properties": { "id": { "type": "integer" }, "kind": { "type": "string" }, "direction": { "type": "string" }, "thread": { "type": "string" }, "from": { "$ref": "#/components/schemas/OperatorBrief" }, "to": { "type": "object", "nullable": true, "additionalProperties": true }, "alliance": { "type": "object", "nullable": true, "additionalProperties": true }, "text": { "type": "string" }, "createdAt": { "type": "integer" }, "readAt": { "type": "integer", "nullable": true } }, "required": [ "id", "kind", "direction", "thread", "from", "to", "alliance", "text", "createdAt", "readAt" ], "additionalProperties": true }, "MessageList": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "next": { "type": "integer", "nullable": true }, "unread": { "type": "integer" } }, "required": [ "serverTime", "items", "next" ], "additionalProperties": true }, "MessageResponse": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "message": { "$ref": "#/components/schemas/Message" } }, "required": [ "serverTime", "message" ], "additionalProperties": true }, "MessageSent": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "messageId": { "type": "integer" }, "kind": { "type": "string" }, "recipients": { "type": "integer" }, "createdAt": { "type": "integer" } }, "required": [ "serverTime", "messageId", "kind", "recipients", "createdAt" ], "additionalProperties": true }, "BlockList": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "operatorId": { "type": "integer" }, "name": { "type": "string" }, "createdAt": { "type": "integer" } }, "required": [ "operatorId", "name", "createdAt" ], "additionalProperties": true } }, "next": { "type": "integer", "nullable": true } }, "required": [ "serverTime", "items", "next" ], "additionalProperties": true }, "RankOperator": { "type": "object", "properties": { "rank": { "type": "integer" }, "operatorId": { "type": "integer" }, "name": { "type": "string" }, "asNumber": { "type": "integer" }, "allianceId": { "type": "integer", "nullable": true }, "allianceTag": { "type": "string", "nullable": true }, "towns": { "type": "integer" }, "footprint": { "type": "number" } }, "required": [ "rank", "operatorId", "name", "asNumber", "allianceId", "allianceTag", "towns", "footprint" ], "additionalProperties": true }, "RankAlliance": { "type": "object", "properties": { "rank": { "type": "integer" }, "allianceId": { "type": "integer" }, "name": { "type": "string" }, "tag": { "type": "string" }, "members": { "type": "integer" }, "towns": { "type": "integer" }, "footprint": { "type": "number" } }, "required": [ "rank", "allianceId", "name", "tag", "members", "towns", "footprint" ], "additionalProperties": true }, "RankBattle": { "type": "object", "properties": { "rank": { "type": "integer" }, "operatorId": { "type": "integer" }, "name": { "type": "string" }, "allianceTag": { "type": "string", "nullable": true }, "attackPoints": { "type": "number" }, "defensePoints": { "type": "number" } }, "required": [ "rank", "operatorId", "name", "allianceTag", "attackPoints", "defensePoints" ], "additionalProperties": true }, "RankOperators": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "total": { "type": "integer" }, "you": { "type": "object", "nullable": true, "additionalProperties": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/RankOperator" } }, "next": { "type": "integer", "nullable": true } }, "required": [ "serverTime", "total", "you", "items", "next" ], "additionalProperties": true }, "RankAlliances": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "total": { "type": "integer" }, "you": { "type": "object", "nullable": true, "additionalProperties": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/RankAlliance" } }, "next": { "type": "integer", "nullable": true } }, "required": [ "serverTime", "total", "you", "items", "next" ], "additionalProperties": true }, "RankBattles": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "by": { "type": "string" }, "available": { "type": "boolean" }, "total": { "type": "integer" }, "you": { "type": "object", "nullable": true, "additionalProperties": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/RankBattle" } }, "next": { "type": "integer", "nullable": true } }, "required": [ "serverTime", "by", "available", "total", "you", "items", "next" ], "additionalProperties": true }, "Ok": { "type": "object", "properties": { "serverTime": { "type": "integer" } }, "required": [ "serverTime" ], "additionalProperties": true }, "Units": { "type": "object", "additionalProperties": true, "description": "unit id -> count" }, "TrainResult": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "eventId": { "type": "integer" }, "unit": { "type": "string" }, "count": { "type": "integer" }, "building": { "type": "string" }, "startAt": { "type": "integer" }, "dueAt": { "type": "integer" }, "cost": { "$ref": "#/components/schemas/Cost" } }, "required": [ "serverTime", "eventId", "unit", "count", "building", "startAt", "dueAt", "cost" ], "additionalProperties": true }, "ResearchResult": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "eventId": { "type": "integer" }, "unit": { "type": "string" }, "stat": { "type": "string" }, "toLevel": { "type": "integer" }, "startedAt": { "type": "integer" }, "dueAt": { "type": "integer" }, "cost": { "$ref": "#/components/schemas/Cost" } }, "required": [ "serverTime", "eventId", "unit", "stat", "toLevel", "startedAt", "dueAt", "cost" ], "additionalProperties": true }, "MovementSent": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "movementId": { "type": "integer" }, "type": { "type": "string" }, "fromTownId": { "type": "integer" }, "toTownId": { "type": "integer", "nullable": true }, "to": { "type": "object", "properties": { "x": { "type": "integer" }, "y": { "type": "integer" } }, "required": [ "x", "y" ], "additionalProperties": true }, "units": { "type": "object", "additionalProperties": true, "description": "unit id -> count" }, "cargo": { "type": "object", "additionalProperties": true }, "departAt": { "type": "integer" }, "arriveAt": { "type": "integer" }, "protectionEnded": { "type": "boolean" } }, "required": [ "serverTime", "movementId", "type", "fromTownId", "toTownId", "departAt", "arriveAt" ], "additionalProperties": true }, "RecallResult": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "recalled": { "type": "integer" }, "returnMovementId": { "type": "integer" }, "arriveAt": { "type": "integer" } }, "required": [ "serverTime", "recalled", "returnMovementId", "arriveAt" ], "additionalProperties": true }, "WithdrawResult": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "movementId": { "type": "integer" }, "units": { "type": "object", "additionalProperties": true, "description": "unit id -> count" }, "arriveAt": { "type": "integer" } }, "required": [ "serverTime", "movementId", "units", "arriveAt" ], "additionalProperties": true }, "MovementEnd": { "type": "object", "properties": { "townId": { "type": "integer", "nullable": true }, "x": { "type": "integer" }, "y": { "type": "integer" }, "name": { "type": "string", "nullable": true }, "owner": { "type": "object", "nullable": true, "additionalProperties": true } }, "required": [ "townId", "x", "y" ], "additionalProperties": true }, "Movement": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "status": { "type": "string" }, "ownerId": { "type": "integer" }, "from": { "$ref": "#/components/schemas/MovementEnd" }, "to": { "$ref": "#/components/schemas/MovementEnd" }, "units": { "type": "object", "additionalProperties": true, "description": "unit id -> count" }, "cargo": { "type": "object", "additionalProperties": true }, "departAt": { "type": "integer" }, "arriveAt": { "type": "integer" }, "recallableUntil": { "type": "integer", "nullable": true }, "target": { "type": "string", "nullable": true }, "parentId": { "type": "integer", "nullable": true }, "incoming": { "type": "boolean" } }, "required": [ "id", "type", "status", "from", "to", "departAt", "arriveAt" ], "additionalProperties": true }, "MovementList": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "outgoing": { "type": "array", "items": { "$ref": "#/components/schemas/Movement" } }, "incoming": { "type": "array", "items": { "$ref": "#/components/schemas/Movement" } }, "alliedIncoming": { "type": "array", "items": { "$ref": "#/components/schemas/Movement" } } }, "required": [ "serverTime", "outgoing", "incoming" ], "additionalProperties": true }, "Marked": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "marked": { "type": "integer" } }, "required": [ "serverTime", "marked" ], "additionalProperties": true }, "ReportItem": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "createdAt": { "type": "integer" }, "role": { "type": "string" }, "read": { "type": "boolean" }, "summary": { "type": "object", "additionalProperties": true } }, "required": [ "id", "type", "createdAt", "role", "read", "summary" ], "additionalProperties": true }, "ReportList": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ReportItem" } }, "next": { "type": "integer", "nullable": true }, "unread": { "type": "integer" } }, "required": [ "serverTime", "items", "next", "unread" ], "additionalProperties": true }, "Report": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" }, "role": { "type": "string" }, "read": { "type": "boolean" }, "summary": { "type": "object", "additionalProperties": true }, "data": { "type": "object", "additionalProperties": true } }, "required": [ "id", "type", "createdAt", "expiresAt", "role", "read", "summary", "data" ], "additionalProperties": true }, "ReportResponse": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "report": { "$ref": "#/components/schemas/Report" } }, "required": [ "serverTime", "report" ], "additionalProperties": true }, "TileInfo": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "x": { "type": "integer" }, "y": { "type": "integer" }, "type": { "type": "string" }, "bonus": { "type": "string", "nullable": true }, "distances": { "type": "array", "items": { "type": "object", "properties": { "townId": { "type": "integer" }, "distance": { "type": "number" } }, "required": [ "townId", "distance" ], "additionalProperties": true } }, "town": { "type": "object", "additionalProperties": true }, "incumbent": { "type": "object", "additionalProperties": true }, "settle": { "type": "object", "properties": { "possible": { "type": "boolean" }, "code": { "type": "string", "nullable": true }, "footprint": { "type": "number" }, "footprintNeeded": { "type": "number" }, "maxDistance": { "type": "integer" } }, "required": [ "possible", "code", "footprint", "footprintNeeded", "maxDistance" ], "additionalProperties": true } }, "required": [ "serverTime", "x", "y", "type", "distances", "settle" ], "additionalProperties": true }, "TownMilitary": { "type": "object", "properties": { "units": { "type": "object", "properties": { "home": { "type": "object", "additionalProperties": true, "description": "unit id -> count" }, "online": { "type": "boolean" }, "offlineSince": { "type": "integer", "nullable": true }, "stationedHere": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "stationedAway": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "garrisoned": { "type": "array", "items": { "type": "object", "properties": { "siteId": { "type": "integer" }, "x": { "type": "integer" }, "y": { "type": "integer" }, "units": { "type": "object", "additionalProperties": true, "description": "unit id -> count" } }, "required": [ "siteId", "x", "y", "units" ], "additionalProperties": true } } }, "required": [ "home", "online", "offlineSince", "stationedHere", "stationedAway", "garrisoned" ], "additionalProperties": true }, "training": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "unit": { "type": "string" }, "count": { "type": "integer" }, "building": { "type": "string" }, "startAt": { "type": "integer" }, "dueAt": { "type": "integer" } }, "required": [ "id", "unit", "count", "building", "startAt", "dueAt" ], "additionalProperties": true } }, "trainable": { "type": "array", "items": { "type": "object", "properties": { "unit": { "type": "string" }, "building": { "type": "string" }, "role": { "type": "string" }, "cost": { "$ref": "#/components/schemas/Cost" }, "timeMs": { "type": "integer" }, "missing": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "locked": { "type": "boolean" } }, "required": [ "unit", "building", "role", "cost", "timeMs", "missing", "locked" ], "additionalProperties": true } }, "research": { "type": "object", "properties": { "levels": { "type": "object", "additionalProperties": true }, "queue": { "type": "object", "nullable": true, "additionalProperties": true }, "speedBonus": { "type": "number" }, "maxLevel": { "type": "integer" } }, "required": [ "levels", "queue", "speedBonus", "maxLevel" ], "additionalProperties": true }, "transport": { "type": "object", "properties": { "links": { "type": "integer" }, "active": { "type": "integer" }, "capacityPerLink": { "type": "integer" } }, "required": [ "links", "active", "capacityPerLink" ], "additionalProperties": true }, "movements": { "type": "object", "properties": { "outgoing": { "type": "array", "items": { "$ref": "#/components/schemas/Movement" } }, "incoming": { "type": "array", "items": { "$ref": "#/components/schemas/Movement" } } }, "required": [ "outgoing", "incoming" ], "additionalProperties": true }, "protectionUntil": { "type": "integer" } }, "required": [ "units", "training", "trainable", "research", "transport", "movements", "protectionUntil" ], "additionalProperties": true }, "TradeAmount": { "type": "object", "properties": { "resource": { "type": "string" }, "amount": { "type": "integer" } }, "required": [ "resource", "amount" ], "additionalProperties": true }, "TradeOffer": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "worldId": { "type": "integer" }, "townId": { "type": "integer" }, "townName": { "type": "string", "nullable": true }, "x": { "type": "integer", "nullable": true }, "y": { "type": "integer", "nullable": true }, "operator": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "nullable": true } }, "required": [ "id", "name" ], "additionalProperties": true }, "give": { "$ref": "#/components/schemas/TradeAmount" }, "want": { "$ref": "#/components/schemas/TradeAmount" }, "maxDistance": { "type": "integer" }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" }, "acceptedAt": { "type": "integer", "nullable": true }, "closedAt": { "type": "integer", "nullable": true }, "role": { "type": "string" }, "acceptableFrom": { "type": "array", "items": { "type": "object", "properties": { "townId": { "type": "integer" }, "distance": { "type": "number" } }, "required": [ "townId", "distance" ], "additionalProperties": true } } }, "required": [ "id", "status", "townId", "operator", "give", "want", "maxDistance", "createdAt", "expiresAt" ], "additionalProperties": true }, "TradeOfferList": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/TradeOffer" } }, "next": { "type": "integer", "nullable": true }, "exchangeLevels": { "type": "array", "items": { "type": "object", "properties": { "townId": { "type": "integer" }, "level": { "type": "integer" }, "reach": { "type": "number" } }, "required": [ "townId", "level", "reach" ], "additionalProperties": true } } }, "required": [ "serverTime", "items", "next" ], "additionalProperties": true }, "TradeOfferResponse": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "offer": { "$ref": "#/components/schemas/TradeOffer" } }, "required": [ "serverTime", "offer" ], "additionalProperties": true }, "TradeCancelled": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "offerId": { "type": "integer" }, "status": { "type": "string" }, "returned": { "$ref": "#/components/schemas/TradeAmount" } }, "required": [ "serverTime", "offerId", "status", "returned" ], "additionalProperties": true }, "TradeAccepted": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "offerId": { "type": "integer" }, "status": { "type": "string" }, "goodsMovementId": { "type": "integer" }, "paymentMovementId": { "type": "integer" }, "distance": { "type": "number" }, "arriveAt": { "type": "integer" }, "give": { "$ref": "#/components/schemas/TradeAmount" }, "want": { "$ref": "#/components/schemas/TradeAmount" } }, "required": [ "serverTime", "offerId", "status", "goodsMovementId", "paymentMovementId", "distance", "arriveAt", "give", "want" ], "additionalProperties": true }, "LandingSite": { "type": "object", "properties": { "id": { "type": "integer", "nullable": true }, "index": { "type": "integer" }, "x": { "type": "integer" }, "y": { "type": "integer" }, "holder": { "type": "object", "nullable": true, "properties": { "allianceId": { "type": "integer" }, "tag": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": true }, "takenBy": { "type": "object", "nullable": true, "additionalProperties": true }, "takenAt": { "type": "integer", "nullable": true }, "shieldUntil": { "type": "integer", "nullable": true }, "level": { "type": "integer" }, "maxLevel": { "type": "integer" }, "progress": { "type": "number" }, "pool": { "$ref": "#/components/schemas/Cost" }, "build": { "type": "object", "nullable": true, "properties": { "toLevel": { "type": "integer" }, "startedAt": { "type": "integer" }, "dueAt": { "type": "integer" } }, "additionalProperties": true }, "next": { "type": "object", "nullable": true, "properties": { "toLevel": { "type": "integer" }, "cost": { "$ref": "#/components/schemas/Cost" }, "durationMs": { "type": "integer" } }, "additionalProperties": true } }, "required": [ "id", "index", "x", "y", "holder", "takenBy", "takenAt", "shieldUntil", "level", "maxLevel", "progress", "pool", "build", "next" ], "additionalProperties": true }, "WorldStatus": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "worldId": { "type": "integer" }, "name": { "type": "string" }, "speed": { "type": "number" }, "status": { "type": "string" }, "phase": { "type": "string" }, "ageDays": { "type": "number" }, "openDay": { "type": "integer" }, "opensAt": { "type": "integer" }, "sites": { "type": "array", "items": { "$ref": "#/components/schemas/LandingSite" } }, "winner": { "type": "object", "nullable": true, "additionalProperties": true }, "endsAt": { "type": "integer", "nullable": true }, "endedAt": { "type": "integer", "nullable": true } }, "required": [ "serverTime", "worldId", "name", "speed", "status", "phase", "ageDays", "openDay", "opensAt", "sites", "winner", "endsAt", "endedAt" ], "additionalProperties": true }, "WorldResults": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "available": { "type": "boolean" }, "status": { "type": "string" }, "winner": { "type": "object", "nullable": true, "additionalProperties": true }, "endsAt": { "type": "integer", "nullable": true }, "results": { "type": "object", "nullable": true, "additionalProperties": true } }, "required": [ "serverTime", "available", "status", "winner", "endsAt", "results" ], "additionalProperties": true }, "LandingSiteResponse": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "site": { "$ref": "#/components/schemas/LandingSite" }, "you": { "type": "object", "properties": { "holder": { "type": "boolean" }, "canBuild": { "type": "boolean" }, "canShip": { "type": "boolean" }, "canAttack": { "type": "boolean" }, "canReinforce": { "type": "boolean" } }, "required": [ "holder", "canBuild", "canShip", "canAttack", "canReinforce" ], "additionalProperties": true }, "contributions": { "type": "array", "items": { "type": "object", "properties": { "operatorId": { "type": "integer" }, "name": { "type": "string" }, "fiber": { "type": "integer" }, "hardware": { "type": "integer" }, "capital": { "type": "integer" } }, "required": [ "operatorId", "name", "fiber", "hardware", "capital" ], "additionalProperties": true } }, "defence": { "type": "object", "properties": { "static": { "type": "number" }, "garrison": { "type": "number" }, "total": { "type": "number" } }, "required": [ "static", "garrison", "total" ], "additionalProperties": true }, "garrison": { "type": "array", "items": { "type": "object", "properties": { "ownerTownId": { "type": "integer" }, "townName": { "type": "string", "nullable": true }, "operator": { "type": "object", "nullable": true, "additionalProperties": true }, "units": { "type": "object", "additionalProperties": true }, "online": { "type": "boolean" }, "power": { "type": "number" }, "mine": { "type": "boolean" } }, "required": [ "ownerTownId", "townName", "operator", "units", "online", "power", "mine" ], "additionalProperties": true } } }, "required": [ "serverTime", "site", "you" ], "additionalProperties": true }, "GarrisonWithdrawn": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "movementId": { "type": "integer" }, "siteId": { "type": "integer" }, "fromTownId": { "type": "integer" }, "units": { "type": "object", "additionalProperties": true }, "arriveAt": { "type": "integer" } }, "required": [ "serverTime", "movementId", "siteId", "fromTownId", "units", "arriveAt" ], "additionalProperties": true }, "BackboneBuildStarted": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "siteId": { "type": "integer" }, "eventId": { "type": "integer" }, "toLevel": { "type": "integer" }, "startedAt": { "type": "integer" }, "dueAt": { "type": "integer" }, "cost": { "$ref": "#/components/schemas/Cost" } }, "required": [ "serverTime", "siteId", "eventId", "toLevel", "startedAt", "dueAt", "cost" ], "additionalProperties": true }, "ReportShared": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "changed": { "type": "boolean" }, "reportId": { "type": "integer" }, "allianceId": { "type": "integer" } }, "required": [ "serverTime", "changed", "reportId", "allianceId" ], "additionalProperties": true }, "SharedReportItem": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "createdAt": { "type": "integer" }, "sharedAt": { "type": "integer" }, "sharedBy": { "type": "object", "properties": { "operatorId": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "operatorId", "name" ], "additionalProperties": true }, "summary": { "type": "object", "additionalProperties": true } }, "required": [ "id", "type", "createdAt", "sharedAt", "sharedBy", "summary" ], "additionalProperties": true }, "SharedReportList": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SharedReportItem" } }, "next": { "type": "integer", "nullable": true } }, "required": [ "serverTime", "items", "next" ], "additionalProperties": true }, "SharedReport": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" }, "sharedAt": { "type": "integer" }, "sharedBy": { "type": "object", "properties": { "operatorId": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "operatorId", "name" ], "additionalProperties": true }, "summary": { "type": "object", "additionalProperties": true }, "data": { "type": "object", "additionalProperties": true } }, "required": [ "id", "type", "createdAt", "expiresAt", "sharedAt", "sharedBy", "summary", "data" ], "additionalProperties": true }, "SharedReportResponse": { "type": "object", "properties": { "serverTime": { "type": "integer" }, "report": { "$ref": "#/components/schemas/SharedReport" } }, "required": [ "serverTime", "report" ], "additionalProperties": true } }, "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "Opaque device token from /auth/login or /auth/signup" } } }, "x-error-codes": { "bad_request": { "status": 400, "description": "The request could not be parsed." }, "validation_failed": { "status": 422, "description": "A field is missing or has the wrong shape." }, "unauthorized": { "status": 401, "description": "Missing, invalid or revoked token." }, "invalid_credentials": { "status": 401, "description": "Wrong username or password." }, "forbidden": { "status": 403, "description": "You may not do that." }, "not_found": { "status": 404, "description": "No such thing." }, "method_not_allowed": { "status": 405, "description": "Wrong HTTP method for this path." }, "conflict": { "status": 409, "description": "The request conflicts with the current state." }, "request_in_progress": { "status": 409, "description": "A request with this Idempotency-Key is still running." }, "idempotency_key_reuse": { "status": 422, "description": "This Idempotency-Key was used for a different request." }, "payload_too_large": { "status": 413, "description": "Request body too large." }, "rate_limited": { "status": 429, "description": "Too many requests, slow down." }, "internal_error": { "status": 500, "description": "Something broke on our side." }, "signup_closed": { "status": 403, "description": "Signup needs a valid invite code." }, "username_taken": { "status": 409, "description": "That username is taken." }, "world_full": { "status": 409, "description": "There is no room left on the map." }, "unknown_building": { "status": 404, "description": "No such building or slot." }, "not_buildable": { "status": 409, "description": "That building cannot be built here." }, "max_level": { "status": 409, "description": "Already at the maximum level." }, "requirements_not_met": { "status": 409, "description": "A required building level is missing." }, "already_queued": { "status": 409, "description": "That building is already being built." }, "queue_full": { "status": 409, "description": "All build slots are busy." }, "not_enough_resources": { "status": 409, "description": "Not enough resources." }, "peering_office_required": { "status": 409, "description": "A Peering office (level 1 or higher) is needed to found or join an alliance." }, "already_in_alliance": { "status": 409, "description": "That operator is already in an alliance." }, "not_in_alliance": { "status": 409, "description": "You are not in that alliance." }, "alliance_name_taken": { "status": 409, "description": "That alliance name is taken." }, "alliance_tag_taken": { "status": 409, "description": "That alliance tag is taken." }, "alliance_full": { "status": 409, "description": "The alliance has no room for more members." }, "invite_expired": { "status": 409, "description": "The invite has expired." }, "leader_must_transfer": { "status": 409, "description": "The leader must hand over leadership before leaving." }, "notes_full": { "status": 409, "description": "The alliance has reached its pinned-note limit." }, "diplomacy_invalid": { "status": 409, "description": "That diplomatic move is not allowed from the current state." }, "diplomacy_pending": { "status": 409, "description": "A diplomatic change between these alliances is already scheduled." }, "proposal_exists": { "status": 409, "description": "The other alliance already proposed this; accept their proposal instead." }, "proposal_expired": { "status": 409, "description": "The proposal has expired." }, "unknown_unit": { "status": 404, "description": "No such unit type." }, "not_researchable": { "status": 409, "description": "That unit stat cannot be researched." }, "not_enough_units": { "status": 409, "description": "Not enough units at home." }, "units_offline": { "status": 409, "description": "Those units are offline (the battery is empty)." }, "invalid_target": { "status": 409, "description": "That target is not valid for this kind of movement." }, "target_protected": { "status": 409, "description": "The target is under beginner protection." }, "protection_active": { "status": 409, "description": "Attacking ends your beginner protection; confirm to go ahead." }, "out_of_range": { "status": 409, "description": "The target is too far from your POPs." }, "footprint_too_low": { "status": 409, "description": "Your footprint is too low for another POP." }, "cannot_takeover": { "status": 409, "description": "That POP cannot be taken over." }, "recall_expired": { "status": 409, "description": "The recall window (first 90 seconds) has passed." }, "capacity_exceeded": { "status": 409, "description": "More than one transport link can carry." }, "no_transport_link": { "status": 409, "description": "All transport links are busy (or there is no Internet exchange)." }, "trade_ratio": { "status": 409, "description": "The offered and the wanted amount may differ by at most 1:2." }, "offer_closed": { "status": 409, "description": "That offer is not open any more." }, "own_offer": { "status": 409, "description": "You cannot accept your own offer." }, "trade_out_of_range": { "status": 409, "description": "That POP is too far from the offer (its max distance or your Internet exchange reach)." }, "no_room_for_goods": { "status": 409, "description": "Your Rack hall will not have room for the goods when they arrive; make room (spend, or raise the hall) and accept again." }, "world_ended": { "status": 409, "description": "This world has ended: it can still be read, but nothing can be changed." }, "backbone_closed": { "status": 409, "description": "The backbone landing sites have not appeared yet." } } }