Mute all alerts

POST /api/alerting/rule/{id}/_mute_all
Api key auth Basic 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.

POST /api/alerting/rule/{id}/_mute_all 
curl \
 --request POST 'https://localhost:5601/api/alerting/rule/{id}/_mute_all' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Update the API key for a rule

POST /api/alerting/rule/{id}/_update_api_key
Api key auth Basic 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://localhost:5601/api/alerting/rule/{id}/_update_api_key' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Unmute an alert

POST /api/alerting/rule/{rule_id}/alert/{alert_id}/_unmute
Api key auth Basic 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}/_unmute 
curl \
 --request POST 'https://localhost:5601/api/alerting/rule/{rule_id}/alert/{alert_id}/_unmute' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Delete agent configuration

DELETE /api/apm/settings/agent-configuration
Api key auth Basic 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://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"'
Request example
Run `DELETE /api/apm/settings/agent-configuration` to delete a configuration. 
{
    "service" : {
        "name": "frontend",
        "environment": "production"
    }
}

Get environments for service

GET /api/apm/settings/agent-configuration/environments
Api key auth Basic 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.

Query parameters

Responses

  • 200 application/json

    Successful response

    Hide response attribute Show response attribute object
    • environments array[object]

      Service environment list

      Hide environments attributes Show environments attributes 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
  • 404 application/json

    Not found response

    Hide response attributes Show response attributes object
GET /api/apm/settings/agent-configuration/environments 
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

POST /api/apm/agent_keys
Api key auth Basic auth

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 is 2023-10-31.

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

application/json

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 or config_agent:read.

Responses

  • 200 application/json

    Agent key created successfully

    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
  • 500 application/json

    Internal Server Error response

    Hide response attributes Show response attributes object
POST /api/apm/agent_keys 
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"'
Request example
Run `POST /api/apm/agent_keys` to create an APM agent API key with the specified privileges. 
{
    "name": "apm-key",
    "privileges": ["event:write", "config_agent:read"]
}
Response examples (200)
An example of a successful response from `POST /api/apm/agent_keys`, which creates an APM agent API key. 
{
  "agentKey": {
    "id": "3DCLmn0B3ZMhLUa7WBG9",
    "name": "apm-key",
    "api_key": "PjGloCGOTzaZr8ilUPvkjA",
    "encoded": "M0RDTG1uMEIzWk1oTFVhN1dCRzk6UGpHbG9DR09UemFacjhpbFVQdmtqQQ=="
  }
}

Create a service annotation

POST /api/apm/services/{serviceName}/annotation
Api key auth Basic auth

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 is 2023-10-31.

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

application/json

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.

    Hide service attributes Show service attributes object
  • tags array[string]

    Tags are used by the Applications UI to distinguish APM annotations from other annotations. Tags may have additional functionality in future releases. It defaults to [apm]. While you can add additional tags, you cannot remove the apm tag.

Responses

  • 200 application/json

    Annotation created successfully

    Hide response attributes Show response attributes 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
POST /api/apm/services/{serviceName}/annotation 
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"
    }'
