API guide

When your own tool (Warcon, an admin panel, a bot) bans a player because of a hub report, it can tell the hub. Your ban then shows on the report and its Discord posts ("Banned by N communities"), exactly like clicking Banned in Discord. The same API lets your tool read new reports, look up players and download a ban list.

The hub never bans anyone. How you use the reports on your own server is your community's decision.

1. Create a key

Owners and admins of a community can do this.

Sign in, then open Settings → API keys.
Give the key a label that says what will use it, for example "Warcon".
Tick the scopes it needs. To record bans you need reports:read and decisions:write.
Click Create key and copy it straight away. It is shown only once.

Store the key like a password. If it leaks, revoke it in Settings; it stops working immediately.

The key acts on your community's behalf and every call is recorded in the hub's audit log under the staff member who created it. A key keeps working if that person leaves your staff, so when someone leaves, revoke their keys and create new ones.

Scope	Allows
`reports:read`	reading reports, players and the ban list
`reports:write`	filing reports and adding evidence
`decisions:write`	recording your community's decision on a report

2. Record a ban

PUT https://wardogsoverwatch.com/api/v1/reports/RH-000123/decision
Authorization: Bearer rh_yourkey…
Content-Type: application/json

{"decision": "banned", "ban_hours": 72, "note": "Banned via Warcon"}

Field	Value
`decision`	`banned`, `watching` or `dismissed`
`ban_hours`	hours for a temp ban, or `null` for a permanent ban (maximum 87600, ten years); ignored unless `decision` is `banned`
`note`	optional, up to 500 characters

Sending it again updates your community's decision, for example dismissed after you unban someone. Earlier decisions stay in the audit log.

With curl:

curl -X PUT https://wardogsoverwatch.com/api/v1/reports/RH-000123/decision \
  -H "Authorization: Bearer $OVERWATCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decision": "banned", "ban_hours": null, "note": "Perm ban via Warcon"}'

A successful call returns:

{"ref": "RH-000123", "decision": "banned", "ban_hours": null, "decided_at": "2026-10-06T12:00:00Z"}

3. Find reports to act on

All of these need reports:read.

Request	Returns
`GET /api/v1/reports?cursor=<last id>`	Sent-out reports in the categories your community subscribes to, oldest first, up to 100 at a time. Keep the highest `id` you received and pass it as `cursor` next time. Optional filters: `since` (ISO time with a time zone), `category`, `status`.
`GET /api/v1/reports/RH-000123`	One report with its evidence and every community's decision
`GET /api/v1/players/<steam64>`	A player's known names and reports, and which communities banned
`GET /api/v1/export/steam64.txt`	One Steam64 per line, refreshed hourly. Defaults to open and upheld reports; overturned, withdrawn and expired reports are never included. Optional: `categories=hate_speech,griefing` and `statuses=open,upheld,disputed`.

Rules

Decisions can be recorded only on reports that are open, disputed or upheld. Withdrawn, overturned, expired and rejected reports return 409.
A community on probation can't record decisions.
Each key may make 60 requests a minute. Checking for new reports once a minute is plenty.

Errors

Every error has the same shape:

{"error": {"code": "insufficient_scope", "message": "This key doesn't have the decisions:write scope."}}

Status	Meaning
`401`	Missing, wrong or revoked key
`403`	The key lacks the scope (`insufficient_scope`), or the action isn't allowed for your community
`404`	No such report, or one your community can't see
`409`	The report is closed (see Rules)
`422`	Invalid input; the message says which field
`429`	Too many requests; wait for the number of seconds in the `Retry-After` header

Please keep it fair

If your tool bans automatically, also watch for reports that get overturned or withdrawn and unban those players. The ban list leaves them out, so a player who drops off it is the signal to check. Banning only on upheld reports, or on reports that several communities have already banned on, avoids acting on a report that is later overturned.

Full reference

Signed-in staff can browse and try every endpoint at /api/docs.