6.2 — Kanban tracker API reference

If you've gone through the user guide, you already know the kanban tracker as the Development board. Under the hood it's also a fully-scriptable API — every move on the board is one HTTP call, and every MCP tool your IDE agent uses for kanban work calls these endpoints.

This page is the reference for those endpoints: the seven-state lifecycle, the MCP tool signatures, the HTTP API, the audit log shape, the real-time subscription, and the error codes.

If you just want your IDE agent to work through criteria, you don't need any of this — the MCP server handles it. Read this when you're:

• Building a custom UI on top of the kanban data
• Wiring up CI to resolve reviews (the ready-made recipe is 6.3 — CI review driver)
• Writing automations that watch the audit log
• Debugging why a transition got rejected

The lifecycle

Every acceptance criterion moves through these seven states:

   ┌──────────┐    you approve       ┌──────────┐   claim (atomic)   ┌──────────────┐
   │  draft   │  ──── (web only) ──▶ │  ready   │  ─── agent or you ▶│ in_progress  │
   └──────────┘                      └──────────┘                    └──────┬───────┘
                                          ▲                                 │
                                          │                                 │ agent submits
                          system auto-reverts after 24h idle                │ (with git SHA + diff URL)
                                          │                                 ▼
                                          │                          ┌─────────────┐
                                          └──────────────────────────│  in_review  │
                                                                     └──────┬──────┘
                                                                            │
                              ci runner or web user resolves                │
                                            ┌──────────────────────┐        │
                                            │  passed (terminal)   │ ◀──────┤
                                            └──────────────────────┘        │
                                            ┌──────────────────────┐        │
                                            │  failed              │ ◀──────┤
                                            └──────────┬───────────┘
                                                       │ rework — the ASSIGNED
                                                       │ agent, or you
                                                       ▼
                                                 ┌──────────┐
                                                 │  ready   │
                                                 └──────────┘

   any active state → blocked (agent or user) ↔ unblock restores prior state

Two of these changed with the build-loop work and are worth calling out, because older material (including earlier versions of this page) says otherwise:

• ready → in_progress is no longer agent-only. A web session can claim by dragging a card into In Progress. Claiming binds the caller as the assignee, so who claimed it is recorded either way.
• failed → ready is no longer human-only. The criterion's assigned agent can re-queue its own rejected work via the rework endpoint. An agent that is not the assignee still gets 403 not_assigned_agent — you cannot re-queue someone else's rejected work.

Key principle: the agent owns the work-in-progress states (claim, submit_for_review, block, rework) but cannot resolve its own review. Final acceptance is always gated by either a CI result or a human click. Even if an agent calls the resolve endpoint with the right token shape, it gets 403 agents_cannot_self_resolve.

Roles & permissions

A token carries exactly one scope — agent or ci_review, never both. That split is the whole reason an agent can't approve itself: the two capabilities can't live on the same credential.

MCP tool reference

Each tool below is exposed by @vibemap.ai/mcp-server and callable from your IDE.

vibemap_get_next_ready_criterion

Find the highest-priority AC in ready state. Use this at session start or after finishing the previous AC.

Input: { projectId: string }

Output: the criterion record (or null if nothing is available to you).

{
  "criterion": {
    "id": "abc-...",
    "project_id": "...",
    "story_id": "...",
    "title": "User can reset password via email",
    "description": "...",
    "status": "ready",
    "created_at": "..."
  }
}

Reservation — and the footgun

The selector applies a reservation filter: it will only return a criterion whose assignee_id is null or equals the caller's own id. Anything assigned to somebody else is skipped, so assigning a card is a real "leave this one alone" signal rather than a decorative label.

The footgun is who the caller is. A personal access token's identity is the agent — the token itself — not the human who owns it. So:

If you assign a criterion to yourself, your own agent will skip it.

