> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiwifs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Task claims

> Short-lived leases that tell other agents a page is taken, so two agents do not work the same task.

A claim is a **lease** on a path. An agent claims a page before working on it, and other agents that try to claim the same page get `409 Conflict` until the lease expires or the holder releases it. Use claims when several agents pull work from the same pool of pages, such as a task board or a review queue.

Claims are **cooperative**. They do not block writes: a page stays editable by anyone, and agents are expected to check or take a claim first. For protection against overwriting someone else's edit, use [ETags and `If-Match`](https://docs.kiwifs.com/api/overview#optimistic-concurrency).

## How it works

```mermaid theme={null}
sequenceDiagram
  participant A as Agent A
  participant K as KiwiFS
  participant B as Agent B
  A->>K: POST /claim tasks/add-sso.md (X-Actor: agent-a)
  K-->>A: 200 claimed, expires_at
  B->>K: POST /claim tasks/add-sso.md (X-Actor: agent-b)
  K-->>B: 409 already claimed, active_claim
  A->>K: DELETE /claim tasks/add-sso.md
  K-->>A: 200 released
  B->>K: POST /claim tasks/add-sso.md
  K-->>B: 200 claimed
```

* The claim holder is the value of the **`X-Actor`** header (or the `actor` argument over MCP). Give every agent a distinct actor name.
* Claiming a path you already hold renews the lease.
* Only the holder can release a claim. Another actor gets `403`.
* An expired lease is free for anyone to claim. KiwiFS also sweeps expired claims every 30 seconds.
* The path must exist. Claiming a missing file returns `404`.

## Lease duration

Pass `lease_duration` as a duration string such as `15m`, `1h`, or `90s`.

| Value | Result |
| - | - |
| Omitted | 30 minutes |
| Under 1 minute | Raised to 1 minute |
| Over 24 hours | Rejected with `400` |

Pick a lease that covers the work with some margin, and renew it by claiming again if the work runs long.

## Claim, work, release

> [tab] REST
>
> ```bash Terminal theme={null}
> curl -X POST 'http://localhost:3333/api/kiwi/claim' \
>   -H 'Content-Type: application/json' \
>   -H 'X-Actor: agent:builder-1' \
>   -d '{"path": "tasks/add-sso.md", "lease_duration": "45m"}'
> ```
>
> ```json Response theme={null}
> {
>   "path": "tasks/add-sso.md",
>   "claimed_by": "agent:builder-1",
>   "claimed_at": "2026-10-19T09:00:00Z",
>   "expires_at": "2026-10-19T09:45:00Z"
> }
> ```
>
> When the work is done, release the claim:
>
> ```bash Terminal theme={null}
> curl -X DELETE 'http://localhost:3333/api/kiwi/claim' \
>   -H 'Content-Type: application/json' \
>   -H 'X-Actor: agent:builder-1' \
>   -d '{"path": "tasks/add-sso.md"}'
> ```

> [tab] MCP
>
> Call `kiwi_claim` with `path`, `actor`, and an optional `lease_duration`. Release with `kiwi_release` using the same `actor`. `kiwi_claims_list` shows every active claim. `kiwi_task_create` can create a task and claim it in one call with `claim: true`.

A conflicting claim returns the current holder so the agent can move on to other work:

```json 409 Conflict theme={null}
{
  "error": "already claimed",
  "active_claim": {
    "path": "tasks/add-sso.md",
    "claimed_by": "agent:builder-1",
    "claimed_at": "2026-10-19T09:00:00Z",
    "expires_at": "2026-10-19T09:45:00Z"
  }
}
```

`GET /api/kiwi/claims` lists active claims.

## Claims and restructuring

[Refactor plans](https://docs.kiwifs.com/concepts/refactor.md) respect claims. A plan that would move or merge a page someone else has claimed fails with an error naming the holder. A plan that only rewrites links inside a claimed page succeeds with a warning. When a move does go through, the claim follows the page to its new path.

## Storage

Claims live in `.kiwi/state/claims.db`, a SQLite file that is not versioned. Claims are on by default; if the database cannot be opened, the claim endpoints return `503` with `claims not enabled`.

## Related

> [card] [Claims REST API](https://docs.kiwifs.com/api/claims.md)
>
> Claim, release, and list endpoints.

> [card] [Workflows](https://docs.kiwifs.com/concepts/workflows.md)
>
> Move claimed tasks across a Kanban board.

> [card] [Agent playbook](https://docs.kiwifs.com/concepts/agent-playbook.md)
>
> Patterns for agents sharing a knowledge base.

> [card] [MCP](https://docs.kiwifs.com/concepts/mcp.md)
>
> `kiwi_claim`, `kiwi_release`, and `kiwi_claims_list`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.