# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Harness Environment API
  version: 1.0.0
extends: openapi/harness-environment-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: 5
- target: $.paths['/v1/idp-environments'].post
  update:
    x-apievangelist-phrasing:
      intent: Create, compile and run an IDP environment
      effect: write
      questions:
      - How do I spin up a new developer environment from an environment blueprint?
      - Can I dry-run creating an environment before it actually executes?
      instructions:
      - text: Create environment {name} (id {id}) owned by {owner} from blueprint {blueprint} version {version} with overrides {overrides}.
        slots:
          name: requestBody.environment_name
          id: requestBody.environment_identifier
          owner: requestBody.owner
          blueprint: requestBody.environment_blueprint_identifier
          version: requestBody.environment_blueprint_version
          overrides: requestBody.overrides
      - text: Dry-run a new environment from blueprint {environment_blueprint_identifier} with dryRun {dryRun}.
        slots:
          environment_blueprint_identifier: requestBody.environment_blueprint_identifier
          dryRun: query.dryRun
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/idp-environments/{environment-id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update and re-run an IDP environment
      effect: write
      questions:
      - How do I move an existing environment to a newer blueprint version?
      - Can I change an environment's target state and have it recompile and execute?
      instructions:
      - text: Update environment {environment_id} to blueprint version {environment_blueprint_version}.
        slots:
          environment_id: path.environment-id
          environment_blueprint_version: requestBody.environment_blueprint_version
      - text: Set target state {target_state} on existing environment {environment_id} and re-execute it.
        slots:
          target_state: requestBody.target_state
          environment_id: path.environment-id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/idp-environments/{environment-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an IDP environment
      effect: destructive
      questions:
      - How do I tear down a developer environment that's no longer active?
      - Can I delete an environment within a specific project?
      instructions:
      - text: Delete environment {environment_id}.
        slots:
          environment_id: path.environment-id
      - text: Remove inactive environment {environment_id} from project {projectIdentifier}.
        slots:
          environment_id: path.environment-id
          projectIdentifier: query.projectIdentifier
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/environments/compile'].post
  update:
    x-apievangelist-phrasing:
      intent: Compile an environment to infrastructure
      effect: read
      questions:
      - What infrastructure would my environment YAML compile to for a given target state?
      - Can I validate an environment definition without creating it?
      instructions:
      - text: Compile environment YAML {environmentYaml} for target state {targetState}.
        slots:
          environmentYaml: requestBody.environmentYaml
          targetState: requestBody.targetState
      - text: Check that {environmentYaml} compiles to valid infrastructure in project {projectIdentifier} at state {targetState}.
        slots:
          environmentYaml: requestBody.environmentYaml
          projectIdentifier: requestBody.projectIdentifier
          targetState: requestBody.targetState
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/environments/schemas'].get
  update:
    x-apievangelist-phrasing:
      intent: Get environment and blueprint schemas
      effect: read
      questions:
      - Where can I find the schema for writing environment and blueprint YAML?
      - What fields does an environment blueprint definition accept?
      instructions:
      - text: Get the environment and blueprint schemas for account {account}.
        slots:
          account: header.Harness-Account
      - text: Show the environment blueprint schema for project {projectIdentifier}.
        slots:
          projectIdentifier: requestBody.projectIdentifier
      method: generated
      generated: '2026-09-26'