Response examples (200)
An example of a successful response from `POST /api/apm/services/opbeans-java/annotation`, which creates an annotation for a service named `opbeans-java`. 
{
  "_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

GET /api/cases/{caseId}/alerts
Api key auth Basic auth

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.

Responses

  • 200 application/json

    Indicates a successful call.

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

    Authorization information is missing or invalid.

    Hide response attributes Show response attributes object
GET /api/cases/{caseId}/alerts 
curl \
 --request GET 'https://localhost:5601/api/cases/9c235210-6834-11ea-a78c-6ffb38a34414/alerts' \
 --header "Authorization: $API_KEY"
Response examples (200) 
[
  {
    "id": "f6a7d0c3-d52d-432c-b2e6-447cd7fce04d",
    "index": ".alerts-observability.logs.alerts-default",
    "attached_at": "2022-07-25T20:09:40.963Z"
  }
]

Delete a connector

DELETE /api/actions/connector/{id}
Api key auth Basic auth

WARNING: When you delete a connector, it cannot be recovered.

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    An identifier for the connector.

Responses

  • 204

    Indicates a successful call.

DELETE /api/actions/connector/{id} 
curl \
 --request DELETE 'https://localhost:5601/api/actions/connector/{id}' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Reassign an agent

POST /api/fleet/agents/{agentId}/reassign
Api key auth Basic auth

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

application/json

Body

Responses

POST /api/fleet/agents/{agentId}/reassign 
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 /api/fleet/agent_policies/{agentPolicyId}/full
Api key auth Basic 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://localhost:5601/api/fleet/agent_policies/{agentPolicyId}/full' \
 --header "Authorization: $API_KEY"

Update an agent

PUT /api/fleet/agents/{agentId}
Api key auth Basic auth

Update an agent by ID.

[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

PUT /api/fleet/agents/{agentId} 
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

GET /api/fleet/agents/setup
Api key auth Basic 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://localhost:5601/api/fleet/agents/setup' \
 --header "Authorization: $API_KEY"

Get a package signature verification key ID

GET /api/fleet/epm/verification_key_id
Api key auth Basic auth

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

Responses

GET /api/fleet/epm/verification_key_id 
curl \
 --request GET 'https://localhost:5601/api/fleet/epm/verification_key_id' \
 --header "Authorization: $API_KEY"

Get metadata for latest uninstall tokens

GET /api/fleet/uninstall_tokens
Api key auth Basic auth

List the metadata for the latest uninstall tokens per agent policy.

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

Query parameters

  • policyId string

    Partial match filtering for policy IDs

    Maximum length is 50.

  • perPage number

    The number of items to return

    Minimum value is 5.

  • page number

    Minimum value is 1.

Responses

GET /api/fleet/uninstall_tokens 
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.

Get response actions

GET /api/endpoint/action
Api key auth Basic auth

Get a list of all response actions.

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.

  • commands array[string]

    A list of response action command names.

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

  • 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, or microsoft_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 or manual.

Responses

  • 200 application/json

    OK
GET /api/endpoint/action 
curl \
 --request GET 'https://localhost:5601/api/endpoint/action' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "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"
  ]
}

Get a file

POST /api/endpoint/action/get_file
Api key auth Basic auth

Get a file from 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 attribute Show parameters attribute object

Responses

  • 200 application/json

    OK
