Push a case to an external service

POST /api/cases/{caseId}/connector/{connectorId}/_push

You must have all privileges for the Actions and Connectors feature in the Management section of the Kibana feature privileges. You must also have all privileges for the Cases feature in the Management, Observability, or Security section of the Kibana feature privileges, depending on the owner of the case you're pushing.

Headers

kbn-xsrf string Required

Cross-site request forgery protection

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.
connectorId string Required

An identifier for the connector. To retrieve connector IDs, use the find connectors API.

application/json

Body

object | null

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- assignees array[object] | null
  
  An array containing users that are assigned to the case.
  
  Not more than 10 elements.
  
  Hide assignees attribute Show assignees attribute object
  
  uid string Required
  
  A unique identifier for the user profile. These identifiers can be found by using the suggest user profile API.
- category string | null
  
  The case category.
- closed_at string(date-time) | null Required
- closed_by object | null Required
  
  Hide closed_by attributes Show closed_by attributes object | null
  
  email string | null Required
  
  full_name string | null Required
  
  profile_uid string
  
  username string | null Required
- comments array[object] Required
  
  An array of comment objects for the case.
  
  Not more than 10000 elements.
  
  One of:
  Cases_alert_comment_response_properties object Cases_user_comment_response_properties object
  
  Hide attributes Show attributes
  
  alertId array[string]
  
  created_at string(date-time)
  
  created_by object
  
  Hide created_by attributes Show created_by attributes object
  
  email string | null Required
  
  full_name string | null Required
  
  profile_uid string
  
  username string | null Required
  
  id string
  
  index array[string]
  
  owner string
  
  The application that owns the cases: Stack Management, Observability, or Elastic Security.
  
  Values are cases, observability, or securitySolution.
  
  pushed_at string(date-time) | null
  
  pushed_by object | null
  
  Hide pushed_by attributes Show pushed_by attributes object | null
  
  email string | null Required
  
  full_name string | null Required
  
  profile_uid string
  
  username string | null Required
  
  rule object
  
  Hide rule attributes Show rule attributes object
  
  id string
  
  The rule identifier.
  
  name string
  
  The rule name.
  
  type string Required Discriminator
  
  Value is alert.
  
  updated_at string(date-time) | null
  
  updated_by object | null
  
  Hide updated_by attributes Show updated_by attributes object | null
  
  email string | null Required
  
  full_name string | null Required
  
  profile_uid string
  
  username string | null Required
  
  version string
  
  Hide attributes Show attributes
  
  comment string
  
  created_at string(date-time)
  
  created_by object
  
  Hide created_by attributes Show created_by attributes object
  
  email string | null Required
  
  full_name string | null Required
  
  profile_uid string
  
  username string | null Required
  
  id string
  
  owner string
  
  The application that owns the cases: Stack Management, Observability, or Elastic Security.
  
  Values are cases, observability, or securitySolution.
  
  pushed_at string(date-time) | null
  
  pushed_by object | null
  
  Hide pushed_by attributes Show pushed_by attributes object | null
  
  email string | null Required
  
  full_name string | null Required
  
  profile_uid string
  
  username string | null Required
  
  type string Required Discriminator
  
  Value is user.
  
  updated_at string(date-time) | null
  
  updated_by object | null
  
  Hide updated_by attributes Show updated_by attributes object | null
  
  email string | null Required
  
  full_name string | null Required
  
  profile_uid string
  
  username string | null Required
  
  version string
