Skip to content

api-reference.md

Latest commit

 

History

History
118 lines (94 loc) · 4.58 KB

api-reference.md

File metadata and controls

118 lines (94 loc) · 4.58 KB
Raw

API Reference

Base URL: http://localhost:28326 Authentication: X-Auth-Token header or ?token= query param Key files: src/server/routes/

REST Endpoints

Authentication

Method Path Description
GET /api/health Health check (no auth required)
POST /api/auth/verify Verify token

Conversations

Method Path Description
GET /api/conversations List (returns { active[], archived[] })
POST /api/conversations Create new conversation
GET /api/conversations/:id Get conversation detail (includes task info)
PATCH /api/conversations/:id Rename { name }
POST /api/conversations/:id/archive Archive

Messages & Chat

Method Path Description
GET /api/conversations/:id/messages?limit=50 Message history
POST /api/conversations/:id/messages Send message { content }
POST /api/conversations/:id/chat Core endpoint — send message + trigger Dispatcher

Chat endpoint flow:

POST /chat { messages: [{ role, content }] }
  -> Store user message
  -> Call Dispatcher -> parse action
  -> resolveAndExecute(action, params)
  -> Store assistant response
  -> SSE notify frontend

Actions (Direct Operations)

Method Path Description
POST /api/conversations/:id/actions Execute action { action, params }

Available actions:

Action Params Description
dispatch { title, description, workspace, repos, mode, ... } Create a new task (Zod-validated)
update { task_id, field, value } Update a PENDING_CONFIRMATION task
plan { task_id, instruction? } Start plan creation
argue { task_id, max_rounds? } Start adversarial plan review
implement { task_id } Start implementation
review { task_id, max_rounds? } Start code review
plan:continue / plan:force_complete / plan:manual_edit { task_id, rounds? } Post-argue-exhausted user decisions
review:continue / review:force_complete / review:manual_edit { task_id, rounds? } Post-review-exhausted user decisions
pr { task_id } Push branches + create pull request(s) (GitHub/Bitbucket)
merge { task_id, strategy? } Finalize with strategy: local | pr | both | "local only". Omit for a prompt.
push { task_id } After merge local: push base branch to origin
complete { task_id } After merge local: finalize without pushing (MERGING → MERGED)
stop { task_id } Kill process tree + transition to ABANDONED
pause / resume { task_id } Task state transitions
respond { task_id, answer } Reply to a BLOCKED task's escalation
diagnose / status { task_id } Inspect task health, process, worktrees, sessions
health {} System-wide counts (active / blocked / total)

Tasks

Method Path Description
GET /api/tasks?filter=active Task list
GET /api/tasks/:id Task detail (includes worktrees)
GET /api/tasks/:id/events?since=0&limit=50 Agent events (paginated)
GET /api/tasks/:id/plan Read plan file content (plain text/markdown)

SSE Event Streams

Conversation Stream

GET /api/conversations/:id/stream?token=xxx
Event Data Triggered When
state { status } Processing state changes
complete { messageId } Dispatcher finished, new message available
error { error } Processing error
task_update { taskId, status, phase } Task status change
heartbeat {} Keep-alive every 30s

Agent Discussion Stream

GET /api/tasks/:id/agents/stream?token=xxx
Event Data Triggered When
agent:thinking { agentRole } Agent starts thinking
agent:text_delta { delta, agentRole } Streaming text increment
agent:text_done { content, agentRole } Complete output
phase:transition { phase } Phase change
round:start { round, phase } Adversarial round begins
round:end { round, verdict } Round ends (approved/needs_revision)
agent:handoff { from, to } Role handoff

Response Conventions

  • Success: 200 + JSON body
  • Async operation: 202 + { status: "accepted" }
  • Unauthenticated: 401 (frontend auto-clears token and refreshes)
  • Error: 4xx/5xx + { error: "message" }