{% extends "base.html" %} {% block title %}API Documentation - {{ app_name }}{% endblock %} {% block content %}

API Documentation

REST API for geo-blocking configuration generation.

Base URL:
API Usage Guidelines

Choose the endpoint based on your integration needs.

Use Case Recommended Endpoint
Programmatic CIDR integration (TXT / CSV / JSON / JS) POST /api/generate/raw
Download ready-to-use application config (nginx / apache / haproxy) POST /api/generate
Web UI preview (admin panel) POST /api/generate/preview
UI-only: /api/generate/preview is intended for internal web UI usage. It returns JSON with a raw config string + metadata and is not recommended for external production integrations.
Recommendation: Avoid nginx + map for production. Prefer nginx variants geo or deny.
GET /health Service health check

Simple liveness probe.

Returns JSON.
GET /api/countries Get available countries

Returns list of countries with ISO codes and flag emojis.

Response Schema
{
  "success": true,
  "countries": [
    {"code": "CN", "name": "China", "flag": "🇨🇳"}
  ]
}
GET /api/database/status Check MaxMind DB status

Database status including update need and timestamps.

Response Schema
{
  "success": true,
  "exists": true,
  "needs_update": false,
  "last_update": "2026-02-10T08:00:00",
  "file_size": 5242880,
  "auto_update": true
}
POST /api/database/update Trigger MaxMind DB update

Manual database update (download + replace).

Response Schema
{
  "success": true,
  "url": "https://github.com/...",
  "size": 5242880
}
GET /api/cache/redis/status Redis L1 status

Redis health + key stats.

GET /api/cache/sqlite/status SQLite L2 status

SQLite cache file stats and top countries.

POST /api/cache/invalidate/<country_code> Invalidate a single country

Clears Redis networks for a country + related cached configs.

ISO 3166-1 alpha-2
cURL
curl -X POST /api/cache/invalidate/CN
POST /api/cache/flush Flush Redis cache (all keys)

Flushes all Redis keys used by the application.

cURL
curl -X POST /api/cache/flush
GET /api/progress Generation progress

Poll this endpoint during generation.

GET /api/stats/summary Combined status summary

Aggregated status of MaxMind + SQLite + Redis.

POST /api/generate/preview UI preview (JSON wrapper)
UI-only: Intended for internal web UI. Response is JSON, but config contains raw text.
Request Body
{
  "countries": ["SG"],
  "app_type": "haproxy",
  "app_variant": "map",
  "aggregate": true,
  "use_cache": true
}
Shows headers + JSON response.
POST /api/generate/raw Raw blocklist (TXT / CSV / JSON / JS)

Output format is selected by app_type. Cache metadata is returned via response headers.

Supported Modes
app_typeContent-TypeNotes
raw-cidr_txttext/plaindefault
raw-cidr_csvtext/csvCSV export
raw-cidr_jsonapplication/json{countries, networks, count, aggregated}
raw-cidr_json + as_js=trueapplication/javascriptconst <js_var> = {...};
raw-jsonapplication/jsonalias (same schema as raw-cidr_json)
Example JSON Schema (raw-cidr_json / raw-json)
{
  "countries": ["SG"],
  "networks": ["1.2.3.0/24", "..."],
  "count": 123,
  "aggregated": true
}
Tip: set use_cache to false to force fresh scan.
“Download result” saves response as file (TXT/CSV/JSON/JS).
cURL Examples

JSON:

curl -X POST /api/generate/raw \
  -H "Content-Type: application/json" \
  -d '{"countries":["PL"],"app_type":"raw-cidr_json","aggregate":true,"use_cache":true}' \
  -o blocklist.json

JSON (alias raw-json):

curl -X POST /api/generate/raw \
  -H "Content-Type: application/json" \
  -d '{"countries":["CN"],"aggregate":true,"use_cache":true,"app_type":"raw-json"}' \
  -o blocklist.cn.json

JS wrapped:

curl -X POST /api/generate/raw \
  -H "Content-Type: application/json" \
  -d '{"countries":["PL"],"app_type":"raw-cidr_json","as_js":true,"js_var":"geoipBlocklist"}' \
  -o blocklist.js

TXT (default):

curl -X POST /api/generate/raw \
  -H "Content-Type: application/json" \
  -d '{"countries":["PL"]}' \
  -o blocklist.txt

CSV:

curl -X POST /api/generate/raw \
  -H "Content-Type: application/json" \
  -d '{"countries":["PL"],"app_type":"raw-cidr_csv"}' \
  -o blocklist.csv
POST /api/generate Download configuration file

Returns a file download (text/plain). Use the download action below.

Not recommended: nginx + map. Prefer nginx geo / deny.
Supported Variants
app_typeapp_variantRecommendation
nginxgeorecommended
nginxdenyrecommended
nginxmapnot recommended
apache24recommended
apache22legacy
haproxymaprecommended
haproxyaclOK
haproxyluaOK
Use use_cache:false to force fresh scan. Prefer haproxy map or apache 24 / nginx geo.
Preview shows headers + first ~80 lines.
cURL (recommended variants)

HAProxy (map):

curl -X POST /api/generate \
  -H "Content-Type: application/json" \
  -d '{"countries":["SG"],"app_type":"haproxy","app_variant":"map","aggregate":true,"use_cache":true}' \
  -o geoblock_haproxy_map.cfg

Apache 2.4:

curl -X POST /api/generate \
  -H "Content-Type: application/json" \
  -d '{"countries":["SG"],"app_type":"apache","app_variant":"24","aggregate":true,"use_cache":true}' \
  -o geoblock_apache24.conf

Nginx (geo):

curl -X POST /api/generate \
  -H "Content-Type: application/json" \
  -d '{"countries":["SG"],"app_type":"nginx","app_variant":"geo","aggregate":true,"use_cache":true}' \
  -o geoblock_nginx_geo.conf
{% endblock %} {% block scripts %} {% endblock %}