- connector object Required
  
  One of:
  Cases_connector_properties_none object Cases_connector_properties_cases_webhook object Cases_connector_properties_jira object Cases_connector_properties_resilient object Cases_connector_properties_servicenow object Cases_connector_properties_servicenow_sir object Cases_connector_properties_swimlane object
  
  Defines properties for connectors when type is .none.
  
  Hide attributes Show attributes
  
  fields string | null Required
  
  An object containing the connector fields. To create a case without a connector, specify null. To update a case to remove the connector, specify null.
  
  id string Required
  
  The identifier for the connector. To create a case without a connector, use none. To update a case to remove the connector, specify none.
  
  name string Required
  
  The name of the connector. To create a case without a connector, use none. To update a case to remove the connector, specify none.
  
  type string Required Discriminator
  
  The type of connector. To create a case without a connector, use .none. To update a case to remove the connector, specify .none.
  
  Value is .none.
  
  Defines properties for connectors when type is .cases-webhook.
  
  Hide attributes Show attributes
  
  fields string | null Required
  
  id string Required
  
  The identifier for the connector. To retrieve connector IDs, use the find connectors API.
  
  name string Required
  
  The name of the connector.
  
  type string Required Discriminator
  
  The type of connector.
  
  Value is .cases-webhook.
  
  Defines properties for connectors when type is .jira.
  
  Hide attributes Show attributes
  
  fields object Required
  
  An object containing the connector fields. If you want to omit any individual field, specify null as its value.
  
  Hide fields attributes Show fields attributes object
  
  issueType string | null Required
  
  The type of issue.
  
  parent string | null Required
  
  The key of the parent issue, when the issue type is sub-task.
  
  priority string | null Required
  
  The priority of the issue.
  
  id string Required
  
  The identifier for the connector. To retrieve connector IDs, use the find connectors API.
  
  name string Required
  
  The name of the connector.
  
  type string Required Discriminator
  
  The type of connector.
  
  Value is .jira.
  
  Defines properties for connectors when type is .resilient.
  
  Hide attributes Show attributes
  
  fields object | null Required
  
  An object containing the connector fields. If you want to omit any individual field, specify null as its value.
  
  Hide fields attributes Show fields attributes object | null
  
  issueTypes array[string] Required
  
  The type of incident.
  
  severityCode string Required
  
  The severity code of the incident.
  
  id string Required
  
  The identifier for the connector.
  
  name string Required
  
  The name of the connector.
  
  type string Required Discriminator
  
  The type of connector.
  
  Value is .resilient.
  
  Defines properties for connectors when type is .servicenow.
  
  Hide attributes Show attributes
  
  fields object Required
  
  An object containing the connector fields. If you want to omit any individual field, specify null as its value.
  
  Hide fields attributes Show fields attributes object
  
  category string | null Required
  
  The category of the incident.
  
  impact string | null Required
  
  The effect an incident had on business.
  
  severity string | null Required
  
  The severity of the incident.
  
  subcategory string | null Required
  
  The subcategory of the incident.
  
  urgency string | null Required
  
  The extent to which the incident resolution can be delayed.
  
  id string Required
  
  The identifier for the connector. To retrieve connector IDs, use the find connectors API.
  
  name string Required
  
  The name of the connector.
  
  type string Required Discriminator
  
  The type of connector.
  
  Value is .servicenow.
  
  Defines properties for connectors when type is .servicenow-sir.
  
  Hide attributes Show attributes
  
  fields object Required
  
  An object containing the connector fields. If you want to omit any individual field, specify null as its value.
  
  Hide fields attributes Show fields attributes object
  
  category string | null Required
  
  The category of the incident.
  
  destIp boolean | null Required
  
  Indicates whether cases will send a comma-separated list of destination IPs.
  
  malwareHash boolean | null Required
  
  Indicates whether cases will send a comma-separated list of malware hashes.
  
  malwareUrl boolean | null Required
  
  Indicates whether cases will send a comma-separated list of malware URLs.
  
  priority string | null Required
  
  The priority of the issue.
  
  sourceIp boolean | null Required
  
  Indicates whether cases will send a comma-separated list of source IPs.
  
  subcategory string | null Required
  
  The subcategory of the incident.
  
  id string Required
  
  The identifier for the connector. To retrieve connector IDs, use the find connectors API.
  
  name string Required
  
  The name of the connector.
  
  type string Required Discriminator
  
  The type of connector.
  
  Value is .servicenow-sir.
  
  Defines properties for connectors when type is .swimlane.
  
  Hide attributes Show attributes
  
  fields object Required
  
  An object containing the connector fields. If you want to omit any individual field, specify null as its value.
  
  Hide fields attribute Show fields attribute object
  
  caseId string | null Required
  
  The case identifier for Swimlane connectors.
  
  id string Required
  
  The identifier for the connector. To retrieve connector IDs, use the find connectors API.
  
  name string Required
  
  The name of the connector.
  
  type string Required Discriminator
  
  The type of connector.
  
  Value is .swimlane.
- created_at string(date-time) Required
- created_by object Required
  
  Hide created_by attributes Show created_by attributes object
  
  email string | null Required
  
  full_name string | null Required
  
  profile_uid string
  
  username string | null Required
- customFields array[object]
  
  Custom field values for the case.
  
  Hide customFields attributes Show customFields attributes object
  
  key string
  
  The unique identifier for the custom field. The key value must exist in the case configuration settings.
  
  type string
  
  The custom field type. It must match the type specified in the case configuration settings.
  
  Values are text or toggle.
  
  value string | null | boolean
  
  The custom field value. If the custom field is required, it cannot be explicitly set to null. However, for cases that existed when the required custom field was added, the default value stored in Elasticsearch is undefined. The value returned in the API and user interface in this case is null.
  
  One of:
  string-1 string | null boolean-2 boolean
  
  Minimum length is 1, maximum length is 160.
- description string Required
- duration integer | null Required
  
  The elapsed time from the creation of the case to its closure (in seconds). If the case has not been closed, the duration is set to null. If the case was closed after less than half a second, the duration is rounded down to zero.
- external_service object | null Required
  
  Hide external_service attributes Show external_service attributes object | null
  
  connector_id string
  
  connector_name string
  
  external_id string
  
  external_title string
  
  external_url string
  
  pushed_at string(date-time)
  
  pushed_by object | null
  
  Hide pushed_by attributes Show pushed_by attributes object | null
  
  email string | null
  
  full_name string | null
  
  profile_uid string
  
  username string | null
- id string Required
- owner string Required
  
  The application that owns the cases: Stack Management, Observability, or Elastic Security.
  
  Values are cases, observability, or securitySolution.
- settings object Required
  
  An object that contains the case settings.
  
  Hide settings attribute Show settings attribute object
  
  syncAlerts boolean Required
  
  Turns alert syncing on or off.
- severity string Required
  
  The severity of the case.
  
  Values are critical, high, low, or medium. Default value is low.
- status string Required
  
  The status of the case.
  
  Values are closed, in-progress, or open.
- tags array[string] Required
- title string Required
- totalAlerts integer Required
- totalComment integer Required
- updated_at string(date-time) | null Required
- updated_by object | null Required
  
  Hide updated_by attributes Show updated_by attributes object | null
  
  email string | null Required
  
  full_name string | null Required
  
  profile_uid string
  
  username string | null Required
- version string Required
401 application/json

Authorization information is missing or invalid.
Hide response attributes Show response attributes object
- error string
- message string
- statusCode integer

POST /api/cases/{caseId}/connector/{connectorId}/_push

curl \
 --request POST 'https://localhost:5601/api/cases/9c235210-6834-11ea-a78c-6ffb38a34414/connector/abed3a70-71bd-11ea-a0b2-c51ea50a58e2/_push' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string"

Request examples

# Headers
kbn-xsrf: string

# Payload
{}

Response examples (200)

