Alert Sources Reference

Source configuration

-alert-sources-config, AKRITAS_ALERT_SOURCES_CONFIG, and the service field alert_sources_config select a strict JSON file. Enabling it requires a non-empty alert store path through -alert-store, AKRITAS_ALERT_STORE, or alert_store.

{
  "version": 1,
  "sources": [
    {
      "name": "alertmanager-main",
      "type": "alertmanager",
      "bearer_token_env": "AKRITAS_ALERTMANAGER_TOKEN"
    }
  ]
}

The file accepts 1 to 32 uniquely named sources. Names match [a-z0-9][a-z0-9._-]{0,63}. Supported type values are generic, alertmanager, uptime-kuma, and pingdom. Unknown fields, trailing JSON, unsupported versions or adapters, duplicate names, and missing secret variables fail startup.

Authentication fields can be combined:

Field	Request requirement
bearer_token_env	Authorization: Bearer <secret>
hmac_secret_env	X-Akritas-Signature: sha256=<hex> over the exact body
secret_header and secret_env	The named header must equal the secret
allow_unauthenticated	Must be explicitly true only when no authentication field is configured

The configuration stores environment-variable names, not secret values.

Ingress

POST /api/v1/alerts/{source}/webhook

The body limit is 1 MiB and one delivery can contain at most 128 events. All provider fields remain untrusted input. The legacy authenticated POST /api/v1/alertmanager/webhook route uses the same durable pipeline.

Canonical generic payload

The generic adapter accepts a versioned batch:

{
  "schema_version": 1,
  "alerts": [
    {
      "schema_version": 1,
      "state": "firing",
      "name": "HighCPU",
      "severity": "critical",
      "summary": "CPU usage is above 95%",
      "description": "pg01 has exceeded 95% for 10 minutes",
      "entity": {
        "kind": "instance",
        "id": "pg01",
        "display_name": "pg01"
      },
      "related_entities": [],
      "started_at": "2026-09-04T08:00:00Z",
      "observed_at": "2026-09-04T08:01:00Z",
      "labels": {"role": "postgresql"},
      "annotations": {},
      "links": [{"type": "generator", "url": "https://prometheus.example/graph"}],
      "deduplication_key": "highcpu-pg01-20260904",
      "correlation_key": "highcpu-pg01"
    }
  ]
}

Clients omit event_id; Akritas assigns it after acceptance. The configured adapter fixes source.type and source.name, so generic clients cannot override them. state is firing or resolved; severity is unknown, info, warning, or critical; timestamps are RFC 3339 and normalized to UTC. Missing deduplication and correlation keys are deterministically derived.

Ingestion response

{
  "delivery_id": "delivery_...",
  "accepted": true,
  "events": [
    {
      "status": "accepted",
      "event_id": "evt_...",
      "incident_id": "inc_...",
      "job_id": "job_..."
    }
  ]
}

Status	Meaning
202	At least one new event and its pending job were durably accepted.
200	Every event was a duplicate; no new job was created.
400	The payload or normalized event is invalid.
401	Source authentication failed.
404	The configured source name is unknown.
503	Alert ingestion or durable persistence is unavailable.

Query APIs

These routes use the common Akritas Bearer authentication:

GET /api/v1/incidents
GET /api/v1/incidents/{id}
GET /api/v1/alert-events/{id}
GET /api/v1/investigation-jobs/{id}
GET /api/v1/runs
GET /api/v1/runs/{id}
POST /api/v1/runs/{id}/chat

List endpoints accept limit from 1 to 1000. A completed job contains the run_id that links the incident to its structured investigation and host-owned evidence. Follow-up chat appends events to that completed Run.