Kibana APIs
1.0.2
https://localhost:5601
The Kibana REST APIs enable you to manage resources such as connectors, data views, and saved objects. The API calls are stateless. Each request that you make happens in isolation from other calls and must include all of the necessary information for Kibana to fulfill the request. API requests return JSON output, which is a format that is machine-readable and works well for automation.
To interact with Kibana APIs, use the following operations:
- GET: Fetches the information.
- PATCH: Applies partial modifications to the existing information.
- POST: Adds new information.
- PUT: Updates the existing information.
- DELETE: Removes the information.
You can prepend any Kibana API endpoint with kbn:
and run the request in Dev Tools → Console.
For example:
GET kbn:/api/data_views
For more information about the console, refer to Run API requests.
NOTE: Access to internal Kibana API endpoints will be restricted in Kibana version 9.0. Please move any integrations to publicly documented APIs.
Documentation source and versions
This documentation is derived from the main
branch of the kibana repository.
It is provided under license Attribution-NonCommercial-NoDerivatives 4.0 International.
This documentation contains work-in-progress information for future Elastic Stack releases.
This is version 1.0.2
of this API documentation.
Last update on Feb 11, 2025.
Update the API key for a rule
Path parameters
-
The identifier for the rule.
curl \
--request POST https://localhost:5601/api/alerting/rule/{id}/_update_api_key \
--header "kbn-xsrf: true"
Lookup single agent configuration
This endpoint allows to search for single agent configuration and update 'applied_by_agent' field.
Headers
-
The version of the API to use
Value is
2023-10-31
. Default value is2023-10-31
. -
A required header to protect against CSRF attacks
Body Required
-
etag string
If etags match then
applied_by_agent
field will be set totrue
-
mark_as_applied_by_agent boolean
markAsAppliedByAgent=true
means "force setting it to true regardless of etag". This is needed for Jaeger agent that doesn't have etags -
Service
Additional properties are allowed.
curl \
--request POST https://localhost:5601/api/apm/settings/agent-configuration/search \
--header "Content-Type: application/json" \
--header "elastic-api-version: 2023-10-31" \
--header "kbn-xsrf: true" \
--data '{"etag":"0bc3b5ebf18fba8163fe4c96f491e3767a358f85","mark_as_applied_by_agent":true,"service":{"environment":"prod","name":"node"}}'
# Headers
elastic-api-version: 2023-10-31
kbn-xsrf: true
# Payload
{
"etag": "0bc3b5ebf18fba8163fe4c96f491e3767a358f85",
"mark_as_applied_by_agent": true,
"service": {
"environment": "prod",
"name": "node"
}
}
{
"_id": "string",
"_index": "string",
"_score": 42.0,
"_source": {
"@timestamp": 1730194190636,
"agent_name": "string",
"applied_by_agent": true,
"etag": "0bc3b5ebf18fba8163fe4c96f491e3767a358f85",
"service": {
"environment": "prod",
"name": "node"
},
"settings": {
"additionalProperty1": "string",
"additionalProperty2": "string"
}
}
}
{
"error": "Not Found",
"message": "Not Found",
"statusCode": 400
}
{
"error": "Unauthorized",
"message": "string",
"statusCode": 401
}
{
"error": "Not Found",
"message": "Not Found",
"statusCode": 404
}
APM annotations
Annotate visualizations in the APM app with significant events. Annotations enable you to easily see how events are impacting the performance of your applications.
APM sourcemaps
Configure APM source maps.
Get data streams
[Required authorization] Route required privileges: ALL of [fleet-agents-all, fleet-agent-policies-all, fleet-settings-all].
curl \
--request GET https://localhost:5601/api/fleet/data_streams
{
"data_streams": [
{
"dashboards": [
{
"id": "string",
"title": "string"
}
],
"dataset": "string",
"index": "string",
"last_activity_ms": 42.0,
"namespace": "string",
"package": "string",
"package_version": "string",
"serviceDetails": {
"environment": "string",
"serviceName": "string"
},
"size_in_bytes": 42.0,
"size_in_bytes_formatted": 42.0,
"type": "string"
}
]
}
{
"error": "string",
"message": "string",
"statusCode": 42.0
}
Update data view fields metadata
Update fields presentation metadata such as count, customLabel, customDescription, and format.
Path parameters
-
An identifier for the data view.
curl \
--request POST https://localhost:5601/api/data_views/data_view/ff959d40-b880-11e8-a6d9-e546fe2bba5f/fields \
--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"}}}'
{
"fields": {
"field1": {
"count": 123,
"customLabel": "Field 1 label"
},
"field2": {
"customLabel": "Field 2 label",
"customDescription": "Field 2 description"
}
}
}
{
"acknowledged": true
}
{
"error": "Bad Request",
"message": "string",
"statusCode": 400
}
Reassign an agent
[Required authorization] Route required privileges: ALL of [fleet-agents-all].
curl \
--request POST https://localhost:5601/api/fleet/agents/{agentId}/reassign \
--header "Content-Type: application/json" \
--header "kbn-xsrf: true" \
--data '{"policy_id":"string"}'
# Headers
kbn-xsrf: true
# Payload
{
"policy_id": "string"
}
{}
{
"error": "string",
"message": "string",
"statusCode": 42.0
}
Bulk request diagnostics from agents
[Required authorization] Route required privileges: ALL of [fleet-agents-read].
Body
-
additional_metrics array[string]
Value is
CPU
. agents array[string] | string Required
-
batchSize number
curl \
--request POST https://localhost:5601/api/fleet/agents/bulk_request_diagnostics \
--header "Content-Type: application/json" \
--header "kbn-xsrf: true" \
--data '{"additional_metrics":["CPU"],"agents":["string"],"batchSize":42.0}'
# Headers
kbn-xsrf: true
# Payload
{
"additional_metrics": [
"CPU"
],
"agents": [
"string"
],
"batchSize": 42.0
}
{
"actionId": "string"
}
{
"error": "string",
"message": "string",
"statusCode": 42.0
}
Get an agent binary download source
Get an agent binary download source by ID.
[Required authorization] Route required privileges: ANY of [fleet-agent-policies-read OR fleet-settings-read].
curl \
--request GET https://localhost:5601/api/fleet/agent_download_sources/{sourceId}
{
"item": {
"host": "https://example.com",
"id": "string",
"is_default": false,
"name": "string",
"proxy_id": "string"
}
}
{
"error": "string",
"message": "string",
"statusCode": 42.0
}
Update settings
[Required authorization] Route required privileges: ALL of [fleet-settings-all].
Body
-
additional_yaml_config string
-
delete_unenrolled_agents object
Additional properties are NOT allowed.
-
has_seen_add_data_notice boolean
-
kibana_ca_sha256 string
-
kibana_urls array[string(uri)]
-
prerelease_integrations_enabled boolean
curl \
--request PUT https://localhost:5601/api/fleet/settings \
--header "Content-Type: application/json" \
--header "kbn-xsrf: true" \
--data '{"additional_yaml_config":"string","delete_unenrolled_agents":{"enabled":true,"is_preconfigured":true},"has_seen_add_data_notice":true,"kibana_ca_sha256":"string","kibana_urls":["https://example.com"],"prerelease_integrations_enabled":true}'
# Headers
kbn-xsrf: true
# Payload
{
"additional_yaml_config": "string",
"delete_unenrolled_agents": {
"enabled": true,
"is_preconfigured": true
},
"has_seen_add_data_notice": true,
"kibana_ca_sha256": "string",
"kibana_urls": [
"https://example.com"
],
"prerelease_integrations_enabled": true
}
{
"item": {
"delete_unenrolled_agents": {
"enabled": true,
"is_preconfigured": true
},
"has_seen_add_data_notice": true,
"id": "string",
"output_secret_storage_requirements_met": true,
"preconfigured_fields": [
"fleet_server_hosts"
],
"prerelease_integrations_enabled": true,
"secret_storage_requirements_met": true,
"use_space_awareness_migration_started_at": "string",
"use_space_awareness_migration_status": "pending",
"version": "string"
}
}
{
"error": "string",
"message": "string",
"statusCode": 42.0
}
{
"message": "string"
}
Get package policies
Query parameters
-
page number
-
perPage number
-
sortField string
-
sortOrder string
Values are
desc
orasc
. -
showUpgradeable boolean
-
kuery string
-
format string
Values are
simplified
orlegacy
. -
withAgentCount boolean
curl \
--request GET https://localhost:5601/api/fleet/package_policies
{
"items": [
{
"agents": 42.0,
"created_at": "string",
"created_by": "string",
"description": "string",
"elasticsearch": {
"privileges": {
"cluster": [
"string"
]
}
},
"enabled": true,
"id": "string",
"inputs": [
{
"config": {
"additionalProperty1": {
"frozen": true,
"type": "string"
},
"additionalProperty2": {
"frozen": true,
"type": "string"
}
},
"enabled": true,
"id": "string",
"keep_enabled": true,
"policy_template": "string",
"streams": [
{
"config": {
"additionalProperty1": {
"frozen": true,
"type": "string"
},
"additionalProperty2": {
"frozen": true,
"type": "string"
}
},
"data_stream": {
"dataset": "string",
"elasticsearch": {
"dynamic_dataset": true,
"dynamic_namespace": true,
"privileges": {
"indices": [
"string"
]
}
},
"type": "string"
},
"enabled": true,
"id": "string",
"keep_enabled": true,
"release": "ga",
"vars": {
"additionalProperty1": {
"frozen": true,
"type": "string"
},
"additionalProperty2": {
"frozen": true,
"type": "string"
}
}
}
],
"type": "string",
"vars": {
"additionalProperty1": {
"frozen": true,
"type": "string"
},
"additionalProperty2": {
"frozen": true,
"type": "string"
}
}
}
],
"is_managed": true,
"name": "string",
"namespace": "string",
"output_id": "string",
"overrides": {
"inputs": {}
},
"package": {
"experimental_data_stream_features": [
{
"data_stream": "string",
"features": {
"doc_value_only_numeric": true,
"doc_value_only_other": true,
"synthetic_source": true,
"tsdb": true
}
}
],
"name": "string",
"requires_root": true,
"title": "string",
"version": "string"
},
"policy_id": "string",
"policy_ids": [
"string"
],
"revision": 42.0,
"secret_references": [
{
"id": "string"
}
],
"spaceIds": [
"string"
],
"supports_agentless": false,
"updated_at": "string",
"updated_by": "string",
"vars": {
"additionalProperty1": {
"frozen": true,
"type": "string"
},
"additionalProperty2": {
"frozen": true,
"type": "string"
}
},
"version": "string"
}
],
"page": 42.0,
"perPage": 42.0,
"total": 42.0
}
{
"error": "string",
"message": "string",
"statusCode": 42.0
}
Delete a package policy
Delete a package policy by ID.
[Required authorization] Route required privileges: ALL of [fleet-agent-policies-all, integrations-all].
Query parameters
-
force boolean
curl \
--request DELETE https://localhost:5601/api/fleet/package_policies/{packagePolicyId} \
--header "kbn-xsrf: true"
{
"id": "string"
}
{
"error": "string",
"message": "string",
"statusCode": 42.0
}
Dry run a package policy upgrade
[Required authorization] Route required privileges: ALL of [fleet-agent-policies-read, integrations-read].
Body
-
packageVersion string
curl \
--request POST https://localhost:5601/api/fleet/package_policies/upgrade/dryrun \
--header "Content-Type: application/json" \
--header "kbn-xsrf: true" \
--data '{"packagePolicyIds":["string"],"packageVersion":"string"}'
# Headers
kbn-xsrf: true
# Payload
{
"packagePolicyIds": [
"string"
],
"packageVersion": "string"
}
[
{
"agent_diff": [
[
{
"data_stream": {
"namespace": "string"
},
"id": "string",
"meta": {
"package": {
"name": "string",
"version": "string"
}
},
"name": "string",
"package_policy_id": "string",
"processors": [
{
"add_fields": {
"fields": {},
"target": "string"
}
}
],
"revision": 42.0,
"streams": [
{
"data_stream": {
"dataset": "string",
"type": "string"
},
"id": "string"
}
],
"type": "string",
"use_output": "string"
}
]
],
"body": {
"message": "string"
},
"diff": [
{
"agents": 42.0,
"created_at": "string",
"created_by": "string",
"description": "string",
"elasticsearch": {
"privileges": {
"cluster": [
"string"
]
}
},
"enabled": true,
"id": "string",
"inputs": [
{
"config": {
"additionalProperty1": {
"frozen": true,
"type": "string"
},
"additionalProperty2": {
"frozen": true,
"type": "string"
}
},
"enabled": true,
"id": "string",
"keep_enabled": true,
"policy_template": "string",
"streams": [
{
"config": {
"additionalProperty1": {
"frozen": true,
"type": "string"
},
"additionalProperty2": {
"frozen": true,
"type": "string"
}
},
"data_stream": {
"dataset": "string",
"elasticsearch": {
"dynamic_dataset": true,
"dynamic_namespace": true,
"privileges": {
"indices": [
"string"
]
}
},
"type": "string"
},
"enabled": true,
"id": "string",
"keep_enabled": true,
"release": "ga",
"vars": {
"additionalProperty1": {
"frozen": true,
"type": "string"
},
"additionalProperty2": {
"frozen": true,
"type": "string"
}
}
}
],
"type": "string",
"vars": {
"additionalProperty1": {
"frozen": true,
"type": "string"
},
"additionalProperty2": {
"frozen": true,
"type": "string"
}
}
}
],
"is_managed": true,
"name": "string",
"namespace": "string",
"output_id": "string",
"overrides": {
"inputs": {}
},
"package": {
"experimental_data_stream_features": [
{
"data_stream": "string",
"features": {
"doc_value_only_numeric": true,
"doc_value_only_other": true,
"synthetic_source": true,
"tsdb": true
}
}
],
"name": "string",
"requires_root": true,
"title": "string",
"version": "string"
},
"policy_id": "string",
"policy_ids": [
"string"
],
"revision": 42.0,
"secret_references": [
{
"id": "string"
}
],
"spaceIds": [
"string"
],
"supports_agentless": false,
"updated_at": "string",
"updated_by": "string",
"vars": {
"additionalProperty1": {
"frozen": true,
"type": "string"
},
"additionalProperty2": {
"frozen": true,
"type": "string"
}
},
"version": "string"
}
],
"hasErrors": true,
"name": "string",
"statusCode": 42.0
}
]
{
"error": "string",
"message": "string",
"statusCode": 42.0
}
Rotate a Fleet message signing key pair
[Required authorization] Route required privileges: ALL of [fleet-agents-all, fleet-agent-policies-all, fleet-settings-all].
Query parameters
-
acknowledge boolean
Default value is
false
.
curl \
--request POST https://localhost:5601/api/fleet/message_signing_service/rotate_key_pair \
--header "kbn-xsrf: true"
{
"message": "string"
}
{
"error": "string",
"message": "string",
"statusCode": 42.0
}
{
"error": "string",
"message": "string",
"statusCode": 42.0
}
Delete saved objects Deprecated
WARNING: When you delete a saved object, it cannot be recovered.
Query parameters
-
force boolean
When true, force delete objects that exist in multiple namespaces. Note that the option applies to the whole request. Use the delete object API to specify per-object deletion behavior. TIP: Use this if you attempted to delete objects and received an HTTP 400 error with the following message: "Unable to delete saved object that exists in multiple namespaces, use the force option to delete it anyway". WARNING: When you bulk delete objects that exist in multiple namespaces, the API also deletes legacy url aliases that reference the object. These requests are batched to minimise the impact but they can place a heavy load on Kibana. Make sure you limit the number of objects that exist in multiple namespaces in a single bulk delete operation.
curl \
--request POST https://localhost:5601/api/saved_objects/_bulk_delete \
--header "Content-Type: application/json" \
--header "kbn-xsrf: string" \
--data '[{}]'
# Headers
kbn-xsrf: string
# Payload
[
{}
]
{}
{
"error": "Bad Request",
"message": "string",
"statusCode": 400
}
Update saved objects Deprecated
Update the attributes for multiple Kibana saved objects.
curl \
--request POST https://localhost:5601/api/saved_objects/_bulk_update \
--header "Content-Type: application/json" \
--header "kbn-xsrf: string" \
--data '[{}]'
# Headers
kbn-xsrf: string
# Payload
[
{}
]
{}
{
"error": "Bad Request",
"message": "string",
"statusCode": 400
}
Get a conversation
Get the details of an existing conversation using the conversation ID.
Path parameters
-
The conversation's
id
value.Minimum length is
1
.
curl \
--request GET https://localhost:5601/api/security_ai_assistant/current_user/conversations/{id}
{
"apiConfig": {
"actionTypeId": "string",
"connectorId": "string",
"defaultSystemPromptId": "string",
"model": "string",
"provider": "OpenAI"
},
"category": "assistant",
"createdAt": "string",
"excludeFromLastConversationStorage": true,
"id": "string",
"isDefault": true,
"messages": [
{
"content": "string",
"isError": true,
"metadata": {
"contentReferences": {}
},
"reader": {},
"role": "system",
"timestamp": "string",
"traceData": {
"traceId": "string",
"transactionId": "string"
}
}
],
"namespace": "string",
"replacements": {
"additionalProperty1": "string",
"additionalProperty2": "string"
},
"summary": {
"confidence": "low",
"content": "string",
"public": true,
"timestamp": "string"
},
"timestamp": "string",
"title": "string",
"updatedAt": "string",
"users": [
{
"id": "string",
"name": "string"
}
]
}
{
"error": "string",
"message": "string",
"statusCode": 42.0
}
Path parameters
-
resource string
The KnowledgeBase
resource
value.
curl \
--request GET https://localhost:5601/api/security_ai_assistant/knowledge_base/{resource}
{
"elser_exists": true,
"index_exists": true,
"is_setup_available": true,
"is_setup_in_progress": true,
"pipeline_exists": true,
"security_labs_exists": true,
"user_data_exists": true
}
{
"error": "string",
"message": "string",
"statusCode": 42.0
}
Assign and unassign users from detection alerts
Assign users to detection alerts, and unassign them from alerts.
You cannot add and remove the same assignee in the same request.
curl \
--request POST https://localhost:5601/api/detection_engine/signals/assignees \
--header "Content-Type: application/json" \
--data '{"ids":["681c2a707335aa7df5f349b70013d87254746191712ecf0ced9b3e2d538503a6"],"assignees":{"add":["u_MxY0jbrft7EcfC6iNZSUGeI_n6iYrSwZj5mWF5EqmSU_0"],"remove":[]}}'
{
"ids": [
"681c2a707335aa7df5f349b70013d87254746191712ecf0ced9b3e2d538503a6"
],
"assignees": {
"add": [
"u_MxY0jbrft7EcfC6iNZSUGeI_n6iYrSwZj5mWF5EqmSU_0"
],
"remove": []
}
}
{
"ids": [
"681c2a707335aa7df5f349b70013d87254746191712ecf0ced9b3e2d538503a6"
],
"assignees": {
"add": [],
"remove": [
"u_MxY0jbrft7EcfC6iNZSUGeI_n6iYrSwZj5mWF5EqmSU_0"
]
}
}
{
"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
}
Set a detection alert status
Set the status of one or more detection alerts.
Body object Required
An object containing desired status and explicit alert ids or a query to select alerts
-
List of alert
id
s.At least
1
element. Minimum length of each is1
. -
The status of an alert, which can be
open
,acknowledged
,in-progress
, orclosed
.Values are
open
,closed
,acknowledged
, orin-progress
.
curl \
--request POST https://localhost:5601/api/detection_engine/signals/status \
--header "Content-Type: application/json" \
--data '{"status":"closed","signal_ids":["80e1383f856e67c1b7f7a1634744fa6d66b6e2ef7aa26d226e57afb5a7b2b4a1"]}'
{
"status": "closed",
"signal_ids": [
"80e1383f856e67c1b7f7a1634744fa6d66b6e2ef7aa26d226e57afb5a7b2b4a1"
]
}
{
"query": {
"bool": {
"must": [],
"filter": [
{
"range": null,
"@timestamp": {
"gte": "2024-10-23T07:00:00.000Z",
"lte": "2025-01-21T20:12:11.704Z",
"format": "strict_date_optional_time"
}
},
{
"bool": {
"filter": {
"bool": {
"must": [],
"filter": [
{
"match_phrase": {
"kibana.alert.workflow_status": "open"
}
},
{
"range": null,
"@timestamp": {
"gte": "2024-10-23T07:00:00.000Z",
"lte": "2025-01-21T20:12:11.704Z",
"format": "strict_date_optional_time"
}
}
],
"should": [],
"must_not": [
{
"exists": {
"field": "kibana.alert.building_block_type"
}
}
]
}
}
}
}
],
"should": [],
"must_not": []
}
},
"status": "closed",
"conflicts": "proceed"
}
{
"took": 81,
"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
}
{
"took": 100,
"noops": 0,
"total": 17,
"batches": 1,
"deleted": 0,
"retries": {
"bulk": 0,
"search": 0
},
"updated": 17,
"failures": [],
"timed_out": false,
"throttled_millis": 0,
"version_conflicts": 0,
"requests_per_second": -1,
"throttled_until_millis": 0
}
{
"error": "string",
"message": "string",
"statusCode": 42
}
{
"message": "string",
"status_code": 42
}
{
"error": "string",
"message": "string",
"statusCode": 42
}
{
"message": "string",
"status_code": 42
}
Suspend a process
Suspend a running process on an endpoint.
Body Required
-
agent_type string
The host agent type (optional). Defaults to endpoint.
Values are
endpoint
,sentinel_one
,crowdstrike
, ormicrosoft_defender_endpoint
. -
alert_ids array[string(nonempty)]
A list of alerts
id
s.At least
1
element. Minimum length of each is1
. -
case_ids array[string]
Case IDs to be updated (cannot contain empty strings)
At least
1
element. Minimum length of each is1
. -
comment string
Optional comment
-
List of endpoint IDs (cannot contain empty strings)
At least
1
element. Minimum length of each is1
.
curl \
--request POST https://localhost:5601/api/endpoint/action/suspend_process \
--header "Content-Type: application/json" \
--data '{"agent_type":"endpoint","alert_ids":["string"],"case_ids":["string"],"comment":"string","endpoint_ids":["string"],"parameters":{"pid":42}}'
{
"agent_type": "endpoint",
"alert_ids": [
"string"
],
"case_ids": [
"string"
],
"comment": "string",
"endpoint_ids": [
"string"
],
"parameters": {
"pid": 42
}
}
{}
Get a protection updates note
curl \
--request GET https://localhost:5601/api/endpoint/protection_updates_note/{package_policy_id}
{
"note": "string"
}
Create an exception list
An exception list groups exception items and can be associated with detection rules. You can assign exception lists to multiple detection rules.
All exception items added to the same list are evaluated using OR
logic. That is, if any of the items in a list evaluate to true
, the exception prevents the rule from generating an alert. Likewise, OR
logic is used for evaluating exceptions when more than one exception list is assigned to a rule. To use the AND
operator, you can define multiple clauses (entries
) in a single exception item.
Body Required
Exception list's properties
-
Describes the exception list.
-
list_id string(nonempty)
Exception list's human readable string identifier, e.g.
trusted-linux-processes
.Minimum length is
1
. -
meta object
Placeholder for metadata about the list container.
Additional properties are allowed.
-
The name of the exception list.
-
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
orsingle
. Default value issingle
. -
os_types array[string]
Use this field to specify the operating system.
Values are
linux
,macos
, orwindows
. -
The type of exception list to be created. Different list types may denote where they can be utilized.
Values are
detection
,rule_default
,endpoint
,endpoint_trusted_apps
,endpoint_events
,endpoint_host_isolation_exceptions
, orendpoint_blocklists
. -
version integer
The document version, automatically increasd on updates.
Minimum value is
1
.
Responses
-
200 application/json
Successful response
-
400 application/json
Invalid input data response
-
401 application/json
Unsuccessful authentication response
-
403 application/json
Not enough privileges response
-
409 application/json
Exception list already exists response
-
500 application/json
Internal server error response
curl \
--request POST https://localhost:5601/api/exception_lists \
--header "Content-Type: application/json" \
--data '{"name":"Sample Detection Exception List","tags":["malware"],"type":"detection","list_id":"simple_list","os_types":["linux"],"description":"This is a sample detection type exception list.","namespace_type":"single"}'
{
"name": "Sample Detection Exception List",
"tags": [
"malware"
],
"type": "detection",
"list_id": "simple_list",
"os_types": [
"linux"
],
"description": "This is a sample detection type exception list.",
"namespace_type": "single"
}
{
"id": "28243c2f-624a-4443-823d-c0b894880931",
"name": "Sample Detection Exception List",
"tags": [
"malware"
],
"type": "detection",
"list_id": "8c1aae4c-1ef5-4bce-a2e3-16584b501783",
"version": 1,
"_version": "WzMsMV0=",
"os_types": [],
"immutable": false,
"created_at": "2025-01-09T01:05:23.019Z",
"created_by": "elastic",
"updated_at": "2025-01-09T01:05:23.020Z",
"updated_by": "elastic",
"description": "This is a sample detection type exception with an autogenerated list_id.",
"namespace_type": "single",
"tie_breaker_id": "ad94de31-39f7-4ad7-b8e4-988bfa95f338"
}
{
"id": "1a744e77-22ca-4b6b-9085-54f55275ebe5",
"name": "Sample Agnostic Endpoint Exception List",
"tags": [
"malware"
],
"type": "endpoint",
"list_id": "b935eb55-7b21-4c1c-b235-faa1df23b3d6",
"version": 1,
"_version": "WzUsMV0=",
"os_types": [
"linux"
],
"immutable": false,
"created_at": "2025-01-09T01:10:36.369Z",
"created_by": "elastic",
"updated_at": "2025-01-09T01:10:36.369Z",
"updated_by": "elastic",
"description": "This is a sample agnostic endpoint type exception.",
"namespace_type": "agnostic",
"tie_breaker_id": "49ea0adc-a2b8-4d83-a8f3-2fb98301dea3"
}
{
"id": "9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85",
"name": "Sample Detection Exception List",
"tags": [
"malware"
],
"type": "detection",
"list_id": "simple_list",
"version": 1,
"_version": "WzIsMV0=",
"os_types": [
"linux"
],
"immutable": false,
"created_at": "2025-01-07T19:34:27.942Z",
"created_by": "elastic",
"updated_at": "2025-01-07T19:34:27.942Z",
"updated_by": "elastic",
"description": "This is a sample detection type exception list.",
"namespace_type": "single",
"tie_breaker_id": "78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3"
}
{
"id": "a79f4730-6e32-4278-abfc-349c0add7d54",
"name": "Sample Endpoint Exception List",
"tags": [
"malware"
],
"type": "endpoint",
"list_id": "endpoint_list",
"version": 1,
"_version": "WzQsMV0=",
"os_types": [
"linux"
],
"immutable": false,
"created_at": "2025-01-09T01:07:49.658Z",
"created_by": "elastic",
"updated_at": "2025-01-09T01:07:49.658Z",
"updated_by": "elastic",
"description": "This is a sample endpoint type exception list.",
"namespace_type": "single",
"tie_breaker_id": "94a028af-8f47-427a-aca5-ffaf829e64ee"
}
{
"error": "Bad Request",
"message": "[request body]: list_id: Expected string, received number",
"statusCode": 400
}
{
"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
}
{
"error": "Forbidden",
"message": "API [POST /api/exception_lists] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
"statusCode": 403
}
{
"message": "exception list id: \"simple_list\" already exists",
"status_code": 409
}
{
"message": "Internal Server Error",
"status_code": 500
}
Delete an exception list
Delete an exception list using the id
or list_id
field.
Query parameters
-
id string(nonempty)
Exception list's identifier. Either
id
orlist_id
must be specified.Minimum length is
1
. -
list_id string(nonempty)
Human readable exception list string identifier, e.g.
trusted-linux-processes
. Eitherid
orlist_id
must be specified.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
orsingle
. Default value issingle
.
Responses
-
200 application/json
Successful response
-
400 application/json
Invalid input data response
-
401 application/json
Unsuccessful authentication response
-
403 application/json
Not enough privileges response
-
404 application/json
Exception list not found response
-
500 application/json
Internal server error response
curl \
--request DELETE https://localhost:5601/api/exception_lists
{
"id": "9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85",
"name": "Sample Detection Exception List",
"tags": [
"malware"
],
"type": "detection",
"list_id": "simple_list",
"version": 1,
"_version": "WzIsMV0=",
"os_types": [
"linux"
],
"immutable": false,
"created_at": "2025-01-07T19:34:27.942Z",
"created_by": "elastic",
"updated_at": "2025-01-07T19:34:27.942Z",
"updated_by": "elastic",
"description": "This is a sample detection type exception list.",
"namespace_type": "single",
"tie_breaker_id": "78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3"
}
{
"error": "Bad Request",
"message": "[request query]: namespace_type.0: Invalid enum value. Expected 'agnostic' | 'single', received 'blob'",
"statusCode": 400
}
{
"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
}
{
"error": "Forbidden",
"message": "API [DELETE /api/exception_lists?list_id=simple_list&namespace_type=single] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
"statusCode": 403
}
{
"message": "exception list list_id: \"foo\" does not exist",
"status_code": 404
}
{
"message": "Internal Server Error",
"status_code": 500
}
Export an exception list
Export an exception list and its associated items to an NDJSON file.
Query parameters
-
Exception list's identifier.
Minimum length is
1
. -
Exception list's human readable string identifier, e.g.
trusted-linux-processes
.Minimum length is
1
. -
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
orsingle
. Default value issingle
. -
Determines whether to include expired exceptions in the exported list. Expiration date defined by
expire_time
.Values are
true
orfalse
. Default value istrue
.
Responses
-
200 application/ndjson
Successful response
A
.ndjson
file containing specified exception list and its items -
400 application/json
Invalid input data response
-
401 application/json
Unsuccessful authentication response
-
403 application/json
Not enough privileges response
-
404 application/json
Exception list not found response
-
500 application/json
Internal server error response
curl \
--request POST https://localhost:5601/api/exception_lists/_export?id=9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85&list_id=simple_list&namespace_type=agnostic&include_expired_exceptions=true
{"_version":"WzExNDU5LDFd","created_at":"2025-01-09T16:18:17.757Z","created_by":"elastic","description":"This is a sample detection type exception","id":"c86c2da0-2ab6-4343-b81c-216ef27e8d75","immutable":false,"list_id":"simple_list","name":"Sample Detection Exception List","namespace_type":"single","os_types":[],"tags":["user added string for a tag","malware"],"tie_breaker_id":"cf4a7b92-732d-47f0-a0d5-49a35a1736bf","type":"detection","updated_at":"2025-01-09T16:18:17.757Z","updated_by":"elastic","version":1}
{"_version":"WzExNDYxLDFd","comments":[],"created_at":"2025-01-09T16:18:42.308Z","created_by":"elastic","description":"This is a sample endpoint type exception","entries":[{"type":"exists","field":"actingProcess.file.signer","operator":"excluded"},{"type":"match_any","field":"host.name","value":["some host","another host"],"operator":"included"}],"id":"f37597ce-eaa7-4b64-9100-4301118f6806","item_id":"simple_list_item","list_id":"simple_list","name":"Sample Endpoint Exception List","namespace_type":"single","os_types":["linux"],"tags":["user added string for a tag","malware"],"tie_breaker_id":"4ca3ef3e-9721-42c0-8107-cf47e094d40f","type":"simple","updated_at":"2025-01-09T16:18:42.308Z","updated_by":"elastic"}
{"exported_exception_list_count":1,"exported_exception_list_item_count":1,"missing_exception_list_item_count":0,"missing_exception_list_items":[],"missing_exception_lists":[],"missing_exception_lists_count":0}
{
"error": "Bad Request",
"message": "[request query]: list_id: Required, namespace_type: Required",
"statusCode": 400
}
{
"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
}
{
"error": "Forbidden",
"message": "API [POST /api/exception_lists/_export] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
"statusCode": 403
}
{
"message\"": "exception list id: \"foo\" does not exist",
"status_code\"": 404
}
{
"message": "Internal Server Error",
"status_code": 500
}
Body Required
Value list's properties
-
Describes the value list.
Minimum length is
1
. -
deserializer string
Determines how retrieved list item values are presented. By default list items are presented using these Handelbar expressions:
{{{value}}}
- Single value item types, such asip
,long
,date
,keyword
, andtext
.{{{gte}}}-{{{lte}}}
- Range value item types, such asip_range
,double_range
,float_range
,integer_range
, andlong_range
.{{{gte}}},{{{lte}}}
- Date range values.
-
id string(nonempty)
Value list's identifier.
Minimum length is
1
. -
meta object
Placeholder for metadata about the value list.
Additional properties are allowed.
-
Value list's name.
Minimum length is
1
. -
serializer string
Determines how uploaded list item values are parsed. By default, list items are parsed using these named regex groups:
(?<value>.+)
- Single value item types, such as ip, long, date, keyword, and text.(?<gte>.+)-(?<lte>.+)|(?<value>.+)
- Range value item types, such asdate_range
,ip_range
,double_range
,float_range
,integer_range
, andlong_range
.
-
Specifies the Elasticsearch data type of excludes the list container holds. Some common examples:
keyword
: Many ECS fields are Elasticsearch keywordsip
: IP addressesip_range
: Range of IP addresses (supports IPv4, IPv6, and CIDR notation)
Values are
binary
,boolean
,byte
,date
,date_nanos
,date_range
,double
,double_range
,float
,float_range
,geo_point
,geo_shape
,half_float
,integer
,integer_range
,ip
,ip_range
,keyword
,long
,long_range
,shape
,short
, ortext
. -
version integer
Minimum value is
1
. Default value is1
.
Responses
-
200 application/json
Successful response
-
400 application/json
Invalid input data response
-
401 application/json
Unsuccessful authentication response
-
403 application/json
Not enough privileges response
-
409 application/json
List already exists response
-
500 application/json
Internal server error response
curl \
--request POST https://localhost:5601/api/lists \
--header "Content-Type: application/json" \
--data '{"id":"ip_list","name":"Simple list with ips","type":"ip","description":"This list describes bad internet ips"}'
{
"id": "ip_list",
"name": "Simple list with ips",
"type": "ip",
"description": "This list describes bad internet ips"
}
{
"id": "ip_range_list",
"name": "Simple list with ip ranges",
"type": "ip_range",
"description": "This list has ip ranges"
}
{
"id": "keyword_list",
"name": "Simple list with a keyword",
"type": "keyword",
"description": "This list describes bad host names"
}
{
"id": "keyword_custom_format_list",
"name": "Simple list with a keyword using a custom format",
"type": "keyword",
"serializer": "(?<value>((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?))",
"description": "This parses the first found ipv4 only",
"deserializer": "{{value}}"
}
{
"id": "ip_list",
"name": "Simple list with ips",
"type": "ip",
"version": 1,
"_version": "WzAsMV0=",
"immutable": false,
"@timestamp": "2025-01-08T04:47:34.273Z",
"created_at": "2025-01-08T04:47:34.273Z",
"created_by": "elastic",
"updated_at": "2025-01-08T04:47:34.273Z",
"updated_by": "elastic",
"description": "This list describes bad internet ips",
"tie_breaker_id": "f5508188-b1e9-4e6e-9662-d039a7d89899"
}
{
"id": "ip_range_list",
"name": "Simple list with ip ranges",
"type": "ip_range",
"version": 1,
"_version": "WzAsMV0=",
"immutable": false,
"@timestamp": "2025-01-09T18:23:52.241Z",
"created_at": "2025-01-09T18:23:52.241Z",
"created_by": "elastic",
"updated_at": "2025-01-09T18:23:52.241Z",
"updated_by": "elastic",
"description": "This list has ip ranges",
"tie_breaker_id": "74aebdaf-601f-4940-b351-155728ff7003"
}
{
"id": "keyword_list",
"name": "Simple list with a keyword",
"type": "keyword",
"version": 1,
"_version": "WzEsMV0=",
"immutable": false,
"@timestamp": "2025-01-09T18:24:55.786Z",
"created_at": "2025-01-09T18:24:55.786Z",
"created_by": "elastic",
"updated_at": "2025-01-09T18:24:55.786Z",
"updated_by": "elastic",
"description": "This list describes bad host names",
"tie_breaker_id": "f7e7dbaa-daf7-4c9a-a3dc-56643923ef68"
}
{
"id": "keyword_custom_format_list",
"name": "Simple list with a keyword using a custom format",
"type": "keyword",
"version": 1,
"_version": "WzIsMV0=",
"immutable": false,
"@timestamp": "2025-01-09T18:25:39.604Z",
"created_at": "2025-01-09T18:25:39.604Z",
"created_by": "elastic",
"serializer": "(?<value>((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?))",
"updated_at": "2025-01-09T18:25:39.604Z",
"updated_by": "elastic",
"description": "This parses the first found ipv4 only",
"deserializer": "{{value}}",
"tie_breaker_id": "8247ae63-b780-47b8-9a89-948b643e9ec2"
}
{
"message": "To create a list, the data stream must exist first. Data stream \\\".lists-default\\\" does not exist",
"status_code": 400
}
{
"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
}
{
"error": "Forbidden",
"message": "API [POST /api/lists] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
"statusCode": 403
}
{
"message": "list id: \"keyword_custom_format_list\" already exists",
"status_code": 409
}
{
"message": "Internal Server Error",
"status_code": 500
}
Responses
-
200 application/json
Successful response
-
400 application/json
Invalid input data response
-
401 application/json
Unsuccessful authentication response
-
403 application/json
Not enough privileges response
-
404 application/json
List data stream not found response
-
500 application/json
Internal server error response
curl \
--request DELETE https://localhost:5601/api/lists/index
{
"acknowledged": true
}
{
"error": "string",
"message": "string",
"statusCode": 42
}
{
"message": "string",
"status_code": 42
}
{
"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
}
{
"error": "string",
"message": "string",
"statusCode": 42
}
{
"message": "string",
"status_code": 42
}
{
"message": "Internal Server Error",
"status_code": 500
}
Query parameters
-
id string(nonempty)
Value list item identifier. Required if
list_id
andvalue
are not specified.Minimum length is
1
. -
list_id string(nonempty)
Value list item list's
id
identfier. Required ifid
is not specified.Minimum length is
1
. -
value string
The value used to evaluate exceptions. Required if
id
is not specified.
Responses
-
200 application/json
Successful response
-
400 application/json
Invalid input data response
-
401 application/json
Unsuccessful authentication response
-
403 application/json
Not enough privileges response
-
404 application/json
List item not found response
-
500 application/json
Internal server error response
curl \
--request GET https://localhost:5601/api/lists/items
{
"id": "qN1XRJQBs4HAK3VQs3Gc",
"type": "ip",
"value": "127.0.0.2",
"list_id": "ip_list",
"_version": "WzExLDFd",
"@timestamp": "2025-01-08T05:16:25.882Z",
"created_at": "2025-01-08T05:16:25.882Z",
"created_by": "elastic",
"updated_at": "2025-01-08T05:16:25.882Z",
"updated_by": "elastic",
"tie_breaker_id": "a9a34c02-a385-436e-86a0-02a3942f3537"
}
{
"message": "Either \\\"list_id\\\" or \\\"id\\\" needs to be defined in the request",
"status_code": 400
}
{
"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
}
{
"error": "Forbidden",
"message": "API [GET /api/lists/items?id=qN1XRJQBs4HAK3VQs3Gc] is unauthorized for user, this action is granted by the Kibana privileges [lists-read]",
"statusCode": 403
}
{
"message": "list item id: \\\"foo\\\" not found",
"status_code": 404
}
{
"message": "Internal Server Error",
"status_code": 500
}
Security Osquery
Run live queries, manage packs and saved queries.