{
  "id": "b917f300-0ed9-11ed-bd18-65557fe66949",
  "tags": [
    "tag 1"
  ],
  "owner": "cases",
  "title": "Case title 1",
  "status": "open",
  "version": "WzE3NjgsM10=",
  "comments": [],
  "duration": null,
  "settings": {
    "syncAlerts": true
  },
  "severity": "low",
  "closed_at": null,
  "closed_by": null,
  "connector": {
    "id": "09f8c0b0-0eda-11ed-bd18-65557fe66949",
    "name": "My connector",
    "type": ".jira",
    "fields": {
      "parent": null,
      "priority": "Low",
      "issueType": "10006"
    }
  },
  "created_at": "2022-07-29T00:59:39.444Z",
  "created_by": {
    "email": null,
    "username": "elastic",
    "full_name": null
  },
  "updated_at": "2022-07-29T01:20:58.436Z",
  "updated_by": {
    "email": null,
    "username": "elastic",
    "full_name": null
  },
  "description": "A case description.",
  "totalAlerts": 0,
  "totalComment": 0,
  "external_service": {
    "pushed_at": "2022-07-29T01:20:58.436Z",
    "pushed_by": {
      "email": null,
      "username": "elastic",
      "full_name": null
    },
    "external_id": "71926",
    "connector_id": "09f8c0b0-0eda-11ed-bd18-65557fe66949",
    "external_url": "https://cases.jira.com",
    "connector_name": "My connector",
    "external_title": "ES-554"
  }
}

Response examples (401)

{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}

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
- error string
- message string
- statusCode integer

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
}

Get all connectors

GET /api/actions/connectors

Api key auth Basic auth

Responses

200 application/json

Indicates a successful call.

GET /api/actions/connectors

curl \
 --request GET 'https://localhost:5601/api/actions/connectors' \
 --header "Authorization: $API_KEY"

Response examples (200)

[
  {
    "id": "preconfigured-email-connector",
    "name": "my-preconfigured-email-notification",
    "is_deprecated": false,
    "is_preconfigured": true,
    "is_system_action": false,
    "connector_type_id": ".email",
    "referenced_by_count": 0
  },
  {
    "id": "e07d0c80-8b8b-11ed-a780-3b746c987a81",
    "name": "my-index-connector",
    "config": {
      "index": "test-index",
      "refresh": false,
      "executionTimeField": null
    },
    "is_deprecated": false,
    "is_preconfigured": false,
    "is_system_action": false,
    "connector_type_id": ".index",
    "is_missing_secrets": false,
    "referenced_by_count": 2
  }
]

Delete a dashboard Technical Preview

DELETE /api/dashboards/dashboard/{id}

Api key auth Basic auth

This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

A unique identifier for the dashboard.

DELETE /api/dashboards/dashboard/{id}

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

Delete an uploaded file

DELETE /api/fleet/agents/files/{fileId}

Api key auth Basic auth

Delete a file uploaded by an agent.

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

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

fileId string Required

Responses

200 application/json
Hide response attributes Show response attributes object
- deleted boolean Required
- id string Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

DELETE /api/fleet/agents/files/{fileId}

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

Response examples (200)

{
  "deleted": true,
  "id": "string"
}

Response examples (400)

{
  "error": "string",
  "errorType": "string",
  "message": "string",
  "statusCode": 42.0
}

Bulk get assets

POST /api/fleet/epm/bulk_assets

Api key auth Basic auth

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

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

assetIds array[object] Required
Hide assetIds attributes Show assetIds attributes object
- id string Required
- type string Required

Responses

200 application/json
Hide response attribute Show response attribute object
- items array[object] Required
  
  Hide items attributes Show items attributes object
  
  appLink string
  
  attributes object Required
  
  Additional properties are NOT allowed.
  
  Hide attributes attributes Show attributes attributes object
  
  description string
  
  service string
  
  title string
  
  id string Required
  
  type string Required
  
  updatedAt string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/epm/bulk_assets

curl \
 --request POST 'https://localhost:5601/api/fleet/epm/bulk_assets' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"assetIds":[{"id":"string","type":"string"}]}'

Request examples

# Headers
kbn-xsrf: true

# Payload
{
  "assetIds": [
    {
      "id": "string",
      "type": "string"
    }
  ]
}

Response examples (200)

{
  "items": [
    {
      "appLink": "string",
      "attributes": {
        "description": "string",
        "service": "string",
        "title": "string"
      },
      "id": "string",
      "type": "string",
      "updatedAt": "string"
    }
  ]
}

Response examples (400)

{
  "error": "string",
  "errorType": "string",
  "message": "string",
  "statusCode": 42.0
}

Get Fleet Server hosts

GET /api/fleet/fleet_server_hosts

Api key auth Basic auth

[Required authorization] Route required privileges: ANY of [fleet-agents-all OR fleet-settings-read].

Responses

200 application/json
Hide response attributes Show response attributes object
- items array[object] Required
  
  Hide items attributes Show items attributes object
  
  host_urls array[string] Required
  
  At least 1 element.
  
  id string Required
  
  is_default boolean
  
  Default value is false.
  
  is_internal boolean
  
  is_preconfigured boolean
  
  Default value is false.
  
  name string Required
  
  proxy_id string | null
  
  secrets object
  
  Additional properties are NOT allowed.
  
  Hide secrets attribute Show secrets attribute object
  
  ssl object
  
  Additional properties are NOT allowed.
  
  Hide ssl attributes Show ssl attributes object
  
  es_key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  ssl object | null
  
  Additional properties are NOT allowed.
  
  Hide ssl attributes Show ssl attributes object | null
  
  certificate string
  
  certificate_authorities array[string]
  
  client_auth string
  
  Values are optional, required, or none.
  
  es_certificate string
  
  es_certificate_authorities array[string]
  
  es_key string
  
  key string
