Webapp Struct API Endpoints

Category: webapp Entity: Struct Base URL: ${webappBaseUrl} (default: http://localhost:8080, public guild webapp: http://crew.oh.energy) Last Updated: May 13, 2026

Endpoint Summary

Method Path Description Auth Required
GET /api/struct/player/{player_id} Get structs by player ID Yes
GET /api/struct/planet/{planet_id} Get structs on planet Yes
GET /api/struct/type Get struct types Yes
GET /api/struct/{struct_id} Get struct by ID Yes
GET /api/struct/list/all/page/{page} Catalog list of every struct Yes
GET /api/struct/list/owner/{owner}/page/{page} Catalog list of structs owned by a player Yes
GET /api/struct/list/location/{location_id}/page/{page} Catalog list of structs at a location Yes

Per-struct attributes and defender relationships live in struct-attribute.md and struct-defender.md.

Endpoint Details

GET /api/struct/player/{player_id}

Get structs by player ID.

Parameters

Name Type Required Format Description
player_id string Yes player-id Player identifier

Example

Request: GET http://localhost:8080/api/struct/player/1-11

Response — envelope; data is a flat array of struct s.* rows (snake_case) plus joined health, status, defending_struct_ids:

{
  "success": true,
  "errors": {},
  "data": [
    {
      "id": "5-1",
      "type": 14,
      "owner": "1-11",
      "location_type": "planet",
      "location_id": "2-1",
      "operating_ambit": "space",
      "slot": 0,
      "is_destroyed": false,
      "health": 100,
      "status": 1,
      "defending_struct_ids": []
    }
  ]
}

GET /api/struct/planet/{planet_id}

Get structs on planet.

Parameters

Name Type Required Format Description
planet_id string Yes planet-id Planet identifier

Example

Request: GET http://localhost:8080/api/struct/planet/2-1

Response (envelope; flat array of snake_case struct rows):

{
  "success": true,
  "errors": {},
  "data": [
    {
      "id": "5-1",
      "type": 14,
      "owner": "1-11",
      "location_type": "planet",
      "location_id": "2-1",
      "operating_ambit": "space",
      "slot": 0,
      "is_destroyed": false,
      "health": 100,
      "status": 1,
      "defending_struct_ids": []
    }
  ]
}

GET /api/struct/type

Get struct types.

Example

Request: GET http://localhost:8080/api/struct/type

Response (envelope; flat array of struct_type rows, snake_case):

{
  "success": true,
  "errors": {},
  "data": [
    {
      "id": 14,
      "name": "Command Ship",
      "cheatsheet_details": "...",
      "cheatsheet_extended_details": "..."
    }
  ]
}

GET /api/struct/{struct_id}

Get struct by ID.

Parameters

Name Type Required Format Description
struct_id string Yes struct-id Struct identifier

Example

Request: GET http://localhost:8080/api/struct/5-1

Response (envelope; data is a single snake_case struct row, or null):

{
  "success": true,
  "errors": {},
  "data": {
    "id": "5-1",
    "type": 14,
    "owner": "1-11",
    "location_type": "planet",
    "location_id": "2-1",
    "operating_ambit": "space",
    "slot": 0,
    "is_destroyed": false,
    "health": 100,
    "status": 1,
    "defending_struct_ids": []
  }
}

GET /api/struct/list/all/page/{page}

Catalog list of every struct on the chain, paginated.

Parameters

Name Type Required Format Description
page integer Yes \d+ Page number, 1-indexed

GET /api/struct/list/owner/{owner}/page/{page}

Catalog list of structs owned by a player.

Parameters

Name Type Required Format Description
owner string Yes player-id Owning player identifier (e.g. 1-11)
page integer Yes \d+ Page number

GET /api/struct/list/location/{location_id}/page/{page}

Catalog list of structs sitting on a given location object (planet, fleet, or other container).

Parameters

Name Type Required Format Description
location_id string Yes entity-id Location object identifier (e.g. planet 2-1 or fleet 9-11)
page integer Yes \d+ Page number

Response Schema

Struct Response

Destroyed structs are filtered out of responses. The is_destroyed field is used in queries (WHERE s.is_destroyed = false) but destroyed structs are not returned to clients. The bespoke struct managers select struct s.* (snake_case DB columns) plus joined health, status, and defending_struct_ids, wrapped in the standard envelope:

{
  "success": true,
  "errors": {},
  "data": {
    "id": "5-1",
    "type": 14,
    "owner": "1-11",
    "location_type": "planet",
    "location_id": "2-1",
    "operating_ambit": "space",
    "slot": 0,
    "is_destroyed": false,
    "health": 100,
    "status": 1,
    "defending_struct_ids": []
  }
}

Struct Type Response

Struct type responses include cheatsheet fields (verified via SELECT * FROM struct_type):

{
  "id": 14,
  "name": "Command Ship",
  "cheatsheet_details": "...",
  "cheatsheet_extended_details": "...",
  ...
}

See: reviews/webapp-review-findings.md for code review verification

The /api/struct/list/... endpoints return the shared envelope with rows directly in data as a flat array (fixed page size 100 — if data.length === 100, fetch the next page). Bespoke struct endpoints also use the { "success", "errors", "data" } envelope. See protocols/webapp-api-protocol.md.