Kibana Elastic Agents API
Elastic Agents APIs enable you to manage Elastic Agents, including retrieving agent information, managing agent lifecycle, handling file uploads, and initiating agent setup.
OpenAPI Specification
openapi: 3.0.3
info:
contact:
name: Kibana Team
description: 'The Kibana REST APIs enable you to manage resources such as connectors, data views, and saved objects.
The API calls are stateless.
Each request that you make happens in isolation from other calls and must include all of the necessary information for Kibana to fulfill the
request.
API requests return JSON output, which is a format that is machine-readable and works well for automation.
To interact with Kibana APIs, use the following operations:
- GET: Fetches the information.
- PATCH: Applies partial modifications to the existing information.
- POST: Adds new information.
- PUT: Updates the existing information.
- DELETE: Removes the information.
You can prepend any Kibana API endpoint with `kbn:` and run the request in **Dev Tools → Console**.
For example:
```
GET kbn:/api/data_views
```
For more information about the console, refer to [Run API requests](https://www.elastic.co/docs/explore-analyze/query-filter/tools/console).
NOTE: Access to internal Kibana API endpoints will be restricted in Kibana version 9.0. Please move any integrations to publicly documented APIs.
## Documentation source and versions
This documentation is derived from the `main` branch of the [kibana](https://github.com/elastic/kibana) repository.
It is provided under license [Attribution-NonCommercial-NoDerivatives 4.0 International](https://creativecommons.org/licenses/by-nc-nd/4.0/).
This documentation contains work-in-progress information for future Elastic Stack releases.
'
title: Kibana APIs Actions Elastic Agents API
version: ''
x-doc-license:
name: Attribution-NonCommercial-NoDerivatives 4.0 International
url: https://creativecommons.org/licenses/by-nc-nd/4.0/
x-feedbackLink:
label: Feedback
url: https://github.com/elastic/docs-content/issues/new?assignees=&labels=feedback%2Ccommunity&projects=&template=api-feedback.yaml&title=%5BFeedback%5D%3A+
servers:
- url: https://{kibana_url}
variables:
kibana_url:
default: localhost:5601
security:
- apiKeyAuth: []
- basicAuth: []
tags:
- name: Elastic Agents
description: 'Elastic Agents APIs enable you to manage Elastic Agents, including retrieving agent information, managing agent lifecycle, handling file uploads, and initiating agent setup.
'
x-displayName: Elastic Agents
paths:
/api/fleet/agent_status/data:
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/fleet/agent_status/data</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Get the data streams that an agent is actively sending data to.<br/><br/>[Required authorization] Route required privileges: fleet-agents-read.'
operationId: get-fleet-agent-status-data
parameters:
- description: Agent IDs to check data for, as an array or comma-separated string
in: query
name: agentsIds
required: true
schema:
items:
type: string
maxItems: 10000
type: array
- description: Filter by integration package name
in: query
name: pkgName
required: false
schema:
type: string
- description: Filter by integration package version
in: query
name: pkgVersion
required: false
schema:
type: string
- description: When true, return a preview of the ingested data
in: query
name: previewData
required: false
schema:
default: false
type: boolean
responses:
'200':
content:
application/json:
examples:
getAgentDataExample:
description: Data streams the agent is actively sending data to
value:
items:
- data:
logs-nginx.access-default:
- id: agent-id-1
name: my-host
total: 1
totalMonitoring: 0
schema:
additionalProperties: false
type: object
properties:
dataPreview:
items:
nullable: true
maxItems: 10000
type: array
items:
items:
additionalProperties:
additionalProperties: false
type: object
properties:
data:
type: boolean
required:
- data
type: object
maxItems: 10000
type: array
required:
- items
- dataPreview
description: Successful response
'400':
content:
application/json:
examples:
genericErrorResponseExample:
description: Example of a generic error response
value:
error: Bad Request
message: An error message describing what went wrong
statusCode: 400
schema:
additionalProperties: false
description: Generic Error
type: object
properties:
attributes:
nullable: true
error:
type: string
errorType:
type: string
message:
type: string
statusCode:
type: number
required:
- message
- attributes
description: Bad Request
summary: Get incoming agent data
tags:
- Elastic Agents
x-metaTags:
- content: Kibana
name: product_name
/api/fleet/agents:
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/fleet/agents</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
List agents, with optional filtering and pagination.<br/><br/>[Required authorization] Route required privileges: fleet-agents-read.'
operationId: get-fleet-agents
parameters:
- description: Page number
in: query
name: page
required: false
schema:
type: number
- description: Number of results per page
in: query
name: perPage
required: false
schema:
default: 20
type: number
- description: A KQL query string to filter results
in: query
name: kuery
required: false
schema:
type: string
- description: When true, include agentless agents in the results
in: query
name: showAgentless
required: false
schema:
default: true
type: boolean
- description: When true, include inactive agents in the results
in: query
name: showInactive
required: false
schema:
default: false
type: boolean
- description: When true, include CPU and memory metrics in the response
in: query
name: withMetrics
required: false
schema:
default: false
type: boolean
- description: When true, only return agents that are upgradeable
in: query
name: showUpgradeable
required: false
schema:
default: false
type: boolean
- description: When true, return a summary of agent statuses in the response
in: query
name: getStatusSummary
required: false
schema:
default: false
type: boolean
- description: Field to sort results by
in: query
name: sortField
required: false
schema:
type: string
- description: Sort order, ascending or descending
in: query
name: sortOrder
required: false
schema:
enum:
- asc
- desc
type: string
- description: JSON-encoded array of sort values for `search_after` pagination
in: query
name: searchAfter
required: false
schema:
type: string
- description: When true, opens a new point-in-time for pagination
in: query
name: openPit
required: false
schema:
type: boolean
- description: Point-in-time ID for pagination
in: query
name: pitId
required: false
schema:
type: string
- description: Duration to keep the point-in-time alive, for example, `1m`
in: query
name: pitKeepAlive
required: false
schema:
type: string
responses:
'200':
content:
application/json:
examples:
getAgentsExample:
description: List of agents
value:
items:
- active: true
enrolled_at: '2024-01-01T00:00:00.000Z'
id: agent-id-1
policy_id: agent-policy-id-1
policy_revision: 1
status: online
type: PERMANENT
updated_at: '2024-01-01T00:00:00.000Z'
page: 1
perPage: 20
total: 1
schema:
additionalProperties: false
type: object
properties:
items:
items:
additionalProperties: false
type: object
properties:
access_api_key:
type: string
access_api_key_id:
type: string
active:
type: boolean
agent:
additionalProperties: true
type: object
properties:
id:
type: string
type:
type: string
version:
type: string
required:
- id
- version
audit_unenrolled_reason:
type: string
capabilities:
items:
type: string
maxItems: 100
type: array
components:
items:
additionalProperties: false
type: object
properties:
id:
type: string
message:
type: string
status:
enum:
- STARTING
- CONFIGURING
- HEALTHY
- DEGRADED
- FAILED
- STOPPING
- STOPPED
type: string
type:
type: string
units:
items:
additionalProperties: false
type: object
properties:
id:
type: string
message:
type: string
payload:
additionalProperties:
nullable: true
type: object
status:
enum:
- STARTING
- CONFIGURING
- HEALTHY
- DEGRADED
- FAILED
- STOPPING
- STOPPED
type: string
type:
enum:
- input
- output
- ''
type: string
required:
- id
- type
- status
- message
maxItems: 10000
type: array
required:
- id
- type
- status
- message
maxItems: 10000
type: array
default_api_key:
type: string
default_api_key_history:
items:
additionalProperties: false
deprecated: true
type: object
properties:
id:
type: string
retired_at:
type: string
required:
- id
- retired_at
maxItems: 100
type: array
default_api_key_id:
type: string
effective_config:
nullable: true
enrolled_at:
type: string
health:
additionalProperties:
nullable: true
type: object
id:
type: string
identifying_attributes:
additionalProperties:
type: string
type: object
last_checkin:
type: string
last_checkin_message:
type: string
last_checkin_status:
enum:
- error
- online
- degraded
- updating
- starting
- disconnected
type: string
last_known_status:
enum:
- offline
- error
- online
- inactive
- enrolling
- unenrolling
- unenrolled
- updating
- degraded
- uninstalled
- orphaned
type: string
local_metadata:
additionalProperties:
nullable: true
type: object
metrics:
additionalProperties: false
type: object
properties:
cpu_avg:
type: number
memory_size_byte_avg:
type: number
namespaces:
items:
type: string
maxItems: 100
type: array
non_identifying_attributes:
additionalProperties:
type: string
type: object
outputs:
additionalProperties:
additionalProperties: false
type: object
properties:
api_key_id:
type: string
to_retire_api_key_ids:
items:
additionalProperties: false
type: object
properties:
id:
type: string
retired_at:
type: string
required:
- id
- retired_at
maxItems: 100
type: array
type:
type: string
type: object
packages:
items:
type: string
maxItems: 10000
type: array
policy_id:
type: string
policy_revision:
nullable: true
type: number
sequence_num:
type: number
sort:
items:
nullable: true
maxItems: 10
type: array
status:
enum:
- offline
- error
- online
- inactive
- enrolling
- unenrolling
- unenrolled
- updating
- degraded
- uninstalled
- orphaned
type: string
tags:
items:
type: string
maxItems: 100
type: array
type:
enum:
- PERMANENT
- EPHEMERAL
- TEMPORARY
- OPAMP
type: string
unenrolled_at:
type: string
unenrollment_started_at:
type: string
unhealthy_reason:
items:
enum:
- input
- output
- other
type: string
maxItems: 3
nullable: true
type: array
upgrade:
additionalProperties: false
type: object
properties:
rollbacks:
items:
additionalProperties: false
type: object
properties:
valid_until:
type: string
version:
type: string
required:
- valid_until
- version
maxItems: 100
type: array
upgrade_attempts:
items:
type: string
maxItems: 10000
nullable: true
type: array
upgrade_details:
additionalProperties: false
nullable: true
type: object
properties:
action_id:
type: string
metadata:
additionalProperties: false
type: object
properties:
download_percent:
type: number
download_rate:
type: number
error_msg:
type: string
failed_state:
enum:
- UPG_REQUESTED
- UPG_SCHEDULED
- UPG_DOWNLOADING
- UPG_EXTRACTING
- UPG_REPLACING
- UPG_RESTARTING
- UPG_FAILED
- UPG_WATCHING
- UPG_ROLLBACK
type: string
reason:
type: string
retry_error_msg:
type: string
retry_until:
type: string
scheduled_at:
type: string
state:
enum:
- UPG_REQUESTED
- UPG_SCHEDULED
- UPG_DOWNLOADING
- UPG_EXTRACTING
- UPG_REPLACING
- UPG_RESTARTING
- UPG_FAILED
- UPG_WATCHING
- UPG_ROLLBACK
type: string
target_version:
type: string
required:
- target_version
- action_id
- state
upgrade_started_at:
nullable: true
type: string
upgraded_at:
nullable: true
type: string
user_provided_metadata:
additionalProperties:
nullable: true
type: object
required:
- id
- packages
- type
- active
- enrolled_at
- local_metadata
- effective_config
maxItems: 10000
type: array
nextSearchAfter:
type: string
page:
type: number
perPage:
type: number
pit:
type: string
statusSummary:
additionalProperties:
type: number
type: object
total:
type: number
required:
- items
- total
- page
- perPage
description: Successful response
'400':
content:
application/json:
examples:
genericErrorResponseExample:
description: Example of a generic error response
value:
error: Bad Request
message: An error message describing what went wrong
statusCode: 400
schema:
additionalProperties: false
description: Generic Error
type: object
properties:
attributes:
nullable: true
error:
type: string
errorType:
type: string
message:
type: string
statusCode:
type: number
required:
- message
- attributes
description: Bad Request
summary: Get agents
tags:
- Elastic Agents
x-metaTags:
- content: Kibana
name: product_name
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/fleet/agents</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Retrieve agents associated with specific action IDs.<br/><br/>[Required authorization] Route required privileges: fleet-agents-read.'
operationId: post-fleet-agents
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
requestBody:
content:
application/json:
examples:
postGetAgentsByActionsRequestExample:
description: Retrieve agents associated with specific action IDs
value:
actionIds:
- action-id-1
- action-id-2
schema:
additionalProperties: false
type: object
properties:
actionIds:
items:
type: string
maxItems: 1000
type: array
required:
- actionIds
responses:
'200':
content:
application/json:
examples:
postGetAgentsByActionsExample:
description: Agents associated with the given actions
value:
items:
- active: true
id: agent-id-1
policy_id: agent-policy-id-1
status: online
total: 1
schema:
additionalProperties: false
type: object
properties:
items:
items:
type: string
maxItems: 10000
type: array
required:
- items
description: Successful response
'400':
content:
application/json:
examples:
genericErrorResponseExample:
description: Example of a generic error response
value:
error: Bad Request
message: An error message describing what went wrong
statusCode: 400
schema:
additionalProperties: false
description: Generic Error
type: object
properties:
attributes:
nullable: true
error:
type: string
errorType:
type: string
message:
type: string
statusCode:
type: number
required:
- message
- attributes
description: Bad Request
summary: Get agents by action ids
tags:
- Elastic Agents
x-metaTags:
- content: Kibana
name: product_name
/api/fleet/agents/{agentId}:
delete:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb delete">delete</span> <span class="operation-path">/s/{space_id}/api/fleet/agents/{agentId}</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Delete an agent by ID.<br/><br/>[Required authorization] Route required privileges: fleet-agents-all.'
operationId: delete-fleet-agents-agentid
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
- description: The agent ID
in: path
name: agentId
required: true
schema:
type: string
responses:
'200':
content:
application/json:
examples:
deleteAgentExample:
description: Agent successfully deleted
value:
id: agent-id-1
success: true
schema:
additionalProperties: false
type: object
properties:
action:
enum:
- deleted
type: string
required:
- action
description: Successful response
'400':
content:
application/json:
examples:
genericErrorResponseExample:
description: Example of a generic error response
value:
error: Bad Request
message: An error message describing what went wrong
statusCode: 400
schema:
additionalProperties: false
description: Generic Error
type: object
properties:
attributes:
nullable: true
error:
type: string
errorType:
type: string
message:
type: string
statusCode:
type: number
required:
- message
- attributes
description: Bad Request
'404':
content:
application/json:
examples:
notFoundExample:
description: No agent was found with the given ID
value:
error: Not Found
message: Agent agent-id-1 not f
# --- truncated at 32 KB (107 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kibana/refs/heads/main/openapi/kibana-elastic-agents-api-openapi.yml