Authentication

The API accepts 2 different authentication methods:

Api key auth (http_api_key)

These APIs use key-based authentication. You must create an API key and use the encoded value in the request header. For example: Authorization: ApiKey base64AccessApiKey

Basic auth (http)

Basic auth tokens are constructed with the Basic keyword, followed by a space, followed by a base64-encoded string of your username:password (separated by a : colon).

Example: send a Authorization: Basic aGVsbG86aGVsbG8= HTTP header with your requests to authenticate with the API.

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"

Create or update agent configuration

PUT /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

Query parameters

  • overwrite boolean

    If the config exists ?overwrite=true is required

application/json

Body Required

  • agent_name string

    Agent name

  • service object Required

    Service

    Hide service attributes Show service attributes object
  • settings object Required

    Agent configuration settings

    Hide settings attribute Show settings attribute object
    • * string Additional properties

Responses

  • 200 application/json

    Successful response

    Additional properties are NOT allowed.
  • 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
PUT /api/apm/settings/agent-configuration 
curl \
 --request PUT '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 '{"agent_name":"string","service":{"environment":"prod","name":"node"},"settings":{"additionalProperty1":"string","additionalProperty2":"string"}}'
Request examples 
# Headers
elastic-api-version: 2023-10-31
kbn-xsrf: true

# Payload
{
  "agent_name": "string",
  "service": {
    "environment": "prod",
    "name": "node"
  },
  "settings": {
    "additionalProperty1": "string",
    "additionalProperty2": "string"
  }
}
Response examples (200) 
{}
Response examples (400) 
{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 400
}
Response examples (401) 
{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}
Response examples (403) 
{
  "error": "Forbidden",
  "message": "string",
  "statusCode": 403
}
Response examples (404) 
{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 404
}

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"
Response examples (200) 
{
  "environments": [
    {
      "alreadyConfigured": true,
      "name": "ALL_OPTION_VALUE"
    }
  ]
}
Response examples (400) 
{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 400
}
Response examples (401) 
{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}
Response examples (404) 
{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 404
}

Lookup single agent configuration

POST /api/apm/settings/agent-configuration/search
Api key auth Basic auth

This endpoint allows to search for single agent configuration and update 'applied_by_agent' field.

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

  • etag string

    If etags match then applied_by_agent field will be set to true

  • mark_as_applied_by_agent boolean

    markAsAppliedByAgent=true means "force setting it to true regardless of etag". This is needed for Jaeger agent that doesn't have etags

  • service object Required

    Service

    Hide service attributes Show service attributes object

Responses

  • 200 application/json

    Successful response

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

    Not found response

    Hide response attributes Show response attributes object
POST /api/apm/settings/agent-configuration/search 
curl \
 --request POST 'https://localhost:5601/api/apm/settings/agent-configuration/search' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "elastic-api-version: 2023-10-31" \
 --header "kbn-xsrf: true" \
 --data '{"etag":"0bc3b5ebf18fba8163fe4c96f491e3767a358f85","mark_as_applied_by_agent":true,"service":{"environment":"prod","name":"node"}}'
Request examples 
# Headers
elastic-api-version: 2023-10-31
kbn-xsrf: true

# Payload
{
  "etag": "0bc3b5ebf18fba8163fe4c96f491e3767a358f85",
  "mark_as_applied_by_agent": true,
  "service": {
    "environment": "prod",
    "name": "node"
  }
}
Response examples (200) 
{
  "_id": "string",
  "_index": "string",
  "_score": 42.0,
  "_source": {
    "@timestamp": 1730194190636,
    "agent_name": "string",
    "applied_by_agent": true,
    "etag": "0bc3b5ebf18fba8163fe4c96f491e3767a358f85",
    "service": {
      "environment": "prod",
      "name": "node"
    },
    "settings": {
      "additionalProperty1": "string",
      "additionalProperty2": "string"
    }
  }
}
Response examples (400) 
{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 400
}
Response examples (401) 
{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}
Response examples (404) 
{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 404
}

Get cases for an alert Technical preview

