API Response Schemas

Version: 1.0.0 Category: api Schema: JSON Schema Draft-07 Description: Complete catalog of all API response formats for AI agents. See schemas/formats.md for format specifications.

General Responses

ApiResponseContentDto (webapp envelope)

Every structs-webapp JSON response — success or failure, bespoke or catalog — uses this single envelope (PHP App\Dto\ApiResponseContentDto). Clients must check success, then read errors or unwrap data.

Field	Type	Required	Description
success	boolean	Yes	`true` on success, `false` on failure
errors	object	Yes	Keyed map of `error_key` → message (e.g. `{"signature_validation_failed":"Invalid signature"}`). Empty `{}` on success. Never a string array.
data	object \| array \| null	Yes	Payload. Single-row reads → object; list/catalog reads → flat array; `null` on error or empty single lookup.

Examples:

{ "success": true, "errors": {}, "data": { "id": "1-11" } }

{ "success": true, "errors": {}, "data": [ { "id": "3-1" }, { "id": "3-2" } ] }

{ "success": false, "errors": { "player_address_does_not_exists": "Player address does not exist" }, "data": null }

The consensus network (chain REST) API does NOT use this envelope — it returns Cosmos-SDK shapes with top-level code/message on error. See protocols/error-handling.md.

Catalog pagination

Catalog list reads put rows directly in data as a flat JSON array — there is no rows/page/page_size wrapper. Page size is fixed at 100 and the page number is a 1-indexed path segment (/page/{n}). To detect more pages: if data.length === 100, fetch the next page; if fewer than 100 (or empty), stop. See protocols/webapp-api-protocol.md.

Consensus PaginationResponse

Key-based pagination used only by the consensus network API (/structs/...).

Field	Type	Description
pagination.next_key	string	Key for next page
pagination.total	string	Total count

Authentication Responses

AuthResponse

Webapp login response. Login uses Cosmos signature verification and returns a session cookie (PHPSESSID); there is no JWT/bearer token. See examples/auth/webapp-login.md.

Field	Type	Description
success	boolean	`true` on successful login (HTTP 200)
errors	object	Keyed errors on failure (HTTP 401), e.g. `signature_validation_failed`, `player_address_does_not_exists`
data	null	Login carries no body payload; identity is established via the `Set-Cookie: PHPSESSID` header

PlayerData

Player data structure, reused across multiple responses.

Field	Type	Format	Description
id	string	entity-id	Player identifier in format `type-index` (e.g., `1-11`). Pattern: `^1-[0-9]+$`. Type 1 = Player.
username	string		Player username
address	string	blockchain-address	Player blockchain address

Player Responses

Webapp note: all webapp response bodies below are carried inside the data field of the ApiResponseContentDto envelope ({ "success": true, "errors": {}, "data": ... }). Bespoke endpoints return SQL column names (snake_case) from their backing query unless otherwise noted. Always unwrap data after checking success.

WebappPlayerResponse

Web application player response (data payload of GET /api/player/{player_id}).

Field	Type	Description
player	PlayerData	Player data
guild	object	Guild information
stats	object	Player statistics

PlayerIdResponse

Player ID response.

Field	Type	Format	Description
player_id	string	entity-id	Player identifier in format `type-index` (e.g., `1-11`). Pattern: `^1-[0-9]+$`. Type 1 = Player.
address	string	blockchain-address	Player blockchain address
guild_id	string	entity-id	Guild identifier in format `type-index` (e.g., `0-1`). Pattern: `^0-[0-9]+$`. Type 0 = Guild.

ActivationCodeResponse

Activation code information response.

Field	Type	Description
code	string	Activation code
valid	boolean	Whether code is valid
player_id	string (entity-id)	Associated player ID if applicable. Format: `type-index` (e.g., `1-11`). Pattern: `^1-[0-9]+$`. Type 1 = Player.

Planet Responses

ShieldHealthResponse

Planetary shield health response.

Field	Type	Format	Description
planet_id	string	entity-id	Planet identifier in format `type-index` (e.g., `2-1`). Pattern: `^2-[0-9]+$`. Type 2 = Planet.
health	integer		Shield health value
max_health	integer		Maximum shield health

ShieldResponse

Planetary shield information response.

Field	Type	Format	Description
planet_id	string	entity-id	Planet identifier in format `type-index` (e.g., `2-1`). Pattern: `^2-[0-9]+$`. Type 2 = Planet.
shield	object		Shield details

Guild Responses

GuildNameResponse

Guild name response.

Field	Type	Format	Description
guild_id	string	entity-id	Guild identifier in format `type-index` (e.g., `0-1`). Pattern: `^0-[0-9]+$`. Type 0 = Guild.
name	string		Guild name

GuildNameListResponse

List of guild names. Response is an array of objects:

Field	Type	Format	Description
guild_id	string	entity-id	Guild identifier in format `type-index` (e.g., `0-1`). Pattern: `^0-[0-9]+$`. Type 0 = Guild.
name	string		Guild name

