# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Pipeline Management API v2 Pipeline Versions API
  version: 1.0.0
extends: openapi/here-pipeline-versions-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: 17
- target: $.paths['/v2/pipelines/{pipelineId}/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: List the versions of a pipeline
      effect: read
      questions:
      - How do I see every version defined for one of my HERE data pipelines?
      - Can I get verbose details when listing a pipeline's versions?
      instructions:
      - text: List all versions of pipeline {pipelineId}.
        slots:
          pipelineId: path.pipelineId
      - text: Show the versions of pipeline {pipelineId} with verbose output {verbose}.
        slots:
          pipelineId: path.pipelineId
          verbose: query.verbose
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/pipelines/{pipelineId}/versions'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new version of a pipeline
      effect: write
      questions:
      - How do I define a new pipeline version with its template and input and output catalogs?
      - What do I need to supply to create a runnable version of a pipeline?
      instructions:
      - text: Create version {name} of pipeline {pipelineId} from template {pipelineTemplateId}, reading {inputCatalogs} and writing to {outputCatalogHRN}.
        slots:
          name: requestBody.name
          pipelineId: path.pipelineId
          pipelineTemplateId: requestBody.pipelineTemplateId
          inputCatalogs: requestBody.inputCatalogs
          outputCatalogHRN: requestBody.outputCatalogHRN
      - text: Add a new pipeline version {name} to {pipelineId} with billing tag {billingTag}.
        slots:
          name: requestBody.name
          pipelineId: path.pipelineId
          billingTag: requestBody.billingTag
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/pipelines/{pipelineId}/versions/{versionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get details of a pipeline version
      effect: read
      questions:
      - What state is a particular pipeline version in right now?
      - Where can I see the template and catalogs a specific pipeline version uses?
      instructions:
      - text: Get the details of version {versionId} of pipeline {pipelineId}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
      - text: Show pipeline version {versionId} of {pipelineId}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/pipelines/{pipelineId}/versions/{versionId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a pipeline version
      effect: destructive
      questions:
      - How do I delete a pipeline version I no longer need?
      - Why would deleting a pipeline version fail if it isn't in the Ready state?
      instructions:
      - text: Delete version {versionId} of pipeline {pipelineId}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
      - text: Remove the ready pipeline version {versionId} from pipeline {pipelineId}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/pipelines/{pipelineId}/versions/{versionId}/jobs'].get
  update:
    x-apievangelist-phrasing:
      intent: List jobs run by a pipeline version
      effect: read
      questions:
      - Which jobs has a pipeline version run, and is one running right now?
      - How can I see the job history of a specific pipeline version?
      instructions:
      - text: List the jobs of pipeline version {versionId} in pipeline {pipelineId}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
      - text: Show the running and past jobs for version {versionId} of {pipelineId}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/pipelines/{pipelineId}/versions/{versionId}/logging-configuration'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a pipeline version's logging configuration
      effect: read
      questions:
      - What log level is currently configured for my pipeline version?
      - How can I check the logging settings on a pipeline version?
      instructions:
      - text: Get the logging configuration of version {versionId} of pipeline {pipelineId}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
      - text: Show the current log settings for version {versionId} of pipeline {pipelineId}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/pipelines/{pipelineId}/versions/{versionId}/logging-configuration'].put
  update:
    x-apievangelist-phrasing:
      intent: Change a pipeline version's logging configuration
      effect: write
      questions:
      - Can I change the log level of a pipeline version while a job is running?
      - How do I turn up logging for a pipeline version to debug it?
      instructions:
      - text: Set the logging configuration of version {versionId} in pipeline {pipelineId} to {configuration}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
          configuration: requestBody.configuration
      - text: Update the log levels for version {versionId} of pipeline {pipelineId} to {configuration}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
          configuration: requestBody.configuration
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/pipelines/{pipelineId}/versions/{versionId}/operations'].get
  update:
    x-apievangelist-phrasing:
      intent: List operations on a pipeline version
      effect: read
      questions:
      - What activate, pause or cancel operations are pending on a pipeline version?
      - How do I see the history of operations performed on a pipeline version?
      instructions:
      - text: List all operations on version {versionId} of pipeline {pipelineId}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
      - text: Show completed and pending operations for version {versionId} of {pipelineId}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/pipelines/{pipelineId}/versions/{versionId}/operations/activate'].post
  update:
    x-apievangelist-phrasing:
      intent: Activate a pipeline version
      effect: write
      questions:
      - How do I activate a pipeline version so it gets scheduled to run?
      - Can I start a stream pipeline version from a saved snapshot?
      instructions:
      - text: Activate version {versionId} of pipeline {pipelineId}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
      - text: Schedule pipeline version {versionId} of {pipelineId} starting from snapshot {snapshotId}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
          snapshotId: requestBody.snapshotId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/pipelines/{pipelineId}/versions/{versionId}/operations/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a running pipeline version
      effect: destructive
      questions:
      - How do I stop a running or paused pipeline version without keeping its state?
      - Does cancelling a pipeline version save a snapshot of its progress?
      instructions:
      - text: Cancel pipeline version {versionId} of {pipelineId}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
      - text: Abort the running version {versionId} in pipeline {pipelineId} and discard its state.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/pipelines/{pipelineId}/versions/{versionId}/operations/deactivate'].post
  update:
    x-apievangelist-phrasing:
      intent: Deactivate a scheduled pipeline version
      effect: write
      questions:
      - How do I take a scheduled pipeline version out of the schedule?
      - Can I deactivate a pipeline version that is scheduled but not yet running?
      instructions:
      - text: Deactivate scheduled version {versionId} of pipeline {pipelineId}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
      - text: Unschedule pipeline version {versionId} in {pipelineId}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/pipelines/{pipelineId}/versions/{versionId}/operations/pause'].post
  update:
    x-apievangelist-phrasing:
      intent: Pause a running pipeline version
      effect: write
      questions:
      - Can I pause a streaming pipeline version and keep a snapshot of its state?
      - How do I temporarily halt a running pipeline version?
      instructions:
      - text: Pause running version {versionId} of pipeline {pipelineId}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
      - text: Temporarily halt pipeline version {versionId} of {pipelineId}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/pipelines/{pipelineId}/versions/{versionId}/operations/resume'].post
  update:
    x-apievangelist-phrasing:
      intent: Resume a paused pipeline version
      effect: write
      questions:
      - How do I restart a paused pipeline version from where it left off?
      - Can I resume a paused pipeline version in high-availability mode?
      instructions:
      - text: Resume paused version {versionId} of pipeline {pipelineId}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
      - text: Resume pipeline version {versionId} of {pipelineId} with high availability {highAvailability}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
          highAvailability: requestBody.highAvailability
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/pipelines/{pipelineId}/versions/{versionId}/operations/upgrade'].post
  update:
    x-apievangelist-phrasing:
      intent: Upgrade a pipeline version to another version
      effect: write
      questions:
      - How do I switch a running pipeline to a newer version without losing stream state?
      - Can I upgrade one pipeline version to a different one in place?
      instructions:
      - text: Upgrade version {versionId} of pipeline {pipelineId} to version {toVersionId}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
          toVersionId: requestBody.toVersionId
      - text: Replace running version {versionId} of pipeline {pipelineId} with {toVersionId}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
          toVersionId: requestBody.toVersionId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/pipelines/{pipelineId}/versions/{versionId}/operations/{operationId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one operation on a pipeline version
      effect: read
      questions:
      - How do I check whether a specific activate or upgrade operation on my pipeline finished?
      - What's the status of a single pipeline version operation?
      instructions:
      - text: Get operation {operationId} on version {versionId} of pipeline {pipelineId}.
        slots:
          operationId: path.operationId
          versionId: path.versionId
          pipelineId: path.pipelineId
      - text: Check the status of operation {operationId} on {pipelineId} version {versionId}.
        slots:
          operationId: path.operationId
          versionId: path.versionId
          pipelineId: path.pipelineId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/pipelines/{pipelineId}/versions/{versionId}/scheduler-configuration'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a pipeline version's scheduler configuration
      effect: read
      questions:
      - What triggers are configured to run my pipeline version, catalog changes or time?
      - How can I see when a batch pipeline version is scheduled to run?
      instructions:
      - text: Get the scheduler configuration for version {versionId} of pipeline {pipelineId}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
      - text: Show the run triggers set on version {versionId} of pipeline {pipelineId}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/pipelines/{pipelineId}/versions/{versionId}/scheduler-configuration'].put
  update:
    x-apievangelist-phrasing:
      intent: Change a pipeline version's scheduler triggers
      effect: write
      questions:
      - Can I make a pipeline version run on a timer instead of on catalog changes?
      - Why can I only change scheduler settings when the version is in the READY state?
      instructions:
      - text: Set time trigger {timeTriggerOptions} on version {versionId} of pipeline {pipelineId}.
        slots:
          timeTriggerOptions: requestBody.timeTriggerOptions
          versionId: path.versionId
          pipelineId: path.pipelineId
      - text: Update pipeline version {versionId} of {pipelineId} to run on catalog trigger {catalogTriggerOptions}.
        slots:
          versionId: path.versionId
          pipelineId: path.pipelineId
          catalogTriggerOptions: requestBody.catalogTriggerOptions
      method: generated
      generated: '2026-10-01'