Kibana APIs
1.0.2

Base URL 
https://localhost:5601

The Kibana REST APIs enable you to manage resources such as connectors, data views, and saved objects. The API calls are stateless. Each request that you make happens in isolation from other calls and must include all of the necessary information for Kibana to fulfill the request. API requests return JSON output, which is a format that is machine-readable and works well for automation.

To interact with Kibana APIs, use the following operations:

  • GET: Fetches the information.
  • PATCH: Applies partial modifications to the existing information.
  • POST: Adds new information.
  • PUT: Updates the existing information.
  • DELETE: Removes the information.

You can prepend any Kibana API endpoint with kbn: and run the request in Dev Tools → Console. For example:

GET kbn:/api/data_views

For more information about the console, refer to Run API requests.

NOTE: Access to internal Kibana API endpoints will be restricted in Kibana version 9.0. Please move any integrations to publicly documented APIs.

Documentation source and versions

This documentation is derived from the 8.18 branch of the kibana repository. It is provided under license Attribution-NonCommercial-NoDerivatives 4.0 International.

This is version 1.0.2 of this API documentation. Last update on May 9, 2025.

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.

Delete a rule

DELETE /api/alerting/rule/{id}
Api key auth Basic auth

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    The identifier for the rule.

Responses

  • 204

    Indicates a successful call.

  • 400

    Indicates an invalid schema or parameters.

  • 403

    Indicates that this call is forbidden.

  • 404

    Indicates a rule with the given ID does not exist.

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

Mute all alerts

POST /api/alerting/rule/{id}/_mute_all
Api key auth Basic auth

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    The identifier for the rule.

Responses

  • 204

    Indicates a successful call.

  • 400

    Indicates an invalid schema or parameters.

  • 403

    Indicates that this call is forbidden.

  • 404

    Indicates a rule with the given ID does not exist.

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

Unmute all alerts

POST /api/alerting/rule/{id}/_unmute_all
Api key auth Basic auth

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    The identifier for the rule.

Responses

  • 204

    Indicates a successful call.

  • 400

    Indicates an invalid schema or parameters.

  • 403

    Indicates that this call is forbidden.

  • 404

    Indicates a rule with the given ID does not exist.

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

Update an alert Deprecated

PUT /api/alerts/alert/{alertId}
Api key auth Basic auth

Deprecated in 7.13.0. Use the update rule API instead.

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

Path parameters

  • alertId string Required

    The identifier for the alert.

application/json

Body Required

  • actions array[object]
    Hide actions attributes Show actions attributes object
    • actionTypeId string Required

      The identifier for the action type.

    • group string Required

      Grouping actions is recommended for escalations for different types of alert instances. If you don't need this functionality, set it to default.

    • id string Required

      The ID of the action saved object.

    • params object Required

      The map to the params that the action type will receive. params are handled as Mustache templates and passed a default set of context.

  • name string Required

    A name to reference and search.

  • notifyWhen string Required

    The condition for throttling the notification.

    Values are onActionGroupChange, onActiveAlert, or onThrottleInterval.

  • params object Required

    The parameters to pass to the alert type executor params value. This will also validate against the alert type params validator, if defined.

  • schedule object Required

    The schedule specifying when this alert should be run. A schedule is structured such that the key specifies the format you wish to use and its value specifies the schedule.

    Hide schedule attribute Show schedule attribute object
    • interval string

      The interval format specifies the interval in seconds, minutes, hours or days at which the alert should run.

  • tags array[string]

    A list of keywords to reference and search.

  • throttle string

    How often this alert should fire the same actions. This will prevent the alert from sending out the same notification over and over. For example, if an alert with a schedule of 1 minute stays in a triggered state for 90 minutes, setting a throttle of 10m or 1h will prevent it from sending 90 notifications during this period.

Responses

PUT /api/alerts/alert/{alertId} 
curl \
 --request PUT 'https://localhost:5601/api/alerts/alert/41893910-6bca-11eb-9e0d-85d233e3ee35' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"actions":[{"actionTypeId":"string","group":"string","id":"string","params":{}}],"name":"string","notifyWhen":"onActionGroupChange","params":{},"schedule":{"interval":"1d"},"tags":["string"],"throttle":"string"}'

Disable an alert Deprecated

POST /api/alerts/alert/{alertId}/_disable
Api key auth Basic auth

Deprecated in 7.13.0. Use the disable rule API instead.

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

Path parameters

  • alertId string Required

    The identifier for the alert.

Responses

  • 204

    Indicates a successful call.

  • 401 application/json

    Authorization information is missing or invalid.

    Hide response attributes Show response attributes object
POST /api/alerts/alert/{alertId}/_disable 
curl \
 --request POST 'https://localhost:5601/api/alerts/alert/41893910-6bca-11eb-9e0d-85d233e3ee35/_disable' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: string"

Mute an alert instance Deprecated

POST /api/alerts/alert/{alertId}/alert_instance/{alertInstanceId}/_mute
Api key auth Basic auth

Deprecated in 7.13.0. Use the mute alert API instead.

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

Path parameters

Responses

  • 204

    Indicates a successful call.

  • 401 application/json

    Authorization information is missing or invalid.

    Hide response attributes Show response attributes object
POST /api/alerts/alert/{alertId}/alert_instance/{alertInstanceId}/_mute 
curl \
 --request POST 'https://localhost:5601/api/alerts/alert/41893910-6bca-11eb-9e0d-85d233e3ee35/alert_instance/dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2/_mute' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: string"

Unmute an alert instance Deprecated

POST /api/alerts/alert/{alertId}/alert_instance/{alertInstanceId}/_unmute
Api key auth Basic auth

Deprecated in 7.13.0. Use the unmute alert API instead.

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

Path parameters

Responses

  • 204

    Indicates a successful call.

  • 401 application/json

    Authorization information is missing or invalid.

    Hide response attributes Show response attributes object
POST /api/alerts/alert/{alertId}/alert_instance/{alertInstanceId}/_unmute 
curl \
 --request POST 'https://localhost:5601/api/alerts/alert/41893910-6bca-11eb-9e0d-85d233e3ee35/alert_instance/dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2/_unmute' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: string"

Get the alerting framework health Deprecated

GET /api/alerts/alerts/_health
Api key auth Basic auth

Deprecated in 7.13.0. Use the get alerting framework health API instead.

Responses

  • 200 application/json

    Indicates a successful call.

    Hide response attributes Show response attributes object
    • alertingFrameworkHealth object

      Three substates identify the health of the alerting framework: decryptionHealth, executionHealth, and readHealth.

      Hide alertingFrameworkHealth attributes Show alertingFrameworkHealth attributes object
      • decryptionHealth object

        The timestamp and status of the alert decryption.

        Hide decryptionHealth attributes Show decryptionHealth attributes object
      • executionHealth object

        The timestamp and status of the alert execution.

        Hide executionHealth attributes Show executionHealth attributes object
      • readHealth object

        The timestamp and status of the alert reading events.

        Hide readHealth attributes Show readHealth attributes object
    • hasPermanentEncryptionKey boolean

      If false, the encrypted saved object plugin does not have a permanent encryption key.

    • isSufficientlySecure boolean

      If false, security is enabled but TLS is not.
  • 401 application/json

    Authorization information is missing or invalid.

    Hide response attributes Show response attributes object
GET /api/alerts/alerts/_health 
curl \
 --request GET 'https://localhost:5601/api/alerts/alerts/_health' \
 --header "Authorization: $API_KEY"

APM agent configuration

Adjust APM agent configuration without need to redeploy your application.

Upload source map

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

Upload a source map for a specific service and version.

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

multipart/form-data

Body Required

Responses

POST /api/apm/sourcemaps 
curl \
 --request POST 'https://localhost:5601/api/apm/sourcemaps' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: multipart/form-data" \
 --header "elastic-api-version: 2023-10-31" \
 --header "kbn-xsrf: true" \
 --form "bundle_filepath=string" \
 --form "service_name=string" \
 --form "service_version=string" \
 --form "sourcemap=@file"

Create a case

POST /api/cases
Api key auth Basic auth

You must 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 creating.

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

application/json