GuildRosterResponse

Guild roster response.

Field	Type	Format	Description
guild_id	string	entity-id	Guild identifier in format `type-index` (e.g., `0-1`). Pattern: `^0-[0-9]+$`. Type 0 = Guild.
members	array of PlayerData		List of guild members
member_count	integer		Number of members

PowerStatsResponse

Power statistics response.

Field	Type	Format	Description
guild_id	string	entity-id	Guild identifier in format `type-index` (e.g., `0-1`). Pattern: `^0-[0-9]+$`. Type 0 = Guild.
total_power	integer		Total power
power_by_type	object		Power breakdown by type

Ore and Stats Responses

OreStatsResponse

Ore statistics response.

Field	Type	Format	Description
player_id	string	entity-id	Player identifier in format `type-index` (e.g., `1-11`). Pattern: `^1-[0-9]+$`. Type 1 = Player.
total_ore	integer		Total ore mined
ore_by_type	object		Ore counts by type

BlockHeightResponse

Block height response.

Field	Type	Required	Description
height	integer	Yes	Block height

CountResponse

Count response.

Field	Type	Required	Description
count	integer	Yes	Count value

TimestampResponse

Unix timestamp response. The webapp returns this inside data as { "unix_timestamp": <int> } (no iso field). The fields below describe the data payload.

Field	Type	Required	Format	Description
unix_timestamp	integer	Yes		Current server time in unix seconds

Transaction Responses

TransactionResponse

Transaction submission response (Cosmos SDK format).

Field	Type	Required	Description
tx_response	object	Yes	Transaction response envelope

The tx_response object:

Field	Type	Description
code	integer	Transaction result code (0 = success)
txhash	string	Transaction hash
height	integer	Block height
raw_log	string	Raw log output

RPCStatusResponse

RPC node status response.

Field	Type	Description
result.node_info	object	Node information
result.sync_info	object	Sync information

Cosmetic Mod Responses (Deprecated)

These responses use the older mod-based system. Use the Cosmetic Set equivalents instead.

CosmeticModListResponse

DEPRECATED: Use CosmeticSetListResponse.

Field	Type	Required	Description
mods	array of CosmeticModSummary	Yes	List of installed cosmetic mods

CosmeticModSummary

DEPRECATED: Use CosmeticSetSummary.

Field	Type	Required	Pattern	Description
modId	string	Yes	`^[a-z0-9-]+$`	Mod identifier
name	object	No		Mod name by language (string values keyed by language code)
version	string	Yes	`^\d+\.\d+\.\d+$`	Mod version
author	string	Yes		Mod author
guildId	string	No	`^0-[0-9]+$`	Guild ID (if guild-specific, entity-id format)
active	boolean	Yes		Whether mod is active
structTypes	array of string	No		Struct type IDs this mod affects
languages	array of string	No	`^[a-z]{2}$` each	Supported language codes

CosmeticModResponse

DEPRECATED: Use CosmeticSetResponse.

Field	Type	Required	Description
modId	string	Yes	Pattern: `^[a-z0-9-]+$`
manifest	object	Yes	See `schemas/cosmetic-mod.md` manifest definition
active	boolean	Yes	Whether mod is active
structTypes	array of string	No	Struct type IDs
languages	array of string	No	Language codes (pattern: `^[a-z]{2}$` each)

CosmeticModUninstallResponse

DEPRECATED: Use CosmeticSetDeleteResponse.

Field	Type	Required	Description
status	string	Yes	`success` or `error`
modId	string	Yes	Pattern: `^[a-z0-9-]+$`

CosmeticModActivateResponse

DEPRECATED: Use CosmeticSetActivateResponse.

Field	Type	Required	Description
status	string	Yes	`success` or `error`
modId	string	Yes	Pattern: `^[a-z0-9-]+$`
active	boolean	Yes	Whether mod is active

CosmeticModDeactivateResponse

DEPRECATED: Use CosmeticSetDeactivateResponse.

Field	Type	Required	Description
status	string	Yes	`success` or `error`
modId	string	Yes	Pattern: `^[a-z0-9-]+$`
active	boolean	Yes	Whether mod is active

Cosmetic Set Responses

CosmeticSetListResponse

List of cosmetic sets response.

Field	Type	Required	Description
sets	array of CosmeticSetSummary	Yes	List of installed cosmetic sets

CosmeticSetSummary

Summary information about a cosmetic set.

Field	Type	Required	Pattern	Description
setHash	string	Yes	`^[a-f0-9]{64}$`	Set hash (SHA-256, 64-character hexadecimal)
name	object	No		Set name by language (string values keyed by language code)
version	string	Yes	`^\d+\.\d+\.\d+$`	Set version
author	string	Yes		Set author
guildId	string	No	`^0-[0-9]+$`	Guild ID (if guild-specific, entity-id format)
active	boolean	Yes		Whether set is active
classes	array of string	No		Struct type classes this set affects (e.g., `Miner`, `Reactor`)
languages	array of string	No	`^[a-z]{2}$` each	Supported language codes

