---
title: "Atomically claim the next actionable task"
method: POST
path: "/api/v0/tasks/claim-next"
tags: ["Agent"]
---

# Atomically claim the next actionable task

`POST /api/v0/tasks/claim-next`

## Request

- Base URL: `https://app.vibeflow.tools`
- URL: `https://app.vibeflow.tools/api/v0/tasks/claim-next`
- Auth: HTTP bearer

No local HTTP handler — local claim lives in core claimNextTaskAtomic + MCP claim_next_task. Cloud needs SELECT FOR UPDATE SKIP LOCKED (Phase 3). Runner marks NOT-RUNNABLE locally.

## Request body

- ClaimFilter
  - `status` 'backlog' | 'todo' | 'in-progress' | 'review' | 'done' | 'cancelled'
  - `tags` string[]

## Response `200`

Atomically claim the next actionable task — success

- ClaimNext
  - `task` Task, required: v0 canonical task = local Task fields plus external id, counts, and createdAt alias. D3: responses carry BOTH id and externalId.
    - `id` string, required: External id (cli_id ?? id on cloud; the local id locally)
    - `externalId` string, required: Universal external id — equal to id on the local surface
    - `title` string, required
    - `description` string
    - `status` 'backlog' | 'todo' | 'in-progress' | 'review' | 'done' | 'cancelled', required
    - `selector` string
    - `priority` string
    - `verified` boolean, nullable
    - `links` TaskLink[]
      - `taskId` string, required
      - `type` 'parent' | 'relates' | 'blocks', required
    - `commentCount` integer
    - `fileCount` integer
    - `createdAt` string, date-time

## Other responses

- `400`: Malformed request (includes invalid task/comment id form)
- `401`: Missing or invalid principal
- `403`: Lacking scope or membership
- `404`: Unknown id
- `429`: Rate limited — cloud per-token quota exceeded (reads 300/min, writes 60/min, token creation 10/hour); counters are per-replica, so the effective limit is the configured value × replicas. The response carries Retry-After.

---

[API](https://skmtc.dev/vibeflow/apis/vibeflow-api-v0.md) · [All operations](https://skmtc.dev/vibeflow/apis/vibeflow-api-v0/llms.txt) · [OpenAPI document](https://skmtc.dev/vibeflow/apis/vibeflow-api-v0/revisions/efd4ba944b0b?raw)