Skip to content

Document kuery (KQL) filtering and improve Fleet API page structure #7067

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
charlotte-hoblik wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Document kuery (KQL) filtering and improve Fleet API page structure #7067

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
424a303
add seactiona bout kuery
charlotte-hoblik Jun 22, 2026
2a3ad42
add style review edits
charlotte-hoblik Jun 22, 2026
e5a1e07
add frontmatter
charlotte-hoblik Jun 22, 2026
398e0fb
Improve Fleet API docs structure and navigation
charlotte-hoblik Jun 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 64 additions & 23 deletions reference/fleet/fleet-api-docs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
mapped_pages:
- https://www.elastic.co/guide/en/fleet/current/fleet-api-docs.html
description: Send Fleet API requests with the Kibana Console or cURL. Reference examples cover agent policies, integration policies, enrollment tokens, agent listing, KQL filters, and manual rollback.
applies_to:
stack: ga
serverless: ga
Expand All @@ -11,34 +12,39 @@ products:

# Kibana Fleet APIs [fleet-api-docs]

You can find details for all available {{fleet}} API endpoints in the [Kibana API docs]({{kib-apis}}). For {{serverless-full}} projects, check the [Kibana Serverless API docs]({{kib-serverless-apis}}).
This page provides cURL and {{kib}} Console examples for commonly used {{fleet}} APIs, including agent policies, integration policies, enrollment tokens, agent listing, KQL filtering, and agent rollback.

In this section, we provide examples of some commonly used {{fleet}} APIs.
For full endpoint specifications, parameters, and response schemas, refer to the [Kibana API docs]({{kib-apis}}). For {{serverless-full}} projects, use the [Kibana Serverless API docs]({{kib-serverless-apis}}).


## Before you begin [fleet-api-before-you-begin]

You'll need:

* A running {{kib}} deployment or {{serverless-full}} project with {{fleet}} available
* The {{kib}} host URL for your deployment (for example, `https://my-kibana-host:9243`)
* Authentication credentials for {{kib}} API requests. API key authentication is recommended. For details, refer to [Authentication]({{kib-apis}}authentication).
* A {{kib}} user with the required {{fleet}} and {{integrations}} privileges. For details, refer to [Roles and privileges](/reference/fleet/fleet-roles-privileges.md).


## Using the Console [using-the-console]

You can run {{fleet}} API requests through the {{kib}} Console.

1. Open the {{kib}} menu and go to **Management → Dev Tools**.
1. From the {{kib}} menu, go to **Management → Dev Tools**.

@bmorelli25 bmorelli25 Jun 24, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this wording aligns with our guidance on referring to apps and pages.

@vishaangelova vishaangelova Jun 25, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You mean this one: https://www.elastic.co/docs/contribute-docs/style-guide/ui-writing#referring-to-apps-and-pages

2. In your request, prepend your {{fleet}} API endpoint with `kbn:`, for example:

```sh
GET kbn:/api/fleet/agent_policies
```


For more detail about using the {{kib}} Console refer to [Run API requests](/explore-analyze/query-filter/tools/console.md).


## Authentication [authentication]

Authentication is required to send {{fleet}} API requests. For more information, refer to [Authentication]({{kib-apis}}authentication).
For more details about using the {{kib}} Console, refer to [Run API requests](/explore-analyze/query-filter/tools/console.md).


## Create agent policy [create-agent-policy-api]

To create a new agent policy in {{fleet}}, call `POST /api/fleet/agent_policies`.
To create an agent policy in {{fleet}}, call `POST /api/fleet/agent_policies`.

This cURL example creates an agent policy called `Agent policy 1` in the default namespace.

Expand Down Expand Up @@ -96,7 +102,7 @@ Example response:
}
```

1. Make a note of the policy ID. You’ll need the policy ID to add integration policies.
1. Note the policy ID. You need it to add integration policies.



Expand All @@ -109,7 +115,7 @@ You can use the {{fleet}} API to [Create and customize an {{elastic-defend}} pol
::::


This cURL example creates an integration policy for Nginx and adds it to the agent policy created in the previous example:
This cURL example creates an integration policy for Nginx and adds it to the agent policy you created in [Create agent policy](#create-agent-policy-api):

```shell
curl --request POST \
Expand Down Expand Up @@ -414,10 +420,10 @@ Example response (formatted for readability):

