# Claims

> Exclusive, leased ownership of a named key inside a run.

Source: https://docs.getrunstate.com/api/claims/

<!-- Generated by apps/docs/scripts/gen-api.mjs from packages/contracts/openapi.yaml. Do not edit. -->

All paths are relative to the API base URL (`https://api.getrunstate.com`) and require `Authorization: Bearer <api key>`. See [the API overview](https://docs.getrunstate.com/api/) for authentication, idempotency and the error envelope.

## GET /claims

```http
GET /v1/spaces/{spaceId}/claims
```

Read-only claim list with optional key prefix filter.

- **Key permission:** `coordination_read`

**Path parameters**

| Name | Type | Notes |
| --- | --- | --- |
| `spaceId` | string (uuid) | required |

**Responses**

| Status | Meaning |
| --- | --- |
| `200` | Claims |

```bash
curl -X GET "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/claims" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY"
```

## POST /claims

```http
POST /v1/spaces/{spaceId}/claims
```

Claim a named key.

- **Key permission:** `coordination_write`
- **Idempotency-Key header:** required
- **TypeScript SDK:** `run.claim(key).acquire() / .tryAcquire() / .run()`
- **Python SDK:** `run.claim(key).acquire() / .try_acquire() / .run()`

**Path parameters**

| Name | Type | Notes |
| --- | --- | --- |
| `spaceId` | string (uuid) | required |

**Request body** (JSON)

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `key` | string | yes | length 1–512 |
| `scopeId` | string (uuid) | yes |  |
| `holder` | string | yes |  |
| `holderSession` | string | yes |  |
| `leaseSeconds` | integer | no | 5–600; default `30` |

**Responses**

| Status | Meaning |
| --- | --- |
| `201` | Claim held; fenced token returned |
| `409` | Error envelope `{"error":{"code","message","requestId"}}` |

```bash
curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/claims" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"key":"<key>","scopeId":"<run id>","holder":"worker-1","holderSession":"<session id>"}'
```

## GET /claims/{key}

```http
GET /v1/spaces/{spaceId}/claims/{key}
```

Current holder of a key.

- **Key permission:** `coordination_read`

**Path parameters**

| Name | Type | Notes |
| --- | --- | --- |
| `spaceId` | string (uuid) | required |
| `key` | string | required |

**Responses**

| Status | Meaning |
| --- | --- |
| `200` | Claim row |
| `404` | Error envelope `{"error":{"code","message","requestId"}}` |

```bash
curl -X GET "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/claims/<key>" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY"
```

## POST /claims/{key}/renew

```http
POST /v1/spaces/{spaceId}/claims/{key}/renew
```

Renew the current holder's lease.

- **Key permission:** `coordination_write`
- **TypeScript SDK:** `lease.renew() (automatic while held)`
- **Python SDK:** `lease.renew() (automatic while held)`

**Path parameters**

| Name | Type | Notes |
| --- | --- | --- |
| `spaceId` | string (uuid) | required |
| `key` | string | required |

**Request body** (JSON)

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `token` | string | yes |  |
| `leaseSeconds` | integer | no | 5–600; default `30` |

**Responses**

| Status | Meaning |
| --- | --- |
| `200` | New lease expiry |
| `409` | Error envelope `{"error":{"code","message","requestId"}}` |

```bash
curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/claims/<key>/renew" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"token":"<lease token>"}'
```

## POST /claims/{key}/release

```http
POST /v1/spaces/{spaceId}/claims/{key}/release
```

Release with token; allowed after scope cancellation (safe cleanup)

- **Key permission:** `coordination_write`
- **TypeScript SDK:** `lease.release()`
- **Python SDK:** `lease.release()`

**Path parameters**

| Name | Type | Notes |
| --- | --- | --- |
| `spaceId` | string (uuid) | required |
| `key` | string | required |

**Request body** (JSON)

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `token` | string | yes |  |
| `observation` | any JSON | no |  |

**Responses**

| Status | Meaning |
| --- | --- |
| `200` | Released |
| `409` | Error envelope `{"error":{"code","message","requestId"}}` |

```bash
curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/claims/<key>/release" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"token":"<lease token>"}'
```