- page number Required
- perPage number Required
- total number Required
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

GET /api/fleet/fleet_server_hosts

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

Response examples (200)

{
  "items": [
    {
      "host_urls": [
        "string"
      ],
      "id": "string",
      "is_default": false,
      "is_internal": true,
      "is_preconfigured": false,
      "name": "string",
      "proxy_id": "string",
      "secrets": {
        "ssl": {
          "es_key": {
            "id": "string"
          },
          "key": {
            "id": "string"
          }
        }
      },
      "ssl": {
        "certificate": "string",
        "certificate_authorities": [
          "string"
        ],
        "client_auth": "optional",
        "es_certificate": "string",
        "es_certificate_authorities": [
          "string"
        ],
        "es_key": "string",
        "key": "string"
      }
    }
  ],
  "page": 42.0,
  "perPage": 42.0,
  "total": 42.0
}

Response examples (400)

{
  "error": "string",
  "errorType": "string",
  "message": "string",
  "statusCode": 42.0
}

Create a Fleet Server host

POST /api/fleet/fleet_server_hosts

Api key auth Basic auth

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

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

host_urls array[string] Required

At least 1 element.
id string
is_default boolean

Default value is false.
is_internal boolean
is_preconfigured boolean

Default value is false.
name string Required
proxy_id string | null
secrets object

Additional properties are NOT allowed.
Hide secrets attribute Show secrets attribute object
- ssl object
  
  Additional properties are NOT allowed.
  Hide ssl attributes Show ssl attributes object
  
  es_key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
ssl object | null

Additional properties are NOT allowed.
Hide ssl attributes Show ssl attributes object | null
- certificate string
- certificate_authorities array[string]
- client_auth string
  
  Values are optional, required, or none.
- es_certificate string
- es_certificate_authorities array[string]
- es_key string
- key string

Responses

200 application/json
Hide response attribute Show response attribute object
- item object Required
  
  Additional properties are NOT allowed.
  
  Hide item attributes Show item attributes object
  
  host_urls array[string] Required
  
  At least 1 element.
  
  id string Required
  
  is_default boolean
  
  Default value is false.
  
  is_internal boolean
  
  is_preconfigured boolean
  
  Default value is false.
  
  name string Required
  
  proxy_id string | null
  
  secrets object
  
  Additional properties are NOT allowed.
  
  Hide secrets attribute Show secrets attribute object
  
  ssl object
  
  Additional properties are NOT allowed.
  
  Hide ssl attributes Show ssl attributes object
  
  es_key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  key object | string
  
  Any of:
  object-1 object string-2 string
  
  Hide attribute Show attribute
  
  id string Required
  
  ssl object | null
  
  Additional properties are NOT allowed.
  
  Hide ssl attributes Show ssl attributes object | null
  
  certificate string
  
  certificate_authorities array[string]
  
  client_auth string
  
  Values are optional, required, or none.
  
  es_certificate string
  
  es_certificate_authorities array[string]
  
  es_key string
  
  key string
400 application/json
Hide response attributes Show response attributes object
- error string
- errorType string
- message string Required
- statusCode number

POST /api/fleet/fleet_server_hosts

curl \
 --request POST 'https://localhost:5601/api/fleet/fleet_server_hosts' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"host_urls":["string"],"id":"string","is_default":false,"is_internal":true,"is_preconfigured":false,"name":"string","proxy_id":"string","secrets":{"ssl":{"es_key":{"id":"string"},"key":{"id":"string"}}},"ssl":{"certificate":"string","certificate_authorities":["string"],"client_auth":"optional","es_certificate":"string","es_certificate_authorities":["string"],"es_key":"string","key":"string"}}'

Request examples

# Headers
kbn-xsrf: true

# Payload
{
  "host_urls": [
    "string"
  ],
  "id": "string",
  "is_default": false,
  "is_internal": true,
  "is_preconfigured": false,
  "name": "string",
  "proxy_id": "string",
  "secrets": {
    "ssl": {
      "es_key": {
        "id": "string"
      },
      "key": {
        "id": "string"
      }
    }
  },
  "ssl": {
    "certificate": "string",
    "certificate_authorities": [
      "string"
    ],
    "client_auth": "optional",
    "es_certificate": "string",
    "es_certificate_authorities": [
      "string"
    ],
    "es_key": "string",
    "key": "string"
  }
}

Response examples (200)

{
  "item": {
    "host_urls": [
      "string"
    ],
    "id": "string",
    "is_default": false,
    "is_internal": true,
    "is_preconfigured": false,
    "name": "string",
    "proxy_id": "string",
    "secrets": {
      "ssl": {
        "es_key": {
          "id": "string"
        },
        "key": {
          "id": "string"
        }
      }
    },
    "ssl": {
      "certificate": "string",
      "certificate_authorities": [
        "string"
      ],
      "client_auth": "optional",
      "es_certificate": "string",
      "es_certificate_authorities": [
        "string"
      ],
      "es_key": "string",
      "key": "string"
    }
  }
}

Response examples (400)

{
  "error": "string",
  "errorType": "string",
  "message": "string",
  "statusCode": 42.0
}

Sync saved objects in the default space

GET /api/ml/saved_objects/sync

Api key auth Basic auth

Synchronizes Kibana saved objects for machine learning jobs and trained models in the default space. You must have all privileges for the Machine Learning feature in the Analytics section of the Kibana feature privileges. This API runs automatically when you start Kibana and periodically thereafter.

Query parameters

simulate boolean

When true, simulates the synchronization by returning only the list of actions that would be performed.

Responses

200 application/json

