cx-nexredirect/docs/API.md

API

Public REST-API für CoreX NexRedirect. Versioniert unter /api/v1. JSON-only.

Auth

Tokens erstellen unter Einstellungen → API-Tokens im Web-UI. Token wird nur einmalig angezeigt — sicher kopieren.

Format: nrx_<64-hex>. Im Header senden:

Authorization: Bearer nrx_<your-token>

Tokens haben Scopes:

Scope	Erlaubt
read:domains	Domains lesen
write:domains	Domains anlegen/löschen
read:analytics	Aggregierte Statistiken
read:hits	Roh-Hits (nur ip_hash, kein Klartext-IP)

Fehler-Format:

{ "error": "forbidden", "code": "missing_scope", "required": "read:domains" }

Endpoints

GET /api/v1/health

Liveness-Check. Kein Token nötig.

curl https://admin.firma.de/api/v1/health
# {"ok":true,"ts":1714500000000}

GET /api/v1/version

Aktuelle Version + Update-Status. Kein Token nötig.

{
  "current": "0.1.0",
  "latest": "0.1.1",
  "update_available": true,
  "release_url": "https://github.com/.../releases/tag/v0.1.1",
  "auto_update": false
}

GET /api/v1/domains

Scope: read:domains

curl -H "Authorization: Bearer nrx_..." https://admin.firma.de/api/v1/domains

{
  "domains": [
    {
      "id": 1, "domain": "alt-firma.de", "status": "active",
      "target_url": "https://www.firma.de", "redirect_code": 301,
      "preserve_path": 1, "include_www": 1,
      "total_hits": 142, "last_hit": 1714499000000
    }
  ]
}

POST /api/v1/domains

Scope: write:domains

Body:

{
  "domain": "alt-firma.de",
  "target_url": "https://www.firma.de",
  "redirect_code": 301,
  "preserve_path": true,
  "include_www": true
}

Response (201):

{
  "domain": { "id": 5, "status": "pending", ... },
  "dns_records": [
    { "type": "A", "name": "alt-firma.de", "value": "203.0.113.42" },
    { "type": "A", "name": "www.alt-firma.de", "value": "203.0.113.42" }
  ]
}

DNS muss anschließend gesetzt + verifiziert werden (über UI oder via internen /api/domains/:id/verify-Endpoint, der einen User-Login erfordert).

GET /api/v1/domains/:id

Scope: read:domains

DELETE /api/v1/domains/:id

Scope: write:domains

GET /api/v1/domains/:id/stats?days=30

Scope: read:analytics

{
  "domain_id": 1, "days": 30, "total": 412,
  "daily": [{"day":"2026-04-01","hits":12}, ...],
  "by_country": [{"country":"DE","hits":380},{"country":"AT","hits":18}, ...]
}

GET /api/v1/analytics/summary?days=30

Scope: read:analytics

{
  "days": 30, "total": 12480,
  "daily": [...],
  "top": [{"id":1,"domain":"alt-firma.de","hits":412}, ...],
  "by_country": [...]
}

GET /api/v1/hits?domain_id=1&limit=100

Scope: read:hits

{
  "hits": [
    {
      "id": 9001, "domain_id": 1, "ts": 1714499000000,
      "ip_hash": "9f4a...", "country": "DE",
      "user_agent": "Mozilla/5.0 ...", "referer": null, "path": "/"
    }
  ]
}

ip_hash = sha256(ip + täglicher Salt). Kein Klartext-IP wird gespeichert.

Versionierung

/api/v1 ist stabil. Breaking-Changes erscheinen unter /api/v2. Deprecation-Hinweise im Sunset-Header.

Rate-Limits

Kein hartes Limit aktuell. Empfehlung: max. 60 Requests/Minute pro Token. Bei Problemen Token rotieren.

Beispiele

Uptime-Check eines Tokens:

curl -fsS -H "Authorization: Bearer $NRX" https://admin.firma.de/api/v1/health || echo "DOWN"

Liste tote Domains (0 Hits / 90d):

curl -s -H "Authorization: Bearer $NRX" \
  "https://admin.firma.de/api/v1/analytics/summary?days=90" \
  | jq '.top | map(select(.hits == 0))'

Domain anlegen + DNS-Records anzeigen:

curl -X POST -H "Authorization: Bearer $NRX" -H "Content-Type: application/json" \
  -d '{"domain":"shop.alt.de","target_url":"https://shop.firma.de"}' \
  https://admin.firma.de/api/v1/domains | jq '.dns_records'