Claims

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

POST /api/kiwi/claim

string

required

Who is claiming the path. Returns 400 if missing.

string

required

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

string

default:"30m"

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

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"}'

string

Claimed path.

string

Actor holding the lease.

string

When the lease started (RFC 3339, UTC).

string

When the lease ends (RFC 3339, UTC).

{
  "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:

{
  "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.

DELETE /api/kiwi/claim

string

required

Must match the actor that holds the lease.

string

required

Claimed path.

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.

{ "status": "released" }

List active claims

Return every unexpired claim.

GET /api/kiwi/claims

curl 'http://localhost:3333/api/kiwi/claims'

object[]

Active claims, with the same fields as the claim response.

{
  "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.

Claims concepts

How agents coordinate with leases.

Workflows

Move claimed tasks through workflow states.

REST API

CLI

Claim a path

Release a claim

List active claims

MCP equivalents

Claims concepts

Workflows

​Claim a path

​Release a claim

​List active claims

​MCP equivalents

​Related

Claims concepts

Workflows

Claim a path

Release a claim

List active claims

MCP equivalents

Related