# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Kibana APM agent configuration API
  version: 1.0.0
extends: openapi/elk-stack-apm-agent-configuration-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: 7
- target: $.paths['/api/apm/settings/agent-configuration'].get
  update:
    x-apievangelist-phrasing:
      intent: List all APM agent configurations
      effect: read
      questions:
      - How do I see every APM agent configuration defined in Kibana?
      - What privileges do I need to read the full list of agent configurations?
      instructions:
      - text: List all APM agent configurations using API version {elastic_api_version}.
        slots:
          elastic_api_version: header.elastic-api-version
      - text: Show me every central agent configuration across my APM services.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/apm/settings/agent-configuration'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or update an APM agent configuration
      effect: write
      questions:
      - How do I centrally change settings like sample rate for an APM agent on one service?
      - Why does saving an agent configuration that already exists fail unless I pass overwrite?
      - Can I push new agent settings to a service without redeploying it?
      instructions:
      - text: Create an agent configuration for service {service} with settings {settings}.
        slots:
          service: requestBody.service
          settings: requestBody.settings
      - text: Overwrite the existing agent configuration for {service} with {settings}, setting overwrite to {overwrite}.
        slots:
          service: requestBody.service
          settings: requestBody.settings
          overwrite: query.overwrite
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/apm/settings/agent-configuration'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an APM agent configuration
      effect: destructive
      questions:
      - How do I remove the central agent configuration for a service?
      - Does deleting an agent configuration also sync the APM package policies in Fleet?
      instructions:
      - text: Delete the APM agent configuration for service {service}.
        slots:
          service: requestBody.service
      - text: Remove central agent settings from {service}.
        slots:
          service: requestBody.service
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/apm/settings/agent-configuration/agent_name'].get
  update:
    x-apievangelist-phrasing:
      intent: Find which APM agent a service uses
      effect: read
      questions:
      - Which APM agent language is instrumenting a given service?
      - How can I tell whether a service runs the Java or Node.js agent?
      instructions:
      - text: Get the agent name for service {serviceName}.
        slots:
          serviceName: query.serviceName
      - text: Tell me which APM agent {serviceName} is using.
        slots:
          serviceName: query.serviceName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/apm/settings/agent-configuration/environments'].get
  update:
    x-apievangelist-phrasing:
      intent: List environments available for a service
      effect: read
      questions:
      - What environments can I target when configuring an agent for a service?
      - Can I get the environments across all services at once?
      instructions:
      - text: List the environments for service {serviceName}.
        slots:
          serviceName: query.serviceName
      - text: Show the environments known across every APM service.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/apm/settings/agent-configuration/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Look up an agent's config and mark it applied
      effect: write
      questions:
      - How does an APM agent fetch its configuration and report that it applied it?
      - Can I mark an agent configuration as applied when the etag matches?
      instructions:
      - text: Look up the agent configuration for {service} and mark it applied if the etag is {etag}.
        slots:
          service: requestBody.service
          etag: requestBody.etag
      - text: Record error {error} against the agent configuration for {service}.
        slots:
          error: requestBody.error
          service: requestBody.service
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/apm/settings/agent-configuration/view'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the agent configuration for a service
      effect: read
      questions:
      - How do I view the agent settings configured for one service in a specific environment?
      - What happens if no agent configuration matches the service and environment I ask for?
      instructions:
      - text: Show the agent configuration for service {name} in environment {environment}.
        slots:
          name: query.name
          environment: query.environment
      - text: Get the single agent configuration for {name}.
        slots:
          name: query.name
      method: generated
      generated: '2026-09-26'