That is the intended behaviour (it's how you hold work back for yourself), but it surprises people, because the token is "yours" in every other sense. To hand work to an agent, assign it to that agent by name — your tokens appear in the board's assignee picker under Your agents. See Assigning work.

VibeMap's own first-party tokens — the ones whose actor id reads env_token:* — pass no caller identity and keep unrestricted behaviour. Their actor id isn't a UUID, so they could never be an assignee in the first place. Your personal access token is not one of these.

Because reservation makes an empty result ambiguous — "nothing is ready" and "everything ready belongs to someone else" look identical to a polling loop — the response adds a diagnostic when the second case applies:

{
  "criterion": null,
  "reason": "reserved",
  "reservedElsewhere": 3,
  "detail": "No criterion is available to you. 3 ready criteria are assigned to someone else."
}

Treat reason: "reserved" as "back off and tell the human", not as "the project is finished".

vibemap_claim_criterion

Atomically transition an AC from ready → in_progress. Race-safe: two parallel callers will see one succeed and the other receive 409 race.

Input: { criterionId: string } Output: the new event row. Errors: 409 race if another agent already claimed it; 422 illegal_transition if the AC isn't in ready.

vibemap_report_progress

Append a progress note to the AC's timeline without changing status.

Input: { criterionId: string, summary: string } (summary 1–2000 chars) Output: the new event row (from_status === to_status).

vibemap_submit_for_review

Mark the implementation done and request review. Transitions in_progress → in_review. Requires a git SHA and a diff URL as audit evidence.

Input:

vibemap_resolve_review (CI / human only)

Resolve a criterion in review — in_review → passed or in_review → failed.

Input:

Errors: 403 agents_cannot_self_resolve — agents can't self-pass their own work. Use a ci_review-scoped token (CI runners) or have a human click "Pass" on the web.

vibemap_block_criterion

Flag a criterion as blocked. Transitions any active state → blocked and captures the prior status so unblock can restore it.

Input:

vibemap_unblock_criterion

Restore a blocked criterion to its prior state.

Input: { criterionId: string, resolution: string }

vibemap_list_kanban_events

List the project's transition history, newest first. Use since for incremental fetches.

Input:

HTTP API reference

Every MCP tool is a thin wrapper around an HTTP endpoint. You can call these directly from CI scripts, custom integrations, or curl. All endpoints require Authorization: Bearer <vm_token>.

The three routes below are the newest, and are not in the MCP tools reference — call them over HTTP.

POST /api/mcp/kanban/criterion/[id]/ci-result

Your CI pipeline's outcome for a criterion sitting in in_review. Resolved as actor kind ci.

This is a deliberately separate surface from resolve-review, not a synonym: it requires the ci_review scope and rejects agent tokens outright, so the CI driver can never become a back door for an agent approving its own work. A browser session is refused too (403 ci_token_required) — humans resolve from the board.

Body:

On success it also fires the build-evidence join (kanban/build.evidence.record), which records the evidence on the criterion and links it to the code-map nodes whose files the sha touched. The join runs out of band — if it fails, the resolve still stands.

Errors: 403 ci_token_required (session caller) · 403 agents_cannot_self_resolve (agent token) · 403 insufficient_scope (token lacks ci_review) · 422 illegal_transition (not in in_review) · 409 race.

Full walkthrough, including the GitHub Actions workflow: 6.3 — CI review driver.

POST /api/mcp/kanban/criterion/[id]/rework

Re-queue a rejected criterion: failed → ready.

The caller must be the criterion's assigned agent — assignee_kind = 'agent' and assignee_id equal to the calling token's own id. Any other agent gets 403 not_assigned_agent, and so does a first-party env token, which has no agent identity and was never bindable as an assignee. A browser session can always do this; that path is the Send back to Ready drag on the board.

Body:

review_feedback is injected server-side from the most recent failed event, so a retry always carries the reason it failed (outcome, test_run_url, notes, resolved_at). Don't send it yourself — the payload schema is strict and an extra key is a 422.

The resulting kanban_events row is also the human-visible notification that rework started: it's what surfaces in the events feed and the card's timeline.

Errors: 403 not_assigned_agent · 403 insufficient_scope · 422 illegal_transition (not in failed) · 409 race.

GET /api/mcp/kanban/projects/[projectId]/execution-plan

The whole plan in one read, instead of discovering it one next-ready call at a time. Read-only; requires the agent scope.

Criteria are topologically sorted by hard dependency, then grouped by sprint in sprint position order, with an Unscheduled group last for anything without a sprint.

{
  "projectId": "...",
  "total": 47,
  "cycle": null,
  "groups": [
    {
      "sprintId": "...",
      "name": "Auth & Sign-up",
      "position": 1,
      "criteria": [
        {
          "id": "...",
          "title": "User can sign in with email",
          "status": "ready",
          "storyId": "...",
          "sprintId": "...",
          "assignee": { "kind": "agent", "id": "..." },
          "order": 0,
          "ready": true,
          "blockedOn": []
        }
      ]
    }
  ]
}

• order is the global topo position, not the position within the group.
• ready is true only when the criterion is in ready and every hard prerequisite has passed. blockedOn lists the prerequisite ids that haven't.
• assignee is null when unassigned — combine it with the reservation rule to see which items your agent will actually be served.

Dependency cycles. A surviving hard-dependency cycle makes a strict order impossible. Rather than fail, the plan falls back to created-at order and names the offenders:

{
  "cycle": {
    "memberIds": ["...", "..."],
    "message": "Hard dependency cycle detected — strict ordering impossible; plan falls back to created-at order. Resolve the dependency-cycle finding first."
  }
}

A non-null cycle means the ordering you're reading is not dependency-respecting. Fix the cycle before trusting it.

Request/response shape

POST endpoints accept either:

• Bare object: { "git_sha": "...", "diff_url": "..." }
• Wrapped: { "payload": { "git_sha": "...", "diff_url": "..." } }

Success response (status-changing routes):

{
  "event": {
    "id": "uuid",
    "project_id": "...",
    "entity_type": "criterion",
    "entity_id": "...",
    "from_status": "in_progress",
    "to_status": "in_review",
    "actor_kind": "mcp",
    "actor_id": "env_token:agent",
    "payload": { "git_sha": "...", "diff_url": "..." },
    "created_at": "..."
  }
}

Curl examples

# Find the next ready AC
curl https://vibemap.ai/api/mcp/kanban/projects/$PROJECT_ID/next-ready \
  -H "Authorization: Bearer $VIBEMAP_API_KEY"

# Claim it
curl -X POST https://vibemap.ai/api/mcp/kanban/criterion/$AC_ID/claim \
  -H "Authorization: Bearer $VIBEMAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# Submit for review with evidence
curl -X POST https://vibemap.ai/api/mcp/kanban/criterion/$AC_ID/submit-for-review \
  -H "Authorization: Bearer $VIBEMAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"git_sha":"a1b2c3d","diff_url":"https://github.com/me/proj/pull/42","notes":"green tests"}'

# Block it
curl -X POST https://vibemap.ai/api/mcp/kanban/criterion/$AC_ID/block \
  -H "Authorization: Bearer $VIBEMAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"spec_unclear","reason":"AC says \"fast\" — what latency target?"}'

