Skip to content

Request bodies and shared data types

Generated from the HTTP handlers and their shared Go types. JSON tags name wire fields. omitempty controls response omission, not whether a request passes validation. Pointer fields can represent absence. Maps use the English catalog keys. Server-side validation and ownership rules still apply. Handler names correspond to the source router. Read integration workflows before sending a mutation. These structures are not an OpenAPI schema.

acceptTrade

trades.go

struct {
    PlanetID int64 `json:"planet_id"`
}

authLogin

handlers.go

struct {
    Username string `json:"username"`
    Password string `json:"password"`

    TOTP string `json:"totp,omitempty"`
}

authRegister

handlers.go

struct {
    Username string `json:"username"`
    Email    string `json:"email"`
    Password string `json:"password"`
}

boostProduction

darkmatter.go

struct {
    PlanetID int64 `json:"planet_id"`
}

combatForecastHandler

combat.go

game.ForecastRequest

companionBlock

companion_safety.go

struct {
    Username string `json:"username"`
}

companionComplaint

companion_safety.go

struct {
    Username          string `json:"username"`
    MessageID         int64  `json:"message_id"`
    AllianceMessageID int64  `json:"alliance_message_id"`
    Category          string `json:"category"`
    Body              string `json:"body"`
}

companionReadIDs

companion.go

struct {
    IDs []int64 `json:"ids"`
}

companionRegisterPush

companion.go

struct {
    Provider    string `json:"provider"`
    Token       string `json:"token"`
    Environment string `json:"environment"`
}

companionSendAllianceChat

companion_safety.go

struct {
    Body string `json:"body"`
}

companionSendMessage

companion_safety.go

struct {
    To   string `json:"to"`
    Body string `json:"body"`
}

createACS

acs.go

struct {
    FleetID int64 `json:"fleet_id"`
}

createAlliance

handlers.go

struct {
    Tag         string `json:"tag"`
    Name        string `json:"name"`
    Description string `json:"description"`
}

createTrade

trades.go

svc.TradeCreateRequest

devicePoll

handlers.go

struct {
    AuthCode string `json:"auth_code"`
}

dispatchFleet

handlers.go

svc.FleetDispatchRequest

inviteACS

acs.go

struct {
    Username string `json:"username"`
}

jumpGate

handlers.go

struct {
    FromMoonID int64          `json:"from_moon_id"`
    ToMoonID   int64          `json:"to_moon_id"`
    Ships      map[string]int `json:"ships"`
}

launchMissiles

handlers.go

svc.MissileLaunch

markNoticesRead

handlers.go

struct {
    IDs []int64 `json:"ids"`
}

mountCompanion

companion.go

struct {
    Code         string `json:"code"`
    CodeVerifier string `json:"code_verifier"`
}

mountCompanion

companion.go

struct {
    DeviceName    string `json:"device_name"`
    CodeChallenge string `json:"code_challenge"`
    State         string `json:"state"`
}

mountCompanion

companion.go

struct {
    RefreshToken string `json:"refresh_token"`
}

phalanxScan

handlers.go

struct {
    MoonID   int64 `json:"moon_id"`
    Galaxy   int   `json:"galaxy"`
    System   int   `json:"system"`
    Position int   `json:"position"`
}

planetAbandon

abandon.go

svc.AbandonRequest

queueBuilding

handlers.go

struct {
    Building string `json:"building"`
}

queueDefense

handlers.go

struct {
    Defense string `json:"defense"`
    Count   int    `json:"count"`
}

queueDemolition

handlers.go

struct {
    Building string `json:"building"`
}

queueResearch

handlers.go

struct {
    Tech     string `json:"tech"`
    PlanetID int64  `json:"planet_id"`
}

queueShip

handlers.go

struct {
    Ship  string `json:"ship"`
    Count int    `json:"count"`
}

renamePlanet

darkmatter.go

struct {
    PlanetID int64  `json:"planet_id"`
    Name     string `json:"name"`
}

rushBuild

darkmatter.go

struct {
    QueueID int64 `json:"queue_id"`
}

sendAllianceChat

handlers.go

struct {
    Body string `json:"body"`
}

sendMessage

handlers.go

struct {
    To   string `json:"to"`
    Body string `json:"body"`
}

game.ForecastForce

type ForecastForce struct {
    Ships     map[string]int `json:"ships"`
    Defenses  map[string]int `json:"defenses,omitempty"`
    Weapons   int            `json:"weapons"`
    Shielding int            `json:"shielding"`
    Armour    int            `json:"armour"`
}

game.ForecastLoss

