GeoIP
API: GeoIP
Admin: AdminAuth() + RoleAuth("admin"). Source: geoip_handler.go, policydomain.GeoIPRule.
Agent pull (Enterprise Agent-facing): GET /api/v1/agent-geoip-rules, GET /api/v1/agent-geoip-database. Not a public website cookbook.
GET /api/v1/geoip/rules
Purpose. List GeoIP country rules.
Authentication. Admin.
Parameters. None.
Request. Empty.
Example request.
curl -sS https://manager.example.com:8443/api/v1/geoip/rules \
-H "Authorization: Bearer TOKEN"Response (200).
{
"rules": [
{
"id": 1,
"rule_type": "GEOIP_BLOCK",
"country_code": "CN",
"action": "block",
"enabled": true,
"description": "example",
"scope": "global",
"agent_ids": [],
"created_at": "2026-08-21T12:00:00Z",
"updated_at": "2026-08-21T12:00:00Z"
}
],
"count": 1
}Errors. 500 {"error":"Failed to retrieve GeoIP rules"}.
Edition. SHARED.
GET /api/v1/geoip/rules/:id
Purpose. Fetch one GeoIP rule.
Authentication. Admin.
Parameters. :id integer.
Response (200). Domain GeoIPRule object (not wrapped). 400 Invalid rule ID; 404 GeoIP rule not found.
Edition. SHARED.
POST /api/v1/geoip/rules
Purpose. Create a GeoIP country rule.
Authentication. Admin (Enterprise writes may pass license gate).
Request. Binds policydomain.GeoIPRule:
Scroll sideways to see the full table. Use the arrow keys when focused.
| Field | Required in handler |
|---|---|
rule_type | GEOIP_BLOCK or GEOIP_ALLOW |
country_code | 2-letter ISO |
action | block or allow |
enabled, description, scope, agent_ids | as on the struct |
Example request.
{
"rule_type": "GEOIP_BLOCK",
"country_code": "RU",
"action": "block",
"enabled": true,
"description": "Example block",
"scope": "global"
}Response (201). Created rule object. 400 invalid type/country/action or Invalid request body: ...; 500 create/assign failures.
Edition. SHARED.
PUT /api/v1/geoip/rules/:id
Purpose. Update a GeoIP rule. Scope/agent_ids are taken from the existing row if omitted.
Authentication. Admin.
Request. Same GeoIPRule bind. 404 if missing. 500 Failed to update GeoIP rule.
Response (200). Updated rule object.
Edition. SHARED.
DELETE /api/v1/geoip/rules/:id
Purpose. Delete by id.
Authentication. Admin.
Response (200). {"message":"GeoIP rule deleted successfully"}. 400 invalid id; 500 delete failure.
Edition. SHARED.
DELETE /api/v1/geoip/rules/country/:code
Purpose. Delete by ISO country code.
Authentication. Admin.
Parameters. :code must be length 2.
Response (200). {"message":"GeoIP rule for country XX deleted successfully"}. 400 if code length ≠ 2; 500 on delete failure.
Edition. SHARED.
GET /api/v1/geoip/settings
Purpose. Non-secret GeoIP configuration projection.
Authentication. Admin.
Response (200) (GeoIPSettingsResponse):
Scroll sideways to see the full table. Use the arrow keys when focused.
| Field | Notes |
|---|---|
enabled | from config |
database_type | default "maxmind" |
database_path | |
has_maxmind_credentials | bool; does not return the license key |
maxmind_account_id | omitempty |
update_interval_hours | |
auto_update | |
cache_size | |
allow_on_lookup_failure | |
database_status | not_loaded | loaded | error (probe lookup of 8.8.8.8) |
last_lookup_country | omitempty |
Edition. SHARED.
Security. Account ID may appear; license key never does.
GET /api/v1/geoip/status
Purpose. Service status widget.
Authentication. Admin.
Response (200). gin.H keys: enabled, database_loaded, rules_count, cache_hits, cache_misses, plus database_path / auto_update when config is set. Additional per-action counts may be added in the same object. API_SCHEMA_DOCUMENTATION_BLOCKED for additive keys after the guaranteed set above (GetGeoIPStatus mutates a gin.H).
Edition. SHARED.
POST /api/v1/geoip/lookup
Purpose. Admin GeoIP lookup for one IP against the loaded database and current rules.
Authentication. Admin. Not an unauthenticated geolocation API.
Request (GeoIPLookupRequest):
{"ip": "203.0.113.10"}ip required.
Response (200) (GeoIPLookupResponse):
{
"ip": "203.0.113.10",
"country_code": "US",
"country_name": "United States",
"is_blocked": false,
"is_allowed": false
}rule_id omitempty when a matching enabled rule exists.
Errors. 400 Invalid request: ... or Invalid IP address; 503 GeoIP lookup failed or GeoIP service not available.
Edition. SHARED.
Security. Admin-only. Example IPs in docs are RFC 5737.