Indicates a successful call
Hide response attributes Show response attributes object
- datafeedsAdded object
  
  If a saved object for an anomaly detection job is missing a datafeed identifier, it is added when you run the sync machine learning saved objects API.
  
  Hide datafeedsAdded attribute Show datafeedsAdded attribute object
  
  * object Additional properties
  
  The sync machine learning saved objects API response contains this object when there are datafeeds affected by the synchronization. There is an object for each relevant datafeed, which contains the synchronization status.
  
  Hide * attribute Show * attribute object
  
  success boolean
  
  The success or failure of the synchronization.
- datafeedsRemoved object
  
  If a saved object for an anomaly detection job references a datafeed that no longer exists, it is deleted when you run the sync machine learning saved objects API.
  
  Hide datafeedsRemoved attribute Show datafeedsRemoved attribute object
  
  * object Additional properties
  
  The sync machine learning saved objects API response contains this object when there are datafeeds affected by the synchronization. There is an object for each relevant datafeed, which contains the synchronization status.
  
  Hide * attribute Show * attribute object
  
  success boolean
  
  The success or failure of the synchronization.
- savedObjectsCreated object
  
  If saved objects are missing for machine learning jobs or trained models, they are created when you run the sync machine learning saved objects API.
  
  Hide savedObjectsCreated attributes Show savedObjectsCreated attributes object
  
  anomaly-detector object
  
  If saved objects are missing for anomaly detection jobs, they are created.
  
  Hide anomaly-detector attribute Show anomaly-detector attribute object
  
  * object Additional properties
  
  The sync machine learning saved objects API response contains this object when there are anomaly detection jobs affected by the synchronization. There is an object for each relevant job, which contains the synchronization status.
  
  Hide * attribute Show * attribute object
  
  success boolean
  
  The success or failure of the synchronization.
  
  data-frame-analytics object
  
  If saved objects are missing for data frame analytics jobs, they are created.
  
  Hide data-frame-analytics attribute Show data-frame-analytics attribute object
  
  * object Additional properties
  
  The sync machine learning saved objects API response contains this object when there are data frame analytics jobs affected by the synchronization. There is an object for each relevant job, which contains the synchronization status.
  
  Hide * attribute Show * attribute object
  
  success boolean
  
  The success or failure of the synchronization.
  
  trained-model object
  
  If saved objects are missing for trained models, they are created.
  
  Hide trained-model attribute Show trained-model attribute object
  
  * object Additional properties
  
  The sync machine learning saved objects API response contains this object when there are trained models affected by the synchronization. There is an object for each relevant trained model, which contains the synchronization status.
  
  Hide * attribute Show * attribute object
  
  success boolean
  
  The success or failure of the synchronization.
- savedObjectsDeleted object
  
  If saved objects exist for machine learning jobs or trained models that no longer exist, they are deleted when you run the sync machine learning saved objects API.
  
  Hide savedObjectsDeleted attributes Show savedObjectsDeleted attributes object
  
  anomaly-detector object
  
  If there are saved objects exist for nonexistent anomaly detection jobs, they are deleted.
  
  Hide anomaly-detector attribute Show anomaly-detector attribute object
  
  * object Additional properties
  
  The sync machine learning saved objects API response contains this object when there are anomaly detection jobs affected by the synchronization. There is an object for each relevant job, which contains the synchronization status.
  
  Hide * attribute Show * attribute object
  
  success boolean
  
  The success or failure of the synchronization.
  
  data-frame-analytics object
  
  If there are saved objects exist for nonexistent data frame analytics jobs, they are deleted.
  
  Hide data-frame-analytics attribute Show data-frame-analytics attribute object
  
  * object Additional properties
  
  The sync machine learning saved objects API response contains this object when there are data frame analytics jobs affected by the synchronization. There is an object for each relevant job, which contains the synchronization status.
  
  Hide * attribute Show * attribute object
  
  success boolean
  
  The success or failure of the synchronization.
  
  trained-model object
  
  If there are saved objects exist for nonexistent trained models, they are deleted.
  
  Hide trained-model attribute Show trained-model attribute object
  
  * object Additional properties
  
  The sync machine learning saved objects API response contains this object when there are trained models affected by the synchronization. There is an object for each relevant trained model, which contains the synchronization status.
  
  Hide * attribute Show * attribute object
  
  success boolean
  
  The success or failure of the synchronization.
401 application/json

Authorization information is missing or invalid.
Hide response attributes Show response attributes object
- error string
- message string
- statusCode integer

GET /api/ml/saved_objects/sync

curl \
 --request GET 'https://localhost:5601/api/ml/saved_objects/sync' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "datafeedsAdded": {},
  "datafeedsRemoved": {},
  "savedObjectsCreated": {
    "anomaly-detector": {
      "myjob1": {
        "success": true
      },
      "myjob2": {
        "success": true
      }
    }
  },
  "savedObjectsDeleted": {}
}

Response examples (401)

{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}

Get conversations

GET /api/security_ai_assistant/current_user/conversations/_find

Api key auth Basic auth

Get a list of all conversations for the current user.

Query parameters

fields array[string]
filter string

Search query
sort_field string

Field to sort by

Values are created_at, title, or updated_at.
sort_order string

Sort order

Values are asc or desc.
page integer

Page number

Minimum value is 1. Default value is 1.
per_page integer

Conversations per page

