Webapp API Endpoints

Purpose: Webapp endpoints split per entity for context-window efficiency Last Updated: September 4, 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": ... } with optional meta.height (indexer or current_block) and total. 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.

Charting and analytics. Leaderboards, inventory, guild-bank history, time-series aggregates, market snapshots, and census counts are documented together in analytics.md — that is the page to load when you are drawing a dashboard rather than fetching one entity.

Pagination and batch caps. Catalog page size defaults to 100. Optional ?limit= is clamped to 1–10000. /api/objects?ids= and /api/resolve name search cap at 200 ids.

Base URLs:

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.

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.

Other

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.