GET /api/cases/alerts/{alertId}
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

  • alertId string Required

    An identifier for the alert.

Query parameters

  • owner string | array[string]

    A filter to limit the response to a specific set of applications. If this parameter is omitted, the response contains information about all the cases that the user has access to read.

Responses

  • 200 application/json

    Indicates a successful call.

    Hide response attributes Show response attributes object
    • id string

      The case identifier.

    • title string

      The case title.
  • 401 application/json

    Authorization information is missing or invalid.

    Hide response attributes Show response attributes object
GET /api/cases/alerts/{alertId} 
curl \
 --request GET 'https://localhost:5601/api/cases/alerts/09f0c261e39e36351d75995b78bb83673774d1bc2cca9df2d15f0e5c0a99a540' \
 --header "Authorization: $API_KEY"
Response examples (200) 
[
  {
    "id": "06116b80-e1c3-11ec-be9b-9b1838238ee6",
    "title": "security_case"
  }
]
Response examples (401) 
{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}

Preview a saved object reference swap

POST /api/data_views/swap_references/_preview
Api key auth Basic auth

Preview the impact of swapping saved object references from one data view identifier to another.

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

application/json

Body Required

  • delete boolean

    Deletes referenced saved object if all references are removed.

  • forId string | array[string]

    Limit the affected saved objects to one or more by identifier.

    One of:
    string-1 string array-2 array[string]
  • forType string

    Limit the affected saved objects by type.

  • fromId string Required

    The saved object reference to change.

  • fromType string

    Specify the type of the saved object reference to alter. The default value is index-pattern for data views.

  • toId string Required

    New saved object reference value to replace the old value.

Responses

  • 200 application/json

    Indicates a successful call.

    Hide response attribute Show response attribute object
    • result array[object]
      Hide result attributes Show result attributes object
      • id string

        A saved object identifier.

      • type string

        The saved object type.
POST /api/data_views/swap_references/_preview 
curl \
 --request POST 'https://localhost:5601/api/data_views/swap_references/_preview' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"toId":"xyz-123","fromId":"abcd-efg"}'
Request example 
{
  "toId": "xyz-123",
  "fromId": "abcd-efg"
}
Response examples (200) 
{
  "result": [
    {
      "id": "string",
      "type": "string"
    }
  ]
}

Create saved objects Deprecated

POST /api/saved_objects/_bulk_create
Api key auth Basic auth

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

Query parameters

  • overwrite boolean

    When true, overwrites the document with the same identifier.

application/json

Body Required

object object

Responses

  • 200 application/json

    Indicates a successful call.
  • 400 application/json

    Bad request

    Hide response attributes Show response attributes object
POST /api/saved_objects/_bulk_create 
curl \
 --request POST 'https://localhost:5601/api/saved_objects/_bulk_create' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '[{}]'
Request examples 
# Headers
kbn-xsrf: string

# Payload
[
  {}
]
Response examples (200) 
{}
Response examples (400) 
{
  "error": "Bad Request",
  "message": "string",
  "statusCode": 400
}

Reads the alert index name if it exists

GET /api/detection_engine/index
Api key auth Basic auth

Responses

  • 200 application/json

    Successful response

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

    Unsuccessful authentication response

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

    Not enough permissions response

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

    Not found

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

    Internal server error response

    Hide response attributes Show response attributes object
GET /api/detection_engine/index 
curl \
 --request GET 'https://localhost:5601/api/detection_engine/index' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "name": ".alerts-security.alerts-default",
  "index_mapping_outdated": false
}
Response examples (401) 
{
  "error": "string",
  "message": "string",
  "statusCode": 42
}
Response examples (403) 
{
  "message": "string",
  "status_code": 42
}
Response examples (404) 
{
  "message": "string",
  "status_code": 42
}
Response examples (500) 
{
  "message": "string",
  "status_code": 42
}

Get an endpoint exception list item

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

Get the details of an endpoint exception list item using the id or item_id field.

