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

Merged
charlotte-hoblik merged 7 commits into from
Jul 1, 2026
Merged

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

Changes from 4 commits
Commits
Show all changes
7 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
353c735
Apply feedback
charlotte-hoblik Jun 29, 2026
1550e2f
Broaden KQL prefix tip to cover both errors
charlotte-hoblik Jul 1, 2026
4ebd822
Merge branch 'main' into charlotte-Kuery-3401
charlotte-hoblik Jul 1, 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**.
Comment thread
charlotte-hoblik marked this conversation as resolved.
Outdated
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.

@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>").

@charlotte-hoblik charlotte-hoblik Jun 29, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Thanks so much, both of you, this was really helpful. I tested it all on a 9.4.2 cluster and your breakdown held up, with one surprise.

fleet-agent-policies. doesn't actually work on 9.4.2. It 400s, and only ingest-agent-policies. or a bare name:"..." work, even though the data is stored under the fleet-* types (confirmed with a type agg on .kibana*).

In the doc I went with bare fields where possible, prefixed only nested fields like package.name, and added a tip that the KQLSyntaxError names the exact pattern to use.

@vishaangelova does fleet-agent-policies. work for you on main? Thanks again.

@bmorelli25 bmorelli25 Jun 30, 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 can confirm that fleet-agent-policies.name 400s and the following actually work:

GET kbn:/api/fleet/agent_policies?kuery=ingest-agent-policies.name:"Elastic Cloud agent policy"
GET kbn:/api/fleet/agent_policies?kuery=name:"Elastic Cloud agent policy"

Tested on 9.4.3 (unreleased)

@vishaangelova vishaangelova Jun 30, 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.

Hi @paul-tavares, pulling you in this thread to confirm if the way this works is by design:

On GET /api/fleet/agent_policies, the kuery validator rejects the fleet-agent-policies.<field> prefix (returns a 400 KQLSyntaxError), so only ingest-agent-policies.<field> or bare fields work. On GET /api/fleet/package_policies the validator was widened to accept both prefixes as part of elastic/kibana#227862, but the equivalent change doesn't seem to have been made for agent policies. Wondering if this was intentional, so we can document the right prefix?

@vishaangelova vishaangelova Jun 30, 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.

Sorry, after checking with Paul, it seems maybe @criamico could help instead?

@criamico criamico Jun 30, 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.

On GET /api/fleet/agent_policies, the kuery validator rejects the fleet-agent-policies. prefix (returns a 400 KQLSyntaxError), so only ingest-agent-policies. or bare fields work.

I just checked the code and verified that the KQL validator rejects any kuery prefixed with fleet-agent-policies. This was probably missed when doing the work for space awareness. It is actually a bug, so I'll open a ticket to track it.

@criamico criamico Jul 1, 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.

Link to ticket for the KQL bug: elastic/kibana#275810


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)
Comment thread
charlotte-hoblik marked this conversation as resolved.
Outdated
* [Grant standalone {{agents}} access to {{es}}](/reference/fleet/grant-access-to-elasticsearch.md)
* [{{kib}} Query Language (KQL)](elasticsearch://reference/query-languages/kql.md)
Loading