# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Live Direct Marketing Online RPA service protocol API
  version: 1.0.0
extends: openapi/live-direct-marketing-online-rpa-service-protocol-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 16
- target: $.paths['/api/rpa/v1/readiness'].get
  update:
    x-apievangelist-phrasing:
      intent: Read RPA queue and campaign readiness
      effect: read
      questions:
      - Can an RPA worker see what's queued without claiming any task?
      - How do I page through the full RPA queue readiness snapshot?
      instructions:
      - text: Show the RPA queue readiness snapshot.
      - text: Read the next page of RPA queue readiness after cursor {cursor}.
        slots:
          cursor: query.cursor
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/rpa/v1/heartbeat'].post
  update:
    x-apievangelist-phrasing:
      intent: Send an RPA worker heartbeat
      effect: write
      questions:
      - How does an RPA worker signal it is still alive?
      - Can a heartbeat extend the lease on the task a worker holds?
      instructions:
      - text: Send a heartbeat for worker {workerId} on protocol {protocolVersion}.
        slots:
          workerId: requestBody.workerId
          protocolVersion: requestBody.protocolVersion
      - text: Heartbeat worker {workerId} and extend task {taskId} on lease {leaseId}, protocol {protocolVersion}.
        slots:
          workerId: requestBody.workerId
          taskId: requestBody.taskId
          leaseId: requestBody.leaseId
          protocolVersion: requestBody.protocolVersion
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/rpa/v1/claim'].post
  update:
    x-apievangelist-phrasing:
      intent: Claim the next RPA send task
      effect: write
      questions:
      - How does an RPA worker pick up its next email send task?
      - Why does claiming an RPA task sometimes return a null task?
      instructions:
      - text: Claim the next send task for worker {workerId}.
        slots:
          workerId: requestBody.workerId
      - text: Poll for a new RPA task as worker {workerId}.
        slots:
          workerId: requestBody.workerId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/rpa/v1/start'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a claimed RPA send operation
      effect: write
      questions:
      - How does a worker confirm the send gates still pass before sending a claimed task?
      - When is an RPA worker actually allowed to send?
      instructions:
      - text: Start task {taskId} for worker {workerId} on lease {leaseId} with fencing token {fencingToken}.
        slots:
          workerId: requestBody.workerId
          taskId: requestBody.taskId
          leaseId: requestBody.leaseId
          fencingToken: requestBody.fencingToken
      - text: Revalidate send gates for operation {operationId} on task {taskId}, worker {workerId}, lease {leaseId}, token {fencingToken}.
        slots:
          workerId: requestBody.workerId
          taskId: requestBody.taskId
          leaseId: requestBody.leaseId
          fencingToken: requestBody.fencingToken
          operationId: requestBody.operationId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/rpa/v1/current'].post
  update:
    x-apievangelist-phrasing:
      intent: Re-read the current RPA task and lease
      effect: read
      questions:
      - After a control report, how does a worker re-read its current task without a second claim?
      - Can an RPA worker fetch the latest state of the task it already holds?
      instructions:
      - text: Read the current state of task {taskId} for worker {workerId}, lease {leaseId}, token {fencingToken}.
        slots:
          workerId: requestBody.workerId
          taskId: requestBody.taskId
          leaseId: requestBody.leaseId
          fencingToken: requestBody.fencingToken
      - text: Re-fetch held task {taskId} and its lease {leaseId} as worker {workerId} with token {fencingToken}.
        slots:
          workerId: requestBody.workerId
          taskId: requestBody.taskId
          leaseId: requestBody.leaseId
          fencingToken: requestBody.fencingToken
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/rpa/v1/renew'].post
  update:
    x-apievangelist-phrasing:
      intent: Renew an RPA task lease
      effect: write
      questions:
      - How do I extend a live RPA task lease by another hour?
      - Can an expired RPA lease be renewed?
      instructions:
      - text: Renew lease {leaseId} on task {taskId} for worker {workerId}, token {fencingToken}.
        slots:
          workerId: requestBody.workerId
          taskId: requestBody.taskId
          leaseId: requestBody.leaseId
          fencingToken: requestBody.fencingToken
      - text: Extend worker {workerId}'s lease {leaseId} on task {taskId} by 60 minutes using token {fencingToken}.
        slots:
          workerId: requestBody.workerId
          taskId: requestBody.taskId
          leaseId: requestBody.leaseId
          fencingToken: requestBody.fencingToken
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/rpa/v1/refresh'].post
  update:
    x-apievangelist-phrasing:
      intent: Refresh attachment links for an RPA task
      effect: read
      questions:
      - My attachment links on an RPA task expired — can I refresh them?
      - Does refreshing an RPA task's context also extend its lease?
      instructions:
      - text: Refresh attachment links for task {taskId}, worker {workerId}, lease {leaseId}, token {fencingToken}.
        slots:
          workerId: requestBody.workerId
          taskId: requestBody.taskId
          leaseId: requestBody.leaseId
          fencingToken: requestBody.fencingToken
      - text: Reload the relay context of task {taskId} for worker {workerId} on lease {leaseId} with token {fencingToken}.
        slots:
          workerId: requestBody.workerId
          taskId: requestBody.taskId
          leaseId: requestBody.leaseId
          fencingToken: requestBody.fencingToken
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/rpa/v1/report'].post
  update:
    x-apievangelist-phrasing:
      intent: Report the outcome of an RPA send
      effect: write
      questions:
      - How does a worker report that a CONTROL or REAL send went through?
      - Does an accepted RPA report prove the email reached the inbox?
      instructions:
      - text: Report outcome {outcome} for task {taskId} on lease {leaseId}.
        slots:
          outcome: requestBody.outcome
          taskId: requestBody.taskId
          leaseId: requestBody.leaseId
      - text: Report operation {operationId} on task {taskId}, lease {leaseId}, as {outcome} with provider message id {providerMessageId}.
        slots:
          operationId: requestBody.operationId
          taskId: requestBody.taskId
          leaseId: requestBody.leaseId
          outcome: requestBody.outcome
          providerMessageId: requestBody.providerMessageId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/rpa/v1/profile-release'].post
  update:
    x-apievangelist-phrasing:
      intent: Acknowledge the RPA browser profile is closed
      effect: write
      questions:
      - How does a worker tell the server it closed the browser for a finished task?
      - Is acknowledging a browser profile release required?
      instructions:
      - text: Release the browser profile for finished task {taskId} as worker {workerId}, session closed {sessionClosed}.
        slots:
          taskId: requestBody.taskId
          workerId: requestBody.workerId
          sessionClosed: requestBody.sessionClosed
      - text: Acknowledge the browser was closed for task {taskId} on lease {leaseId}.
        slots:
          taskId: requestBody.taskId
          leaseId: requestBody.leaseId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/rpa/v1/return'].post
  update:
    x-apievangelist-phrasing:
      intent: Return an RPA task that did not send
      effect: write
      questions:
      - What should a worker do with a task it knows it didn't send?
      - Can a returned RPA task be retried within its attempt budget?
      instructions:
      - text: Return task {taskId} on lease {leaseId} as not sent, outcome {outcome}.
        slots:
          taskId: requestBody.taskId
          leaseId: requestBody.leaseId
          outcome: requestBody.outcome
      - text: Hand back unsent task {taskId} from worker {workerId} so it retries through the send gates.
        slots:
          taskId: requestBody.taskId
          workerId: requestBody.workerId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/rpa/v1/reconciliation'].post
  update:
    x-apievangelist-phrasing:
      intent: List a worker's unresolved RPA tasks
      effect: read
      questions:
      - Which of my RPA worker's tasks still have an uncertain outcome?
      - How many unresolved tasks per target does the reconciliation list return?
      instructions:
      - text: List unresolved tasks for worker {workerId}.
        slots:
          workerId: requestBody.workerId
      - text: Show the next unresolved tasks for worker {workerId} after {after}.
        slots:
          workerId: requestBody.workerId
          after: requestBody.after
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/rpa/v1/reconcile'].post
  update:
    x-apievangelist-phrasing:
      intent: Resolve an uncertain RPA send with evidence
      effect: write
      questions:
      - How do I settle whether an uncertain RPA send actually went out?
      - What evidence is needed to reconcile an RPA execution?
      instructions:
      - text: Reconcile uncertain task {taskId} using {evidenceKind} evidence {evidenceId}.
        slots:
          taskId: requestBody.taskId
          evidenceKind: requestBody.evidenceKind
          evidenceId: requestBody.evidenceId
      - text: Resolve task {taskId} on lease {leaseId} as {outcome} with proof {evidenceId}.
        slots:
          taskId: requestBody.taskId
          leaseId: requestBody.leaseId
          outcome: requestBody.outcome
          evidenceId: requestBody.evidenceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/rpa/v1/error'].post
  update:
    x-apievangelist-phrasing:
      intent: Report an RPA execution error
      effect: write
      questions:
      - How does a worker report an error during an RPA send?
      - Should a worker retry sending after reporting an uncertain error?
      instructions:
      - text: Report error {errorCode} at stage {stage} on task {taskId}.
        slots:
          errorCode: requestBody.errorCode
          stage: requestBody.stage
          taskId: requestBody.taskId
      - text: Log execution error {errorCode} for task {taskId}, send attempted {sendAttempted}.
        slots:
          errorCode: requestBody.errorCode
          taskId: requestBody.taskId
          sendAttempted: requestBody.sendAttempted
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/rpa/v1/placement'].post
  update:
    x-apievangelist-phrasing:
      intent: Attach seed-copy placement evidence to a task
      effect: write
      questions:
      - How do I record where a seed copy of an RPA send landed?
      - Does seed placement evidence prove inbox placement for the real recipient?
      instructions:
      - text: Attach seed placement {placement} to task {taskId} with evidence {evidenceId}.
        slots:
          placement: requestBody.placement
          taskId: requestBody.taskId
          evidenceId: requestBody.evidenceId
      - text: Record that the seed copy for task {taskId} landed in {placement}, measured at {measuredAt}.
        slots:
          taskId: requestBody.taskId
          placement: requestBody.placement
          measuredAt: requestBody.measuredAt
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/rpa/v1/attachments/{token}/{filename}'].get
  update:
    x-apievangelist-phrasing:
      intent: Download an RPA attachment by token and filename
      effect: read
      questions:
      - How does a worker download a signed task attachment with its original filename?
      - Can I fetch an RPA attachment using a URL that includes the file name?
      instructions:
      - text: Download the signed task attachment {filename} using token {token}.
        slots:
          filename: path.filename
          token: path.token
      - text: Fetch the lease-bound attachment from its filename URL.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/rpa/v1/attachments/{token}'].get
  update:
    x-apievangelist-phrasing:
      intent: Download an RPA attachment by legacy token URL
      effect: read
      questions:
      - Do older token-only RPA attachment URLs still work?
      - Can a worker download an attachment with just the signed token?
      instructions:
      - text: Download the attachment for signed token {token} via the legacy token-only URL.
        slots:
          token: path.token
      - text: Fetch a lease-bound attachment from an old token-only link.
      method: generated
      generated: '2026-10-01'