Minimum value is 0. Default value is 20.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- data array[object] Required
  
  Hide data attributes Show data attributes object
  
  apiConfig object
  
  LLM API configuration.
  
  Hide apiConfig attributes Show apiConfig attributes object
  
  actionTypeId string Required
  
  action type id
  
  connectorId string Required
  
  connector id
  
  defaultSystemPromptId string
  
  defaultSystemPromptId
  
  model string
  
  model
  
  provider string
  
  Provider
  
  Values are OpenAI, Azure OpenAI, or Other.
  
  category string Required
  
  The conversation category.
  
  Values are assistant or insights.
  
  createdAt string Required
  
  The time conversation was created.
  
  excludeFromLastConversationStorage boolean
  
  excludeFromLastConversationStorage.
  
  id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  messages array[object]
  
  The conversation messages.
  
  AI assistant conversation message.
  
  Hide messages attributes Show messages attributes object
  
  content string Required
  
  Message content.
  
  isError boolean
  
  Is error message.
  
  metadata object
  
  metadata
  
  Hide metadata attribute Show metadata attribute object
  
  contentReferences object
  
  Data refered to by the message content.
  
  reader object
  
  Message content.
  
  Additional properties are allowed.
  
  role string Required
  
  Message role.
  
  Values are system, user, or assistant.
  
  timestamp string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  traceData object
  
  trace Data
  
  Hide traceData attributes Show traceData attributes object
  
  traceId string
  
  Could be any string, not necessarily a UUID
  
  transactionId string
  
  Could be any string, not necessarily a UUID
  
  namespace string Required
  
  Kibana space
  
  replacements object
  
  Replacements object used to anonymize/deanomymize messsages
  
  Hide replacements attribute Show replacements attribute object
  
  * string Additional properties
  
  summary object
  
  Hide summary attributes Show summary attributes object
  
  confidence string
  
  How confident you are about this being a correct and useful learning.
  
  Values are low, medium, or high.
  
  content string
  
  Summary text of the conversation over time.
  
  public boolean
  
  Define if summary is marked as publicly available.
  
  timestamp string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  timestamp string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  title string Required
  
  The conversation title.
  
  updatedAt string
  
  The last time conversation was updated.
  
  users array[object] Required
  
  Could be any string, not necessarily a UUID
  
  Hide users attributes Show users attributes object
  
  id string
  
  User id
  
  name string
  
  User name
- page integer Required
- perPage integer Required
- total integer Required
400 application/json

Generic Error
Hide response attributes Show response attributes object
- error string
- message string
- statusCode number

GET /api/security_ai_assistant/current_user/conversations/_find

curl \
 --request GET 'https://localhost:5601/api/security_ai_assistant/current_user/conversations/_find' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "data": [
    {
      "apiConfig": {
        "actionTypeId": "string",
        "connectorId": "string",
        "defaultSystemPromptId": "string",
        "model": "string",
        "provider": "OpenAI"
      },
      "category": "assistant",
      "createdAt": "string",
      "excludeFromLastConversationStorage": true,
      "id": "string",
      "messages": [
        {
          "content": "string",
          "isError": true,
          "metadata": {
            "contentReferences": {}
          },
          "reader": {},
          "role": "system",
          "timestamp": "string",
          "traceData": {
            "traceId": "string",
            "transactionId": "string"
          }
        }
      ],
      "namespace": "string",
      "replacements": {
        "additionalProperty1": "string",
        "additionalProperty2": "string"
      },
      "summary": {
        "confidence": "low",
        "content": "string",
        "public": true,
        "timestamp": "string"
      },
      "timestamp": "string",
      "title": "string",
      "updatedAt": "string",
      "users": [
        {
          "id": "string",
          "name": "string"
        }
      ]
    }
  ],
  "page": 42,
  "perPage": 42,
  "total": 42
}

Response examples (400)

{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}

Get endpoint exception list items

GET /api/endpoint_list/items/_find

Api key auth Basic auth

Get a list of all endpoint exception list items.

Query parameters

filter string(nonempty)

Filters the returned results according to the value of the specified field, using the <field name>:<field value> syntax.

Minimum length is 1.
page integer

The page number to return

Minimum value is 0.
per_page integer

The number of exception list items to return per page

Minimum value is 0.
sort_field string(nonempty)

Determines which field is used to sort the results

Minimum length is 1.
sort_order string

Determines the sort order, which can be desc or asc

Values are desc or asc.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- data array[object] Required
  
  Hide data attributes Show data 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.
  
  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_any.
  
  value array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  list object Required
  
  Hide list attributes Show list attributes object
  
  id string(nonempty) Required
  
  Value list's identifier.
  
  Minimum length is 1.
  
  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.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Value is list.
  
  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 exists.
  
  Hide attributes Show attributes
  
  entries array[object] Required
  
  At least 1 element.
  
  One of:
  Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatch object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Endpoint_Exceptions_API_ExceptionListItemEntryExists 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
  
  Value is match.
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  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
  
  Value is match_any.
  
  value array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
  
  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
  
  Value is exists.
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  type string Required Discriminator
  
  Value is nested.
  
  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 wildcard.
  
  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.
- page integer Required
  
  Minimum value is 0.
- per_page integer Required
  
  Minimum value is 0.
- pit string
- total integer Required
  
  Minimum value is 0.
400 application/json

Invalid input data
One of:
Security_Endpoint_Exceptions_API_PlatformErrorResponse object Security_Endpoint_Exceptions_API_SiemErrorResponse object
Hide attributes Show attributes

error string Required

message string Required

statusCode integer Required
Hide attributes Show attributes

message string Required

status_code integer Required
401 application/json

Unsuccessful authentication
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
403 application/json

Insufficient privileges
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
404 application/json

Endpoint list not found
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required
500 application/json

Internal server error
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required

GET /api/endpoint_list/items/_find

curl \
 --request GET 'https://localhost:5601/api/endpoint_list/items/_find' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "data": [
    {
      "_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"
    }
  ],
  "page": 42,
  "per_page": 42,
  "pit": "string",
  "total": 42
}

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
}

Suspend a process

POST /api/endpoint/action/suspend_process

Api key auth Basic auth

Suspend a running process on an endpoint.

application/json

Body Required

agent_type string

