Goals API

Goal CRUD with workflow integration. Goals are persistent objectives that drive multi-step agent workflows.

Overview

Goals represent long-running, multi-step tasks managed by the workflow engine. Each goal spawns a coordinator process that decomposes the goal into steps, dispatches sub-agents, and tracks completion. Goals are persisted in Mnesia with ETS secondary indexes for O(1) workflow lookups.

Authentication

Requires Authorization: Bearer <token>. Goals are scoped to the authenticated user — non-admin users can only access their own goals.

Endpoints

Create Goal

POST /api/v1/goals

Request Body:

{
  "description": "Research quantum computing advances in 2026",
  "model": "claude-sonnet-4-20250514",
  "mode": "plan",
  "max_steps": 10,
  "tags": ["research", "quantum"]
}

Response:

{
  "ok": true,
  "data": {
    "id": "goal-abc123",
    "description": "Research quantum computing advances in 2026",
    "status": "active",
    "workflow_id": "wf-def456",
    "steps_completed": 0,
    "total_steps": 3,
    "created_at": 1745600000
  }
}

List Goals

GET /api/v1/goals

Query parameters: status (active, completed, failed, cancelled), tag, limit, offset.

Get Goal Details

GET /api/v1/goals/:id

Returns full goal state including current step, step history, and results.

Cancel Goal

DELETE /api/v1/goals/:id

Cancels a running goal. Stops the associated workflow and any in-progress sub-agents.

{
  "ok": true,
  "data": {
    "id": "goal-abc123",
    "status": "cancelled",
    "steps_completed": 2,
    "total_steps": 5
  }
}

Goal Events

GET /api/v1/goals/:id/events

Streams goal lifecycle events via SSE: goal.created, goal.step_started, goal.step_completed, goal.completed, goal.failed, goal.cancelled.

Workflow Integration:

Each goal creates a workflow with the following lifecycle:

Created → Decomposing → Step N Running → Step N Complete → ... → Completed
                               ↓
                            Failed (retry configurable)
                               ↓
                         Max retries exceeded → Failed

The goal projector (sol_goal_projector) maintains secondary indexes mapping workflow_id → goal_ids for O(1) lookup during event processing.

Error Codes:

Code	Description
400	Invalid goal parameters
401	Authentication required
403	Not the goal owner (non-admin)
404	Goal not found
409	Goal already completed or cancelled

Examples:

curl -X POST http://127.0.0.1:11434/api/v1/goals \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "Write unit tests", "model": "claude-sonnet-4-20250514"}'

curl http://127.0.0.1:11434/api/v1/goals \
  -H "Authorization: Bearer $TOKEN"

curl -X DELETE http://127.0.0.1:11434/api/v1/goals/goal-abc123 \
  -H "Authorization: Bearer $TOKEN"