Skip to main content
ZStack
Infrastructure/Agents

AcquireLock

Acquire an exclusive operation lock on a specific agent to prevent concurrent changes

POST/api/v1/agents/locks

Operation ID

AcquireLock

Since

1.0.0

Execution Mode

Synchronous

Auth Context

Auth Required

Auth Context

Send these values as request headers when calling this API.

AuthorizationstringRequired

Bearer Token

X-Tenant-IDstring

X-Tenant-ID

Request Inputs

application/json

Body Fields

  • lock
    ObjectRequired

    The lock value

    • agentId
      String

      UUID of the agent to acquire the lock on

      Example: agent-abc123-def456

    • operationType
      String

      Type of operation requiring the lock (e.g. upgrade, restart)

      Example: upgrade

    • holder
      String

      Identity of the lock holder (user or system component)

      Example: upgrade-service

    • ttlSeconds
      Integer

      Lock expiry duration in seconds

      Example: 300

Responses

200 OK
200 OK

On success, this API returns the following response structure.

  • acquired
    Boolean

    Whether the lock was successfully acquired

    Example: true

  • lockToken
    String

    Token used to identify and release the lock

    Example: lock-token-abc123

  • expiresAt
    String

    Expires at

    Example: 2026-01-15T08:00:00Z

  • message
    String

    Informational message about the lock acquisition result

    Example: Lock acquired successfully