openapi: 3.2.0
info:
  title: LDM v3 RPA service protocol API
  description: 'Multi-tenant B2B outreach automation platform. Auth: JWT Bearer (15-min) or tenant API key (ldm_*) managed in CRM Settings → API Keys. All tenant-scoped endpoints require the X-Tenant-Id header.'
  version: 1.0.0
  contact: {}
servers:
- url: https://api.live-direct-marketing.online
  description: Production
- url: https://api.dev.live-direct-marketing.online
  description: Development
- url: http://127.0.0.1:3000
  description: Local
tags:
- name: RPA service protocol
paths:
  /api/rpa/v1/readiness:
    get:
      operationId: RpaOutboxController_queueReadiness
      parameters:
      - name: cursor
        required: false
        in: query
        description: Use pagination.nextCursor from the preceding target page
        schema:
          maxLength: 512
          type: string
      - name: limit
        required: false
        in: query
        schema:
          minimum: 1
          maximum: 5
          default: 1
          type: number
      - name: campaignAfter
        required: false
        in: query
        description: Use campaigns.nextCampaignAfter, keeping the same target cursor
        schema:
          maxLength: 128
          type: string
      - name: campaignLimit
        required: false
        in: query
        schema:
          minimum: 1
          maximum: 20
          default: 5
          type: number
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      security:
      - rpa-service: []
      summary: Read scoped queue and campaign metadata without claiming, preparing or…
      tags:
      - RPA service protocol
  /api/rpa/v1/heartbeat:
    post:
      operationId: RpaOutboxController_heartbeat
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RpaHeartbeatDto'
      responses:
        '201':
          description: ''
      security:
      - rpa-service: []
      summary: Service heartbeat; include the complete task lease identity to extend a live…
      tags:
      - RPA service protocol
  /api/rpa/v1/claim:
    post:
      description: 'Full tasks include context: durable businessTask UUID and dialog/history links, frozen-render creative/brief references and explicitly mutable source bindings. Links target current CRM resources and require an owner session. Unavailable metadata is explicit. context is not an envelope, send permission, or report input; signed taskId remains the protocol identity.'
      operationId: RpaOutboxController_claim
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RpaWorkerDto'
      responses:
        '201':
          description: ''
      security:
      - rpa-service: []
      summary: 'Poll preparation: task:null while validating; placement-gated tasks begin…'
      tags:
      - RPA service protocol
  /api/rpa/v1/start:
    post:
      description: Includes compact businessTask owner-navigation references, not a second envelope. Read full context from current/refresh; never replace signed taskId with businessTask.id.
      operationId: RpaOutboxController_start
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RpaLeaseDto'
      responses:
        '201':
          description: ''
      security:
      - rpa-service: []
      summary: Revalidate canonical send gates for the claimed operationId; send only when…
      tags:
      - RPA service protocol
  /api/rpa/v1/current:
    post:
      description: Includes the same context contract as claim. Frozen identities are tied to render.fingerprint/renderLeaseId; current names/URLs are not the frozen content. Metadata does not grant CRM access or permission to send.
      operationId: RpaOutboxController_current
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RpaLeaseDto'
      responses:
        '201':
          description: ''
      security:
      - rpa-service: []
      summary: Read the same task and lease after a CONTROL report or server placement poll…
      tags:
      - RPA service protocol
  /api/rpa/v1/renew:
    post:
      operationId: RpaOutboxController_renew
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RpaLeaseDto'
      responses:
        '201':
          description: ''
      security:
      - rpa-service: []
      summary: Extend this worker’s live CLAIMED/STARTED/CONTROL_REPORTED/REAL_READY lease by…
      tags:
      - RPA service protocol
  /api/rpa/v1/refresh:
    post:
      description: Refreshes context/current-resource availability without substituting live campaign creatives or briefs for the matching frozen render. Does not extend the lease.
      operationId: RpaOutboxController_refresh
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RpaLeaseDto'
      responses:
        '201':
          description: ''
      security:
      - rpa-service: []
      summary: Refresh HTTPS attachment links and scoped relay context without changing…
      tags:
      - RPA service protocol
  /api/rpa/v1/report:
    post:
      description: Acknowledgements include compact businessTask references only, never context in the receipt hash. A historical duplicate links its own archived execution/dialog or reports that link unavailable; it does not describe a new child. accepted is receipt acceptance, not proof of final accounting or recipient inbox delivery.
      operationId: RpaOutboxController_report
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RpaReportRequestDto'
      responses:
        '201':
          description: ''
      security:
      - rpa-service: []
      summary: Report one immutable CONTROL or REAL operation.
      tags:
      - RPA service protocol
  /api/rpa/v1/profile-release:
    post:
      operationId: RpaOutboxController_releaseProfile
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RpaProfileReleaseDto'
      responses:
        '201':
          description: ''
      security:
      - rpa-service: []
      summary: Optional terminal-task browser-close acknowledgement.
      tags:
      - RPA service protocol
  /api/rpa/v1/return:
    post:
      operationId: RpaOutboxController_returnTask
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RpaReturnDto'
      responses:
        '201':
          description: ''
      security:
      - rpa-service: []
      summary: Return an execution known not to have sent.
      tags:
      - RPA service protocol
  /api/rpa/v1/reconciliation:
    post:
      operationId: RpaOutboxController_reconciliation
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RpaReconciliationListDto'
      responses:
        '201':
          description: ''
      security:
      - rpa-service: []
      summary: Read this worker’s unresolved tasks, up to 20 per authorized target.
      tags:
      - RPA service protocol
  /api/rpa/v1/reconcile:
    post:
      operationId: RpaOutboxController_reconcile
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RpaReconcileDto'
      responses:
        '201':
          description: ''
      security:
      - rpa-service: []
      summary: Resolve an uncertain execution using positive sent evidence or retained…
      tags:
      - RPA service protocol
  /api/rpa/v1/error:
    post:
      operationId: RpaOutboxController_error
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RpaExecutionErrorDto'
      responses:
        '201':
          description: ''
      security:
      - rpa-service: []
      summary: Report a deduplicated execution error; obey the returned action, never replay…
      tags:
      - RPA service protocol
  /api/rpa/v1/placement:
    post:
      operationId: RpaOutboxController_placement
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RpaPlacementDto'
      responses:
        '201':
          description: ''
      security:
      - rpa-service: []
      summary: Attach late seed-copy placement evidence; never evidence of recipient inbox…
      tags:
      - RPA service protocol
  /api/rpa/v1/attachments/{token}/{filename}:
    get:
      operationId: RpaOutboxAttachmentController_download[0]
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      summary: Download a lease-bound signed attachment with its original filename; legacy…
      tags:
      - RPA service protocol
  /api/rpa/v1/attachments/{token}:
    get:
      operationId: RpaOutboxAttachmentController_download[1]
      parameters:
      - name: X-Tenant-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Tenant UUID — required for all tenant-scoped endpoints
      responses:
        '200':
          description: ''
      summary: Download a lease-bound signed attachment with its original filename; legacy…
      tags:
      - RPA service protocol
