Update the API key for a rule

POST /api/alerting/rule/{id}/_update_api_key
Api key auth

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    The identifier for the rule.

Responses

  • 204

    Indicates a successful call.

  • 400

    Indicates an invalid schema or parameters.

  • 403

    Indicates that this call is forbidden.

  • 404

    Indicates a rule with the given ID does not exist.

  • 409

    Indicates that the rule has already been updated by another user.

POST /api/alerting/rule/{id}/_update_api_key 
curl \
 --request POST 'https://<KIBANA_URL>/api/alerting/rule/{id}/_update_api_key' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Mute an alert

POST /api/alerting/rule/{rule_id}/alert/{alert_id}/_mute
Api key auth

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • rule_id string Required

    The identifier for the rule.

  • alert_id string Required

    The identifier for the alert.

Responses

  • 204

    Indicates a successful call.

  • 400

    Indicates an invalid schema or parameters.

  • 403

    Indicates that this call is forbidden.

  • 404

    Indicates a rule or alert with the given ID does not exist.

POST /api/alerting/rule/{rule_id}/alert/{alert_id}/_mute 
curl \
 --request POST 'https://<KIBANA_URL>/api/alerting/rule/{rule_id}/alert/{alert_id}/_mute' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

APM agent configuration

Adjust APM agent configuration without need to redeploy your application.

Delete agent configuration

DELETE /api/apm/settings/agent-configuration
Api key auth

Headers

  • elastic-api-version string Required

    The version of the API to use

    Value is 2023-10-31. Default value is 2023-10-31.

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

application/json

Body Required

Responses

  • 200 application/json

    Successful response

    Hide response attribute Show response attribute object
  • 400 application/json

    Bad Request response

    Hide response attributes Show response attributes object
  • 401 application/json

    Unauthorized response

    Hide response attributes Show response attributes object
  • 403 application/json

    Forbidden response

    Hide response attributes Show response attributes object
  • 404 application/json

    Not found response

    Hide response attributes Show response attributes object
DELETE /api/apm/settings/agent-configuration 
curl \
 --request DELETE 'https://<KIBANA_URL>/api/apm/settings/agent-configuration' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "elastic-api-version: 2023-10-31" \
 --header "kbn-xsrf: true" \
 --data '"{\n    \"service\" : {\n        \"name\": \"frontend\",\n        \"environment\": \"production\"\n    }\n}\n"'
Request example
Run `DELETE /api/apm/settings/agent-configuration` to delete a configuration. 
{
    "service" : {
        "name": "frontend",
        "environment": "production"
    }
}

Search for annotations

GET /api/apm/services/{serviceName}/annotation/search
Api key auth

Search for annotations related to a specific service.

Headers

  • elastic-api-version string Required

    The version of the API to use

    Value is 2023-10-31. Default value is 2023-10-31.

Path parameters

Query parameters

  • environment string

    The environment to filter annotations by

  • start string

    The start date for the search

  • end string

    The end date for the search

Responses

  • 200 application/json

    Successful response

    Hide response attribute Show response attribute object
  • 400 application/json

    Bad Request response

    Hide response attributes Show response attributes object
  • 401 application/json

    Unauthorized response

    Hide response attributes Show response attributes object
  • 500 application/json

    Internal Server Error response

    Hide response attributes Show response attributes object
GET /api/apm/services/{serviceName}/annotation/search 
curl \
 --request GET 'https://<KIBANA_URL>/api/apm/services/{serviceName}/annotation/search' \
 --header "Authorization: $API_KEY" \
 --header "elastic-api-version: 2023-10-31"

Get data streams

GET /api/fleet/data_streams
Api key auth

[Required authorization] Route required privileges: fleet-agents-all AND fleet-agent-policies-all AND fleet-settings-all.

Responses

GET /api/fleet/data_streams 
curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/data_streams' \
 --header "Authorization: $API_KEY"

Get data streams

GET /api/fleet/epm/data_streams
Api key auth

[Required authorization] Route required privileges: integrations-read OR fleet-setup OR fleet-all.

Query parameters

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • items array[object] Required
      Hide items attribute Show items attribute object
  • 400 application/json
    Hide response attributes Show response attributes object
GET /api/fleet/epm/data_streams 
curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/epm/data_streams' \
 --header "Authorization: $API_KEY"

Update data view fields metadata

POST /api/data_views/data_view/{viewId}/fields
Api key auth

Update fields presentation metadata such as count, customLabel, customDescription, and format.

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

Path parameters

  • viewId string Required

    An identifier for the data view.

application/json

Body Required

  • fields object Required

    The field object.

Responses

  • 200 application/json

    Indicates a successful call.

    Hide response attribute Show response attribute object
  • 400 application/json

    Bad request

    Hide response attributes Show response attributes object
POST /api/data_views/data_view/{viewId}/fields 
curl \
 --request POST 'https://<KIBANA_URL>/api/data_views/data_view/ff959d40-b880-11e8-a6d9-e546fe2bba5f/fields' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"fields":{"field1":{"count":123,"customLabel":"Field 1 label"},"field2":{"customLabel":"Field 2 label","customDescription":"Field 2 description"}}}'
Request example 
{
  "fields": {
    "field1": {
      "count": 123,
      "customLabel": "Field 1 label"
    },
    "field2": {
      "customLabel": "Field 2 label",
      "customDescription": "Field 2 description"
    }
  }
}

Update a runtime field

POST /api/data_views/data_view/{viewId}/runtime_field/{fieldName}
Api key auth

Path parameters

  • fieldName string Required

    The name of the runtime field.

  • viewId string Required

    An identifier for the data view.

application/json

Body Required

  • runtimeField object Required

    The runtime field definition object.

    You can update following fields:

    • type
    • script

Responses

  • 200

    Indicates a successful call.

  • 400 application/json

    Bad request

    Hide response attributes Show response attributes object
POST /api/data_views/data_view/{viewId}/runtime_field/{fieldName} 
curl \
 --request POST 'https://<KIBANA_URL>/api/data_views/data_view/ff959d40-b880-11e8-a6d9-e546fe2bba5f/runtime_field/hour_of_day' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"runtimeField":{"script":{"source":"emit(doc[\"bar\"].value)"}}}'
Request example 
{
  "runtimeField": {
    "script": {
      "source": "emit(doc[\"bar\"].value)"
    }
  }
}

Delete a runtime field from a data view

DELETE /api/data_views/data_view/{viewId}/runtime_field/{fieldName}
Api key auth

Path parameters

  • fieldName string Required

    The name of the runtime field.

  • viewId string Required

    An identifier for the data view.

Responses

  • 200

    Indicates a successful call.

  • 404 application/json

    Object is not found.

    Hide response attributes Show response attributes object
DELETE /api/data_views/data_view/{viewId}/runtime_field/{fieldName} 
curl \
 --request DELETE 'https://<KIBANA_URL>/api/data_views/data_view/ff959d40-b880-11e8-a6d9-e546fe2bba5f/runtime_field/hour_of_day' \
 --header "Authorization: $API_KEY"

Get the default data view

GET /api/data_views/default
Api key auth

Responses

  • 200 application/json

    Indicates a successful call.

    Hide response attribute Show response attribute object
  • 400 application/json

    Bad request

    Hide response attributes Show response attributes object
GET /api/data_views/default 
curl \
 --request GET 'https://<KIBANA_URL>/api/data_views/default' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "data_view_id": "ff959d40-b880-11e8-a6d9-e546fe2bba5f"
}

Set the default data view

POST /api/data_views/default
Api key auth

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

application/json

Body Required

  • data_view_id string | null Required

    The data view identifier. NOTE: The API does not validate whether it is a valid identifier. Use null to unset the default data view.

  • force boolean

    Update an existing default data view identifier.

    Default value is false.

Responses

  • 200 application/json

    Indicates a successful call.

    Hide response attribute Show response attribute object
  • 400 application/json

    Bad request

    Hide response attributes Show response attributes object
POST /api/data_views/default 
curl \
 --request POST 'https://<KIBANA_URL>/api/data_views/default' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"force":true,"data_view_id":"ff959d40-b880-11e8-a6d9-e546fe2bba5f"}'
