# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Knock Management API (mAPI) Commits API
  version: 1.0.0
extends: openapi/knock-app-commits-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: 5
- target: $.paths['/v1/commits/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a commit by ID
      effect: read
      questions:
      - How do I inspect what a specific commit changed?
      - Can I look up one commit by its ID?
      instructions:
      - text: Get commit {id}.
        slots:
          id: path.id
      - text: Show the details of commit {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/commits/{id}/promote'].put
  update:
    x-apievangelist-phrasing:
      intent: Promote a single commit
      effect: write
      questions:
      - How do I promote just one change to the next environment?
      - Can I push a single commit forward without promoting everything?
      instructions:
      - text: Promote commit {id} to the next environment.
        slots:
          id: path.id
      - text: Move only change {id} forward one environment.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/commits/promote'].put
  update:
    x-apievangelist-phrasing:
      intent: Promote all changes to an environment
      effect: write
      questions:
      - How do I promote every pending change into production?
      - Can I promote only one resource type's changes at once?
      instructions:
      - text: Promote all changes to {to_environment}.
        slots:
          to_environment: query.to_environment
      - text: Promote all {resource_type} changes into {to_environment}.
        slots:
          resource_type: query.resource_type
          to_environment: query.to_environment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/commits'].get
  update:
    x-apievangelist-phrasing:
      intent: List commits in an environment
      effect: read
      questions:
      - Which commits haven't been promoted yet?
      - Can I see the commit history for one resource?
      instructions:
      - text: List commits in {environment}.
        slots:
          environment: query.environment
      - text: Show commits in {environment} filtered by promoted status {promoted}.
        slots:
          environment: query.environment
          promoted: query.promoted
      - text: List commits for resource {resource_id} in {environment}.
        slots:
          resource_id: query.resource_id
          environment: query.environment
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/commits'].put
  update:
    x-apievangelist-phrasing:
      intent: Commit all pending development changes
      effect: write
      questions:
      - How do I commit everything I've changed in development?
      - Can I attach a message when committing all changes?
      instructions:
      - text: Commit all changes in {environment}.
        slots:
          environment: query.environment
      - text: Commit all pending changes in {environment} with message {commit_message}.
        slots:
          environment: query.environment
          commit_message: query.commit_message
      method: generated
      generated: '2026-10-01'