Mabl Job Lock API

openapi: 3.2.0
info:
  title: mabl Job Lock API
  description: APIs for interacting with mabl services
  version: 0.599.3.1792436330
  x-readme-id: 62c896636916ce01d2ff4f5a
servers:
- url: /
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: JobLock
paths:
  /jobLocks/{lock_name}:
    put:
      tags:
      - JobLock
      summary: Renew a named job lock and record progress
      description: Renew a held lock, optionally replacing its progress. The server sets the heartbeat time. Restricted to API keys with global write permission on the lock namespace's scope target.
      operationId: heartbeatNamedJobLock
      parameters:
      - name: lock_name
        in: path
        description: Registered namespace, a dot, then the job's own id, e.g. azure-boards-sync.<integration id>
        required: true
        style: simple
        explode: false
        schema:
          maxLength: 128
          minLength: 3
          pattern: ^[A-Za-z0-9_-]+\.[A-Za-z0-9._-]+$
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobLockUpdate'
        required: true
      responses:
        '200':
          description: Lock renewed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobLockHeartbeatResult'
        '400':
          $ref: '#/components/responses/ErrorResponse400'
        '401':
          $ref: '#/components/responses/ErrorResponse401'
        '403':
          $ref: '#/components/responses/ErrorResponse403'
        '404':
          $ref: '#/components/responses/ErrorResponse404'
        '409':
          $ref: '#/components/responses/ErrorResponse409'
        default:
          $ref: '#/components/responses/ErrorResponse'
      x-mabl-action: Edit::AsyncJob
    post:
      tags:
      - JobLock
      summary: Acquire a named job lock
      description: Acquire a named lock for a background job. A lock left without a heartbeat past its namespace's steal timeout may be taken over. The previous holder's progress is returned so the job can resume. Restricted to API keys with global write permission on the lock namespace's scope target.
      operationId: acquireNamedJobLock
      parameters:
      - name: lock_name
        in: path
        description: Registered namespace, a dot, then the job's own id, e.g. azure-boards-sync.<integration id>
        required: true
        style: simple
        explode: false
        schema:
          maxLength: 128
          minLength: 3
          pattern: ^[A-Za-z0-9_-]+\.[A-Za-z0-9._-]+$
          type: string
      responses:
        '200':
          description: Lock acquired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeldJobLock'
        '400':
          $ref: '#/components/responses/ErrorResponse400'
        '401':
          $ref: '#/components/responses/ErrorResponse401'
        '403':
          $ref: '#/components/responses/ErrorResponse403'
        '404':
          $ref: '#/components/responses/ErrorResponse404'
        '409':
          $ref: '#/components/responses/ErrorResponse409'
        default:
          $ref: '#/components/responses/ErrorResponse'
      x-mabl-action: Edit::AsyncJob
  /jobLocks/{lock_name}/release:
    post:
      tags:
      - JobLock
      summary: Release a named job lock
      description: Release a held lock, optionally recording final progress in the same write. Progress is kept for the next holder. Releasing with a key that no longer holds the lock changes nothing. Restricted to API keys with global write permission on the lock namespace's scope target.
      operationId: releaseNamedJobLock
      parameters:
      - name: lock_name
        in: path
        description: Registered namespace, a dot, then the job's own id, e.g. azure-boards-sync.<integration id>
        required: true
        style: simple
        explode: false
        schema:
          maxLength: 128
          minLength: 3
          pattern: ^[A-Za-z0-9_-]+\.[A-Za-z0-9._-]+$
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobLockUpdate'
        required: true
      responses:
        '204':
          description: Lock released, or not held with this key
        '400':
          $ref: '#/components/responses/ErrorResponse400'
        '401':
          $ref: '#/components/responses/ErrorResponse401'
        '403':
          $ref: '#/components/responses/ErrorResponse403'
        '404':
          $ref: '#/components/responses/ErrorResponse404'
        default:
          $ref: '#/components/responses/ErrorResponse'
      x-mabl-action: Edit::AsyncJob
