Skip to main content

​
API overview

KanbanAI exposes a JSON HTTP API and real-time interfaces (WebSocket and Server-Sent Events) under a versioned /api/v1 prefix (with a legacy /api shim). This page gives a high-level map of the main resources and how they fit together.

​
Base URLs

  • REST:
    • Development (default): http://localhost:3000/api/v1
    • Legacy shim: http://localhost:3000/api
  • Real-time:
    • WebSocket:
      • Board channel: ws://localhost:3000/api/v1/ws?boardId=<boardId>
      • Dashboard channel: ws://localhost:3000/api/v1/ws/dashboard
      • Terminal channel: ws://localhost:3000/terminals/<cardId>/ws?projectId=<projectId>
    • Server-Sent Events (SSE):
      • Board channel: http://localhost:3000/api/v1/sse?boardId=<boardId> (alternative to WebSocket)
      • Dashboard channel: http://localhost:3000/api/v1/sse (global dashboard events)
SSE provides a simpler HTTP-based alternative to WebSocket with automatic reconnection, better proxy support, and no special protocol handling. All endpoints below are rooted at /api/v1; paths are shown with the full prefix for clarity.

​
Projects & boards

  • Projects:
    • GET /api/v1/projects – list projects.
    • POST /api/v1/projects – create a project from an existing or new repository.
    • GET /api/v1/projects/:projectId – fetch a single project/board.
    • GET /api/v1/projects/:projectId/github/origin – inspect GitHub origin.
    • GET /api/v1/projects/:projectId/settings – load per-project settings.
    • PATCH /api/v1/projects/:projectId/settings – update per-project settings (branch, remote, defaults, inline agent/profile, optional per-inline-agent profile mapping for workflows like ticket enhancement/PR summary, automation flags, failure tolerance toggles allowScriptsToFail, allowCopyFilesToFail, allowSetupScriptToFail, allowDevScriptToFail, allowCleanupScriptToFail, GitHub Issue settings: githubIssueSyncEnabled, githubIssueSyncState (open/all/closed), githubIssueSyncIntervalMinutes (5–1440 minutes), githubIssueAutoCreateEnabled, autoCloseTicketOnPRMerge, autoCloseTicketOnIssueClose, and custom prompts: enhancePrompt and prSummaryPrompt for overriding the default system prompts for ticket enhancement and PR summary generation respectively).
    • POST /api/v1/projects/:projectId/tickets/enhance – send {title, description?, agent?, profileId?} to the configured agent and receive {ticket} with rewritten text (RFC 7807 errors on failure).
    • GET /api/v1/projects/:projectId/enhancements – hydrate persisted enhancement entries. Returns { enhancements: Record<string, { status: "enhancing" | "ready", suggestion?: { title: string, description?: string } }> } so the UI can show badges and up-to-date suggestions.
    • PUT /api/v1/projects/:projectId/cards/:cardId/enhancement – record a card’s enhancement status ("enhancing" while the job runs, "ready" when the agent response is available) and an optional suggestion payload.
    • DELETE /api/v1/projects/:projectId/cards/:cardId/enhancement – clear the persisted enhancement state after acceptance, rejection, or abandonment.
  • Boards:
    • GET /api/v1/boards/:boardId – board state (columns + cards).
    • POST /api/v1/boards/:boardId/cards – create a card. Accepts optional createGithubIssue: boolean (only effective when githubIssueAutoCreateEnabled is on) and images: MessageImage[] (array of base64-encoded images; supports PNG, JPEG, WebP up to 10MB each, max 5 images per card). Responds with { state, cardId, githubIssueError? }.
    • GET /api/v1/boards/:boardId/cards/:cardId/images – fetch images attached to a card. Returns { images: MessageImage[] } where each image contains data (base64), mime (image type), and optional name.
    • PATCH /api/v1/boards/:boardId/cards/:cardId – update card content or move cards (column + index); the payload also accepts isEnhanced so clients can set/clear the enhancement badge without changing the card text, plus disableAutoCloseOnPRMerge so tickets can opt out of the auto-close-on-PR-merge workflow even when the project has it enabled.
    • DELETE /api/v1/boards/:boardId/cards/:cardId – delete a card.
    • POST /api/v1/boards/:boardId/cards/:cardId/github/issue – create a GitHub issue for an existing card (only effective when githubIssueAutoCreateEnabled is on). Responds with { issueNumber: number; url: string }.
    • POST /api/v1/boards/:boardId/import/github/issues – import GitHub issues as cards.
    • GET /api/v1/boards/:boardId/github/issues/stats – counts linked issues by direction (imported, exported, total).
