REST API Reference

All API routes are defined as Nitro file-based routes under server/api/. The base URL is http://localhost:3000/api.

Projects

List Projects

GET /api/projects

Returns all detected projects.

Create Project

POST /api/projects

Field	Type	Required	Description
name	string	yes	Project name
path	string	yes	Absolute path to project root
type	string	yes	backend, frontend, fullstack, or module
identifierPrefix	string	yes	Unique prefix for issue identifiers (e.g., SYM)

Get Project by Slug

GET /api/projects/by-slug/:slug

Get Project by ID

GET /api/projects/:projectId

Update Project

PUT /api/projects/:projectId

Accepts partial project fields to update. Includes config for project settings.

Rescan Projects

POST /api/projects/rescan

Re-runs project auto-detection to discover new projects in the workspace.

Setup Wizard

POST /api/projects/:projectId/setup-wizard

Triggers the setup wizard agent for a project.

Pipeline

GET /api/projects/:projectId/pipeline

Returns the phase pipeline state for all issues in the project.

Cost Summary

GET /api/projects/:projectId/cost-summary

Returns aggregated agent run cost data for the project.

Cost Timeline

GET /api/projects/:projectId/cost-timeline

Returns cost data over time for the project.

Research Coverage

GET /api/projects/:projectId/research/coverage

Returns research coverage metrics for the project.

Agent Prompts

GET /api/projects/:projectId/agent-prompts

Returns the resolved agent prompts (system + user) for preview.

Experiments

GET /api/projects/:projectId/experiments

Returns experiment configuration and results for the project.

Issues

List Issues

GET /api/projects/:projectId/issues

Query Param	Type	Description
status	string	Filter by status
label	string	Filter by label
limit	number	Max results (default 50, max 100)

Create Issue

POST /api/projects/:projectId/issues

Field	Type	Required	Description
title	string	yes	Issue title
description	string	no	Issue description (markdown)
priority	number	no	1=urgent, 2=high, 3=medium (default), 4=low
size	string	no	small, medium, or large
labels	string[]	no	Labels array
status	string	no	Initial status (default: backlog)

Get Issue by ID

GET /api/projects/:projectId/issues/:issueId

Get Issue by Identifier

GET /api/projects/:projectId/issues/by-identifier/:identifier

Update Issue

PUT /api/projects/:projectId/issues/:issueId

Accepts partial issue fields. Status changes are validated against the transition map.

Delete Issue

DELETE /api/projects/:projectId/issues/:issueId

Update Issue Status

PUT /api/projects/:projectId/issues/:issueId/status

Field	Type	Required	Description
status	string	yes	New status (must be a valid transition)
reason	string	no	Reason for the status change

Issue Sub-Resources

Comments

GET  /api/projects/:projectId/issues/:issueId/comments
POST /api/projects/:projectId/issues/:issueId/comments

Field	Type	Required	Description
content	string	yes	Comment text
author	string	no	user, agent, or system (default: user)

Findings

GET  /api/projects/:projectId/issues/:issueId/findings
POST /api/projects/:projectId/issues/:issueId/findings

Field	Type	Required	Description
category	string	yes	test_result, code_pattern, architecture, bug, or gap
summary	string	yes	Short summary
details	string	no	Full details
files	string[]	no	Related file paths

Learnings

GET  /api/projects/:projectId/issues/:issueId/learnings
POST /api/projects/:projectId/issues/:issueId/learnings

Field	Type	Required	Description
pattern	string	yes	Pattern description
context	string	no	When/where this applies
applies_to	string[]	no	Directory/file prefixes

Dependencies

POST   /api/projects/:projectId/issues/:issueId/dependencies
DELETE /api/projects/:projectId/issues/:issueId/dependencies

Field	Type	Required	Description
dependsOnId	string	yes	ID of the issue this depends on

Merge

POST /api/projects/:projectId/issues/:issueId/merge

Merges the issue's branch into the base branch. Used after PR approval.

Events

GET /api/projects/:projectId/issues/:issueId/events