POST /api/endpoint/action/get_file 
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"]}'
Request example 
{
  "comment": "Get my file",
  "parameters": {
    "path": "/usr/my-file.txt"
  },
  "endpoint_ids": [
    "ed518850-681a-4d60-bb98-e22640cae2a8"
  ]
}
Response examples (200) 
{
  "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

POST /api/exception_lists/_export
Api key auth Basic auth

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 or single. Default value is single.

  • include_expired_exceptions string Required

    Determines whether to include expired exceptions in the exported list. Expiration date defined by expire_time.

    Values are true or false. Default value is true.

Responses

POST /api/exception_lists/_export 
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"
Response examples (200) 
{"_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}
Response examples (400) 
{
  "error": "Bad Request",
  "message": "[request query]: list_id: Required, namespace_type: Required",
  "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/_export] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}
Response examples (404) 
{
  "message\"": "exception list id: \"foo\" does not exist",
  "status_code\"": 404
}
Response examples (500) 
{
  "message": "Internal Server Error",
  "status_code": 500
}

Get an exception list summary

GET /api/exception_lists/summary
Api key auth Basic auth

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 or single. Default value is single.

  • filter string

    Search filter clause

Responses

GET /api/exception_lists/summary 
curl \
 --request GET 'https://localhost:5601/api/exception_lists/summary' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "linux": 0,
  "macos": 0,
  "total": 0,
  "windows": 0
}
Response examples (400) 
{
  "error": "Bad Request",
  "message": "[request query]: namespace_type.0: Invalid enum value. Expected 'agnostic' | 'single', received 'blob'",
  "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 [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
}
Response examples (404) 
{
  "message\"": "exception list id: \"foo\" does not exist",
  "status_code\"": 404
}
Response examples (500) 
{
  "message": "Internal Server Error",
  "status_code": 500
}

Get value list details

GET /api/lists
Api key auth Basic auth

Get the details of a value list using the list ID.

Query parameters

  • id string(nonempty) Required

    Value list's identifier.

    Minimum length is 1.

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 document is retrieved. Use it ensure updates are done against the latest version.

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

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

    • description string(nonempty) Required

      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 as ip, long, date, keyword, and text.
      • {{{gte}}}-{{{lte}}} - Range value item types, such as ip_range, double_range, float_range, integer_range, and long_range.
      • {{{gte}}},{{{lte}}} - Date range values.
    • id string(nonempty) Required

      Value list's identifier.

      Minimum length is 1.

    • immutable boolean Required
    • 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.

    • 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 as date_range, ip_range, double_range, float_range, integer_range, and long_range.
    • tie_breaker_id string Required

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

    • type string Required

      Specifies the Elasticsearch data type of excludes the list container holds. Some common examples:

      • keyword: Many ECS fields are Elasticsearch keywords
      • ip: IP addresses
      • ip_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, or text.

    • updated_at string(date-time) Required

      Autogenerated date of last object update.

    • updated_by string Required

      Autogenerated value - user that last updated object.

    • version integer Required

      The document version number.

      Minimum value is 1.
  • 400 application/json

    Invalid input data response

    One of:
    Security_Lists_API_PlatformErrorResponse object Security_Lists_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
  • 404 application/json

    List not found response

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

    Internal server error response

    Hide response attributes Show response attributes object
GET /api/lists 
curl \
 --request GET 'https://localhost:5601/api/lists?id=21b01cfb-058d-44b9-838c-282be16c91cd' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "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"
}
Response examples (400) 
{
  "error": "Bad Request",
  "message": "[request query]: id: Required",
  "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 [GET /api/lists?id=ip_list] is unauthorized for user, this action is granted by the Kibana privileges [lists-read]",
  "statusCode": 403
}
Response examples (404) 
{
  "message": "list id: \\\"foo\\\" not found",
  "status_code": 404
}
Response examples (500) 
{
  "message": "Internal Server Error",
  "status_code": 500
}

Update a value list

PUT /api/lists
Api key auth Basic auth

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.

application/json

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.

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 document is retrieved. Use it ensure updates are done against the latest version.

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

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

    • description string(nonempty) Required

      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 as ip, long, date, keyword, and text.
      • {{{gte}}}-{{{lte}}} - Range value item types, such as ip_range, double_range, float_range, integer_range, and long_range.
      • {{{gte}}},{{{lte}}} - Date range values.
    • id string(nonempty) Required

      Value list's identifier.

      Minimum length is 1.

    • immutable boolean Required
    • 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.

    • 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 as date_range, ip_range, double_range, float_range, integer_range, and long_range.
    • tie_breaker_id string Required

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

    • type string Required

      Specifies the Elasticsearch data type of excludes the list container holds. Some common examples:

      • keyword: Many ECS fields are Elasticsearch keywords
      • ip: IP addresses
      • ip_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, or text.

    • updated_at string(date-time) Required

      Autogenerated date of last object update.

    • updated_by string Required

      Autogenerated value - user that last updated object.

    • version integer Required

      The document version number.

      Minimum value is 1.
  • 400 application/json

    Invalid input data response

    One of:
    Security_Lists_API_PlatformErrorResponse object Security_Lists_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
  • 404 application/json

    List not found response

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

    Internal server error response

    Hide response attributes Show response attributes object
PUT /api/lists 
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"}'
Request example 
{
  "id": "ip_list",
  "name": "Bad ips - updated",
  "description": "Latest list of bad ips"
}
Response examples (200) 
{
  "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"
}
Response examples (400) 
{
  "error": "Bad Request",
  "message": "[request body]: 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 [PUT /api/lists] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}
Response examples (404) 
{
  "message": "list id: \\\"foo\\\" not found",
  "status_code": 404
}
Response examples (500) 
{
  "message": "Internal Server Error",
  "status_code": 500
}

Get a value list item

GET /api/lists/items
Api key auth Basic auth

Get the details of a value list item.

Query parameters

  • id string(nonempty)

    Value list item identifier. Required if list_id and value are not specified.

    Minimum length is 1.

  • list_id string(nonempty)

    Value list item list's id identfier. Required if id 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

    One of:
    Security_Lists_API_ListItem object array-2 array[object]
    Hide attributes Show attributes
    • _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.

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

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

    • 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 as ip, long, date, keyword, and text.
      • {{{gte}}}-{{{lte}}} - Range value item types, such as ip_range, double_range, float_range, integer_range, and long_range.
      • {{{gte}}},{{{lte}}} - Date range values.
    • id string(nonempty) Required

      Value list item's identifier.

      Minimum length is 1.

    • list_id string(nonempty) Required

      Value list's identifier.

      Minimum length is 1.

    • meta object

      Placeholder for metadata about the value list item.

      Additional properties are allowed.

    • 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 as date_range, ip_range, double_range, float_range, integer_range, and long_range.
    • tie_breaker_id string Required

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

    • type string Required

      Specifies the Elasticsearch data type of excludes the list container holds. Some common examples:

      • keyword: Many ECS fields are Elasticsearch keywords
      • ip: IP addresses
      • ip_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, or text.

    • updated_at string(date-time) Required

      Autogenerated date of last object update.

    • updated_by string Required

      Autogenerated value - user that last updated object.

    • value string(nonempty) Required

      The value used to evaluate exceptions.

      Minimum length is 1.
  • 400 application/json

    Invalid input data response

    One of:
    Security_Lists_API_PlatformErrorResponse object Security_Lists_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
  • 404 application/json

    List item not found response

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

    Internal server error response

    Hide response attributes Show response attributes object
GET /api/lists/items 
curl \
 --request GET 'https://localhost:5601/api/lists/items' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "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"
}
Response examples (400) 
{
  "message": "Either \\\"list_id\\\" or \\\"id\\\" needs to be defined in the request",
  "status_code": 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 [GET /api/lists/items?id=qN1XRJQBs4HAK3VQs3Gc] is unauthorized for user, this action is granted by the Kibana privileges [lists-read]",
  "statusCode": 403
}
Response examples (404) 
{
  "message": "list item id: \\\"foo\\\" not found",
  "status_code": 404
}
Response examples (500) 
{
  "message": "Internal Server Error",
  "status_code": 500
}

Import value list items

POST /api/lists/items/_import
Api key auth Basic auth

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, or text.

  • 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 as date_range, ip_range, double_range, float_range, integer_range, and long_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 as ip, long, date, keyword, and text.
    • {{{gte}}}-{{{lte}}} - Range value item types, such as ip_range, double_range, float_range, integer_range, and long_range.
    • {{{gte}}},{{{lte}}} - Date range values.
  • refresh string

    Determines when changes made by the request are made visible to search.

    Values are true, false, or wait_for.

multipart/form-data

Body Required

  • file string(binary)

    A .txt or .csv file containing newline separated list items.

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 document is retrieved. Use it ensure updates are done against the latest version.

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

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

    • description string(nonempty) Required

      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 as ip, long, date, keyword, and text.
      • {{{gte}}}-{{{lte}}} - Range value item types, such as ip_range, double_range, float_range, integer_range, and long_range.
      • {{{gte}}},{{{lte}}} - Date range values.
    • id string(nonempty) Required

      Value list's identifier.

      Minimum length is 1.

    • immutable boolean Required
    • 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.

    • 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 as date_range, ip_range, double_range, float_range, integer_range, and long_range.
    • tie_breaker_id string Required

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

    • type string Required

      Specifies the Elasticsearch data type of excludes the list container holds. Some common examples:

      • keyword: Many ECS fields are Elasticsearch keywords
      • ip: IP addresses
      • ip_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, or text.

    • updated_at string(date-time) Required

      Autogenerated date of last object update.

    • updated_by string Required

      Autogenerated value - user that last updated object.

    • version integer Required

      The document version number.

      Minimum value is 1.
  • 400 application/json

    Invalid input data response

    One of:
    Security_Lists_API_PlatformErrorResponse object Security_Lists_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

    List with specified list_id does not exist response

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

    Internal server error response

    Hide response attributes Show response attributes object
POST /api/lists/items/_import 
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
"
Response examples (200) 
{
  "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"
}
Response examples (400) 
{
  "message": "Either type or list_id need to be defined in the query",
  "status_code": 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/lists/items/_import?list_id=ip_list] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}