Request example 
{
  "force": true,
  "data_view_id": "ff959d40-b880-11e8-a6d9-e546fe2bba5f"
}

Bulk update agent tags

POST /api/fleet/agents/bulk_update_agent_tags
Api key auth

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

application/json

Body

Responses

POST /api/fleet/agents/bulk_update_agent_tags 
curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/agents/bulk_update_agent_tags' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"agents":["string"],"batchSize":42.0,"includeInactive":false,"tagsToAdd":["string"],"tagsToRemove":["string"]}'

Elastic Agent binary download sources

Get agent binary download sources

GET /api/fleet/agent_download_sources
Api key auth

[Required authorization] Route required privileges: fleet-agent-policies-read OR fleet-settings-read.

Responses

GET /api/fleet/agent_download_sources 
curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agent_download_sources' \
 --header "Authorization: $API_KEY"

Bulk get agent policies

POST /api/fleet/agent_policies/_bulk_get
Api key auth

[Required authorization] Route required privileges: fleet-agent-policies-read OR fleet-agents-read OR fleet-setup.

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Query parameters

  • format string

    Values are simplified or legacy.

application/json

Body

  • full boolean

    get full policies with package policies populated

  • ids array[string] Required

    list of package policy ids

  • ignoreMissing boolean

Responses

POST /api/fleet/agent_policies/_bulk_get 
curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/agent_policies/_bulk_get' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"full":true,"ids":["string"],"ignoreMissing":true}'

Get a full agent policy

GET /api/fleet/agent_policies/{agentPolicyId}/full
Api key auth

Get a full agent policy by ID.

[Required authorization] Route required privileges: fleet-agent-policies-read.

Responses

GET /api/fleet/agent_policies/{agentPolicyId}/full 
curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agent_policies/{agentPolicyId}/full' \
 --header "Authorization: $API_KEY"

Delete an agent policy

POST /api/fleet/agent_policies/delete
Api key auth

Delete an agent policy by ID.

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

application/json

Body

Responses

POST /api/fleet/agent_policies/delete 
curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/agent_policies/delete' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"agentPolicyId":"string","force":true}'

Get agent uploads

GET /api/fleet/agents/{agentId}/uploads
Api key auth

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

Responses

GET /api/fleet/agents/{agentId}/uploads 
curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agents/{agentId}/uploads' \
 --header "Authorization: $API_KEY"

Get available agent versions

GET /api/fleet/agents/available_versions
Api key auth

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

Responses

GET /api/fleet/agents/available_versions 
curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agents/available_versions' \
 --header "Authorization: $API_KEY"

Delete an uploaded file

DELETE /api/fleet/agents/files/{fileId}
Api key auth

Delete a file uploaded by an agent.

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Responses

DELETE /api/fleet/agents/files/{fileId} 
curl \
 --request DELETE 'https://<KIBANA_URL>/api/fleet/agents/files/{fileId}' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Get agent setup info

GET /api/fleet/agents/setup
Api key auth

[Required authorization] Route required privileges: fleet-agents-read OR fleet-agent-policies-read OR fleet-settings-read OR fleet-setup.

Responses

GET /api/fleet/agents/setup 
curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agents/setup' \
 --header "Authorization: $API_KEY"

Get agent tags

GET /api/fleet/agents/tags
Api key auth

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

Query parameters

Responses

GET /api/fleet/agents/tags 
curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agents/tags' \
 --header "Authorization: $API_KEY"

Get a package file

GET /api/fleet/epm/packages/{pkgName}/{pkgVersion}/{filePath}
Api key auth

[Required authorization] Route required privileges: integrations-read OR fleet-setup OR fleet-all.

Path parameters

Responses

GET /api/fleet/epm/packages/{pkgName}/{pkgVersion}/{filePath} 
curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/epm/packages/{pkgName}/{pkgVersion}/{filePath}' \
 --header "Authorization: $API_KEY"

Get installed packages

GET /api/fleet/epm/packages/installed
Api key auth

[Required authorization] Route required privileges: integrations-read OR fleet-setup OR fleet-all.

Query parameters

Responses

GET /api/fleet/epm/packages/installed 
curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/epm/packages/installed' \
 --header "Authorization: $API_KEY"

Get an inputs template

GET /api/fleet/epm/templates/{pkgName}/{pkgVersion}/inputs
Api key auth

[Required authorization] Route required privileges: integrations-read OR fleet-setup OR fleet-all.

Path parameters

Query parameters

Responses

GET /api/fleet/epm/templates/{pkgName}/{pkgVersion}/inputs 
curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/epm/templates/{pkgName}/{pkgVersion}/inputs' \
 --header "Authorization: $API_KEY"

Get enrollment API keys

GET /api/fleet/enrollment_api_keys
Api key auth

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

Query parameters

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • items array[object] Required
      Hide items attributes Show items attributes object
      • active boolean Required

        When false, the enrollment API key is revoked and cannot be used for enrolling Elastic Agents.

      • api_key string Required

        The enrollment API key (token) used for enrolling Elastic Agents.

      • api_key_id string Required

        The ID of the API key in the Security API.

      • created_at string Required
      • hidden boolean
      • id string Required
      • name string

        The name of the enrollment API key.

      • policy_id string

        The ID of the agent policy the Elastic Agent will be enrolled in.

    • list array[object] Required Deprecated
      Hide list attributes Show list attributes object
      • active boolean Required

        When false, the enrollment API key is revoked and cannot be used for enrolling Elastic Agents.

      • api_key string Required

        The enrollment API key (token) used for enrolling Elastic Agents.

      • api_key_id string Required

        The ID of the API key in the Security API.

      • created_at string Required
      • hidden boolean
      • id string Required
      • name string

        The name of the enrollment API key.

      • policy_id string

        The ID of the agent policy the Elastic Agent will be enrolled in.

    • page number Required
    • perPage number Required
    • total number Required
  • 400 application/json
    Hide response attributes Show response attributes object
GET /api/fleet/enrollment_api_keys 
curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/enrollment_api_keys' \
 --header "Authorization: $API_KEY"

Create an enrollment API key

POST /api/fleet/enrollment_api_keys
Api key auth

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

application/json

Body

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • action string Required

      Value is created.

    • item object Required

      Additional properties are NOT allowed.

      Hide item attributes Show item attributes object
      • active boolean Required

        When false, the enrollment API key is revoked and cannot be used for enrolling Elastic Agents.

      • api_key string Required

        The enrollment API key (token) used for enrolling Elastic Agents.

      • api_key_id string Required

        The ID of the API key in the Security API.

      • created_at string Required
      • hidden boolean
      • id string Required
      • name string

        The name of the enrollment API key.

      • policy_id string

        The ID of the agent policy the Elastic Agent will be enrolled in.
  • 400 application/json
    Hide response attributes Show response attributes object
POST /api/fleet/enrollment_api_keys 
curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/enrollment_api_keys' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"expiration":"string","name":"string","policy_id":"string"}'

Get settings

GET /api/fleet/settings
Api key auth

[Required authorization] Route required privileges: fleet-settings-read.

Responses

GET /api/fleet/settings 
curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/settings' \
 --header "Authorization: $API_KEY"

Fleet outputs

Get proxies

GET /api/fleet/proxies
Api key auth

[Required authorization] Route required privileges: fleet-settings-read.

Responses

GET /api/fleet/proxies 
curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/proxies' \
 --header "Authorization: $API_KEY"

Delete a Fleet Server host

DELETE /api/fleet/fleet_server_hosts/{itemId}
Api key auth

Delete a Fleet Server host by ID.

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Responses

DELETE /api/fleet/fleet_server_hosts/{itemId} 
curl \
 --request DELETE 'https://<KIBANA_URL>/api/fleet/fleet_server_hosts/{itemId}' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Saved objects

Export or import sets of saved objects.

To manage a specific type of saved object, use the corresponding APIs. For example, use:

Data views.

Security AI assistant

Manage and interact with Security Assistant resources.

Deletes a single Knowledge Base Entry using the `id` field

DELETE /api/security_ai_assistant/knowledge_base/entries/{id}
Api key auth

Deletes a single Knowledge Base Entry using the id field

Path parameters

  • id string(nonempty) Required

    The Knowledge Base Entry's id value

    Minimum length is 1.