CosmeticSetResponse

Detailed cosmetic set information response.

Field	Type	Required	Pattern	Description
setHash	string	Yes	`^[a-f0-9]{64}$`	Set hash (SHA-256, 64-character hexadecimal)
name	object	No		Set name by language
version	string	Yes	`^\d+\.\d+\.\d+$`	Set version
author	string	Yes		Set author
guildId	string	No	`^0-[0-9]+$`	Guild ID (if guild-specific)
description	object	No		Set description by language
active	boolean	Yes		Whether set is active
skins	array	No		List of skins in this set (see `schemas/cosmetic-set.md` SkinReference definition)
languages	array of string	No	`^[a-z]{2}$` each	Supported language codes

CosmeticSetDeleteResponse

Cosmetic set deletion response.

Field	Type	Required	Description
status	string	Yes	`success` or `error`
setHash	string	Yes	Deleted set hash. Pattern: `^[a-f0-9]{64}$`

CosmeticSetActivateResponse

Cosmetic set activation response.

Field	Type	Required	Description
status	string	Yes	`success` or `error`
setHash	string	Yes	Activated set hash. Pattern: `^[a-f0-9]{64}$`
active	boolean	Yes	Whether set is now active

CosmeticSetDeactivateResponse

Cosmetic set deactivation response.

Field	Type	Required	Description
status	string	Yes	`success` or `error`
setHash	string	Yes	Deactivated set hash. Pattern: `^[a-f0-9]{64}$`
active	boolean	Yes	Whether set is now active (should be false)

Cosmetic Install and Validate Responses

CosmeticModInstallResponse

Cosmetic mod installation response. Mod is converted to Sets/Skins during ingestion.

Field	Type	Required	Description
status	string	Yes	`success` or `error`
type	string	Yes	Type of cosmetic installed: `set` or `skin`
setHash	string	No	Set hash if type is `set`. Pattern: `^[a-f0-9]{64}$`
skinHash	string	No	Skin hash if type is `skin`. Pattern: `^[a-f0-9]{64}$`
version	string	No	Version. Pattern: `^\d+\.\d+\.\d+$`
skins	array	No	List of skins if type is `set` (each with `skinHash` and `class`)
storagePath	string	No	Path where cosmetic was stored (hash-based directory structure)
validated	boolean	No	Whether mod was validated
activated	boolean	No	Whether cosmetic was activated

Each entry in skins (when type is set):

Field	Type	Required	Description
skinHash	string	Yes	Pattern: `^[a-f0-9]{64}$`
class	string	Yes	Struct type class

CosmeticModValidateResponse

Cosmetic mod validation response.

Field	Type	Required	Description
valid	boolean	Yes	Whether mod is valid
errors	array of string	Yes	Validation errors
warnings	array of string	Yes	Validation warnings
modId	string	No	Mod identifier (if valid). Pattern: `^[a-z0-9-]+$`
version	string	No	Mod version (if valid). Pattern: `^\d+\.\d+\.\d+$`

Struct Type Cosmetic Responses

StructTypeCosmeticResponse

Cosmetic data for a struct type class (with skin overrides applied).

Field	Type	Required	Description
class	string	Yes	Struct type class name (e.g., `Miner`, `Reactor`, `Command Ship`). Must match `struct_type.class` field.
skinHash	string	Yes	Skin hash (SHA-256, 64-character hexadecimal). Pattern: `^[a-f0-9]{64}$`
name	string	No	Cosmetic name (localized)
lore	string	No	Lore/description (localized)
weapons	array	No	Weapon cosmetic overrides (see `schemas/cosmetic-skin.md` WeaponCosmetic definition)
abilities	array	No	Ability cosmetic overrides (see `schemas/cosmetic-skin.md` AbilityCosmetic definition)
animations	object	No	Animation file paths (string values keyed by animation name)
icon	string	No	Icon file path
skinSource	object	No	Source skin information (see below)

skinSource

Field	Type	Required	Description
skinHash	string	Yes	Skin hash (SHA-256). Pattern: `^[a-f0-9]{64}$`
setHash	string	No	Parent set hash (if skin is part of a set). Pattern: `^[a-f0-9]{64}$`
version	string	No	Skin version. Pattern: `^\d+\.\d+\.\d+$`

StructTypeCosmeticListResponse

List of struct type cosmetics.

Field	Type	Required	Description
structTypes	array of StructTypeCosmeticResponse	Yes	List of struct type cosmetic entries

StructTypeFullResponse

Struct type data with cosmetic overrides applied (integration endpoint).

Field	Type	Required	Description
structType	object	Yes	Base struct type data from consensus network
cosmetic	StructTypeCosmeticResponse	Yes	Cosmetic override data
merged	object	No	Merged data combining base and cosmetic