Filomena / Docs

API reference

Webhook, investigation, incident, economics and control endpoints.

Filomena exposes JSON APIs for ingestion, investigations, incidents, operator feedback and operational reporting. All bearer tokens use the standard header:

Authorization: Bearer <token>

Use separate ingest, read and admin tokens outside local development. When a scoped token is absent, Filomena falls back to the webhook token for compatibility.

Health and metrics

Method	Path	Authentication	Purpose
`GET`	`/health`	None	Process liveness compatibility endpoint
`GET`	`/healthz`	None	Kubernetes liveness endpoint
`GET`	`/readyz`	None	State-store readiness with a three-second timeout
`GET`	`/metrics`	Deployment policy	Prometheus exposition

Keep /metrics private. It has no application-level authentication. Persisted pipeline timestamps and 24-hour webhook, run and Slack delivery counts are included, so these signals survive a process restart.

Management UI

GET /ui/ serves the read-only operations UI from the Filomena container. The shell is available without application authentication, but it cannot read operational data until the operator enters the read token. The token is kept in browser session storage, is sent only in the Authorization header and is removed when the tab session ends or the operator disconnects.

The UI reads /v1/status, /v1/stats, /v1/runs, /v1/runs/{runId} and /v1/incidents. It has no write actions and loads no external scripts, fonts or images.

Ingestion

`POST /v1/webhooks/grafana`

Requires the ingest token. Accepts the Grafana webhook schema with at least one alert and returns:

{
  "accepted": 1,
  "duplicate": 0,
  "deferred": 0
}

accepted means the event is persisted. deferred means the in-memory queue was full; the recovery worker can pick the persisted event up later. A repeated event identity increments duplicate.

`POST /v1/changes`

Requires the ingest token. Records a deployment, configuration, feature-flag, CI/CD or infrastructure change for later correlation.

{
  "changeId": "deploy-checkout-20260822-1",
  "occurredAt": "2026-08-22T19:00:00Z",
  "kind": "deployment",
  "service": {
    "namespace": "shop",
    "name": "checkout",
    "environment": "production",
    "cluster": "prod-eu"
  },
  "source": "argocd",
  "summary": "checkout moved to image sha256:...",
  "url": "https://argocd.example/applications/checkout",
  "attributes": {}
}

The endpoint returns 202 for a new change and 409 for a duplicate change ID.

Investigations

`GET /v1/runs`

Requires the read token. Lists runs newest first. Supported query parameters:

Parameter	Constraint
`fingerprint`	64-character fingerprint
`eventId`	Event ID, 64 characters or fewer
`service`	Service name, 200 characters or fewer
`status`	Run status
`limit`	1 to 200, default 50
`completedBefore`	Pagination timestamp
`completedBeforeRun`	Pagination run ID

Send both pagination values returned by a full page on the next request. Repeated query parameters are rejected.

`GET /v1/runs/{runId}`

Requires the read token. Returns the alert, complete diagnosis, collected evidence, run economics and latest feedback. Treat this response as sensitive because evidence may contain logs and operational history.

`GET /v1/stats`

Requires the read token. Returns alert and run counts, status totals, feedback outcomes, token usage, estimated cost, processing latency and per-service totals. Supported query parameters are from, to, service and environment. The default window is 24 hours and the maximum is 90 days. The response sets truncated when the window exceeds the 10,000-run scan bound.

`GET /v1/status`

Requires the read token. Returns the last persisted webhook, completed run, Slack delivery and successful Slack delivery timestamps, plus 24-hour counts and the latest Slack delivery result.

`POST /v1/investigate`

Requires the admin token. Starts a bounded investigation for a service without waiting for an alert to fire. Only service.name is required; the remaining service fields default to empty.

{
  "service": {
    "name": "checkout",
    "environment": "production",
    "kubernetesNamespace": "shop-prod",
    "owner": "payments"
  },
  "reason": "latency climbing since the last deploy"
}

Returns 202 with the eventId and fingerprint of the queued investigation, or 503 when the queue is full. Poll GET /v1/runs?eventId=<eventId> for that specific result: investigations of one service share a fingerprint, so filtering by fingerprint can return a different request's run.

An investigation is best effort. Unlike an alert, it has no recovery sweep, so one that is in flight when the process stops is lost and produces no run. Retrying is safe: each request is its own event. If you need a guarantee that a run is eventually recorded, an alert is the durable path.

An investigation is not an alert, so it runs on its own path: it never attaches to an incident, and it is never suppressed as a repeat. Two investigations of the same service inside DedupWindowMinutes both do real work. Runs are recorded with mode investigation.

filomena-investigate is reserved: POST /v1/webhooks/grafana rejects any inbound alert carrying a reserved rule UID, so the UID is a trustworthy record of who started a run rather than a guess. Investigation events are also excluded from the alert recovery sweep, so a restart cannot push one back through triage and attach it to an incident.

The fingerprint is derived from the rule UID filomena-investigate plus the canonical service key (namespace, name, environment), length-prefixed so a / inside a field cannot forge another service's identity. A cluster migration, Kubernetes namespace move or workload rename therefore keeps a service joined to its own confirmed prior cases, while those infrastructure fields are still carried on the event because evidence collection is scoped by them.

`POST /v1/runs/{runId}/retriage`

Requires the admin token. Creates a fresh firing event from the selected run and collects new evidence.

`POST /v1/runs/{runId}/verify`

Requires the admin token. Records an operator recovery verdict.

{
  "status": "recovered",
  "details": "Error rate returned below the SLO threshold.",
  "actor": "on-call@example.com"
}

status must be recovered, still_affected or unknown.

Incidents and enrichment

`GET /v1/incidents`

Requires the read token. Filters by status=open|resolved, service and limit from 1 to 200.

`GET /v1/grafana/enrichment/{fingerprint}`

Requires the read token. Returns the latest diagnosis, its incident, verification history and source links for a 64-character alert fingerprint.

`GET /v1/coverage`

Requires the read token. Reports recent service-identity coverage, enabled providers and whether scoped tokens are configured.

`GET /v1/packs`

Requires the read token. Lists enabled diagnostic packs with required labels and evidence signals.

Feedback and audit

`POST /v1/feedback`

Requires the admin token. The run must exist and its stored fingerprint must match the submitted fingerprint.

{
  "runId": "RUN_ID",
  "fingerprint": "64_CHARACTER_FINGERPRINT",
  "verdict": "correct",
  "rootCause": "Memory limit below the workload working set.",
  "resolution": "Raised the limit and corrected the deployment default.",
  "actor": "on-call@example.com"
}

verdict must be correct, partial or incorrect.

`GET /v1/audit`

Requires the admin token. Returns up to 500 audit events. The default limit is 100.

`POST /v1/slack/interactions`

Uses Slack request signing, not bearer authentication. Expose this route only when interactive Slack feedback is enabled.

Economics

`GET /v1/economics`

Requires the read token. Summarizes the latest 200 completed investigations: model tokens and estimated cost, evidence breadth, feedback outcomes and resolved-incident duration.