Responses

  • 200 application/json

    Successful request returning the deleted Knowledge Base Entry's ID

    Hide response attribute Show response attribute object
    • id string(nonempty) Required

      A string that does not contain only whitespace characters

      Minimum length is 1.
  • 400 application/json

    Generic Error

    Hide response attributes Show response attributes object
DELETE /api/security_ai_assistant/knowledge_base/entries/{id} 
curl \
 --request DELETE 'https://<KIBANA_URL>/api/security_ai_assistant/knowledge_base/entries/{id}' \
 --header "Authorization: $API_KEY"

Security detections

Use the detections APIs to create and manage detection rules. Detection rules search events and external alerts sent to Elastic Security and generate detection alerts from any hits. Alerts are displayed on the Alerts page and can be assigned and triaged, using the alert status to mark them as open, closed, or acknowledged.

This API supports both key-based authentication and basic authentication.

To use key-based authentication, create an API key, then specify the key in the header of your API calls.

To use basic authentication, provide a username and password; this automatically creates an API key that matches the current user’s privileges.

In both cases, the API key is subsequently used for authorization when the rule runs.

If the API key used for authorization has different privileges than the key that created or most recently updated a rule, the rule behavior might change.

If the API key that created a rule is deleted, or the user that created the rule becomes inactive, the rule will stop running.

To create and run rules, the user must meet specific requirements for the Kibana space. Refer to the Detections requirements for a complete list of requirements.

Assign and unassign users from detection alerts

POST /api/detection_engine/signals/assignees
Api key auth

Assign users to detection alerts, and unassign them from alerts.

You cannot add and remove the same assignee in the same request.

application/json

Body Required

  • assignees object Required

    Details about the assignees to assign and unassign.

    Hide assignees attributes Show assignees attributes object
    • add array[string(nonempty)] Required

      A list of users ids to assign.

      Minimum length of each is 1.

    • remove array[string(nonempty)] Required

      A list of users ids to unassign.

      Minimum length of each is 1.

  • ids array[string(nonempty)] Required

    A list of alerts ids.

    At least 1 element. Minimum length of each is 1.

Responses

  • 200 application/ndjson

    Indicates a successful call.

  • 400

    Invalid request.

POST /api/detection_engine/signals/assignees 
curl \
 --request POST 'https://<KIBANA_URL>/api/detection_engine/signals/assignees' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"ids":["681c2a707335aa7df5f349b70013d87254746191712ecf0ced9b3e2d538503a6"],"assignees":{"add":["u_MxY0jbrft7EcfC6iNZSUGeI_n6iYrSwZj5mWF5EqmSU_0"],"remove":[]}}'
Request examples 
{
  "ids": [
    "681c2a707335aa7df5f349b70013d87254746191712ecf0ced9b3e2d538503a6"
  ],
  "assignees": {
    "add": [
      "u_MxY0jbrft7EcfC6iNZSUGeI_n6iYrSwZj5mWF5EqmSU_0"
    ],
    "remove": []
  }
}
{
  "ids": [
    "681c2a707335aa7df5f349b70013d87254746191712ecf0ced9b3e2d538503a6"
  ],
  "assignees": {
    "add": [],
    "remove": [
      "u_MxY0jbrft7EcfC6iNZSUGeI_n6iYrSwZj5mWF5EqmSU_0"
    ]
  }
}
Response examples (200) 
{
  "took": "76,",
  "noops": "0,",
  "total": "1,",
  "batches": "1,",
  "deleted": "0,",
  "retries": [
    {
      "bulk": "0,"
    },
    {
      "search": 0
    }
  ],
  "updated": "1,",
  "failures": [],
  "timed_out": "false,",
  "throttled_millis": "0,",
  "version_conflicts": "0,",
  "requests_per_second": "-1,",
  "throttled_until_millis": "0,"
}

Add and remove detection alert tags

POST /api/detection_engine/signals/tags
Api key auth

And tags to detection alerts, and remove them from alerts.

You cannot add and remove the same alert tag in the same request.

application/json

Body Required

An object containing tags to add or remove and alert ids the changes will be applied

  • ids array[string(nonempty)] Required

    A list of alerts ids.

    At least 1 element. Minimum length of each is 1.

  • tags object Required

    Object with list of tags to add and remove.

    Hide tags attributes Show tags attributes object
    • tags_to_add array[string(nonempty)] Required

      List of keywords to organize related alerts into categories that you can filter and group.

      Minimum length of each is 1.

    • tags_to_remove array[string(nonempty)] Required

      List of keywords to organize related alerts into categories that you can filter and group.

      Minimum length of each is 1.

Responses

POST /api/detection_engine/signals/tags 
curl \
 --request POST 'https://<KIBANA_URL>/api/detection_engine/signals/tags' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"ids":["549c7129c76cbd554aba1bd638f8a49dde95088f5832e50218358e7eca1cf16e"],"tags":{"tags_to_add":["Duplicate"],"tags_to_remove":[]}}'
Request examples 
{
  "ids": [
    "549c7129c76cbd554aba1bd638f8a49dde95088f5832e50218358e7eca1cf16e"
  ],
  "tags": {
    "tags_to_add": [
      "Duplicate"
    ],
    "tags_to_remove": []
  }
}
{
  "ids": [
    "549c7129c76cbd554aba1bd638f8a49dde95088f5832e50218358e7eca1cf16e"
  ],
  "tags": {
    "tags_to_add": [],
    "tags_to_remove": [
      "Duplicate"
    ]
  }
}
Response examples (200) 
{
  "took": "68,",
  "noops": "0,",
  "total": "1,",
  "batches": "1,",
  "deleted": "0,",
  "retries": {
    "bulk": "0,",
    "search": 0
  },
  "updated": "1,",
  "failures": [],
  "timed_out": "false,",
  "throttled_millis": "0,",
  "version_conflicts": "0,",
  "requests_per_second": "-1,",
  "throttled_until_millis": "0,"
}

Security endpoint management

Interact with and manage endpoints running the Elastic Defend integration.

Run a command

POST /api/endpoint/action/execute
Api key auth

Run a shell command on an endpoint.

application/json

Body Required

  • agent_type string

    List of agent types to retrieve. Defaults to endpoint.

    Values are endpoint, sentinel_one, crowdstrike, or microsoft_defender_endpoint.

  • alert_ids array[string(nonempty)]

    A list of alerts ids.

    At least 1 element. Minimum length of each is 1.

  • case_ids array[string]

    Case IDs to be updated (cannot contain empty strings)

    At least 1 element. Minimum length of each is 1.

  • comment string

    Optional comment

  • endpoint_ids array[string] Required

    List of endpoint IDs (cannot contain empty strings)

    At least 1 element. Minimum length of each is 1.

  • parameters object Required

    Optional parameters object

    Hide parameters attributes Show parameters attributes object
    • command string Required

      The command to be executed (cannot be an empty string)

      Minimum length is 1. Values are isolate, unisolate, kill-process, suspend-process, running-processes, get-file, execute, upload, or scan.

    • timeout integer

      The maximum timeout value in milliseconds (optional)

      Minimum value is 1.

Responses

  • 200 application/json

    OK
POST /api/endpoint/action/execute 
curl \
 --request POST 'https://<KIBANA_URL>/api/endpoint/action/execute' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"comment":"Get list of all files","parameters":{"command":"ls -al","timeout":600},"endpoint_ids":["b3d6de74-36b0-4fa8-be46-c375bf1771bf"]}'
Request example 
{
  "comment": "Get list of all files",
  "parameters": {
    "command": "ls -al",
    "timeout": 600
  },
  "endpoint_ids": [
    "b3d6de74-36b0-4fa8-be46-c375bf1771bf"
  ]
}
Response examples (200) 
{
  "data": {
    "id": "9f934028-2300-4927-b531-b26376793dc4",
    "hosts": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "name": "gke-endpoint-gke-clu-endpoint-node-po-e1a3ab89-4c4r"
      }
    },
    "agents": [
      "ed518850-681a-4d60-bb98-e22640cae2a8"
    ],
    "status": "pending",
    "command": "execute",
    "comment": "Get list of all files",
    "outputs": {},
    "agentType": "endpoint",
    "createdBy": "myuser",
    "isExpired": false,
    "startedAt": "2023-07-28T18:43:27.362Z",
    "agentState": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "isCompleted": false,
        "wasSuccessful": false
      }
    },
    "parameters": {
      "command": "ls -al",
      "timeout": 600
    },
    "isCompleted": false,
    "wasSuccessful": false
  }
}

