From 424a30365e059dc572b3e78685d029d3ff96b07f Mon Sep 17 00:00:00 2001 From: charlotte-hoblik Date: Mon, 22 Jun 2026 19:02:10 +0200 Subject: [PATCH 1/5] add seactiona bout kuery --- reference/fleet/fleet-api-docs.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/reference/fleet/fleet-api-docs.md b/reference/fleet/fleet-api-docs.md index e2382999ee..27fbc235dc 100644 --- a/reference/fleet/fleet-api-docs.md +++ b/reference/fleet/fleet-api-docs.md @@ -461,6 +461,24 @@ curl -X GET 'http://:@/api/fleet/agents?perPage=10000&se ``` +## Filter results with KQL [filter-results-with-kql] + +Many {{fleet}} list endpoints accept a `kuery` query parameter that takes a [{{kib}} Query Language (KQL)](elasticsearch://reference/query-languages/kql.md) string. Use it to return only the items that match a filter, such as a specific integration. + +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. + +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+ From 2a3ad424442ae6fd9a1dd87dc45061b0d5ae0665 Mon Sep 17 00:00:00 2001 From: charlotte-hoblik Date: Mon, 22 Jun 2026 19:16:41 +0200 Subject: [PATCH 2/5] add style review edits --- reference/fleet/fleet-api-docs.md | 32 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/reference/fleet/fleet-api-docs.md b/reference/fleet/fleet-api-docs.md index 27fbc235dc..dcfda2fb8e 100644 --- a/reference/fleet/fleet-api-docs.md +++ b/reference/fleet/fleet-api-docs.md @@ -20,7 +20,7 @@ In this section, we provide examples of some commonly used {{fleet}} APIs. 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**. 2. In your request, prepend your {{fleet}} API endpoint with `kbn:`, for example: ```sh @@ -28,17 +28,17 @@ You can run {{fleet}} API requests through the {{kib}} Console. ``` -For more detail about using the {{kib}} Console refer to [Run API requests](/explore-analyze/query-filter/tools/console.md). +For more details 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). +You must authenticate to send {{fleet}} API requests. For more information, refer to [Authentication]({{kib-apis}}authentication). ## 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. @@ -96,7 +96,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. @@ -109,7 +109,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 \ @@ -414,7 +414,7 @@ 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://:@/api/fleet/agents @@ -463,7 +463,7 @@ curl -X GET 'http://:@/api/fleet/agents?perPage=10000&se ## Filter results with KQL [filter-results-with-kql] -Many {{fleet}} list endpoints accept a `kuery` query parameter that takes a [{{kib}} Query Language (KQL)](elasticsearch://reference/query-languages/kql.md) string. Use it to return only the items that match a filter, such as a specific integration. +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. @@ -484,19 +484,17 @@ For the full query syntax, including wildcards, ranges, and boolean operators, r 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. @@ -507,6 +505,6 @@ 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. +- 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. From e5a1e0756d705f07a6aeb9dca1538a6f0de6f088 Mon Sep 17 00:00:00 2001 From: charlotte-hoblik Date: Mon, 22 Jun 2026 19:18:20 +0200 Subject: [PATCH 3/5] add frontmatter --- reference/fleet/fleet-api-docs.md | 1 + 1 file changed, 1 insertion(+) diff --git a/reference/fleet/fleet-api-docs.md b/reference/fleet/fleet-api-docs.md index dcfda2fb8e..8710eb533b 100644 --- a/reference/fleet/fleet-api-docs.md +++ b/reference/fleet/fleet-api-docs.md @@ -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 From 398e0fb4afa078bb73ad5097fc78686f641dca4e Mon Sep 17 00:00:00 2001 From: charlotte-hoblik Date: Mon, 22 Jun 2026 19:24:34 +0200 Subject: [PATCH 4/5] Improve Fleet API docs structure and navigation --- reference/fleet/fleet-api-docs.md | 40 ++++++++++++++++++++++++------- 1 file changed, 32 insertions(+), 8 deletions(-) diff --git a/reference/fleet/fleet-api-docs.md b/reference/fleet/fleet-api-docs.md index 8710eb533b..93379ab363 100644 --- a/reference/fleet/fleet-api-docs.md +++ b/reference/fleet/fleet-api-docs.md @@ -12,9 +12,19 @@ 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] @@ -32,11 +42,6 @@ You can run {{fleet}} API requests through the {{kib}} Console. For more details about using the {{kib}} Console, refer to [Run API requests](/explore-analyze/query-filter/tools/console.md). -## Authentication [authentication] - -You must authenticate to send {{fleet}} API requests. For more information, refer to [Authentication]({{kib-apis}}authentication). - - ## Create agent policy [create-agent-policy-api] To create an agent policy in {{fleet}}, call `POST /api/fleet/agent_policies`. @@ -418,7 +423,7 @@ Example response (formatted for readability): Use the [Get agents API]({{kib-apis}}operation/operation-get-fleet-agents) to retrieve a list of enrolled {{agents}}: ```shell -curl -X GET 'http://:@/api/fleet/agents +curl -X GET 'http://:@/api/fleet/agents' ``` By default, a maximum of 10,000 agents are returned, with 20 agents listed per page. @@ -509,3 +514,22 @@ 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 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] + +* [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) +* [Grant standalone {{agents}} access to {{es}}](/reference/fleet/grant-access-to-elasticsearch.md) +* [{{kib}} Query Language (KQL)](elasticsearch://reference/query-languages/kql.md) From 353c7352340ff93a73d8b59fb6c4d7eb197b612a Mon Sep 17 00:00:00 2001 From: charlotte-hoblik Date: Mon, 29 Jun 2026 15:40:09 +0200 Subject: [PATCH 5/5] Apply feedback --- reference/fleet/fleet-api-docs.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/reference/fleet/fleet-api-docs.md b/reference/fleet/fleet-api-docs.md index 93379ab363..0d50ccfb2b 100644 --- a/reference/fleet/fleet-api-docs.md +++ b/reference/fleet/fleet-api-docs.md @@ -31,7 +31,7 @@ You'll need: You can run {{fleet}} API requests through the {{kib}} Console. -1. From the {{kib}} menu, go to **Management → Dev Tools**. +1. To open **Console**, find **Dev Tools** in the main menu or use the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). 2. In your request, prepend your {{fleet}} API endpoint with `kbn:`, for example: ```sh @@ -469,11 +469,18 @@ curl -X GET 'http://:@/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}}). +The following {{fleet}} list endpoints accept a `kuery` query parameter that takes a [{{kib}} Query Language (KQL)](elasticsearch://reference/query-languages/kql.md) string to filter results: agents (`GET /api/fleet/agents`), agent policies (`GET /api/fleet/agent_policies`), package policies (`GET /api/fleet/package_policies`), and enrollment tokens (`GET /api/fleet/enrollment_api_keys`). 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. +**Agents and enrollment tokens** are stored in {{es}} system indices. Reference fields directly, with no prefix. This cURL example returns only the online agents: -This cURL example returns only the package policies for the `nginx` integration: +```shell +curl --request GET \ + --url 'https://my-kibana-host:9243/api/fleet/agents?kuery=status:online' \ + --header 'Authorization: ApiKey yourbase64encodedkey' \ + --header 'kbn-xsrf: xx' +``` + +**Agent policies and package policies** are stored as saved objects. When a field path contains a dot, prefix it with the saved object type so the query parser reads it as a field name and not as a type. This cURL example returns only the package policies for the `nginx` integration: ```shell curl --request GET \ @@ -482,6 +489,10 @@ curl --request GET \ --header 'kbn-xsrf: xx' ``` +::::{tip} +The accepted saved object type prefix can differ across deployments and endpoints. If a query returns a `KQLSyntaxError` stating that a key does not exist in a saved object index pattern, use the index pattern named in the error as your prefix. For example, if the error names `ingest-agent-policies`, query `ingest-agent-policies.name`. +:::: + For the full query syntax, including wildcards, ranges, and boolean operators, refer to [{{kib}} Query Language (KQL)](elasticsearch://reference/query-languages/kql.md). @@ -530,6 +541,5 @@ After you create agent and integration policies with the API: * [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) * [Grant standalone {{agents}} access to {{es}}](/reference/fleet/grant-access-to-elasticsearch.md) * [{{kib}} Query Language (KQL)](elasticsearch://reference/query-languages/kql.md)