rework api.md and add public facing endpoints

[ryanbarlow97]

Description:

better document player facing endpoints

Please complete the following:

• I have added screenshots for all UI updates
• I process any text displayed to the user through translateText() and I've added it to the en.json file
• I have added relevant tests to the test directory

Please put your Discord username so you can be contacted if a bug or regression is found:

w.o.n

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

The legacy API guide was replaced with a comprehensive reference. It documents HTTP conventions, authentication, public and authenticated endpoints, account and commerce operations, and matchmaking WebSocket behavior.

Changes

API reference documentation

Layer / File(s)	Summary
API conventions and authentication docs/API.md	Adds base URLs, headers, response formats, pagination rules, session actions, OAuth, magic-link, platform-login, and Google-linking documentation.
Public and social endpoint contracts docs/API.md	Documents public game, player, clan, feed, health, asset, friend, and authenticated clan operations, including validation, permissions, pagination, and mutation errors.
Account, commerce, and matchmaking contracts docs/API.md	Documents account updates, rewards, purchases, subscriptions, billing portals, and matchmaking WebSocket messages and failure codes.

Estimated code review effort: 2 (Simple) | ~15 minutes

Poem

Endpoints line up,
Tokens open session doors,
Clans share their state,
Rewards fill the shop,
Matches join the stream.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the API documentation rewrite and addition of public-facing endpoints.
Description check	✅ Passed	The description states that the pull request improves documentation for player-facing endpoints.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/API.md`:
- Around line 1425-1428: Update the WebSocket close-code documentation near the
existing policy and verification codes to describe replacement behavior: when
the same JWT connects through a newer socket, close the previous socket with
code 1000 and reason "Replaced by newer connection", and state that only the
newest socket remains active.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ae088b55-74e7-4483-a0b2-c12a51f6a4d8

📥 Commits

Reviewing files that changed from the base of the PR and between 753c66e and 319b61f.

📒 Files selected for processing (1)

• docs/API.md

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f830d0ea44

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Remove the nonexistent Humans-vs-Nations stats bucket

Integrations cannot retrieve the advertised Humans-vs-Nations counters from this response: PlayerStatsTreeSchema allows the public/private/singleplayer trees to contain only the Free For All and Team modes, while ranked statistics are split into 1v1 and 2v2; there is no Humans-vs-Nations leaf. Clients modeled on this description may therefore look for a bucket that valid profiles never expose.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Do not promise username in ranked entries

A ranked response is not required to contain this username field: RankedLeaderboardEntrySchema defines accountUsername and public_id but deliberately drops the legacy username, and the canonical leaderboard fixtures omit it. The shipped list also falls back directly from accountUsername to public_id, so integrations relying on this documented fallback can receive undefined; remove the field or mark it as non-contractual legacy data.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Document the matchmaking WebSocket

This claims to document the public WebSocket API used by the game client, but the reference contains no WebSocket route at all. The shipped ranked flow in src/client/Matchmaking.ts connects to /matchmaking/join with instance_id and mode, then authenticates through an initial JWT-bearing message, and tests/matchmaking treats that handshake as the integration contract; omitting it leaves integrations unable to reproduce the game's matchmaking flow.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Show the sessions response array

The endpoint returns a list of recorded sessions, but this example shows only a bare session object and never defines the top-level response as an array. An integration modeled on the example can attempt to parse the wire response as one object, or invent a results envelope like the neighboring game-history endpoint, so wrap the item in the actual array response.

Useful? React with 👍 / 👎.