Semaphores
A semaphore limits how many tests use one shared resource at a time, such as a sandbox account or a rate-limited vendor API, across every worker and every run in the workspace. Runs take, renew and release leases with the run token from starting a run or a retry, at POST /v1/workspaces/{slug}/semaphores/{name}/leases, POST …/leases/{lease}/renew and DELETE …/leases/{lease}. The first lease creates the semaphore with its capacity, and finishing a run releases every lease it still holds.
The Semaphore object
A named limit on how many tests may use a resource at once, with its holders.
Attributes
namestringRequiredThe semaphore's name in the workspace, such as payments-sandbox.
capacitynumberRequiredHow many leases it allows at once, 1 to 100. The first lease sets it.
holdersarray of objectsRequiredThe leases held now, oldest first.
{ "name": "payments-sandbox", "capacity": 1, "holders": [ { "lease": "Ls4TnV8qWm2C", "run": 1289, "retry": null, "test": "checkout › applies a coupon", "since": "2026-10-14T09:40:20.000Z", "expiresAt": "2026-10-14T09:41:20.000Z" } ]}List semaphores
GET/Returns each semaphore with its capacity and the leases held now.
Path parameters
slugstringRequiredThe workspace's slug or ID, such as acme.
Returns
Returns an object with these fields. Status 200.
Every semaphore in the workspace, by name.
Errors
- 400
InvalidInputThe request is malformed, or a value is not allowed.- 401
UnauthorizedThe request has no valid API key.- 403
ForbiddenThe key's user or role may not do this.- 404
NotFoundThe workspace or object does not exist, or the caller cannot see it.- 409
ConflictThe change conflicts with current data, such as a slug that is already in use.- 500
InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.
curl https://api.qa.clankership.net/v1/workspaces/acme/semaphores \ -H "Authorization: Bearer $CLANKER_API_KEY"{ "semaphores": [ { "name": "payments-sandbox", "capacity": 1, "holders": [ { "lease": "Ls4TnV8qWm2C", "run": 1289, "retry": null, "test": "checkout › applies a coupon", "since": "2026-10-14T09:40:20.000Z", "expiresAt": "2026-10-14T09:41:20.000Z" } ] } ]}