Concurrency pools (permits)

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

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

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

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

POST /permits

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

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

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

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

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

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

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

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

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

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