Webapp API Endpoints

Purpose: Webapp endpoints split per entity for context-window efficiency Last Updated: May 13, 2026

Overview

This directory contains the structs-webapp HTTP API split per entity. Agents should load only the entity files they need rather than reading the full endpoint catalog.

Implementation: PHP Symfony app at playstructs/structs-webapp. Authentication is by Cosmos signature → session cookie (see auth.md).

Authentication required by default. Per config/packages/security.yaml, the only public routes are /api/auth/*, /api/guild/this, /api/timestamp, and /api/setting. Every other /api/ route — including all catalog read endpoints below — requires an authenticated PHPSESSID session and returns 401 without one. Browser clients must send credentials: include so the cookie rides along.

Response envelope (all endpoints): every webapp response — bespoke or catalog, success or failure — is { "success": bool, "errors": {}, "data": ... }. Always check success, then unwrap data. errors is a keyed object (e.g. {"signature_validation_failed": "..."}), never a string array. Bespoke endpoints return SQL column names (snake_case) inside data unless otherwise noted; catalog reads return a flat array of rows in data. See ../../protocols/webapp-api-protocol.md.

Base URLs:

Local Docker Compose: http://localhost:8080
Public guild webapp (Orbital Hydro): http://crew.oh.energy

Files

Entity-specific endpoints (legacy bespoke endpoints)

These existed before the catalog read layer was added. They tend to return enriched objects (joined data, stats summaries) rather than the raw catalog row.

auth.md — /api/auth/*
player.md — /api/player/{player_id}/* plus /api/player/list/*
planet.md — /api/planet/{planet_id}/* (shield, raid) plus /api/planet/list/*
guild.md — /api/guild/* (directory, roster, power-stats, etc.) plus /api/guild/list/*
struct.md — /api/struct/* (player, planet, type, single struct) plus /api/struct/list/*
ledger.md — /api/ledger/{tx_id} and /api/ledger/player/* plus /api/ledger/list/*
infusion.md — /api/infusion/player/* plus /api/infusion/list/*
system.md — /api/timestamp and other system endpoints

Catalog read endpoints (one entity per file)

Uniform paginated reads under /api/{entity}[/{filter}]/page/{page}. See protocols/webapp-api-protocol.md for the catalog conventions.

address-tag.md — /api/address-tag/*
agreement.md — /api/agreement/*
allocation.md — /api/allocation/*
banned-word.md — /api/banned-word/all/page/{page}
defusion.md — /api/defusion/*
fleet.md — /api/fleet/list/*
grid.md — /api/grid/*
guild-membership-application.md — /api/guild-membership-application/*
permission.md — /api/permission/*
permission-guild-rank.md — /api/permission-guild-rank/*
planet-activity.md — /api/planet-activity/*
planet-attribute.md — /api/planet-attribute/*
provider.md — /api/provider/*
reactor.md — /api/reactor/*
substation.md — /api/substation/*
struct-attribute.md — /api/struct-attribute/*
struct-defender.md — /api/struct-defender/*

Other

setting.md — /api/setting (one-shot snapshot of live tunables)
stat.md — /api/stat/{metric}/object/{object_key}/range/page/{page} with ?start_time=&end_time=

Loading Strategy

Load just the file matching the entity you are working with. Example: when monitoring raids, load planet.md and planet-activity.md, not the entire catalog.

../endpoints.md — Master endpoint catalog (chain queries, transactions, webapp)
../queries/ — Chain query endpoints
../transactions/ — Chain transaction endpoints
../../protocols/webapp-api-protocol.md — Catalog conventions, error envelope, pagination
../../knowledge/infrastructure/database-schema.md — Backing PostgreSQL tables