Run a script

POST /api/endpoint/action/runscript
Api key auth

Run a shell command on an endpoint.

application/json

Body Required

Responses

  • 200 application/json

    OK
POST /api/endpoint/action/runscript 
curl \
 --request POST 'https://<KIBANA_URL>/api/endpoint/action/runscript' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"parameters":{"commandLine":"string","raw":"string","timeout":42}}'

Release an isolated endpoint

POST /api/endpoint/action/unisolate
Api key auth

Release an isolated endpoint, allowing it to rejoin a network.

application/json

Body Required

  • agent_type string

    List of agent types to retrieve. Defaults to endpoint.

    Values are endpoint, sentinel_one, crowdstrike, or microsoft_defender_endpoint.

  • alert_ids array[string(nonempty)]

    A list of alerts ids.

    At least 1 element. Minimum length of each is 1.

  • case_ids array[string]

    Case IDs to be updated (cannot contain empty strings)

    At least 1 element. Minimum length of each is 1.

  • comment string

    Optional comment

  • endpoint_ids array[string] Required

    List of endpoint IDs (cannot contain empty strings)

    At least 1 element. Minimum length of each is 1.

  • parameters object

    Optional parameters object

Responses

  • 200 application/json

    OK
POST /api/endpoint/action/unisolate 
curl \
 --request POST 'https://<KIBANA_URL>/api/endpoint/action/unisolate' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"comment":"Benign process identified, releasing group","endpoint_ids":["9972d10e-4b9e-41aa-a534-a85e2a28ea42","bc0e4f0c-3bca-4633-9fee-156c0b505d16","fa89271b-b9d4-43f2-a684-307cffddeb5a"]}'
Request examples 
{
  "comment": "Benign process identified, releasing group",
  "endpoint_ids": [
    "9972d10e-4b9e-41aa-a534-a85e2a28ea42",
    "bc0e4f0c-3bca-4633-9fee-156c0b505d16",
    "fa89271b-b9d4-43f2-a684-307cffddeb5a"
  ]
}
{
  "endpoint_ids": [
    "ed518850-681a-4d60-bb98-e22640cae2a8"
  ]
}
{
  "comment": "Remediation complete, restoring network",
  "case_ids": [
    "4976be38-c134-4554-bd5e-0fd89ce63667"
  ],
  "endpoint_ids": [
    "1aa1f8fd-0fb0-4fe4-8c30-92068272d3f0",
    "b30a11bf-1395-4707-b508-fbb45ef9793e"
  ]
}
Response examples (200) 
{
  "data": {
    "id": "233db9ea-6733-4849-9226-5a7039c7161d",
    "agents": [
      "ed518850-681a-4d60-bb98-e22640cae2a8"
    ],
    "errors": [],
    "command": "suspend-process",
    "comment": "suspend the process",
    "outputs": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "type": "json",
        "content": {
          "key": "value"
        }
      }
    },
    "agentType": "endpoint",
    "createdBy": "myuser",
    "isExpired": false,
    "startedAt": "2022-07-29T19:08:49.126Z",
    "parameters": {
      "entity_id": "abc123"
    },
    "completedAt": "2022-07-29T19:09:44.961Z",
    "isCompleted": true,
    "wasSuccessful": true
  },
  "action": "233db9ea-6733-4849-9226-5a7039c7161d"
}

Upload a file

POST /api/endpoint/action/upload
Api key auth

Upload a file to an endpoint.

multipart/form-data

Body Required

  • agent_type string

    List of agent types to retrieve. Defaults to endpoint.

    Values are endpoint, sentinel_one, crowdstrike, or microsoft_defender_endpoint.

  • alert_ids array[string(nonempty)]

    A list of alerts ids.

    At least 1 element. Minimum length of each is 1.

  • case_ids array[string]

    Case IDs to be updated (cannot contain empty strings)

    At least 1 element. Minimum length of each is 1.

  • comment string

    Optional comment

  • endpoint_ids array[string] Required

    List of endpoint IDs (cannot contain empty strings)

    At least 1 element. Minimum length of each is 1.

  • parameters object Required

    Optional parameters object

    Hide parameters attribute Show parameters attribute object
    • overwrite boolean

      Overwrite the file on the host if it already exists.

      Default value is false.

  • file string(binary) Required

    The binary content of the file.

Responses

  • 200 application/json

    OK
POST /api/endpoint/action/upload 
curl \
 --request POST 'https://<KIBANA_URL>/api/endpoint/action/upload' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: multipart/form-data" \
 --form "file=RWxhc3RpYw==" \
 --form 'parameters={}' \
 --form "endpoint_ids[]=ed518850-681a-4d60-bb98-e22640cae2a8"
Request example 
{"file"=>"RWxhc3RpYw==", "parameters"=>{}, "endpoint_ids"=>["ed518850-681a-4d60-bb98-e22640cae2a8"]}
Response examples (200) 
{
  "data": {
    "id": "9ff6aebc-2cb6-481e-8869-9b30036c9731",
    "hosts": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "name": "Host-5i6cuc8kdv"
      }
    },
    "agents": [
      "ed518850-681a-4d60-bb98-e22640cae2a8"
    ],
    "status": "pending",
    "command": "upload",
    "outputs": {},
    "agentType": "endpoint",
    "createdBy": "elastic",
    "isExpired": false,
    "startedAt": "2023-07-03T15:07:22.837Z",
    "agentState": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "isCompleted": false,
        "wasSuccessful": false
      }
    },
    "parameters": {
      "file_id": "10e4ce3d-4abb-4f93-a0cd-eaf63a489280",
      "file_name": "fix-malware.sh",
      "file_size": 69,
      "file_sha256": "a0bed94220193ba4895c0aa5b4e7e293381d15765cb164ddf7be5cdd010ae42a"
    },
    "isCompleted": false,
    "wasSuccessful": false
  }
}

Get a metadata list

GET /api/endpoint/metadata
Api key auth

Query parameters

  • page integer

    Page number

    Minimum value is 1. Default value is 1.

  • pageSize integer

    Number of items per page

    Minimum value is 1, maximum value is 100. Default value is 10.

  • kuery string

    A KQL string.

  • hostStatuses array[string] Required

    A set of agent health statuses to filter by.

    Values are healthy, offline, updating, inactive, or unenrolled.

  • sortField string

    Determines which field is used to sort the results.

    Values are enrolled_at, metadata.host.hostname, host_status, metadata.Endpoint.policy.applied.name, metadata.Endpoint.policy.applied.status, metadata.host.os.name, metadata.host.ip, metadata.agent.version, or last_checkin.

  • sortDirection string

    Determines the sort order.

    Values are asc or desc.

Responses

  • 200 application/json

    OK