List of agent types to retrieve. Defaults to endpoint.

Values are endpoint, sentinel_one, crowdstrike, or microsoft_defender_endpoint.
alert_ids array[string(nonempty)]

A list of alerts ids.

At least 1 element. Minimum length of each is 1.
case_ids array[string]

Case IDs to be updated (cannot contain empty strings)

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

Optional comment
endpoint_ids array[string] Required

List of endpoint IDs (cannot contain empty strings)

At least 1 element. Minimum length of each is 1.
parameters object Required

Optional parameters object

Responses

200 application/json

OK

POST /api/endpoint/action/suspend_process

curl \
 --request POST 'https://localhost:5601/api/endpoint/action/suspend_process' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"comment":"suspend the process","parameters":{"entity_id":"abc123"},"endpoint_ids":["ed518850-681a-4d60-bb98-e22640cae2a8"]}'

Request example

{
  "comment": "suspend the process",
  "parameters": {
    "entity_id": "abc123"
  },
  "endpoint_ids": [
    "ed518850-681a-4d60-bb98-e22640cae2a8"
  ]
}

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
  }
}

Initialize an Entity Engine

POST /api/entity_store/engines/{entityType}/init

Api key auth Basic auth

Path parameters

entityType string Required

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

Values are user, host, or service.

application/json

Body Required

Schema for the engine initialization

delay string

The delay before the transform will run.

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

The number of documents per second to process.
enrichPolicyExecutionInterval string

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

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

The number of historical values to keep for each field.

Default value is 10.
filter string
frequency string

The frequency at which the transform will run.

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

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

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

The timeout for initializing the aggregating transform.

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

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

Default value is @timestamp.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- delay string
  
  Format should match the following pattern: [smdh]$. Default value is 1m.
- docsPerSecond integer
- error object
- fieldHistoryLength integer Required
- filter string
- frequency string
  
  Format should match the following pattern: [smdh]$. Default value is 1m.
- indexPattern string Required
- lookbackPeriod string
  
  Format should match the following pattern: [smdh]$. Default value is 24h.
- status string Required
  
  Values are installing, started, stopped, updating, or error.
- timeout string
  
  Format should match the following pattern: [smdh]$. Default value is 180s.
- timestampField string
- type string Required
  
  Values are user, host, or service.
400

Invalid request

POST /api/entity_store/engines/{entityType}/init

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

Request examples

{
  "delay": "1m",
  "docsPerSecond": 42,
  "enrichPolicyExecutionInterval": "1h",
  "fieldHistoryLength": 10,
  "filter": "string",
  "frequency": "1m",
  "indexPattern": "string",
  "lookbackPeriod": "24h",
  "timeout": "180s",
  "timestampField": "@timestamp"
}

Response examples (200)

{
  "delay": "1m",
  "docsPerSecond": 42,
  "error": {},
  "fieldHistoryLength": 42,
  "filter": "string",
  "frequency": "1m",
  "indexPattern": "string",
  "lookbackPeriod": "24h",
  "status": "installing",
  "timeout": "180s",
  "timestampField": "string",
  "type": "user"
}

Start an Entity Engine

POST /api/entity_store/engines/{entityType}/start

Api key auth Basic auth

Path parameters

entityType string Required

The entity type of the engine

Values are user, host, or service.

Responses

200 application/json

Successful response
Hide response attribute Show response attribute object
- started boolean

POST /api/entity_store/engines/{entityType}/start

curl \
 --request POST 'https://localhost:5601/api/entity_store/engines/{entityType}/start' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "started": true
}

Stop an Entity Engine

POST /api/entity_store/engines/{entityType}/stop

Api key auth Basic auth

Path parameters

entityType string Required

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

Values are user, host, or service.

Responses

200 application/json

Successful response
Hide response attribute Show response attribute object
- stopped boolean

POST /api/entity_store/engines/{entityType}/stop

curl \
 --request POST 'https://localhost:5601/api/entity_store/engines/{entityType}/stop' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "stopped": true
}

Configure the Risk Engine Saved Object

PATCH /api/risk_score/engine/saved_object/configure

Api key auth Basic auth

Configuring the Risk Engine Saved Object

application/json

Body Required

exclude_alert_statuses array[string]
exclude_alert_tags array[string]
range object
Hide range attributes Show range attributes object
- end string
- start string

Responses

200 application/json

Successful response
Hide response attribute Show response attribute object
- risk_engine_saved_object_configured boolean
400 application/json

Task manager is unavailable
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required
  
  Minimum value is 400.
default application/json

Unexpected error
Hide response attributes Show response attributes object
- errors array[object] Required
  
  Hide errors attributes Show errors attributes object
  
  error string Required
  
  seq integer Required
- risk_engine_saved_object_configured boolean Required

PATCH /api/risk_score/engine/saved_object/configure

curl \
 --request PATCH 'https://localhost:5601/api/risk_score/engine/saved_object/configure' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"exclude_alert_statuses":["string"],"exclude_alert_tags":["string"],"range":{"end":"string","start":"string"}}'

Request examples

{
  "exclude_alert_statuses": [
    "string"
  ],
  "exclude_alert_tags": [
    "string"
  ],
  "range": {
    "end": "string",
    "start": "string"
  }
}

Response examples (200)

{
  "risk_engine_saved_object_configured": true
}

Response examples (400)

{
  "message": "string",
  "status_code": 42
}

Response examples (default)

