DevPilot API Reference

March 11, 2026 · View on GitHub

The DevPilot CLI server exposes a RESTful API on port 3847 (default).

Base URL

http://localhost:3847/api

Authentication

Local development requires no authentication. For production deployments, configure API keys in the bridge service.

Horizon Items

Manage work items in the kanban board.

List Items

GET /api/items

Query parameters:

zone - Filter by zone: SHAPING, READY, LANDED
repo - Filter by repository

Response:

{
  "items": [
    {
      "id": "item_xxxxx",
      "title": "Implement feature X",
      "description": "Description here",
      "repo": "my-org/my-repo",
      "zone": "READY",
      "complexity": "M",
      "linearTicketId": "LIN-123",
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-01-15T12:00:00Z",
      "plan": { ... }
    }
  ]
}

Create Item

POST /api/items
Content-Type: application/json

{
  "title": "Implement feature X",
  "description": "Description here",
  "repo": "my-org/my-repo",
  "zone": "SHAPING",
  "complexity": "M",
  "linearTicketId": "LIN-123"
}

Response:

{
  "item": { ... },
  "message": "Item created successfully"
}

Get Item

GET /api/items/{itemId}

Response includes the item with its plan, workstreams, and tasks.

Update Item

PUT /api/items/{itemId}
Content-Type: application/json

{
  "title": "Updated title",
  "zone": "READY"
}

Delete Item

DELETE /api/items/{itemId}

Move Item Zone

POST /api/items/{itemId}/move
Content-Type: application/json

{
  "zone": "READY"
}

Plans

Manage implementation plans attached to horizon items.

Create/Update Plan

PUT /api/items/{itemId}/plan
Content-Type: application/json

{
  "goal": "Implement feature X with full test coverage",
  "acceptanceCriteria": [
    "All tests pass",
    "Code reviewed",
    "Documentation updated"
  ],
  "workstreams": [
    {
      "label": "Backend Implementation",
      "orderIndex": 0,
      "tasks": [
        { "label": "Create API endpoint", "orderIndex": 0 },
        { "label": "Add validation", "orderIndex": 1 }
      ]
    },
    {
      "label": "Testing",
      "orderIndex": 1,
      "tasks": [
        { "label": "Write unit tests", "orderIndex": 0 },
        { "label": "Add integration tests", "orderIndex": 1 }
      ]
    }
  ],
  "filesTouched": [
    { "path": "src/api/routes.ts", "reason": "Add new endpoint" },
    { "path": "tests/api.test.ts", "reason": "Add tests" }
  ]
}

Get Plan

GET /api/items/{itemId}/plan

Fleet

Manage active AI agent sessions.

Get Fleet State

GET /api/fleet/state

Response:

{
  "sessions": [
    {
      "id": "sess_xxxxx",
      "repo": "my-org/my-repo",
      "linearTicketId": "LIN-123",
      "ticketTitle": "Implement feature X",
      "currentWorkstream": "Backend Implementation",
      "status": "ACTIVE",
      "progressPercent": 45,
      "elapsedMinutes": 12,
      "estimatedRemainingMinutes": 15,
      "inFlightFiles": ["src/api.ts"],
      "completedTasks": [],
      "createdAt": "2024-01-15T10:00:00Z"
    }
  ],
  "inFlightFiles": [
    {
      "path": "src/api.ts",
      "activeSessionId": "sess_xxxxx",
      "linearTicketId": "LIN-123",
      "estimatedMinutesRemaining": 15
    }
  ]
}

Dispatch Item to Fleet

POST /api/fleet/dispatch/{itemId}

Dispatches a READY horizon item to the agent orchestrator.

Response:

{
  "session": {
    "id": "sess_xxxxx",
    "status": "ACTIVE",
    ...
  },
  "message": "Successfully dispatched \"Implement feature X\" to fleet"
}

Get Session Details

GET /api/fleet/sessions/{sessionId}

Orchestrator Callbacks

These endpoints receive status updates from the orchestrator.

Status Update

POST /api/orchestrator/status
Content-Type: application/json

{
  "sessionId": "sess_xxxxx",
  "status": "running",
  "progressPercent": 50,
  "currentStep": "Writing tests",
  "currentFile": "tests/api.test.ts",
  "filesModified": ["src/api.ts"],
  "tokensUsed": 15000,
  "message": "Implementing test cases"
}

