# 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.9.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.9.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.9.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.9.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.9.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.9.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"]}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.flxbl.io/flxbl/sfp-server/api-reference/locks.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.