GET /api/endpoint/metadata 
curl \
 --request GET 'https://<KIBANA_URL>/api/endpoint/metadata?hostStatuses=healthy&hostStatuses=updating' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "data": [
    {
      "metadata": {
        "ecs": {
          "version": "1.11.0"
        },
        "host": {
          "id": "0cfead88e2024bd8a27476352b5ab264",
          "ip": [
            "127.0.0.1",
            "::1",
            "10.0.2.15",
            "fe80::2ac7:8e15:b957:2fa1"
          ],
          "os": {
            "Ext": {
              "variant": "Ubuntu"
            },
            "full": "Ubuntu 20.04.2",
            "name": "Linux",
            "type": "linux",
            "family": "ubuntu",
            "kernel": "5.8.0-59-generic #66~20.04.1-Ubuntu SMP Thu Jun 17 11:14:10 UTC 2021",
            "version": "20.04.2",
            "platform": "ubuntu"
          },
          "mac": [
            "08:00:27:e6:78:8b"
          ],
          "name": "david-Xubuntu",
          "hostname": "david-Xubuntu",
          "architecture": "x86_64"
        },
        "agent": {
          "id": "285297c6-3bff-4b83-9a07-f3e749801123",
          "type": "endpoint",
          "build": {
            "original": "version: 7.16.0, compiled: Tue Nov 16 16:00:00 2021, branch: 7.16, commit: 73a51033db85e0fb3be1c934697ef6a2b08979ab"
          },
          "version": "7.16.0"
        },
        "event": {
          "id": "MNtSXK/SkhEBnmgt++++++7S",
          "kind": "metric",
          "type": [
            "info"
          ],
          "action": "endpoint_metadata",
          "module": "endpoint",
          "created": "2023-07-04T15:47:57.432173535Z",
          "dataset": "endpoint.metadata",
          "category": [
            "host"
          ],
          "ingested": "2023-07-04T15:47:58Z",
          "sequence": 400,
          "agent_id_status": "verified"
        },
        "elastic": {
          "agent": {
            "id": "285297c6-3bff-4b83-9a07-f3e749801123"
          }
        },
        "message": "Endpoint metadata",
        "Endpoint": {
          "state": {
            "isolation": false
          },
          "policy": {
            "applied": {
              "id": "d5371dcd-93b7-4627-af88-4084f7d6aa3e",
              "name": "test",
              "status": "success",
              "version": "3",
              "endpoint_policy_version": "2"
            }
          },
          "status": "enrolled",
          "capabilities": [
            "isolation"
          ],
          "configuration": {
            "isolation": false
          }
        },
        "@timestamp": "2023-07-04T15:47:57.432173535Z",
        "data_stream": {
          "type": "metrics",
          "dataset": "endpoint.metadata",
          "namespace": "default"
        }
      },
      "host_status": "healthy",
      "policy_info": {
        "agent": {
          "applied": {
            "id": "ed7e3720-4bad-11ec-a2a8-fb22e62a5753",
            "revision": 0
          },
          "configured": {
            "id": "ed7e3720-4bad-11ec-a2a8-fb22e62a5753",
            "revision": 3
          }
        },
        "endpoint": {
          "id": "d5371dcd-93b7-4627-af88-4084f7d6aa3e",
          "revision": 2
        }
      },
      "last_checkin": "2023-07-04T15:47:57.432Z"
    },
    {
      "metadata": {
        "ecs": {
          "version": "1.11.0"
        },
        "host": {
          "id": "17d9cabc-7edd-43bc-bacb-8da5f5e6c0e5",
          "ip": [
            "10.0.2.15",
            "fe80::21a6:63d3:d70e:e3ad",
            "127.0.0.1",
            "::1"
          ],
          "os": {
            "Ext": {
              "variant": "Windows 10 Enterprise Evaluation"
            },
            "full": "Windows 10 Enterprise Evaluation 20H2 (10.0.19042.906)",
            "name": "Windows",
            "type": "windows",
            "family": "windows",
            "kernel": "20H2 (10.0.19042.906)",
            "version": "20H2 (10.0.19042.906)",
            "platform": "windows"
          },
          "mac": [
            "08:00:27:b1:1d:5a"
          ],
          "name": "WinDev2104Eval",
          "hostname": "WinDev2104Eval",
          "architecture": "x86_64"
        },
        "agent": {
          "id": "abb8a826-6812-448c-a571-6d8269b51449",
          "type": "endpoint",
          "build": {
            "original": "version: 7.16.0, compiled: Tue Nov 16 17:00:00 2021, branch: 7.16, commit: 73a51033db85e0fb3be1c934697ef6a2b08979ab"
          },
          "version": "7.16.0"
        },
        "event": {
          "id": "MNtRc++KoKHXXwlj+++++/N9",
          "kind": "metric",
          "type": [
            "info"
          ],
          "action": "endpoint_metadata",
          "module": "endpoint",
          "created": "2023-07-04T15:44:31.4917849Z",
          "dataset": "endpoint.metadata",
          "category": [
            "host"
          ],
          "ingested": "2023-07-04T15:44:33Z",
          "sequence": 5159,
          "agent_id_status": "verified"
        },
        "elastic": {
          "agent": {
            "id": "abb8a826-6812-448c-a571-6d8269b51449"
          }
        },
        "message": "Endpoint metadata",
        "Endpoint": {
          "state": {
            "isolation": false
          },
          "policy": {
            "applied": {
              "id": "d5371dcd-93b7-4627-af88-4084f7d6aa3e",
              "name": "test",
              "status": "success",
              "version": "3",
              "endpoint_policy_version": "2"
            }
          },
          "status": "enrolled",
          "capabilities": [
            "isolation"
          ],
          "configuration": {
            "isolation": false
          }
        },
        "@timestamp": "2023-07-04T15:44:31.4917849Z",
        "data_stream": {
          "type": "metrics",
          "dataset": "endpoint.metadata",
          "namespace": "default"
        }
      },
      "host_status": "healthy",
      "policy_info": {
        "agent": {
          "applied": {
            "id": "ed7e3720-4bad-11ec-a2a8-fb22e62a5753",
            "revision": 0
          },
          "configured": {
            "id": "ed7e3720-4bad-11ec-a2a8-fb22e62a5753",
            "revision": 3
          }
        },
        "endpoint": {
          "id": "d5371dcd-93b7-4627-af88-4084f7d6aa3e",
          "revision": 2
        }
      },
      "last_checkin": "2023-07-04T15:44:31.491Z"
    }
  ],
  "page": 0,
  "total": 2,
  "pageSize": 10,
  "sortField": "enrolled_at",
  "sortDirection": "desc"
}

List asset criticality records

GET /api/asset_criticality/list
Api key auth

List asset criticality records, paging, sorting and filtering as needed.

Query parameters

  • sort_field string

    The field to sort by.

    Values are id_value, id_field, criticality_level, or \@timestamp.

  • sort_direction string

    The order to sort by.

    Values are asc or desc.

  • page integer

    The page number to return.

    Minimum value is 1.

  • per_page integer

    The number of records to return per page.

    Minimum value is 1, maximum value is 1000.

  • kuery string

    The kuery to filter by.

Responses

  • 200 application/json

    Successfully retrieved asset criticality records

    Hide response attributes Show response attributes object
    • page integer Required

      Minimum value is 1.

    • per_page integer Required

      Minimum value is 1, maximum value is 1000.

    • records array[object] Required

      The deleted record if it existed.

      Hide records attributes Show records attributes object

      The deleted record if it existed.

      • id_field string Required

        Values are host.name, user.name, service.name, or entity.id.

      • id_value string Required

        The ID value of the asset.

      • criticality_level string Required

        The criticality level of the asset.

        Values are low_impact, medium_impact, high_impact, or extreme_impact.

      • asset object Required
        Hide asset attribute Show asset attribute object
        • criticality string

          The criticality level of the asset.

          Values are low_impact, medium_impact, high_impact, or extreme_impact.

      • host object
        Hide host attributes Show host attributes object
        • asset object
          Hide asset attribute Show asset attribute object
          • criticality string Required

            The criticality level of the asset.

            Values are low_impact, medium_impact, high_impact, or extreme_impact.

        • name string Required
      • service object
        Hide service attributes Show service attributes object
        • asset object
          Hide asset attribute Show asset attribute object
          • criticality string Required

            The criticality level of the asset.

            Values are low_impact, medium_impact, high_impact, or extreme_impact.

        • name string Required
      • user object
        Hide user attributes Show user attributes object
        • asset object
          Hide asset attribute Show asset attribute object
          • criticality string Required

            The criticality level of the asset.

            Values are low_impact, medium_impact, high_impact, or extreme_impact.

        • name string Required
      • @timestamp string(date-time) Required

        The time the record was created or updated.

    • total integer Required

      Minimum value is 0.
GET /api/asset_criticality/list 
curl \
 --request GET 'https://<KIBANA_URL>/api/asset_criticality/list' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "page": 1,
  "total": 2,
  "records": [
    {
      "host": {
        "name": "my_other_host",
        "asset": {
          "criticality": "medium_impact"
        }
      },
      "asset": {
        "criticality": "medium_impact"
      },
      "id_field": "host.name",
      "id_value": "my_other_host",
      "@timestamp": "2024-08-02T14:40:35.705Z",
      "criticality_level": "medium_impact"
    },
    {
      "host": {
        "name": "my_host",
        "asset": {
          "criticality": "high_impact"
        }
      },
      "asset": {
        "criticality": "high_impact"
      },
      "id_field": "host.name",
      "id_value": "my_host",
      "@timestamp": "2024-08-02T11:15:34.290Z",
      "criticality_level": "high_impact"
    }
  ],
  "per_page": 10
}

