HTTP API¶

A running server exposes a small, read-only HTTP API for inspecting session history. It's handy for dashboards, monitoring, and tooling. The responses match the shape of gdc sessions --json, so the same parser works for both.

Read-only

These endpoints only read session data. They don't start runs or change anything. There's no built-in authentication, so keep the server on loopback or behind an authenticating reverse proxy — see Security.

Endpoints¶

`GET /healthz`¶

Liveness check. Always returns 200.

{ "status": "ok" }

`GET /sessions`¶

List session summaries, newest first.

Query parameters (all optional):

Parameter	Effect
`limit`	Maximum rows (default 20, capped).
`cwd`	Restrict to one project root.
`all`	`true` returns every session and ignores `cwd`.

[
  {
    "id": "0e7ed5cc-...",
    "created_at_ms": 1715300000000,
    "cwd": "/home/u/proj",
    "model": "qwen2.5-coder:14b-instruct"
  }
]

`GET /sessions/{id}/messages`¶

Return one session with its full, ordered message list.

Parameter	Effect
`limit`	Return only the last n messages.

{
  "id": "...",
  "cwd": "/home/u/proj",
  "model": "qwen2.5-coder:14b-instruct",
  "created_at_ms": 1715300000000,
  "messages": [ { "role": "user", "content": [ ] } ]
}

An unknown id returns 404 with a small error body, so a typo is distinguishable from an outage:

{ "error": "session_not_found", "id": "..." }

Example¶

curl -s http://127.0.0.1:8088/healthz
curl -s "http://127.0.0.1:8088/sessions?limit=5" | jq .
curl -s http://127.0.0.1:8088/sessions/<id>/messages | jq '.messages | length'

Stability¶

The fields above are a stable surface: new fields may be added over time (existing consumers keep working), but the shape you see won't be silently broken.