Response examples (500) 
{
  "message": "Internal Server Error",
  "status_code": 500
}

Import Timelines

POST /api/timeline/_import
Api key auth Basic auth

Import Timelines.

application/json

Body Required

The Timelines to import as a readable stream.

  • isImmutable string

    Whether the Timeline should be immutable

    Values are true or false.

Responses

  • 200 application/json

    Indicates the import of Timelines was successful.

    Hide response attributes Show response attributes object
    • errors array[object]

      The list of failed Timeline imports

      Hide errors attributes Show errors attributes object
      • error object

        The error containing the reason why the timeline could not be imported

        Hide error attributes Show error attributes object
        • message string

          The reason why the timeline could not be imported

        • status_code number

          The HTTP status code of the error

      • id string

        The ID of the timeline that failed to import

    • success boolean

      Indicates whether any of the Timelines were successfully imports

    • success_count number

      The amount of successfully imported/updated Timelines

    • timelines_installed number

      The amount of successfully installed Timelines

    • timelines_updated number

      The amount of successfully updated Timelines
  • 400 application/json

    Indicates the import of Timelines was unsuccessful because of an invalid file extension.

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

    Indicates that we were unable to locate the saved object client necessary to handle the import.

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

    Indicates the import of Timelines was unsuccessful.

    Hide response attributes Show response attributes object
POST /api/timeline/_import 
curl \
 --request POST 'https://localhost:5601/api/timeline/_import' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"isImmutable":"true"}'

Get an SLO

GET /s/{spaceId}/api/observability/slos/{sloId}
Api key auth Basic auth