List the Entity Engines

GET /api/entity_store/engines
Api key auth

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • count integer
    • engines array[object]
      Hide engines attributes Show engines attributes object
GET /api/entity_store/engines 
curl \
 --request GET 'https://<KIBANA_URL>/api/entity_store/engines' \
 --header "Authorization: $API_KEY"

Get an Entity Engine

GET /api/entity_store/engines/{entityType}
Api key auth

Path parameters

  • entityType string Required

    The entity type of the engine (either 'user' or 'host').

    Values are user, host, service, or generic.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
GET /api/entity_store/engines/{entityType} 
curl \
 --request GET 'https://<KIBANA_URL>/api/entity_store/engines/{entityType}' \
 --header "Authorization: $API_KEY"

Delete the Entity Engine

DELETE /api/entity_store/engines/{entityType}
Api key auth

Path parameters

  • entityType string Required

    The entity type of the engine (either 'user' or 'host').

    Values are user, host, service, or generic.

Query parameters

  • data boolean

    Control flag to also delete the entity data.

Responses

  • 200 application/json

    Successful response

    Hide response attribute Show response attribute object
DELETE /api/entity_store/engines/{entityType} 
curl \
 --request DELETE 'https://<KIBANA_URL>/api/entity_store/engines/{entityType}' \
 --header "Authorization: $API_KEY"

Initialize an Entity Engine

POST /api/entity_store/engines/{entityType}/init
Api key auth

Path parameters

  • entityType string Required

    The entity type of the engine (either 'user' or 'host').

    Values are user, host, service, or generic.

application/json

Body Required

Schema for the engine initialization

  • delay string

    The delay before the transform will run.

    Format should match the following pattern: [smdh]$. Default value is 1m.

  • docsPerSecond integer

    The number of documents per second to process.

  • enrichPolicyExecutionInterval string

    Interval in which enrich policy runs. For example, "1h" means the rule runs every hour. Must be less than or equal to half the duration of the lookback period,

    Format should match the following pattern: ^[1-9]\d*[smh]$.

  • fieldHistoryLength integer

    The number of historical values to keep for each field.

    Default value is 10.

  • filter string
  • frequency string

    The frequency at which the transform will run.

    Format should match the following pattern: [smdh]$. Default value is 1m.

  • indexPattern string
  • lookbackPeriod string

    The amount of time the transform looks back to calculate the aggregations.

    Format should match the following pattern: [smdh]$. Default value is 24h.

  • timeout string

    The timeout for initializing the aggregating transform.

    Format should match the following pattern: [smdh]$. Default value is 180s.

  • timestampField string

    The field to use as the timestamp for the entity type.

    Default value is @timestamp.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
  • 400

    Invalid request

POST /api/entity_store/engines/{entityType}/init 
curl \
 --request POST 'https://<KIBANA_URL>/api/entity_store/engines/{entityType}/init' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"delay":"1m","docsPerSecond":42,"enrichPolicyExecutionInterval":"1h","fieldHistoryLength":10,"filter":"string","frequency":"1m","indexPattern":"string","lookbackPeriod":"24h","timeout":"180s","timestampField":"@timestamp"}'

Start an Entity Engine

POST /api/entity_store/engines/{entityType}/start
Api key auth

Path parameters

  • entityType string Required

    The entity type of the engine

    Values are user, host, service, or generic.

Responses

  • 200 application/json

    Successful response

    Hide response attribute Show response attribute object
POST /api/entity_store/engines/{entityType}/start 
curl \
 --request POST 'https://<KIBANA_URL>/api/entity_store/engines/{entityType}/start' \
 --header "Authorization: $API_KEY"

Run the risk scoring engine

POST /api/risk_score/engine/schedule_now
Api key auth

Schedule the risk scoring engine to run as soon as possible. You can use this to recalculate entity risk scores after updating their asset criticality.

application/json

Body

Responses

  • 200 application/json

    Successful response

    Hide response attribute Show response attribute object
  • 400 application/json

    Task manager is unavailable

    Hide response attributes Show response attributes object
  • default application/json

    Unexpected error

    Hide response attributes Show response attributes object
POST /api/risk_score/engine/schedule_now 
curl \
 --request POST 'https://<KIBANA_URL>/api/risk_score/engine/schedule_now' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json"

Security exceptions

Exceptions are associated with detection and endpoint rules, and are used to prevent a rule from generating an alert from incoming events, even when the rule's other criteria are met. They can help reduce the number of false positives and prevent trusted processes and network activity from generating unnecessary alerts.

Exceptions are made up of:

  • Exception containers: A container for related exceptions. Generally, a single exception container contains all the exception items relevant for a subset of rules. For example, a container can be used to group together network-related exceptions that are relevant for a large number of network rules. The container can then be associated with all the relevant rules.
  • Exception items: The query (fields, values, and logic) used to prevent rules from generating alerts. When an exception item's query evaluates to true, the rule does not generate an alert.

For detection rules, you can also use lists to define rule exceptions. A list holds multiple values of the same Elasticsearch data type, such as IP addresses. These values are used to determine when an exception prevents an alert from being generated.

You cannot use lists with endpoint rule exceptions.


Only exception containers can be associated with rules. You cannot directly associate an exception item or a list container with a rule. To use list exceptions, create an exception item that references the relevant list container.

Exceptions requirements

Before you can start working with exceptions that use value lists, you must create the .lists and .items data streams for the relevant Kibana space. To do this, use the Create list data streams endpoint. Once these data streams are created, your role needs privileges to manage rules. For a complete list of requirements, refer to Enable and access detections.

Create an exception list item

POST /api/exception_lists/items
Api key auth

Create an exception item and associate it with the specified exception list.

Before creating exception items, you must create an exception list.

application/json

Body Required

