API Reference

Authentication

Authenticate with a bearer token created in the dashboard. Tokens can be scoped per-zone and expire on a schedule you choose.

curl https://api.benediction.site/v1/zones \
  -H "Authorization: Bearer $BENEDICTION_TOKEN"

List zones

GET /v1/zones

{
  "result": [
    {
      "id": "2c6f0a1b-…",
      "name": "example.com",
      "status": "active",
      "dnssec": true,
      "tls_mode": "full",
      "created_at": "2024-03-12T09:40:21Z"
    }
  ],
  "success": true,
  "result_info": { "page": 1, "per_page": 20, "total": 1 }
}

Add a zone

POST /v1/zones

curl -X POST https://api.benediction.site/v1/zones \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"example.com","type":"full"}'

# 201 Created
# {
#   "result": {
#     "id": "9f3c…",
#     "name": "example.com",
#     "status": "pending",
#     "nameservers": ["ns1.benediction.site", "ns2.benediction.site"]
#   },
#   "success": true
# }

Purge cache

Three granularity levels are supported: one URL, everything matching a cache tag, or the whole zone.

POST /v1/zones/{zone_id}/purge_cache
# {"files":["https://example.com/assets/app.js"]}   → single file
# {"tags":["release-2026-07"]}                       → by cache tag
# {"purge_everything":true}                          → whole zone

Create a DNS record

curl -X POST https://api.benediction.site/v1/zones/9f3c…/dns_records \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "CNAME",
    "name": "app",
    "content": "edge.benediction.site",
    "ttl": 300,
    "proxied": true
  }'

# 201 Created
# {
#   "result": {
#     "id": "aa12…",
#     "type": "CNAME",
#     "name": "app.example.com",
#     "content": "edge.benediction.site",
#     "proxied": true
#   },
#   "success": true
# }

List analytics

GET /v1/zones/{zone_id}/analytics
  ?since=2026-07-01T00:00:00Z
  &until=2026-08-01T00:00:00Z
  &granularity=hourly

Returns request volume, bandwidth, cache hit ratio, status-code distribution, top URLs, and security events — unsampled.

Error responses