Returns the event history for the issue (status changes, agent runs, comments).

Agent Runs

GET /api/projects/:projectId/issues/:issueId/runs/:runId

Returns details for a specific agent run, including log output, structured exitReason, and heuristic summary.

The exitReason field is a JSON object with:

• reason — discriminated union on type field (e.g., completed, timeout, phase_completed, circuit_break, process_killed)
• action — one of done, retry, circuit_break, noop

The summary field (nullable JSON string) is a heuristic post-run summary generated from agent_events:

• tools — array of { name, count } sorted by count descending
• files — deduplicated file paths extracted from tool inputs
• totalToolCalls — total number of tool invocations
• outcome — detected outcome (e.g., completed phase:research, created PR, approved PR)
• oneLiner — human-readable single-line summary
• source — always "heuristic" (future: "model" for LLM-generated summaries)

Pull Requests

Get PR

GET /api/projects/:projectId/issues/:issueId/pr

Returns the latest PR for the issue, including diff snapshot, file stats, gate results, and risk score.

Get PR Diff

GET /api/projects/:projectId/issues/:issueId/pr/diff

Returns just the diff content.

Reject PR

POST /api/projects/:projectId/issues/:issueId/pr/reject

Field	Type	Required	Description
reason	string	no	Rejection reason
fix_instructions	string	no	Instructions for the worker

Agent Profiles

List Profiles

GET /api/projects/:projectId/agent-profiles

Create Profile

POST /api/projects/:projectId/agent-profiles

Field	Type	Required	Description
name	string	yes	Profile name
type	string	yes	planner, worker, judge, researcher, or custom
systemPrompt	string	no	Custom instructions (appended to default)
model	string	no	Model override

Update Profile

PUT /api/projects/:projectId/agent-profiles/:profileId

Delete Profile

DELETE /api/projects/:projectId/agent-profiles/:profileId

Labels

List Labels

GET /api/projects/:projectId/labels

Create Label

POST /api/projects/:projectId/labels

Update Label

PUT /api/projects/:projectId/labels/:labelId

Delete Label

DELETE /api/projects/:projectId/labels/:labelId

Seed Default Labels

POST /api/projects/:projectId/labels/seed

Seeds the project with the default label set.

Intake

Submit Intake Batch

POST /api/projects/:projectId/intake

Submits a batch of issues for AI-assisted intake processing (parsing, deduplication, prioritization).

Get Intake Batch

GET /api/projects/:projectId/intake/:batchId

Returns the status and results of an intake batch.

Learnings (Project-Level)

List Project Learnings

GET /api/projects/:projectId/learnings

Returns all learnings across all issues in the project.

Update Learning

PUT /api/projects/:projectId/learnings/:learningId

Delete Learning

DELETE /api/projects/:projectId/learnings/:learningId

Search Learnings

GET /api/projects/:projectId/learnings/search?query=<text>

Searches learnings across all issues in the project by full-text match.

Workspace

Workspace Summary

GET /api/workspace/summary

Returns a high-level summary across all projects (issue counts, active agents, etc.).

Workspace Issues

GET /api/workspace/issues

Returns issues across all projects, with optional filtering.

Workspace Dependencies

GET /api/workspace/dependencies

Returns cross-project issue dependency graph.

Workspace Cost Summary

GET /api/workspace/cost-summary

Returns aggregated cost data across all projects.

Workspace Analytics

GET /api/workspace/analytics

Returns throughput, cycle time, and other analytics across all projects.

Issues (Global Search)

Search Issues

GET /api/issues/search?query=<text>

Full-text search across issues in all projects.

Notifications

List Notifications

GET /api/notifications

Returns unread notifications for the current session.

Mark Notification Read

PUT /api/notifications/:id/read

Mark All Read

PUT /api/notifications/read-all

Delete Read Notifications

DELETE /api/notifications/read

Orchestrator

Get Status

GET /api/orchestrator/status

Returns running agents, retry queue, and concurrency info.