Query parameters

  • id string(nonempty)

    Either id or item_id must be specified

    Minimum length is 1.

  • item_id string(nonempty)

    Either id or item_id must be specified

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

    • comments array[object] Required

      Array of comment fields:

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

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • created_at string(date-time) Required

        Autogenerated date of object creation.

      • created_by string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • id string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • updated_at string(date-time)

        Autogenerated date of last object update.

      • updated_by string(nonempty)

        A string that does not contain only whitespace characters

        Minimum length is 1.

    • created_at string(date-time) Required

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

    • description string Required

      Describes the exception list.

    • entries array[object] Required
      Any of:
      Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatch object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Endpoint_Exceptions_API_ExceptionListItemEntryList object Security_Endpoint_Exceptions_API_ExceptionListItemEntryExists object Security_Endpoint_Exceptions_API_ExceptionListItemEntryNested object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchWildcard object
      Hide attributes Show attributes
      • field string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • operator string Required

        Values are excluded or included.

      • type string Required Discriminator

        Value is match.

      • value string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

    • expire_time string(date-time)

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

    • id string(nonempty) Required

      Exception's identifier.

      Minimum length is 1.

    • item_id string(nonempty) Required

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

      Minimum length is 1.

    • list_id string(nonempty) Required

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

      Minimum length is 1.

    • meta object

      Additional properties are allowed.

    • name string(nonempty) Required

      Exception list name.

      Minimum length is 1.

    • namespace_type string Required

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

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

      Values are agnostic or single.

    • os_types array[string]

      Use this field to specify the operating system.

      Values are linux, macos, or windows.

    • tags array[string(nonempty)]

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

      Minimum length of each is 1.

    • tie_breaker_id string Required

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

    • type string Required

      Value is simple.

    • updated_at string(date-time) Required

      Autogenerated date of last object update.

    • updated_by string Required

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

    Invalid input data

    One of:
    Security_Endpoint_Exceptions_API_PlatformErrorResponse object Security_Endpoint_Exceptions_API_SiemErrorResponse object
    Hide attributes Show attributes
  • 401 application/json

    Unsuccessful authentication

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

    Insufficient privileges

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

    Endpoint list item not found

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

    Internal server error

    Hide response attributes Show response attributes object
GET /api/endpoint_list/items 
curl \
 --request GET 'https://localhost:5601/api/endpoint_list/items' \
 --header "Authorization: $API_KEY"
Response examples (200) 
[
  {
    "_version": "string",
    "comments": [
      {
        "comment": "string",
        "created_at": "2025-05-04T09:42:00Z",
        "created_by": "string",
        "id": "string",
        "updated_at": "2025-05-04T09:42:00Z",
        "updated_by": "string"
      }
    ],
    "created_at": "2025-05-04T09:42:00Z",
    "created_by": "string",
    "description": "string",
    "entries": [
      {
        "field": "string",
        "operator": "excluded",
        "type": "match",
        "value": "string"
      }
    ],
    "expire_time": "2025-05-04T09:42:00Z",
    "id": "71a9f4b2-c85c-49b4-866f-c71eb9e67da2",
    "item_id": "simple_list_item",
    "list_id": "simple_list",
    "meta": {},
    "name": "string",
    "namespace_type": "agnostic",
    "os_types": [
      "linux"
    ],
    "tags": [
      "string"
    ],
    "tie_breaker_id": "string",
    "type": "simple",
    "updated_at": "2025-05-04T09:42:00Z",
    "updated_by": "string"
  }
]
Response examples (400) 
{
  "error": "string",
  "message": "string",
  "statusCode": 42
}
{
  "message": "string",
  "status_code": 42
}
Response examples (401) 
{
  "error": "string",
  "message": "string",
  "statusCode": 42
}
Response examples (403) 
{
  "error": "string",
  "message": "string",
  "statusCode": 42
}
Response examples (404) 
{
  "message": "string",
  "status_code": 42
}
Response examples (500) 
{
  "message": "string",
  "status_code": 42
}

Release an isolated endpoint

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

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

application/json

