API Reference

API Reference

hailsDotGO exposes a read-only JSON API for the game data it aggregates, a set of session-authenticated endpoints used by the site frontend, and a private API tier for trusted consumers. This page documents the endpoints, rate limits, and authentication rules. A live, always-current version of the public and private API tables is on the site itself: open https://pogo.hails.live/credits and switch to the API tab.

All endpoints are relative to the site root (for the production instance, https://pogo.hails.live). Errors are returned as JSON objects of the form {"error": "message"} with an appropriate HTTP status.

Public data endpoints

No authentication required. All responses carry Cache-Control: public, max-age=300.

Endpoint	Method	Returns	Rate limit (per IP)
/api/data	GET	Combined bundle: Pokemon stats, moves, raids, Max Battles, shinies, shadow list, type chart, CP multipliers, types, localized names	10 per 2 minutes
/api/raids	GET	Current raid bosses grouped by tier ("1", "3", "5", "6" for Mega; Shadow bosses fold into their tier with a Shadow name prefix)	10 per 2 minutes
/api/maxbattles	GET	Current Max Battle bosses grouped by tier ("1", "2", "3")	10 per 2 minutes
/api/events	GET	Current and upcoming events (ScrapedDuck feed)	10 per 2 minutes
/api/events/{id}	GET	Sanitized HTML detail for one event; id must match ^[a-z0-9-]{1,128}$	30 per 2 minutes
/api/pokemon	GET	Pokemon base stats	10 per 2 minutes
/api/moves	GET	{"fast": [...], "charged": [...]} move data	10 per 2 minutes

Bandwidth cap

On top of the request limits, the public data endpoints share a per-IP bandwidth budget: 15 MB per rolling 5-minute window, counted across all of the endpoints above. Exceeding it blocks the IP from these endpoints for 30 minutes and returns 429 with {"error":"bandwidth limit exceeded, try again later"}. Logged-in site users are unaffected because the frontend uses the session endpoint below.

Where the data comes from and how often it refreshes is documented in Data Sources.

Authenticated endpoints (session cookie)

These are the endpoints the site frontend uses. Authentication is the hgo_session cookie; there are no API keys. Mutating requests from a browser must also send the CSRF token in the X-CSRF-Token header (the token is rendered into every page; gorilla/csrf pairs it with the _gorilla_csrf cookie). The PayPal webhook is the only CSRF-exempt route.

Endpoint	Method	Purpose
/api/app/data	GET	Same payload as /api/data, but session-authenticated and not subject to the public rate limits
/api/weather	GET	Current in-game weather and boosted types for the user's saved location (see Accounts and Roles)
/api/shinies	GET	The user's shiny collection
/api/shinies	POST	Add a shiny
/api/shinies/{id}	PUT	Update a shiny entry
/api/shinies/{id}	DELETE	Remove a shiny entry

Social and feedback endpoints

See Social Features for the full behavioural description.

Endpoint	Method	Auth	Purpose
/api/social/{username}	GET	session	Relationship state: {is_self, is_friend, is_blocked, they_blocked_you}
/api/social/{username}/friend	POST	session + CSRF	Add {username} as a friend
/api/social/{username}/friend	DELETE	session + CSRF	Remove friend
/api/social/{username}/block	POST	session + CSRF	Block {username}; removes friendship in both directions
/api/social/{username}/block	DELETE	session + CSRF	Unblock
/api/notifications	GET	session	Active raids (open, full, raiding) hosted by the caller's friends; used by the 🔔 badge poller and the /notifications page
/api/feedback/{username}	GET	none	All feedback entries for {username} (public)
/api/feedback/{username}	POST	session + CSRF	Submit or update your feedback; body {"option_id": N}
/api/feedback/entry/{id}	DELETE	session + CSRF	Delete your own feedback entry
/api/users/search?q=	GET	session	Search trainers by username or trainer name; returns [{username, trainer_name}]

Admin-only feedback option management (Admin role required):

Endpoint	Method	Purpose
/api/admin/feedback-options	GET	List all feedback options
/api/admin/feedback-options	POST	Create a new option
/api/admin/feedback-options/{id}	PUT	Update label, sentiment, sort order, or enabled state
/api/admin/feedback-options/{id}	DELETE	Delete an option

Raid Finder endpoints

The full lobby lifecycle behind these is described in Raid Finder.

Endpoint	Method	Auth	Purpose
/api/raid/overview	GET	none	Public overview: per-boss open lobby and queue counts plus open custom lobbies (slow poll)
/api/raid/state	GET	session	The caller's full raid state: queue position, lobby, deadlines, feedback owed (fast poll; doubles as the queue heartbeat)
/api/raid/queue	POST	session	Join the matchmaking queue for a boss
/api/raid/queue	DELETE	session	Leave the queue
/api/raid/lobbies	POST	session	Create a lobby (host)
/api/raid/lobbies/{id}	DELETE	session	Cancel a lobby (host or staff)
/api/raid/lobbies/{id}/confirm	POST	session	Member confirms within the confirm window
/api/raid/lobbies/{id}/leave	POST	session	Member leaves the lobby
/api/raid/lobbies/{id}/kick	POST	session	Host or staff removes a member
/api/raid/lobbies/{id}/invited	POST	session	Host confirms in-game invites were sent
/api/raid/lobbies/{id}/report	POST	session	Host's post-raid attendance report
/api/raid/lobbies/{id}/feedback	POST	session	Member's post-raid feedback (raid success, commend or dislike)

Awards endpoints

See Trust and Awards for granting rules.

Endpoint	Method	Auth	Purpose
/api/awards	GET	none	Active award catalog
/api/awards/of/{username}	GET	none	Awards a user has received
/api/awards/{id}/grant	POST	session	Grant an award by username (staff always; community granting behind a feature flag plus a minimum trust score)
/api/shinies/of/{username}	GET	none	A user's public shiny collection; includes sprite_url (shiny variant, pre-resolved). Returns [] when the user does not exist, has a private profile, or has enabled Hide shiny collection in Settings

Private API

The private tier mirrors the public data endpoints without the public rate limits and bandwidth cap, and adds a refresh trigger. It requires the api_access account flag, which only the superadmin can grant and which only takes effect on admin accounts (the superadmin always has access). Requests still authenticate with the session cookie. Contact the site operator to request access.

Endpoint	Method	Notes
/api/private/data	GET	Mirror of /api/data
/api/private/raids	GET	Mirror of /api/raids
/api/private/maxbattles	GET	Mirror of /api/maxbattles
/api/private/events	GET	Mirror of /api/events
/api/private/events/{id}	GET	Mirror of /api/events/{id}
/api/private/pokemon	GET	Mirror of /api/pokemon
/api/private/moves	GET	Mirror of /api/moves
/api/refresh	POST	Triggers an immediate background re-fetch of all PoGoAPI data; globally limited to 2 requests per 10 minutes across all callers

Webhook

Endpoint	Method	Notes
/api/store/webhook	POST	PayPal server-to-server webhook (CHECKOUT.ORDER.APPROVED). CSRF-exempt; authenticity is checked by verifying the transmission signature against PAYPAL_WEBHOOK_ID through PayPal's verification API. Always answers 200 so PayPal does not retry. See Store.

Auth and admin routes

Login, registration, settings, translation, and the admin toolset are session-flow routes rather than a stable API surface and are intentionally not exhaustively documented here. The login endpoint is limited to 10 attempts per minute per IP and registration to 5 per minute per IP. For the full admin route set and the role each action requires, see the Admin Guide; for the translation endpoints see Translator Workspace.