## List all {{agents}} [list-agents-api]

Use the [Get agents API]({{kib-apis}}operation/operation-get-fleet-agents) to retrieve a list of currently enrolled {{agents}}:
Use the [Get agents API]({{kib-apis}}operation/operation-get-fleet-agents) to retrieve a list of enrolled {{agents}}:

```shell
curl -X GET 'http://<user>:<pass>@<kibana url>/api/fleet/agents
curl -X GET 'http://<user>:<pass>@<kibana url>/api/fleet/agents'
```

By default, a maximum of 10,000 agents are returned, with 20 agents listed per page.
Expand Down Expand Up @@ -461,24 +467,40 @@ curl -X GET 'http://<user>:<pass>@<kibana url>/api/fleet/agents?perPage=10000&se
```


## Filter results with KQL [filter-results-with-kql]

The {{fleet}} list endpoints for agents, agent policies, package policies, and enrollment tokens accept a `kuery` query parameter that takes a [{{kib}} Query Language (KQL)](elasticsearch://reference/query-languages/kql.md) string to filter results. To check whether another endpoint accepts `kuery`, refer to its parameters in the [Kibana API docs]({{kib-apis}}).

Reference each field by the saved object type that stores it. {{fleet}} stores package policies as `ingest-package-policies` objects, so to filter package policies by integration name, query the `ingest-package-policies.package.name` field.
Comment on lines +472 to +474

@bmorelli25 bmorelli25 Jun 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm pretty sure this isn't true. Agents and enrollment tokens are not saved objects. They are stored in .fleet-* system indices so they must be referenced directly with no saved object prefix.

Your example for package policies works in [redacted] test cluster (I'll share w/you on Slack).

GET kbn:/api/fleet/package_policies?kuery=ingest-package-policies.package.name:activemq

✅

{
  "items": [
    {
      "id": "9xxxxa3-b6b2-4xxx-8f20-bb9822xxxxxe",
      "version": "WxxxxxxxxxQ==",
      "name": "activemq-1",
...

However, appending the saved object type to an agent call does not work:

GET kbn:/api/fleet/agents?kuery=ingest-agents.status:online

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "[request query.kuery]: KQLSyntaxError: This key 'ingest-agents.status' does NOT exist in fleet-agents saved object index patterns"
}

Excluding the saved object type from an agent call does work:

GET kbn:/api/fleet/agents?kuery=status:online

✅

{
  "items": [
    {
      "id": "3xxxx1-4a0a-4b00-bxxxx20xxxxx9d4",
      "type": "PERMANENT",
      "active": true,
...

@bmorelli25 bmorelli25 Jun 24, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@vishaangelova keep me honest here

@vishaangelova vishaangelova Jun 25, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, so actually only these two Fleet endpoints are backed by saved objects:

  • Agent policies (GET /api/fleet/agent_policies): stored as a fleet-agent-policies saved object, or, on deployments where space awareness is off, as the legacy ingest-agent-policies saved object (#1 and #2).
    • Use fleet-agent-policies.<field> in the KQL prefix; the legacy ingest-agent-policies.<field> also works because Fleet normalizes either prefix at runtime (#3)
  • Package policies (GET /api/fleet/package_policies): stored as a fleet-package-policies saved object, or, on deployments where space awareness is off, as the legacy ingest-package-policies saved object (#1, and #2).
    • Use fleet-package-policies.<field>, but the legacy ingest-package-policies.<field> also works for the same reason as above (#3).

Agents (GET /api/fleet/agents) are stored in the .fleet-agents ES system index (#1). So these should be referenced without a prefix (e.g., status:online). However, here fleet-agents.status:online also works because Fleet strips it from the kuery (#2), but ingest-agents. does not exist, and that returns an error.

Enrollment API keys (GET /api/fleet/enrollment_api_keys) are stored in the .fleet-enrollment-api-keys ES system index (#1), but here no prefix should be used as the kuery is passed straight through to the index search (e.g., policy_id:"<policy-id>").


This cURL example returns only the package policies for the `nginx` integration:

```shell
curl --request GET \
--url 'https://my-kibana-host:9243/api/fleet/package_policies?kuery=ingest-package-policies.package.name:nginx' \
--header 'Authorization: ApiKey yourbase64encodedkey' \
--header 'kbn-xsrf: xx'
```

For the full query syntax, including wildcards, ranges, and boolean operators, refer to [{{kib}} Query Language (KQL)](elasticsearch://reference/query-languages/kql.md).


## Manually roll back an {{agent}} upgrade [agent-rollback-api]
```{applies_to}
stack: ga 9.3+
```

The manual rollback feature for {{agent}} gives you the ability to roll back to the previously installed version if the install artifacts are still available on disk--typically seven days after the upgrade.
The manual rollback feature for {{agent}} lets you roll back to the previously installed version if the install artifacts are still available on disk (typically seven days after the upgrade).

To roll back a single agent:
:Call `POST /api/fleet/agents/{agentID}/rollback`.
To roll back a single agent, call `POST /api/fleet/agents/{agentID}/rollback`.

To roll back multiple agents:
:Call `POST /api/fleet/agents/bulk_rollback`.
To roll back multiple agents, call `POST /api/fleet/agents/bulk_rollback`.

### Limitations for manual rollback [rollback-limitations-api]

These limitations apply for the manual rollback feature:
These limitations apply for the manual rollback feature:

* Rollback is limited to the version running _before_ the upgrade. Both the previously and currently running versions must be 9.3.0 or later for this functionality to be available.
* Rollback is limited to the version running _before_ the upgrade. Both the pre-upgrade and post-upgrade versions must be 9.3.0 or later for this functionality to be available.
* Data required for the rollback is stored on disk for seven days, which can impact available disk space.
* Rollback must be performed within seven days of the upgrade. Rollback data is automatically cleaned up after seven days and becomes unavailable.
* Manual rollback is not available for system-managed packages such as DEB and RPM.
Expand All @@ -489,6 +511,25 @@ These limitations apply for the manual rollback feature:
If no version is available on disk to rollback to, you get an error.
This situation can happen if:

- the version you upgraded from is earlier than 9.3.0, as the feature is not supported for earlier versions.
- The version you upgraded from is earlier than 9.3.0, as the feature is not supported for earlier versions.

- The rollback window has ended (typically more than seven days). When the rollback window ends, the files from the previous version are removed to free up disk space.


## Next steps [fleet-api-next-steps]

After you create agent and integration policies with the API:

* [Enroll {{agents}}](/reference/fleet/fleet-enrollment-tokens.md) using enrollment tokens from your agent policy
* [Manage {{agents}} in {{fleet}}](/reference/fleet/manage-elastic-agents-in-fleet.md) to monitor status and policy assignments
* [Create an agent policy without using the UI](/reference/fleet/create-policy-no-ui.md) for automation use cases


## Related pages [fleet-api-related-pages]

- the rollback window has ended (typically more than seven days). When the rollback window ends, the files from the previous version are removed to free up disk space.
* [Kibana API docs]({{kib-apis}})
* [Run API requests](/explore-analyze/query-filter/tools/console.md)
* [Roles and privileges](/reference/fleet/fleet-roles-privileges.md)
* [Fleet enrollment tokens](/reference/fleet/fleet-enrollment-tokens.md)

@bmorelli25 bmorelli25 Jun 24, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the same link that's right above this section. I'm not sure how useful it is to list it twice.

* [Grant standalone {{agents}} access to {{es}}](/reference/fleet/grant-access-to-elasticsearch.md)
* [{{kib}} Query Language (KQL)](elasticsearch://reference/query-languages/kql.md)
Loading