Body Required

  • agent_type string

    List of agent types to retrieve. Defaults to endpoint.

    Values are endpoint, sentinel_one, crowdstrike, or microsoft_defender_endpoint.

  • alert_ids array[string(nonempty)]

    A list of alerts ids.

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

  • case_ids array[string]

    Case IDs to be updated (cannot contain empty strings)

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

  • comment string

    Optional comment

  • endpoint_ids array[string] Required

    List of endpoint IDs (cannot contain empty strings)

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

  • parameters object

    Optional parameters object

Responses

  • 200 application/json

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

Get an agent policy summary Deprecated

GET /api/endpoint/policy/summaries
Api key auth Basic auth

Query parameters

Responses

  • 200 application/json

    OK
GET /api/endpoint/policy/summaries 
curl \
 --request GET 'https://localhost:5601/api/endpoint/policy/summaries?query=%7B%7D' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{}

Update an SLO

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

You must have the write 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.

application/json

Body Required

  • budgetingMethod string

    The budgeting method to use when computing the rollup data.

    Values are occurrences or timeslices.

  • description string

    A description for the SLO.

  • groupBy string | array[string]

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

    One of:
    string-1 string array-2 array[string]

  • indicator object

    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
  • name string

    A name for the SLO.

  • objective object

    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}

  • settings object

    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.

  • tags array[string]

    List of tags

  • timeWindow object

    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.

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
    • 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.

    • 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
PUT /s/{spaceId}/api/observability/slos/{sloId} 
curl \
 --request PUT 'https://localhost:5601/s/default/api/observability/slos/9c235211-6834-11ea-a78c-6feb38a34414' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"budgetingMethod":"occurrences","description":"string","groupBy":[["service.name"],"service.name",["service.name","service.environment"]],"indicator":{"params":{"dataViewId":"03b80ab3-003d-498b-881c-3beedbaf1162","filter":"field.environment : \"production\" and service.name : \"my-service\"","good":"request.latency \u003c= 150 and request.status_code : \"2xx\"","index":"my-service-*","timestampField":"timestamp","total":"field.environment : \"production\" and service.name : \"my-service\""},"type":"sli.kql.custom"},"name":"string","objective":{"target":0.99,"timesliceTarget":0.995,"timesliceWindow":"5m"},"settings":{"frequency":"5m","preventInitialBackfill":true,"syncDelay":"5m","syncField":"event.ingested"},"tags":["string"],"timeWindow":{"duration":"30d","type":"rolling"}}'
Request examples 
# Headers
kbn-xsrf: string