Body Required

  • 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

    A word or phrase that categorizes the case.

    Maximum length is 50.

  • 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

      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.

  • customFields array[object]

    Custom field values for a case. Any optional custom fields that are not specified in the request are set to null.

    At least 0 but not more than 10 elements.

    Hide customFields attributes Show customFields attributes object
    • key string Required

      The unique identifier for the custom field. The key value must exist in the case configuration settings.

    • type string Required

      The custom field type. It must match the type specified in the case configuration settings.

      Values are text or toggle.

    • value string | null | boolean Required

      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

    The description for the case.

    Maximum length is 30000.

  • 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

    The severity of the case.

    Values are critical, high, low, or medium. Default value is low.

  • tags array[string] Required

    The words and phrases that help categorize cases. It can be an empty array.

    Not more than 200 elements. Maximum length of each is 256.

  • title string Required

    A title for the case.

    Maximum length is 160.

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

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

    • created_at string(date-time) Required
    • created_by object Required
      Hide created_by attributes Show created_by attributes object
    • 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
    • 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
    • version string Required
  • 401 application/json

    Authorization information is missing or invalid.

    Hide response attributes Show response attributes object
POST /api/cases 
curl \
 --request POST 'https://localhost:5601/api/cases' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"tags":["tag-1"],"owner":"cases","title":"Case title 1","settings":{"syncAlerts":true},"connector":{"id":"131d4448-abe0-4789-939d-8ef60680b498","name":"My connector","type":".jira","fields":{"parent":null,"priority":"High","issueType":"10006"}},"description":"A case description.","customFields":[{"key":"d312efda-ec2b-42ec-9e2c-84981795c581","type":"text","value":"My field value"}]}'
Request example 
{
  "tags": [
    "tag-1"
  ],
  "owner": "cases",
  "title": "Case title 1",
  "settings": {
    "syncAlerts": true
  },
  "connector": {
    "id": "131d4448-abe0-4789-939d-8ef60680b498",
    "name": "My connector",
    "type": ".jira",
    "fields": {
      "parent": null,
      "priority": "High",
      "issueType": "10006"
    }
  },
  "description": "A case description.",
  "customFields": [
    {
      "key": "d312efda-ec2b-42ec-9e2c-84981795c581",
      "type": "text",
      "value": "My field value"
    }
  ]
}
Response examples (200) 
{
  "id": "66b9aa00-94fa-11ea-9f74-e7e108796192",
  "tags": [
    "tag 1"
  ],
  "owner": "cases",
  "title": "Case title 1",
  "status": "open",
  "version": "WzUzMiwxXQ==",
  "comments": [],
  "duration": null,
  "settings": {
    "syncAlerts": true
  },
  "severity": "low",
  "assignees": [],
  "closed_at": null,
  "closed_by": null,
  "connector": {
    "id": "131d4448-abe0-4789-939d-8ef60680b498",
    "name": "My connector",
    "type": ".jira",
    "fields": {
      "parent": null,
      "priority": "High",
      "issueType": "10006"
    }
  },
  "created_at": "2022-10-13T15:33:50.604Z",
  "created_by": {
    "email": null,
    "username": "elastic",
    "full_name": null,
    "profile_uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
  },
  "updated_at": null,
  "updated_by": null,
  "description": "A case description.",
  "totalAlerts": 0,
  "customFields": [
    {
      "key": "d312efda-ec2b-42ec-9e2c-84981795c581",
      "type": "text",
      "value": "My field value"
    },
    {
      "key": "fcc6840d-eb14-42df-8aaf-232201a705ec",
      "type": "toggle",
      "value": null
    }
  ],
  "totalComment": 0,
  "external_service": null
}

Delete cases

DELETE /api/cases
Api key auth Basic auth

You must have read or all privileges and the delete sub-feature privilege 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 deleting.

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

Query parameters

  • ids array[string] Required

    The cases that you want to removed. All non-ASCII characters must be URL encoded.

Responses

  • 204

    Indicates a successful call.

  • 401 application/json

    Authorization information is missing or invalid.

    Hide response attributes Show response attributes object
DELETE /api/cases 
curl \
 --request DELETE 'https://localhost:5601/api/cases?ids=d4e7abb0-b462-11ec-9a8d-698504725a43' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: string"

Update cases

PATCH /api/cases
Api key auth Basic auth

You must 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 updating.

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

application/json

Body

  • cases array[object] Required

    An array containing one or more case objects.

    At least 1 but not more than 100 elements.

    Hide cases attributes Show cases 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

      A word or phrase that categorizes the case.

      Maximum length is 50.

    • connector object

      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

        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.

    • customFields array[object]

      Custom field values for a case. Any optional custom fields that are not specified in the request are set to null.

      At least 0 but not more than 10 elements.

      Hide customFields attributes Show customFields attributes object
      • key string Required

        The unique identifier for the custom field. The key value must exist in the case configuration settings.

      • type string Required

        The custom field type. It must match the type specified in the case configuration settings.

        Values are text or toggle.

      • value string | null | boolean Required

        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

      The description for the case.

      Maximum length is 30000.

    • id string Required

      The identifier for the case.

      Maximum length is 30000.

    • settings object

      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

      The severity of the case.

      Values are critical, high, low, or medium. Default value is low.

    • status string

      The status of the case.

      Values are closed, in-progress, or open.

    • tags array[string]

      The words and phrases that help categorize cases. It can be an empty array.

      Not more than 200 elements. Maximum length of each is 256.

    • title string

      A title for the case.

      Maximum length is 160.

    • version string Required

      The current version of the case. To determine this value, use the get case or find cases APIs.

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

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

    • created_at string(date-time) Required
    • created_by object Required
      Hide created_by attributes Show created_by attributes object
    • 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
    • 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
    • version string Required
  • 401 application/json

    Authorization information is missing or invalid.

    Hide response attributes Show response attributes object
PATCH /api/cases 
curl \
 --request PATCH 'https://localhost:5601/api/cases' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"cases":[{"id":"a18b38a0-71b0-11ea-a0b2-c51ea50a58e2","tags":["tag-1"],"version":"WzIzLDFd","settings":{"syncAlerts":true},"connector":{"id":"131d4448-abe0-4789-939d-8ef60680b498","name":"My connector","type":".jira","fields":{"parent":null,"priority":null,"issueType":"10006"}},"description":"A case description.","customFields":[{"key":"fcc6840d-eb14-42df-8aaf-232201a705ec","type":"toggle","value":false},{"key":"d312efda-ec2b-42ec-9e2c-84981795c581","type":"text","value":"My new field value"}]}]}'
Request example 
{
  "cases": [
    {
      "id": "a18b38a0-71b0-11ea-a0b2-c51ea50a58e2",
      "tags": [
        "tag-1"
      ],
      "version": "WzIzLDFd",
      "settings": {
        "syncAlerts": true
      },
      "connector": {
        "id": "131d4448-abe0-4789-939d-8ef60680b498",
        "name": "My connector",
        "type": ".jira",
        "fields": {
          "parent": null,
          "priority": null,
          "issueType": "10006"
        }
      },
      "description": "A case description.",
      "customFields": [
        {
          "key": "fcc6840d-eb14-42df-8aaf-232201a705ec",
          "type": "toggle",
          "value": false
        },
        {
          "key": "d312efda-ec2b-42ec-9e2c-84981795c581",
          "type": "text",
          "value": "My new field value"
        }
      ]
    }
  ]
}
Response examples (200) 
[
  {
    "id": "66b9aa00-94fa-11ea-9f74-e7e108796192",
    "tags": [
      "tag-1"
    ],
    "owner": "cases",
    "title": "Case title 1",
    "status": "open",
    "version": "WzU0OCwxXQ==",
    "category": null,
    "comments": [],
    "duration": null,
    "settings": {
      "syncAlerts": true
    },
    "severity": "low",
    "assignees": [],
    "closed_at": null,
    "closed_by": null,
    "connector": {
      "id": "131d4448-abe0-4789-939d-8ef60680b498",
      "name": "My connector",
      "type": ".jira",
      "fields": {
        "parent": null,
        "priority": null,
        "issueType": "10006"
      }
    },
    "created_at": "2023-10-13T09:16:17.416Z",
    "created_by": {
      "email": null,
      "username": "elastic",
      "full_name": null,
      "profile_uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
    },
    "updated_at": "2023-10-13T09:48:33.043Z",
    "updated_by": {
      "email": null,
      "username": "elastic",
      "full_name": null,
      "profile_uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
    },
    "description": "A case description.",
    "totalAlerts": 0,
    "customFields": [
      {
        "key": "d312efda-ec2b-42ec-9e2c-84981795c581",
        "type": "text",
        "value": "My new field value"
      },
      {
        "key": "fcc6840d-eb14-42df-8aaf-232201a705ec",
        "type": "toggle",
        "value": false
      }
    ],
    "totalComment": 0,
    "external_service": {
      "pushed_at": "2023-10-13T09:20:40.672Z",
      "pushed_by": {
        "email": null,
        "username": "elastic",
        "full_name": null
      },
      "external_id": "10003",
      "connector_id": "05da469f-1fde-4058-99a3-91e4807e2de8",
      "external_url": "https://hms.atlassian.net/browse/IS-4",
      "connector_name": "Jira",
      "external_title": "IS-4"
    }
  }
]

