API contracts

Read the machine contract #

The downloadable OpenAPI contract is curated from the application's registered routes and actual request schemas. It adds explicit authentication notes because the raw framework schema does not fully describe the manual cookie, Origin, CSRF and Extension guards. It is a contract reference, not a live request console.

Download verified API contract

Primary feature APIs #

Family	Use	Authorization
/api/player/...	Website player session, associated communities, shared materials and canonical inventory	Verified website principal; association; Origin/CSRF for writes
/api/extension/...	Native viewer session, create raider, shared appearance and quick equip	Signed linked viewer/channel JWT and approved Extension Origin
/api/communities/{community_id}/...	Creator settings and room administration	Owning creator; Origin/CSRF for writes
/api/raiderville/...	Resolve/access rooms, join, snapshots, movement, heartbeat and leave	Code access and verified room viewer; mutations require Origin/CSRF

The canonical inventory snapshot #

{
  "community": {"id": "<community-id>", "display_name": "<community-name>", "broadcaster_twitch_id": "<verified-channel>"},
  "raider": {"level": 1, "xp": 0, "community_id": "<community-id>"},
  "slots": ["head", "body", "belt", "pants", "boots", "left_hand", "right_hand"],
  "equipment": {"head": null, "body": null, "belt": null, "pants": null, "boots": null, "left_hand": null, "right_hand": null},
  "items": [], "revision": 0,
  "render": {"mode": "<server-selected-mode>"}
}

Illustrative subset only. Actual responses include identity and appearance metadata; new viewer state can have raider:null. Use the returned render mode and catalog, not this placeholder as a saved character.

A revisioned gear change #

PUT /api/player/communities/{community_id}/inventory/equip
Content-Type: application/json
X-CSRF-Token: <current-session-csrf>

{"slot":"head","item_id":"<owned-item-id>","revision":<accepted-revision>}

Use item_id:null to unequip. Render the complete accepted response. An identical already-achieved operation may be idempotent; do not optimistically award gear or XP.

Errors are not one envelope #

Current errors use detail:string, detail:{code,message}, or validation detail:list. Handle the status and actual shape defensively.401 means identity is missing/expired;403 covers origin, CSRF, ownership or eligibility;404 means unavailable/unassociated;409 includes revision/conflicting identity/unsupported visual state;422 is input validation;429 is rate limiting;503 means configuration/provider unavailable.

Compatibility routes and known inconsistencies #

Prefer the modern /api/player/.../inventory or signed /api/extension/inventory response for new clients. The legacy creator inventory summary omits canonical revision/render/community fields.