# Barriers

> Wait-for-all rendezvous points.

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

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

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

Read-only barrier list with optional state filter.

- **Key permission:** `coordination_read`

**Path parameters**

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

**Responses**

| Status | Meaning |
| --- | --- |
| `200` | Barriers |

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

## POST /barriers

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

Create rendezvous.

- **Key permission:** `resource_config`
- **Idempotency-Key header:** required
- **TypeScript SDK:** `run.barriers.create()`
- **Python SDK:** `run.barriers.create()`

**Path parameters**

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

**Request body** (JSON)

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

**Responses**

| Status | Meaning |
| --- | --- |
| `201` | Barrier id |

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

## POST /barriers/{id}/arrive

```http
POST /v1/spaces/{spaceId}/barriers/{id}/arrive
```

Idempotent arrival per epoch.

- **Key permission:** `coordination_write`
- **TypeScript SDK:** `barrier.arrive()`
- **Python SDK:** `barrier.arrive()`

**Path parameters**

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

**Request body** (JSON)

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `arrivalKey` | string | yes |  |

**Responses**

| Status | Meaning |
| --- | --- |
| `200` | state/epoch/arrivals/target |
| `409` | Error envelope `{"error":{"code","message","requestId"}}` |

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

## POST /barriers/{id}/nextEpoch

```http
POST /v1/spaces/{spaceId}/barriers/{id}/nextEpoch
```

Advance epoch after RELEASED/CANCELLED for reuse.

- **Key permission:** `coordination_write`

**Path parameters**

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

**Responses**

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

```bash
curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/barriers/<id>/nextEpoch" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

## GET /barriers/{id}

```http
GET /v1/spaces/{spaceId}/barriers/{id}
```

Epoch, arrivals, release state.

- **Key permission:** `coordination_read`
- **TypeScript SDK:** `barrier.status(), barrier.wait()`
- **Python SDK:** `barrier.status(), barrier.wait()`

**Path parameters**

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

**Responses**

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

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