beadboard/docs/api-reference.md

BeadBoard API Reference

Overview

BeadBoard exposes REST endpoints for reading bead data, managing agent coordination, and streaming real-time activity. All endpoints return JSON (unless noted otherwise).

Bead Management

GET /api/beads/read

Read beads from the current or specified project.

Query Parameters:

• project (optional): Project key for scope resolution
• mode (optional): single or aggregate

Response:

{
  "issues": [...],
  "projectRoot": "/path/to/project"
}

POST /api/beads/create

Create a new bead.

Body:

{
  "title": "Task title",
  "description": "Optional description",
  "status": "open",
  "priority": "p2",
  "issue_type": "task"
}

POST /api/beads/update

Update an existing bead.

Body:

{
  "id": "bb-abc",
  "updates": {
    "status": "in_progress",
    "assignee": "agent-1"
  }
}

POST /api/beads/close

Close a bead.

Body:

{
  "id": "bb-abc",
  "reason": "Completion reason"
}

POST /api/beads/reopen

Reopen a closed bead.

Body:

{
  "id": "bb-abc"
}

POST /api/beads/comment

Add a comment to a bead.

Body:

{
  "id": "bb-abc",
  "comment": "Comment text",
  "author": "agent-1"
}

Agent Coordination

GET /api/agents/[agentId]/stats

Fetch productivity metrics for a specific agent.

Path Parameters:

• agentId: Agent identifier

Response:

{
  "activeTasks": 3,
  "completedTasks": 12,
  "handoffsSent": 8,
  "recentWins": [
    { "id": "bb-xyz", "title": "Task title" }
  ]
}

GET /api/sessions

Fetch the agent sessions task feed.

Query Parameters:

• project (optional): Project scope
• mode (optional): single or aggregate

Response:

{
  "buckets": [
    {
      "epic": {
        "id": "bb-epic",
        "title": "Epic Title",
        "status": "open"
      },
      "tasks": [
        {
          "id": "bb-task",
          "title": "Task Title",
          "epicId": "bb-epic",
          "status": "in_progress",
          "sessionState": "active",
          "owner": "agent-1",
          "lastActor": "agent-1",
          "lastActivityAt": "2026-02-16T05:00:00Z",
          "communication": {
            "unreadCount": 2,
            "pendingRequired": true,
            "latestSnippet": "Blocked on API"
          }
        }
      ]
    }
  ]
}

GET /api/sessions/[beadId]/conversation

Get the full conversation thread for a bead, including comments and agent messages.

Path Parameters:

• beadId: Bead identifier

Response:

{
  "comments": [...],
  "messages": [...]
}

POST /api/sessions/[beadId]/comment

Add a comment to a bead session.

Path Parameters:

• beadId: Bead identifier

Body:

{
  "comment": "Comment text",
  "author": "agent-1"
}

POST /api/sessions/[beadId]/messages/[messageId]/read

Mark an agent message as read.

Path Parameters:

• beadId: Bead identifier
• messageId: Message identifier

POST /api/sessions/[beadId]/messages/[messageId]/ack

Acknowledge an agent message (required for HANDOFF/BLOCKED categories).

Path Parameters:

• beadId: Bead identifier
• messageId: Message identifier

Activity & Events

GET /api/activity

Fetch recent activity events (history buffer).

Response:

{
  "events": [
    {
      "id": "evt-123",
      "beadId": "bb-abc",
      "kind": "status_changed",
      "actor": "agent-1",
      "timestamp": "2026-02-16T05:00:00Z",
      "changes": {
        "from": "todo",
        "to": "in_progress"
      }
    }
  ]
}

GET /api/events

Server-Sent Events stream for real-time activity.

Response: SSE stream with event and data fields.

Event Types:

• activity: New activity event
• bead_updated: Bead state changed
• agent_registered: New agent registered

Project Management

GET /api/projects

List all registered projects.

Response:

{
  "projects": [
    {
      "key": "proj-1",
      "root": "/path/to/project",
      "name": "Project Name"
    }
  ]
}

POST /api/scan

Scan filesystem for bead-enabled projects.

Body:

{
  "paths": ["/path/to/scan"]
}

Response:

{
  "discovered": [
    {
      "root": "/path/to/project",
      "beadCount": 42
    }
  ]
}

Error Handling

All endpoints follow a consistent error format:

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

Common Error Codes:

• INVALID_REQUEST: Malformed request body or parameters
• NOT_FOUND: Resource does not exist
• PERMISSION_DENIED: Operation not allowed
• INTERNAL_ERROR: Server-side error

Rate Limiting

No rate limiting is currently enforced for local BeadBoard instances. If deploying publicly, implement rate limiting externally.

Authentication

BeadBoard runs as a local dashboard with no authentication. If exposing over a network, secure access using reverse proxy authentication or network isolation.