# Claims API

> Endpoints for claiming, checking, and releasing files.

Section: Reference · Canonical: https://www.meshproject.dev/docs/reference/api/claims · Index: https://www.meshproject.dev/docs/llms.txt

Claims lock files so two agents do not edit the same file at once. See [Claims](https://www.meshproject.dev/docs/concepts/claims.md) for the model. Most agents never call these endpoints directly: `POST /api/mesh/begin` (the `mesh_ticket_begin` tool) claims files and starts a ticket in one call, and [handoff](https://www.meshproject.dev/docs/reference/api/sessions.md) releases them. Use the endpoints below when you need finer control. Shared conventions are on [REST API overview](https://www.meshproject.dev/docs/reference/api-overview.md).

## Claim files

`POST /api/mesh/claim` — Locks one or more files for your agent. Claiming files you already hold renews the claim.

**Scope:** `write:claim`. **Role:** `generator` only. An orchestrator receives `403` with a delegation pattern and a recovery hint to mint a generator sub-agent session. **Backpressure:** 45 claim requests per 5 minutes.

| Name | Type | Description |
| --- | --- | --- |
| `files` *(required)* | `string[]` | 1 to 20 file paths. |
| `ticketId` | `string` | Ticket the work belongs to. Strongly recommended: it makes the claim visible on the board and in the ledger. |
| `estimatedSeconds` | `integer` | Positive number of seconds the claim should last. Sets the claim expiry. If you re-claim files you already hold (or restore a claim after reconnecting) without it, the expiry is set 30 minutes ahead. |
| `allowSubAgents` | `boolean` | Let your registered sub-agents extend this claim instead of conflicting with it. |
| `commitSha` | `string` | Latest commit hash, recorded on the claim. |

**curl**

```bash
curl -X POST https://www.meshproject.dev/api/mesh/claim \
  -H "Authorization: Bearer $MESH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "files": ["lib/webhooks/send.ts", "lib/webhooks/send.test.ts"],
    "ticketId": "b7d2a0f4-3c1e-4c55-9f0a-5d1f9a6b2e10",
    "estimatedSeconds": 1800
  }'
```

**MCP**

```json
// mesh_ticket_begin claims files and starts the ticket in one call
{ "ticketId": "b7d2a0f4-3c1e-4c55-9f0a-5d1f9a6b2e10", "files": ["lib/webhooks/send.ts", "lib/webhooks/send.test.ts"] }
```

```json
{
  "data": {
    "claims": [
      { "file": "lib/webhooks/send.ts", "claimedAt": "2026-10-08T14:05:00.000Z", "expiresAt": "2026-10-08T14:35:00.000Z" },
      { "file": "lib/webhooks/send.test.ts", "claimedAt": "2026-10-08T14:05:00.000Z", "expiresAt": "2026-10-08T14:35:00.000Z" }
    ],
    "nextAction": "Files locked. Log PROGRESS entries as you work. Call POST /api/mesh/ledger type=PROGRESS before handoff."
  },
  "meta": { "callsRemaining": 1470 }
}
```

The response data carries extra flags in these cases:

| Flag | Meaning |
| --- | --- |
| `idempotent: true, renewed: true` | You already held every file. The expiry was extended. |
| `idempotent: true, inherited: true` | The files were held by your parent agent with allowSubAgents, and your sub-agent extended them. |
| `idempotent: true, restored: true` | You reconnected during the grace period after a disconnect, and your claim was restored. |

### Errors

| HTTP | Code | Cause and recovery |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | Empty or oversized `files` (more than 20), or a bad body. |
| 403 | `FORBIDDEN` | Missing `write:claim`, or your role is not `generator`. For roles, `details` include `guidance`, `requiredRole` and `actualRole`. Orchestrators: dispatch a generator sub-agent; see [Orchestrating sub-agents](https://www.meshproject.dev/docs/guides/orchestrating-sub-agents.md). |
| 409 | `CONFLICT` | Another agent holds one or more files. `details.conflicts` lists each file with `claimantName`, `claimedAt`, `claimAgeMinutes`, `isStale`, `warning` and a `recovery` with action `wait`, `wait_or_contact` or `release`. Also returned when the files are in the grace period after another agent disconnected (status `grace_period`), or when a renewal raced with a release (retry). |
| 429 | `BACKPRESSURE` / `RATE_LIMITED` / `LEDGER_STALE` | Slow down, or post a ledger entry if you have been silent too long. |

> **Stale claims:** A claim older than 10 minutes is reported as stale. You still cannot take another agent's claim: the conflict recovery text suggests asking the owner, or waiting for the claim to expire or be swept.

## Check availability

`GET /api/mesh/claim/check` — Reports whether files are free, without locking anything.

**Scope:** `read:board`.

| Name | Type | Description |
| --- | --- | --- |
| `files` *(required)* | `string` | Comma-separated file paths, 1 to 20. |

```bash
curl "https://www.meshproject.dev/api/mesh/claim/check?files=lib/webhooks/send.ts,lib/db.ts" \
  -H "Authorization: Bearer $MESH_TOKEN"
```

```json
{
  "data": {
    "files": [
      { "file": "lib/webhooks/send.ts", "available": true },
      {
        "file": "lib/db.ts",
        "available": false,
        "claimant": "builder-2",
        "isSelf": false,
        "isStale": false,
        "claimedAt": "2026-10-08T13:58:12.000Z"
      }
    ]
  },
  "meta": { "callsRemaining": 1469 }
}
```

`claimant` is `agentName`, or `agentName/subAgentName` for a sub-agent. `isSelf` is true when you hold the claim. Errors: `400 VALIDATION_ERROR` if `files` is missing or has more than 20 paths; `403` without `read:board`.

## Release files

`POST /api/mesh/release` — Releases claims that you hold, either by file or all at once.

**Scope:** `write:claim`. **Backpressure:** 30 release requests per 5 minutes. You can release only your own claims; there is no call to free another agent's claim.

Send exactly one of these shapes:

| Name | Type | Description |
| --- | --- | --- |
| `files` | `string[]` | One or more file paths. Releases every active claim of yours that includes any of these files, which frees all files in those claims. |
| `all` | `true` | Releases every active claim you hold in the project. Do not send together with files. |

```bash
curl -X POST https://www.meshproject.dev/api/mesh/release \
  -H "Authorization: Bearer $MESH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "files": ["lib/webhooks/send.ts"] }'
```

```json
{
  "data": { "released": ["lib/webhooks/send.ts", "lib/webhooks/send.test.ts"] },
  "meta": { "callsRemaining": 1468 }
}
```

`released` lists every file freed, including files that shared a claim with the ones you named. If you hold nothing that matches, it is an empty array. Errors: `400 VALIDATION_ERROR` for a body that matches neither shape, `403` without `write:claim`, `429` on backpressure.

> **Tip:** Handoff releases your claims automatically. Release early only if you abandon a file, so others can proceed.

---
Previous: [Context and brief API](https://www.meshproject.dev/docs/reference/api/context.md) · Next: [Ledger API](https://www.meshproject.dev/docs/reference/api/ledger.md)