components:
  schemas:
    RpaReconcileDto:
      type: object
      properties:
        workerId:
          type: string
          minLength: 1
          maxLength: 128
        capabilityVersion:
          type: string
          maxLength: 64
          description: Required on placement-gated tasks and echoed in the durable receipt
        taskId:
          type: string
          minLength: 1
          maxLength: 4096
        leaseId:
          type: string
          minLength: 1
          maxLength: 128
        fencingToken:
          type: number
          minimum: 1
        operation:
          type: string
          enum:
          - CONTROL
          - REAL
          description: Required for placement-gated tasks; binds this receipt to one immutable phase.
        operationId:
          type: string
          maxLength: 128
          description: Immutable operation identity returned in the full claim.
        taskVersion:
          type: string
          maxLength: 128
        contentFingerprint:
          type: string
          maxLength: 128
        outcome:
          type: string
          enum:
          - SENT
          - DEFINITE_FAILURE
          - UNKNOWN
        relayAccountId:
          type: string
          minLength: 1
          maxLength: 128
        method:
          type: string
          enum:
          - RPA
        envelopeHash:
          type: string
          minLength: 64
          maxLength: 64
        occurredAt:
          type: string
        providerMessageId:
          type: string
          maxLength: 998
        headersApplied:
          type: boolean
        provider:
          type: string
          maxLength: 256
        sender:
          type: string
          maxLength: 320
          description: Sender mailbox from claim.envelope.from; display name is not part of sender identity.
        senderName:
          type: string
          maxLength: 320
          description: Optional display name. Does not authorize delivery or change receipt identity.
        eventId:
          type: string
          format: uuid
        evidenceKind:
          type: string
          enum:
          - PROVIDER_SENT
          - EXECUTOR_NOT_SENT
        evidenceId:
          type: string
          minLength: 1
          maxLength: 256
          description: Reference to retained executor/provider evidence. An empty Sent-folder search is not NOT_SENT evidence.
      required:
      - workerId
      - taskId
      - leaseId
      - fencingToken
      - outcome
      - relayAccountId
      - method
      - envelopeHash
      - occurredAt
      - headersApplied
      - eventId
      - evidenceKind
      - evidenceId
    RpaPlacementDto:
      type: object
      properties:
        workerId:
          type: string
          minLength: 1
          maxLength: 128
        capabilityVersion:
          type: string
          maxLength: 64
          description: Required on placement-gated tasks
        taskId:
          type: string
          minLength: 1
          maxLength: 4096
        leaseId:
          type: string
          minLength: 1
          maxLength: 128
        fencingToken:
          type: number
          minimum: 1
        operation:
          type: string
          enum:
          - CONTROL
          - REAL
        operationId:
          type: string
          maxLength: 128
        taskVersion:
          type: string
          maxLength: 128
        contentFingerprint:
          type: string
          maxLength: 128
        placement:
          type: string
          enum:
          - INBOX
          - SPAM
          - PROMOTIONS
          - NOT_RECEIVED
          - ERROR
        scope:
          type: string
          enum:
          - seed_copy
        provenance:
          type: string
          enum:
          - external_rpa
        correlation:
          type: string
          minLength: 1
          maxLength: 256
        evidenceId:
          type: string
          minLength: 1
          maxLength: 256
        measuredAt:
          type: string
        sentAt:
          type: string
      required:
      - workerId
      - taskId
      - leaseId
      - fencingToken
      - placement
      - scope
      - provenance
      - correlation
      - evidenceId
      - measuredAt
      - sentAt
    RpaProfileReleaseDto:
      type: object
      properties:
        workerId:
          type: string
          minLength: 1
          maxLength: 128
        capabilityVersion:
          type: string
          maxLength: 64
          description: Required for placement-gated tasks; legacy workers fail closed when omitted
        taskId:
          type: string
          minLength: 1
          maxLength: 4096
        leaseId:
          type: string
          minLength: 1
          maxLength: 128
        fencingToken:
          type: number
          minimum: 1
        operation:
          type: string
          enum:
          - CONTROL
          - REAL
        operationId:
          type: string
          maxLength: 128
        taskVersion:
          type: string
          maxLength: 128
        contentFingerprint:
          type: string
          maxLength: 128
        sessionClosed:
          type: number
          enum:
          - true
          description: Positive executor acknowledgement that this task browser session is closed. Mail reports alone do not release the profile before expiresAt.
      required:
      - workerId
      - taskId
      - leaseId
      - fencingToken
      - sessionClosed
    RpaLeaseDto:
      type: object
      properties:
        workerId:
          type: string
          minLength: 1
          maxLength: 128
        capabilityVersion:
          type: string
          maxLength: 64
          description: Required for placement-gated tasks; legacy workers fail closed when omitted
        taskId:
          type: string
          minLength: 1
          maxLength: 4096
        leaseId:
          type: string
          minLength: 1
          maxLength: 128
        fencingToken:
          type: number
          minimum: 1
        operation:
          type: string
          enum:
          - CONTROL
          - REAL
        operationId:
          type: string
          maxLength: 128
        taskVersion:
          type: string
          maxLength: 128
        contentFingerprint:
          type: string
          maxLength: 128
      required:
      - workerId
      - taskId
      - leaseId
      - fencingToken
    RpaReturnDto:
      type: object
      properties:
        workerId:
          type: string
          minLength: 1
          maxLength: 128
        capabilityVersion:
          type: string
          maxLength: 64
          description: Required on placement-gated tasks and echoed in the durable receipt
        taskId:
          type: string
          minLength: 1
          maxLength: 4096
        leaseId:
          type: string
          minLength: 1
          maxLength: 128
        fencingToken:
          type: number
          minimum: 1
        operation:
          type: string
          enum:
          - CONTROL
          - REAL
          description: Required for placement-gated tasks; binds this receipt to one immutable phase.
        operationId:
          type: string
          maxLength: 128
          description: Immutable operation identity returned in the full claim.
        taskVersion:
          type: string
          maxLength: 128
        contentFingerprint:
          type: string
          maxLength: 128
        outcome:
          type: string
          enum:
          - DEFINITE_FAILURE
        relayAccountId:
          type: string
          minLength: 1
          maxLength: 128
        method:
          type: string
          enum:
          - RPA
        envelopeHash:
          type: string
          minLength: 64
          maxLength: 64
        occurredAt:
          type: string
        providerMessageId:
          type: string
          maxLength: 998
        headersApplied:
          type: boolean
        provider:
          type: string
          maxLength: 256
        sender:
          type: string
          maxLength: 320
          description: Sender mailbox from claim.envelope.from; display name is not part of sender identity.
        senderName:
          type: string
          maxLength: 320
          description: Optional display name. Does not authorize delivery or change receipt identity.
      required:
      - workerId
      - taskId
      - leaseId
      - fencingToken
      - outcome
      - relayAccountId
      - method
      - envelopeHash
      - occurredAt
      - headersApplied
    RpaExecutionErrorDto:
      type: object
      properties:
        workerId:
          type: string
          minLength: 1
          maxLength: 128
        capabilityVersion:
          type: string
          maxLength: 64
          description: Required for placement-gated tasks; legacy workers fail closed when omitted
        taskId:
          type: string
          minLength: 1
          maxLength: 4096
        leaseId:
          type: string
          minLength: 1
          maxLength: 128
        fencingToken:
          type: number
          minimum: 1
        operation:
          type: string
          enum:
          - CONTROL
          - REAL
        operationId:
          type: string
          maxLength: 128
        taskVersion:
          type: string
          maxLength: 128
        contentFingerprint:
          type: string
          maxLength: 128
        eventId:
          type: string
          format: uuid
        stage:
          type: string
          enum:
          - PROFILE
          - OPEN_SITE
          - LOGIN
          - PREPARE
          - SEND
          - CONFIRM
        errorCode:
          type: string
          enum:
          - PROFILE_START_FAILED
          - WEBSITE_UNAVAILABLE
          - DNS_ERROR
          - TIMEOUT
          - AUTH_FAILED
          - TWO_FACTOR_REQUIRED
          - CAPTCHA_REQUIRED
          - ACCOUNT_BANNED
          - DELIVERY_UNCERTAIN
        sendAttempted:
          type: boolean
      required:
      - workerId
      - taskId
      - leaseId
      - fencingToken
      - eventId
      - stage
      - errorCode
      - sendAttempted
    RpaReconciliationListDto:
      type: object
      properties:
        workerId:
          type: string
          minLength: 1
          maxLength: 128
        capabilityVersion:
          type: string
          maxLength: 64
          description: Required for placement-gated tasks; legacy workers fail closed when omitted
        after:
          type: string
          description: Read the next page after this delivery ID, independently in each authorized target
      required:
      - workerId
    RpaHeartbeatDto:
      type: object
      properties:
        workerId:
          type: string
          minLength: 1
          maxLength: 128
        capabilityVersion:
          type: string
          maxLength: 64
          description: Required for placement-gated tasks; legacy workers fail closed when omitted
        protocolVersion:
          type: string
          enum:
          - '1'
        taskId:
          type: string
          minLength: 1
          maxLength: 4096
          description: Supply all three lease fields to extend a live task; omit all for service telemetry only
        leaseId:
          type: string
          minLength: 1
          maxLength: 128
        fencingToken:
          type: number
          minimum: 1
        operation:
          type: string
          enum:
          - CONTROL
          - REAL
        operationId:
          type: string
          maxLength: 128
        taskVersion:
          type: string
          maxLength: 128
        contentFingerprint:
          type: string
          maxLength: 128
      required:
      - workerId
      - protocolVersion
    RpaWorkerDto:
      type: object
      properties:
        workerId:
          type: string
          minLength: 1
          maxLength: 128
        capabilityVersion:
          type: string
          maxLength: 64
          description: Required for placement-gated tasks; legacy workers fail closed when omitted
      required:
      - workerId
    RpaReportRequestDto:
      type: object
      properties:
        taskId:
          type: string
          minLength: 1
          maxLength: 4096
        leaseId:
          type: string
          minLength: 1
          maxLength: 128
        outcome:
          type: string
          enum:
          - SENT
          - DEFINITE_FAILURE
          - UNKNOWN
        workerId:
          type: string
          minLength: 1
          maxLength: 128
        capabilityVersion:
          type: string
          maxLength: 64
          description: Required on placement-gated tasks and echoed in the durable receipt
        fencingToken:
          type: number
          minimum: 1
        operation:
          type: string
          enum:
          - CONTROL
          - REAL
          description: Required for placement-gated tasks; binds this receipt to one immutable phase.
        operationId:
          type: string
          maxLength: 128
          description: Immutable operation identity returned in the full claim.
        taskVersion:
          type: string
          maxLength: 128
        contentFingerprint:
          type: string
          maxLength: 128
        relayAccountId:
          type: string
          minLength: 1
          maxLength: 128
        method:
          type: string
          enum:
          - RPA
        envelopeHash:
          type: string
          minLength: 64
          maxLength: 64
        occurredAt:
          type: string
        providerMessageId:
          type: string
          maxLength: 998
        headersApplied:
          type: boolean
        provider:
          type: string
          maxLength: 256
        sender:
          type: string
          maxLength: 320
          description: Sender mailbox from claim.envelope.from; display name is not part of sender identity.
        senderName:
          type: string
          maxLength: 320
          description: Optional display name. Does not authorize delivery or change receipt identity.
      required:
      - taskId
      - leaseId
      - outcome
  securitySchemes:
    jwt:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: JWT access token from /auth/login (Bearer <token>)
    tenant-api-key:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: Tenant API key (Bearer ldm_*) for MCP/A2A clients. Issued via CRM Settings → API Keys.
    rpa-service:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: Dedicated RPA service key. No tenant API-key or query-key authentication.