# Locks

## Queue a lock for a resource

> Requests a lock on a specific resource within a repository. If the resource is already locked, the request is queued. Returns a ticket ID that can be used to check status, attempt acquisition, or release the lock. Locks automatically expire after the specified duration.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/locks":{"post":{"operationId":"MutexController_queueLock","summary":"Queue a lock for a resource","description":"Requests a lock on a specific resource within a repository. If the resource is already locked, the request is queued. Returns a ticket ID that can be used to check status, attempt acquisition, or release the lock. Locks automatically expire after the specified duration.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"repository":{"type":"string"},"resource":{"type":"string"},"leaseDurationSeconds":{"type":"number"}},"required":["repository","resource","leaseDurationSeconds"]}}}},"responses":{"201":{"description":"Lock request queued successfully"},"403":{"description":"Forbidden - Requires role: owner, application"}},"tags":["Locks"]}}}}
```

## Get status of a specific lock

> Retrieves the current status of a lock request by ticket ID. Returns information including lock status (queued/acquired/released), queue position if queued, lease start time and duration if acquired, and requestor details.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/locks/{repository}/{resource}/{ticketId}":{"get":{"operationId":"MutexController_getLockStatus","summary":"Get status of a specific lock","description":"Retrieves the current status of a lock request by ticket ID. Returns information including lock status (queued/acquired/released), queue position if queued, lease start time and duration if acquired, and requestor details.","parameters":[{"name":"repository","required":true,"in":"path","schema":{"type":"string"}},{"name":"resource","required":true,"in":"path","schema":{"type":"string"}},{"name":"ticketId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Lock status retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"resource":{"type":"string"},"ticketId":{"type":"string"},"status":{"type":"string","enum":["queued","acquired","released"]},"queuePosition":{"type":"number"},"leaseStart":{"type":"string","format":"date-time"},"leaseDurationSeconds":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"403":{"description":"Forbidden - Requires role: owner, application"},"404":{"description":"Lock not found"}},"tags":["Locks"]}}}}
```

## Release a lock

> Releases a previously acquired lock using the ticket ID. Only the lock holder or users with owner/application role can release a lock. Once released, the next queued request (if any) will automatically acquire the lock.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/locks/{repository}/{resource}/{ticketId}":{"delete":{"operationId":"MutexController_releaseLock","summary":"Release a lock","description":"Releases a previously acquired lock using the ticket ID. Only the lock holder or users with owner/application role can release a lock. Once released, the next queued request (if any) will automatically acquire the lock.","parameters":[{"name":"repository","required":true,"in":"path","schema":{"type":"string"}},{"name":"resource","required":true,"in":"path","schema":{"type":"string"}},{"name":"ticketId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Lock released successfully"},"403":{"description":"Forbidden - Requires role: owner, application"}},"tags":["Locks"]}}}}
```

## Get all locks for a resource

> Retrieves all lock requests (queued, acquired, and recently released) for a specific resource. Useful for understanding the current lock queue and identifying who holds the lock. Results are ordered by queue position for queued locks.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/locks/{repository}/{resource}":{"get":{"operationId":"MutexController_getResourceLocks","summary":"Get all locks for a resource","description":"Retrieves all lock requests (queued, acquired, and recently released) for a specific resource. Useful for understanding the current lock queue and identifying who holds the lock. Results are ordered by queue position for queued locks.","parameters":[{"name":"repository","required":true,"in":"path","schema":{"type":"string"}},{"name":"resource","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Resource locks retrieved successfully","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"resource":{"type":"string"},"ticketId":{"type":"string"},"status":{"type":"string","enum":["queued","acquired","released"]},"queuePosition":{"type":"number"},"leaseStart":{"type":"string","format":"date-time"},"leaseDurationSeconds":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}},"403":{"description":"Forbidden - Requires role: owner, application"}},"tags":["Locks"]}}}}
```

## Clear all locks for a resource

> Force clears all locks (both acquired and queued) for a specific resource. This is a destructive operation that should only be used for recovery scenarios. All waiting requests will be cancelled. Requires owner or application role.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/locks/{repository}/{resource}":{"delete":{"operationId":"MutexController_clearAllLocks","summary":"Clear all locks for a resource","description":"Force clears all locks (both acquired and queued) for a specific resource. This is a destructive operation that should only be used for recovery scenarios. All waiting requests will be cancelled. Requires owner or application role.","parameters":[{"name":"repository","required":true,"in":"path","schema":{"type":"string"}},{"name":"resource","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"All locks cleared successfully"},"403":{"description":"Forbidden - Requires role: owner, application"}},"tags":["Locks"]}}}}
```

## Attempt to acquire a lock for a queued ticket

> Attempts to acquire a previously queued lock. Returns immediately with the result. If the lock is still queued (another lock is active), returns acquired=false. If this lock is now at the front of the queue, it will be acquired and returns acquired=true. Use this endpoint to poll for lock availability.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.3.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/locks/{repository}/{resource}/{ticketId}/acquire":{"post":{"operationId":"MutexController_attemptLockAcquisition","summary":"Attempt to acquire a lock for a queued ticket","description":"Attempts to acquire a previously queued lock. Returns immediately with the result. If the lock is still queued (another lock is active), returns acquired=false. If this lock is now at the front of the queue, it will be acquired and returns acquired=true. Use this endpoint to poll for lock availability.","parameters":[{"name":"repository","required":true,"in":"path","schema":{"type":"string"}},{"name":"resource","required":true,"in":"path","schema":{"type":"string"}},{"name":"ticketId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"Lock acquisition attempt result","content":{"application/json":{"schema":{"type":"object","properties":{"acquired":{"type":"boolean"},"message":{"type":"string"}}}}}},"403":{"description":"Forbidden - Requires role: owner, application"}},"tags":["Locks"]}}}}
```