Lease locks API

Coordinate identity-owned, fenced work in user, team, or repo scopes. Lock names are 1-200 ASCII letters, digits, ., _, or -.

Learn the ownership boundaries in the Lease locks guide, then see how duplicate responders coordinate.

Endpoints

POST   /api/v1/{scope}/locks/{lock_name}/tickets
GET    /api/v1/{scope}/locks/{lock_name}/tickets/{ticket_uuid}
PUT    /api/v1/{scope}/locks/{lock_name}/tickets/{ticket_uuid}
DELETE /api/v1/{scope}/locks/{lock_name}/tickets/{ticket_uuid}

{scope} is users/{username}, teams/{team_slug}, teams/{team_slug}/repos/{repo_slug}, or users/{username}/repos/{repo_slug}.

Acquire

{"request_uuid":"e41b7608-1fe8-4f54-a5f3-67e8605f480c","lease_seconds":60,"wait_seconds":30}

request_uuid is an identity-level idempotency key. Lease bounds are 5-300 seconds; wait bounds are 0-300. A held ticket returns 201; a FIFO waiter returns 202 with exact queue_position. Immediate contention returns 409 lock_busy; a recursive wait cycle returns 409 deadlock; graph lock timeout returns 503 lock_service_busy.

Lifecycle and fencing

Poll with GET. Heartbeat held tickets with PUT and {"lease_seconds":60} at about one third of the lease interval. DELETE idempotently releases a hold or cancels a waiter and remains allowed for the ticket owner after scope access is revoked.

Reentrant tickets for the same user share a fence token and increment hold depth. Promotion allocates a new globally increasing fence token. Validate and persist that token atomically in the protected external system; a Pearing lease cannot stop already-running external work.