API reference · Coldcache

The API mirrors the app exactly — the app is a client of these routes. Everything is JSON except run streaming, which is server-sent events.

Agents and versions

GET    /api/agents                     list agents with their stable pointer
POST   /api/agents                     { name, description, body } → creates agent + draft
GET    /api/agents/:id                 agent with full version history
PUT    /api/agents/:id/draft           save the draft body
POST   /api/agents/:id/publish         { changelog, advanceStable } → next version
POST   /api/agents/:id/stable          { versionId } → move the stable pointer
POST   /api/versions/:id/deprecate     toggle deprecation

Chats and runs

POST   /api/chats                      { agentId, versionId? } → pins at creation
GET    /api/chats/:id                  chat with its pinned version and runs
POST   /api/chats/:id/runs             { content, sourceMode } → SSE stream
POST   /api/runs/:id/rerun             { versionId, sourceMode } → forks a pinned chat

Streaming

A run streams server-sent events. Every event is a JSON object on a named event type.

Event	Payload
meta	runId, seq, provider, model, sourceMode — sent first, before any tokens
status	text — e.g. searching the web, or a note that temperature was dropped
tool	tool, args — one per tool invocation
citation	n, url, title, snippet, fetchedAt
text	text — an output delta
done	latencyMs, tokens, costUsd, outputHash, resolvedModelId, modelSubstituted, schemaValid
error	message — the run is marked failed and the error is persisted

Comparisons

POST   /api/comparisons                { runAId, runBId } → comparison record
PATCH  /api/comparisons/:id            { verdict, note }
GET    /api/models?provider=anthropic  live model list from that provider's key

Omitting version on chat creation resolves the stable pointer once and writes the resolved id. It never re-resolves — that is the difference between a pin and a default.