type ForecastLoss struct {
    Min  int64   `json:"min"`
    Max  int64   `json:"max"`
    Mean float64 `json:"mean"`
}

game.ForecastRequest

type ForecastRequest struct {
    Attackers []ForecastForce `json:"attackers"`
    Defenders []ForecastForce `json:"defenders"`
    Runs      int             `json:"runs,omitempty"`
    Seed      int64           `json:"seed,omitempty"`
}

game.ForecastResult

type ForecastResult struct {
    RulesVersion string         `json:"combat_rules_version"`
    Runs         int            `json:"runs"`
    Seed         int64          `json:"seed"`
    Outcomes     map[string]int `json:"outcomes"`
    AttackerLoss ForecastLoss   `json:"attacker_loss_resources"`
    DefenderLoss ForecastLoss   `json:"defender_loss_resources_before_rebuild"`
    Sample       CombatResult   `json:"sample"`
    Caveat       string         `json:"caveat"`
}

svc.AbandonBody

type AbandonBody struct {
    ID          int64              `json:"id"`
    Code        string             `json:"code"`
    Name        string             `json:"name"`
    Coordinates string             `json:"coordinates"`
    IsMoon      bool               `json:"is_moon"`
    IsHomeworld bool               `json:"is_homeworld"`
    Resources   map[string]float64 `json:"resources"`
    Buildings   map[string]int     `json:"buildings"`
    Ships       map[string]int     `json:"ships"`
    Defense     map[string]int     `json:"defense"`
}

svc.AbandonPreview

type AbandonPreview struct {
    ConfirmationToken string         `json:"confirmation_token"`
    Planet            AbandonBody    `json:"planet"`
    Moon              *AbandonBody   `json:"moon,omitempty"`
    NewHomeworld      *AbandonBody   `json:"new_homeworld,omitempty"`
    Queues            []AbandonQueue `json:"lost_queues"`
    Blockers          []string       `json:"blockers"`
    OwnFlights        int            `json:"own_flights"`
    ActiveTrades      int            `json:"active_trades"`
    CanAbandon        bool           `json:"can_abandon"`
    ClearsAt          time.Time      `json:"clears_at"`
}

svc.AbandonQueue

type AbandonQueue struct {
    ID       int64  `json:"id"`
    PlanetID int64  `json:"planet_id"`
    Kind     string `json:"kind"`
    Item     string `json:"item"`
    Count    int    `json:"remaining_count"`
    Level    int    `json:"level,omitempty"`
}

svc.AbandonRequest

type AbandonRequest struct {
    ConfirmationToken string `json:"confirmation_token"`
    ConfirmationCode  string `json:"confirmation_code"`
    Confirm           bool   `json:"confirm"`
}

svc.AbandonResult

type AbandonResult struct {
    PlanetID       int64     `json:"planet_id"`
    Name           string    `json:"name"`
    Coordinates    string    `json:"coordinates"`
    MoonID         int64     `json:"moon_id,omitempty"`
    NewHomeworldID int64     `json:"new_homeworld_id,omitempty"`
    ClearsAt       time.Time `json:"clears_at"`
}

svc.Alliance

type Alliance struct {
    Score       int64     `json:"score"`
    Rank        int       `json:"rank"`
    ID          int64     `json:"id"`
    Tag         string    `json:"tag"`
    Name        string    `json:"name"`
    Description string    `json:"description"`
    OwnerUserID int64     `json:"owner_user_id"`
    MemberCount int       `json:"member_count"`
    CreatedAt   time.Time `json:"created_at"`
}

svc.AuthResult

type AuthResult struct {
    Token string `json:"token"`
    User  *User  `json:"user"`
}

svc.BuildingView

type BuildingView struct {
    Key          string `json:"key"`
    Label        string `json:"label"`
    Category     string `json:"category"`
    Level        int    `json:"level"`
    NextCost     Cost   `json:"next_cost"`
    BuildSeconds int    `json:"build_seconds"`
    Affordable   bool   `json:"affordable"`
    Locked       bool   `json:"locked"`
    LockedReason string `json:"locked_reason,omitempty"`

    EnergyAfter int     `json:"energy_after"`
    FactorAfter float64 `json:"production_factor_after"`

    CostsProduction bool `json:"costs_production,omitempty"`
}

svc.Cost

type Cost struct {
    Metal     float64 `json:"metal"`
    Crystal   float64 `json:"crystal"`
    Deuterium float64 `json:"deuterium"`
    Energy    int     `json:"energy,omitempty"`
}

svc.DebrisView

type DebrisView struct {
    Metal     int64 `json:"metal"`
    Crystal   int64 `json:"crystal"`
    Recyclers int   `json:"recyclers"`
}