Completion Report

POST /api/orchestrator/complete
Content-Type: application/json

{
  "sessionId": "sess_xxxxx",
  "success": true,
  "prUrl": "https://github.com/org/repo/pull/123",
  "filesModified": ["src/api.ts", "tests/api.test.ts"],
  "tokensUsed": 45000,
  "costUsd": 0.15,
  "durationMinutes": 25,
  "summary": "Implemented feature with full test coverage"
}

Conductor Score

System health metrics.

Get Score

GET /api/score

Response:

{
  "score": {
    "id": "score_xxxxx",
    "total": 850,
    "velocityTrend": 125,
    "costEfficiency": 110,
    "qualityGate": 95,
    "lastUpdated": "2024-01-15T12:00:00Z"
  },
  "history": [
    {
      "timestamp": "2024-01-15T11:00:00Z",
      "total": 840,
      "delta": 10,
      "reason": "dispatch"
    }
  ]
}

Update Score

POST /api/score
Content-Type: application/json

{
  "delta": 10,
  "reason": "manual_adjustment"
}

Activity Events

Event log for all system activity.

List Events

GET /api/events

Query parameters:

limit - Number of events (default: 50)
type - Filter by event type
repo - Filter by repository

Response:

{
  "events": [
    {
      "id": "evt_xxxxx",
      "type": "ITEM_DISPATCHED",
      "message": "Dispatched \"Implement feature X\" to fleet",
      "repo": "my-org/my-repo",
      "ticketId": "LIN-123",
      "metadata": {
        "sessionId": "sess_xxxxx",
        "estimatedMinutes": 30
      },
      "timestamp": "2024-01-15T10:00:00Z"
    }
  ]
}

Event Types

Type	Description
`ITEM_CREATED`	New horizon item created
`ITEM_MOVED`	Item moved between zones
`ITEM_DISPATCHED`	Item dispatched to fleet
`SESSION_STARTED`	Agent session started
`SESSION_PROGRESS`	Session progress update
`SESSION_COMPLETE`	Session completed
`FILE_LOCKED`	File locked by session
`FILE_UNLOCKED`	File released
`SCORE_UPDATE`	Conductor score changed
`LINEAR_SYNC`	Linear sync event

Server-Sent Events (SSE)

Real-time updates via SSE stream.

Connect to Stream

GET /api/events/stream
Accept: text/event-stream

Events:

event: session_update
data: {"sessionId":"sess_xxx","status":"ACTIVE","progressPercent":50}

event: score_update
data: {"total":860,"delta":10}

event: activity
data: {"type":"SESSION_PROGRESS","message":"..."}

Linear Integration

Check Configuration

GET /api/integrations/linear/connect

Response:

{
  "configured": true,
  "team": {
    "id": "team_xxxxx",
    "name": "My Team",
    "key": "TEAM"
  }
}

Configure Linear

POST /api/integrations/linear/connect
Content-Type: application/json

{
  "apiKey": "lin_api_xxxxx",
  "teamId": "team_xxxxx"
}

Linear Webhook

POST /api/integrations/linear/webhook
Content-Type: application/json
Linear-Signature: sha256=xxxxx

{
  "type": "Issue",
  "action": "update",
  "data": { ... }
}

Health Check

GET /api/health

Response:

{
  "status": "ok",
  "version": "0.1.0",
  "uptime": 3600,
  "database": "connected",
  "orchestrator": {
    "mode": "ao-cli",
    "status": "ready"
  }
}

Error Responses

All endpoints return errors in this format:

{
  "error": "Error message here",
  "code": "ERROR_CODE",
  "details": { ... }
}

HTTP Status Codes:

200 - Success
201 - Created
400 - Bad Request (validation error)
404 - Not Found
500 - Internal Server Error

TypeScript Types

Import types from @devpilot.sh/core:

import type {
  HorizonItem,
  NewHorizonItem,
  Plan,
  NewPlan,
  RufloSession,
  ConductorScore,
  ActivityEvent,
  Zone,
  Complexity,
  SessionStatus,
} from '@devpilot.sh/core/db';

import type {
  DispatchRequest,
  DispatchResponse,
  StatusUpdate,
  CompletionReport,
} from '@devpilot.sh/core/orchestrator';