Conventions

Things that hold across the whole API, written once here so the per-endpoint pages do not repeat them.

Trailing slashes

Most collection and detail routes end in a slash — /guilds/, /players/{id}/. A request without it will usually redirect rather than fail, but clients that do not follow redirects should send the slash.

Identifiers

• Players are addressed by Comlink player ID, not by ally code. Ally-code lookup is a separate route.
• Guilds are addressed by guild ID.
• Units are addressed by base_id, the game's own stable unit identifier.

Timestamps

UTC throughout, ISO 8601. History records also carry a meta block with enough denormalised detail to render a row without re-reading the underlying entity.

Refresh endpoints

Several resources expose a POST …/refresh/ sibling that re-pulls from Comlink. These are slow — a guild refresh is fifty upstream fetches — and they are not idempotent in timing: the response reflects what came back, which may differ between two calls seconds apart.

Errors

Standard FastAPI shape:

{ "detail": "…" }

Validation failures return 422 with a detail array naming the offending fields.

Rate limits

None enforced by SWGoH. The upstream Comlink API is the real constraint, which is why refresh endpoints exist as explicit actions rather than happening on every read.