Path parameters
-
id
string Required The identifier for the rule.
curl \
--request POST 'https://localhost:5601/api/alerting/rule/{id}/_mute_all' \
--header "Authorization: $API_KEY" \
--header "kbn-xsrf: true"
Path parameters
-
id
string Required The identifier for the rule.
curl \
--request POST 'https://localhost:5601/api/alerting/rule/{id}/_update_api_key' \
--header "Authorization: $API_KEY" \
--header "kbn-xsrf: true"
curl \
--request POST 'https://localhost:5601/api/alerting/rule/{rule_id}/alert/{alert_id}/_unmute' \
--header "Authorization: $API_KEY" \
--header "kbn-xsrf: true"
Headers
-
elastic-api-version
string Required The version of the API to use
Value is
2023-10-31
. Default value is2023-10-31
. -
kbn-xsrf
string Required A required header to protect against CSRF attacks
Body
Required
-
environment
string The environment of the service.
-
name
string The name of the service.
curl \
--request DELETE 'https://localhost:5601/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"'
{
"service" : {
"name": "frontend",
"environment": "production"
}
}
Get environments for service
Headers
-
elastic-api-version
string Required The version of the API to use
Value is
2023-10-31
. Default value is2023-10-31
.
Query parameters
-
serviceName
string The name of the service
curl \
--request GET 'https://localhost:5601/api/apm/settings/agent-configuration/environments' \
--header "Authorization: $API_KEY" \
--header "elastic-api-version: 2023-10-31"
Create an APM agent key
Create a new agent key for APM.
The user creating an APM agent API key must have at least the manage_own_api_key
cluster privilege and the APM application-level privileges that it wishes to grant.
After it is created, you can copy the API key (Base64 encoded) and use it to to authorize requests from APM agents to the APM Server.
Headers
-
elastic-api-version
string Required The version of the API to use
Value is
2023-10-31
. Default value is2023-10-31
. -
kbn-xsrf
string Required A required header to protect against CSRF attacks
Body
Required
-
name
string Required The name of the APM agent key.
-
privileges
array[string] Required The APM agent key privileges. It can take one or more of the following values:
event:write
, which is required for ingesting APM agent events. *config_agent:read
, which is required for APM agents to read agent configuration remotely.
Values are
event:write
orconfig_agent:read
.
curl \
--request POST 'https://localhost:5601/api/apm/agent_keys' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--header "elastic-api-version: 2023-10-31" \
--header "kbn-xsrf: true" \
--data '"{\n \"name\": \"apm-key\",\n \"privileges\": [\"event:write\", \"config_agent:read\"]\n}\n"'
{
"name": "apm-key",
"privileges": ["event:write", "config_agent:read"]
}
{
"agentKey": {
"id": "3DCLmn0B3ZMhLUa7WBG9",
"name": "apm-key",
"api_key": "PjGloCGOTzaZr8ilUPvkjA",
"encoded": "M0RDTG1uMEIzWk1oTFVhN1dCRzk6UGpHbG9DR09UemFacjhpbFVQdmtqQQ=="
}
}
Create a service annotation
Create a new annotation for a specific service.
Headers
-
elastic-api-version
string Required The version of the API to use
Value is
2023-10-31
. Default value is2023-10-31
. -
kbn-xsrf
string Required A required header to protect against CSRF attacks
Path parameters
-
serviceName
string Required The name of the service
Body
Required
-
@timestamp
string Required The date and time of the annotation. It must be in ISO 8601 format.
-
message
string The message displayed in the annotation. It defaults to
service.version
. -
service
object Required The service that identifies the configuration to create or update.
curl -X POST \
http://localhost:5601/api/apm/services/opbeans-java/annotation \
-H 'Content-Type: application/json' \
-H 'kbn-xsrf: true' \
-H 'Authorization: Basic YhUlubWZhM0FDbnlQeE6WRtaW49FQmSGZ4RUWXdX' \
-d '{
"@timestamp": "2020-05-08T10:31:30.452Z",
"service": {
"version": "1.2"
},
"message": "Deployment 1.2"
}'
{
"_index": "observability-annotations",
"_id": "Lc9I93EBh6DbmkeV7nFX",
"_version": 1,
"_seq_no": 12,
"_primary_term": 1,
"found": true,
"_source": {
"message": "Deployment 1.2",
"@timestamp": "2020-05-08T10:31:30.452Z",
"service": {
"version": "1.2",
"name": "opbeans-java"
},
"tags": [
"apm",
"elastic.co",
"customer"
],
"annotation": {
"type": "deployment"
},
"event": {
"created": "2020-05-09T02:34:43.937Z"
}
}
}
Get all alerts for a case
Technical preview
You must have read
privileges for the Cases feature in the Management, Observability, or Security section of the Kibana feature privileges, depending on the owner of the cases you're seeking.
Path parameters
-
caseId
string Required The identifier for the case. To retrieve case IDs, use the find cases API. All non-ASCII characters must be URL encoded.
curl \
--request GET 'https://localhost:5601/api/cases/9c235210-6834-11ea-a78c-6ffb38a34414/alerts' \
--header "Authorization: $API_KEY"
[
{
"id": "f6a7d0c3-d52d-432c-b2e6-447cd7fce04d",
"index": ".alerts-observability.logs.alerts-default",
"attached_at": "2022-07-25T20:09:40.963Z"
}
]
Delete a connector
WARNING: When you delete a connector, it cannot be recovered.
Path parameters
-
id
string Required An identifier for the connector.
curl \
--request DELETE 'https://localhost:5601/api/actions/connector/{id}' \
--header "Authorization: $API_KEY" \
--header "kbn-xsrf: true"
Reassign an agent
[Required authorization] Route required privileges: fleet-agents-all.
Path parameters
-
agentId
string Required
curl \
--request POST 'https://localhost:5601/api/fleet/agents/{agentId}/reassign' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--header "kbn-xsrf: true" \
--data '{"policy_id":"string"}'
Get a full agent policy
Get a full agent policy by ID.
[Required authorization] Route required privileges: fleet-agent-policies-read.
Path parameters
-
agentPolicyId
string Required
Query parameters
-
download
boolean -
standalone
boolean -
kubernetes
boolean
curl \
--request GET 'https://localhost:5601/api/fleet/agent_policies/{agentPolicyId}/full' \
--header "Authorization: $API_KEY"
Update an agent
Update an agent by ID.
[Required authorization] Route required privileges: fleet-agents-all.
Path parameters
-
agentId
string Required
Body
-
user_provided_metadata
object Additional properties are allowed.
curl \
--request PUT 'https://localhost:5601/api/fleet/agents/{agentId}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--header "kbn-xsrf: true" \
--data '{"tags":["string"],"user_provided_metadata":{}}'
Get agent setup info
[Required authorization] Route required privileges: fleet-agents-read OR fleet-agent-policies-read OR fleet-settings-read OR fleet-setup.
curl \
--request GET 'https://localhost:5601/api/fleet/agents/setup' \
--header "Authorization: $API_KEY"
Get a package signature verification key ID
[Required authorization] Route required privileges: integrations-read OR fleet-setup OR fleet-all.
curl \
--request GET 'https://localhost:5601/api/fleet/epm/verification_key_id' \
--header "Authorization: $API_KEY"
Get metadata for latest uninstall tokens
List the metadata for the latest uninstall tokens per agent policy.
[Required authorization] Route required privileges: fleet-agents-all.
curl \
--request GET 'https://localhost:5601/api/fleet/uninstall_tokens' \
--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.
Query parameters
-
page
integer Page number
Minimum value is
1
. Default value is1
. -
pageSize
integer Number of items per page
Minimum value is
1
, maximum value is100
. Default value is10
. -
commands
array[string] A list of response action command names.
Minimum length of each is
1
. Values areisolate
,unisolate
,kill-process
,suspend-process
,running-processes
,get-file
,execute
,upload
, orscan
. -
agentIds
array[string] | string A list of agent IDs. Max of 50.
-
userIds
array[string] | string A list of user IDs.
-
startDate
string A start date in ISO 8601 format or Date Math format.
-
endDate
string An end date in ISO format or Date Math format.
-
agentTypes
string List of agent types to retrieve. Defaults to
endpoint
.Values are
endpoint
,sentinel_one
,crowdstrike
, ormicrosoft_defender_endpoint
. -
withOutputs
array[string] | string A list of action IDs that should include the complete output of the action.
-
types
array[string] List of types of response actions
Values are
automated
ormanual
.
curl \
--request GET 'https://localhost:5601/api/endpoint/action' \
--header "Authorization: $API_KEY"
{
"data": [
{
"id": "b3d6de74-36b0-4fa8-be46-c375bf1771bf",
"agents": [
"afdc366c-e2e0-4cdb-ae1d-94575bd2d8e0"
],
"command": "running-processes",
"agentType": "endpoint",
"createdBy": "elastic",
"isExpired": false,
"startedAt": "2022-08-08T15:24:57.402Z",
"completedAt": "2022-08-08T09:50:47.672Z",
"isCompleted": true,
"wasSuccessful": true
},
{
"id": "43b4098b-8752-4fbb-a7a7-6df7c74d0ee3",
"agents": [
"afdc366c-e2e0-4cdb-ae1d-94575bd2d8e0"
],
"command": "isolate",
"agentType": "endpoint",
"createdBy": "elastic",
"isExpired": false,
"startedAt": "2022-08-08T15:23:37.359Z",
"completedAt": "2022-08-08T10:41:57.352Z",
"isCompleted": true,
"wasSuccessful": true
},
{
"id": "5bc92c86-b8e6-42dd-837f-12ad29e09caa",
"agents": [
"afdc366c-e2e0-4cdb-ae1d-94575bd2d8e0"
],
"command": "kill-process",
"comment": "bad process - taking up too much cpu",
"agentType": "endpoint",
"createdBy": "elastic",
"isExpired": false,
"startedAt": "2022-08-08T14:38:44.125Z",
"completedAt": "2022-08-08T09:44:50.952Z",
"isCompleted": true,
"wasSuccessful": true
},
{
"id": "790d54e0-3aa3-4e5b-8255-3ce9d851246a",
"agents": [
"afdc366c-e2e0-4cdb-ae1d-94575bd2d8e0"
],
"command": "unisolate",
"comment": "Not a threat to the network",
"agentType": "endpoint",
"createdBy": "elastic",
"isExpired": false,
"startedAt": "2022-08-08T14:38:15.391Z",
"completedAt": "2022-08-08T09:40:47.398Z",
"isCompleted": true,
"wasSuccessful": true
}
],
"page": 1,
"total": 4,
"endDate": "now",
"pageSize": 10,
"startDate": "now-24h/h",
"elasticAgentIds": [
"afdc366c-e2e0-4cdb-ae1d-94575bd2d8e0"
]
}
Body
Required
-
agent_type
string List of agent types to retrieve. 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
-
endpoint_ids
array[string] Required List of endpoint IDs (cannot contain empty strings)
At least
1
element. Minimum length of each is1
. -
parameters
object Required Optional parameters object
curl \
--request POST 'https://localhost:5601/api/endpoint/action/get_file' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"comment":"Get my file","parameters":{"path":"/usr/my-file.txt"},"endpoint_ids":["ed518850-681a-4d60-bb98-e22640cae2a8"]}'
{
"comment": "Get my file",
"parameters": {
"path": "/usr/my-file.txt"
},
"endpoint_ids": [
"ed518850-681a-4d60-bb98-e22640cae2a8"
]
}
{
"data": {
"id": "27ba1b42-7cc6-4e53-86ce-675c876092b2",
"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": "get-file",
"outputs": {},
"agentType": "endpoint",
"createdBy": "myuser",
"isExpired": false,
"startedAt": "2023-07-28T19:00:03.911Z",
"agentState": {
"ed518850-681a-4d60-bb98-e22640cae2a8": {
"isCompleted": false,
"wasSuccessful": false
}
},
"parameters": {
"path": "/usr/my-file.txt"
},
"isCompleted": false,
"wasSuccessful": false
}
}
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.
Export an exception list
Export an exception list and its associated items to an NDJSON file.
Query parameters
-
id
string(nonempty) Required Exception list's identifier.
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
. -
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
orsingle
. Default value issingle
. -
include_expired_exceptions
string Required 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' \
--header "Authorization: $API_KEY"
{"_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
}
Get an exception list summary
Get a summary of the specified exception list.
Query parameters
-
id
string(nonempty) Exception list's identifier generated upon creation.
Minimum length is
1
. -
list_id
string(nonempty) Exception list's human readable identifier.
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
. -
filter
string Search filter clause
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 GET 'https://localhost:5601/api/exception_lists/summary' \
--header "Authorization: $API_KEY"
{
"linux": 0,
"macos": 0,
"total": 0,
"windows": 0
}
{
"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 [GET /api/exception_lists/summary?list_id=simple_list&namespace_type=agnostic] is unauthorized for user, this action is granted by the Kibana privileges [lists-summary]",
"statusCode": 403
}
{
"message\"": "exception list id: \"foo\" does not exist",
"status_code\"": 404
}
{
"message": "Internal Server Error",
"status_code": 500
}
Query parameters
-
id
string(nonempty) Required Value list's identifier.
Minimum length is
1
.
curl \
--request GET 'https://localhost:5601/api/lists?id=21b01cfb-058d-44b9-838c-282be16c91cd' \
--header "Authorization: $API_KEY"
{
"id": "ip_list",
"name": "My bad ips",
"type": "ip",
"version": 1,
"_version": "WzEsMV0=",
"immutable": false,
"@timestamp": "2025-01-08T04:47:34.273Z",
"created_at": "2025-01-08T04:47:34.273Z",
"created_by": "elastic",
"updated_at": "2025-01-08T05:21:53.843Z",
"updated_by": "elastic",
"description": "This list describes bad internet ip",
"tie_breaker_id": "f5508188-b1e9-4e6e-9662-d039a7d89899"
}
{
"error": "Bad Request",
"message": "[request query]: id: 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 [GET /api/lists?id=ip_list] is unauthorized for user, this action is granted by the Kibana privileges [lists-read]",
"statusCode": 403
}
{
"message": "list id: \\\"foo\\\" not found",
"status_code": 404
}
{
"message": "Internal Server Error",
"status_code": 500
}
Update a value list
Update a value list using the list id
. The original list is replaced, and all unspecified fields are deleted.
You cannot modify the id
value.
Body
Required
Value list's properties
-
_version
string The version id, normally returned by the API when the document is retrieved. Use it ensure updates are done against the latest version.
-
description
string(nonempty) Required Describes the value list.
Minimum length is
1
. -
id
string(nonempty) Required Value list's identifier.
Minimum length is
1
. -
meta
object Placeholder for metadata about the value list.
Additional properties are allowed.
-
name
string(nonempty) Required Value list's name.
Minimum length is
1
. -
version
integer The document version number.
Minimum value is
1
.
curl \
--request PUT 'https://localhost:5601/api/lists' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"id":"ip_list","name":"Bad ips - updated","description":"Latest list of bad ips"}'
{
"id": "ip_list",
"name": "Bad ips - updated",
"description": "Latest list of bad ips"
}
{
"id": "ip_list",
"name": "Bad ips - updated",
"type": "ip",
"version": 3,
"_version": "WzIsMV0=",
"immutable": false,
"@timestamp": "2025-01-08T04:47:34.273Z",
"created_at": "2025-01-08T04:47:34.273Z",
"created_by": "elastic",
"updated_at": "2025-01-08T05:39:39.292Z",
"updated_by": "elastic",
"description": "Latest list of bad ips",
"tie_breaker_id": "f5508188-b1e9-4e6e-9662-d039a7d89899"
}
{
"error": "Bad Request",
"message": "[request body]: 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 [PUT /api/lists] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
"statusCode": 403
}
{
"message": "list id: \\\"foo\\\" not found",
"status_code": 404
}
{
"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' \
--header "Authorization: $API_KEY"
{
"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
}
Import value list items
Import value list items from a TXT or CSV file. The maximum file size is 9 million bytes.
You can import items to a new or existing list.
Query parameters
-
list_id
string(nonempty) List's id.
Required when importing to an existing list.
Minimum length is
1
. -
type
string Type of the importing list.
Required when importing a new list whose list
id
is not specified.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
. -
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
.
-
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.
-
refresh
string Determines when changes made by the request are made visible to search.
Values are
true
,false
, orwait_for
.
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 with specified list_id does not exist response
-
500 application/json
Internal server error response
curl \
--request POST 'https://localhost:5601/api/lists/items/_import' \
--header "Authorization: $API_KEY" \
--header "Content-Type: multipart/form-data" \
--form "file=127.0.0.1
127.0.0.2
127.0.0.3
127.0.0.4
127.0.0.5
127.0.0.6
127.0.0.7
127.0.0.8
127.0.0.9
"
{
"id": "ip_list",
"name": "Simple list with an ip",
"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 ip",
"tie_breaker_id": "f5508188-b1e9-4e6e-9662-d039a7d89899"
}
{
"message": "Either type or list_id need to be defined in the query",
"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/items/_import?list_id=ip_list] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
"statusCode": 403
}
{
"message": "Internal Server Error",
"status_code": 500
}
Body
Required
The Timelines to import as a readable stream.
-
isImmutable
string Whether the Timeline should be immutable
Values are
true
orfalse
.
Responses
-
200 application/json
Indicates the import of Timelines was successful.
-
400 application/json
Indicates the import of Timelines was unsuccessful because of an invalid file extension.
-
404 application/json
Indicates that we were unable to locate the saved object client necessary to handle the import.
-
409 application/json
Indicates the import of Timelines was unsuccessful.
curl \
--request POST 'https://localhost:5601/api/timeline/_import' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"isImmutable":"true"}'
Get an SLO
You must have the read
privileges for the SLOs feature in the Observability section of the Kibana feature privileges.
Query parameters
-
instanceId
string the specific instanceId used by the summary calculation
curl \
--request GET 'https://localhost:5601/s/default/api/observability/slos/9c235211-6834-11ea-a78c-6feb38a34414' \
--header "Authorization: $API_KEY" \
--header "kbn-xsrf: string"
Spaces
Manage your Kibana spaces.
Get features
Technical Preview
Get information about all Kibana features. Features are used by spaces and security to refine and secure access to Kibana.
curl \
--request GET 'https://localhost:5601/api/features' \
--header "Authorization: $API_KEY"
{
"features": [
{
"name": "tasks",
"description": "Manages task results"
},
{
"name": "security",
"description": "Manages configuration for Security features, such as users and roles"
},
{
"name": "searchable_snapshots",
"description": "Manages caches and configuration for searchable snapshots"
},
{
"name": "logstash_management",
"description": "Enables Logstash Central Management pipeline storage"
},
{
"name": "transform",
"description": "Manages configuration and state for transforms"
},
{
"name": "kibana",
"description": "Manages Kibana configuration and reports"
},
{
"name": "synonyms",
"description": "Manages synonyms"
},
{
"name": "async_search",
"description": "Manages results of async searches"
},
{
"name": "ent_search",
"description": "Manages configuration for Enterprise Search features"
},
{
"name": "machine_learning",
"description": "Provides anomaly detection and forecasting functionality"
},
{
"name": "geoip",
"description": "Manages data related to GeoIP database downloader"
},
{
"name": "watcher",
"description": "Manages Watch definitions and state"
},
{
"name": "fleet",
"description": "Manages configuration for Fleet"
},
{
"name": "enrich",
"description": "Manages data related to Enrich policies"
},
{
"name": "inference_plugin",
"description": "Inference plugin for managing inference services and inference"
}
]
}