You must have the read privileges for the SLOs feature in the Observability section of the Kibana feature privileges.

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

Path parameters

  • spaceId string Required

    An identifier for the space. If /s/ and the identifier are omitted from the path, the default space is used.

  • sloId string Required

    An identifier for the slo.

Query parameters

  • instanceId string

    the specific instanceId used by the summary calculation

Responses

  • 200 application/json

    Successful request

    Hide response attributes Show response attributes object
    • budgetingMethod string Required

      The budgeting method to use when computing the rollup data.

      Values are occurrences or timeslices.

    • createdAt string Required

      The creation date

    • description string Required

      The description of the SLO.

    • enabled boolean Required

      Indicate if the SLO is enabled

    • groupBy string | array[string] Required

      optional group by field or fields to use to generate an SLO per distinct value

      One of:
      string-1 string array-2 array[string]
    • id string Required

      The identifier of the SLO.

    • indicator object Required

      One of:
      SLOs_indicator_properties_custom_kql object SLOs_indicator_properties_apm_availability object SLOs_indicator_properties_apm_latency object SLOs_indicator_properties_custom_metric object SLOs_indicator_properties_histogram object SLOs_indicator_properties_timeslice_metric object

      Defines properties for a custom query indicator type

      Hide attributes Show attributes
    • instanceId string Required

      the value derived from the groupBy field, if present, otherwise '*'

    • name string Required

      The name of the SLO.

    • objective object Required

      Defines properties for the SLO objective

      Hide objective attributes Show objective attributes object
      • target number Required

        the target objective between 0 and 1 excluded

        Minimum value is 0, maximum value is 100.

      • timesliceTarget number

        the target objective for each slice when using a timeslices budgeting method

        Minimum value is 0, maximum value is 100.

      • timesliceWindow string

        the duration of each slice when using a timeslices budgeting method, as {duraton}{unit}

    • revision number Required

      The SLO revision

    • settings object Required

      Defines properties for SLO settings.

      Hide settings attributes Show settings attributes object
      • frequency string

        The interval between checks for changes in the source data. The minimum value is 1m and the maximum is 59m. The default value is 1 minute.

        Default value is 1m.

      • preventInitialBackfill boolean

        Start aggregating data from the time the SLO is created, instead of backfilling data from the beginning of the time window.

        Default value is false.

      • syncDelay string

        The time delay in minutes between the current time and the latest source data time. Increasing the value will delay any alerting. The default value is 1 minute. The minimum value is 1m and the maximum is 359m. It should always be greater then source index refresh interval.

        Default value is 1m.

      • syncField string

        The date field that is used to identify new documents in the source. It is strongly recommended to use a field that contains the ingest timestamp. If you use a different field, you might need to set the delay such that it accounts for data transmission delays. When unspecified, we use the indicator timestamp field.

    • summary object Required

      The SLO computed data

      Hide summary attributes Show summary attributes object
      • errorBudget object Required
        Hide errorBudget attributes Show errorBudget attributes object
        • consumed number Required

          The error budget consummed, as a percentage of the initial value.

        • initial number Required

          The initial error budget, as 1 - objective

        • isEstimated boolean Required

          Only for SLO defined with occurrences budgeting method and calendar aligned time window.

        • remaining number Required

          The error budget remaining, as a percentage of the initial value.

      • sliValue number Required
      • status string Required

        Values are NO_DATA, HEALTHY, DEGRADING, or VIOLATED.

    • tags array[string] Required

      List of tags

    • timeWindow object Required

      Defines properties for the SLO time window

      Hide timeWindow attributes Show timeWindow attributes object
      • duration string Required

        the duration formatted as {duration}{unit}. Accepted values for rolling: 7d, 30d, 90d. Accepted values for calendar aligned: 1w (weekly) or 1M (monthly)

      • type string Required

        Indicates weither the time window is a rolling or a calendar aligned time window.

        Values are rolling or calendarAligned.

    • updatedAt string Required

      The last update date

    • version number Required

      The internal SLO version
  • 400 application/json

    Bad request

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

    Unauthorized response

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

    Unauthorized response

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

    Not found response

    Hide response attributes Show response attributes object
GET /s/{spaceId}/api/observability/slos/{sloId} 
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.

Space overview

Get features Technical Preview

GET /api/features
Api key auth Basic auth

Get information about all Kibana features. Features are used by spaces and security to refine and secure access to Kibana.

Responses

  • 200 application/json

    Indicates a successful call
GET /api/features 
curl \
 --request GET 'https://localhost:5601/api/features' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "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"
    }
  ]
}