Skip to content

api-quick-reference.md

Latest commit

 

History

History
427 lines (320 loc) · 10.3 KB

api-quick-reference.md

File metadata and controls

427 lines (320 loc) · 10.3 KB
Raw

API Quick Reference

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

Base URLs

Consensus Network API

  • Local: http://localhost:1317
  • Public testnet (SSL): https://public.testnet.structs.network (standard HTTPS, no port — http://...:1317 is local-devnet only and is dead on the public host)
  • Base Path: /structs
  • Local Tendermint RPC: http://localhost:26657
  • Public Tendermint RPC (SSL): https://public.testnet.structs.network:26657
  • Public Tendermint WebSocket: wss://public.testnet.structs.network:26657/websocket

Web Application API

  • Local: http://localhost:8080
  • Public guild webapp (Orbital Hydro): http://crew.oh.energy
  • Base Path: /api

Streaming (GRASS/NATS)

  • Local NATS: nats://localhost:4222
  • Local GRASS WebSocket: ws://localhost:1443
  • Public GRASS WebSocket (Orbital Hydro): ws://crew.oh.energy:1443

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

  • 200 - Success
  • 400 - Bad Request
  • 404 - Not Found
  • 429 - Rate Limit Exceeded
  • 500 - Internal Server Error
  • 503 - Service Unavailable

Rate Limiting

Default Limits:

  • Consensus Network: 60 requests/minute
  • Web Application: 100 requests/minute
  • RPC: 30 requests/minute

Headers:

  • X-RateLimit-Limit - Maximum requests
  • X-RateLimit-Remaining - Remaining requests
  • X-RateLimit-Reset - Reset timestamp
  • Retry-After - Seconds to wait (when rate limited)

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

Error Handling

Retryable Errors

  • 500 - Internal Server Error
  • 503 - Service Unavailable
  • 429 - Rate Limit (with delay)
  • Network errors
  • Timeout errors

Non-Retryable Errors

  • 400 - Bad Request
  • 404 - Not Found
  • 401 - Unauthorized (re-authenticate)
  • 403 - Forbidden

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

Streaming

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

Subject Patterns

  • Player Events: structs.player.> (specific: structs.player.{guild_id}.{player_id})
  • Guild Events: structs.guild.*
  • Planet Events: structs.planet.> (specific: structs.planet.{planet_id}.{player_id}, e.g. structs.planet.3-1.*)
  • Struct Events: structs.struct.*
  • Fleet Events: structs.fleet.*
  • Grid Attributes: structs.grid.> (specific: structs.grid.{object_type}.{object_id}.{player_id})
  • Inventory: structs.inventory.>
  • Global Events: structs.global

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

  • Consensus: block
  • Guild: guild_consensus, guild_meta, guild_membership
  • Planet: raid_status, planet_activity (includes struct_health details), fleet_arrive, fleet_advance, fleet_depart
  • Struct: struct_status, struct_move, struct_attack, struct_block_build_start
  • Player: player_consensus

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:

  • protocols/query-protocol.md - Query API protocol
  • protocols/action-protocol.md - Transaction protocol
  • protocols/webapp-api-protocol.md - Webapp API protocol
  • protocols/streaming.md - GRASS/NATS streaming
  • protocols/authentication.md - Authentication
  • protocols/error-handling.md - Error handling
  • protocols/testing-protocol.md - Testing

API Documentation:

  • api/endpoints.md - Complete endpoint catalog
  • api/endpoints-by-entity.md - Entity-based organization
  • api/error-codes.md - Error code catalog
  • api/rate-limits.md - Rate limiting
  • api/streaming/ - Streaming documentation

Examples:

  • examples/workflows/ - Workflow examples
  • examples/errors/ - Error examples
  • examples/auth/ - Authentication examples

Reference:

  • reference/endpoint-index.md - Endpoint index
  • reference/action-index.md - Action index
  • reference/action-quick-reference.md - Action quick reference
  • reference/api-quick-reference.md - This file

Patterns Reference

Data Retrieval Patterns

  • Pagination: patterns/pagination.md - Handle paginated responses
  • Caching: patterns/caching.md - Cache API responses
  • Polling vs Streaming: patterns/polling-vs-streaming.md - Choose data access method

Error Handling Patterns

  • Rate Limiting: patterns/rate-limiting.md - Handle rate limits
  • Retry Strategies: patterns/retry-strategies.md - Retry failed requests

Workflow Patterns

  • Workflow Patterns: patterns/workflow-patterns.md - Multi-step operations
  • Workflow Examples: examples/workflows/README.md - Complete examples

Security Patterns

  • Security: patterns/security.md - Security best practices

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