Barriers

Wait-for-all rendezvous points.

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

GET /barriers

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

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

POST /barriers

POST /v1/spaces/{spaceId}/barriers

Create rendezvous.

Key permission: resource_config
Idempotency-Key header: required

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

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

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

Idempotent arrival per epoch.

Key permission: coordination_write
TypeScript SDK: runstate.together(name, count)
Python SDK: runstate.together(name, count)

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

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

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

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}

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

Epoch, arrivals, release state.

Key permission: coordination_read
TypeScript SDK: runstate.together(name, count) (while waiting)
Python SDK: runstate.together(name, count) (while waiting)

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

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

PUT /barriers/by-name/{name}

PUT /v1/spaces/{spaceId}/barriers/by-name/{name}

Get-or-create a named barrier in a run.

Key permission: coordination_write
TypeScript SDK: runstate.together(name, count)
Python SDK: runstate.together(name, count)

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required
`name`	string	length 1–256

Request body (JSON)

Field	Type	Required	Notes
`scopeId`	string (uuid)	yes
`target`	integer	yes	1–100000

Responses

Status	Meaning
`200`	Existing barrier: {id, name, epoch, target, state, arrivals, created: false}
`201`	Created
`409`	Error envelope `{"error":{"code","message","requestId"}}`

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