Exception list item's properties

  • comments array[object]

    Default value is [] (empty).

    Hide comments attribute Show comments attribute object
    • comment string(nonempty) Required

      A string that does not contain only whitespace characters

      Minimum length is 1.

  • description string Required

    Describes the exception list.

  • entries array[object] Required
    Any of:
    Security_Exceptions_API_ExceptionListItemEntryMatch object Security_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Exceptions_API_ExceptionListItemEntryList object Security_Exceptions_API_ExceptionListItemEntryExists object Security_Exceptions_API_ExceptionListItemEntryNested object Security_Exceptions_API_ExceptionListItemEntryMatchWildcard object
    Hide attributes Show attributes
    • field string(nonempty) Required

      A string that does not contain only whitespace characters

      Minimum length is 1.

    • operator string Required

      Values are excluded or included.

    • type string Required Discriminator

      Value is match.

    • value string(nonempty) Required

      A string that does not contain only whitespace characters

      Minimum length is 1.

  • expire_time string(date-time)

    The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.

  • item_id string(nonempty)

    Human readable string identifier, e.g. trusted-linux-processes

    Minimum length is 1.

  • list_id string(nonempty) Required

    Exception list's human readable string identifier, e.g. trusted-linux-processes.

    Minimum length is 1.

  • meta object

    Additional properties are allowed.

  • name string(nonempty) Required

    Exception list name.

    Minimum length is 1.

  • namespace_type string

    Determines whether the exception container is available in all Kibana spaces or just the space in which it is created, where:

    • single: Only available in the Kibana space in which it is created.
    • agnostic: Available in all Kibana spaces.

    Values are agnostic or single. Default value is single.

  • os_types array[string]

    Use this field to specify the operating system.

    Values are linux, macos, or windows. Default value is [] (empty).

  • tags array[string(nonempty)]

    String array containing words and phrases to help categorize exception items.

    Minimum length of each is 1. Default value is [] (empty).

  • type string Required

    Value is simple.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • _version string

      The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version.

    • comments array[object] Required

      Array of comment fields:

      • comment (string): Comments about the exception item.
      Hide comments attributes Show comments attributes object
      • comment string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • created_at string(date-time) Required

        Autogenerated date of object creation.

      • created_by string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • id string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • updated_at string(date-time)

        Autogenerated date of last object update.

      • updated_by string(nonempty)

        A string that does not contain only whitespace characters

        Minimum length is 1.

    • created_at string(date-time) Required

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

    • description string Required

      Describes the exception list.

    • entries array[object] Required
      Any of:
      Security_Exceptions_API_ExceptionListItemEntryMatch object Security_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Exceptions_API_ExceptionListItemEntryList object Security_Exceptions_API_ExceptionListItemEntryExists object Security_Exceptions_API_ExceptionListItemEntryNested object Security_Exceptions_API_ExceptionListItemEntryMatchWildcard object
      Hide attributes Show attributes
      • field string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • operator string Required

        Values are excluded or included.

      • type string Required Discriminator

        Value is match.

      • value string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

    • expire_time string(date-time)

      The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.

    • id string(nonempty) Required

      Exception's identifier.

      Minimum length is 1.

    • item_id string(nonempty) Required

      Human readable string identifier, e.g. trusted-linux-processes

      Minimum length is 1.

    • list_id string(nonempty) Required

      Exception list's human readable string identifier, e.g. trusted-linux-processes.

      Minimum length is 1.

    • meta object

      Additional properties are allowed.

    • name string(nonempty) Required

      Exception list name.

      Minimum length is 1.

    • namespace_type string Required

      Determines whether the exception container is available in all Kibana spaces or just the space in which it is created, where:

      • single: Only available in the Kibana space in which it is created.
      • agnostic: Available in all Kibana spaces.

      Values are agnostic or single. Default value is single.

    • os_types array[string]

      Use this field to specify the operating system.

      Values are linux, macos, or windows. Default value is [] (empty).

    • tags array[string(nonempty)]

      String array containing words and phrases to help categorize exception items.

      Minimum length of each is 1. Default value is [] (empty).

    • tie_breaker_id string Required

      Field used in search to ensure all containers are sorted and returned correctly.

    • type string Required

      Value is simple.

    • updated_at string(date-time) Required

      Autogenerated date of last object update.

    • updated_by string Required

      Autogenerated value - user that last updated object.
  • 400 application/json

    Invalid input data response

    One of:
    Security_Exceptions_API_PlatformErrorResponse object Security_Exceptions_API_SiemErrorResponse object
    Hide attributes Show attributes
  • 401 application/json

    Unsuccessful authentication response

    Hide response attributes Show response attributes object
  • 403 application/json

    Not enough privileges response

    Hide response attributes Show response attributes object
  • 409 application/json

    Exception list item already exists response

    Hide response attributes Show response attributes object
  • 500 application/json

    Internal server error response

    Hide response attributes Show response attributes object
POST /api/exception_lists/items 
curl \
 --request POST 'https://<KIBANA_URL>/api/exception_lists/items' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"name":"Sample Exception List Item","tags":["malware"],"type":"simple","entries":[{"type":"exists","field":"actingProcess.file.signer","operator":"excluded"},{"type":"match_any","field":"host.name","value":["saturn","jupiter"],"operator":"included"}],"item_id":"simple_list_item","list_id":"simple_list","os_types":["linux"],"description":"This is a sample detection type exception item.","namespace_type":"single"}'