components:
  responses:
    ErrorResponse401:
      description: User not authenticated
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseGeneric'
    ErrorResponse400:
      description: Invalid or missing parameter
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseGeneric'
    ErrorResponse404:
      description: Entity not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseGeneric'
    ErrorResponse403:
      description: User not authorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseGeneric'
    ErrorResponse409:
      description: Conflicts with the current state of the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseGeneric'
    ErrorResponse:
      description: Unknown error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseGeneric'
  schemas:
    GuardrailApprovalKind:
      type: string
      description: Who decides a guardrail approval. SELF is decided by the person the agent acts for; WORKSPACE, for an agent acting for an API key, by a workspace owner or editor.
      enum:
      - SELF
      - WORKSPACE
    GuardrailRefusal:
      type: object
      properties:
        id:
          type: string
          description: The id of the guardrail policy that decided the refusal.
        reason:
          type: string
          description: Why the policy refuses the request, written for the person the agent acts for.
        decision_id:
          type: string
          description: The id of this decision in the guardrail decision log.
        action:
          type: string
          description: The action the request was evaluated as, written Verb::Resource (for example Delete::Test), as declared by the operation's x-mabl-action extension.
        policy_source:
          type: string
          description: 'Who set the deciding policy: workspace for a rule the workspace''s owners wrote, account for a rule set for the workspace''s account, mabl_agent_type for the agent type''s ceiling, and mabl_default for mabl''s own defaults.'
        approval:
          description: The approval for this request; present when error_code is approval_required and the approval could be recorded. Without it the request cannot be approved.
          allOf:
          - $ref: '#/components/schemas/GuardrailApprovalRef'
      description: The guardrail policy that refused an agent request.
    GuardrailApprovalState:
      type: string
      description: Where a guardrail approval stands. PENDING awaits a decision and expires undecided after 24 hours; APPROVED lets the agent repeat the request, as often as it does, for 20 minutes; DENIED refuses the same request for 20 minutes after the decision, after which asking again opens a new approval; CANCELLED means a person withdrew it while pending or revoked it while approved. EXPIRED and CANCELLED are final.
      enum:
      - PENDING
      - APPROVED
      - DENIED
      - EXPIRED
      - CANCELLED
    JobLockHeartbeatResult:
      required:
      - last_updated
      - lock_name
      type: object
      properties:
        lock_name:
          type: string
          description: Name of the lock
        last_updated:
          type: integer
          description: Epoch milliseconds of this heartbeat, set by the server
          format: int64
      description: A renewed lock
    HeldJobLock:
      required:
      - acquired_time
      - last_updated
      - lock_key
      - lock_name
      type: object
      properties:
        lock_name:
          type: string
          description: Name of the lock
        lock_key:
          type: string
          description: Key that renews or releases the lock while it is held
          x-sensitive: true
        acquired_time:
          type: integer
          description: Epoch milliseconds when the lock was acquired
          format: int64
        last_updated:
          type: integer
          description: Epoch milliseconds of the lock's last write, set by the server
          format: int64
        progress:
          type: string
          description: Opaque progress last recorded on the lock, kept across holders
      description: A named job lock held by the caller
    GuardrailApprovalRef:
      type: object
      properties:
        id:
          type: string
          description: The approval's id.
        state:
          description: Where the approval stands.
          allOf:
          - $ref: '#/components/schemas/GuardrailApprovalState'
        kind:
          description: Who decides the approval.
          allOf:
          - $ref: '#/components/schemas/GuardrailApprovalKind'
        request_expires_time:
          type: integer
          description: When the approval expires if nobody decides it, in epoch milliseconds.
          format: int64
        url:
          type: string
          description: The mabl app page where a person reviews the approval.
      description: 'An approval a guardrail policy asks for. While it is PENDING, stop: give the person the url, tell them the request is waiting for approval, and do not repeat the request or poll in a loop. Once a person tells you it is APPROVED, repeat the identical request with the header X-Mabl-Approval set to id. DENIED means a person said no, so do not work around it.'
    ErrorResponseGeneric:
      type: object
      properties:
        id:
          type: string
          x-mabl-scope: public
        code:
          maximum: 599
          minimum: 100
          type: integer
          format: int32
          x-mabl-scope: public
        message:
          type: string
          x-mabl-scope: public
        error_code:
          type: string
          description: Machine-readable reason for the error, present only when the API names one. Values are guardrail_blocked (a guardrail policy refused an agent request), approval_required (a guardrail policy requires a person to approve the request first).
        guardrail:
          description: The guardrail policy that refused the request; present only when error_code is guardrail_blocked or approval_required.
          allOf:
          - $ref: '#/components/schemas/GuardrailRefusal'
    JobLockUpdate:
      required:
      - lock_key
      type: object
      properties:
        lock_key:
          maxLength: 64
          minLength: 1
          type: string
          description: Key returned when the lock was acquired
          x-sensitive: true
        progress:
          maxLength: 8192
          type: string
          description: Opaque progress to store, at most 8192 bytes as UTF-8. Omit to keep the stored progress.
      description: Renews or releases a held lock
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    bearerAuth:
      type: apiKey
      name: Authorization
      in: header