Bulk unenroll agents

POST /api/fleet/agents/bulk_unenroll
Api key auth Basic auth

Spaces method and path for this operation:

post /s/{space_id}/api/fleet/agents/bulk_unenroll

Refer to Spaces for more information.

Unenroll multiple agents. By default, the agents stop sending data and their API keys are invalidated after they acknowledge the unenroll action. To invalidate the API keys immediately, use revoke. Force unenroll in the UI sends revoke: true.

[Required authorization] Route required privileges: fleet-agents-all.

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

application/json

Body

  • agents array[string] | string Required
    Any of:
    array-1 array[string] string-2 string

    list of agent IDs

    Not more than 10000 elements. Maximum length of each is 512.

    KQL query string, leave empty to action all agents

    Maximum length is 500000.

  • batchSize number
  • dryRun boolean
  • force boolean

    Also unenrolls agents that are enrolled in hosted agent policies or are managed agents. Does not revoke API keys immediately. To do so, also set revoke.

  • includeInactive boolean

    When passing agents by KQL query, unenrolls inactive agents too

  • revoke boolean

    Immediately invalidates the API keys of the agents without notifying them. The agents keep running and can still send data to outputs not covered by the invalidated keys, such as Kafka and Logstash. Remote Elasticsearch keys are invalidated by Fleet Server on a best-effort basis. This action cannot be undone. Use it only for offline or compromised agents.

Responses

  • 200 application/json

    Successful response

    Any of:
    object-1 object object-2 object
  • 400 application/json

    Bad Request

    Hide response attributes Show response attributes object
    • attributes Required
    • error string
    • errorType string
    • message string Required
    • statusCode number
POST /api/fleet/agents/bulk_unenroll 
curl \
 --request POST 'https://localhost:5601/api/fleet/agents/bulk_unenroll' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{
  "agents": [
    "agent-id-1",
    "agent-id-2"
  ],
  "revoke": false
}'
Request example
Unenroll multiple agents 
{
  "agents": [
    "agent-id-1",
    "agent-id-2"
  ],
  "revoke": false
}
Response examples (200)
Bulk unenroll action result 
{
  "actionId": "action-id-1"
}
Response examples (400)
Example of a generic error response 
{
  "error": "Bad Request",
  "message": "An error message describing what went wrong",
  "statusCode": 400
}