HTTP API

The panel uses the JSON API at /api/v1. Response shapes may change between minor versions. There is no OpenAPI document.

Paths

Unknown paths under /api, /agent, /auth, /e, /ping, /hooks, and /mcp answer 404. Other unknown paths load the panel.

/api/v1

Reads take range=1h, 24h, 7d, 30d, or 1y, or from and to in milliseconds (up to 400 days), but not both.

read means a session of any role or a read or write token. write means an admin’s session or a write token. A viewer’s session gets 403 “only admins can do this”.

Authentication

The panel uses kogut_session after password or OpenID Connect sign-in. Forward auth uses the proxy’s identity headers instead. Sessions last 30 days. The cookie is HttpOnly, SameSite=Lax, and Secure with an HTTPS public URL.

API tokens start with kg_ and go only in the Authorization: Bearer <token> header, not in query parameters. A token takes precedence over a cookie. Missing credentials return 401, the wrong scope 403. kogut status, kogut incidents, and kogut checks take a read token.

The panel also offers ping and agent scopes, which no route accepts yet. Heartbeats use their ping URL, and agents the host token from Hosts → Add a server.

Tokens are shown once, at creation. kogut stores their SHA-256 hashes and last-use times. Writes authenticated by a cookie or forward auth need an Origin equal to [server] url, or to the request’s Host when no URL is set. Bearer tokens do not.

Ping URLs

POST /api/v1/checks/{id}/ping-url returns 201 with {"url": "https://kogut.acme.com/ping/btp_...", "replaced": false}. The heartbeat’s public id is in GET /api/v1/services/{name}. Another call invalidates the old URL and returns replaced: true. A ping_token from kogut.toml is not replaced and keeps working; replaced counts only URLs made here.

Checks

POST /api/v1/checks validates checks and heartbeats by the configuration rules, with durations in milliseconds. Nullable fields may be omitted; null uses the default:

{
  "name": "API health", "service": "api", "kind": "http",
  "target": "https://api.acme.com/health", "method": null,
  "everyMs": 30000, "timeoutMs": null, "from": null,
  "expect": [
    { "status": "2xx", "bodyContains": null, "bodyNotContains": null, "json": null,
      "equals": null, "responseTimeBelowMs": null, "degraded": false }
  ],
  "cron": null, "timezone": null, "graceMs": null
}

kind is http, tcp, dns, ping, domain, or heartbeat. command exists only on command checks from an agent’s host and is refused here with 422. target is the URL, host:port, DNS name, ping host, or registered domain. Ping assertions take only responseTimeBelowMs. Domain checks take neither everyMs nor from. Heartbeats take everyMs or cron, optional timezone, and graceMs, and no target. from names an agent host. Missing services are created.

Success returns 201 with {"id": "<public id>"} and schedules the check at once. A name conflict returns 409, invalid values 422 with the field in the detail. PUT /api/v1/checks/{id} takes the same body. DELETE removes the check and its history. File-managed and command checks refuse both with 409. GET returns {id, managed, hostDefined, input}.

POST /api/v1/discovered/monitor takes {host, service, check}, where check is the body above or null. It atomically creates a missing service, links the host, and adds the check, and returns 201 with {service, check}. File-managed services return 409.

Drafts

GET /api/v1/drafts returns {drafts}, oldest first. Each draft has id, check (the check body that approving creates), proposedBy (such as token "assistant"), createdAt, expiresAt, and problem: why approving would fail now, or null.

POST /api/v1/drafts/{id}/approve creates the check as POST /api/v1/checks does and returns 201 with {"id": "<public id>"}. A name conflict returns 409 and invalid values 422; the draft stays open. POST /api/v1/drafts/{id}/reject returns 204 and creates nothing. Both return 404 for an unknown draft and 409 for one already decided or expired. Tokens of every scope and viewers’ sessions get 403. Changes to drafts invalidate drafts in the event stream.

A check’s runs

GET /api/v1/checks/{id}/detail accepts a range, default 24h, and returns:

expiry is {kind, expires, seen} for the latest observed certificate or domain registration, or null without one or after the target host, port, or domain changes. Service check rows include it too.

GET /api/v1/checks/{id}/history accepts before in milliseconds and limit from 1 to 100, default 20. It returns {items, next}, newest first. Each item has {ts, kind, status, title, detail, latencyMs}:

• failure is a down or degraded run, kept for [retention] check_results.
• change is a check or certificate state change, including before a service move.

next is the next page’s before, or null at the end. Pages never split a timestamp, so a page can have fewer items than limit, or more when the newest timestamp alone has more. Both endpoints return 404 for unknown ids and use service:<name> live invalidations.

Incident timeline rows have the changed check’s id in check, or null, and for a deploy or change who made it in by and its link in url. Incident timelines also show changes of no service or host. The overview lists every change in the range in changes; a service or host lists its own.

Channels

POST /api/v1/channels accepts these fields:

PUT /api/v1/channels/{name} takes the same body and name. secret: null keeps the stored secret, and for Slack and Discord url: null keeps the stored URL. An empty string removes an optional secret. File-managed channels refuse changes with 409.

In GET /api/v1/settings, admins and write tokens get each panel channel’s settings without secrets and with hasSecret. Viewers and read tokens get settings: null, since URLs may contain secrets.

kogut watchdogs

Both return 204 and send the first request at once. PUT and DELETE return 409 while kogut.toml sets the same thing.

GET /api/v1/watchdog returns {edge, heartbeat}. Each is null or an object with {address, managed, lastSentAt, lastError, lastErrorAt}, without tokens. A heartbeat address shows only the host. lastError stays set until a request succeeds.

Silences and maintenance

POST /api/v1/silences and POST /api/v1/maintenance take:

{ "scope": "service", "name": "api", "starts": 1760533200000, "ends": 1760536800000,
  "reason": "database upgrade" }

scope is all, service, or host; name is null for all. A window must end after it starts, end in the future, and last at most 90 days. createdBy records the caller. PUT .../{id} changes scope, times, and reason, and DELETE .../{id} removes the window. GET /api/v1/settings lists ids under holds.

Conventions

Incidents and other objects use 16-character hexadecimal public ids, such as 3f9c2e1a7b4d0c55. Services and hosts use names. Timestamps are UTC milliseconds since the Unix epoch.

Errors use application/problem+json with type: "about:blank", status, title, and an optional detail. 429 means a client rate limit, and 503 that the server is at capacity, such as a full write queue. Both include Retry-After in seconds.

Addresses come from X-Forwarded-For only behind a proxy in trusted_proxies in kogut.toml.

Live updates

GET /api/v1/stream sends invalidations as server-sent events, at most every 500 ms:

data: {"invalidate":["incident:3f9c2e1a7b4d0c55","incidents","overview","service:api"]}

"*" invalidates everything. Fetch invalidated resources again. A : ping comment after 25 idle seconds keeps the connection open.

Metrics

GET /metrics returns Prometheus text to a session or a read or write token:

scrape_configs:
  - job_name: kogut
    scheme: https
    authorization:
      credentials: kg_...
    static_configs:
      - targets: ["kogut.acme.com"]

It has kogut_check_runs_total, kogut_ingest_accepted_total, kogut_ingest_rejected_total, kogut_agent_unknown_frames_total, kogut_writer_commits_total, kogut_agents_connected, kogut_outbox_due, and kogut_engine_up. kogut_ingest_accepted_total has an endpoint label: tracker, ping, deploy, change, or agent. kogut_ingest_rejected_total has a reason label: invalid, unknown_site, bot, extension (JavaScript errors from browser extensions), rate_limited, or queue_full.