Search cases

GET /api/cases/_find
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.

Query parameters

  • assignees string | array[string]

    Filters the returned cases by assignees. Valid values are none or unique identifiers for the user profiles. These identifiers can be found by using the suggest user profile API.

  • category string | array[string]

    Filters the returned cases by category.

  • defaultSearchOperator string

    he default operator to use for the simple_query_string.

    Default value is OR.

  • from string

    Returns only cases that were created after a specific date. The date must be specified as a KQL data range or date match expression.

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

  • page integer

    The page number to return.

    Default value is 1.

  • perPage integer

    The number of items to return. Limited to 100 items.

    Maximum value is 100. Default value is 20.

  • reporters string | array[string]

    Filters the returned cases by the user name of the reporter.

  • searchFields string | array[string]

    The fields to perform the simple_query_string parsed query against.

  • severity string

    The severity of the case.

    Values are critical, high, low, or medium.

  • sortField string

    Determines which field is used to sort the results.

    Values are createdAt, updatedAt, closedAt, title, category, status, or severity. Default value is createdAt.

  • sortOrder string

    Determines the sort order.

    Values are asc or desc. Default value is desc.

  • status string

    Filters the returned cases by state.

    Values are closed, in-progress, or open.

  • tags string | array[string]

    Filters the returned cases by tags.

  • to string

    Returns only cases that were created before a specific date. The date must be specified as a KQL data range or date match expression.

Responses

  • 200 application/json

    Indicates a successful call.

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

      Not more than 10000 elements.

      Hide cases attributes Show cases 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
      • 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

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

      • created_at string(date-time) Required
      • created_by object Required
        Hide created_by attributes Show created_by attributes object
      • 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
      • 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
      • version string Required
    • count_closed_cases integer
    • count_in_progress_cases integer
    • count_open_cases integer
    • page integer
    • per_page integer
    • total integer
  • 401 application/json

    Authorization information is missing or invalid.

    Hide response attributes Show response attributes object
GET /api/cases/_find 
curl \
 --request GET 'https://localhost:5601/api/cases/_find' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "page": 1,
  "cases": [
    {
      "id": "abed3a70-71bd-11ea-a0b2-c51ea50a58e2",
      "tags": [
        "tag-1"
      ],
      "owner": "cases",
      "title": "Case title",
      "status": "open",
      "version": "WzExMCwxXQ==",
      "category": null,
      "comments": [],
      "duration": null,
      "settings": {
        "syncAlerts": true
      },
      "severity": "low",
      "assignees": [],
      "closed_at": null,
      "closed_by": null,
      "connector": {
        "id": "none",
        "name": "none",
        "type": ".none",
        "fields": null
      },
      "created_at": "2023-10-12T00:16:36.371Z",
      "created_by": {
        "email": null,
        "username": "elastic",
        "full_name": null,
        "profile_uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
      },
      "updated_at": "2023-10-12T00:27:58.162Z",
      "updated_by": {
        "email": null,
        "username": "elastic",
        "full_name": null,
        "profile_uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
      },
      "description": "Case description",
      "totalAlerts": 0,
      "customFields": [
        {
          "key": "d312efda-ec2b-42ec-9e2c-84981795c581",
          "type": "text",
          "value": "My field value"
        },
        {
          "key": "fcc6840d-eb14-42df-8aaf-232201a705ec",
          "type": "toggle",
          "value": null
        }
      ],
      "totalComment": 1,
      "external_service": null
    }
  ],
  "total": 1,
  "per_page": 5,
  "count_open_cases": 1,
  "count_closed_cases": 0,
  "count_in_progress_cases": 0
}

Get case information

GET /api/cases/{caseId}
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 case you're seeking.

Path parameters

  • caseId string Required

    The identifier for the case. To retrieve case IDs, use the find cases API. All non-ASCII characters must be URL encoded.

Query parameters

  • includeComments boolean Deprecated

    Deprecated in 8.1.0. This parameter is deprecated and will be removed in a future release. It determines whether case comments are returned.

    Default value is true.

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

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

    • created_at string(date-time) Required
    • created_by object Required
      Hide created_by attributes Show created_by attributes object
    • 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
    • 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
    • version string Required
  • 401 application/json

    Authorization information is missing or invalid.

    Hide response attributes Show response attributes object
GET /api/cases/{caseId} 
curl \
 --request GET 'https://localhost:5601/api/cases/9c235210-6834-11ea-a78c-6ffb38a34414' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "id": "31cdada0-02c1-11ed-85f2-4f7c222ca2fa",
  "tags": [
    "tag 1"
  ],
  "owner": "cases",
  "title": "Case title 1",
  "status": "open",
  "version": "WzM2LDFd",
  "category": null,
  "comments": [
    {
      "id": "2134c1d0-02c2-11ed-85f2-4f7c222ca2fa",
      "type": "user",
      "owner": "cases",
      "comment": "A new comment",
      "version": "WzM3LDFd",
      "pushed_at": null,
      "pushed_by": null,
      "created_at": "2023-10-13T15:40:32.335Z",
      "created_by": {
        "email": null,
        "username": "elastic",
        "full_name": null,
        "profile_uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
      },
      "updated_at": null,
      "updated_by": null
    }
  ],
  "duration": null,
  "settings": {
    "syncAlerts": true
  },
  "severity": "low",
  "assignees": [
    {
      "uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
    }
  ],
  "closed_at": null,
  "closed_by": null,
  "connector": {
    "id": "none",
    "name": "none",
    "type": ".none",
    "fields": null
  },
  "created_at": "2023-10-13T15:33:50.604Z",
  "created_by": {
    "email": null,
    "username": "elastic",
    "full_name": null,
    "profile_uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
  },
  "updated_at": "2023-10-13T15:40:32.335Z",
  "updated_by": {
    "email": null,
    "username": "elastic",
    "full_name": null,
    "profile_uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
  },
  "description": "A case description",
  "totalAlerts": 0,
  "customFields": [
    {
      "key": "d312efda-ec2b-42ec-9e2c-84981795c581",
      "type": "text",
      "value": "My field value"
    },
    {
      "key": "fcc6840d-eb14-42df-8aaf-232201a705ec",
      "type": "toggle",
      "value": null
    }
  ],
  "totalComment": 1,
  "external_service": null
}
{
  "id": "c3ff7550-def1-4e90-b6bc-c9969a4a09b1",
  "tags": [
    "observability",
    "tag 1"
  ],
  "owner": "observability",
  "title": "Observability case title 1",
  "status": "in-progress",
  "version": "WzI0NywyXQ==",
  "category": null,
  "comments": [
    {
      "id": "59d438d0-79a9-4864-8d4b-e63adacebf6e",
      "rule": {
        "id": "03e4eb87-62ca-4e5d-9570-3d7625e9669d",
        "name": "Observability rule"
      },
      "type": "alert",
      "index": [
        ".internal.alerts-observability.logs.alerts-default-000001"
      ],
      "owner": "observability",
      "alertId": [
        "a6e12ac4-7bce-457b-84f6-d7ce8deb8446"
      ],
      "version": "WzY3LDJd",
      "pushed_at": null,
      "pushed_by": null,
      "created_at": "2023-11-06T19:29:38.424Z",
      "created_by": {
        "email": null,
        "username": "elastic",
        "full_name": null,
        "profile_uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
      },
      "updated_at": null,
      "updated_by": null
    },
    {
      "id": "d99342d3-3aa3-4b80-90ec-a702607604f5",
      "type": "user",
      "owner": "observability",
      "comment": "The first comment.",
      "version": "WzcyLDJd",
      "pushed_at": null,
      "pushed_by": null,
      "created_at": "2023-11-06T19:29:57.812Z",
      "created_by": {
        "email": null,
        "username": "elastic",
        "full_name": null,
        "profile_uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
      },
      "updated_at": null,
      "updated_by": null
    }
  ],
  "duration": null,
  "settings": {
    "syncAlerts": false
  },
  "severity": "low",
  "assignees": [
    {
      "uid": "u_0wpfV1MqYDaXzLtRVY-gLMrddKDEmfz51Fszhj7hWC8_0"
    }
  ],
  "closed_at": null,
  "closed_by": null,
  "connector": {
    "id": "none",
    "name": "none",
    "type": ".none",
    "fields": null
  },
  "created_at": "2023-11-06T19:29:04.086Z",
  "created_by": {
    "email": null,
    "username": "elastic",
    "full_name": null
  },
  "updated_at": "2023-11-06T19:47:55.662Z",
  "updated_by": {
    "email": null,
    "username": "elastic",
    "full_name": null,
    "profile_uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
  },
  "description": "An Observability case description.",
  "totalAlerts": 1,
  "customFields": [],
  "totalComment": 1,
  "external_service": null
}