For a project-specific view, you can also access board routes under /api/v1/projects/:projectId/board/*.

​
Attempts & git

  • Attempts:
    • POST /api/v1/projects/:projectId/cards/:cardId/attempts – start a new Attempt for a card.
    • GET /api/v1/projects/:projectId/cards/:cardId/attempt – fetch the latest Attempt for a card.
    • GET /api/v1/attempts/:id – attempt details.
    • PATCH /api/v1/attempts/:id – stop an Attempt ({status:"stopped"}).
    • POST /api/v1/attempts/:id/messages – send follow-up prompts. Accepts {prompt, profileId?, images?: MessageImage[]} where images is an optional array of base64-encoded images (PNG, JPEG, WebP up to 10MB each, max 5 per message).
    • GET /api/v1/attempts/:id/logs – stream logs/messages.
    • GET /api/v1/attempts/:id/messages – fetch paginated conversation messages. Accepts optional query parameters limit (default 25) and offset (default 0). Returns {items: ConversationItem[], total: number, hasMore: boolean}.
    • DELETE /api/v1/attempts/:id/reset – reset an Attempt by clearing conversation history, logs, and todos. Accepts {deleteWorktree: boolean} to optionally delete the git worktree and branch. Returns {attempt, worktreeDeleted: boolean}. Cannot reset running or stopping Attempts.
    • POST /api/v1/projects/:projectId/cards/:cardId/ai-review – trigger AI review for a completed Attempt. Moves the card to AI Review column and starts automated code review.
  • Attempt-scoped Git:
    • GET /api/v1/attempts/:id/git/status – branch + file status for the Attempt worktree.
    • GET /api/v1/attempts/:id/git/file – file content.
    • POST /api/v1/attempts/:id/git/commit – commit changes.
    • POST /api/v1/attempts/:id/git/push – push branch.
    • POST /api/v1/attempts/:id/git/merge – merge into the configured base branch.
These endpoints are used by the Changes dialog, Commit UI, and PR flows in the client.

​
GitHub integration

  • OAuth / device flow:
    • POST /api/v1/auth/github/device/start
    • POST /api/v1/auth/github/device/poll
    • GET /api/v1/auth/github/check
    • POST /api/v1/auth/github/logout
  • App configuration:
    • GET /api/v1/auth/github/app – current OAuth app config and origin (db|env|unset).
    • PUT /api/v1/auth/github/app – update OAuth app client ID/secret.
  • Pull Requests:
    • GET /api/v1/projects/:projectId/pull-requests – list PRs.
    • GET /api/v1/projects/:projectId/pull-requests/:number – PR details.
    • POST /api/v1/projects/:projectId/pull-requests – create a PR, optionally linking branch, attemptId, and cardId.
    • POST /api/v1/projects/:projectId/pull-requests/summary – ask the configured inline agent to generate a PR title/body summary for a base/head branch pair; accepts optional attemptId/cardId so linked GitHub issues can be auto-closed (the response may append closes #123/fixes #456 lines) and returns {summary} or RFC 7807 errors on failure.
Legacy /projects/:projectId/github/pr routes have been removed; all PR operations go through the project-scoped endpoints above.

​
Settings, onboarding, and agents

  • Onboarding:
    • GET /api/v1/onboarding/status
    • PATCH /api/v1/onboarding/progress
    • POST /api/v1/onboarding/complete
  • App settings:
    • GET /api/v1/settings
    • PATCH /api/v1/settings
  • Agents & profiles:
    • GET /api/v1/agents – list registered agents and capabilities.
    • GET /api/v1/projects/:projectId/agents/profiles – list profiles (project + global).
    • POST /api/v1/projects/:projectId/agents/profiles – create a profile.
    • PATCH /api/v1/projects/:projectId/agents/profiles/:id – update a profile.
    • DELETE /api/v1/projects/:projectId/agents/profiles/:id – delete a profile.

​
Filesystem & editor

  • Filesystem:
    • GET /api/v1/fs/git-repos – discover local Git repositories; accepts optional path query.
    • GET /api/v1/fs/browse – browse directories with optional filtering (path, showHidden, executablesOnly).
  • Editor:
    • GET /api/v1/editors/suggestions – list detected and installed editors.
    • POST /api/v1/editors/validate – validate an editor executable path.
    • POST /api/v1/editors/open – open a path in a configured editor.
    • POST /api/v1/attempts/:id/open-editor – open the preferred editor at the Attempt worktree path.
Editor commands emit editor.open.requested/succeeded/failed events that surface as system status in the UI.

​
Dashboard & metrics

  • Dashboard:
    • GET /api/v1/dashboard – returns DashboardOverview (metrics, active attempts, recent activity, inbox, project snapshots, agent stats).
      • Supports time-range selection via query:
        • GET /api/v1/dashboard?timeRangePreset=last_24h
        • GET /api/v1/dashboard?timeRangePreset=last_7d
        • GET /api/v1/dashboard?from=2025-01-01T00:00:00Z&to=2025-01-02T00:00:00Z
        • Convenience alias: range=<value> (supports 24h, 7d, 30d, 90d, all; each maps to the matching timeRangePreset).
          • GET /api/v1/dashboard?range=24h → shorthand for timeRangePreset=last_24h; unknown values return HTTP 400.
        • Precedence: explicit from/to wins, otherwise a provided timeRangePreset is used before range.
      • The DashboardOverview.meta object includes availableTimeRangePresets (allowed presets) and version (forward-compatible version string).
      • The handler maps these parameters into the shared DashboardTimeRange type and echoes it on the response.
    • Real-time channels:
      • WebSocket: GET /api/v1/ws/dashboard (see realtime docs).
      • SSE: GET /api/v1/sse – subscribe to dashboard overview updates via Server-Sent Events.
  • Metrics:
    • GET /api/v1/metrics – minimal Prometheus-style metrics for liveness.
    • GET /api/v1/healthz, GET /api/v1/readyz – health probes.

​
Server metadata

  • GET /api/v1/version – returns {currentVersion, latestVersion, updateAvailable, checkedAt}.
    • currentVersion is derived from KANBANAI_VERSION or the nearest kanban-ai package.json.
    • latestVersion is fetched from GitHub Releases (KANBANAI_UPDATE_REPO, KANBANAI_UPDATE_TOKEN), cached for ~15 minutes, and falls back to currentVersion when the lookup fails.
    • updateAvailable lets clients know when a newer release exists so UI can prompt for restart.

​
Worktrees management

  • Worktrees:
    • GET /api/v1/projects/:projectId/worktrees – list all tracked, orphaned, and stale worktrees with summary statistics.
    • POST /api/v1/projects/:projectId/worktrees/sync – scan the filesystem and database to discover new orphaned and stale worktrees.
    • DELETE /api/v1/projects/:projectId/worktrees/:id – delete a tracked worktree with options (force, diskOnly, deleteBranch, deleteRemoteBranch).
    • DELETE /api/v1/projects/:projectId/worktrees/orphaned/:encodedPath – delete an orphaned worktree found on disk.
    • DELETE /api/v1/projects/:projectId/worktrees/stale/:id – remove a stale database entry for a worktree that no longer exists on disk.

​
Terminals

Terminals are available for cards in “In Progress” or “Review” columns with active worktrees.
  • Terminal support:
    • GET /api/v1/terminals/status – check if terminals are supported on the current platform (returns {supported: boolean, reason: string | null, platform: string}).
  • Project terminals:
    • GET /api/v1/projects/:projectId/terminals – list active terminals for a project.
    • GET /api/v1/projects/:projectId/terminals/eligible – list cards eligible for terminal access.
  • Card terminals:
    • GET /api/v1/terminals/:cardId – get terminal session info.
    • POST /api/v1/terminals/:cardId/resize – resize terminal (cols, rows).
    • DELETE /api/v1/terminals/:cardId – force close a terminal.
  • WebSocket:
    • ws://host/terminals/:cardId/ws?projectId=:projectId – bidirectional terminal I/O.
    • Client → Server: {type: 'data', data: string} or {type: 'resize', cols, rows}.
    • Server → Client: {type: 'data', data: string}, {type: 'exit', code}, or {type: 'error', message}.
For realtime message shapes and WebSocket usage, see core/realtime-and-websockets.md.