HTTP and WebSocket API

gdc serve exposes session inspection, mutations, provider operations and WebSocket execution. Session endpoints have no built-in user authentication. See Security for access restrictions.

Session endpoints

Method	Path	Operation
GET	/healthz	Liveness: {"status":"ok"}
GET	/sessions	Session summaries
POST	/sessions	Create a session or fork
GET	/sessions/{id}/messages	Ordered history
POST	/sessions/{id}/messages	Append a message
PATCH	/sessions/{id}	Update model, endpoint, profile or reasoning
DELETE	/sessions/{id}	Delete the session

GET /sessions

Parameter	Effect
limit	Rows; default 20, clamped to 1–1000
cwd	Canonical project path prefix with directory-boundary matching
all=true	Ignore cwd filter
root_only=true	Hide child sessions
parent_id	Exact parent id
status	Exact lifecycle status

No cwd filter means all sessions in the server's database.

GET /sessions/{id}/messages

Parameter	Effect
limit	Last N messages
audit=true	Include compaction audit records

Returns metadata and messages in one object. Unknown ids return 404 with {"error":"session_not_found","id":"..."}.

POST /sessions

Field	Requirement	Effect
cwd	Required	Project directory
model, base_url, system	Optional	Run defaults
profile, title, reasoning	Optional	Session settings
parent_id	Optional	Parent relationship
fork_from	Optional	Source session
fork_from_up_to_count	Optional	Number of source messages to copy

curl -s http://127.0.0.1:8088/healthz
curl -s 'http://127.0.0.1:8088/sessions?limit=5' | jq .
curl -s -X POST http://127.0.0.1:8088/sessions \
  -H 'Content-Type: application/json' -d '{"cwd":"/path/to/project"}'

WebSocket execution

Path	Use
/sessions/stream	Multiplexed session updates, run commands and events used by the TUI
/sessions/{id}/run	Single-session run channel; tails a running worker

Messages carry runs, cancellation and approval decisions. Server events include streamed text, reasoning, tool activity and worker state.

Providers and profiles

Method	Path	Operation
GET	/profiles	Available profiles
GET / POST	/provider/models	Model catalog for default or specified provider
POST	/provider/reload	Reload provider defaults

Swarm endpoints

Method	Path	Operation
POST	/swarm/join	Join with an invite
WS	/swarm/ws	Signed swarm messages
POST	/swarm/blob	Upload a bounded blob
GET	/swarm/blob/{id}	Fetch a blob
GET	/.well-known/agent.json	Opt-in sanitized public description

Unconfigured swarm dependencies return 503.

Stability

Public JSON additions are optional or defaulted. Existing field removals or renames require a version change. Consumers should tolerate unknown optional fields and retain raw message content.