# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Kibana Elastic Agent actions API
  version: 1.0.0
extends: openapi/elk-stack-elastic-agent-actions-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: 16
- target: $.paths['/api/fleet/agents/{agentId}/actions'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a custom action to one Fleet agent
      effect: write
      questions:
      - Can I push a custom action to a single Elastic Agent?
      - What kinds of actions can I queue for one agent through Fleet?
      instructions:
      - text: Send action {action} to agent {agentId}.
        slots:
          action: requestBody.action
          agentId: path.agentId
      - text: Queue a custom Fleet action {action} for agent {agentId}.
        slots:
          action: requestBody.action
          agentId: path.agentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/fleet/agents/{agentId}/reassign'].post
  update:
    x-apievangelist-phrasing:
      intent: Move one agent to another policy
      effect: write
      questions:
      - How do I move a single Elastic Agent to a different agent policy?
      - Can I change which policy one agent is enrolled in?
      instructions:
      - text: Reassign agent {agentId} to policy {policy_id}.
        slots:
          agentId: path.agentId
          policy_id: requestBody.policy_id
      - text: Move agent {agentId} onto agent policy {policy_id}.
        slots:
          agentId: path.agentId
          policy_id: requestBody.policy_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/fleet/agents/{agentId}/remove_collector'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove one OpAMP collector from Fleet
      effect: destructive
      questions:
      - How do I take a single OpAMP collector off the Fleet agents list?
      - Can a removed collector reconnect since its API keys stay valid?
      instructions:
      - text: Remove OpAMP collector {agentId} from Fleet.
        slots:
          agentId: path.agentId
      - text: Mark collector {agentId} as unenrolled.
        slots:
          agentId: path.agentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/fleet/agents/{agentId}/request_diagnostics'].post
  update:
    x-apievangelist-phrasing:
      intent: Request diagnostics from one agent
      effect: write
      questions:
      - How do I collect a diagnostics bundle from a misbehaving Elastic Agent?
      - Can the diagnostics bundle include extra metrics like CPU profiles?
      instructions:
      - text: Request a diagnostics bundle from agent {agentId}.
        slots:
          agentId: path.agentId
      - text: Collect diagnostics from agent {agentId} with extra metrics {additional_metrics}.
        slots:
          agentId: path.agentId
          additional_metrics: requestBody.additional_metrics
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/fleet/agents/{agentId}/rollback'].post
  update:
    x-apievangelist-phrasing:
      intent: Roll back one agent to its previous version
      effect: write
      questions:
      - Can I undo an Elastic Agent upgrade on one host?
      - How do I roll a single agent back to the version it ran before?
      instructions:
      - text: Roll back agent {agentId} to its previous version.
        slots:
          agentId: path.agentId
      - text: Revert the upgrade on agent {agentId}.
        slots:
          agentId: path.agentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/fleet/agents/{agentId}/unenroll'].post
  update:
    x-apievangelist-phrasing:
      intent: Unenroll one agent from Fleet
      effect: destructive
      questions:
      - How do I unenroll a single Elastic Agent from Fleet?
      - Can I also revoke the agent's enrollment API key when unenrolling it?
      instructions:
      - text: Unenroll agent {agentId}.
        slots:
          agentId: path.agentId
      - text: Unenroll agent {agentId} and revoke its API key ({revoke}).
        slots:
          agentId: path.agentId
          revoke: requestBody.revoke
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/fleet/agents/{agentId}/upgrade'].post
  update:
    x-apievangelist-phrasing:
      intent: Upgrade one agent to a new version
      effect: write
      questions:
      - How do I upgrade a single Elastic Agent to a specific version?
      - Can I upgrade an agent from a custom download source?
      instructions:
      - text: Upgrade agent {agentId} to version {version}.
        slots:
          agentId: path.agentId
          version: requestBody.version
      - text: Upgrade agent {agentId} to {version} using source {source_uri}.
        slots:
          agentId: path.agentId
          version: requestBody.version
          source_uri: requestBody.source_uri
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/fleet/agents/action_status'].get
  update:
    x-apievangelist-phrasing:
      intent: Check progress of recent agent actions
      effect: read
      questions:
      - Did my recent Fleet upgrade or reassign actions finish successfully?
      - Can I see only scheduled agent actions and their status?
      instructions:
      - text: Show the status of recent Fleet agent actions.
      - text: List the latest {latest} agent actions since {date}.
        slots:
          latest: query.latest
          date: query.date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/fleet/agents/actions/{actionId}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel a pending agent action
      effect: destructive
      questions:
      - Can I cancel a Fleet action that hasn't run yet, like a scheduled upgrade?
      - How do I stop a pending agent action?
      instructions:
      - text: Cancel agent action {actionId}.
        slots:
          actionId: path.actionId
      - text: Stop pending Fleet action {actionId}.
        slots:
          actionId: path.actionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/fleet/agents/bulk_reassign'].post
  update:
    x-apievangelist-phrasing:
      intent: Move many agents to another policy
      effect: write
      questions:
      - How do I move a whole group of agents to a new policy at once?
      - Can I dry-run a bulk reassignment first?
      instructions:
      - text: Reassign agents {agents} to policy {policy_id}.
        slots:
          agents: requestBody.agents
          policy_id: requestBody.policy_id
      - text: Bulk move agents {agents} onto policy {policy_id}, including inactive ones ({includeInactive}).
        slots:
          agents: requestBody.agents
          policy_id: requestBody.policy_id
          includeInactive: requestBody.includeInactive
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/fleet/agents/bulk_remove_collectors'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove many OpAMP collectors from Fleet
      effect: destructive
      questions:
      - Can I clear several OpAMP collectors from the Fleet list in one go?
      - Will bulk-removed collectors be able to reconnect on their own?
      instructions:
      - text: Remove OpAMP collectors {agents} from Fleet.
        slots:
          agents: requestBody.agents
      - text: Dry-run removing collectors {agents} ({dryRun}).
        slots:
          agents: requestBody.agents
          dryRun: requestBody.dryRun
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/fleet/agents/bulk_request_diagnostics'].post
  update:
    x-apievangelist-phrasing:
      intent: Request diagnostics from many agents
      effect: write
      questions:
      - Can I gather diagnostics bundles from a batch of agents at once?
      - Is there a batch size setting when requesting diagnostics in bulk?
      instructions:
      - text: Request diagnostics bundles from agents {agents}.
        slots:
          agents: requestBody.agents
      - text: Collect diagnostics from agents {agents} in batches of {batchSize}.
        slots:
          agents: requestBody.agents
          batchSize: requestBody.batchSize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/fleet/agents/bulk_rollback'].post
  update:
    x-apievangelist-phrasing:
      intent: Roll back many agents to previous versions
      effect: write
      questions:
      - How do I roll back a failed agent upgrade across many hosts?
      - Can a bulk rollback include inactive agents?
      instructions:
      - text: Roll back agents {agents} to their previous version.
        slots:
          agents: requestBody.agents
      - text: Revert upgrades on agents {agents} in batches of {batchSize}.
        slots:
          agents: requestBody.agents
          batchSize: requestBody.batchSize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/fleet/agents/bulk_unenroll'].post
  update:
    x-apievangelist-phrasing:
      intent: Unenroll many agents from Fleet
      effect: destructive
      questions:
      - Can I unenroll a list of agents in one request?
      - Does bulk unenroll let me revoke the agents' enrollment keys too?
      instructions:
      - text: Unenroll agents {agents}.
        slots:
          agents: requestBody.agents
      - text: Force unenroll agents {agents} and revoke their keys ({revoke}).
        slots:
          agents: requestBody.agents
          revoke: requestBody.revoke
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/fleet/agents/bulk_update_agent_tags'].post
  update:
    x-apievangelist-phrasing:
      intent: Add or remove tags on many agents
      effect: write
      questions:
      - How do I tag a group of Elastic Agents?
      - Can I add some tags and remove others across agents in one call?
      instructions:
      - text: Add tags {tagsToAdd} to agents {agents}.
        slots:
          tagsToAdd: requestBody.tagsToAdd
          agents: requestBody.agents
      - text: Remove tags {tagsToRemove} from agents {agents}.
        slots:
          tagsToRemove: requestBody.tagsToRemove
          agents: requestBody.agents
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/fleet/agents/bulk_upgrade'].post
  update:
    x-apievangelist-phrasing:
      intent: Upgrade many agents with a rollout
      effect: write
      questions:
      - Can I upgrade my whole fleet of agents to a new version?
      - Is it possible to spread a bulk upgrade over a rollout window or start it later?
      instructions:
      - text: Upgrade agents {agents} to version {version}.
        slots:
          agents: requestBody.agents
          version: requestBody.version
      - text: Upgrade agents {agents} to {version} over {rollout_duration_seconds} seconds starting at {start_time}.
        slots:
          agents: requestBody.agents
          version: requestBody.version
          rollout_duration_seconds: requestBody.rollout_duration_seconds
          start_time: requestBody.start_time
      method: generated
      generated: '2026-09-26'