> ## 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.

# Claims

> Claim, release, and list cooperative leases on file paths.

A claim is a time-limited lease that tells other agents you are working on a path. Claims are cooperative: they don't block writes, but agents that check claims before working avoid doing the same task twice. Refactor plans also refuse to move claimed pages and keep claims attached to pages they move. See [Claims](https://docs.kiwifs.com/concepts/claims.md) for patterns.

Claims are stored in `.kiwi/state/` and are on by default. If the claim store can't open, every endpoint returns `503` with `claims not enabled`.

## Claim a path

Acquire a lease on an existing file, or extend a lease you already hold.

```http theme={null}
POST /api/kiwi/claim
```

**X-Actor** `string` *required*

Who is claiming the path. Returns `400` if missing.

**path** `string` *required*

File path. Returns `404` if the file does not exist.

**lease\_duration** `string` (default: 30m)

Go duration such as `45m` or `2h`. Values under `1m` are raised to `1m`. Values over `24h` return `400`.

```bash theme={null}
curl -X POST 'http://localhost:3333/api/kiwi/claim' \
  -H "Content-Type: application/json" \
  -H "X-Actor: agent:deployer" \
  -d '{"path": "runbooks/deploy.md", "lease_duration": "45m"}'
```

**path** `string`

Claimed path.

**claimed\_by** `string`

Actor holding the lease.

**claimed\_at** `string`

When the lease started (RFC 3339, UTC).

**expires\_at** `string`

When the lease ends (RFC 3339, UTC).

```json theme={null}
{
  "path": "runbooks/deploy.md",
  "claimed_by": "agent:deployer",
  "claimed_at": "2026-10-19T14:00:00Z",
  "expires_at": "2026-10-19T14:45:00Z"
}
```

If another actor holds an unexpired lease, the server returns `409` with that lease:

```json theme={null}
{
  "error": "already claimed",
  "active_claim": {
    "path": "runbooks/deploy.md",
    "claimed_by": "agent:other",
    "claimed_at": "2026-10-19T13:50:00Z",
    "expires_at": "2026-10-19T14:20:00Z"
  }
}
```

## Release a claim

Release a lease you hold. The body goes on a `DELETE` request.

```http theme={null}
DELETE /api/kiwi/claim
```

**X-Actor** `string` *required*

Must match the actor that holds the lease.

**path** `string` *required*

Claimed path.

```bash theme={null}
curl -X DELETE 'http://localhost:3333/api/kiwi/claim' \
  -H "Content-Type: application/json" \
  -H "X-Actor: agent:deployer" \
  -d '{"path": "runbooks/deploy.md"}'
```

Returns `403` if the caller does not hold a claim on the path.

```json theme={null}
{ "status": "released" }
```

## List active claims

Return every unexpired claim.

```http theme={null}
GET /api/kiwi/claims
```

```bash theme={null}
curl 'http://localhost:3333/api/kiwi/claims'
```

**claims** `object[]`

Active claims, with the same fields as the [claim response](#claim-a-path).

```json theme={null}
{
  "claims": [
    {
      "path": "runbooks/deploy.md",
      "claimed_by": "agent:deployer",
      "claimed_at": "2026-10-19T14:00:00Z",
      "expires_at": "2026-10-19T14:45:00Z"
    }
  ]
}
```

## MCP equivalents

`kiwi_claim`, `kiwi_release`, and `kiwi_claims_list`.

## Related

> [card] [Claims concepts](https://docs.kiwifs.com/concepts/claims.md)
>
> How agents coordinate with leases.

> [card] [Workflows](https://docs.kiwifs.com/api/workflows.md)
>
> Move claimed tasks through workflow states.


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