Skip to main content

REST Endpoints

The REST API is read-oriented and mirrors the MCP tool surface for use in dashboards and integrations. Write operations go through MCP tools.

Base URL: http://localhost:3000/api/v1

Auth: Authorization: Bearer <token> on all endpoints (when MCP_AUTH_TOKEN is set).

Health​

GET /api/v1/health​

Database connectivity check.

Response

{
  "status": "ok",
  "db": "connected",
  "timestamp": "2026-04-04T12:00:00.000Z"
}

Projects​

GET /api/v1/projects​

List all project keys visible to the caller.

Response

{
  "projects": [
    { "project_key": "myproject", "created_at": "2026-01-01T00:00:00.000Z" },
    { "project_key": "ikeo-ops",  "created_at": "2026-02-15T09:30:00.000Z" }
  ]
}

Facts​

GET /api/v1/projects/:key/facts​

List facts for a project.

Query Parameters

ParameterTypeDescription
categorystringFilter to a single category
limitnumberMaximum results (default: 50, max: 200)

Response

{
  "facts": [
    {
      "id": "uuid",
      "project_key": "myproject",
      "category": "infra",
      "key": "deploy.target",
      "value_json": { "provider": "oci", "region": "us-ashburn-1" },
      "confidence": 1.0,
      "tags": ["deploy", "production"],
      "created_at": "2026-04-01T10:00:00.000Z",
      "updated_at": "2026-04-04T08:00:00.000Z"
    }
  ]
}

GET /api/v1/projects/:key/facts/:category.:factKey​

Get a single fact by category.key (dot-separated).

Example: GET /api/v1/projects/myproject/facts/infra.deploy.target

Response

{
  "fact": {
    "id": "uuid",
    "project_key": "myproject",
    "category": "infra",
    "key": "deploy.target",
    "value_json": { "provider": "oci", "region": "us-ashburn-1" },
    "confidence": 1.0,
    "tags": ["deploy"],
    "created_at": "2026-04-01T10:00:00.000Z",
    "updated_at": "2026-04-04T08:00:00.000Z"
  }
}

Returns 404 if not found or soft-deleted.

Tasks​

GET /api/v1/projects/:key/tasks​

List tasks for a project.

Query Parameters

ParameterTypeDescription
statestringFilter by status: backlog, todo, in_progress, in_review, completed, failed, cancelled, blocked, skipped
assigneestringFilter by assigned agent UUID
limitnumberMaximum results (default: 20, max: 1000)

Response

{
  "tasks": [
    {
      "task_id": "uuid",
      "project_key": "myproject",
      "title": "Implement rate limiting",
      "status": "in_progress",
      "priority": "high",
      "assigned_to": "agent-uuid",
      "parent_id": null,
      "created_at": "2026-04-02T09:00:00.000Z",
      "updated_at": "2026-04-04T11:00:00.000Z"
    }
  ]
}

GET /api/v1/projects/:key/tasks/:id​

Get a single task by UUID.

Response

{
  "task": {
    "task_id": "uuid",
    "project_key": "myproject",
    "title": "Implement rate limiting",
    "detail": "Full markdown description...",
    "status": "in_progress",
    "priority": "high",
    "assigned_to": "agent-uuid",
    "parent_id": null,
    "depends_on": [],
    "meta_json": {},
    "created_at": "2026-04-02T09:00:00.000Z",
    "updated_at": "2026-04-04T11:00:00.000Z"
  }
}

Returns 404 if not found.

Runs​

GET /api/v1/projects/:key/runs​

List recent runs for a project.

Query Parameters

ParameterTypeDescription
limitnumberMaximum results (default: 20, max: 200)

Response

{
  "runs": [
    {
      "run_id": "uuid",
      "project_key": "myproject",
      "agent_id": "agent-uuid",
      "task_id": "task-uuid",
      "status": "completed",
      "summary": "Deployed rate limiter to staging",
      "input_tokens": 12400,
      "output_tokens": 3200,
      "cost_usd": 0.042,
      "started_at": "2026-04-04T10:00:00.000Z",
      "ended_at": "2026-04-04T10:07:30.000Z"
    }
  ]
}