Liveness Probe (Health)

GET /api/orchestrator/health

Public endpoint (no authentication required). Returns orchestrator health classification with appropriate HTTP status codes for monitoring and Kubernetes liveness probes.

HTTP Status Codes:

• 200 — healthy or degraded (orchestrator is alive)
• 503 — unhealthy (tick loop stalled or DB unreachable)

Status Classification (based on tick loop staleness relative to poll_interval_ms):

• healthy: last tick < 2x poll_interval (default: < 10s)
• degraded: last tick < 5x poll_interval (default: < 25s)
• unhealthy: last tick >= 5x poll_interval or DB unreachable

Response fields:

Field	Type	Description
available	boolean	Whether metrics are available (backward compatible)
stale	boolean	Whether orchestrator is not healthy (backward compatible)
status	string	healthy, degraded, or unhealthy
reason	string	Human-readable explanation
staleSinceSeconds	number	Seconds since last metrics update
metrics	object/null	Full health metrics snapshot

Example (healthy, 200):

{
  "available": true,
  "stale": false,
  "status": "healthy",
  "reason": "Orchestrator operating normally",
  "staleSinceSeconds": 2,
  "metrics": { "generatedAt": "...", "uptimeSeconds": 300, "pid": 1234, "..." : "..." }
}

Example (unhealthy, 503):

{
  "available": true,
  "stale": true,
  "status": "unhealthy",
  "reason": "Orchestrator tick loop stalled for 30s (threshold: 25s)",
  "staleSinceSeconds": 30,
  "metrics": { "..." : "..." }
}

Readiness Probe

GET /api/orchestrator/ready

Public endpoint (no authentication required). Kubernetes-style readiness probe. Returns 200 only when the orchestrator is fully initialized and operating normally.

Readiness Checks:

1. tickLoopHealthy — Tick loop is not stalled (status is not unhealthy)
2. dbInitialized — Database file exists and has data (size > 0)
3. contractsLoaded — All phase contracts loaded successfully

HTTP Status Codes:

• 200 — ready (all checks pass)
• 503 — not ready (one or more checks failed)

Response fields:

Field	Type	Description
ready	boolean	Whether all readiness checks pass
status	string	Health classification (healthy/degraded/unhealthy)
checks	object	Individual check results
details	object	Human-readable reasons per check

Example (ready, 200):

{
  "ready": true,
  "status": "healthy",
  "checks": { "tickLoopHealthy": true, "dbInitialized": true, "contractsLoaded": true },
  "details": { "tickLoopReason": "OK", "dbReason": "OK", "contractReason": "OK" }
}

Example (not ready, 503):

{
  "ready": false,
  "status": "unhealthy",
  "checks": { "tickLoopHealthy": false, "dbInitialized": true, "contractsLoaded": true },
  "details": { "tickLoopReason": "Orchestrator tick loop stalled for 30s (threshold: 25s)", "dbReason": "OK", "contractReason": "OK" }
}

Use Cases:

• Kubernetes: Readiness probe waits for /ready to return 200 before routing traffic
• CI/CD: Poll /ready before running integration tests
• Monitoring: Distinguish between "starting up" (not ready) and "stuck" (unhealthy)

Refresh

POST /api/orchestrator/refresh

Triggers an immediate orchestrator tick.

Checkpoint

POST /api/orchestrator/checkpoint

Forces the orchestrator to checkpoint its current state.

Prompt Stats

GET /api/orchestrator/prompt-stats

Returns token usage statistics for recent agent prompts.

Stream Logs

GET /api/orchestrator/logs/stream

Server-Sent Events (SSE) stream of live agent log output. Connect with EventSource.

Status Transitions

Valid status transitions enforced by the API:

From	Allowed Destinations
backlog	todo
todo	backlog, cancelled
in_progress	review, todo, blocked
blocked	todo
review	done, todo
done	todo
cancelled	backlog, todo

The orchestrator also performs: todo -> in_progress (dispatch) and in_progress -> todo (failure/retry).