--- title: Kibana Fleet APIs 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. url: https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7067/reference/fleet/fleet-api-docs products: - Elastic Agent - Fleet applies_to: - Elastic Cloud Serverless: Generally available - Elastic Stack: Generally available --- # Kibana Fleet APIs This page provides cURL and Kibana Console examples for commonly used Fleet APIs, including agent policies, integration policies, enrollment tokens, agent listing, KQL filtering, and agent rollback. For full endpoint specifications, parameters, and response schemas, refer to the [Kibana API docs](https://www.elastic.co/docs/api/doc/kibana/). For Elastic Cloud Serverless projects, use the [Kibana Serverless API docs](https://www.elastic.co/docs/api/doc/serverless/). ## Before you begin You'll need: - A running Kibana deployment or Elastic Cloud Serverless project with Fleet available - The Kibana host URL for your deployment (for example, `https://my-kibana-host:9243`) - Authentication credentials for Kibana API requests. API key authentication is recommended. For details, refer to [Authentication](https://www.elastic.co/docs/api/doc/kibana/authentication). - A Kibana user with the required Fleet and Integrations privileges. For details, refer to [Roles and privileges](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7067/reference/fleet/fleet-roles-privileges). ## Using the Console You can run Fleet API requests through the Kibana Console. 1. From the Kibana menu, go to **Management → Dev Tools**. 2. In your request, prepend your Fleet API endpoint with `kbn:`, for example: ```sh GET kbn:/api/fleet/agent_policies ``` For more details about using the Kibana Console, refer to [Run API requests](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7067/explore-analyze/query-filter/tools/console). ## Create agent policy 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. ```shell curl --request POST \ --url 'https://my-kibana-host:9243/api/fleet/agent_policies?sys_monitoring=true' \ --header 'Accept: */*' \ --header 'Authorization: ApiKey yourbase64encodedkey' \ --header 'Cache-Control: no-cache' \ --header 'Connection: keep-alive' \ --header 'Content-Type: application/json' \ --header 'kbn-xsrf: xxx' \ --data '{ "name": "Agent policy 1", "description": "", "namespace": "default", "monitoring_enabled": [ "logs", "metrics" ] }' ``` To save time, you can use Kibana to generate the API request, then run it from the Dev Tools console. 1. Go to **Fleet → Agent policies**. 2. Click **Create agent policy** and give the policy a name. 3. Click **Preview API request**. 4. Click **Open in Console** and run the request. Example response: ```shell { "item": { "id": "2b820230-4b54-11ed-b107-4bfe66d759e4", "name": "Agent policy 1", "description": "", "namespace": "default", "monitoring_enabled": [ "logs", "metrics" ], "status": "active", "is_managed": false, "revision": 1, "updated_at": "2022-10-14T00:07:19.763Z", "updated_by": "1282607447", "schema_version": "1.0.0" } } ``` ## Create integration policy To create an integration policy (also known as a package policy) and add it to an existing agent policy, call `POST /api/fleet/package_policies`. You can use the Fleet API to [Create and customize an Elastic Defend policy](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7067/solutions/security/configure-elastic-defend/create-an-elastic-defend-policy-using-api). 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 \ --url 'https://my-kibana-host:9243/api/fleet/package_policies' \ --header 'Authorization: ApiKey yourbase64encodedkey' \ --header 'Content-Type: application/json' \ --header 'kbn-xsrf: xx' \ --data '{ "name": "nginx-demo-123", "policy_id": "2b820230-4b54-11ed-b107-4bfe66d759e4", "package": { "name": "nginx", "version": "1.5.0" }, "inputs": { "nginx-logfile": { "streams": { "nginx.access": { "vars": { "tags": [ "test" ] } }, "nginx.error": { "vars": { "tags": [ "test" ] } } } } } }' ``` - To save time, you can use Kibana to generate the API call, then run it from the Dev Tools console. 1. Go to **Integrations**, select an Elastic Agent integration, and click **Add **. 2. Configure the integration settings and select which agent policy to use. 3. Click **Preview API request**. If you’re creating the integration policy for a new agent policy, the preview shows two requests: one to create the agent policy, and another to create the integration policy. 4. Click **Open in Console** and run the request (or requests). - To find out which inputs, streams, and variables are available for an integration, go to **Integrations**, select an Elastic Agent integration, and click **API reference**. Example response (truncated for readability): ```shell { "item" : { "created_at" : "2022-10-15T00:41:28.594Z", "created_by" : "1282607447", "enabled" : true, "id" : "92f33e57-3165-4dcd-a1d5-f01c8ffdcbcd", "inputs" : [ { "enabled" : true, "policy_template" : "nginx", "streams" : [ { "compiled_stream" : { "exclude_files" : [ ".gz$" ], "ignore_older" : "72h", "paths" : [ "/var/log/nginx/access.log*" ], "processors" : [ { "add_locale" : null } ], "tags" : [ "test" ] }, "data_stream" : { "dataset" : "nginx.access", "type" : "logs" }, "enabled" : true, "id" : "logfile-nginx.access-92f33e57-3165-4dcd-a1d5-f01c8ffdcbcd", "release" : "ga", "vars" : { "ignore_older" : { "type" : "text", "value" : "72h" }, "paths" : { "type" : "text", "value" : [ "/var/log/nginx/access.log*" ] }, "preserve_original_event" : { "type" : "bool", "value" : false }, "processors" : { "type" : "yaml" }, "tags" : { "type" : "text", "value" : [ "test" ] } } }, { "compiled_stream" : { "exclude_files" : [ ".gz$" ], "ignore_older" : "72h", "multiline" : { "match" : "after", "negate" : true, "pattern" : "^\\d{4}\\/\\d{2}\\/\\d{2} " }, "paths" : [ "/var/log/nginx/error.log*" ], "processors" : [ { "add_locale" : null } ], "tags" : [ "test" ] }, "data_stream" : { "dataset" : "nginx.error", "type" : "logs" }, "enabled" : true, "id" : "logfile-nginx.error-92f33e57-3165-4dcd-a1d5-f01c8ffdcbcd", "release" : "ga", "vars" : { "ignore_older" : { "type" : "text", "value" : "72h" }, "paths" : { "type" : "text", "value" : [ "/var/log/nginx/error.log*" ] }, "preserve_original_event" : { "type" : "bool", "value" : false }, "processors" : { "type" : "yaml" }, "tags" : { "type" : "text", "value" : [ "test" ] } } } ], "type" : "logfile" }, ... { "enabled" : true, "policy_template" : "nginx", "streams" : [ { "compiled_stream" : { "hosts" : [ "http://127.0.0.1:80" ], "metricsets" : [ "stubstatus" ], "period" : "10s", "server_status_path" : "/nginx_status" }, "data_stream" : { "dataset" : "nginx.stubstatus", "type" : "metrics" }, "enabled" : true, "id" : "nginx/metrics-nginx.stubstatus-92f33e57-3165-4dcd-a1d5-f01c8ffdcbcd", "release" : "ga", "vars" : { "period" : { "type" : "text", "value" : "10s" }, "server_status_path" : { "type" : "text", "value" : "/nginx_status" } } } ], "type" : "nginx/metrics", "vars" : { "hosts" : { "type" : "text", "value" : [ "http://127.0.0.1:80" ] } } } ], "name" : "nginx-demo-123", "namespace" : "default", "package" : { "name" : "nginx", "title" : "Nginx", "version" : "1.5.0" }, "policy_id" : "d625b2e0-4c21-11ed-9426-31f0877749b7", "revision" : 1, "updated_at" : "2022-10-15T00:41:28.594Z", "updated_by" : "1282607447", "version" : "WzI5OTAsMV0=" } } ``` ## Get enrollment tokens To get a list of valid enrollment tokens from Fleet, call `GET /api/fleet/enrollment_api_keys`. This cURL example returns a list of enrollment tokens. ```shell curl --request GET \ --url 'https://my-kibana-host:9243/api/fleet/enrollment_api_keys' \ --header 'Authorization: ApiKey N2VLRDA0TUJIQ05MaGYydUZrN1Y6d2diMUdwSkRTWGFlSm1rSVZlc2JGQQ==' \ --header 'Content-Type: application/json' \ --header 'kbn-xsrf: xx' ``` Example response (formatted for readability): ```shell { "items" : [ { "active" : true, "api_key" : "QlN2UaA0TUJlMGFGbF8IVkhJaHM6eGJjdGtyejJUUFM0a0dGSwlVSzdpdw==", "api_key_id" : "BSvR04MBe0aFl_HVHIhs", "created_at" : "2022-10-14T00:07:21.420Z", "id" : "39703af4-5945-4232-90ae-3161214512fa", "name" : "Default (39703af4-5945-4232-90ae-3161214512fa)", "policy_id" : "2b820230-4b54-11ed-b107-4bfe66d759e4" }, { "active" : true, "api_key" : "Yi1MSTA2TUJIQ05MaGYydV9kZXQ5U2dNWFkyX19sWEdSemFQOUfzSDRLZw==", "api_key_id" : "b-LI04MBHCNLhf2u_det", "created_at" : "2022-10-13T23:58:29.266Z", "id" : "e4768bf2-55a6-433f-a540-51d4ca2d34be", "name" : "Default (e4768bf2-55a6-433f-a540-51d4ca2d34be)", "policy_id" : "ee37a8e0-4b52-11ed-b107-4bfe66d759e4" }, { "active" : true, "api_key" : "b3VLbjA0TUJIQ04MaGYydUk1Z3Q6VzhMTTBITFRTmnktRU9IWDaXWnpMUQ==", "api_key_id" : "luKn04MBHCNLhf2uI5d4", "created_at" : "2022-10-13T23:21:30.707Z", "id" : "d18d2918-bb10-44f2-9f98-df5543e21724", "name" : "Default (d18d2918-bb10-44f2-9f98-df5543e21724)", "policy_id" : "c3e31e80-4b4d-11ed-b107-4bfe66d759e4" }, { "active" : true, "api_key" : "V3VLRTa0TUJIQ05MaGYydVMx4S06WjU5dsZ3YzVRSmFUc5xjSThImi1ydw==", "api_key_id" : "WuKE04MBHCNLhf2uS1E-", "created_at" : "2022-10-13T22:43:27.139Z", "id" : "aad31121-df89-4f57-af84-7c43f72640ee", "name" : "Default (aad31121-df89-4f57-af84-7c43f72640ee)", "policy_id" : "72fcc4d0-4b48-11ed-b107-4bfe66d759e4" }, ], "page" : 1, "perPage" : 20, "total" : 4 } ``` ## List all Elastic Agents Use the [Get agents API](https://www.elastic.co/docs/api/doc/kibana/operation/operation-get-fleet-agents) to retrieve a list of enrolled Elastic Agents: ```shell curl -X GET 'http://:@/api/fleet/agents' ``` By default, a maximum of 10,000 agents are returned, with 20 agents listed per page. ### List all Elastic Agents with `perPage` setting The following query returns the same list, showing 10,000 Elastic Agents per page: ```shell curl -X GET 'http://:@/api/fleet/agents?perPage=10000' ``` ### List the next set of 10,000 Elastic Agents - Elastic Stack: Generally available since 9.1 Beginning with Elastic Stack version 9.1, the previous query response includes a `nextSearchAfter` parameter that you can pass in a subsequent call, to retrieve the next page of 10,000 enrolled agents: ```shell curl -X GET 'http://:@/api/fleet/agents?perPage=10000&searchAfter=' ``` ### List all Elastic Agents for a point in time - Elastic Stack: Generally available since 9.1 Beginning with Elastic Stack version 9.1, you can also capture a point-in-time ID (`pitId`) parameter from the `Get agents API` response, and use that together with the `nextSearchAfter` parameter to capture the next page of 10,000 enrolled agents for a specific point in time. Include the `openPit` and `pitKeepAlive` parameters in your initial request: ```shell curl -X GET 'http://:@/api/fleet/agents?perPage=10000&openPit=true&pitKeepAlive=5m' ``` You can then use the returned values in a new request to retrieve the next set of 10,000 agents: ```shell curl -X GET 'http://:@/api/fleet/agents?perPage=10000&searchAfter=&pitId=&pitKeepAlive=5m' ``` ## 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 [Kibana Query Language (KQL)](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/kql) string to filter results. To check whether another endpoint accepts `kuery`, refer to its parameters in the [Kibana API docs](https://www.elastic.co/docs/api/doc/kibana/). 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 [Kibana Query Language (KQL)](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/kql). ## Manually roll back an Elastic Agent upgrade - Elastic Stack: Generally available since 9.3 The manual rollback feature for Elastic 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 multiple agents, call `POST /api/fleet/agents/bulk_rollback`. ### Limitations for manual rollback These limitations apply for the manual rollback feature: - 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. - Some data might be re-ingested after rollback. #### Possible errors 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 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 After you create agent and integration policies with the API: - [Enroll Elastic Agents](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7067/reference/fleet/fleet-enrollment-tokens) using enrollment tokens from your agent policy - [Manage Elastic Agents in Fleet](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7067/reference/fleet/manage-elastic-agents-in-fleet) to monitor status and policy assignments - [Create an agent policy without using the UI](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7067/reference/fleet/create-policy-no-ui) for automation use cases ## Related pages - [Kibana API docs](https://www.elastic.co/docs/api/doc/kibana/) - [Run API requests](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7067/explore-analyze/query-filter/tools/console) - [Roles and privileges](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7067/reference/fleet/fleet-roles-privileges) - [Fleet enrollment tokens](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7067/reference/fleet/fleet-enrollment-tokens) - [Grant standalone Elastic Agents access to Elasticsearch](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/7067/reference/fleet/grant-access-to-elasticsearch) - [Kibana Query Language (KQL)](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/kql)