API

The API is local-first and binds to 127.0.0.1 by default because it controls real terminal processes.

Endpoints

GET  /health
POST /v1/runs
GET  /v1/runs
GET  /v1/runs/:id
GET  /v1/runs/:id/events
GET  /v1/runs/:id/summary
GET  /v1/runs/:id/summary.json
GET  /v1/runs/:id/diff
GET  /v1/runs/:id/progress
GET  /v1/runs/:id/progress/:artifact
POST /v1/runs/:id/cancel
POST /v1/sessions
GET  /v1/sessions
GET  /v1/sessions/:id
POST /v1/sessions/:id/input
POST /v1/sessions/:id/resize
POST /v1/sessions/:id/cancel
GET  /v1/sessions/:id/transcript
GET  /v1/sessions/:id/events

Run a reviewed plan

Use the run API when RalphTerm owns the plan loop. The daemon creates a run record, starts the markdown plan in the background, stores lifecycle events, and writes result artifacts under .ralphterm/runs/<id>/ when the run finishes.

POST /v1/runs
content-type: application/json

{
  "plan_path": "docs/plans/example.md",
  "agent_command": "claude",
  "review_command": "codex exec review-task",
  "require_review": true,
  "max_review_retries": 1,
  "no_commit": false
}

review_command starts an independent reviewer after validation. require_review rejects the request if that reviewer is missing. workspace_id runs the plan in a managed worktree; with dry_run, the run record previews workspace_path without creating the worktree or running the agent.

POST /v1/runs returns as soon as the run has started:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "created_at": "unix-ms:1778954400000",
  "phase": "executing",
  "status": "running",
  "plan_path": "docs/plans/example.md"
}

Poll GET /v1/runs/:id for succeeded or failed, or read GET /v1/runs/:id/events for lifecycle events. If agent_command is omitted, the daemon only creates the record and returns phase: "planning", status: "created".

Run phase values are planning, executing, validating, reviewing, and complete: planning means the run record exists without active agent work, executing means the implementation command or agent is active, validating means plan validation commands are active, reviewing means the independent review command or agent is active, and complete means the run has reached a terminal status.

GET /v1/runs returns newest runs first so dashboards and watchdogs see active work before older records.

GET  /v1/runs
GET  /v1/runs/:id
GET  /v1/runs/:id/summary
GET  /v1/runs/:id/summary.json
GET  /v1/runs/:id/diff
GET  /v1/runs/:id/progress
GET  /v1/runs/:id/progress/:artifact
GET  /v1/runs/:id/events
POST /v1/runs/:id/cancel

GET /v1/runs/:id/events returns events such as run_created, run_succeeded, run_failed, and run_cancelled. Plan-runner executions write summary.md and diff.patch; agent-backed runs also preserve the runner-generated summary.json when the runner produced one. GET /v1/runs/:id/summary returns summary.md as plain text; GET /v1/runs/:id/summary.json returns the machine-readable task result summary when present. Each task includes accepted and acceptance_gates, so callers can see agent, validation, review, and commit gate status without inferring acceptance from transcript paths. GET /v1/runs/:id/diff returns diff.patch as plain text. GET /v1/runs/:id/progress returns a JSON index of copied progress artifacts with name, kind, and url fields for transcripts, validation output, review transcripts, and the progress log. Follow an artifact url, or call GET /v1/runs/:id/progress/:artifact, to fetch the copied transcript, validation output, review transcript, or progress log directly. Runs that exist but do not have an artifact yet return 404 with an artifact-specific message.

Create a raw session

POST /v1/sessions
content-type: application/json

{
  "agent": "claude",
  "prompt": "Implement this task and end with COMPLETED",
  "cols": 120,
  "rows": 40
}

Session records

GET /v1/sessions and GET /v1/sessions/:id return session records with approval_pending. It is true while the session has pending approval and is waiting for an explicit approval response; otherwise it is false.

{
  "id": "00000000-0000-0000-0000-000000000000",
  "agent": "claude",
  "status": "running",
  "signal": null,
  "approval_pending": false,
  "exit_code": null
}

Send input

POST /v1/sessions/:id/input

{
  "text": "continue\n"
}

Signals

The current detector recognizes COMPLETED, FAILED, QUESTION, PLAN_READY, REVIEW_DONE, and ALL_TASKS_DONE.

Events stream

The WebSocket stream emits PTY output chunks, signals, lifecycle transitions, and exit status.