API Evangelist conversational phrasing for Testflinger Job API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Testflinger Job API
  version: 1.0.0
extends: openapi/canonical-job-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: 9
- target: $.paths['/v1/job'].get
  update:
    x-apievangelist-phrasing:
      intent: Pick up the next job from a queue
      effect: read
      questions:
      - How does an agent ask the server for the next job on its queues?
      - What does an agent get back when no job is waiting on its queues?
      instructions:
      - text: Request the next available job for my agent's queues.
      - text: Fetch a job to run from the queues this agent supports.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/job'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit a test job
      effect: write
      questions:
      - How do I submit a test job to a Testflinger queue?
      - Can I set a priority and a global timeout when I submit a job?
      - Is it possible to get webhook updates as my job changes status?
      instructions:
      - text: Submit a job to queue {job_queue}.
        slots:
          job_queue: requestBody.job_queue
      - text: Queue job {name} on {job_queue} with priority {job_priority}.
        slots:
          name: requestBody.name
          job_queue: requestBody.job_queue
          job_priority: requestBody.job_priority
      - text: Submit a job to {job_queue} tagged {tags} and post status to {job_status_webhook}.
        slots:
          job_queue: requestBody.job_queue
          tags: requestBody.tags
          job_status_webhook: requestBody.job_status_webhook
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/job/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search jobs by tag
      effect: read
      questions:
      - Can I find all jobs carrying a certain tag?
      - Which of my tagged jobs are still running?
      instructions:
      - text: Search for jobs tagged {tags}.
        slots:
          tags: query.tags
      - text: Find jobs matching {match} of tags {tags} in state {state}.
        slots:
          match: query.match
          tags: query.tags
          state: query.state
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/job/{job_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a job's definition
      effect: read
      questions:
      - What did I submit as the definition of a job that already ran?
      - Can I see the provision and test data of a past job?
      instructions:
      - text: Show the job definition for {job_id}.
        slots:
          job_id: path.job_id
      - text: Get the submitted JSON of job {job_id}.
        slots:
          job_id: path.job_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/job/{job_id}/action'].post
  update:
    x-apievangelist-phrasing:
      intent: Take an action on a job
      effect: write
      questions:
      - How do I change the status of a job that is queued or running?
      - Which job actions does the server accept for a job ID?
      instructions:
      - text: Apply action {action} to job {job_id}.
        slots:
          action: requestBody.action
          job_id: path.job_id
      - text: Send the {action} action to job {job_id}.
        slots:
          action: requestBody.action
          job_id: path.job_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/job/{job_id}/events'].post
  update:
    x-apievangelist-phrasing:
      intent: Forward job status events to a webhook
      effect: write
      questions:
      - How does an agent push job status events to the webhook the user registered?
      - Can job events be forwarded to the configured status webhook?
      instructions:
      - text: Post events {events} for job {job_id} to webhook {job_status_webhook}.
        slots:
          events: requestBody.events
          job_id: path.job_id
          job_status_webhook: requestBody.job_status_webhook
      - text: Forward job {job_id} status updates to {job_status_webhook}.
        slots:
          job_id: path.job_id
          job_status_webhook: requestBody.job_status_webhook
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/job/{job_id}/position'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a job's place in the queue
      effect: read
      questions:
      - How many jobs are ahead of mine in the queue?
      - Has my queued job moved up yet?
      instructions:
      - text: Show the queue position of job {job_id}.
        slots:
          job_id: path.job_id
      - text: Tell me where job {job_id} sits in its queue.
        slots:
          job_id: path.job_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/job/{job_id}/attachments'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a job's attachments
      effect: read
      questions:
      - Where can an agent download the files attached to a job?
      - Can I retrieve the attachment tarball I uploaded with a job?
      instructions:
      - text: Download the attachments bundle for job {job_id}.
        slots:
          job_id: path.job_id
      - text: Get the attachment tarball of job {job_id}.
        slots:
          job_id: path.job_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/job/{job_id}/attachments'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a job's attachments
      effect: write
      questions:
      - How do I attach local files to a job I submitted?
      - Can I send an attachment bundle along with a test job?
      instructions:
      - text: Upload the attachments bundle for job {job_id}.
        slots:
          job_id: path.job_id
      - text: Attach this tarball to job {job_id}.
        slots:
          job_id: path.job_id
      method: generated
      generated: '2026-10-01'