Commander, HTTP, and machine-readable guides¶
Choose a surface¶
| Surface | Use it for | Important limit |
|---|---|---|
| Terminal | Everyday play, slash commands, live fleet and queue views | Item keys stay English |
| Browser | Enrollment, account security, alliance HQ, messages, reports, planet rename/removal, public rankings | It is not a full browser build-and-dispatch client |
| Commander MCP | Assistant access to the authenticated game | Tools depend on enabled permission tiers |
| Player HTTP API | A custom client using the same game services | Authentication and ownership checks still apply |
| Discord | Linked identity, community roles, and configured notifications | Separate bot, not a game sign-in method |
Use the Commander setup guide, the exact tool contract, and its JSON download. The tool list comes from a real MCP handshake during tests. A running older process can expose a different list until restarted.
Commander workflow¶
- Read
empire_overviewfor current bodies, queues, fleets, and notices. - Read
codexandresearch_treefor keys, costs, and completed prerequisites. - Select the intended planet explicitly when an input accepts it.
- Submit one authorized purchase or mission.
- Read the affected state before another order or a retry.
The read tier limits available tools but does not imply zero server-side bookkeeping. Planet reads settle elapsed production. Quest reads can pay rewards. The galaxy tool belongs to the spend tier because navigation can spend ten deuterium. The server applies those same rules to every client.
Do not run independent writers against one empire without coordination. A tool response describes one moment. Another terminal or assistant can spend the same visible resources before your next request. The server enforces the final balance and locks.
Abandonment uses preview_abandon_planet followed by abandon_planet with its fresh confirmation material and explicit confirmation. A preview is not authorization to abandon. Other destructive operations retain their normal game effects even when an assistant submits them.
HTTP session and transport¶
The base is https://terminal.army. Player API routes use /api/v1. Send the session in Authorization: Bearer <session-token>. Send JSON bodies with Content-Type: application/json. Do not place a token in a URL or public documentation.
Device sign-in starts with POST /auth/start. It returns the browser authorization information. POST /auth/poll accepts the device code until approval or expiry. /auth/me and /api/v1/me read the authenticated identity. Prefer the device flow for interactive clients. Raw password registration/login endpoints exist but require the server's account and two-factor rules.
The route inventory is generated from the mounted router. The request and data types preserve actual JSON field names. They describe shape, not permission or all validation. omitempty does not mean an input is optional. Read the relevant game chapter for limits.
GET /api/v1/events is server-sent events (SSE), not a WebSocket. Maintain one connection, reconnect after disconnection, and reread authoritative state. A stream notification is a reason to refresh, not a complete replacement for that state.
Common writes¶
P, Q, F, A, and T below stand for actual planet, queue, fleet, ACS, and trade IDs.
| Action | Method and path | JSON body |
|---|---|---|
| Upgrade | POST /api/v1/planets/P/buildings |
{"building":"metal_mine"} |
| Build ships | POST /api/v1/planets/P/shipyard |
{"ship":"small_cargo","count":1} |
| Build defense | POST /api/v1/planets/P/defense |
{"defense":"rocket_launcher","count":1} |
| Research | POST /api/v1/research/ |
{"planet_id":P,"tech":"energy"} |
| Cancel queue | DELETE /api/v1/queues/Q |
None |
| Recall | POST /api/v1/fleet/F/recall |
None |
| Create ACS | POST /api/v1/fleet/acs |
{"fleet_id":F} |
| Invite ACS member | POST /api/v1/fleet/acs/A/invite |
{"username":"friend"} |
| Accept trade | POST /api/v1/trades/T/accept |
{"planet_id":P} |
| Cancel open trade | DELETE /api/v1/trades/T |
None |
| Production boost | POST /api/v1/darkmatter/boost |
{"planet_id":P} |
| Rush | POST /api/v1/darkmatter/rush |
{"queue_id":Q} |
| Rename | POST /api/v1/darkmatter/rename |
{"planet_id":P,"name":"New Dawn"} |
The symbolic IDs make the table a schema example, not directly executable JSON. Read /planets/, /queues, and /fleet/ to get real IDs.
Fleet dispatch uses POST /api/v1/fleet/ and svc.FleetDispatchRequest in the wire reference. It names origin_planet_id, target galaxy/system/position, mission, ship counts, cargo, speed, target body, and optional ACS/hold parameters. The terminal /deploy command uses the same deploy mission.
Trade search uses GET /api/v1/trades/?planet_id=P. Optional filters are offered, wanted, scope, max_hours, mine=true, and sort=distance. List results are capped at 200. Create uses the complete TradeCreateRequest structure. Acceptance can fail because another buyer accepted first.
Phalanx uses POST /api/v1/moon/phalanx with moon_id, galaxy, system, and position. Jump uses /api/v1/moon/jump with from_moon_id, to_moon_id, and ships. Neither takes cargo. Missile launch uses /api/v1/fleet/missiles and MissileLaunch.
Read the abandonment preview with GET /api/v1/planets/P/abandon. The POST uses confirmation_code, confirmation_token, and confirm=true. The token expires after five minutes and binds the reviewed state. Review again after any changed blocker or expired preview.
Errors and retries¶
Errors normally contain error, and game action errors also contain a stable code. Some older validation responses contain only error. Inspect status and content rather than parsing an English sentence.
| Status | Meaning | Next action |
|---|---|---|
| 400 | Invalid body or action | Correct the input. Do not repeat unchanged |
| 401 | Missing, expired, or revoked session | Sign in again |
| 403 | Ownership, role, protection, or policy refusal | Read the reason and current state |
| 404 | Missing object or unsupported route | Check IDs and client/server versions |
| 409 | State conflict, including resources, queue, or settled work | Refresh the affected state |
| 429 | Rate limit | Obey Retry-After or retry_after |
| 500/503 | Server failure or unavailable service | Check status, then reread state before retrying writes |
Important codes include insufficient_resources, prerequisite_not_met, queue_busy, and queue_item_done. A POST is not generally idempotent. The player API has no universal idempotency-key contract. If the response is lost, inspect the queue, fleet, trade, or message history before retrying. Never infer rollback solely from a network timeout.
Mobile companion¶
The companion uses /api/mobile/v1 when the server enables it. It shows status, fleets, reports, chat, and notifications. It cannot place game orders or manage alliance roles.
Sign-in uses browser approval and separate companion credentials. Game credentials cannot authenticate the companion API. Companion credentials cannot authenticate the gameplay API. Companion reads do not change game presence or award dark matter.
LLM discovery and exports¶
llms.txt indexes English Markdown chapters. llms-full.txt combines the full guide. Turkish versions live under /tr/. Every chapter URL has a sibling index.md, such as /economy/index.md.
HTML pages advertise the Markdown alternative and the llms index through link metadata. The game's /llms.txt redirects to the documentation index. Exports come from the same public Markdown files as the human guide. Internal operator notes and credentials are excluded.
The index follows the llms.txt proposal. It supplies context. It does not grant an assistant permission to spend resources, send messages, or attack. Current server responses take precedence over cached documentation and outside OGame references.