Request example 
{
  "name": "Sample Exception List Item",
  "tags": [
    "malware"
  ],
  "type": "simple",
  "entries": [
    {
      "type": "exists",
      "field": "actingProcess.file.signer",
      "operator": "excluded"
    },
    {
      "type": "match_any",
      "field": "host.name",
      "value": [
        "saturn",
        "jupiter"
      ],
      "operator": "included"
    }
  ],
  "item_id": "simple_list_item",
  "list_id": "simple_list",
  "os_types": [
    "linux"
  ],
  "description": "This is a sample detection type exception item.",
  "namespace_type": "single"
}
Response examples (200) 
{
  "id": "323faa75-c657-4fa0-9084-8827612c207b",
  "name": "Sample Autogenerated Exception List Item ID",
  "tags": [
    "malware"
  ],
  "type": "simple",
  "entries": [
    {
      "type": "exists",
      "field": "actingProcess.file.signer",
      "operator": "excluded"
    }
  ],
  "item_id": "80e6edf7-4b13-4414-858f-2fa74aa52b37",
  "list_id": "8c1aae4c-1ef5-4bce-a2e3-16584b501783",
  "_version": "WzYsMV0=",
  "comments": [],
  "os_types": [],
  "created_at": "2025-01-09T01:16:23.322Z",
  "created_by": "elastic",
  "updated_at": "2025-01-09T01:16:23.322Z",
  "updated_by": "elastic",
  "description": "This is a sample exception that has no item_id so it is autogenerated.",
  "namespace_type": "single",
  "tie_breaker_id": "d6799986-3a23-4213-bc6d-ed9463a32f23"
}
{
  "id": "71a9f4b2-c85c-49b4-866f-c71eb9e67da2",
  "name": "Sample Exception List Item",
  "tags": [
    "malware"
  ],
  "type": "simple",
  "entries": [
    {
      "type": "exists",
      "field": "actingProcess.file.signer",
      "operator": "excluded"
    }
  ],
  "item_id": "simple_list_item",
  "list_id": "simple_list",
  "_version": "WzQsMV0=",
  "comments": [],
  "os_types": [
    "linux"
  ],
  "created_at": "2025-01-07T20:07:33.119Z",
  "created_by": "elastic",
  "updated_at": "2025-01-07T20:07:33.119Z",
  "updated_by": "elastic",
  "description": "This is a sample detection type exception item.",
  "namespace_type": "single",
  "tie_breaker_id": "09434836-9db9-4942-a234-5a9268e0b34c"
}
{
  "id": "71a9f4b2-c85c-49b4-866f-c71eb9e67da2",
  "name": "Sample Exception List Item",
  "tags": [
    "malware"
  ],
  "type": "simple",
  "entries": [
    {
      "type": "exists",
      "field": "actingProcess.file.signer",
      "operator": "excluded"
    }
  ],
  "item_id": "simple_list_item",
  "list_id": "simple_list",
  "_version": "WzQsMV0=",
  "comments": [],
  "os_types": [
    "linux"
  ],
  "created_at": "2025-01-07T20:07:33.119Z",
  "created_by": "elastic",
  "updated_at": "2025-01-07T20:07:33.119Z",
  "updated_by": "elastic",
  "description": "This is a sample detection type exception item.",
  "namespace_type": "single",
  "tie_breaker_id": "09434836-9db9-4942-a234-5a9268e0b34c"
}
{
  "id": "71a9f4b2-c85c-49b4-866f-c71eb9e67da2",
  "name": "Sample Exception List Item",
  "tags": [
    "malware"
  ],
  "type": "simple",
  "entries": [
    {
      "type": "match_any",
      "field": "host.name",
      "value": [
        "saturn",
        "jupiter"
      ],
      "operator": "included"
    }
  ],
  "item_id": "simple_list_item",
  "list_id": "simple_list",
  "_version": "WzQsMV0=",
  "comments": [],
  "os_types": [
    "linux"
  ],
  "created_at": "2025-01-07T20:07:33.119Z",
  "created_by": "elastic",
  "updated_at": "2025-01-07T20:07:33.119Z",
  "updated_by": "elastic",
  "description": "This is a sample detection type exception item.",
  "namespace_type": "single",
  "tie_breaker_id": "09434836-9db9-4942-a234-5a9268e0b34c"
}
{
  "id": "71a9f4b2-c85c-49b4-866f-c71eb9e67da2",
  "name": "Sample Exception List Item",
  "tags": [
    "malware"
  ],
  "type": "simple",
  "entries": [
    {
      "type": "match",
      "field": "actingProcess.file.signer",
      "value": "Elastic N.V.",
      "operator": "included"
    }
  ],
  "item_id": "simple_list_item",
  "list_id": "simple_list",
  "_version": "WzQsMV0=",
  "comments": [],
  "os_types": [
    "linux"
  ],
  "created_at": "2025-01-07T20:07:33.119Z",
  "created_by": "elastic",
  "updated_at": "2025-01-07T20:07:33.119Z",
  "updated_by": "elastic",
  "description": "This is a sample detection type exception item.",
  "namespace_type": "single",
  "tie_breaker_id": "09434836-9db9-4942-a234-5a9268e0b34c"
}
{
  "id": "71a9f4b2-c85c-49b4-866f-c71eb9e67da2",
  "name": "Sample Exception List Item",
  "tags": [
    "malware"
  ],
  "type": "simple",
  "entries": [
    {
      "type": "nested",
      "field": "file.signature",
      "entries": [
        {
          "type": "match",
          "field": "signer",
          "value": "Evil",
          "operator": "included"
        },
        {
          "type": "match",
          "field": "trusted",
          "value": true,
          "operator": "included"
        }
      ]
    }
  ],
  "item_id": "simple_list_item",
  "list_id": "simple_list",
  "_version": "WzQsMV0=",
  "comments": [],
  "os_types": [
    "linux"
  ],
  "created_at": "2025-01-07T20:07:33.119Z",
  "created_by": "elastic",
  "updated_at": "2025-01-07T20:07:33.119Z",
  "updated_by": "elastic",
  "description": "This is a sample detection type exception item.",
  "namespace_type": "single",
  "tie_breaker_id": "09434836-9db9-4942-a234-5a9268e0b34c"
}
{
  "id": "deb26876-297d-4677-8a1f-35467d2f1c4f",
  "name": "Filter out good guys ip and agent.name rock01",
  "tags": [
    "malware"
  ],
  "type": "simple",
  "entries": [
    {
      "list": {
        "id": "goodguys.txt",
        "type": "ip"
      },
      "type": "list",
      "field": "source.ip",
      "operator": "excluded"
    }
  ],
  "item_id": "686b129e-9b8d-4c59-8d8d-c93a9ea82c71",
  "list_id": "8c1aae4c-1ef5-4bce-a2e3-16584b501783",
  "_version": "WzcsMV0=",
  "comments": [],
  "os_types": [],
  "created_at": "2025-01-09T01:31:12.614Z",
  "created_by": "elastic",
  "updated_at": "2025-01-09T01:31:12.614Z",
  "updated_by": "elastic",
  "description": "Don't signal when agent.name is rock01 and source.ip is in the goodguys.txt list",
  "namespace_type": "single",
  "tie_breaker_id": "5e0288ce-6657-4c18-9dcc-00ec9e8cc6c8"
}
Response examples (400) 
{
  "error": "Bad Request,",
  "message": "[request body]: list_id: Expected string, received number",
  "statusCode": "400,"
}
Response examples (401) 
{
  "error": "Unauthorized",
  "message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403) 
{
  "error": "Forbidden",
  "message": "API [POST /api/exception_lists/items] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}
Response examples (409) 
{
  "message": "exception list item id: \\\"simple_list_item\\\" already exists",
  "status_code": 409
}
Response examples (500) 
{
  "message": "Internal Server Error",
  "status_code": 500
}

Delete value list data streams

DELETE /api/lists/index
Api key auth

Delete the .lists and .items data streams.

Responses

DELETE /api/lists/index 
curl \
 --request DELETE 'https://<KIBANA_URL>/api/lists/index' \
 --header "Authorization: $API_KEY"
Response examples (401) 
{
  "error": "Unauthorized",
  "message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (500) 
{
  "message": "Internal Server Error",
  "status_code": 500
}

Get packs

GET /api/osquery/packs
Api key auth

Get a list of all query packs.

Query parameters

  • page integer | null

    The page number to return. The default is 1.

  • pageSize integer | null

    The number of results to return per page. The default is 20.

  • sort string | null

    The field that is used to sort the results.

    Default value is createdAt.

  • sortOrder string

    Specifies the sort order.

    Values are asc or desc.

Responses

  • 200 application/json

    OK
GET /api/osquery/packs 
curl \
 --request GET 'https://<KIBANA_URL>/api/osquery/packs' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "data": [
    {
      "id": "42ba9c50-0cc5-11ed-aa1d-2b27890bc90d",
      "type": "osquery-pack",
      "attributes": {
        "name": "My Pack",
        "enabled": true,
        "queries": [
          {
            "id": "uptime",
            "query": "select * from uptime;",
            "interval": "3600",
            "ecs_mapping": [
              {
                "host.uptime": {
                  "field": "total_seconds"
                }
              }
            ]
          }
        ],
        "created_at": "2023-10-31T00:00:00Z",
        "created_by": "elastic",
        "updated_at": "2023-10-31T00:00:00Z",
        "updated_by": "elastic",
        "description": "My pack description"
      },
      "namespaces": [
        "default"
      ]
    }
  ],
  "page": 1,
  "total": 1,
  "pageSize": 10,
  "policy_ids": []
}

Get saved query details

GET /api/osquery/saved_queries/{id}
Api key auth

Get the details of a saved query using the query ID.

Path parameters

  • id string | null Required

    The ID of a saved query.

Responses

  • 200 application/json

    OK
GET /api/osquery/saved_queries/{id} 
curl \
 --request GET 'https://<KIBANA_URL>/api/osquery/saved_queries/3c42c847-eb30-4452-80e0-728584042334' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "data": {
    "id": "3c42c847-eb30-4452-80e0-728584042334",
    "type": "osquery-saved-query",
    "version": "WzQzMTcsMV0=",
    "attributes": {
      "id": "saved_query_id",
      "query": "select * from uptime;",
      "version": "2.8.0",
      "interval": "60",
      "platform": "linux,darwin",
      "prebuilt": false,
      "created_at": "2022-07-26T09:28:08.597Z",
      "created_by": "elastic",
      "updated_at": "2022-07-26T09:28:08.597Z",
      "updated_by": "elastic",
      "description": "Saved query description",
      "ecs_mapping": {
        "host.uptime": {
          "field": "total_seconds"
        }
      }
    },
    "namespaces": [
      "default"
    ],
    "references": [],
    "updated_at": "2022-07-26T09:28:08.600Z",
    "coreMigrationVersion": "8.4.0"
  }
}

Update a saved query

PUT /api/osquery/saved_queries/{id}
Api key auth

Update a saved query using the query ID.

You cannot update a prebuilt saved query.

Path parameters

  • id string | null Required

    The ID of a saved query.

application/json

Body Required

  • description string | null

    The saved query description.

  • ecs_mapping object | null

    Map osquery results columns or static values to Elastic Common Schema (ECS) fields

    Hide ecs_mapping attribute Show ecs_mapping attribute object | null
  • id string | null

    The ID of a saved query.

  • interval string

    An interval, in seconds, on which to run the query.

  • platform string | null

    Restricts the query to a specified platform. The default is all platforms. To specify multiple platforms, use commas. For example, linux,darwin.

  • query string

    The SQL query you want to run.

  • removed boolean | null

    Indicates whether the query is removed.

  • snapshot boolean | null

    Indicates whether the query is a snapshot.

  • version string | null

    Uses the Osquery versions greater than or equal to the specified version string.

Responses

  • 200 application/json

    OK
PUT /api/osquery/saved_queries/{id} 
curl \
 --request PUT 'https://<KIBANA_URL>/api/osquery/saved_queries/3c42c847-eb30-4452-80e0-728584042334' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"id":"updated_my_saved_query_name"}'
Request example 
{
  "id": "updated_my_saved_query_name"
}
Response examples (200) 
{
  "data": {}
}

Security timeline

You can create Timelines and Timeline templates via the API, as well as import new Timelines from an ndjson file.

Delete a note

DELETE /api/note
Api key auth

Delete a note from a Timeline using the note ID.

application/json

Body object | null Required

The ID of the note to delete.

One of:
object-1 object | null object-2 object | null

Responses

  • 200

    Indicates the note was successfully deleted.

DELETE /api/note 
curl \
 --request DELETE 'https://<KIBANA_URL>/api/note' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"noteId":"string"}'

Get draft Timeline or Timeline template details

GET /api/timeline/_draft
Api key auth

Get the details of the draft Timeline or Timeline template for the current user. If the user doesn't have a draft Timeline, an empty Timeline is returned.

Query parameters

  • timelineType string | null Required

    The type of Timeline.

    Values are default or template.

Responses

GET /api/timeline/_draft 
curl \
 --request GET 'https://<KIBANA_URL>/api/timeline/_draft?timelineType=default' \
 --header "Authorization: $API_KEY"