# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Testflinger Result API
  version: 1.0.0
extends: openapi/canonical-result-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: 7
- target: $.paths['/v1/result/{job_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a job's full results
      effect: read
      questions:
      - How do I see the output and exit status of every phase of a finished job?
      - Can I get a job's results including captured logs and serial output?
      instructions:
      - text: Show the full results for job {job_id}.
        slots:
          job_id: path.job_id
      - text: Get job {job_id}'s phase statuses together with its output and serial logs.
        slots:
          job_id: path.job_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/result/{job_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Post a job's results
      effect: write
      questions:
      - How does an agent report the final status of a job?
      - Can an agent attach device info when it posts a job result?
      instructions:
      - text: Post result status {status} for job {job_id}.
        slots:
          status: requestBody.status
          job_id: path.job_id
      - text: Record job {job_id} in state {job_state} from agent {agent_id}.
        slots:
          job_id: path.job_id
          job_state: requestBody.job_state
          agent_id: requestBody.agent_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/result/{job_id}/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a job's state and exit codes only
      effect: read
      questions:
      - Is there a lightweight way to check a job's state without pulling its logs?
      - Which phase of my job failed, by exit code?
      instructions:
      - text: Show only the state and phase exit codes of job {job_id}.
        slots:
          job_id: path.job_id
      - text: Check whether job {job_id} passed, without fetching logs.
        slots:
          job_id: path.job_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/result/{job_id}/artifact'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a job's artifact bundle
      effect: read
      questions:
      - Where do I download the artifacts my test job produced?
      - Can I fetch a job's output artifacts as a tarball?
      instructions:
      - text: Download the artifact bundle for job {job_id}.
        slots:
          job_id: path.job_id
      - text: Get the artifacts tarball produced by job {job_id}.
        slots:
          job_id: path.job_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/result/{job_id}/artifact'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a job's artifact bundle
      effect: write
      questions:
      - How does an agent upload artifacts produced by a test run?
      - Can artifacts be stored against a job after it runs?
      instructions:
      - text: Upload the artifact bundle for job {job_id}.
        slots:
          job_id: path.job_id
      - text: Store this artifacts tarball as the output of job {job_id}.
        slots:
          job_id: path.job_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/result/{job_id}/log/{log_type}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a job's logs by type
      effect: read
      questions:
      - Can I read a job's serial log separately from its output log?
      - What log fragments have been recorded for each phase of a job?
      instructions:
      - text: Get the {log_type} log for job {job_id}.
        slots:
          log_type: path.log_type
          job_id: path.job_id
      - text: Show job {job_id}'s {log_type} logs grouped by phase.
        slots:
          job_id: path.job_id
          log_type: path.log_type
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/result/{job_id}/log/{log_type}'].post
  update:
    x-apievangelist-phrasing:
      intent: Stream a log fragment for a job
      effect: write
      questions:
      - How does an agent stream log data for a running job?
      - In what order must log fragments be numbered?
      instructions:
      - text: 'Post fragment {fragment_number} of the {log_type} log for job {job_id} in phase {phase}: {log_data} at {timestamp}.'
        slots:
          fragment_number: requestBody.fragment_number
          log_type: path.log_type
          job_id: path.job_id
          phase: requestBody.phase
          log_data: requestBody.log_data
          timestamp: requestBody.timestamp
      - text: Append {log_data} to job {job_id}'s {log_type} log as fragment {fragment_number}, phase {phase}, time {timestamp}.
        slots:
          log_data: requestBody.log_data
          job_id: path.job_id
          log_type: path.log_type
          fragment_number: requestBody.fragment_number
          phase: requestBody.phase
          timestamp: requestBody.timestamp
      method: generated
      generated: '2026-10-01'