# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for DaaS IQ Jobs API
  version: 1.0.0
extends: openapi/controlup-jobs-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 8
- target: $.paths['/jobs/{jobId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a background job's full record
      effect: read
      questions:
      - Why did a background job fail — what are its error details?
      - Can I see a job's full record including current step and progress?
      instructions:
      - text: Show job {jobId}.
        slots:
          jobId: path.jobId
      - text: Get the full record and error details of job {jobId}.
        slots:
          jobId: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/{jobId}/parameters'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a job's input parameters
      effect: read
      questions:
      - What inputs was a background job created with?
      - Can I see the raw parameters a job was started with?
      instructions:
      - text: Show the input parameters of job {jobId}.
        slots:
          jobId: path.jobId
      - text: Get the raw request parameters used for job {jobId}.
        slots:
          jobId: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs'].get
  update:
    x-apievangelist-phrasing:
      intent: List background jobs
      effect: read
      questions:
      - Which background jobs are running in my organization?
      - Can I include system jobs when listing jobs?
      instructions:
      - text: List my background jobs.
      - text: List jobs matching {filter}, including system jobs.
        slots:
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/{jobId}/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Poll a job's status
      effect: read
      questions:
      - What's the cheapest way to poll whether a job is finished?
      - Has cancellation been requested for a running job?
      instructions:
      - text: Check the status of job {jobId}.
        slots:
          jobId: path.jobId
      - text: Poll job {jobId} for progress.
        slots:
          jobId: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/{jobId}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a background job
      effect: destructive
      questions:
      - Can I stop a running background job?
      - Can admins cancel jobs that other users started?
      instructions:
      - text: Cancel job {jobId}.
        slots:
          jobId: path.jobId
      - text: Request cancellation of running job {jobId}.
        slots:
          jobId: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/{jobId}/retry'].post
  update:
    x-apievangelist-phrasing:
      intent: Retry a failed job
      effect: write
      questions:
      - Can I rerun a failed job with the same parameters?
      - Does retrying a job keep the original failed one?
      instructions:
      - text: Retry failed job {jobId}.
        slots:
          jobId: path.jobId
      - text: Create a new retry of job {jobId}.
        slots:
          jobId: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/{jobId}/logs'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a job's structured logs
      effect: read
      questions:
      - Can I tail a job's log entries incrementally with a cursor?
      - What log entries has a job written so far, as structured JSON?
      instructions:
      - text: Get the logs of job {jobId}.
        slots:
          jobId: path.jobId
      - text: Get job {jobId} log entries after cursor {after}.
        slots:
          jobId: path.jobId
          after: query.after
      method: generated
      generated: '2026-09-26'
- target: $.paths['/jobs/{jobId}/logs/transcript'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a job's logs as text
      effect: read
      questions:
      - Can I download a job's logs as plain text?
      - Is there a readable text transcript of a job's log?
      instructions:
      - text: Download the log transcript for job {jobId}.
        slots:
          jobId: path.jobId
      - text: Give me job {jobId}'s logs as plain text, up to {limit} lines.
        slots:
          jobId: path.jobId
          limit: query.limit
      method: generated
      generated: '2026-09-26'