# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for CloudBees Unify API (Beta) Runs API
  version: 1.0.0
extends: openapi/cloudbees-runs-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: 13
- target: $.paths['/v4/components/{componentId}/runs'].post
  update:
    x-apievangelist-phrasing:
      intent: Record a CI/CD run for a component
      effect: write
      questions:
      - How do I report a pipeline run from an external CI tool?
      - Which CI/CD tools can a run be recorded from?
      - What triggers can a recorded run have, like push or pull request?
      instructions:
      - text: Record a run of workflow {workflowName} for component {componentId} on ref {scmRef} at commit {commitSha}.
        slots:
          workflowName: requestBody.workflowName
          componentId: path.componentId
          scmRef: requestBody.scmRef
          commitSha: requestBody.commitSha
      - text: Create a run for component {componentId} with status {status}, triggered by {actorName}, from {url}.
        slots:
          componentId: path.componentId
          status: requestBody.status
          actorName: requestBody.actorName
          url: requestBody.url
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v4/components/{componentId}/runs/{run.id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a run's status
      effect: write
      questions:
      - How do I mark a run as finished or failed after it started?
      - Can I add a failure message to a run I already recorded?
      instructions:
      - text: Update run {runId} of component {componentId} to status {status}.
        slots:
          runId: path.run.id
          componentId: path.componentId
          status: requestBody.status
      - text: Set the end time of run {runId} in component {componentId} to {endedAt}.
        slots:
          runId: path.run.id
          componentId: path.componentId
          endedAt: requestBody.endedAt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v4/components/{componentId}/runs/{runId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a run
      effect: read
      questions:
      - How can I look up a single run and its status?
      - Who triggered a particular run and at which commit?
      instructions:
      - text: Get run {runId} of component {componentId}.
        slots:
          runId: path.runId
          componentId: path.componentId
      - text: Show the status and trigger of run {runId} in component {componentId}.
        slots:
          runId: path.runId
          componentId: path.componentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v4/components/{componentId}/runs/{runId}/artifacts'].get
  update:
    x-apievangelist-phrasing:
      intent: List build artifacts on a run
      effect: read
      questions:
      - What build artifacts were produced by a run?
      - Can I see the artifacts already attached to a run?
      instructions:
      - text: List the artifacts of run {runId} in component {componentId}.
        slots:
          runId: path.runId
          componentId: path.componentId
      - text: Show build artifacts attached to run {runId} for component {componentId}.
        slots:
          runId: path.runId
          componentId: path.componentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v4/components/{componentId}/runs/{runId}/artifacts'].post
  update:
    x-apievangelist-phrasing:
      intent: Attach build artifacts to a run
      effect: write
      questions:
      - How do I attach build artifacts, like container images, to a run?
      - Does attaching artifacts return IDs I can reference later?
      instructions:
      - text: Attach build artifacts to run {runId} of component {componentId}.
        slots:
          runId: path.runId
          componentId: path.componentId
      - text: Add artifacts {artifacts} to run {runId} in component {componentId}.
        slots:
          artifacts: requestBody.artifacts
          runId: path.runId
          componentId: path.componentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v4/components/{componentId}/runs/{runId}/deployments'].get
  update:
    x-apievangelist-phrasing:
      intent: List deployments recorded on a run
      effect: read
      questions:
      - Which deployments are associated with a run?
      - Where was a run's output deployed?
      instructions:
      - text: List deployments for run {runId} of component {componentId}.
        slots:
          runId: path.runId
          componentId: path.componentId
      - text: Show the deployments attached to run {runId} in component {componentId}.
        slots:
          runId: path.runId
          componentId: path.componentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v4/components/{componentId}/runs/{runId}/deployments'].post
  update:
    x-apievangelist-phrasing:
      intent: Record a deployment on a run
      effect: write
      questions:
      - How do I record that a run deployed artifacts to production?
      - Can I link existing build artifacts to a deployment in an environment?
      instructions:
      - text: Record a deployment of run {runId} in component {componentId} to environment {environment}.
        slots:
          runId: path.runId
          componentId: path.componentId
          environment: requestBody.environment
      - text: Attach deployment of artifacts {artifactReferences} to {environment} for run {runId}, component {componentId}.
        slots:
          artifactReferences: requestBody.artifactReferences
          environment: requestBody.environment
          runId: path.runId
          componentId: path.componentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v4/components/{componentId}/runs/{runId}/evidences'].get
  update:
    x-apievangelist-phrasing:
      intent: List evidence attached to a run
      effect: read
      questions:
      - What compliance evidence has been attached to a run?
      - Can I review the evidence entries recorded for a run?
      instructions:
      - text: List the evidences for run {runId} of component {componentId}.
        slots:
          runId: path.runId
          componentId: path.componentId
      - text: Show evidence attached to run {runId} in component {componentId}.
        slots:
          runId: path.runId
          componentId: path.componentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v4/components/{componentId}/runs/{runId}/evidences'].post
  update:
    x-apievangelist-phrasing:
      intent: Attach evidence to a run
      effect: write
      questions:
      - How do I attach evidence, such as approvals or checks, to a run?
      - Can I add several evidence entries to a run at once?
      instructions:
      - text: Attach evidence to run {runId} of component {componentId}.
        slots:
          runId: path.runId
          componentId: path.componentId
      - text: Add evidences {evidences} to run {runId} in component {componentId}.
        slots:
          evidences: requestBody.evidences
          runId: path.runId
          componentId: path.componentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v4/components/{componentId}/runs/{runId}/security-results'].get
  update:
    x-apievangelist-phrasing:
      intent: List security findings for a run
      effect: read
      questions:
      - What security vulnerabilities were found in a run's scans?
      - Can I see the processed security findings for a build?
      instructions:
      - text: List the security findings for run {runId} of component {componentId}.
        slots:
          runId: path.runId
          componentId: path.componentId
      - text: Show processed scan results for run {runId} in component {componentId}.
        slots:
          runId: path.runId
          componentId: path.componentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v4/components/{componentId}/runs/{runId}/security-results'].post
  update:
    x-apievangelist-phrasing:
      intent: Attach security scan results to a run
      effect: write
      questions:
      - How do I upload security scan reports for a run?
      - Can I attach several scanner reports to one run?
      instructions:
      - text: Attach security scan results to run {runId} of component {componentId}.
        slots:
          runId: path.runId
          componentId: path.componentId
      - text: Upload scan reports {securityResults} to run {runId} in component {componentId}.
        slots:
          securityResults: requestBody.securityResults
          runId: path.runId
          componentId: path.componentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v4/components/{componentId}/runs/{runId}/test-results'].get
  update:
    x-apievangelist-phrasing:
      intent: Get download links for a run's test results
      effect: read
      questions:
      - How do I download the test results files uploaded for a run?
      - Are test result files returned as download links?
      instructions:
      - text: Get download links for the test results of run {runId}, component {componentId}.
        slots:
          runId: path.runId
          componentId: path.componentId
      - text: List test result files for run {runId} in component {componentId}.
        slots:
          runId: path.runId
          componentId: path.componentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v4/components/{componentId}/runs/{runId}/test-results'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload test results to a run
      effect: write
      questions:
      - How do I upload test results for a run?
      - Why don't uploaded test results show up right away after a 202 response?
      instructions:
      - text: Upload test results to run {runId} of component {componentId}.
        slots:
          runId: path.runId
          componentId: path.componentId
      - text: Attach the test report file to run {runId} in component {componentId}.
        slots:
          runId: path.runId
          componentId: path.componentId
      method: generated
      generated: '2026-09-26'