# Replay history (incremental from last seen)
curl "https://vibemap.ai/api/mcp/kanban/projects/$PROJECT_ID/events?since=2026-05-09T00:00:00Z&limit=50" \
  -H "Authorization: Bearer $VIBEMAP_API_KEY"

CI integration

Wire your test runner to the ci-result endpoint with a ci_review-scoped token. That route is purpose-built for this: it records build evidence and links the criterion to the code it touched, which resolve-review does not.

The full recipe — minting the token, the workflow YAML, and how to get the criterion id into the job — is 6.3 — CI review driver.

Convention for linking commits to ACs

CI needs to know which criterion a run belongs to. Two workable conventions:

• PR body marker — the agent writes VibeMap-Criterion: <uuid> into the PR body and the workflow greps it. This is what 6.3 uses.
• Commit message suffix — feat(auth): password reset via email (AC-abc-123), grepped from git log -1.

Neither is enforced by the API. The agent's submit_for_review call attaches the git SHA to the audit log regardless; the convention exists purely so your workflow can map a run back to a criterion id.

Audit & event log

Every transition produces an event you can query via the events endpoint above. Event shape:

Payload shapes by transition

Real-time subscription (for custom UIs)

The events feed is published in real time. You can subscribe from a browser client to stream transitions as they happen — useful for building your own kanban UI or a status dashboard. Your client only sees events for projects you can access.

Operational behavior

If you'd like the long-blocked metric to also notify Slack/email, wire your own alerting against the events feed — VibeMap doesn't push notifications natively in v1.

Error reference

Notes on terminal states

• passed is terminal by design. To "reopen", edit the AC's content and approve a new draft, or open a follow-up AC. This intentional friction keeps the audit log trustworthy.
• submit_for_review requires gitSha at the schema level. Local-only experiments can pass a placeholder (e.g. local- plus the first 7 chars of a hash). See the local-only scenario in the user guide.

Related docs

• Kanban tracker: step-by-step user guide — the agent loop, assignment, and the scenarios
• CI review driver — wiring your test pipeline to resolve reviews automatically
• 5.1 — MCP server overview — the broader MCP integration
• 5.2 — Full tools reference — every MCP tool, including non-kanban ones
• 4.1 — API overview — general API conventions