Delete all case comments and alerts

DELETE /api/cases/{caseId}/comments
Api key auth Basic auth

Deletes all comments and alerts from a case. You must 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 cases you're deleting.

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.

Responses

  • 204

    Indicates a successful call.

  • 401 application/json

    Authorization information is missing or invalid.

    Hide response attributes Show response attributes object
DELETE /api/cases/{caseId}/comments 
curl \
 --request DELETE 'https://localhost:5601/api/cases/9c235210-6834-11ea-a78c-6ffb38a34414/comments' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: string"

Update a case comment or alert

PATCH /api/cases/{caseId}/comments
Api key auth Basic auth

You must 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 updating. NOTE: You cannot change the comment type or the owner of a comment.

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.

application/json

Body object Required

The update case comment API request body varies depending on whether you are updating an alert or a comment.

One of:
Cases_update_alert_comment_request_properties object Cases_update_user_comment_request_properties object

Defines properties for case comment requests when type is alert.

  • alertId string | array[string] Required

    The alert identifiers. It is required only when type is alert. You can use an array of strings to add multiple alerts to a case, provided that they all relate to the same rule; index must also be an array with the same length or number of elements. Adding multiple alerts in this manner is recommended rather than calling the API multiple times. 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.

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

    The identifier for the comment. To retrieve comment IDs, use the get comments API.

  • index string | array[string] Required

    The alert indices. It is required only when type is alert. If you are adding multiple alerts to a case, use an array of strings; the position of each index name in the array must match the position of the corresponding alert identifier in the alertId array. 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.

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

    The application that owns the cases: Stack Management, Observability, or Elastic Security.

    Values are cases, observability, or securitySolution.

  • rule object Required Technical preview

    The rule that is associated with the alerts. It is required only when type is alert. 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.

    Hide rule attributes Show rule attributes object
    • id string

      The rule identifier.

    • name string

      The rule name.

  • type string Required Discriminator

    The type of comment.

    Value is alert.

  • version string Required

    The current comment version. To retrieve version values, use the get comments API.

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

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

    • created_at string(date-time) Required
    • created_by object Required
      Hide created_by attributes Show created_by attributes object
    • 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
    • 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
    • version string Required
  • 401 application/json

    Authorization information is missing or invalid.

    Hide response attributes Show response attributes object
PATCH /api/cases/{caseId}/comments 
curl \
 --request PATCH 'https://localhost:5601/api/cases/9c235210-6834-11ea-a78c-6ffb38a34414/comments' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"id":"8af6ac20-74f6-11ea-b83a-553aecdb28b6","type":"user","owner":"cases","comment":"An updated comment.","version":"Wzk1LDFd"}'
Request example 
{
  "id": "8af6ac20-74f6-11ea-b83a-553aecdb28b6",
  "type": "user",
  "owner": "cases",
  "comment": "An updated comment.",
  "version": "Wzk1LDFd"
}
Response examples (200) 
{
  "id": "293f1bc0-74f6-11ea-b83a-553aecdb28b6",
  "tags": [
    "tag 1"
  ],
  "owner": "cases",
  "title": "Case title 1",
  "status": "open",
  "version": "WzIwNjM2LDFd",
  "category": null,
  "comments": [
    {
      "id": "8af6ac20-74f6-11ea-b83a-553aecdb28b6",
      "type": "user",
      "owner": "cases",
      "comment": "An updated comment.",
      "version": "WzIwNjM3LDFd",
      "pushed_at": null,
      "pushed_by": null,
      "created_at": "2023-10-24T00:37:10.832Z",
      "created_by": {
        "email": null,
        "username": "elastic",
        "full_name": null,
        "profile_uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
      },
      "updated_at": "2023-10-24T01:27:06.210Z",
      "updated_by": {
        "email": null,
        "username": "elastic",
        "full_name": null,
        "profile_uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
      }
    }
  ],
  "duration": null,
  "settings": {
    "syncAlerts": false
  },
  "severity": "low",
  "assignees": [],
  "closed_at": null,
  "closed_by": null,
  "connector": {
    "id": "none",
    "name": "none",
    "type": ".none",
    "fields": null
  },
  "created_at": "2023-10-24T00:37:03.906Z",
  "created_by": {
    "email": null,
    "username": "elastic",
    "full_name": null,
    "profile_uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
  },
  "updated_at": "2023-10-24T01:27:06.210Z",
  "updated_by": {
    "email": null,
    "username": "elastic",
    "full_name": null,
    "profile_uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
  },
  "description": "A case description.",
  "totalAlerts": 0,
  "customFields": [
    {
      "key": "d312efda-ec2b-42ec-9e2c-84981795c581",
      "type": "text",
      "value": "My new field value"
    },
    {
      "key": "fcc6840d-eb14-42df-8aaf-232201a705ec",
      "type": "toggle",
      "value": false
    }
  ],
  "totalComment": 1,
  "external_service": null
}

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

Get case status summary Deprecated

GET /api/cases/status
Api key auth Basic auth

Returns the number of cases that are open, closed, and in progress. Deprecated in 8.1.0. This API is deprecated and will be removed in a future release; use the find cases API instead. 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.

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

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

Get all connectors Deprecated

GET /api/actions
Api key auth Basic auth
GET /api/actions 
curl \
 --request GET 'https://localhost:5601/api/actions' \
 --header "Authorization: $API_KEY"

Create a connector Deprecated

POST /api/actions/action
Api key auth Basic auth

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

application/json

Body

  • actionTypeId string Required

    The connector type identifier.

  • config object

    Default value is {} (empty). Additional properties are allowed.

  • name string Required

    The display name for the connector.

  • secrets object

    Default value is {} (empty). Additional properties are allowed.

Responses

  • 200 application/json

    Indicates a successful call.

    Hide response attributes Show response attributes object
    • config object

      Additional properties are allowed.

    • connector_type_id string Required

      The connector type identifier.

    • id string Required

      The identifier for the connector.

    • is_deprecated boolean Required

      Indicates whether the connector is deprecated.

    • is_missing_secrets boolean

      Indicates whether the connector is missing secrets.

    • is_preconfigured boolean Required

      Indicates whether the connector is preconfigured. If true, the config and is_missing_secrets properties are omitted from the response.

    • is_system_action boolean Required

      Indicates whether the connector is used for system actions.

    • name string Required

      The name of the rule.
POST /api/actions/action 
curl \
 --request POST 'https://localhost:5601/api/actions/action' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"actionTypeId":"string","config":{},"name":"string","secrets":{}}'

Delete a data view

DELETE /api/data_views/data_view/{viewId}
Api key auth Basic auth

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

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

Path parameters

  • viewId string Required

    An identifier for the data view.

Responses

  • 204

    Indicates a successful call.

  • 404 application/json

    Object is not found.

    Hide response attributes Show response attributes object
DELETE /api/data_views/data_view/{viewId} 
curl \
 --request DELETE 'https://localhost:5601/api/data_views/data_view/ff959d40-b880-11e8-a6d9-e546fe2bba5f' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: string"

Get a runtime field

GET /api/data_views/data_view/{viewId}/runtime_field/{fieldName}
Api key auth Basic auth

Path parameters

  • fieldName string Required

    The name of the runtime field.

  • viewId string Required

    An identifier for the data view.

Responses

  • 200 application/json

    Indicates a successful call.

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

    Object is not found.

    Hide response attributes Show response attributes object
