API Reference

All REST API endpoints. Base URL is http://localhost:5000. Full interactive docs at /api/v1.

Auth

All endpoints require a Bearer token unless DISABLE_AUTH=true is set.

Authorization: Bearer <clerk_jwt>

Response Envelope

Every response is wrapped in:

{
  "content": <T> | null,
  "errors": [{ "message": "..." }]
}

Planets

MethodPathDescription
GET/api/v1/planetsList planets (filter: galaxyId, sectorId, ownerId)
GET/api/v1/planets/:idGet single planet
POST/api/v1/planetsCreate planet
PUT/api/v1/planets/:idReplace planet
DELETE/api/v1/planets/:idDelete planet

Economy

MethodPathDescription
GET/api/v1/game/economyGet economy view for all planets
POST/api/v1/game/tickAdvance one economic tick for all planets

Hangar — Frames

MethodPathDescription
GET/api/v1/framesList frames (filter: category)
GET/api/v1/frames/:idGet single frame

Hangar — Modules

MethodPathDescription
GET/api/v1/modulesList modules (filter: type)
GET/api/v1/modules/:idGet single module

Hangar — Blueprints

MethodPathDescription
GET/api/v1/blueprintsList current user's blueprints
GET/api/v1/blueprints/:idGet blueprint with all slot details
POST/api/v1/blueprintsCreate blueprint
PUT/api/v1/blueprints/:idReplace blueprint (increments version)
DELETE/api/v1/blueprints/:idDelete blueprint

Fleet — Production

MethodPathDescription
GET/api/v1/planets/:id/productionList production orders for a planet
POST/api/v1/planets/:id/productionQueue a new production order
DELETE/api/v1/planets/:id/production/:orderIdCancel order (refunds unfinished ships)
GET/api/v1/planets/:id/production/cost/:blueprintIdPreview cost for one ship from blueprint

Queue Order Body

{
  "blueprintId": "uuid",
  "quantity": 5
}

Fleet

MethodPathDescription
GET/api/v1/fleetsList current user's fleets
GET/api/v1/fleets/:idGet single fleet with ship stacks

Users

MethodPathDescription
GET/api/v1/usersList users
GET/api/v1/users/:idGet user
POST/api/v1/usersCreate/upsert user
Architecture
Monorepo structure, backend layers, frontend patterns, and infrastructure.