svc.DeviceAuthPoll

type DeviceAuthPoll struct {
    Token string `json:"token"`
}

svc.DeviceAuthStart

type DeviceAuthStart struct {
    AuthCode        string `json:"auth_code"`
    ExpiresIn       int    `json:"expires_in"`
    PollingInterval int    `json:"polling_interval"`
}

svc.FleetDispatchRequest

type FleetDispatchRequest struct {
    BotOperationTarget int64          `json:"-"`
    ACSGroupID         int64          `json:"acs_group_id,omitempty"`
    HoldHours          int            `json:"hold_hours,omitempty"`
    OriginPlanetID     int64          `json:"origin_planet_id"`
    TargetGalaxy       int            `json:"target_galaxy"`
    TargetSystem       int            `json:"target_system"`
    TargetPosition     int            `json:"target_position"`
    Mission            string         `json:"mission"`
    Ships              map[string]int `json:"ships"`
    Cargo              map[string]int `json:"cargo,omitempty"`
    SpeedPercent       int            `json:"speed_percent,omitempty"`

    TargetMoon bool `json:"target_moon,omitempty"`

    ConfirmAlly bool `json:"confirm_ally,omitempty"`
}

svc.Fleet

type Fleet struct {
    TargetPlayer     *PlayerIdentity `json:"target_player,omitempty"`
    OwnerAllianceTag string          `json:"owner_alliance_tag,omitempty"`
    TargetPlanetID   *int64          `json:"target_planet_id,omitempty"`
    TargetMoon       bool            `json:"target_moon,omitempty"`
    ACSGroupID       *int64          `json:"acs_group_id,omitempty"`
    HoldUntil        *time.Time      `json:"hold_until,omitempty"`
    FuelCost         int             `json:"fuel_cost"`
    HoldFuel         int             `json:"hold_fuel,omitempty"`
    ID               int64           `json:"id"`
    UserID           int64           `json:"user_id"`
    OwnerName        string          `json:"owner_name,omitempty"`
    OriginPlanetID   int64           `json:"origin_planet_id"`
    OriginGalaxy     int             `json:"origin_galaxy,omitempty"`
    OriginSystem     int             `json:"origin_system,omitempty"`
    OriginPosition   int             `json:"origin_position,omitempty"`
    TargetGalaxy     int             `json:"target_galaxy"`
    TargetSystem     int             `json:"target_system"`
    TargetPosition   int             `json:"target_position"`
    Mission          string          `json:"mission"`
    State            string          `json:"state"`
    DepartureAt      time.Time       `json:"departure_at"`
    ArrivalAt        time.Time       `json:"arrival_at"`
    ReturnAt         *time.Time      `json:"return_at,omitempty"`
    ShipCount        int             `json:"ship_count,omitempty"`
    ShipTypes        []string        `json:"ship_types,omitempty"`
    Ships            map[string]int  `json:"ships"`
    Cargo            map[string]int  `json:"cargo,omitempty"`
}

svc.LeaderboardEntry

type LeaderboardEntry struct {
    Rank     int    `json:"rank"`
    UserID   int64  `json:"user_id"`
    Username string `json:"username"`
    Score    int64  `json:"score"`
    Alliance string `json:"alliance,omitempty"`

    Simulated bool `json:"simulated,omitempty"`
}

svc.Message

type Message struct {
    ID     int64 `json:"id"`
    UserID int64 `json:"user_id"`

    SenderID   *int64    `json:"sender_id,omitempty"`
    SenderName string    `json:"sender_name,omitempty"`
    Subject    string    `json:"subject"`
    Body       string    `json:"body"`
    Category   string    `json:"category"`
    Read       bool      `json:"read"`
    CreatedAt  time.Time `json:"created_at"`
}

svc.MissileLaunch

type MissileLaunch struct {
    OriginPlanetID int64 `json:"origin_planet_id"`
    TargetGalaxy   int   `json:"target_galaxy"`
    TargetSystem   int   `json:"target_system"`
    TargetPosition int   `json:"target_position"`
    Count          int   `json:"count"`

    TargetMoon bool `json:"target_moon,omitempty"`

    Order []string `json:"order,omitempty"`
}

svc.MoonView

type MoonView struct {
    Name   string `json:"name"`
    Fields int    `json:"fields"`
}

svc.Planet

