# Concurrency pools (permits)

> Capacity counters (permits) and the leased grants taken from them.

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

<!-- 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 /permits

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

Read-only permit list with unit accounting.

- **Key permission:** `coordination_read`
- **TypeScript SDK:** `pool.status()`
- **Python SDK:** `pool.status()`

**Path parameters**

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

**Responses**

| Status | Meaning |
| --- | --- |
| `200` | Permits |

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

## POST /permits

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

Configure capacity counter.

- **Key permission:** `coordination_write`
- **Idempotency-Key header:** required
- **TypeScript SDK:** `rs.pools.ensure()`
- **Python SDK:** `rs.pools.ensure()`

**Path parameters**

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

**Request body** (JSON)

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `units` | integer | yes | min 1 |

**Responses**

| Status | Meaning |
| --- | --- |
| `201` | Permit id |

```bash
curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/permits" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"<name>","units":1}'
```

## POST /permits/{id}/acquire

```http
POST /v1/spaces/{spaceId}/permits/{id}/acquire
```

Take units when available.

- **Key permission:** `coordination_write`
- **TypeScript SDK:** `run.pool(name).acquire() / .tryAcquire() / .run()`
- **Python SDK:** `run.pool(name).acquire() / .try_acquire() / .run()`

**Path parameters**

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

**Request body** (JSON)

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `scopeId` | string (uuid) | yes |  |
| `units` | integer | yes | min 1 |
| `holder` | string | yes |  |
| `holderSession` | string | yes |  |
| `leaseSeconds` | integer | no | default `30` |
| `waiterId` | string (uuid) | no |  |

**Responses**

| Status | Meaning |
| --- | --- |
| `201` | Grant with token |
| `409` | Error envelope `{"error":{"code","message","requestId"}}` |

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

## POST /permits/{id}/wait

```http
POST /v1/spaces/{spaceId}/permits/{id}/wait
```

Enqueue durably in FIFO waiter list.

- **Key permission:** `coordination_write`

**Path parameters**

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

**Request body** (JSON)

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `scopeId` | string (uuid) | yes |  |
| `units` | integer | yes | min 1 |
| `holder` | string | yes |  |

**Responses**

| Status | Meaning |
| --- | --- |
| `202` | waiterId |

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

## POST /grants/{id}/renew

```http
POST /v1/spaces/{spaceId}/grants/{id}/renew
```

Renew held grant.

- **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 |
| `id` | string (uuid) | required |

**Request body** (JSON)

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

**Responses**

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

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

## POST /grants/{id}/release

```http
POST /v1/spaces/{spaceId}/grants/{id}/release
```

Release grant; 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 |
| `id` | string (uuid) | 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/grants/<id>/release" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"token":"<lease token>"}'
```