Toban API Reference

Base URL: https://api.toban.dev

Authentication

All /api/v1/* endpoints require a Bearer token:

Authorization: Bearer tb_wsXXX_sk_XXX

API keys are Project-scoped and automatically generated on login. Copy the CLI connection command from the Sprint page header. User session keys expire after 7 days of inactivity (sliding window). Agent keys do not expire.

Health

GET /api/health

Health check. No auth required.

Response: 200 OK

{ "status": "ok" }

Site Status

GET /api/site/status

Public site status (maintenance mode, banner). No auth required.

Response:

{
  "maintenance": false,
  "maintenance_message": "The system is currently under maintenance.",
  "banner": false,
  "banner_message": "",
  "banner_scheduled_at": ""
}

Auth

GET /api/auth/github

Redirect to GitHub OAuth authorization. No auth required.

GET /api/auth/github/callback

GitHub OAuth callback. Exchanges code for token, creates/finds workspace, sets session cookie.

GET /api/auth/github/installed

GitHub App post-installation callback. Links the GitHub App installation to the workspace.

POST /api/auth/logout

Invalidate the current session and clear the session cookie.

GET /api/auth/me

Check if the current session is valid. Returns minimal session info (no workspace data). For user profile data (GitHub login, avatar), use GET /api/v1/auth/me instead (requires workspace-scoped auth).

Config

GET /api/v1/config/constants

Public configuration constants. No workspace-specific data. Returns available roles, engines, templates, and other UI configuration.

Response:

{
  "roles": ["manager", "builder"],
  "engines": ["claude-code", "claude-api", "gemini", "codex", "custom"],
  "templates": ["implementation", "reviewer"],
  "priorities": ["p0", "p1", "p2", "p3"],
  "task_statuses": ["todo", "in_progress", "review", "done", "blocked"]
}

Workspace

GET /api/v1/workspace

Get current workspace details including name, description, connected repo, language, workflow type, and spec.

Response:

{
  "id": "ws-abc123",
  "name": "My Project",
  "description": "A web application",
  "github_org": "my-org",
  "github_repo": "my-org/my-repo",
  "agent_type": "claude-code",
  "language": "en",
  "workflow": "scrum",
  "spec": "Project specification text...",
  "created_at": "2026-01-01T00:00:00",
  "updated_at": "2026-01-02T00:00:00"
}

PUT /api/v1/workspace

Update workspace settings.

Body:

{
  "name": "string (optional)",
  "description": "string (optional)",
  "language": "en | ja (optional)",
  "workflow": "scrum | kanban | checklist (optional)",
  "github_repo": "owner/repo (optional)",
  "spec": "string (optional)",
  "terminal_emulator": "auto | terminal.app | iterm2 | ghostty | ... (optional)"
}

DELETE /api/v1/workspace

Delete workspace and all associated data.

Workspace Repositories

GET /api/v1/workspace/repositories

List registered repositories.

Response:

[
  {
    "id": "repo-abc123",
    "workspace_id": "ws-abc123",
    "repo_path": "my-org/my-app",
    "repo_name": "my-app",
    "description": "Main application",
    "access_agents": ["builder"],
    "created_at": "2026-01-01T00:00:00"
  }
]

POST /api/v1/workspace/repositories

Add a repository.

Body:

{
  "repo_path": "owner/repo",
  "repo_name": "repo-name",
  "description": "optional description",
  "access_agents": ["builder"]
}

PUT /api/v1/workspace/repositories/:id

Update a repository configuration.

DELETE /api/v1/workspace/repositories/:id

Remove a repository.

Workspace Export / Import

GET /api/v1/workspace/export

Export workspace configuration as JSON. Includes agents and task templates.

Response:

{
  "version": 1,
  "exported_at": "2026-01-01T00:00:00.000Z",
  "workspace": {
    "name": "My Project",
    "description": "...",
    "language": "en",
    "workflow": "scrum"
  },
  "agents": [
    { "name": "builder", "engine": "claude-code", "execution_mode": "local", "system_prompt": null }
  ],
  "task_templates": [
    { "title": "Setup repo", "description": "...", "priority": "p0", "owner": "builder", "labels": "[]" }
  ]
}

POST /api/v1/workspace/import

Import workspace configuration from JSON.

Body:

{
  "version": 1,
  "mode": "merge | replace (optional, default: merge)",
  "agents": [],
  "task_templates": []
}

Response:

{ "ok": true, "mode": "merge", "stats": { "agents_imported": 2, "templates_imported": 3 } }

Workspace User Tasks

GET /api/v1/workspace/user-tasks

List user tasks (manual/human tasks separate from agent sprint tasks). Supports query param status to filter by todo, in_progress, or done.

Response:

[
  {
    "id": "utask-abc12345",
    "workspace_id": "ws-abc123",
    "title": "Review deployment guide",
    "description": "",
    "status": "todo",
    "related_tasks": ["task-uuid-1"],
    "created_at": "2026-01-01T00:00:00",
    "completed_at": null
  }
]

GET /api/v1/workspace/user-tasks/blockers

List incomplete user tasks that block active sprint tasks (tasks whose related_tasks overlap with current sprint task IDs).

Response:

[
  {
    "id": "utask-abc12345",
    "title": "Review deployment guide",
    "status": "todo",
    "related_tasks": ["task-uuid-1"],
    "blocked_sprint_tasks": [
      { "id": "task-uuid-1", "title": "Deploy to prod", "status": "todo", "owner": "builder" }
    ]
  }
]

POST /api/v1/workspace/user-tasks

Create a user task.

Body:

{
  "title": "string (required, max 200)",
  "description": "string (optional, max 2000)",
  "related_tasks": ["task-id-1"]
}

PUT /api/v1/workspace/user-tasks/:id

Update a user task.

Body:

{
  "title": "string (optional)",
  "description": "string (optional)",
  "status": "todo | in_progress | done (optional)",
  "related_tasks": ["task-id"]
}

DELETE /api/v1/workspace/user-tasks/:id

Delete a user task.

Git Token

GET /api/v1/workspace/git-token

Return a short-lived GitHub App installation token for git operations (clone, push, pull). Tokens expire after 1 hour.

Response:

{
  "token": "ghs_xxxxxxxxxxxx",
  "expires_at": "2026-01-01T01:00:00Z"
}

Used by the CLI's credential helper script to authenticate git operations on demand.

Workspaces (Multi-Project)

GET /api/v1/workspaces

List all workspaces for the current user (by GitHub login).

Response:

[
  { "id": "ws-abc123", "name": "My Project", "github_org": "my-org", "github_avatar": "https://..." }
]

POST /api/v1/workspaces

Create a new workspace and switch to it (sets session cookie).

Body:

{
  "language": "en | ja (optional)"
}

POST /api/v1/workspaces/:id/switch

Switch to another workspace owned by the same user. Returns a new API key and sets session cookie.

Response:

{
  "key": "tb_xxx_sk_xxx",
  "workspace": { "id": "ws-abc123", "name": "My Project" }
}

Projects

POST /api/v1/projects/setup

Complete project setup for the current workspace. Creates the manager agent, Sprint 0, initial tasks, and a welcome message. Optionally creates additional agents with per-role engine configuration.

Body:

{
  "name": "string (optional)",
  "github_repo": "owner/repo (optional)",
  "agent_type": "claude-code | codex | custom (optional, default: claude-code)",
  "language": "en | ja (optional, default: ja)",
  "description": "string (optional)",
  "agents": [
    {
      "name": "builder",
      "engine": "claude-code | claude-api | gemini | codex | custom (optional)",
      "execution_mode": "local | byok (optional)",
      "api_key": "string (optional)",
      "command_template": "string (optional)"
    }
  ]
}

Response: 201 Created

{
  "workspace": { "id": "ws-abc123", "name": "My Project", "..." : "..." },
  "manager_agent": { "name": "manager", "status": "active", "..." : "..." },
  "sprint": { "number": 0, "status": "active" }
}

Manager

GET /api/v1/manager/context

Returns enriched context for the Manager agent. This is the primary endpoint the CLI uses to build the Manager's system prompt. Includes:

• Current sprint info and status
• All tasks with their statuses and assignments
• Agent statuses and activity
• Project spec
• Backlog items
• Previous sprint retrospective data

Tasks

GET /api/v1/tasks

List all tasks. Supports query params:

POST /api/v1/tasks

Create a task.

Body:

{
  "title": "Implement login page",
  "description": "Create OAuth login flow with GitHub",
  "owner": "builder (optional, auto-inferred from type)",
  "priority": "p0 (optional, default: p1)",
  "status": "todo (optional)",
  "type": "feature (optional, auto-inferred from title/description)",
  "sprint": 1,
  "branch": "string (optional)",
  "labels": ["feature", "auth"],
  "blocks": [],
  "blocked_by": [],
  "context_notes": "string (optional)",
  "target_repo": "string (optional)",
  "parent_task": "uuid (optional)",
  "story_points": 3
}

PATCH /api/v1/tasks/:id

Update a task. Common fields:

{
  "status": "in_progress",
  "owner": "builder",
  "review_comment": "Completed implementation with tests",
  "commits": "abc1234,def5678",
  "story_points": 3
}

The review_comment field is used by agents to describe what they did. The commits field records commit hashes produced during the task.

DELETE /api/v1/tasks/:id

Delete a task (soft delete).

POST /api/v1/tasks/:id/approve

Approve a task in review status (moves to done).

POST /api/v1/tasks/:id/reject

Reject a task in review status (moves back to in_progress with feedback).

Body:

{ "reason": "Tests are failing" }

POST /api/v1/tasks/:id/review-action

Combined review action endpoint. Supports approve (marks task done, unblocks children) or fix (creates a fix sub-task).

Body:

{
  "action": "approve | fix",
  "comment": "string (optional)",
  "fix_description": "string (optional, used when action is fix)"
}

Response (approve):

{
  "ok": true,
  "status": "done",
  "unblocked_children": [{ "id": "...", "title": "..." }]
}

Response (fix):

{
  "ok": true,
  "status": "review",
  "fix_task": { "id": "...", "title": "Fix: original title" }
}

POST /api/v1/tasks/:id/review-report

Submit a structured review report for a task. If the task is currently in_progress, it is automatically transitioned to review.

Body:

{
  "summary": "string (required)",
  "changes": "string (optional, description of changes made)",
  "test_results": "string (optional)",
  "commits": "string (optional, comma-separated commit hashes)",
  "notes": "string (optional)"
}

Response:

{ "ok": true }

Stories

GET /api/v1/stories

List all stories in the workspace. Stories group related tasks.

POST /api/v1/stories

Create a story. Auto-creates a Builder task for the story.

Body:

{
  "title": "string (required)",
  "description": "string (optional)",
  "sprint": 1,
  "priority": "p1 (optional)"
}

GET /api/v1/stories/:id

Get a single story with its tasks.

PATCH /api/v1/stories/:id

Update a story.

DELETE /api/v1/stories/:id

Delete a story.

GET /api/v1/stories/:id/tasks

List tasks belonging to a story.

Agents

GET /api/v1/agents

List all agents in the workspace with their current status. By default, finished child processes are excluded.

POST /api/v1/agents

Create an agent.

Body:

{ "name": "builder" }

PUT /api/v1/agents

Upsert agent status. Used by the CLI to report agent state. This is an upsert -- if the agent does not exist, it is created.

Body:

{
  "name": "builder",
  "status": "active",
  "activity": "Working on task-123",
  "parent_agent": "string (optional)",
  "ws_port": 4000
}

The ws_port field registers the CLI's WebSocket server port so the Dashboard can connect.

PUT /api/v1/agents/:name/config

Update agent engine configuration.

Body:

{
  "engine": "claude-code",
  "execution_mode": "local",
  "api_key": "sk-... (optional, encrypted at rest)",
  "system_prompt": "Custom instructions..."
}

DELETE /api/v1/agents/:name

Remove an agent. Cannot delete manager or agents that have been active or have assigned tasks.

GET /api/v1/agents/:name/context

Return the assembled agent context (for debugging). Shows the full context that would be injected into the agent's system prompt.

Response:

{
  "agent_name": "builder",
  "context": "Full context string...",
  "parts": { "..." : "..." }
}

GET /api/v1/agents/:name/api-docs

Return the API reference prompt for CLI/agent consumption.

GET /api/v1/agents/:name/prompt-preview

Return the full prompt that would be sent to the agent, for transparency.

Response:

{
  "agent_name": "builder",
  "role": "builder",
  "mode": "compact",
  "prompt": "...",
  "length": 5000,
  "token_estimate": 1250
}

POST /api/v1/agents/check-stalls

Detect stalled agents (no heartbeat within the configured timeout). Updates their status to stalled.

Response:

{
  "stalled": [{ "name": "builder", "last_seen": "2026-01-01T00:00:00" }],
  "count": 1
}

Agent Progress

POST /api/v1/agents/progress

Report agent progress (called by agent-runner during task execution).

Body:

{
  "agent_name": "builder",
  "task_name": "string (optional)",
  "step": "string (optional)",
  "file": "string (optional)",
  "detail": "string (optional)"
}

GET /api/v1/agents/:name/progress

Get latest progress entries for a specific agent (up to 20).

Response:

[
  {
    "id": "...",
    "agent_name": "builder",
    "task_name": "Implement login",
    "step": "writing tests",
    "file": "src/auth.test.ts",
    "detail": "Added 3 test cases",
    "created_at": "2026-01-01T00:05:00"
  }
]

GET /api/v1/agents/progress/latest

Get the latest progress entry per agent across the workspace.

DELETE /api/v1/agents/progress/purge

Purge progress data older than 24 hours.

Agent Memories (Knowledge)

GET /api/v1/agents/memories

List all memory entries across all agents in the workspace.

Response:

{
  "memories": [
    {
      "id": "...",
      "workspace_id": "ws-abc123",
      "agent_name": "builder",
      "key": "preferred-framework",
      "type": "project",
      "content": "Use Next.js for all frontend work",
      "version": 1,
      "last_validated_at": "2026-01-01T00:00:00",
      "expires_days": 7,
      "updated_at": "2026-01-01T00:00:00",
      "created_at": "2026-01-01T00:00:00"
    }
  ],
  "count": 1
}

GET /api/v1/agents/memories/shared

List shared memory entries visible to all agents in the workspace.

GET /api/v1/agents/memories/expired

List expired memory entries in the workspace (entries past their expires_days since last_validated_at).

GET /api/v1/agents/memories/search

Search memory entries by keyword across key and content fields.

GET /api/v1/agents/:name/memories

List all memory entries for a specific agent. Optional query param type to filter.

PUT /api/v1/agents/:name/memories/:key

Create or update a memory entry (upsert by agent name + key). Supports optimistic locking via version.

Body:

{
  "content": "string (required, max 2000)",
  "type": "identity | feedback | project | reference (required)",
  "version": 1,
  "expires_days": 7
}

POST /api/v1/agents/memories/:id/revalidate

Refresh last_validated_at to now, extending the memory's expiration window.

DELETE /api/v1/agents/:name/memories/:key

Delete a memory entry.

Sprints

GET /api/v1/sprints

List all sprints.

POST /api/v1/sprints

Create a sprint.

Body:

{ "number": 1 }

The sprint defaults to active status. The planning status is accepted for backward compatibility but is not used in the current UX. The UI creates sprints as Active immediately.

POST /api/v1/sprints/current/start

Start the current sprint. This is the primary endpoint the CLI calls at startup. It:

1. Activates the sprint (sets status to active)
2. Sets assigned agents to starting status
3. Returns the full sprint context (tasks, agents, workspace info)

Response:

{
  "sprint": { "number": 1, "status": "active" },
  "agents": [{ "name": "builder", "status": "starting", "engine": "claude-code", "execution_mode": "local" }],
  "skippedAgents": [],
  "tasks": [...]
}

PATCH /api/v1/sprints/:number

Update sprint status or metadata.

Body:

{
  "status": "review (optional)",
  "goal": "string (optional)",
  "deadline": "string (optional)"
}

Status values: planning, active, review, retrospective, completed

Valid transitions: planning -> active -> review -> retrospective -> completed (and review -> active for re-opening).

Note: planning exists for API backward compatibility. The UI starts sprints as Active by default. The primary phase flow is: Active -> Review -> Retrospective -> Completed.

GET /api/v1/sprints/current/tasks

Get tasks, agents, sprints list, latest agent progress, and repositories for the current active sprint. Supports query param sprint to specify a sprint number.

GET /api/v1/sprints/:number/review

Get sprint review data with summary, completion stats, tasks grouped by owner, and retrospective comments.

GET /api/v1/sprints/:number/retro

Get retrospective comments for a sprint.

POST /api/v1/sprints/:number/retro

Submit a retrospective comment.

Body:

{
  "agent_name": "builder",
  "went_well": "Fast implementation of auth flow",
  "to_improve": "Need better test coverage",
  "suggested_tasks": [
    { "title": "Add e2e tests for auth", "priority": "p1" }
  ]
}

Analytics

GET /api/v1/sprints/:number/analytics

Sprint analytics data for charts. Includes summary stats, breakdowns by agent/type/priority, and burndown data.

Response:

{
  "sprint": { "number": 1, "status": "active", "created_at": "...", "completed_at": null },
  "summary": {
    "total": 10,
    "done": 6,
    "review": 2,
    "in_progress": 1,
    "todo": 1,
    "completion_rate": 60,
    "total_points": 30,
    "done_points": 18
  },
  "by_agent": {
    "builder": { "total": 5, "done": 3, "points": 15 }
  },
  "by_type": { "feature": 6, "bug": 2, "chore": 2 },
  "by_priority": { "p0": 3, "p1": 5, "p2": 2 },
  "burndown": [
    { "date": "2026-01-01", "remaining": 10 },
    { "date": "2026-01-02", "remaining": 8 }
  ],
  "tasks": [
    { "id": "...", "title": "...", "status": "done", "owner": "builder", "type": "feature", "story_points": 3 }
  ]
}

GET /api/v1/analytics/velocity

Cross-sprint velocity data. Shows task and story point completion across sprints.

Response:

{
  "velocity": [
    {
      "sprint": 1,
      "status": "completed",
      "total": 10,
      "done": 8,
      "total_points": 30,
      "done_points": 24
    }
  ]
}

GET /api/v1/analytics/daily

Daily activity data including hourly task activity, cumulative completion trend, and scorecard.

Response:

{
  "date": "2026-01-15",
  "scorecard": {
    "tasks_done": 5,
    "points": 12,
    "agents_active": 2,
    "types": { "feature": 3, "bug": 2 }
  },
  "hourly": [
    { "hour": 0, "done": 0, "started": 0, "total": 0 },
    { "hour": 14, "done": 3, "started": 1, "total": 5 }
  ],
  "cumulative": [
    { "date": "2026-01-14", "total": 20, "daily": 4 },
    { "date": "2026-01-15", "total": 25, "daily": 5 }
  ],
  "tasks": [
    { "id": "...", "title": "...", "owner": "builder", "type": "feature", "completed_at": "2026-01-15T14:30:00" }
  ]
}

ADR (Architecture Decision Records)

GET /api/v1/adr

List all ADR records for the workspace, ordered by number descending.

Response:

[
  {
    "id": "uuid",
    "workspace_id": "ws-abc123",
    "number": 1,
    "title": "Use PostgreSQL for primary database",
    "status": "accepted",
    "context": "We need a relational database...",
    "decision": "Use PostgreSQL via Supabase",
    "rationale": "Strong SQL support, good ecosystem...",
    "consequences": "Need to manage migrations...",
    "author": "builder",
    "superseded_by": null,
    "created_at": "2026-01-01T00:00:00",
    "updated_at": "2026-01-01T00:00:00"
  }
]

GET /api/v1/adr/prompt

Get ADR summary formatted as prompt text for agent injection. Returns accepted and proposed ADRs as a concise reference block.

Response:

{ "prompt": "\n### Architecture Decisions (ADR)\n..." }

GET /api/v1/adr/:id

Get a single ADR by ID.

POST /api/v1/adr

Create a new ADR. The number is auto-assigned.

Body:

{
  "title": "string (required)",
  "context": "string (required)",
  "decision": "string (required)",
  "rationale": "string (required)",
  "consequences": "string (optional)",
  "author": "string (optional)",
  "status": "proposed | accepted | deprecated | superseded (optional, default: proposed)"
}

Response: 201 Created

{ "id": "uuid", "number": 1 }

PATCH /api/v1/adr/:id

Update an ADR. All fields are optional.

Body:

{
  "title": "string (optional)",
  "status": "proposed | accepted | deprecated | superseded (optional)",
  "context": "string (optional)",
  "decision": "string (optional)",
  "rationale": "string (optional)",
  "consequences": "string (optional)",
  "superseded_by": "uuid | null (optional)"
}

DELETE /api/v1/adr/:id

Delete an ADR.

Messages

GET /api/v1/messages

Get messages. Supports query params:

POST /api/v1/messages

Send a message.

Body:

{
  "from": "user",
  "to": "manager",
  "content": "Please prioritize the login feature"
}

Messages are the API-polling fallback for communication. When the Dashboard is connected via WebSocket, messages flow through the WS server instead.

Failures

GET /api/v1/failures

List failure records for the workspace. Failures are recorded when tasks fail or are rejected during review.

POST /api/v1/failures

Record a failure.

Activity

GET /api/v1/activity

Get activity timeline for the workspace.

Audit Logs

GET /api/v1/audit-logs

Get security audit logs (prompt injection attempts, auth events, agent spawns).

Search

GET /api/v1/search?q=query

Search tasks and messages.

Repos (GitHub)

GET /api/v1/repos

List repositories from the connected GitHub account/organization.

POST /api/v1/repos

Create a new GitHub repository.

GET /api/v1/repos/orgs

List GitHub organizations the user has access to.

GET /api/v1/repos/pulls

List pull requests for the connected repo.

User Info

GET /api/v1/auth/me

Get current user info (GitHub login and avatar) from the workspace. This is the workspace-scoped variant; GET /api/auth/me (without /v1/) is the session-only check used by the auth flow.

Response:

{
  "github_login": "octocat",
  "github_avatar": "https://avatars.githubusercontent.com/u/..."
}

Assistant

GET /api/v1/assistant/templates

List available agent and project templates.

Response:

{
  "agents": [{ "name": "builder", "..." : "..." }],
  "projects": [{ "..." : "..." }]
}

POST /api/v1/assistant/suggest-agents

Suggest agent composition based on project type.

Body:

{ "projectType": "web-app" }

Response:

{
  "agents": ["builder"],
  "details": [{ "name": "builder", "..." : "..." }]
}

POST /api/v1/assistant/translate-task

Convert a natural language instruction into a structured task.

Body:

{ "instruction": "Add dark mode to the settings page" }

Response:

{
  "task": { "title": "...", "description": "...", "type": "feature", "owner": "builder", "priority": "p1" }
}

POST /api/v1/assistant/generate-sprint0

Generate Sprint 0 tasks and create them in the database.

Body:

{
  "projectName": "My App",
  "selectedAgents": ["builder"],
  "templateKey": "web-app (optional)",
  "language": "en | ja (optional)"
}

Response: 201 Created

{
  "tasks": [{ "id": "...", "title": "...", "description": "...", "owner": "builder", "priority": "p0" }],
  "agents": ["builder"]
}

Admin (Site Owner Only)

These endpoints require site owner access (the user who created the first workspace).

GET /api/v1/admin/settings

Get all site settings.

PUT /api/v1/admin/settings

Update site settings.

Body:

{
  "maintenance_enabled": "true | false",
  "maintenance_message": "string",
  "banner_enabled": "true | false",
  "banner_message": "string",
  "banner_scheduled_at": "string"
}

GET /api/v1/admin/workspaces

List all workspaces (admin view).

GET /api/v1/admin/stats

Site-wide statistics.

Response:

{
  "workspaces": 42,
  "active_workspaces_7d": 15,
  "total_tasks": 1200,
  "total_agents": 85
}

API Keys (Internal)

These endpoints are mounted at /api/keys (no /v1/ prefix, no workspace auth).

POST /api/keys

Generate a new API key for an agent.

Body:

{
  "workspace_id": "ws-abc123",
  "agent_name": "builder"
}

GET /api/keys/:workspace_id

List keys for a workspace (prefix only, no secrets).

DELETE /api/keys/:id

Revoke an API key.

Rate Limits

Rate limit headers are included in responses:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset