Lock API

The Synchronize Lock API provides distributed lock management capabilities. This API allows you to acquire, release, and query locks across distributed systems.

Base URL


https://www.synchronize.dev/api

Authentication

All endpoints (except anonymous user creation) require Bearer token authentication.


Authorization: Bearer <your-api-key>

Endpoints

Create Anonymous User

Creates an anonymous user and returns an API key for authentication.

Endpoint: POST /v0/users/anonymous

Note: This endpoint does not require authentication.

Response: 200 OK


{
  "userId": "string",
  "apiKey": "uuid"
}

Field	Type	Required	Description
`userId`	string	Yes	The unique identifier for the created user
`apiKey`	string (uuid)	Yes	The API key to use for authentication

Example:


curl -X POST https://www.synchronize.dev/api/v0/users/anonymous

Create a Lock

Acquires a lock on a specific resource identifier.

Endpoint: POST /v0/lock

Request Body:


{
  "lockName": "string",
  "requester": "string"
}

Field	Type	Required	Description
`lockName`	string	Yes	The name/identifier of the lock to acquire
`requester`	string	Yes	Identifier of the entity requesting the lock

Response: 200 OK


{
  "locked": true,
  "leaseId": "uuid",
  "message": "string"
}

Field	Type	Required	Description
`locked`	boolean	Yes	Whether the lock was successfully acquired
`leaseId`	string (uuid)	No	Unique identifier for this lock lease (returned if locked is true)
`message`	string	No	Additional information about the lock attempt

Example:


curl -X POST https://www.synchronize.dev/api/v0/lock \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "lockName": "resource-123",
    "requester": "service-a"
  }'

Get Lock Information

Retrieves information about a specific lock.

Endpoint: GET /v0/lock

Query Parameters:

Parameter	Type	Required	Description
`lockName`	string	Yes	The name/identifier of the lock to query

Response: 200 OK


{
  "lockName": "string",
  "locked": true,
  "leaseId": "uuid",
  "leasedBy": "string",
  "createdAt": "string",
  "updatedAt": "string"
}

Field	Type	Required	Description
`lockName`	string	Yes	The name/identifier of the lock
`locked`	boolean	Yes	Whether the lock is currently held
`leaseId`	string (uuid)	Yes	The current lease identifier
`leasedBy`	string	Yes	Identifier of the entity holding the lock
`createdAt`	string	No	Timestamp when the lock was created
`updatedAt`	string	No	Timestamp when the lock was last updated

Example:


curl -X GET "https://www.synchronize.dev/api/v0/lock?lockName=resource-123" \
  -H "Authorization: Bearer <your-api-key>"

Unlock a Resource

Releases a previously acquired lock.

Endpoint: POST /v0/unlock

Request Body:


{
  "lockName": "string",
  "leaseId": "string"
}

Field	Type	Required	Description
`lockName`	string	Yes	The name/identifier of the lock to release
`leaseId`	string	Yes	The lease identifier obtained when the lock was acquired

Response: 200 OK


{
  "unlocked": true
}

Field	Type	Description
`unlocked`	boolean	Whether the lock was successfully released

Response: 404 Not Found

Lock identifier not found.

Example:


curl -X POST https://www.synchronize.dev/api/v0/unlock \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "lockName": "resource-123",
    "leaseId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Get All Locks

Retrieves all locks for the authenticated user.

Endpoint: GET /v0/locks

Response: 200 OK


{
  "locks": [
    {
      "lockName": "string",
      "locked": true,
      "leaseId": "uuid",
      "leasedBy": "string",
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}

Field	Type	Description
`locks`	array	Array of lock objects (same structure as Get Lock Information response)

Example:


curl -X GET https://www.synchronize.dev/api/v0/locks \
  -H "Authorization: Bearer <your-api-key>"

Common Use Cases

Acquiring a Lock

Create an anonymous user if you don’t have an API key
Use the API key to authenticate
Call the create lock endpoint with your lock name and requester identifier
If successful, store the leaseId for later use

Releasing a Lock

Call the unlock endpoint with the lock name and lease ID
Verify the unlock was successful

Checking Lock Status

Call the get lock information endpoint with the lock name
Check the locked field to see if the lock is currently held
Review leasedBy to see who holds the lock

Error Handling

401 Unauthorized: Missing or invalid API key
404 Not Found: Lock identifier not found (unlock endpoint)
200 OK with locked: false: Lock acquisition failed because another entity holds the lock