Agents API

Agent Tasks

List Agent Tasks

GET /api/agent-tasks?project_id={id}&stage={stage}

Returns agent tasks with pipeline metadata. Filterable by project and stage (comma-separated).

Get Agent Task Detail

GET /api/agent-tasks/{taskId}

Returns task + agent meta + recent run history.

Update Agent Task Meta

PATCH /api/agent-tasks/{taskId}
Content-Type: application/json

{ "effort_estimate": "M", "scope_document": "..." }

Allowed fields: effort_estimate, scope_document, claude_confidence_note.

Dispatch to Scoping

POST /api/agent-tasks/{taskId}/dispatch

Moves task from draft or rejected to scoping. Creates a run record.

Approve Scope

POST /api/agent-tasks/{taskId}/approve

Moves task from pending_approval to building. Creates a build run record.

Reject Scope

POST /api/agent-tasks/{taskId}/reject
Content-Type: application/json

{ "reason": "Scope too broad" }

Moves task from pending_approval to rejected.

Approve Review

POST /api/agent-tasks/{taskId}/review-approve
Content-Type: application/json

{ "force": false }

Moves task from review to done. Checks proof-of-work gates (playwright_status, ci_status). Send force: true to override.

Reject Review

POST /api/agent-tasks/{taskId}/review-reject
Content-Type: application/json

{ "reason": "Button alignment is off" }

Moves task from review back to building with incremented retry count.

Get Stats

GET /api/agent-tasks/stats?project_id={id}

Returns aggregate stats (total tasks, runs, tokens, cost) and pipeline stage counts.

Project Agent Configuration

Get Config

GET /api/projects/{projectId}/agent-config

Returns the agent configuration for a project, or { config: null } if not configured.

Upsert Config

PUT /api/projects/{projectId}/agent-config
Content-Type: application/json

{
  "project_type": "shopify_theme",
  "github_org": "dotcollectiveanz",
  "github_repo": "client-theme",
  "default_branch": "main",
  "deploy_target": "shopify",
  "preview_url_pattern": "https://{branch}.preview.store.com",
  "production_url": "https://store.com",
  "workflow_config": { "shopifyStore": "store.myshopify.com", "themeId": "123" },
  "runner_url": "https://nucleus-dev-runner.workers.dev",
  "enabled": true
}

Runner Callback (Webhook)

POST /api/webhooks/agent-callback
Authorization: Bearer {runner_secret}
Content-Type: application/json

{
  "task_id": "abc123",
  "project_id": "proj456",
  "stage": "scoping",
  "status": "success",
  "run_id": "run789",
  "result": {
    "scope_document": "## Summary\n...",
    "effort_estimate": "M",
    "branch_name": "agent/task-abc123",
    "pr_url": "https://github.com/org/repo/pull/42",
    "preview_url": "https://store.com?preview_theme_id=123",
    "playwright_status": "pass",
    "playwright_video_url": "https://r2.example.com/video.webm",
    "ci_status": "success"
  }
}

Uses Bearer token authentication (not session auth). The token must match the project’s runner_secret in agent_project_config.

Orchestrator Proxy

All orchestrator endpoints are proxied through the main app:

Method	Path	Proxied To
GET	/api/orchestrator/status	Orchestrator /status
POST	/api/orchestrator/pause	Orchestrator /pause
POST	/api/orchestrator/resume	Orchestrator /resume
POST	/api/orchestrator/restart	Orchestrator /restart
GET	/api/orchestrator/tasks	Orchestrator /tasks
POST	/api/orchestrator/tasks	Orchestrator /tasks

Business Agent Proxy

Method	Path	Purpose
GET	/api/business-agents	List all registered agents
GET	/api/business-agents/{id}/status	Agent health check
POST	/api/business-agents/{id}/command	Send command to agent
GET	/api/business-agents/{id}/logs	Execution history
POST	/api/business-agents/{id}/trigger/{name}	Manual trigger