Elastic Agent policies APIs enable you to manage agent policies, including creating, updating, and deleting policies, as well as to retrieve agent policy outputs, manifests, and auto-upgrade status information.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/elk-stack-elastic-agent-policies-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
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 Elastic Agent policies 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 Agent policies
description: 'Elastic Agent policies APIs enable you to manage agent policies, including creating, updating, and deleting policies, as well as to retrieve agent policy outputs, manifests, and auto-upgrade status information.
'
x-displayName: Elastic Agent policies
paths:
/api/fleet/agent_policies:
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_policies</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
List all agent policies.<br/><br/>[Required authorization] Route required privileges: fleet-agent-policies-read OR fleet-agents-read OR fleet-setup.'
operationId: get-fleet-agent-policies
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:
type: number
- 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:
- desc
- asc
type: string
- description: When true, only show policies with upgradeable agents
in: query
name: showUpgradeable
required: false
schema:
type: boolean
- description: A KQL query string to filter results
in: query
name: kuery
required: false
schema:
type: string
- description: use withAgentCount instead
in: query
name: noAgentCount
required: false
schema:
deprecated: true
type: boolean
- description: get policies with agent count
in: query
name: withAgentCount
required: false
schema:
type: boolean
- description: get full policies with package policies populated
in: query
name: full
required: false
schema:
type: boolean
- description: 'Format for the response: simplified or legacy'
in: query
name: format
required: false
schema:
enum:
- simplified
- legacy
type: string
responses:
'200':
content:
application/json:
examples:
getAgentPoliciesExample:
description: List of agent policies
value:
items:
- description: A sample agent policy
id: agent-policy-id-1
is_managed: false
is_protected: false
name: My agent policy
namespace: default
revision: 1
status: active
updated_at: '2024-01-15T10:00:00.000Z'
updated_by: user1
page: 1
perPage: 20
total: 1
schema:
additionalProperties: false
type: object
properties:
items:
items:
$ref: '#/components/schemas/Kibana_HTTP_APIs_agent_policy_response'
maxItems: 10000
type: array
page:
type: number
perPage:
type: number
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: {}
error:
type: string
errorType:
type: string
message:
type: string
statusCode:
type: number
required:
- message
- attributes
description: Bad Request
summary: Get agent policies
tags:
- Elastic Agent policies
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/agent_policies</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Create a new agent policy.<br/><br/>[Required authorization] Route required privileges: fleet-agent-policies-all.'
operationId: post-fleet-agent-policies
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
- description: Whether to add the system integration to the new agent policy
in: query
name: sys_monitoring
required: false
schema:
type: boolean
requestBody:
content:
application/json:
examples:
postAgentPolicyRequestExample:
description: Create a new agent policy
value:
description: A sample agent policy
monitoring_enabled:
- logs
- metrics
name: My agent policy
namespace: default
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_new_agent_policy'
responses:
'200':
content:
application/json:
examples:
postAgentPolicyExample:
description: The created agent policy
value:
item:
description: A sample agent policy
id: agent-policy-id-2
is_managed: false
is_protected: false
name: My agent policy
namespace: default
revision: 1
status: active
updated_at: '2024-01-15T10:00:00.000Z'
updated_by: user1
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_get_agent_policy_response'
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: {}
error:
type: string
errorType:
type: string
message:
type: string
statusCode:
type: number
required:
- message
- attributes
description: Bad Request
summary: Create an agent policy
tags:
- Elastic Agent policies
x-metaTags:
- content: Kibana
name: product_name
/api/fleet/agent_policies/_bulk_get:
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/agent_policies/_bulk_get</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Get multiple agent policies by ID.<br/><br/>[Required authorization] Route required privileges: fleet-agent-policies-read OR fleet-agents-read OR fleet-setup.'
operationId: post-fleet-agent-policies-bulk-get
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
- description: 'Format for the response: simplified or legacy'
in: query
name: format
required: false
schema:
enum:
- simplified
- legacy
type: string
requestBody:
content:
application/json:
examples:
postBulkGetAgentPoliciesRequestExample:
description: Retrieve multiple agent policies by ID
value:
ids:
- agent-policy-id-1
- agent-policy-id-2
schema:
additionalProperties: false
type: object
properties:
full:
description: get full policies with package policies populated
type: boolean
ids:
description: list of package policy ids
items:
type: string
maxItems: 1000
type: array
ignoreMissing:
type: boolean
required:
- ids
responses:
'200':
content:
application/json:
examples:
postBulkGetAgentPoliciesExample:
description: The requested agent policies
value:
items:
- id: agent-policy-id-1
is_managed: false
is_protected: false
name: My agent policy
namespace: default
revision: 1
status: active
updated_at: '2024-01-15T10:00:00.000Z'
updated_by: user1
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_bulk_get_agent_policies_response'
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: {}
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: One or more agent policies were not found
value:
error: Not Found
message: An error message describing what went wrong
statusCode: 404
description: Not Found
summary: Bulk get agent policies
tags:
- Elastic Agent policies
x-metaTags:
- content: Kibana
name: product_name
/api/fleet/agent_policies/{agentPolicyId}:
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_policies/{agentPolicyId}</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Get an agent policy by ID.<br/><br/>[Required authorization] Route required privileges: fleet-agent-policies-read OR fleet-agents-read OR fleet-setup.'
operationId: get-fleet-agent-policies-agentpolicyid
parameters:
- description: The ID of the agent policy
in: path
name: agentPolicyId
required: true
schema:
type: string
- description: 'Format for the response: simplified or legacy'
in: query
name: format
required: false
schema:
enum:
- simplified
- legacy
type: string
responses:
'200':
content:
application/json:
examples:
getAgentPolicyExample:
description: An agent policy
value:
item:
description: A sample agent policy
id: agent-policy-id-1
is_managed: false
is_protected: false
name: My agent policy
namespace: default
revision: 1
status: active
updated_at: '2024-01-15T10:00:00.000Z'
updated_by: user1
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_get_agent_policy_response'
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: {}
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 policy was found with the given ID
value:
error: Not Found
message: Agent policy not found
statusCode: 404
description: Not Found
summary: Get an agent policy
tags:
- Elastic Agent policies
x-metaTags:
- content: Kibana
name: product_name
put:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb put">put</span> <span class="operation-path">/s/{space_id}/api/fleet/agent_policies/{agentPolicyId}</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Update an agent policy by ID.<br/><br/>[Required authorization] Route required privileges: fleet-agent-policies-all.'
operationId: put-fleet-agent-policies-agentpolicyid
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
- description: The ID of the agent policy
in: path
name: agentPolicyId
required: true
schema:
type: string
- description: 'Format for the response: simplified or legacy'
in: query
name: format
required: false
schema:
enum:
- simplified
- legacy
type: string
requestBody:
content:
application/json:
examples:
putAgentPolicyRequestExample:
description: Update an agent policy
value:
description: An updated agent policy description
monitoring_enabled:
- logs
name: Updated agent policy
namespace: default
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_update_agent_policy_request_body'
responses:
'200':
content:
application/json:
examples:
putAgentPolicyExample:
description: The updated agent policy
value:
item:
description: An updated agent policy description
id: agent-policy-id-1
is_managed: false
is_protected: false
name: Updated agent policy
namespace: default
revision: 2
status: active
updated_at: '2024-01-15T11:00:00.000Z'
updated_by: user1
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_get_agent_policy_response'
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: {}
error:
type: string
errorType:
type: string
message:
type: string
statusCode:
type: number
required:
- message
- attributes
description: Bad Request
summary: Update an agent policy
tags:
- Elastic Agent policies
x-metaTags:
- content: Kibana
name: product_name
/api/fleet/agent_policies/{agentPolicyId}/auto_upgrade_agents_status:
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_policies/{agentPolicyId}/auto_upgrade_agents_status</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Get the auto-upgrade status for agents assigned to an agent policy.<br/><br/>[Required authorization] Route required privileges: fleet-agents-read.'
operationId: get-fleet-agent-policies-agentpolicyid-auto-upgrade-agents-status
parameters:
- description: The ID of the agent policy
in: path
name: agentPolicyId
required: true
schema:
type: string
responses:
'200':
content:
application/json:
examples:
getAutoUpgradeAgentsStatusExample:
description: Auto-upgrade status for agents in the policy
value:
agentsCount: 5
currentVersion: 8.16.0
failedAgentsCount: 0
upgradedAgentsCount: 3
upgradingAgentsCount: 1
schema:
additionalProperties: false
type: object
properties:
currentVersions:
items:
additionalProperties: false
type: object
properties:
agents:
description: Number of agents that upgraded to this version
type: number
failedUpgradeActionIds:
description: List of action IDs related to failed upgrades
items:
type: string
maxItems: 1000
type: array
failedUpgradeAgents:
description: Number of agents that failed to upgrade to this version
type: number
inProgressUpgradeActionIds:
description: List of action IDs related to in-progress upgrades
items:
type: string
maxItems: 1000
type: array
inProgressUpgradeAgents:
description: Number of agents that are upgrading to this version
type: number
version:
description: Agent version
type: string
required:
- version
- agents
- failedUpgradeAgents
- inProgressUpgradeAgents
maxItems: 10000
type: array
totalAgents:
type: number
required:
- currentVersions
- totalAgents
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: {}
error:
type: string
errorType:
type: string
message:
type: string
statusCode:
type: number
required:
- message
- attributes
description: Bad Request
summary: Get auto upgrade agent status
tags:
- Elastic Agent policies
x-metaTags:
- content: Kibana
name: product_name
/api/fleet/agent_policies/{agentPolicyId}/copy:
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/agent_policies/{agentPolicyId}/copy</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Copy an agent policy by ID.<br/><br/>[Required authorization] Route required privileges: fleet-agent-policies-all.'
operationId: post-fleet-agent-policies-agentpolicyid-copy
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
- description: The ID of the agent policy
in: path
name: agentPolicyId
required: true
schema:
type: string
- description: 'Format for the response: simplified or legacy'
in: query
name: format
required: false
schema:
enum:
- simplified
- legacy
type: string
requestBody:
content:
application/json:
examples:
postCopyAgentPolicyRequestExample:
description: Copy an agent policy with a new name
value:
description: A copy of the original agent policy
name: Copy of my agent policy
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_copy_agent_policy_request'
responses:
'200':
content:
application/json:
examples:
postCopyAgentPolicyExample:
description: The copied agent policy
value:
item:
description: A copy of the original agent policy
id: agent-policy-id-copy-1
is_managed: false
is_protected: false
name: Copy of my agent policy
namespace: default
revision: 1
status: active
updated_at: '2024-01-15T11:00:00.000Z'
updated_by: user1
schema:
$ref: '#/components/schemas/Kibana_HTTP_APIs_get_agent_policy_response'
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: {}
error:
type: string
errorType:
type: string
message:
type: string
statusCode:
type: number
required:
- message
- attributes
description: Bad Request
summary: Copy an agent policy
tags:
- Elastic Agent policies
x-metaTags:
- content: Kibana
name: product_name
/api/fleet/agent_policies/{agentPolicyId}/download:
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_policies/{agentPolicyId}/download</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Download an agent policy by ID.<br/><br/>[Required authorization] Route required privileges: fleet-agent-policies-read OR fleet-setup.'
operationId: get-fleet-agent-policies-agentpolicyid-download
parameters:
- description: The ID of the agent policy
in: path
name: agentPolicyId
required: true
schema:
type: string
- description: If true, returns the policy as a downloadable file
in: query
name: download
required: false
schema:
type: boolean
- description: If true, returns the policy formatted for standalone agents
in: query
name: standalone
required: false
schema:
type: boolean
- description: If true, returns the policy formatted for Kubernetes deployment
in: query
name: kubernetes
required: false
schema:
type: boolean
- description: If provided, returns the policy at the specified revision. Cannot be used with standalone or kubernetes flags.
in: query
name: revision
required: false
schema:
type: number
responses:
'200':
content:
application/json:
examples:
getDownloadAgentPolicyExample:
description: The agent policy download response
value:
item: 'id: agent-policy-id-1\nrevision: 1\noutputs:\n default:\n type: elasticsearch\n hosts:\n - https://elasticsearch.example.com:9200\n'
schema:
type: string
description: Successful response — returns the agent policy as a YAML file download
'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: {}
error:
type: string
errorType:
type: string
message:
type: string
# --- truncated at 32 KB (116 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elk-stack/refs/heads/main/openapi/elk-stack-elastic-agent-policies-api-openapi.yml