{ "openapi": "3.0.0", "info": { "contact": { "email": "joel@spacetraders.io", "name": "Joel Brubaker" }, "description": "SpaceTraders is an open-universe game and learning platform that offers a set of HTTP endpoints to control a fleet of ships and explore a multiplayer universe.\n\nThe API is documented using [OpenAPI](https://github.com/SpaceTradersAPI/api-docs). You can send your first request right here in your browser to check the status of the game server.\n\n```json http\n{\n \"method\": \"GET\",\n \"url\": \"https://api.spacetraders.io/v2\",\n}\n```\n\nUnlike a traditional game, SpaceTraders does not have a first-party client or app to play the game. Instead, you can use the API to build your own client, write a script to automate your ships, or try an app built by the community.\n\nWe have a [Discord channel](https://discord.com/invite/jh6zurdWk5) where you can share your projects, ask questions, and get help from other players.\n\n\n", "license": { "name": "No Permission", "url": "https://choosealicense.com/no-permission/" }, "title": "SpaceTraders API", "version": "2.0.0" }, "security": [ { "AgentToken": [] } ], "servers": [ { "description": "v2", "url": "https://api.spacetraders.io/v2" } ], "tags": [ { "description": "Agents", "name": "Agents" }, { "description": "Contracts", "name": "Contracts" }, { "description": "Factions", "name": "Factions" }, { "description": "Fleet", "name": "Fleet" }, { "description": "Systems", "name": "Systems" } ], "components": { "requestBodies": {}, "schemas": {}, "securitySchemes": { "AgentToken": { "description": "When you register a new agent you will be granted a private bearer token which grants authorization to use the API.", "scheme": "bearer", "type": "http" } } }, "paths": { "/": { "get": { "description": "Return the status of the game server.\nThis also includes a few global elements, such as announcements, server reset dates and leaderboards.", "operationId": "get-status", "responses": { "200": { "content": { "application/json": { "schema": { "description": "OK", "properties": { "status": { "type": "string", "description": "The current status of the game server." }, "version": { "type": "string", "description": "The current version of the API." }, "resetDate": { "type": "string", "description": "The date and time when the game server was last reset." }, "description": { "type": "string" }, "stats": { "type": "object", "properties": { "agents": { "type": "integer" }, "ships": { "type": "integer" }, "systems": { "type": "integer" }, "waypoints": { "type": "integer" } }, "required": [ "agents", "ships", "systems", "waypoints" ] }, "leaderboards": { "type": "object", "properties": { "mostCredits": { "type": "array", "items": { "type": "object", "properties": { "agentSymbol": { "type": "string" }, "credits": { "type": "integer", "format": "int64" } }, "required": [ "agentSymbol", "credits" ] } }, "mostSubmittedCharts": { "type": "array", "items": { "type": "object", "properties": { "agentSymbol": { "type": "string" }, "chartCount": { "type": "integer" } }, "required": [ "agentSymbol", "chartCount" ] } } }, "required": [ "mostCredits", "mostSubmittedCharts" ] }, "serverResets": { "type": "object", "properties": { "next": { "type": "string", "description": "The date and time when the game server will reset." }, "frequency": { "type": "string", "description": "How often we intend to reset the game server." } }, "required": [ "next", "frequency" ] }, "announcements": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "body": { "type": "string" } }, "required": [ "title", "body" ] } }, "links": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" } }, "required": [ "name", "url" ] } } }, "required": [ "status", "version", "resetDate", "description", "stats", "leaderboards", "serverResets", "announcements", "links" ], "type": "object" } } }, "description": "OK" } }, "summary": "Get Status", "tags": [], "security": [] } }, "/register": { "post": { "description": "Creates a new agent and ties it to an account.\n\nThe agent symbol must consist of a 3-14 character string, and will be used to represent your agent. This symbol will prefix the symbol of every ship you own. Agent symbols will be cast to all uppercase characters.\n\nThis new agent will be tied to a starting faction of your choice, which determines your starting location, and will be granted an authorization token, a contract with their starting faction, a command ship that can fly across space with advanced capabilities, a small probe ship that can be used for reconnaissance, and 150,000 credits.\n\n> #### Keep your token safe and secure\n>\n> Save your token during the alpha phase. There is no way to regenerate this token without starting a new agent. In the future you will be able to generate and manage your tokens from the SpaceTraders website.\n\nIf you are new to SpaceTraders, It is recommended to register with the COSMIC faction, a faction that is well connected to the rest of the universe. After registering, you should try our interactive [quickstart guide](https://docs.spacetraders.io/quickstart/new-game) which will walk you through basic API requests in just a few minutes.", "operationId": "register", "requestBody": { "content": { "application/json": { "schema": { "properties": { "faction": { "$ref": "../models/FactionSymbols.json", "example": "COSMIC" }, "symbol": { "description": "Your desired agent symbol. This will be a unique name used to represent your agent, and will be the prefix for your ships.", "example": "BADGER", "maxLength": 14, "minLength": 3, "type": "string" }, "email": { "type": "string", "description": "Your email address. This is used if you reserved your call sign between resets." } }, "required": [ "symbol", "faction" ], "type": "object" } } }, "description": "" }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "agent": { "$ref": "../models/Agent.json" }, "contract": { "$ref": "../models/Contract.json" }, "faction": { "$ref": "../models/Faction.json" }, "ship": { "$ref": "../models/Ship.json" }, "token": { "description": "A Bearer token for accessing secured API endpoints.", "type": "string" } }, "required": [ "token", "agent", "faction", "contract", "ship" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "OK" } }, "summary": "Register New Agent", "tags": [], "security": [] } }, "/systems": { "get": { "description": "Return a paginated list of all systems.", "operationId": "get-systems", "responses": { "200": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "items": { "$ref": "../models/System.json" }, "type": "array" }, "meta": { "$ref": "../models/Meta.json" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "OK" } }, "security": [ {}, {"AgentToken": []} ], "summary": "List Systems", "tags": [ "Systems" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1 }, "in": "query", "name": "page", "description": "What entry offset to request" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 20 }, "in": "query", "name": "limit", "description": "How many entries to return per page" } ] } }, "/systems/{systemSymbol}": { "get": { "description": "Get the details of a system.", "operationId": "get-system", "responses": { "200": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "$ref": "../models/System.json" } }, "required": [ "data" ], "type": "object" } } }, "description": "OK" } }, "security": [ {}, {"AgentToken": []} ], "summary": "Get System", "tags": [ "Systems" ] }, "parameters": [ { "description": "The system symbol", "in": "path", "name": "systemSymbol", "required": true, "schema": { "default": "X1-OE", "type": "string" } } ] }, "/systems/{systemSymbol}/waypoints": { "get": { "description": "Return a paginated list of all of the waypoints for a given system.\n\nIf a waypoint is uncharted, it will return the 'Uncharted' trait instead of its actual traits.", "operationId": "get-system-waypoints", "responses": { "200": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "items": { "$ref": "../models/Waypoint.json" }, "type": "array" }, "meta": { "$ref": "../models/Meta.json" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "OK" } }, "security": [ {}, {"AgentToken": []} ], "summary": "List Waypoints in System", "tags": [ "Systems" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1 }, "in": "query", "name": "page", "description": "What entry offset to request" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 20 }, "in": "query", "name": "limit", "description": "How many entries to return per page" } ] }, "parameters": [ { "description": "The system symbol", "in": "path", "name": "systemSymbol", "required": true, "schema": { "type": "string" } } ] }, "/systems/{systemSymbol}/waypoints/{waypointSymbol}": { "get": { "description": "View the details of a waypoint.\n\nIf the waypoint is uncharted, it will return the 'Uncharted' trait instead of its actual traits.", "operationId": "get-waypoint", "responses": { "200": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "$ref": "../models/Waypoint.json" } }, "required": [ "data" ], "type": "object" } } }, "description": "OK" } }, "security": [ {}, {"AgentToken": []} ], "summary": "Get Waypoint", "tags": [ "Systems" ] }, "parameters": [ { "description": "The system symbol", "in": "path", "name": "systemSymbol", "required": true, "schema": { "type": "string" } }, { "description": "The waypoint symbol", "in": "path", "name": "waypointSymbol", "required": true, "schema": { "type": "string" } } ] }, "/systems/{systemSymbol}/waypoints/{waypointSymbol}/market": { "get": { "description": "Retrieve imports, exports and exchange data from a marketplace. Requires a waypoint that has the 'Marketplace' trait to use.\n\nSend a ship to the waypoint to access trade good prices and recent transactions. Refer to the [Market Tutorial page](https://docs.spacetraders.io/game-concepts/markets) to gain better a understanding of the market in the game.", "operationId": "get-market", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "../models/Market.json" } }, "required": [ "data" ], "type": "object" } } }, "description": "OK" } }, "security": [ {}, {"AgentToken": []} ], "summary": "Get Market", "tags": [ "Systems" ] }, "parameters": [ { "description": "The system symbol", "in": "path", "name": "systemSymbol", "required": true, "schema": { "type": "string" } }, { "description": "The waypoint symbol", "in": "path", "name": "waypointSymbol", "required": true, "schema": { "type": "string" } } ] }, "/systems/{systemSymbol}/waypoints/{waypointSymbol}/shipyard": { "get": { "description": "Get the shipyard for a waypoint. Requires a waypoint that has the 'Shipyard' trait to use. Send a ship to the waypoint to access data on ships that are currently available for purchase and recent transactions.", "operationId": "get-shipyard", "responses": { "200": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "$ref": "../models/Shipyard.json" } }, "required": [ "data" ], "type": "object" } } }, "description": "OK" } }, "security": [ {}, {"AgentToken": []} ], "summary": "Get Shipyard", "tags": [ "Systems" ] }, "parameters": [ { "description": "The system symbol", "in": "path", "name": "systemSymbol", "required": true, "schema": { "type": "string" } }, { "description": "The waypoint symbol", "in": "path", "name": "waypointSymbol", "required": true, "schema": { "type": "string" } } ] }, "/systems/{systemSymbol}/waypoints/{waypointSymbol}/jump-gate": { "get": { "description": "Get jump gate details for a waypoint. Requires a waypoint of type 'JUMP_GATE' to use.\n\nThe response will return all systems that are have a Jump Gate in range of this Jump Gate and can be jumped to from this jump gate.", "operationId": "get-jump-gate", "responses": { "200": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "$ref": "../models/JumpGate.json" } }, "required": [ "data" ], "type": "object" } } }, "description": "OK" } }, "security": [ {}, {"AgentToken": []} ], "summary": "Get Jump Gate", "tags": [ "Systems" ] }, "parameters": [ { "description": "The system symbol", "in": "path", "name": "systemSymbol", "required": true, "schema": { "type": "string" } }, { "description": "The waypoint symbol", "in": "path", "name": "waypointSymbol", "required": true, "schema": { "type": "string" } } ] }, "/factions": { "get": { "description": "Return a paginated list of all the factions in the game.", "operationId": "get-factions", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "../models/Faction.json" }, "type": "array" }, "meta": { "$ref": "../models/Meta.json" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "" } }, "summary": "List Factions", "tags": [ "Factions" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1 }, "in": "query", "name": "page", "description": "What entry offset to request" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 20 }, "in": "query", "name": "limit", "description": "How many entries to return per page" } ] } }, "/factions/{factionSymbol}": { "get": { "description": "View the details of a faction.", "operationId": "get-faction", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "../models/Faction.json" } }, "required": [ "data" ], "type": "object" } } }, "description": "OK" } }, "summary": "Get Faction", "tags": [ "Factions" ] }, "parameters": [ { "description": "The faction symbol", "in": "path", "name": "factionSymbol", "required": true, "schema": { "default": "CGR", "type": "string" } } ] }, "/my/agent": { "get": { "description": "Fetch your agent's details.", "operationId": "get-my-agent", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "../models/Agent.json" } }, "required": [ "data" ], "type": "object" } } }, "description": "OK" } }, "security": [ { "AgentToken": [] } ], "summary": "Get Agent", "tags": [ "Agents" ] } }, "/my/contracts": { "get": { "description": "Return a paginated list of all your contracts.", "operationId": "get-contracts", "responses": { "200": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "items": { "$ref": "../models/Contract.json" }, "type": "array" }, "meta": { "$ref": "../models/Meta.json" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "OK" } }, "security": [ { "AgentToken": [] } ], "summary": "List Contracts", "tags": [ "Contracts" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1 }, "in": "query", "name": "page", "description": "What entry offset to request" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 20 }, "in": "query", "name": "limit", "description": "How many entries to return per page" } ] } }, "/my/contracts/{contractId}": { "get": { "description": "Get the details of a contract by ID.", "operationId": "get-contract", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "../models/Contract.json" } }, "required": [ "data" ], "type": "object" } } }, "description": "OK" } }, "security": [ { "AgentToken": [] } ], "summary": "Get Contract", "tags": [ "Contracts" ] }, "parameters": [ { "description": "The contract ID", "in": "path", "name": "contractId", "required": true, "schema": { "type": "string" } } ] }, "/my/contracts/{contractId}/accept": { "parameters": [ { "description": "The contract ID to accept.", "in": "path", "name": "contractId", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Accept a contract.", "operationId": "accept-contract", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "agent": { "$ref": "../models/Agent.json" }, "contract": { "$ref": "../models/Contract.json" } }, "required": [ "contract", "agent" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "OK" } }, "security": [ { "AgentToken": [] } ], "summary": "Accept Contract", "tags": [ "Contracts" ] } }, "/my/contracts/{contractId}/deliver": { "parameters": [ { "description": "The contract ID to deliver cargo to", "in": "path", "name": "contractId", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Deliver cargo on a given contract.\n\nIn order to use this API, a ship must be at the delivery location (denoted in the delivery terms as 'destinationSymbol' of a contract) and must have the specific amount of units of a good required by this contract in its cargo.\n\nDelivered cargo will be removed from the ship's cargo.", "operationId": "deliver-contract", "requestBody": { "content": { "application/json": { "schema": { "properties": { "shipSymbol": { "type": "string", "description": "Symbol of a ship located in the destination to deliver a contract and that has a good to deliver in its cargo." }, "tradeSymbol": { "type": "string", "description": "The symbol of the good to deliver." }, "units": { "type": "integer", "description": "Amount of units to deliver." } }, "required": [ "shipSymbol", "tradeSymbol", "units" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "properties": { "contract": { "$ref": "../models/Contract.json" }, "cargo": { "$ref": "../models/ShipCargo.json" } }, "required": [ "contract", "cargo" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "OK" } }, "security": [ { "AgentToken": [] } ], "summary": "Deliver Cargo to Contract", "tags": [ "Contracts" ] } }, "/my/contracts/{contractId}/fulfill": { "parameters": [ { "description": "The ID of the contract to fulfill", "in": "path", "name": "contractId", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Fulfill a contract. Can only be used on contracts that have all of their delivery terms fulfilled.", "operationId": "fulfill-contract", "responses": { "200": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "properties": { "agent": { "$ref": "../models/Agent.json" }, "contract": { "$ref": "../models/Contract.json" } }, "required": [ "contract", "agent" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "OK" } }, "security": [ { "AgentToken": [] } ], "summary": "Fulfill Contract", "tags": [ "Contracts" ] } }, "/my/ships": { "get": { "description": "Return a paginated list of all of ships under your agent's ownership.", "operationId": "get-my-ships", "responses": { "200": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "items": { "$ref": "../models/Ship.json" }, "type": "array" }, "meta": { "$ref": "../models/Meta.json" } }, "required": [ "data", "meta" ], "type": "object" } } }, "description": "OK" } }, "security": [ { "AgentToken": [] } ], "summary": "List Ships", "tags": [ "Fleet" ], "parameters": [ { "schema": { "type": "integer", "minimum": 1 }, "in": "query", "name": "page", "description": "What entry offset to request" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 20 }, "in": "query", "name": "limit", "description": "How many entries to return per page" } ] }, "post": { "description": "Purchase a ship from a Shipyard. In order to use this API, a ship you own must be in a waypoint that has the 'Shipyard' trait, and the Shipyard must sell the type of the desired ship.\n\nShipyards typically offer ship types, which are predefined templates of ships that have dedicated roles.", "operationId": "purchase-ship", "requestBody": { "content": { "application/json": { "schema": { "properties": { "shipType": { "$ref": "../models/ShipType.json" }, "waypointSymbol": { "description": "The symbol of the waypoint you want to purchase the ship at.", "type": "string" } }, "required": [ "shipType", "waypointSymbol" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "properties": { "agent": { "$ref": "../models/Agent.json" }, "ship": { "$ref": "../models/Ship.json" }, "transaction": { "$ref": "../models/ShipyardTransaction.json" } }, "required": [ "ship", "agent", "transaction" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Created" } }, "security": [ { "AgentToken": [] } ], "summary": "Purchase Ship", "tags": [ "Fleet" ] } }, "/my/ships/{shipSymbol}": { "get": { "description": "Retrieve the details of a ship under your agent's ownership.", "operationId": "get-my-ship", "responses": { "200": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "$ref": "../models/Ship.json" } }, "required": [ "data" ], "type": "object" } } }, "description": "OK" } }, "security": [ { "AgentToken": [] } ], "summary": "Get Ship", "tags": [ "Fleet" ] }, "parameters": [ { "description": "The symbol of the ship.", "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ] }, "/my/ships/{shipSymbol}/cargo": { "parameters": [ { "description": "The symbol of the ship.", "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ], "get": { "description": "Retrieve the cargo of your ship.", "operationId": "get-my-ship-cargo", "responses": { "200": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "$ref": "../models/ShipCargo.json" } }, "required": [ "data" ], "type": "object" } } }, "description": "OK" } }, "security": [ { "AgentToken": [] } ], "summary": "Get Ship Cargo", "tags": [ "Fleet" ] } }, "/my/ships/{shipSymbol}/orbit": { "parameters": [ { "description": "The symbol of the ship.", "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Attempt to move your ship into orbit at its current location. The request will only succeed if your ship is capable of moving into orbit at the time of the request.\n\nOrbiting ships are able to do actions that require the ship to be above surface such as navigating or extracting, but cannot access elements in their current location, such as the market or a shipyard.\n\nThe endpoint is idempotent - successive calls will succeed even if the ship is already in orbit.", "operationId": "orbit-ship", "responses": { "200": { "content": { "application/json": { "schema": { "title": "Orbit Ship 200 Response", "description": "", "properties": { "data": { "properties": { "nav": { "$ref": "../models/ShipNav.json" } }, "type": "object", "required": [ "nav" ] } }, "required": [ "data" ], "type": "object" } } }, "description": "The ship has successfully moved into orbit at its current location." } }, "security": [ { "AgentToken": [] } ], "summary": "Orbit Ship", "tags": [ "Fleet" ] } }, "/my/ships/{shipSymbol}/refine": { "parameters": [ { "description": "The symbol of the ship.", "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Attempt to refine the raw materials on your ship. The request will only succeed if your ship is capable of refining at the time of the request. In order to be able to refine, a ship must have goods that can be refined and have a 'Refinery' module that can refine it.\n\nWhen refining, 30 basic goods will be converted into 10 processed goods.", "operationId": "ship-refine", "requestBody": { "content": { "application/json": { "schema": { "properties": { "produce": { "description": "The goods to produce out of the refining process.", "type": "string", "enum": [ "IRON", "COPPER", "SILVER", "GOLD", "ALUMINUM", "PLATINUM", "URANITE", "MERITIUM", "FUEL" ] } }, "required": [ "produce" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "title": "Ship Refine 200 Response", "description": "", "properties": { "data": { "properties": { "cargo": { "$ref": "../models/ShipCargo.json" }, "cooldown": { "$ref": "../models/Cooldown.json" }, "produced": { "type": "array", "items": { "type": "object", "properties": { "tradeSymbol": { "type": "string" }, "units": { "type": "integer" } } } }, "consumed": { "type": "array", "items": { "type": "object", "properties": { "tradeSymbol": { "type": "string" }, "units": { "type": "integer" } } } } }, "type": "object", "required": [ "cargo", "cooldown", "produced", "consumed" ] } }, "required": [ "data" ], "type": "object" } } }, "description": "The ship has successfully refined goods." } }, "security": [ { "AgentToken": [] } ], "summary": "Ship Refine", "tags": [ "Fleet" ] } }, "/my/ships/{shipSymbol}/chart": { "parameters": [ { "description": "The symbol of the ship.", "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Command a ship to chart the current waypoint.\n\nMost waypoints in the universe are uncharted by default. These waypoints have their traits hidden until they have been charted by a ship.\n\nCharting a waypoint will record your agent as the one who created the chart.", "operationId": "create-chart", "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "chart": { "$ref": "../models/Chart.json" }, "waypoint": { "$ref": "../models/Waypoint.json" } }, "required": [ "chart", "waypoint" ], "type": "object" } }, "type": "object", "required": [ "data" ] } } }, "description": "Created" } }, "security": [ { "AgentToken": [] } ], "summary": "Create Chart", "tags": [ "Fleet" ] } }, "/my/ships/{shipSymbol}/cooldown": { "get": { "description": "Retrieve the details of your ship's reactor cooldown. Some actions such as activating your jump drive, scanning, or extracting resources taxes your reactor and results in a cooldown.\n\nYour ship cannot perform additional actions until your cooldown has expired. The duration of your cooldown is relative to the power consumption of the related modules or mounts for the action taken.\n\nResponse returns a 204 status code (no-content) when the ship has no cooldown.", "operationId": "get-ship-cooldown", "responses": { "200": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "$ref": "../models/Cooldown.json" } }, "required": [ "data" ], "type": "object" } } }, "description": "OK" }, "204": { "description": "No cooldown." } }, "security": [ { "AgentToken": [] } ], "summary": "Get Ship Cooldown", "tags": [ "Fleet" ] }, "parameters": [ { "description": "The symbol of the ship.", "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ] }, "/my/ships/{shipSymbol}/dock": { "parameters": [ { "description": "The symbol of the ship.", "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Attempt to dock your ship at its current location. Docking will only succeed if the waypoint is a dockable location, and your ship is capable of docking at the time of the request.\n\nDocked ships can access elements in their current location, such as the market or a shipyard, but cannot do actions that require the ship to be above surface such as navigating or extracting.\n\nThe endpoint is idempotent - successive calls will succeed even if the ship is already docked.", "operationId": "dock-ship", "responses": { "200": { "content": { "application/json": { "schema": { "title": "Dock Ship 200 Response", "description": "", "properties": { "data": { "properties": { "nav": { "$ref": "../models/ShipNav.json" } }, "required": [ "nav" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The ship has successfully docked at its current location." } }, "security": [ { "AgentToken": [] } ], "summary": "Dock Ship", "tags": [ "Fleet" ] } }, "/my/ships/{shipSymbol}/survey": { "parameters": [ { "description": "The symbol of the ship", "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Create a survey on a waypoint that can be extracted such as asteroid fields. A survey focuses on specific types of deposits from the extracted location. When ships extract using this survey, they are guaranteed to procure a high amount of one of the goods in the survey.\n\nIn order to use the survey, send the entire survey details in the body of the extract request.\n\nEach survey may have multiple deposits, and if a symbol shows up more than once, that indicates a higher chance of extracting that resource.\n\nYour ship will enter a cooldown after surveying in which it is unable to perform certain actions. Surveys will eventually expire after a period of time or will be exhausted after being extracted several times. Multiple ships can use the same survey for extraction.\n\nA ship must have the 'Surveyor' mount in order to use this function.", "operationId": "create-survey", "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "cooldown": { "$ref": "../models/Cooldown.json" }, "surveys": { "items": { "$ref": "../models/Survey.json" }, "type": "array" } }, "required": [ "surveys", "cooldown" ], "type": "object" } }, "type": "object", "required": [ "data" ] } } }, "description": "Created" } }, "security": [ { "AgentToken": [] } ], "summary": "Create Survey", "tags": [ "Fleet" ] } }, "/my/ships/{shipSymbol}/extract": { "parameters": [ { "description": "The ship symbol.", "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Extract resources from the waypoint into your ship. Send an optional survey as the payload to target specific yields.\n\nThe ship must be in orbit to be able to extract.", "operationId": "extract-resources", "requestBody": { "content": { "application/json": { "schema": { "properties": { "survey": { "$ref": "../models/Survey.json" } }, "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "properties": { "cooldown": { "$ref": "../models/Cooldown.json" }, "extraction": { "$ref": "../models/Extraction.json" }, "cargo": { "$ref": "../models/ShipCargo.json" } }, "required": [ "extraction", "cooldown", "cargo" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Created" } }, "security": [ { "AgentToken": [] } ], "summary": "Extract Resources", "tags": [ "Fleet" ] } }, "/my/ships/{shipSymbol}/jettison": { "parameters": [ { "description": "The ship symbol.", "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Jettison cargo from your ship's cargo hold.\n\nCargo that was jettison is lost and cannot be fetched again by any means.", "operationId": "jettison", "requestBody": { "content": { "application/json": { "schema": { "properties": { "symbol": { "type": "string" }, "units": { "minimum": 1, "type": "integer" } }, "required": [ "symbol", "units" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "properties": { "cargo": { "$ref": "../models/ShipCargo.json" } }, "required": [ "cargo" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "OK" } }, "security": [ { "AgentToken": [] } ], "summary": "Jettison Cargo", "tags": [ "Fleet" ] } }, "/my/ships/{shipSymbol}/jump": { "parameters": [ { "description": "The ship symbol.", "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Jump your ship instantly to a target system. The ship must be in orbit to use this function. When used while in orbit of a Jump Gate waypoint, any ship can use this command and end up on the target system's Jump Gate waypoint. When used elsewhere, jumping requires the ship to have a Jump Drive module and consumes a unit of antimatter from the ship's cargo. The command will fail if there is no antimatter to consume.", "operationId": "jump-ship", "requestBody": { "content": { "application/json": { "schema": { "properties": { "systemSymbol": { "description": "The system symbol to jump to.", "type": "string" } }, "required": [ "systemSymbol" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "properties": { "cooldown": { "$ref": "../models/Cooldown.json" }, "nav": { "$ref": "../models/ShipNav.json" } }, "required": [ "nav", "cooldown" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "OK" } }, "security": [ { "AgentToken": [] } ], "summary": "Jump Ship", "tags": [ "Fleet" ] } }, "/my/ships/{shipSymbol}/navigate": { "parameters": [ { "description": "The ship symbol.", "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Navigate to a target destination. The ship must be in orbit to use this function. The destination waypoint must be within the same system as the ship. Navigating will consume the necessary fuel from the ship's manifest based on the distance to the target waypoint.\n\nThe returned response will detail the route information including the expected time of arrival. Most ship actions are unavailable until the ship has arrived at it's destination.\n\nTo travel between systems, see the ship's warp or jump actions.", "operationId": "navigate-ship", "requestBody": { "content": { "application/json": { "schema": { "properties": { "waypointSymbol": { "description": "The target destination.", "type": "string" } }, "required": [ "waypointSymbol" ], "type": "object" } } }, "description": "" }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "properties": { "fuel": { "$ref": "../models/ShipFuel.json" }, "nav": { "$ref": "../models/ShipNav.json" } }, "required": [ "nav", "fuel" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The successful transit information including the route details and changes to ship fuel. The route includes the expected time of arrival." } }, "security": [ { "AgentToken": [] } ], "summary": "Navigate Ship", "tags": [ "Fleet" ] } }, "/my/ships/{shipSymbol}/nav": { "parameters": [ { "description": "The ship symbol.", "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ], "patch": { "description": "Update the nav configuration of a ship.\n\nCurrently only supports configuring the Flight Mode of the ship, which affects its speed and fuel consumption.", "operationId": "patch-ship-nav", "requestBody": { "content": { "application/json": { "schema": { "properties": { "flightMode": { "$ref": "../models/ShipNavFlightMode.json" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "$ref": "../models/ShipNav.json" } }, "required": [ "data" ], "type": "object" } } }, "description": "The updated nav data of the ship." } }, "security": [ { "AgentToken": [] } ], "summary": "Patch Ship Nav", "tags": [ "Fleet" ] }, "get": { "description": "Get the current nav status of a ship.", "operationId": "get-ship-nav", "responses": { "200": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "$ref": "../models/ShipNav.json" } }, "required": [ "data" ], "type": "object" } } }, "description": "The current nav status of the ship." } }, "security": [ { "AgentToken": [] } ], "summary": "Get Ship Nav", "tags": [ "Fleet" ] } }, "/my/ships/{shipSymbol}/warp": { "parameters": [ { "description": "The ship symbol.", "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Warp your ship to a target destination in another system. The ship must be in orbit to use this function. Warping will consume the necessary fuel from the ship's manifest.\n\nThe returned response will detail the route information including the expected time of arrival. Most ship actions are unavailable until the ship has arrived at it's destination.", "operationId": "warp-ship", "requestBody": { "content": { "application/json": { "schema": { "properties": { "waypointSymbol": { "description": "The target destination.", "type": "string" } }, "required": [ "waypointSymbol" ], "type": "object" } } }, "description": "" }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "properties": { "fuel": { "$ref": "../models/ShipFuel.json" }, "nav": { "$ref": "../models/ShipNav.json" } }, "required": [ "nav", "fuel" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "The successful transit information including the route details and changes to ship fuel. The route includes the expected time of arrival." } }, "security": [ { "AgentToken": [] } ], "summary": "Warp Ship", "tags": [ "Fleet" ] } }, "/my/ships/{shipSymbol}/sell": { "parameters": [ { "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Sell cargo in your ship to a market that trades this cargo. The ship must be docked in a waypoint that has the 'Marketplace' trait in order to use this function.", "operationId": "sell-cargo", "requestBody": { "content": { "application/json": { "schema": { "title": "SellCargoRequest", "properties": { "symbol": { "type": "string" }, "units": { "type": "integer" } }, "required": [ "symbol", "units" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "title": "Sell Cargo 201 Response", "description": "", "properties": { "data": { "properties": { "agent": { "$ref": "../models/Agent.json" }, "cargo": { "$ref": "../models/ShipCargo.json" }, "transaction": { "$ref": "../models/MarketTransaction.json" } }, "required": [ "cargo", "transaction", "agent" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Created" } }, "security": [ { "AgentToken": [] } ], "summary": "Sell Cargo", "tags": [ "Fleet" ] } }, "/my/ships/{shipSymbol}/scan/systems": { "parameters": [ { "description": "The ship symbol.", "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Scan for nearby systems, retrieving information on the systems' distance from the ship and their waypoints. Requires a ship to have the 'Sensor Array' mount to use.\n\nThe ship will enter a cooldown after using this function.", "operationId": "create-ship-system-scan", "responses": { "201": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "properties": { "cooldown": { "$ref": "../models/Cooldown.json" }, "systems": { "items": { "$ref": "../models/ScannedSystem.json" }, "type": "array" } }, "required": [ "cooldown", "systems" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Successfully scanned for nearby systems." } }, "security": [ { "AgentToken": [] } ], "summary": "Scan Systems", "tags": [ "Fleet" ] } }, "/my/ships/{shipSymbol}/scan/waypoints": { "parameters": [ { "description": "The ship symbol.", "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Scan for nearby waypoints, retrieving detailed information on each waypoint in range. Scanning uncharted waypoints will allow you to ignore their uncharted state and will list the waypoints' traits.\n\nRequires a ship to have the 'Sensor Array' mount to use.\n\nThe ship will enter a cooldown after using this function.", "operationId": "create-ship-waypoint-scan", "responses": { "201": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "properties": { "cooldown": { "$ref": "../models/Cooldown.json" }, "waypoints": { "items": { "$ref": "../models/ScannedWaypoint.json" }, "type": "array" } }, "required": [ "cooldown", "waypoints" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Successfully scanned for nearby waypoints." } }, "security": [ { "AgentToken": [] } ], "summary": "Scan Waypoints", "tags": [ "Fleet" ] } }, "/my/ships/{shipSymbol}/scan/ships": { "parameters": [ { "description": "The ship symbol.", "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Scan for nearby ships, retrieving information for all ships in rnage.\n\nRequires a ship to have the 'Sensor Array' mount to use.\n\nThe ship will enter a cooldown after using this function.", "operationId": "create-ship-ship-scan", "responses": { "201": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "properties": { "cooldown": { "$ref": "../models/Cooldown.json" }, "ships": { "items": { "$ref": "../models/ScannedShip.json" }, "type": "array" } }, "required": [ "cooldown", "ships" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Successfully scanned for nearby ships." } }, "security": [ { "AgentToken": [] } ], "summary": "Scan Ships", "tags": [ "Fleet" ] } }, "/my/ships/{shipSymbol}/refuel": { "parameters": [ { "description": "The ship symbol.", "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Refuel your ship by buying fuel from the local market.\n\nRequires the ship to be docked in a waypoint that has the 'Marketplace' trait, and the market must be selling fuel in order to refuel.\n\nEach fuel bought from the market replenishes 100 units in your ship's fuel.\n\nShips will always be refuel to the maximum amount when using this action.", "operationId": "refuel-ship", "responses": { "200": { "content": { "application/json": { "schema": { "description": "", "properties": { "data": { "properties": { "agent": { "$ref": "../models/Agent.json" }, "fuel": { "$ref": "../models/ShipFuel.json" }, "transaction": { "$ref": "../models/MarketTransaction.json" } }, "required": [ "agent", "fuel", "transaction" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Refueled successfully." } }, "security": [ { "AgentToken": [] } ], "summary": "Refuel Ship", "tags": [ "Fleet" ] } }, "/my/ships/{shipSymbol}/purchase": { "parameters": [ { "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Purchase cargo.", "operationId": "purchase-cargo", "requestBody": { "content": { "application/json": { "schema": { "title": "Purchase Cargo Request", "properties": { "symbol": { "type": "string" }, "units": { "type": "integer" } }, "required": [ "symbol", "units" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "title": "Purchase Cargo 201 Response", "description": "", "properties": { "data": { "properties": { "agent": { "$ref": "../models/Agent.json" }, "cargo": { "$ref": "../models/ShipCargo.json" }, "transaction": { "$ref": "../models/MarketTransaction.json" } }, "required": [ "cargo", "transaction", "agent" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Created" } }, "security": [ { "AgentToken": [] } ], "summary": "Purchase Cargo", "tags": [ "Fleet" ] } }, "/my/ships/{shipSymbol}/transfer": { "parameters": [ { "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Transfer cargo between ships.", "operationId": "transfer-cargo", "requestBody": { "content": { "application/json": { "schema": { "title": "Transfer Cargo Request", "properties": { "tradeSymbol": { "type": "string" }, "units": { "type": "integer" }, "shipSymbol": { "type": "string" } }, "required": [ "tradeSymbol", "units", "shipSymbol" ], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "title": "Transfer Cargo 200 Response", "description": "", "properties": { "data": { "properties": { "cargo": { "$ref": "../models/ShipCargo.json" } }, "required": [ "cargo" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Created" } }, "security": [ { "AgentToken": [] } ], "summary": "Transfer Cargo", "tags": [ "Fleet" ] } }, "/my/ships/{shipSymbol}/negotiate/contract": { "parameters": [ { "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ], "post": { "description": "", "operationId": "negotiateContract", "requestBody": { "content": { "application/json": { "schema": {} } } }, "responses": { "201": { "content": { "application/json": { "schema": { "title": "Negotiate Contract 200 Response", "description": "", "properties": { "data": { "properties": { "contract": { "$ref": "../models/Contract.json" } }, "required": [ "contract" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Created" } }, "security": [ { "AgentToken": [] } ], "summary": "Negotiate Contract", "tags": [ "Fleet" ] } }, "/my/ships/{shipSymbol}/mounts": { "parameters": [ { "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ], "get": { "description": "Get the mounts on a ship.", "operationId": "get-mounts", "responses": { "200": { "content": { "application/json": { "schema": { "title": "Get Mounts 200 Response", "description": "", "properties": { "data": { "items": { "$ref": "../models/ShipMount.json" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "OK" } }, "security": [ { "AgentToken": [] } ], "summary": "Get Mounts", "tags": [ "Fleet" ] } }, "/my/ships/{shipSymbol}/mounts/install": { "parameters": [ { "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Install a mount on a ship.", "operationId": "install-mount", "requestBody": { "content": { "application/json": { "schema": { "title": "Install Mount Request", "properties": { "symbol": { "type": "string" } }, "required": [ "symbol" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "title": "Install Mount 201 Response", "description": "", "properties": { "data": { "properties": { "agent": { "$ref": "../models/Agent.json" }, "mounts": { "type": "array", "items": { "$ref": "../models/ShipMount.json" } }, "cargo": { "$ref": "../models/ShipCargo.json" }, "transaction": { "properties": { "totalPrice": { "type": "integer", "description": "The total price of the transaction.", "minimum": 0 }, "timestamp": { "type": "string", "format": "date-time", "description": "The timestamp of the transaction." } }, "required": [ "totalPrice", "timestamp" ] } }, "required": [ "agent", "mounts", "cargo", "transaction" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Created" } }, "security": [ { "AgentToken": [] } ], "summary": "Install Mount", "tags": [ "Fleet" ] } }, "/my/ships/{shipSymbol}/mounts/remove": { "parameters": [ { "in": "path", "name": "shipSymbol", "required": true, "schema": { "type": "string" } } ], "post": { "description": "Remove a mount from a ship.", "operationId": "remove-mount", "requestBody": { "content": { "application/json": { "schema": { "title": "Remove Mount Request", "properties": { "symbol": { "type": "string" } }, "required": [ "symbol" ], "type": "object" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "title": "Remove Mount 201 Response", "description": "", "properties": { "data": { "properties": { "agent": { "$ref": "../models/Agent.json" }, "mounts": { "type": "array", "items": { "$ref": "../models/ShipMount.json" } }, "cargo": { "$ref": "../models/ShipCargo.json" }, "transaction": { "properties": { "totalPrice": { "type": "integer", "description": "The total price of the transaction.", "minimum": 0 }, "timestamp": { "type": "string", "format": "date-time", "description": "The timestamp of the transaction." } }, "required": [ "totalPrice", "timestamp" ] } }, "required": [ "agent", "mounts", "cargo", "transaction" ], "type": "object" } }, "required": [ "data" ], "type": "object" } } }, "description": "Created" } }, "security": [ { "AgentToken": [] } ], "summary": "Remove Mount", "tags": [ "Fleet" ] } } } }