GET /api/data_views/data_view/{viewId}/runtime_field/{fieldName} 
curl \
 --request GET 'https://localhost:5601/api/data_views/data_view/ff959d40-b880-11e8-a6d9-e546fe2bba5f/runtime_field/hour_of_day' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "fields": [
    {
      "name": "hour_of_day",
      "type": "number",
      "count": 0,
      "esTypes": [
        "long"
      ],
      "scripted": false,
      "searchable": true,
      "aggregatable": true,
      "runtimeField": {
        "type": "long",
        "script": {
          "source": "emit(doc['timestamp'].value.getHour());"
        }
      },
      "shortDotsEnable": false,
      "readFromDocValues": false
    }
  ],
  "data_view": {
    "id": "d3d7af60-4c81-11e8-b3d7-01146121b73d",
    "name": "Kibana Sample Data Flights",
    "title": "kibana_sample_data_flights",
    "fields": {
      "_id": {
        "name": "_id",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "_id"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "Dest": {
        "name": "Dest",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "Origin": {
        "name": "Origin",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "_index": {
        "name": "_index",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "_index"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "_score": {
        "name": "_score",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "isMapped": true,
        "scripted": false,
        "searchable": false,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "Carrier": {
        "name": "Carrier",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "_source": {
        "name": "_source",
        "type": "_source",
        "count": 0,
        "format": {
          "id": "_source"
        },
        "esTypes": [
          "_source"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": false,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "Cancelled": {
        "name": "Cancelled",
        "type": "boolean",
        "count": 0,
        "format": {
          "id": "boolean"
        },
        "esTypes": [
          "boolean"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "FlightNum": {
        "name": "FlightNum",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "dayOfWeek": {
        "name": "dayOfWeek",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "integer"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "timestamp": {
        "name": "timestamp",
        "type": "date",
        "count": 0,
        "format": {
          "id": "date"
        },
        "esTypes": [
          "date"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "DestRegion": {
        "name": "DestRegion",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "DestCountry": {
        "name": "DestCountry",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "DestWeather": {
        "name": "DestWeather",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "FlightDelay": {
        "name": "FlightDelay",
        "type": "boolean",
        "count": 0,
        "format": {
          "id": "boolean"
        },
        "esTypes": [
          "boolean"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "hour_of_day": {
        "name": "hour_of_day",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number",
          "params": {
            "pattern": "00"
          }
        },
        "esTypes": [
          "long"
        ],
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "runtimeField": {
          "type": "long",
          "script": {
            "source": "emit(doc['timestamp'].value.getHour());"
          }
        },
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "DestCityName": {
        "name": "DestCityName",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "DestLocation": {
        "name": "DestLocation",
        "type": "geo_point",
        "count": 0,
        "format": {
          "id": "geo_point",
          "params": {
            "transform": "wkt"
          }
        },
        "esTypes": [
          "geo_point"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "OriginRegion": {
        "name": "OriginRegion",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "DestAirportID": {
        "name": "DestAirportID",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "DistanceMiles": {
        "name": "DistanceMiles",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "FlightTimeMin": {
        "name": "FlightTimeMin",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "OriginCountry": {
        "name": "OriginCountry",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "OriginWeather": {
        "name": "OriginWeather",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "AvgTicketPrice": {
        "name": "AvgTicketPrice",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number",
          "params": {
            "pattern": "$0,0.[00]"
          }
        },
        "esTypes": [
          "float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "FlightDelayMin": {
        "name": "FlightDelayMin",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "integer"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "FlightTimeHour": {
        "name": "FlightTimeHour",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "OriginCityName": {
        "name": "OriginCityName",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "OriginLocation": {
        "name": "OriginLocation",
        "type": "geo_point",
        "count": 0,
        "format": {
          "id": "geo_point",
          "params": {
            "transform": "wkt"
          }
        },
        "esTypes": [
          "geo_point"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "FlightDelayType": {
        "name": "FlightDelayType",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "OriginAirportID": {
        "name": "OriginAirportID",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "DistanceKilometers": {
        "name": "DistanceKilometers",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      }
    },
    "version": "WzM2LDJd",
    "fieldAttrs": {},
    "allowNoIndex": false,
    "fieldFormats": {
      "hour_of_day": {
        "id": "number",
        "params": {
          "pattern": "00"
        }
      },
      "AvgTicketPrice": {
        "id": "number",
        "params": {
          "pattern": "$0,0.[00]"
        }
      }
    },
    "sourceFilters": [],
    "timeFieldName": "timestamp",
    "runtimeFieldMap": {
      "hour_of_day": {
        "type": "long",
        "script": {
          "source": "emit(doc['timestamp'].value.getHour());"
        }
      }
    }
  }
}

Delete a runtime field from a data view

DELETE /api/data_views/data_view/{viewId}/runtime_field/{fieldName}
Api key auth Basic auth

Path parameters

  • fieldName string Required

    The name of the runtime field.

  • viewId string Required

    An identifier for the data view.

Responses

  • 200

    Indicates a successful call.

  • 404 application/json

    Object is not found.

    Hide response attributes Show response attributes object
DELETE /api/data_views/data_view/{viewId}/runtime_field/{fieldName} 
curl \
 --request DELETE 'https://localhost:5601/api/data_views/data_view/ff959d40-b880-11e8-a6d9-e546fe2bba5f/runtime_field/hour_of_day' \
 --header "Authorization: $API_KEY"

Logstash configuration management

Programmatically integrate with Logstash configuration management.

Do not directly access the .logstash index. The structure of the .logstash index is subject to change, which could cause your integration to break. Instead, use the Logstash configuration management APIs.

Centralized pipeline management

Get all roles

GET /api/security/role
Api key auth Basic auth

Query parameters

  • replaceDeprecatedPrivileges boolean

    If true and the response contains any privileges that are associated with deprecated features, they are omitted in favor of details about the appropriate replacement feature privileges.

Responses

  • 200 application/json

    Indicates a successful call.

GET /api/security/role 
curl \
 --request GET 'https://localhost:5601/api/security/role' \
 --header "Authorization: $API_KEY"
Response examples (200) 
[
  {
    "name": "my_kibana_role",
    "kibana": [
      {
        "base": [
          "all"
        ],
        "spaces": [
          "*"
        ],
        "feature": {}
      }
    ],
    "metadata": {
      "version": 1
    },
    "description": "My kibana role description",
    "elasticsearch": {
      "run_as": [],
      "cluster": [],
      "indices": []
    },
    "transient_metadata": {
      "enabled": true
    }
  },
  {
    "name": "my_admin_role",
    "kibana": [],
    "metadata": {
      "version": 1
    },
    "description": "My admin role description",
    "elasticsearch": {
      "cluster": [
        "all"
      ],
      "indices": [
        {
          "names": [
            "index1",
            "index2"
          ],
          "query": "{\\\"match\\\": {\\\"title\\\": \\\"foo\\\"}}",
          "privileges": [
            "all"
          ],
          "field_security": {
            "grant": [
              "title",
              "body"
            ]
          }
        }
      ]
    },
    "transient_metadata": {
      "enabled": true
    }
  }
]

Delete saved objects Deprecated

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

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

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

Query parameters

  • force boolean

    When true, force delete objects that exist in multiple namespaces. Note that the option applies to the whole request. Use the delete object API to specify per-object deletion behavior. TIP: Use this if you attempted to delete objects and received an HTTP 400 error with the following message: "Unable to delete saved object that exists in multiple namespaces, use the force option to delete it anyway". WARNING: When you bulk delete objects that exist in multiple namespaces, the API also deletes legacy url aliases that reference the object. These requests are batched to minimise the impact but they can place a heavy load on Kibana. Make sure you limit the number of objects that exist in multiple namespaces in a single bulk delete operation.

application/json

Body Required

object object

Responses

  • 200 application/json

    Indicates a successful call. NOTE: This HTTP response code indicates that the bulk operation succeeded. Errors pertaining to individual objects will be returned in the response body.
  • 400 application/json

    Bad request

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

Import saved objects

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

Create sets of Kibana saved objects from a file created by the export API. Saved objects can be imported only into the same version, a newer minor on the same major, or the next major. Exported saved objects are not backwards compatible and cannot be imported into an older version of Kibana.

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

Query parameters

  • createNewCopies boolean

    Creates copies of saved objects, regenerates each object ID, and resets the origin. When used, potential conflict errors are avoided. NOTE: This option cannot be used with the overwrite and compatibilityMode options.

  • overwrite boolean

    Overwrites saved objects when they already exist. When used, potential conflict errors are automatically resolved by overwriting the destination object. NOTE: This option cannot be used with the createNewCopies option.

  • compatibilityMode boolean

    Applies various adjustments to the saved objects that are being imported to maintain compatibility between different Kibana versions. Use this option only if you encounter issues with imported saved objects. NOTE: This option cannot be used with the createNewCopies option.

multipart/form-data

Body Required

  • file

    A file exported using the export API. NOTE: The savedObjects.maxImportExportSize configuration setting limits the number of saved objects which may be included in this file. Similarly, the savedObjects.maxImportPayloadBytes setting limits the overall size of the file that can be imported.

Responses

  • 200 application/json

    Indicates a successful call.

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

      Indicates the import was unsuccessful and specifies the objects that failed to import.

      NOTE: One object may result in multiple errors, which requires separate steps to resolve. For instance, a missing_references error and conflict error.

    • success boolean

      Indicates when the import was successfully completed. When set to false, some objects may not have been created. For additional information, refer to the errors and successResults properties.

    • successCount integer

      Indicates the number of successfully imported records.

    • successResults array[object]

      Indicates the objects that are successfully imported, with any metadata if applicable.

      NOTE: Objects are created only when all resolvable errors are addressed, including conflicts and missing references. If objects are created as new copies, each entry in the successResults array includes a destinationId attribute.
  • 400 application/json

    Bad request.

    Hide response attributes Show response attributes object
POST /api/saved_objects/_import 
curl \
  -X POST api/saved_objects/_import?createNewCopies=true
  -H "kbn-xsrf: true"
  --form file=@file.ndjson
Request example 
{"file"=>"file.ndjson"}
Response examples (200) 
{
  "success": true,
  "successCount": 1,
  "successResults": [
    {
      "id": "90943e30-9a47-11e8-b64d-95841ca0b247",
      "meta": {
        "icon": "indexPatternApp",
        "title": "Kibana Sample Data Logs"
      },
      "type": "index-pattern",
      "managed": false,
      "destinationId": "82d2760c-468f-49cf-83aa-b9a35b6a8943"
    }
  ]
}

Resolve import errors

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

To resolve errors from the Import objects API, you can:

  • Retry certain saved objects
  • Overwrite specific saved objects
  • Change references to different saved objects

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

Query parameters

  • compatibilityMode boolean

    Applies various adjustments to the saved objects that are being imported to maintain compatibility between different Kibana versions. When enabled during the initial import, also enable when resolving import errors. This option cannot be used with the createNewCopies option.

  • createNewCopies boolean

    Creates copies of the saved objects, regenerates each object ID, and resets the origin. When enabled during the initial import, also enable when resolving import errors.

multipart/form-data

Body Required

  • file string(binary)

    The same file given to the import API.

  • retries array[object] Required

    The retry operations, which can specify how to resolve different types of errors.

    Hide retries attributes Show retries attributes object
    • destinationId string

      Specifies the destination ID that the imported object should have, if different from the current ID.

    • id string Required

      The saved object ID.

    • ignoreMissingReferences boolean

      When set to true, ignores missing reference errors. When set to false, does nothing.

    • overwrite boolean

      When set to true, the source object overwrites the conflicting destination object. When set to false, does nothing.

    • replaceReferences array[object]

      A list of type, from, and to used to change the object references.

      Hide replaceReferences attributes Show replaceReferences attributes object
    • type string Required

      The saved object type.

Responses

  • 200 application/json

    Indicates a successful call.

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

      Specifies the objects that failed to resolve.

      NOTE: One object can result in multiple errors, which requires separate steps to resolve. For instance, a missing_references error and a conflict error.

    • success boolean

      Indicates a successful import. When set to false, some objects may not have been created. For additional information, refer to the errors and successResults properties.

    • successCount number

      Indicates the number of successfully resolved records.

    • successResults array[object]

      Indicates the objects that are successfully imported, with any metadata if applicable.

      NOTE: Objects are only created when all resolvable errors are addressed, including conflict and missing references.
  • 400 application/json

    Bad request.

    Hide response attributes Show response attributes object
POST /api/saved_objects/_resolve_import_errors 
curl \
 --request POST 'https://localhost:5601/api/saved_objects/_resolve_import_errors' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: multipart/form-data" \
 --header "kbn-xsrf: string" \
 --form "file=file.ndjson" \
 --form "retries[]={"id"=>"my-pattern", "type"=>"index-pattern", "overwrite"=>true}" \
 --form "retries[]={"id"=>"my-vis", "type"=>"visualization", "overwrite"=>true, "destinationId"=>"another-vis"}" \
 --form "retries[]={"id"=>"my-canvas", "type"=>"canvas", "overwrite"=>true, "destinationId"=>"yet-another-canvas"}" \
 --form "retries[]={"id"=>"my-dashboard", "type"=>"dashboard"}"
Request example 
{"file"=>"file.ndjson", "retries"=>[{"id"=>"my-pattern", "type"=>"index-pattern", "overwrite"=>true}, {"id"=>"my-vis", "type"=>"visualization", "overwrite"=>true, "destinationId"=>"another-vis"}, {"id"=>"my-canvas", "type"=>"canvas", "overwrite"=>true, "destinationId"=>"yet-another-canvas"}, {"id"=>"my-dashboard", "type"=>"dashboard"}]}
Response examples (200) 
{
  "success": true,
  "successCount": 3,
  "successResults": [
    {
      "id": "my-vis",
      "meta": {
        "icon": "visualizeApp",
        "title": "Look at my visualization"
      },
      "type": "visualization"
    },
    {
      "id": "my-search",
      "meta": {
        "icon": "searchApp",
        "title": "Look at my search"
      },
      "type": "search"
    },
    {
      "id": "my-dashboard",
      "meta": {
        "icon": "dashboardApp",
        "title": "Look at my dashboard"
      },
      "type": "dashboard"
    }
  ]
}

Get a saved object Deprecated

GET /api/saved_objects/{type}/{id}
Api key auth Basic auth

Retrieve a single Kibana saved object by identifier.

Path parameters

  • id string Required

    An identifier for the saved object.

  • type string Required

    Valid options include visualization, dashboard, search, index-pattern, config.

Responses

  • 200 application/json

    Indicates a successful call.
  • 400 application/json

    Bad request.

    Hide response attributes Show response attributes object
GET /api/saved_objects/{type}/{id} 
curl \
 --request GET 'https://localhost:5601/api/saved_objects/{type}/{id}' \
 --header "Authorization: $API_KEY"

Update a saved object Deprecated

PUT /api/saved_objects/{type}/{id}
Api key auth Basic auth

Update the attributes for Kibana saved objects.

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

Path parameters

  • id string Required

    An identifier for the saved object.

  • type string Required

    Valid options include visualization, dashboard, search, index-pattern, config.

application/json

Body Required

object object

Responses

  • 200 application/json

    Indicates a successful call.
  • 404 application/json

    Indicates the object was not found.
  • 409 application/json

    Indicates a conflict error.
PUT /api/saved_objects/{type}/{id} 
curl \
 --request PUT 'https://localhost:5601/api/saved_objects/{type}/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string"

Update a Knowledge Base Entry

PUT /api/security_ai_assistant/knowledge_base/entries/{id}
Api key auth Basic auth

Update an existing Knowledge Base Entry by its unique id.

Path parameters

  • id string(nonempty) Required

    The unique identifier (id) of the Knowledge Base Entry to update.

    Minimum length is 1.

application/json

Body object Required

Any of:
Security_AI_Assistant_API_DocumentEntryCreateFields object Security_AI_Assistant_API_IndexEntryCreateFields object
  • global boolean

    Whether this Knowledge Base Entry is global, defaults to false.

  • name string Required

    Name of the Knowledge Base Entry.

  • namespace string

    Kibana Space, defaults to 'default' space.

  • users array[object]

    Users who have access to the Knowledge Base Entry, defaults to current user. Empty array provides access to all users.

    Could be any string, not necessarily a UUID.

    Hide users attributes Show users attributes object
  • kbResource string Required

    Knowledge Base resource name for grouping entries, e.g. 'security_labs', 'user', etc.

    Values are security_labs or user.

  • source string Required

    Source document name or filepath.

  • text string Required

    Knowledge Base Entry content.

  • type string Required Discriminator

    Entry type.

    Value is document.

  • required boolean

    Whether this resource should always be included, defaults to false.

  • vector object

    Object containing Knowledge Base Entry text embeddings and modelId used to create the embeddings.

    Hide vector attributes Show vector attributes object
    • modelId string Required

      ID of the model used to create the embeddings.

    • tokens object Required

      Tokens with their corresponding values.

      Hide tokens attribute Show tokens attribute object
      • * number Additional properties

Responses

  • 200 application/json

    Successful request returning the updated Knowledge Base Entry.

    Any of:
    Security_AI_Assistant_API_DocumentEntryResponseFields object Security_AI_Assistant_API_IndexEntryResponseFields object
    Hide attributes Show attributes
    • global boolean Required

      Whether this Knowledge Base Entry is global, defaults to false.

    • name string Required

      Name of the Knowledge Base Entry.

    • namespace string Required

      Kibana Space, defaults to 'default' space.

    • users array[object] Required

      Users who have access to the Knowledge Base Entry, defaults to current user. Empty array provides access to all users.

      Could be any string, not necessarily a UUID.

      Hide users attributes Show users attributes object
    • createdAt string Required

      Time the Knowledge Base Entry was created.

    • createdBy string Required

      User who created the Knowledge Base Entry.

    • id string(nonempty) Required

      The ID of the anonymization field.

      Minimum length is 1.

    • updatedAt string Required

      Time the Knowledge Base Entry was last updated.

    • updatedBy string Required

      User who last updated the Knowledge Base Entry.

    • kbResource string Required

      Knowledge Base resource name for grouping entries, e.g. 'security_labs', 'user', etc.

      Values are security_labs or user.

    • source string Required

      Source document name or filepath.

    • text string Required

      Knowledge Base Entry content.

    • type string Required Discriminator

      Entry type.

      Value is document.

    • required boolean

      Whether this resource should always be included, defaults to false.

    • vector object

      Object containing Knowledge Base Entry text embeddings and modelId used to create the embeddings.

      Hide vector attributes Show vector attributes object
      • modelId string Required

        ID of the model used to create the embeddings.

      • tokens object Required

        Tokens with their corresponding values.

        Hide tokens attribute Show tokens attribute object
        • * number Additional properties
  • 400 application/json

    A generic error occurred, such as invalid input or the entry not being found.

    Hide response attributes Show response attributes object
    • error string Required

      Error type or category.

    • message string Required

      Detailed error message.

    • statusCode number Required

      HTTP status code of the error.
PUT /api/security_ai_assistant/knowledge_base/entries/{id} 
curl \
 --request PUT 'https://localhost:5601/api/security_ai_assistant/knowledge_base/entries/12345' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"tags":["password","reset","help","update"],"title":"How to reset a password (updated)","content":"To reset your password, go to the settings page, click 'Reset Password', and follow the instructions."}'
Request example 
{
  "tags": [
    "password",
    "reset",
    "help",
    "update"
  ],
  "title": "How to reset a password (updated)",
  "content": "To reset your password, go to the settings page, click 'Reset Password', and follow the instructions."
}
Response examples (200) 
{
  "id": "12345",
  "tags": [
    "password",
    "reset",
    "help",
    "update"
  ],
  "title": "How to reset a password (updated)",
  "content": "To reset your password, go to the settings page, click 'Reset Password', and follow the instructions."
}
Response examples (400) 
{
  "error": "Invalid input",
  "message": "The 'content' field cannot be empty."
}

Deletes a single Knowledge Base Entry using the `id` field

DELETE /api/security_ai_assistant/knowledge_base/entries/{id}
Api key auth Basic auth

Delete a Knowledge Base Entry by its unique id.

Path parameters

  • id string(nonempty) Required

    The unique identifier (id) of the Knowledge Base Entry to delete.

    Minimum length is 1.

Responses

  • 200 application/json

    Successful request returning the id of the deleted Knowledge Base Entry.

    Hide response attribute Show response attribute object
    • id string(nonempty) Required

      The ID of the anonymization field.

      Minimum length is 1.
  • 400 application/json

    A generic error occurred, such as an invalid id or the entry not being found.

    Hide response attributes Show response attributes object
    • error string Required

      Error type or category.

    • message string Required

      Detailed error message.

    • statusCode number Required

      HTTP status code of the error.
DELETE /api/security_ai_assistant/knowledge_base/entries/{id} 
curl \
 --request DELETE 'https://localhost:5601/api/security_ai_assistant/knowledge_base/entries/12345' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "id": "12345",
  "message": "Knowledge Base Entry successfully deleted."
}
Response examples (400) 
{
  "error": "Not Found",
  "message": "No Knowledge Base Entry found with the provided `id`."
}

Apply a bulk action to prompts

POST /api/security_ai_assistant/prompts/_bulk_action
Api key auth Basic auth

Apply a bulk action to multiple prompts. The bulk action is applied to all prompts that match the filter or to the list of prompts by their IDs. This action allows for bulk create, update, or delete operations.

application/json

Body

  • create array[object]

    List of prompts to be created.

    Hide create attributes Show create attributes object
    • categories array[string]

      List of categories for the prompt.

    • color string

      The color associated with the prompt.

    • consumer string

      The consumer associated with the prompt.

    • content string Required

      The content of the prompt.

    • isDefault boolean

      Whether this prompt should be the default.

    • isNewConversationDefault boolean

      Whether this prompt should be the default for new conversations.

    • name string Required

      The name of the prompt.

    • promptType string Required

      The type of the prompt.

      Values are system or quick.

  • delete object

    Criteria for deleting prompts in bulk.

    Hide delete attributes Show delete attributes object
    • ids array[string]

      Array of IDs to apply the action to.

      At least 1 element.

    • query string

      Query to filter the bulk action.

  • update array[object]

    List of prompts to be updated.

    Hide update attributes Show update attributes object
    • categories array[string]

      The updated categories for the prompt.

    • color string

      The updated color associated with the prompt.

    • consumer string

      The updated consumer for the prompt.

    • content string

      The updated content for the prompt.

    • id string Required

      The ID of the prompt to update.

    • isDefault boolean

      Whether this prompt should be the default.

    • isNewConversationDefault boolean

      Whether the prompt should be the default for new conversations.

Responses

  • 200 application/json

    Indicates a successful call with the results of the bulk action.

    Hide response attributes Show response attributes object
    • attributes object Required
      Hide attributes attributes Show attributes attributes object
      • errors array[object]
        Hide errors attributes Show errors attributes object
        • err_code string

          A code representing the error type.

        • message string Required

          A message describing the error encountered.

        • prompts array[object] Required

          List of prompts that encountered errors.

          Hide prompts attributes Show prompts attributes object
          • id string Required

            The ID of the prompt that encountered an error.

          • name string

            The name of the prompt that encountered an error.

        • status_code integer Required

          The HTTP status code associated with the error.

      • results object Required
        Hide results attributes Show results attributes object
        • created array[object] Required

          List of prompts that were created.

          Hide created attributes Show created attributes object
          • categories array[string]

            Categories associated with the prompt.

          • color string

            The color associated with the prompt.

          • consumer string

            The consumer that the prompt is associated with.

          • content string Required

            The content of the prompt.

          • createdAt string

            The timestamp of when the prompt was created.

          • createdBy string

            The user who created the prompt.

          • id string(nonempty) Required

            The ID of the anonymization field.

            Minimum length is 1.

          • isDefault boolean

            Whether this prompt is the default.

          • isNewConversationDefault boolean

            Whether this prompt is the default for new conversations.

          • name string Required

            The name of the prompt.

          • namespace string

            Kibana space where the prompt is located.

          • promptType string Required

            The type of the prompt.

            Values are system or quick.

          • timestamp string(nonempty)

            Timestamp when the anonymization field was initially created.

            Minimum length is 1.

          • updatedAt string

            The timestamp of when the prompt was last updated.

          • updatedBy string

            The user who last updated the prompt.

          • users array[object]

            List of users associated with the prompt.

            Could be any string, not necessarily a UUID.

            Hide users attributes Show users attributes object
        • deleted array[string] Required

          List of IDs of prompts that were deleted.

        • skipped array[object] Required

          List of prompts that were skipped.

          Hide skipped attributes Show skipped attributes object
          • id string Required

            The ID of the prompt that was skipped.

          • name string

            The name of the prompt that was skipped.

          • skip_reason string Required

            The reason for skipping the prompt.

            Value is PROMPT_FIELD_NOT_MODIFIED.

        • updated array[object] Required

          List of prompts that were updated.

          Hide updated attributes Show updated attributes object
          • categories array[string]

            Categories associated with the prompt.

          • color string

            The color associated with the prompt.

          • consumer string

            The consumer that the prompt is associated with.

          • content string Required

            The content of the prompt.

          • createdAt string

            The timestamp of when the prompt was created.

          • createdBy string

            The user who created the prompt.

          • id string(nonempty) Required

            The ID of the anonymization field.

            Minimum length is 1.

          • isDefault boolean

            Whether this prompt is the default.

          • isNewConversationDefault boolean

            Whether this prompt is the default for new conversations.

          • name string Required

            The name of the prompt.

          • namespace string

            Kibana space where the prompt is located.

          • promptType string Required

            The type of the prompt.

            Values are system or quick.

          • timestamp string(nonempty)

            Timestamp when the anonymization field was initially created.

            Minimum length is 1.

          • updatedAt string

            The timestamp of when the prompt was last updated.

          • updatedBy string

            The user who last updated the prompt.

          • users array[object]

            List of users associated with the prompt.

            Could be any string, not necessarily a UUID.

            Hide users attributes Show users attributes object
      • summary object Required
        Hide summary attributes Show summary attributes object
        • failed integer Required

          The number of failed actions.

        • skipped integer Required

          The number of skipped actions.

        • succeeded integer Required

          The number of successfully performed actions.

        • total integer Required

          The total number of actions attempted.

    • message string

      A message describing the result of the bulk action.

    • prompts_count integer

      The number of prompts processed in the bulk action.

    • status_code integer

      The HTTP status code of the response.

    • success boolean

      Indicates if the bulk action was successful.
  • 400 application/json

    Indicates a generic error due to a bad request.

    Hide response attributes Show response attributes object
POST /api/security_ai_assistant/prompts/_bulk_action 
curl \
 --request POST 'https://localhost:5601/api/security_ai_assistant/prompts/_bulk_action' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"create":[{"name":"New Security Prompt","content":"Please verify the security settings.","promptType":"system"}],"delete":{"ids":["prompt1","prompt2"]},"update":[{"id":"prompt123","content":"Updated content for security prompt."}]}'
Request example 
{
  "create": [
    {
      "name": "New Security Prompt",
      "content": "Please verify the security settings.",
      "promptType": "system"
    }
  ],
  "delete": {
    "ids": [
      "prompt1",
      "prompt2"
    ]
  },
  "update": [
    {
      "id": "prompt123",
      "content": "Updated content for security prompt."
    }
  ]
}
Response examples (200) 
{
  "message": "Bulk action completed successfully.",
  "success": true,
  "attributes": {
    "errors": [],
    "results": {
      "created": [
        {
          "id": "prompt6",
          "name": "New Security Prompt",
          "content": "Please verify the security settings.",
          "promptType": "system"
        }
      ],
      "deleted": [
        "prompt2",
        "prompt3"
      ],
      "skipped": [
        {
          "id": "prompt4",
          "name": "Security Prompt",
          "skip_reason": "PROMPT_FIELD_NOT_MODIFIED"
        }
      ],
      "updated": [
        {
          "id": "prompt1",
          "name": "Security Prompt",
          "content": "Updated security settings prompt",
          "promptType": "system"
        }
      ]
    },
    "summary": {
      "total": 5,
      "failed": 0,
      "skipped": 1,
      "succeeded": 4
    }
  },
  "status_code": 200,
  "prompts_count": 5
}

Create a value list

POST /api/lists
Api key auth Basic auth

Create a new value list.

application/json

Body Required

Value list's properties

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

    Value list's identifier.

    Minimum length is 1.

  • meta object

    Placeholder for metadata about the value list.

    Additional properties are allowed.

  • name string(nonempty) Required

    Value list's name.

    Minimum length is 1.

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

  • version integer

    Minimum value is 1. Default value is 1.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • _version string

      The version id, normally returned by the API when the document is retrieved. Use it ensure updates are done against the latest version.

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

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

    • description string(nonempty) Required

      Describes the value list.

      Minimum length is 1.

    • deserializer string

      Determines how retrieved list item values are presented. By default list items are presented using these Handelbar expressions:

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

      Value list's identifier.

      Minimum length is 1.

    • immutable boolean Required
    • meta object

      Placeholder for metadata about the value list.

      Additional properties are allowed.

    • name string(nonempty) Required

      Value list's name.

      Minimum length is 1.

    • serializer string

      Determines how uploaded list item values are parsed. By default, list items are parsed using these named regex groups:

      • (?<value>.+) - Single value item types, such as ip, long, date, keyword, and text.
      • (?<gte>.+)-(?<lte>.+)|(?<value>.+) - Range value item types, such as date_range, ip_range, double_range, float_range, integer_range, and long_range.
    • tie_breaker_id string Required

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

    • type string Required

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

      • keyword: Many ECS fields are Elasticsearch keywords
      • ip: IP addresses
      • ip_range: Range of IP addresses (supports IPv4, IPv6, and CIDR notation)

      Values are binary, boolean, byte, date, date_nanos, date_range, double, double_range, float, float_range, geo_point, geo_shape, half_float, integer, integer_range, ip, ip_range, keyword, long, long_range, shape, short, or text.

    • updated_at string(date-time) Required

      Autogenerated date of last object update.

    • updated_by string Required

      Autogenerated value - user that last updated object.

    • version integer Required

      The document version number.

      Minimum value is 1.
  • 400 application/json

    Invalid input data response

    One of:
    Security_Lists_API_PlatformErrorResponse object Security_Lists_API_SiemErrorResponse object
    Hide attributes Show attributes
  • 401 application/json

    Unsuccessful authentication response

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

    Not enough privileges response

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

    List already exists response

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

    Internal server error response

    Hide response attributes Show response attributes object
POST /api/lists 
curl \
 --request POST 'https://localhost:5601/api/lists' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"id":"ip_list","name":"Simple list with ips","type":"ip","description":"This list describes bad internet ips"}'
Request examples 
{
  "id": "ip_list",
  "name": "Simple list with ips",
  "type": "ip",
  "description": "This list describes bad internet ips"
}
{
  "id": "ip_range_list",
  "name": "Simple list with ip ranges",
  "type": "ip_range",
  "description": "This list has ip ranges"
}
{
  "id": "keyword_list",
  "name": "Simple list with a keyword",
  "type": "keyword",
  "description": "This list describes bad host names"
}
{
  "id": "keyword_custom_format_list",
  "name": "Simple list with a keyword using a custom format",
  "type": "keyword",
  "serializer": "(?<value>((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?))",
  "description": "This parses the first found ipv4 only",
  "deserializer": "{{value}}"
}
Response examples (200) 
{
  "id": "ip_list",
  "name": "Simple list with ips",
  "type": "ip",
  "version": 1,
  "_version": "WzAsMV0=",
  "immutable": false,
  "@timestamp": "2025-01-08T04:47:34.273Z",
  "created_at": "2025-01-08T04:47:34.273Z",
  "created_by": "elastic",
  "updated_at": "2025-01-08T04:47:34.273Z",
  "updated_by": "elastic",
  "description": "This list describes bad internet ips",
  "tie_breaker_id": "f5508188-b1e9-4e6e-9662-d039a7d89899"
}
{
  "id": "ip_range_list",
  "name": "Simple list with ip ranges",
  "type": "ip_range",
  "version": 1,
  "_version": "WzAsMV0=",
  "immutable": false,
  "@timestamp": "2025-01-09T18:23:52.241Z",
  "created_at": "2025-01-09T18:23:52.241Z",
  "created_by": "elastic",
  "updated_at": "2025-01-09T18:23:52.241Z",
  "updated_by": "elastic",
  "description": "This list has ip ranges",
  "tie_breaker_id": "74aebdaf-601f-4940-b351-155728ff7003"
}
{
  "id": "keyword_list",
  "name": "Simple list with a keyword",
  "type": "keyword",
  "version": 1,
  "_version": "WzEsMV0=",
  "immutable": false,
  "@timestamp": "2025-01-09T18:24:55.786Z",
  "created_at": "2025-01-09T18:24:55.786Z",
  "created_by": "elastic",
  "updated_at": "2025-01-09T18:24:55.786Z",
  "updated_by": "elastic",
  "description": "This list describes bad host names",
  "tie_breaker_id": "f7e7dbaa-daf7-4c9a-a3dc-56643923ef68"
}
{
  "id": "keyword_custom_format_list",
  "name": "Simple list with a keyword using a custom format",
  "type": "keyword",
  "version": 1,
  "_version": "WzIsMV0=",
  "immutable": false,
  "@timestamp": "2025-01-09T18:25:39.604Z",
  "created_at": "2025-01-09T18:25:39.604Z",
  "created_by": "elastic",
  "serializer": "(?<value>((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?))",
  "updated_at": "2025-01-09T18:25:39.604Z",
  "updated_by": "elastic",
  "description": "This parses the first found ipv4 only",
  "deserializer": "{{value}}",
  "tie_breaker_id": "8247ae63-b780-47b8-9a89-948b643e9ec2"
}
Response examples (400) 
{
  "message": "To create a list, the data stream must exist first. Data stream \\\".lists-default\\\" does not exist",
  "status_code": 400
}
Response examples (401) 
{
  "error": "Unauthorized",
  "message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403) 
{
  "error": "Forbidden",
  "message": "API [POST /api/lists] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}
Response examples (409) 
{
  "message": "list id: \"keyword_custom_format_list\" already exists",
  "status_code": 409
}
Response examples (500) 
{
  "message": "Internal Server Error",
  "status_code": 500
}