# 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 Tasks API
  version: 1.0.0
extends: openapi/live-direct-marketing-online-tasks-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: 41
- target: $.paths['/api/tasks'].get
  update:
    x-apievangelist-phrasing:
      intent: List tasks with status and method filters
      effect: read
      questions:
      - Which of my tasks are currently active?
      - Can I filter my task list down to only site-scoring tasks?
      - What tasks have I created so far, page by page?
      instructions:
      - text: List my tasks with status {status}.
        slots:
          status: query.status
      - text: Show page {page} of my tasks for method {methodId}, {pageSize} per page.
        slots:
          page: query.page
          methodId: query.methodId
          pageSize: query.pageSize
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new processing task
      effect: write
      questions:
      - How do I set up a site-scoring task that pulls its companies from a company list?
      - Can I create an email validation task that sources contacts from a contact list?
      - Is it possible to delay a new task so it waits until a set date before running?
      instructions:
      - text: Create a scoring task with method {methodId} named {methodName} that scores companies from list {companyListId}.
        slots:
          methodId: requestBody.methodId
          methodName: requestBody.methodName
          companyListId: requestBody.companyListId
      - text: Create a {methodName} task (method {methodId}) over contact list {contactListId} that waits until {resumeAt}.
        slots:
          methodName: requestBody.methodName
          methodId: requestBody.methodId
          contactListId: requestBody.contactListId
          resumeAt: requestBody.resumeAt
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a task's details and progress
      effect: read
      questions:
      - How far along is my task — how many items has it processed out of the total?
      - Where can I see the full record for one task?
      instructions:
      - text: Show me task {id}.
        slots:
          id: path.id
      - text: Fetch the details and progress counters of task {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a task
      effect: destructive
      questions:
      - How do I permanently remove a task I no longer need?
      - Can I delete a task outright instead of just stopping it?
      instructions:
      - text: Delete task {id}.
        slots:
          id: path.id
      - text: Remove task {id} from my workspace for good.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a task's description, config or schedule
      effect: write
      questions:
      - Can I change the description or source list on a task I already created?
      - How do I push back the date an existing task resumes at?
      - Is it possible to raise the parallel stream count of an existing task?
      instructions:
      - text: Change the description of task {id} to {description}.
        slots:
          id: path.id
          description: requestBody.description
      - text: Reschedule task {id} to resume at {resumeAt} with {streamCount} parallel streams.
        slots:
          id: path.id
          resumeAt: requestBody.resumeAt
          streamCount: requestBody.streamCount
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/branches'].get
  update:
    x-apievangelist-phrasing:
      intent: List a task's sub-sequence branches
      effect: read
      questions:
      - What sub-sequence branches hang off my task?
      - Which branches have been created under a given task?
      instructions:
      - text: List the branches of task {id}.
        slots:
          id: path.id
      - text: Show every sub-sequence branch configured under task {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/branches'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a sub-sequence branch off a task
      effect: write
      questions:
      - Can I branch contacts off a task into an ICP review when a certain event happens?
      - How do I add a conditional sub-sequence to an existing task?
      instructions:
      - text: Create a {methodName} branch (method {methodId}) on task {id} triggered by {branchTrigger}.
        slots:
          methodName: requestBody.methodName
          methodId: requestBody.methodId
          id: path.id
          branchTrigger: requestBody.branchTrigger
      - text: Add a branch to task {id} using method {methodId} ({methodName}) that fires on {branchTrigger} and draws from list {contactListId}.
        slots:
          id: path.id
          methodId: requestBody.methodId
          methodName: requestBody.methodName
          branchTrigger: requestBody.branchTrigger
          contactListId: requestBody.contactListId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/branches/{branchId}/enroll'].post
  update:
    x-apievangelist-phrasing:
      intent: Enroll contacts into a task branch
      effect: write
      questions:
      - How do I manually put specific contacts into a task's branch?
      - Can I push a handful of contacts straight into a sub-sequence branch?
      instructions:
      - text: Enroll contacts {contactIds} into branch {branchId} of task {id}.
        slots:
          contactIds: requestBody.contactIds
          branchId: path.branchId
          id: path.id
      - text: Add these contacts {contactIds} to task branch {branchId}.
        slots:
          contactIds: requestBody.contactIds
          branchId: path.branchId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/items'].get
  update:
    x-apievangelist-phrasing:
      intent: List the items a task has processed
      effect: read
      questions:
      - Which individual items has my task worked through, and with what status?
      - Can I page through only the failed items of a task?
      instructions:
      - text: List items of task {id} with status {status}.
        slots:
          id: path.id
          status: query.status
      - text: Show page {page} of task {id}'s items, {pageSize} per page.
        slots:
          page: query.page
          id: path.id
          pageSize: query.pageSize
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/items/{itemId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one item from a task
      effect: read
      questions:
      - What happened to one particular item inside my task?
      - Where can I inspect a single processed item of a task?
      instructions:
      - text: Show item {itemId} of task {id}.
        slots:
          itemId: path.itemId
          id: path.id
      - text: Fetch the result for task item {itemId} in task {id}.
        slots:
          itemId: path.itemId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get aggregate stats for a task
      effect: read
      questions:
      - What are the overall counts for my task — done, pending, errored?
      - Can I see a summary of totals for one task?
      instructions:
      - text: Give me the aggregate stats for task {id}.
        slots:
          id: path.id
      - text: Summarize item totals by status for task {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/errors'].get
  update:
    x-apievangelist-phrasing:
      intent: List errors from a task run
      effect: read
      questions:
      - Why did my task run hit errors?
      - What error messages did a task produce while running?
      instructions:
      - text: List the errors encountered by task {id}.
        slots:
          id: path.id
      - text: Show me what went wrong during task {id}'s run.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/start'].post
  update:
    x-apievangelist-phrasing:
      intent: Start or resume a task
      effect: write
      questions:
      - How do I kick off a task so it begins processing its list?
      - Can I do a trial run that only processes a few items and then pauses?
      instructions:
      - text: Start task {id}.
        slots:
          id: path.id
      - text: Run task {id} as a trial on at most {limit} items, then pause.
        slots:
          id: path.id
          limit: requestBody.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/pause'].post
  update:
    x-apievangelist-phrasing:
      intent: Pause a running task
      effect: write
      questions:
      - Can I temporarily halt a task that is running right now?
      - What do I call to put an active task on hold?
      instructions:
      - text: Pause task {id}.
        slots:
          id: path.id
      - text: Put running task {id} on hold for now.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/stop'].post
  update:
    x-apievangelist-phrasing:
      intent: Stop a task and mark it done
      effect: destructive
      questions:
      - How do I end a task for good and mark it as done?
      - Can I finish a task early without deleting it?
      instructions:
      - text: Stop task {id} and mark it as done.
        slots:
          id: path.id
      - text: End task {id} now.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/restart'].post
  update:
    x-apievangelist-phrasing:
      intent: Retry a task's errored items
      effect: write
      questions:
      - How do I retry only the items that errored in a task without redoing scored ones?
      - Will restarting a task wipe out results that were already scored?
      instructions:
      - text: Restart task {id} so its errored items are retried.
        slots:
          id: path.id
      - text: Reset the ERROR items of task {id} to pending and reactivate it.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/analytics'].get
  update:
    x-apievangelist-phrasing:
      intent: Get open, click and reply rates for a task
      effect: read
      questions:
      - What open, click and reply rates did my mailing task get?
      - How well did a task perform in terms of engagement?
      instructions:
      - text: Show open, click and reply analytics for task {id}.
        slots:
          id: path.id
      - text: Report the engagement rates of task {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/monitor'].get
  update:
    x-apievangelist-phrasing:
      intent: Watch a running task in real time
      effect: read
      questions:
      - What is my running task doing at this moment?
      - Is there a live monitoring view for a task in progress?
      instructions:
      - text: Show the real-time monitor for task {id}.
        slots:
          id: path.id
      - text: Get live monitoring data for running task {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/report.csv'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a CSV report of task items
      effect: read
      questions:
      - Can I export all of a task's items to a spreadsheet?
      - How do I get a CSV of everything a task processed?
      instructions:
      - text: Download the CSV item report for task {id}.
        slots:
          id: path.id
      - text: Export all items of task {id} as a CSV file.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/circuit-breaker'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a task's circuit-breaker state
      effect: read
      questions:
      - Has the circuit breaker tripped on my task?
      - Why did a task stop itself after too many errors?
      instructions:
      - text: Show the circuit-breaker state for task {id}.
        slots:
          id: path.id
      - text: Check whether task {id}'s circuit breaker is open.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/circuit-breaker/reset'].post
  update:
    x-apievangelist-phrasing:
      intent: Reset a tripped circuit breaker
      effect: write
      questions:
      - How do I clear a tripped circuit breaker so my task can carry on?
      - Can I reset the breaker after fixing what caused the errors?
      instructions:
      - text: Reset the circuit breaker on task {id}.
        slots:
          id: path.id
      - text: Clear the tripped breaker for task {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/steps'].get
  update:
    x-apievangelist-phrasing:
      intent: List a task's pipeline steps
      effect: read
      questions:
      - Which pipeline steps are configured on my scoring task?
      - In what order will a task run its steps?
      instructions:
      - text: List the pipeline steps of task {id}.
        slots:
          id: path.id
      - text: Show the configured step pipeline for task {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/steps'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a pipeline step to a task
      effect: write
      questions:
      - Can I add a site availability check or email extraction step to a scoring task?
      - How do I route companies to another list when a pipeline step fails?
      instructions:
      - text: Add a {type} step to task {id}.
        slots:
          type: requestBody.type
          id: path.id
      - text: Add a {type} step named {name} to task {id} that moves failures to list {onFailTarget}.
        slots:
          type: requestBody.type
          name: requestBody.name
          id: path.id
          onFailTarget: requestBody.onFailTarget
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/steps/reorder'].put
  update:
    x-apievangelist-phrasing:
      intent: Reorder a task's pipeline steps
      effect: write
      questions:
      - Can I change the order in which a task runs its pipeline steps?
      - How do I move the keyword step ahead of the AI content step?
      instructions:
      - text: Reorder the steps of task {id} to {stepIds}.
        slots:
          id: path.id
          stepIds: requestBody.stepIds
      - text: Set the pipeline order for task {id} as {stepIds}.
        slots:
          id: path.id
          stepIds: requestBody.stepIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/steps/{stepId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a pipeline step from a task
      effect: destructive
      questions:
      - How do I drop a step from a task's pipeline?
      - Can I remove the phone extraction step from my scoring task?
      instructions:
      - text: Delete step {stepId} from task {id}.
        slots:
          stepId: path.stepId
          id: path.id
      - text: Remove pipeline step {stepId} of task {id}.
        slots:
          stepId: path.stepId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/steps/{stepId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a single pipeline step
      effect: write
      questions:
      - Can I disable one pipeline step without deleting it?
      - How do I change what happens when a particular step errors?
      instructions:
      - text: Set enabled to {enabled} on step {stepId} of task {id}.
        slots:
          enabled: requestBody.enabled
          stepId: path.stepId
          id: path.id
      - text: Change step {stepId} in task {id} so errors do {onError}.
        slots:
          stepId: path.stepId
          id: path.id
          onError: requestBody.onError
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/scoring-results'].get
  update:
    x-apievangelist-phrasing:
      intent: List a task's company scoring results
      effect: read
      questions:
      - What scores did each company get in my site-scoring task?
      - Can I see only the scoring results flagged as contradictory?
      - Which scored companies match a search term or reason code?
      instructions:
      - text: List scoring results of task {id} with status {status}.
        slots:
          id: path.id
          status: query.status
      - text: Show contradictory scoring results for task {id}.
        slots:
          id: path.id
      - text: Search task {id}'s scoring results for {search}, latest per company only.
        slots:
          id: path.id
          search: query.search
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/scoring-stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get aggregate scoring stats for a task
      effect: read
      questions:
      - How many companies scored above threshold versus below in my task?
      - What is the breakdown of scoring outcomes for a task?
      instructions:
      - text: Show scoring statistics for task {id}.
        slots:
          id: path.id
      - text: Summarize the scoring outcome counts for task {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/scoring-results/{resultId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one scoring result
      effect: destructive
      questions:
      - Can I remove a single company's scoring card from a task?
      - How do I get rid of one bad scoring result?
      instructions:
      - text: Delete scoring result {resultId} from task {id}.
        slots:
          resultId: path.resultId
          id: path.id
      - text: Remove scoring card {resultId} in task {id}.
        slots:
          resultId: path.resultId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/scoring-results/retry'].post
  update:
    x-apievangelist-phrasing:
      intent: Retry a selection of scoring results
      effect: write
      questions:
      - Can I re-score companies that came back with errors or below threshold?
      - Is there a way to preview how many results a retry would pick before running it?
      - Will dead domains be retried unless I explicitly include them?
      instructions:
      - text: Retry scoring results of task {id} with statuses {statuses}.
        slots:
          id: path.id
          statuses: requestBody.statuses
      - text: Re-score companies {companyIds} in task {id}.
        slots:
          companyIds: requestBody.companyIds
          id: path.id
      - text: Preview how many results of task {id} processed after {processedAfter} a retry would select.
        slots:
          id: path.id
          processedAfter: requestBody.processedAfter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/scoring-results/{resultId}/events'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the step journal for a scoring card
      effect: read
      questions:
      - What steps ran on one company's scoring card, and in what order?
      - Did a scoring card get interrupted or resumed after a restart?
      instructions:
      - text: Show the step events for scoring result {resultId} in task {id}.
        slots:
          resultId: path.resultId
          id: path.id
      - text: Page {page} of the step journal for card {resultId} in task {id}, {pageSize} per page.
        slots:
          page: query.page
          resultId: path.resultId
          id: path.id
          pageSize: query.pageSize
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/scoring-results.csv'].get
  update:
    x-apievangelist-phrasing:
      intent: Download scoring results as CSV
      effect: read
      questions:
      - Can I export my scored companies to a CSV file?
      - How do I download only the scoring results with a given status as a spreadsheet?
      instructions:
      - text: Download scoring results of task {id} with status {status} as CSV.
        slots:
          id: path.id
          status: query.status
      - text: Export task {id}'s scoring results matching {search} to a CSV.
        slots:
          id: path.id
          search: query.search
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/error-settings'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a task's error-handling settings
      effect: read
      questions:
      - At what error rate will my task trip and stop?
      - What consecutive-error limit is set on a task?
      instructions:
      - text: Show the error-handling settings for task {id}.
        slots:
          id: path.id
      - text: Get the error thresholds configured on task {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/error-settings'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change a task's error thresholds
      effect: write
      questions:
      - Can I make a task tolerate more consecutive errors before it trips?
      - How do I set the error-rate percentage and window that halts a task?
      instructions:
      - text: Set the consecutive error limit of task {id} to {consecutiveErrorLimit}.
        slots:
          id: path.id
          consecutiveErrorLimit: requestBody.consecutiveErrorLimit
      - text: Trip task {id} at {errorRatePercent}% errors over {errorRateWindowMin} minutes.
        slots:
          id: path.id
          errorRatePercent: requestBody.errorRatePercent
          errorRateWindowMin: requestBody.errorRateWindowMin
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/memory'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a task's AI memory instructions
      effect: read
      questions:
      - What standing instructions has the AI been given for this task?
      - Where can I read the AI memory attached to a task?
      instructions:
      - text: Show the AI memory for task {id}.
        slots:
          id: path.id
      - text: Read the AI memory instructions saved on task {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/memory'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a task's AI memory instructions
      effect: write
      questions:
      - Can I give the AI on a task standing instructions it should remember?
      - How do I rewrite the memory the AI uses for one task?
      instructions:
      - text: Set the AI memory of task {id} to {memory}.
        slots:
          id: path.id
          memory: requestBody.memory
      - text: 'Tell the AI on task {id} to remember: {memory}.'
        slots:
          id: path.id
          memory: requestBody.memory
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/ai-settings'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a task's AI provider and model
      effect: read
      questions:
      - Which AI provider and models is my task using?
      - What model settings are configured on a task?
      instructions:
      - text: Show the AI provider and model settings for task {id}.
        slots:
          id: path.id
      - text: Tell me which models task {id} runs on.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/ai-settings'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change a task's AI provider and model
      effect: write
      questions:
      - Can I switch the AI provider a task uses?
      - How do I change which models a task runs on?
      instructions:
      - text: Switch task {id} to AI provider {provider}.
        slots:
          id: path.id
          provider: requestBody.provider
      - text: Set task {id} to use provider {provider} with models {models}.
        slots:
          id: path.id
          provider: requestBody.provider
          models: requestBody.models
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/cron'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a task's cron schedule settings
      effect: read
      questions:
      - Is my task set to run on a schedule, and how often?
      - What batch size and interval does a task's cron use?
      instructions:
      - text: Show the cron settings for task {id}.
        slots:
          id: path.id
      - text: Get the scheduled-run interval and batch size of task {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/cron'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change a task's cron schedule
      effect: write
      questions:
      - Can I make a task run automatically every few minutes?
      - How do I change the batch size a scheduled task processes each run?
      instructions:
      - text: Enable cron on task {id} every {cronInterval} minutes.
        slots:
          id: path.id
          cronInterval: requestBody.cronInterval
      - text: Set the cron batch size of task {id} to {batchSize}.
        slots:
          id: path.id
          batchSize: requestBody.batchSize
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/tasks/{id}/cron/trigger'].post
  update:
    x-apievangelist-phrasing:
      intent: Trigger a task's cron run now
      effect: write
      questions:
      - Can I fire a scheduled task's next batch right away instead of waiting?
      - How do I manually kick off one cron run of a task?
      instructions:
      - text: Trigger a cron run of task {id} now.
        slots:
          id: path.id
      - text: Run the next scheduled batch of task {id} immediately.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'