type Planet struct {
    ID                     int64          `json:"id"`
    Code                   string         `json:"code"`
    Name                   string         `json:"name"`
    OwnerUserID            int64          `json:"owner_user_id"`
    UniverseID             int64          `json:"universe_id"`
    Galaxy                 int            `json:"galaxy"`
    System                 int            `json:"system"`
    Position               int            `json:"position"`
    FieldsUsed             int            `json:"fields_used"`
    FieldsTotal            int            `json:"fields_total"`
    TempMin                int            `json:"temp_min"`
    TempMax                int            `json:"temp_max"`
    Metal                  float64        `json:"metal"`
    Crystal                float64        `json:"crystal"`
    Deuterium              float64        `json:"deuterium"`
    EnergyUsed             int            `json:"energy_used"`
    EnergyProduced         int            `json:"energy_produced"`
    ResourcesLastUpdatedAt time.Time      `json:"resources_last_updated_at"`
    Buildings              map[string]int `json:"buildings"`
    Ships                  map[string]int `json:"ships,omitempty"`
    Defense                map[string]int `json:"defense,omitempty"`

    IsMoon      bool `json:"is_moon,omitempty"`
    IsHomeworld bool `json:"is_homeworld,omitempty"`

    JumpGateReadyAt *time.Time `json:"jump_gate_ready_at,omitempty"`
}

svc.PlayerIdentity

type PlayerIdentity struct {
    UserID      int64  `json:"user_id,omitempty"`
    Name        string `json:"name"`
    AllianceTag string `json:"alliance_tag,omitempty"`
}

svc.ProductionReport

type ProductionReport struct {
    PlanetID            int64   `json:"planet_id"`
    MetalPerHour        float64 `json:"metal_per_hour"`
    CrystalPerHour      float64 `json:"crystal_per_hour"`
    DeuteriumPerHour    float64 `json:"deuterium_per_hour"`
    EnergyProduced      int     `json:"energy_produced"`
    EnergyUsed          int     `json:"energy_used"`
    ProductionFactor    float64 `json:"production_factor"`
    StorageCapMetal     int     `json:"storage_cap_metal"`
    StorageCapCrystal   int     `json:"storage_cap_crystal"`
    StorageCapDeuterium int     `json:"storage_cap_deuterium"`

    BoostMultiplier float64    `json:"boost_multiplier"`
    BoostExpiresAt  *time.Time `json:"boost_expires_at,omitempty"`
}

svc.PublicServerStats

type PublicServerStats struct {
    Name        string `json:"name"`
    Description string `json:"description"`
    MaxUsers    int    `json:"max_users"`
    Registered  int    `json:"registered"`
    Online      int    `json:"online"`
    Active24h   int    `json:"active_24h"`
    Full        bool   `json:"full"`
    Version     string `json:"version"`
    BuildDate   string `json:"build_date,omitempty"`

    MinClient string `json:"min_client,omitempty"`
}

svc.QueueItem

type QueueItem struct {
    ID          int64     `json:"id"`
    PlanetID    *int64    `json:"planet_id,omitempty"`
    UserID      int64     `json:"user_id"`
    QueueType   string    `json:"queue_type"`
    ItemKey     string    `json:"item_key"`
    TargetLevel int       `json:"target_level,omitempty"`
    Count       int       `json:"count,omitempty"`
    StartedAt   time.Time `json:"started_at"`
    FinishedAt  time.Time `json:"finished_at"`

    CreatedAt time.Time `json:"created_at"`
}

svc.Report

type Report struct {
    Players []PlayerIdentity `json:"players,omitempty"`
    ID      int64            `json:"id"`
    UserID  int64            `json:"user_id"`
    Kind    string           `json:"kind"`

    Subject string         `json:"subject"`
    Body    string         `json:"body"`
    Payload map[string]any `json:"payload"`

    TargetGalaxy   int       `json:"target_galaxy"`
    TargetSystem   int       `json:"target_system"`
    TargetPosition int       `json:"target_position"`
    CreatedAt      time.Time `json:"created_at"`
}

svc.ResearchLevel

type ResearchLevel struct {
    Tech  string `json:"tech"`
    Level int    `json:"level"`
}

svc.ResearchNode

type ResearchNode struct {
    Key          string `json:"key"`
    Label        string `json:"label"`
    Level        int    `json:"level"`
    NextCost     Cost   `json:"next_cost"`
    BuildSeconds int    `json:"build_seconds"`

    LabLevel     int    `json:"lab_level,omitempty"`
    Parent       string `json:"parent,omitempty"`
    Affordable   bool   `json:"affordable"`
    Locked       bool   `json:"locked"`
    LockedReason string `json:"locked_reason,omitempty"`
}

svc.ResearchView

type ResearchView struct {
    LabLevel int            `json:"lab_level"`
    Nodes    []ResearchNode `json:"nodes"`

    NetworkLevel int `json:"network_level,omitempty"`
    NetworkLabs  int `json:"network_labs,omitempty"`

    InProgress []QueueItem `json:"in_progress,omitempty"`
}

