API Quick Reference

Last Updated: May 13, 2026 Purpose: Quick reference guide for AI agents

Base URLs

Consensus Network API

Web Application API

Streaming (GRASS/NATS)

Common Endpoints

Player Endpoints

Get Player (Consensus):

GET /structs/player/{id}

Get Player (Webapp):

GET /api/player/{player_id}

Get Player Ore Stats:

GET /api/player/{player_id}/ore/stats

Get Player’s Planets:

GET /structs/planet_by_player/{playerId}

Planet Endpoints

Get Planet (Consensus):

GET /structs/planet/{id}

Get Planet (Webapp):

GET /api/planet/{planet_id}

Get Planet Shield Health:

GET /api/planet/{planet_id}/shield/health

Guild Endpoints

Get Guild (Consensus):

GET /structs/guild/{id}

Get Guild (Webapp):

GET /api/guild/{guild_id}

Get Guild Member Count:

GET /api/guild/{guild_id}/members/count

Get Guild Power Stats:

GET /api/guild/{guild_id}/power/stats

Struct Endpoints

Get Struct (Consensus):

GET /structs/struct/{id}

Get Struct (Webapp):

GET /api/struct/{struct_id}

Get Struct Type (Consensus):

GET /structs/struct_type/{id}

Note: the struct_type LCD query can return gRPC code 12 (“Not Implemented”) on the deployed testnet build. Fall back to the CLI (structsd query structs struct-type-all) or the Guild Stack PostgreSQL mirror.

Get Structs at a Location (Webapp) (planet or fleet):

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

Get a Player’s Structs (Webapp):

GET /api/struct/player/{player_id}

Transaction Endpoints

Submit Transaction:

POST /cosmos/tx/v1beta1/txs

Get Transaction:

GET /cosmos/tx/v1beta1/txs/{hash}

Catalog Read (Webapp)

Uniform paginated lists under /api/{entity}[/{filter}]/page/{page}:

GET /api/allocation/source/{source_id}/page/{page}
GET /api/agreement/owner/{owner}
GET /api/permission/object/{object_id}/page/{page}
GET /api/permission-guild-rank/guild/{guild_id}/page/{page}
GET /api/planet-activity/planet/{planet_id}/page/{page}
GET /api/grid/object/{object_id}/page/{page}
GET /api/struct-defender/protected/{protected_struct_id}/page/{page}
GET /api/banned-word/all
GET /api/defusion/validator/{validator_address}/page/{page}

See webapp/ for the full per-entity catalog.

Time-Series Stats and Live Tunables

GET /api/setting
GET /api/stat/{metric}/object/{object_key}/range/page/{page}?start_time={unix}&end_time={unix}

Response Formats

Success Response (Webapp)

{
  "success": true,
  "data": {...}
}

Error Response (Webapp)

{
  "success": false,
  "data": null,
  "errors": ["Error message"]
}

Success Response (Consensus)

{
  "Player": {...}
}

Error Response (Consensus)

{
  "code": 2,
  "message": "codespace structs code 1900: object not found",
  "details": []
}

Common HTTP Status Codes

Rate Limiting

Default Limits:

Headers:

See: api/rate-limits.md for complete details

Error Handling

Retryable Errors

Non-Retryable Errors

See: api/error-codes.md for complete error catalog

Streaming

GRASS (NATS-over-WebSocket) — game-level events

Subject Patterns

Grid and planet subjects end with the owning player_id (added 2026-07-07; noPlayer when unresolved), and their payloads carry a player_id field. NATS * matches one token, > the rest — a bare structs.planet.* no longer matches.

Tendermint WebSocket — chain events

For untyped chain events (e.g. ugc_moderated) subscribe to wss://public.testnet.structs.network:26657/websocket.

Event Categories

See: protocols/streaming.md for complete documentation

Authentication

Web Application (Signature-Based Session)

Login (sign LOGIN_GUILD{guildId}ADDRESS{address}DATETIME{unix_timestamp}):

POST /api/auth/login
Body: {"address": "...", "signature": "...", "pubkey": "...", "guild_id": "0-1", "unix_timestamp": "..."}
Response: 200 {"success": true, "errors": {}, "data": null} + Set-Cookie: PHPSESSID

Authenticated Request (session required for all /api/ except /api/auth/*, /api/guild/this, /api/timestamp, /api/setting):

GET /api/reactor/all/page/1
Headers: {"Cookie": "PHPSESSID=..."}

Consensus Network (Transaction Signing)

Process:

  1. Get account info
  2. Create transaction
  3. Sign with private key
  4. Submit transaction

See: protocols/authentication.md for complete documentation

Pagination

Consensus Network:

GET /structs/player?pagination.limit=10&pagination.offset=0

Response:

{
  "Player": [...],
  "pagination": {
    "next_key": "...",
    "total": "100"
  }
}

Common Patterns

Get Player and Planets

  1. GET /api/player/{player_id}
  2. GET /structs/planet_by_player/{playerId}

Pattern: Linear Chain
See: examples/workflows/get-player-and-planets.md

Get Guild Stats

  1. GET /api/guild/{guild_id}
  2. GET /api/guild/{guild_id}/members/count (parallel)
  3. GET /api/guild/{guild_id}/power/stats (parallel)

Pattern: Parallel with Dependency
See: examples/workflows/query-guild-stats.md

Monitor Planet Shield

  1. GET /api/planet/{planet_id} (initial load)
  2. Subscribe to structs.planet.{id}.* (streaming)

Pattern: Hybrid (Query + Streaming)
See: examples/workflows/monitor-planet-shield.md

See: examples/workflows/README.md for complete workflow examples

Schema References

Request Schemas: schemas/requests.md
Response Schemas: schemas/responses.md
Entity Schemas: schemas/entities.md
Error Schemas: schemas/errors.md

Documentation Files

Protocols:

API Documentation:

Examples:

Reference:

Patterns Reference

Data Retrieval Patterns

Error Handling Patterns

Workflow Patterns

Security Patterns

See: patterns/README.md for complete pattern catalog

Quick Tips

  1. Always check response status before processing
  2. Validate responses against schemas
  3. Handle errors gracefully with retry logic
  4. Respect rate limits and use headers
  5. Cache responses when possible
  6. Use appropriate authentication for each API
  7. Test endpoints before production use
  8. Monitor streaming events for real-time updates
  9. Use patterns for common scenarios (see Patterns Reference above)
  10. Follow workflow examples for multi-step operations