webapp

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/*
• player-address.md — /api/player-address/* and /api/auth/player-address*
• 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, 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/*
• work.md — /api/work/* (outstanding proof-of-work jobs)
• 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
• defusion.md — /api/defusion/*
• fleet.md — /api/fleet/list/* plus /api/fleet/player/{player_id}
• 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.

---

Related Documentation

• ../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