svc.StatsOverview

type StatsOverview struct {
    Universes     int `json:"universes"`
    Players       int `json:"players"`
    Planets       int `json:"planets"`
    OnlinePlayers int `json:"online_players"`

    OnlineHumans   int   `json:"online_humans"`
    FleetsInFlight int   `json:"fleets_in_flight"`
    UptimeSeconds  int64 `json:"uptime_seconds"`
}

svc.SystemPlanetView

type SystemPlanetView struct {
    Abandoned   bool       `json:"abandoned,omitempty"`
    ClearsAt    *time.Time `json:"clears_at,omitempty"`
    Position    int        `json:"position"`
    PlanetName  string     `json:"planet_name,omitempty"`
    OwnerName   string     `json:"owner_name,omitempty"`
    AllianceTag string     `json:"alliance_tag,omitempty"`

    Simulated bool  `json:"simulated,omitempty"`
    Online    bool  `json:"online,omitempty"`
    Score     int64 `json:"score,omitempty"`

    Debris *DebrisView `json:"debris,omitempty"`

    Moon *MoonView `json:"moon,omitempty"`
}

svc.SystemReach

type SystemReach struct {
    FromCoord string `json:"from_coord"`

    Hops    int    `json:"hops"`
    HopUnit string `json:"hop_unit"`

    FlightSeconds int `json:"flight_seconds"`
    Fuel          int `json:"fuel"`

    Ship string `json:"ship"`
}

svc.SystemView

type SystemView struct {
    Galaxy int `json:"galaxy"`
    System int `json:"system"`

    Systems int `json:"systems,omitempty"`

    JumpCost int `json:"jump_cost,omitempty"`

    Reach   *SystemReach       `json:"reach,omitempty"`
    Planets []SystemPlanetView `json:"planets"`
}

svc.TradeCreateRequest

type TradeCreateRequest struct {
    PlanetID        int64  `json:"planet_id"`
    OfferResource   string `json:"offer_resource"`
    OfferAmount     int    `json:"offer_amount"`
    RequestResource string `json:"request_resource"`
    RequestAmount   int    `json:"request_amount"`
    MaxHours        int    `json:"max_hours"`
    AllianceOnly    bool   `json:"alliance_only"`
}

svc.TradeView

type TradeView struct {
    ID              int64     `json:"id"`
    Seller          string    `json:"seller"`
    SellerPlanetID  int64     `json:"seller_planet_id"`
    Coordinate      string    `json:"coordinate"`
    OfferResource   string    `json:"offer_resource"`
    OfferAmount     int       `json:"offer_amount"`
    RequestResource string    `json:"request_resource"`
    RequestAmount   int       `json:"request_amount"`
    CargoCount      int       `json:"cargo_count"`
    AllianceOnly    bool      `json:"alliance_only"`
    AllianceTag     string    `json:"alliance_tag,omitempty"`
    MaxHours        int       `json:"max_hours"`
    TravelSeconds   int       `json:"travel_seconds"`
    CreatedAt       time.Time `json:"created_at"`
    Status          string    `json:"status"`
}

svc.UnitView

type UnitView struct {
    Key          string `json:"key"`
    Label        string `json:"label"`
    Owned        int    `json:"owned"`
    UnitCost     Cost   `json:"unit_cost"`
    BuildSeconds int    `json:"build_seconds"`
    BuildableNow int    `json:"buildable_now"`
    Locked       bool   `json:"locked"`
    LockedReason string `json:"locked_reason,omitempty"`
}

svc.Universe

type Universe struct {
    ID            int64     `json:"id"`
    Name          string    `json:"name"`
    SpeedEconomy  int       `json:"speed_economy"`
    SpeedFleet    int       `json:"speed_fleet"`
    SpeedResearch int       `json:"speed_research"`
    GalaxiesCount int       `json:"galaxies_count"`
    SystemsCount  int       `json:"systems_count"`
    PlayerCount   int       `json:"player_count"`
    CreatedAt     time.Time `json:"created_at"`
}

svc.User

type User struct {
    ID                int64      `json:"id"`
    Username          string     `json:"username"`
    Email             string     `json:"email"`
    Role              string     `json:"role"`
    CurrentUniverseID *int64     `json:"current_universe_id,omitempty"`
    CreatedAt         time.Time  `json:"created_at"`
    LastSeenAt        *time.Time `json:"last_seen_at,omitempty"`
    TwoFactorEnabled  bool       `json:"two_factor_enabled"`

    DarkMatter float64 `json:"dark_matter"`
}