# Payload
{
  "budgetingMethod": "occurrences",
  "description": "string",
  "groupBy": [
    [
      "service.name"
    ],
    "service.name",
    [
      "service.name",
      "service.environment"
    ]
  ],
  "indicator": {
    "params": {
      "dataViewId": "03b80ab3-003d-498b-881c-3beedbaf1162",
      "filter": "field.environment : \"production\" and service.name : \"my-service\"",
      "good": "request.latency <= 150 and request.status_code : \"2xx\"",
      "index": "my-service-*",
      "timestampField": "timestamp",
      "total": "field.environment : \"production\" and service.name : \"my-service\""
    },
    "type": "sli.kql.custom"
  },
  "name": "string",
  "objective": {
    "target": 0.99,
    "timesliceTarget": 0.995,
    "timesliceWindow": "5m"
  },
  "settings": {
    "frequency": "5m",
    "preventInitialBackfill": true,
    "syncDelay": "5m",
    "syncField": "event.ingested"
  },
  "tags": [
    "string"
  ],
  "timeWindow": {
    "duration": "30d",
    "type": "rolling"
  }
}
Response examples (200) 
{
  "budgetingMethod": "occurrences",
  "createdAt": "2023-01-12T10:03:19.000Z",
  "description": "My SLO description",
  "enabled": true,
  "groupBy": [
    [
      "service.name"
    ],
    "service.name",
    [
      "service.name",
      "service.environment"
    ]
  ],
  "id": "8853df00-ae2e-11ed-90af-09bb6422b258",
  "indicator": {
    "params": {
      "dataViewId": "03b80ab3-003d-498b-881c-3beedbaf1162",
      "filter": "field.environment : \"production\" and service.name : \"my-service\"",
      "good": "request.latency <= 150 and request.status_code : \"2xx\"",
      "index": "my-service-*",
      "timestampField": "timestamp",
      "total": "field.environment : \"production\" and service.name : \"my-service\""
    },
    "type": "sli.kql.custom"
  },
  "name": "My Service SLO",
  "objective": {
    "target": 0.99,
    "timesliceTarget": 0.995,
    "timesliceWindow": "5m"
  },
  "revision": 2,
  "settings": {
    "frequency": "5m",
    "preventInitialBackfill": true,
    "syncDelay": "5m",
    "syncField": "event.ingested"
  },
  "tags": [
    "string"
  ],
  "timeWindow": {
    "duration": "30d",
    "type": "rolling"
  },
  "updatedAt": "2023-01-12T10:03:19.000Z",
  "version": 2
}
Response examples (400) 
{
  "error": "Bad Request",
  "message": "Invalid value 'foo' supplied to: [...]",
  "statusCode": 400
}
Response examples (401) 
{
  "error": "Unauthorized",
  "message": "[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastics] for REST request [/_security/_authenticate]]: unable to authenticate user [elastics] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403) 
{
  "error": "Unauthorized",
  "message": "[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastics] for REST request [/_security/_authenticate]]: unable to authenticate user [elastics] for REST request [/_security/_authenticate]",
  "statusCode": 403
}
Response examples (404) 
{
  "error": "Not Found",
  "message": "SLO [3749f390-03a3-11ee-8139-c7ff60a1692d] not found",
  "statusCode": 404
}

Reset an SLO

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

You must have the write 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.

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
    • 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.

    • 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
POST /s/{spaceId}/api/observability/slos/{sloId}/_reset 
curl \
 --request POST 'https://localhost:5601/s/default/api/observability/slos/9c235211-6834-11ea-a78c-6feb38a34414/_reset' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: string"
Response examples (200) 
{
  "budgetingMethod": "occurrences",
  "createdAt": "2023-01-12T10:03:19.000Z",
  "description": "My SLO description",
  "enabled": true,
  "groupBy": [
    [
      "service.name"
    ],
    "service.name",
    [
      "service.name",
      "service.environment"
    ]
  ],
  "id": "8853df00-ae2e-11ed-90af-09bb6422b258",
  "indicator": {
    "params": {
      "dataViewId": "03b80ab3-003d-498b-881c-3beedbaf1162",
      "filter": "field.environment : \"production\" and service.name : \"my-service\"",
      "good": "request.latency <= 150 and request.status_code : \"2xx\"",
      "index": "my-service-*",
      "timestampField": "timestamp",
      "total": "field.environment : \"production\" and service.name : \"my-service\""
    },
    "type": "sli.kql.custom"
  },
  "name": "My Service SLO",
  "objective": {
    "target": 0.99,
    "timesliceTarget": 0.995,
    "timesliceWindow": "5m"
  },
  "revision": 2,
  "settings": {
    "frequency": "5m",
    "preventInitialBackfill": true,
    "syncDelay": "5m",
    "syncField": "event.ingested"
  },
  "tags": [
    "string"
  ],
  "timeWindow": {
    "duration": "30d",
    "type": "rolling"
  },
  "updatedAt": "2023-01-12T10:03:19.000Z",
  "version": 2
}
Response examples (400) 
{
  "error": "Bad Request",
  "message": "Invalid value 'foo' supplied to: [...]",
  "statusCode": 400
}
Response examples (401) 
{
  "error": "Unauthorized",
  "message": "[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastics] for REST request [/_security/_authenticate]]: unable to authenticate user [elastics] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403) 
{
  "error": "Unauthorized",
  "message": "[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastics] for REST request [/_security/_authenticate]]: unable to authenticate user [elastics] for REST request [/_security/_authenticate]",
  "statusCode": 403
}
Response examples (404) 
{
  "error": "Not Found",
  "message": "SLO [3749f390-03a3-11ee-8139-c7ff60a1692d] not found",
  "statusCode": 404
}

Get a parameter

GET /api/synthetics/params/{id}
Api key auth Basic auth

Get a parameter from the Synthetics app. You must have read privileges for the Synthetics feature in the Observability section of the Kibana feature privileges.

Path parameters

  • id string Required

    The unique identifier for the parameter.

Responses

  • 200 application/json

    A successful response.

    Hide response attributes Show response attributes object
    • description string

      The description of the parameter. It is included in the response if the user has read-only permissions to the Synthetics app.

    • id string

      The unique identifier of the parameter.

    • key string

      The key of the parameter.

    • namespaces array[string]

      The namespaces associated with the parameter. It is included in the response if the user has read-only permissions to the Synthetics app.

    • tags array[string]

      An array of tags associated with the parameter. It is included in the response if the user has read-only permissions to the Synthetics app.

    • value string

      The value associated with the parameter. It will be included in the response if the user has write permissions.

GET /api/synthetics/params/{id} 
curl \
 --request GET 'https://localhost:5601/api/synthetics/params/{id}' \
 --header "Authorization: $API_KEY"
Response examples (200)
A successful response for a user with read-only permissions to get a single parameter. 
{
  "id": "unique-parameter-id",
  "key": "your-api-key",
  "description": "Param to use in browser monitor",
  "tags": ["authentication", "security"],
  "namespaces": ["namespace1", "namespace2"]
}
A successful response for a user with write permissions to get a single parameter. 
{
  "id": "unique-parameter-id",
  "key": "your-param-key",
  "description": "Param to use in browser monitor",
  "tags": ["authentication", "security"],
  "namespaces": ["namespace1", "namespace2"],
  "value": "your-param-value"
}

Get private locations

GET /api/synthetics/private_locations
Api key auth Basic auth

Get a list of private locations. You must have read privileges for the Synthetics and Uptime feature in the Observability section of the Kibana feature privileges.

Responses

  • 200 application/json

    A successful response.

    Hide response attributes Show response attributes object
    • agentPolicyId string

      The ID of the agent policy associated with the private location.

    • geo object

      Geographic coordinates (WGS84) for the location.

      Hide geo attributes Show geo attributes object
      • lat number Required

        The latitude of the location.

      • lon number Required

        The longitude of the location.

    • id string

      The unique identifier of the private location.

    • isInvalid boolean

      Indicates whether the location is invalid. If true, the location is invalid, which means the agent policy associated with the location is deleted.

    • label string

      A label for the private location.

    • namespace string

      The namespace of the location, which is the same as the namespace of the agent policy associated with the location.
GET /api/synthetics/private_locations 
curl \
 --request GET 'https://localhost:5601/api/synthetics/private_locations' \
 --header "Authorization: $API_KEY"
Response examples (200) 
[
    {
        "label": "Test private location",
        "id": "fleet-server-policy",
        "agentPolicyId": "fleet-server-policy",
        "isInvalid": false,
        "geo": {
            "lat": 0,
            "lon": 0
        },
        "namespace": "default"
    },
    {
        "label": "Test private location 2",
        "id": "691225b0-6ced-11ee-8f5a-376306ee85ae",
        "agentPolicyId": "691225b0-6ced-11ee-8f5a-376306ee85ae",
        "isInvalid": false,
        "geo": {
            "lat": 0,
            "lon": 0
        },
        "namespace": "test"
    }
]

Get uptime settings

GET /api/uptime/settings
Api key auth Basic auth

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

Responses

  • 200 application/json

    Indicates a successful call
GET /api/uptime/settings 
curl \
 --request GET 'https://localhost:5601/api/uptime/settings' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "heartbeatIndices": "heartbeat-8*",
  "certExpirationThreshold": 30,
  "certAgeThreshold": 730,
  "defaultConnectors": [
      "08990f40-09c5-11ee-97ae-912b222b13d4",
      "db25f830-2318-11ee-9391-6b0c030836d6"
  ],
  "defaultEmail": {
      "to": [],
      "cc": [],
      "bcc": []
  }
}