API¶
PoracleNG provides a REST API for external tools (e.g. PoracleWeb) to manage users, tracking, geofences, and configuration. The processor is a single binary — there is no separate alerter component, and the entire API is served from the processor on its configured port (default 3030).
Canonical endpoint reference
This page summarises the API surface for the documentation site. For the authoritative, always-up-to-date endpoint reference — including request/response payloads, the new /api/humans/{id}/locations/* named-location endpoints, the DTS editor (/api/dts/templates, /api/dts/reload, /api/dts/actions), and the auto-create surface — see API.md in the PoracleNG repo. It tracks the source code more closely than these per-page summaries.
Authentication¶
API access requires setting an api_secret in the [processor] section of config.toml:
Requests must include the secret in the X-Poracle-Secret header:
Note
Leave api_secret blank (or unset) to disable the authenticated API entirely. The public endpoints (POST /, GET /health, GET /metrics) remain accessible.
Backward compatibility
For installs migrating from older Poracle releases, an api_secret defined under [alerter] will still be read and copied into [processor] at load time. New configs should use [processor] directly.
Public Endpoints¶
These do not require the X-Poracle-Secret header.
| Method | Path | Description |
|---|---|---|
POST |
/ |
Receive scanner webhooks (Golbat / RDM) |
GET |
/health |
Health check |
GET |
/metrics |
Prometheus metrics |
GET |
/debug/pprof/* |
Go pprof endpoints (when enabled) |
Authenticated Endpoints¶
All endpoints below sit under /api/ and require X-Poracle-Secret.
Reload¶
| Method | Path | Description |
|---|---|---|
POST / GET |
/api/reload |
Reload state from the database |
POST / GET |
/api/geofence/reload |
Reload geofences from disk |
Data¶
| Method | Path | Description |
|---|---|---|
GET |
/api/weather |
Current weather state |
GET |
/api/stats/rarity |
Pokemon rarity groups |
GET |
/api/stats/shiny |
Shiny rate statistics |
GET |
/api/stats/shiny-possible |
Pokemon observed as shiny |
GET |
/api/geocode/forward |
Forward geocode lookup |
POST |
/api/test |
Inject a synthetic webhook for template / delivery testing |
Geofences¶
See Geofence API for full detail.
| Method | Path | Description |
|---|---|---|
GET |
/api/geofence/all |
Loaded geofences (raw) |
GET |
/api/geofence/all/geojson |
Loaded geofences as GeoJSON |
GET |
/api/geofence/all/hash |
Hash of current geofence set |
GET |
/api/geofence/:area/map |
Static map for a named area |
GET |
/api/geofence/locationMap/:lat/:lon |
Static map centred on a point |
GET |
/api/geofence/distanceMap/:lat/:lon/:distance |
Static map with distance ring |
GET |
/api/geofence/weatherMap/:lat/:lon |
Static map with weather overlay |
POST |
/api/geofence/overviewMap |
Overview map (POST body) |
Humans, tracking, profiles, config¶
These endpoints back PoracleWeb's user-facing functionality. See Humans API and Config API for detail.
| Path prefix | Description |
|---|---|
/api/humans/* |
User CRUD |
/api/tracking/* |
Per-user tracking rules |
/api/profiles/* |
Profile CRUD |
/api/config/* |
Configuration queries used by PoracleWeb |
Auto-create¶
See Auto-create API for the full capability outline.
| Method | Path | Description |
|---|---|---|
GET / POST / DELETE |
/api/autocreate/templates* |
Read, validate, write, and delete channel templates |
GET |
/api/autocreate/templates/schema |
Schema metadata for editor UIs |
POST |
/api/autocreate/run |
Trigger a bulk sync of one or all rules |