{
  "errors": [
    {
      "error": "string",
      "seq": 42
    }
  ],
  "risk_engine_saved_object_configured": 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.

Delete a value list

DELETE /api/lists

Api key auth Basic auth

Delete a value list using the list ID.

When you delete a list, all of its list items are also deleted.

Query parameters

id string(nonempty) Required

Value list's identifier.

Minimum length is 1.
deleteReferences boolean

Determines whether exception items referencing this value list should be deleted.

Default value is false.
ignoreReferences boolean

Determines whether to delete value list without performing any additional checks of where this list may be utilized.

Default value is false.

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

error string Required

message string Required

statusCode integer Required
Hide attributes Show attributes

message string Required

status_code integer Required
401 application/json

Unsuccessful authentication response
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
403 application/json

Not enough privileges response
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
404 application/json

List not found response
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required
500 application/json

Internal server error response
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required

DELETE /api/lists

curl \
 --request DELETE 'https://localhost:5601/api/lists?id=21b01cfb-058d-44b9-838c-282be16c91cd' \
 --header "Authorization: $API_KEY"

Response examples (200)

{
  "id": "21b01cfb-058d-44b9-838c-282be16c91cd",
  "name": "Bad ips",
  "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": "List of bad internet ips.",
  "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 [DELETE /api/lists?id=ip_list] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}

Response examples (404)

{
  "message": "list id: \\\"ip_list\\\" was not found",
  "status_code": 404
}

Response examples (500)

{
  "message": "Internal Server Error",
  "status_code": 500
}

Delete a note

DELETE /api/note

Api key auth Basic auth

Delete a note from a Timeline using the note ID.

application/json

Body object | null Required

The ID of the note to delete.

noteId string Required

Responses

200

Indicates the note was successfully deleted.

DELETE /api/note

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

Request examples

{
  "noteId": "string"
}

{
  "noteIds": [
    "string"
  ]
}

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
- body string
  
  The error message
- statusCode number
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
- body string
  
  The error message
- statusCode number
409 application/json

Indicates the import of Timelines was unsuccessful.
Hide response attributes Show response attributes object
- body string
  
  The error message
- statusCode number

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"}'

Request examples

{
  "isImmutable": "true"
}

Response examples (200)

{
  "errors": [
    {
      "error": {
        "message": "Malformed JSON",
        "status_code": 400
      },
      "id": "6ce1b592-84e3-4b4a-9552-f189d4b82075"
    }
  ],
  "success": true,
  "success_count": 99,
  "timelines_installed": 80,
  "timelines_updated": 19
}

Response examples (400)

{
  "body": "Invalid file extension",
  "statusCode": 400
}

Response examples (404)

{
  "body": "Unable to find saved object client",
  "statusCode": 404
}

Response examples (409)

{
  "body": "Could not import timelines",
  "statusCode": 409
}

Resync streams Technical Preview

POST /api/streams/_resync

Api key auth Basic auth

Resyncs all streams, making sure that Elasticsearch assets are up to date

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

object

Additional properties are NOT allowed.

POST /api/streams/_resync

curl \
 --request POST 'https://localhost:5601/api/streams/_resync' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true"

Request examples

# Headers
kbn-xsrf: true

# Payload
{}

Get group stream settings Technical Preview

GET /api/streams/{name}/_group

Api key auth Basic auth

Fetches the group settings of a group stream definition

Path parameters

name string Required

application/json

Body

object

Additional properties are NOT allowed.

GET /api/streams/{name}/_group

curl \
 --request GET 'https://localhost:5601/api/streams/{name}/_group' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json"

Request examples

{}

Invalidate user sessions Technical Preview

POST /api/security/session/_invalidate

Api key auth Basic auth

Invalidate user sessions that match a query. To use this API, you must be a superuser.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

match string Required

The method Kibana uses to determine which sessions to invalidate. If it is all, all existing sessions will be invalidated. If it is query, only the sessions that match the query will be invalidated.

Values are all or query.
query object

The query that Kibana uses to match the sessions to invalidate when the match parameter is set to query.
Hide query attributes Show query attributes object
- provider object Required
  
  The authentication providers that will have their user sessions invalidated.
  Hide provider attributes Show provider attributes object
  
  name string
  
  The authentication provider name.
  
  type string Required
  
  The authentication provide type. For example: basic, token, saml, oidc, kerberos, or pki.
- username string
  
  The username that will have its sessions invalidated.

Responses

200 application/json

Indicates a successful call
Hide response attribute Show response attribute object
- total integer
  
  The number of sessions that were successfully invalidated.
403

Indicates that the user may not be authorized to invalidate sessions for other users.

POST /api/security/session/_invalidate

curl \
 --request POST 'https://localhost:5601/api/security/session/_invalidate' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '"{\n  \"match\" : \"all\"\n}"'

Request examples

Run `POST api/security/session/_invalidate` to invalidate all existing sessions.

{
  "match" : "all"
}

Run `POST api/security/session/_invalidate` to invalidate sessions that were created by any SAML authentication provider.

{
  "match" : "query",
  "query": {
    "provider" : { "type": "saml" }
  }
}

Run `POST api/security/session/_invalidate` to invalidate sessions that were created by the SAML authentication provider named `saml1`.

{
  "match" : "query",
  "query": {
    "provider" : { "type": "saml", "name": "saml1" }
  }
}

Run `POST api/security/session/_invalidate` to invalidate sessions that were created by any OpenID Connect authentication provider for the user with the username `user@my-oidc-sso.com`.

{
  "match" : "query",
  "query": {
    "provider" : { "type": "oidc" },
    "username": "user@my-oidc-sso.com"
  }
}

Response examples (200)

{
  "total": 42
}

connector object Required

value string | null | boolean

Get cases for an alert Technical preview

Delete a dashboard Technical Preview

es_key object | string

key object | string

es_key object | string

key object | string

es_key object | string

key object | string

Body Required

Body Required

Body Required

Body object | null Required

Body Required

Resync streams Technical Preview

Get group stream settings Technical Preview

Invalidate user sessions Technical Preview