Get information about rules Beta

GET /api/alerting/rules/_find

Query parameters

  • per_page number

    The number of rules to return per page.

    Minimum value is 0. Default value is 10.

  • page number

    The page number to return.

    Minimum value is 1. Default value is 1.

  • The default operator to use for the simple_query_string.

    Values are OR or AND. Default value is OR.

  • search_fields array[string] | string

    The fields to perform the simple_query_string parsed query against.

  • Determines which field is used to sort the results. The field must exist in the attributes key of the response.

  • Determines the sort order.

    Values are asc or desc.

  • has_reference object | null

    Filters the rules that have a relation with the reference objects with a specific type and identifier.

    Additional properties are NOT allowed.

    Hide has_reference attributes Show has_reference attributes object | null
  • fields array[string]

    The fields to return in the attributes key of the response.

  • filter string

    A KQL string that you filter with an attribute from your saved object. It should look like savedObjectType.attributes.title: "myTitle". However, if you used a direct attribute of a saved object, such as updatedAt, you must define your filter, for example, savedObjectType.updatedAt > 2018-12-22.

  • filter_consumers array[string]

    List of consumers to filter.

Responses

  • 200 application/json

    Indicates a successful call.

    Hide response attributes Show response attributes object
    • actions array[object] Required
      Hide actions attributes Show actions attributes object
      • Defines a period that limits whether the action runs.

        Additional properties are NOT allowed.

        Hide alerts_filter attributes Show alerts_filter attributes object
        • query object

          Additional properties are NOT allowed.

          Hide query attributes Show query attributes object
          • dsl string

            A filter written in Elasticsearch Query Domain Specific Language (DSL).

          • filters array[object] Required

            A filter written in Elasticsearch Query Domain Specific Language (DSL) as defined in the kbn-es-query package.

            Hide filters attributes Show filters attributes object
            • $state object

              Additional properties are NOT allowed.

              Hide $state attribute Show $state attribute object
              • store string Required

                A filter can be either specific to an application context or applied globally.

                Values are appState or globalState.

            • meta object Required

              Additional properties are allowed.

            • query object

              Additional properties are allowed.

          • kql string Required

            A filter written in Kibana Query Language (KQL).

        • Additional properties are NOT allowed.

          Hide timeframe attributes Show timeframe attributes object
          • days array[integer] Required

            Defines the days of the week that the action can run, represented as an array of numbers. For example, 1 represents Monday. An empty array is equivalent to specifying all the days of the week.

            Values are 1, 2, 3, 4, 5, 6, or 7.

          • hours object Required

            Additional properties are NOT allowed.

            Hide hours attributes Show hours attributes object
            • end string Required

              The end of the time frame in 24-hour notation (hh:mm).

            • start string Required

              The start of the time frame in 24-hour notation (hh:mm).

          • timezone string Required

            The ISO time zone for the hours values. Values such as UTC and UTC+1 also work but lack built-in daylight savings time support and are not recommended.

      • connector_type_id string Required

        The type of connector. This property appears in responses but cannot be set in requests.

      • Additional properties are NOT allowed.

        Hide frequency attributes Show frequency attributes object
        • notify_when string Required

          Indicates how often alerts generate actions. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify notify_when at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.

          Values are onActionGroupChange, onActiveAlert, or onThrottleInterval.

        • summary boolean Required

          Indicates whether the action is a summary.

        • throttle string | null Required

          The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if 'notify_when' is set to 'onThrottleInterval'. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.

      • group string

        The group name, which affects when the action runs (for example, when the threshold is met or when the alert is recovered). Each rule type has a list of valid action group names. If you don't need to group actions, set to default.

      • id string Required

        The identifier for the connector saved object.

      • params object Required

        The parameters for the action, which are sent to the connector. The params are handled as Mustache templates and passed a default set of context.

        Additional properties are allowed.

      • Indicates whether to use alert data as a template.

      • uuid string

        A universally unique identifier (UUID) for the action.

    • active_snoozes array[string]

      List of active snoozes for the rule.

    • Indicates that an alert occurs only when the specified number of consecutive runs met the rule conditions.

      Additional properties are NOT allowed.

      Hide alert_delay attribute Show alert_delay attribute object
      • active number Required

        The number of consecutive runs that must meet the rule conditions.

    • Indicates whether the API key that is associated with the rule was created by the user.

    • api_key_owner string | null Required

      The owner of the API key that is associated with the rule and used to run background tasks.

    • consumer string Required

      The name of the application or feature that owns the rule. For example: alerts, apm, discover, infrastructure, logs, metrics, ml, monitoring, securitySolution, siem, stackAlerts, or uptime.

    • created_at string Required

      The date and time that the rule was created.

    • created_by string | null Required

      The identifier for the user that created the rule.

    • enabled boolean Required

      Indicates whether you want to run the rule on an interval basis after it is created.

    • execution_status object Required

      Additional properties are NOT allowed.

      Hide execution_status attributes Show execution_status attributes object
      • error object

        Additional properties are NOT allowed.

        Hide error attributes Show error attributes object
        • message string Required

          Error message.

        • reason string Required

          Reason for error.

          Values are read, decrypt, execute, unknown, license, timeout, disabled, or validate.

      • Duration of last execution of the rule.

      • last_execution_date string Required

        The date and time when rule was executed last.

      • status string Required

        Status of rule execution.

        Values are ok, active, error, warning, pending, or unknown.

      • warning object

        Additional properties are NOT allowed.

        Hide warning attributes Show warning attributes object
        • message string Required

          Warning message.

        • reason string Required

          Reason for warning.

          Values are maxExecutableActions, maxAlerts, maxQueuedActions, or ruleExecution.

    • flapping object | null

      When flapping detection is turned on, alerts that switch quickly between active and recovered states are identified as “flapping” and notifications are reduced.

      Additional properties are NOT allowed.

      Hide flapping attributes Show flapping attributes object | null
      • look_back_window number Required

        The minimum number of runs in which the threshold must be met.

        Minimum value is 2, maximum value is 20.

      • The minimum number of times an alert must switch states in the look back window.

        Minimum value is 2, maximum value is 20.

    • id string Required

      The identifier for the rule.

    • is_snoozed_until string | null

      The date when the rule will no longer be snoozed.

    • last_run object | null

      Additional properties are NOT allowed.

      Hide last_run attributes Show last_run attributes object | null
      • alerts_count object Required

        Additional properties are NOT allowed.

        Hide alerts_count attributes Show alerts_count attributes object
        • active number | null

          Number of active alerts during last run.

        • ignored number | null

          Number of ignored alerts during last run.

        • new number | null

          Number of new alerts during last run.

        • recovered number | null

          Number of recovered alerts during last run.

      • outcome string Required

        Outcome of last run of the rule. Value could be succeeded, warning or failed.

        Values are succeeded, warning, or failed.

      • outcome_msg array[string] | null

        Outcome message generated during last rule run.

      • Order of the outcome.

      • warning string | null

        Warning of last rule execution.

        Values are read, decrypt, execute, unknown, license, timeout, disabled, validate, maxExecutableActions, maxAlerts, maxQueuedActions, or ruleExecution.

    • Additional properties are allowed.

    • Monitoring details of the rule.

      Additional properties are NOT allowed.

      Hide monitoring attribute Show monitoring attribute object
      • run object Required

        Rule run details.

        Additional properties are NOT allowed.

        Hide run attributes Show run attributes object
        • calculated_metrics object Required

          Calculation of different percentiles and success ratio.

          Additional properties are NOT allowed.

          Hide calculated_metrics attributes Show calculated_metrics attributes object
        • history array[object] Required

          History of the rule run.

          Hide history attributes Show history attributes object
          • duration number

            Duration of the rule run.

          • outcome string

            Outcome of last run of the rule. Value could be succeeded, warning or failed.

            Values are succeeded, warning, or failed.

          • success boolean Required

            Indicates whether the rule run was successful.

          • timestamp number Required

            Time of rule run.

        • last_run object Required

          Additional properties are NOT allowed.

          Hide last_run attributes Show last_run attributes object
          • metrics object Required

            Additional properties are NOT allowed.

            Hide metrics attributes Show metrics attributes object
            • duration number

              Duration of most recent rule run.

            • gap_duration_s number | null

              Duration in seconds of rule run gap.

            • gap_range object | null

              Additional properties are NOT allowed.

              Hide gap_range attributes Show gap_range attributes object | null
              • gte string Required

                End of the gap range.

              • lte string Required

                Start of the gap range.

            • Total number of alerts created during last rule run.

            • Total number of alerts detected during last rule run.

            • Total time spent indexing documents during last rule run in milliseconds.

            • Total time spent performing Elasticsearch searches as measured by Kibana; includes network latency and time spent serializing or deserializing the request and response.

          • timestamp string Required

            Time of the most recent rule run.

    • mute_all boolean Required

      Indicates whether all alerts are muted.

    • muted_alert_ids array[string] Required

      List of identifiers of muted alerts.

    • name string Required

      The name of the rule.

    • next_run string | null

      Date and time of the next run of the rule.

    • notify_when string | null

      Indicates how often alerts generate actions. Valid values include: onActionGroupChange: Actions run when the alert status changes; onActiveAlert: Actions run when the alert becomes active and at each check interval while the rule conditions are met; onThrottleInterval: Actions run when the alert becomes active and at the interval specified in the throttle property while the rule conditions are met. NOTE: You cannot specify notify_when at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.

      Values are onActionGroupChange, onActiveAlert, or onThrottleInterval.

    • params object Required

      The parameters for the rule.

      Additional properties are allowed.

    • revision number Required

      The rule revision number.

    • rule_type_id string Required

      The rule type identifier.

    • running boolean | null

      Indicates whether the rule is running.

    • schedule object Required

      Additional properties are NOT allowed.

      Hide schedule attribute Show schedule attribute object
      • interval string Required

        The interval is specified in seconds, minutes, hours, or days.

    • Identifier of the scheduled task.

    • snooze_schedule array[object]
      Hide snooze_schedule attributes Show snooze_schedule attributes object
      • duration number Required

        Duration of the rule snooze schedule.

      • id string

        Identifier of the rule snooze schedule.

      • rRule object Required

        Additional properties are NOT allowed.

        Hide rRule attributes Show rRule attributes object
        • byhour array[number] | null

          Indicates hours of the day to recur.

        • byminute array[number] | null

          Indicates minutes of the hour to recur.

        • bymonth array[number] | null

          Indicates months of the year that this rule should recur.

        • bymonthday array[number] | null

          Indicates the days of the month to recur.

        • bysecond array[number] | null

          Indicates seconds of the day to recur.

        • bysetpos array[number] | null

          A positive or negative integer affecting the nth day of the month. For example, -2 combined with byweekday of FR is 2nd to last Friday of the month. It is recommended to not set this manually and just use byweekday.

        • byweekday array[string | number] | null

          Indicates the days of the week to recur or else nth-day-of-month strings. For example, "+2TU" second Tuesday of month, "-1FR" last Friday of the month, which are internally converted to a byweekday/bysetpos combination.

        • byweekno array[number] | null

          Indicates number of the week hours to recur.

        • byyearday array[number] | null

          Indicates the days of the year that this rule should recur.

        • count number

          Number of times the rule should recur until it stops.

        • dtstart string Required

          Rule start date in Coordinated Universal Time (UTC).

        • freq integer

          Indicates frequency of the rule. Options are YEARLY, MONTHLY, WEEKLY, DAILY.

          Values are 0, 1, 2, 3, 4, 5, or 6.

        • interval number

          Indicates the interval of frequency. For example, 1 and YEARLY is every 1 year, 2 and WEEKLY is every 2 weeks.

        • tzid string Required

          Indicates timezone abbreviation.

        • until string

          Recur the rule until this date.

        • wkst string

          Indicates the start of week, defaults to Monday.

          Values are MO, TU, WE, TH, FR, SA, or SU.

      • skipRecurrences array[string]

        Skips recurrence of rule on this date.

    • tags array[string] Required

      The tags for the rule.

    • throttle string | null Deprecated

      Deprecated in 8.13.0. Use the throttle property in the action frequency object instead. The throttle interval, which defines how often an alert generates repeated actions. NOTE: You cannot specify the throttle interval at both the rule and action level. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.

    • updated_at string Required

      The date and time that the rule was updated most recently.

    • updated_by string | null Required

      The identifier for the user that updated this rule most recently.

    • Relative URL to view rule in the app.

  • Indicates an invalid schema or parameters.

  • Indicates that this call is forbidden.

GET /api/alerting/rules/_find
curl \
 --request GET https://<KIBANA_URL>/api/alerting/rules/_find
Response examples (200)
A response that contains information about an index threshold rule.
{
  "data": [
    {
      "id": "3583a470-74f6-11ed-9801-35303b735aef",
      "name": "my alert",
      "tags": [
        "cpu"
      ],
      "params": {
        "index": [
          "test-index"
        ],
        "aggType": "avg",
        "groupBy": "top",
        "aggField": "sheet.version",
        "termSize": 6,
        "termField": "name.keyword",
        "threshold": [
          1000
        ],
        "timeField": "@timestamp",
        "timeWindowSize": 5,
        "timeWindowUnit": "m",
        "thresholdComparator": ">"
      },
      "actions": [
        {
          "id": "9dca3e00-74f5-11ed-9801-35303b735aef",
          "uuid": "1c7a1280-f28c-4e06-96b2-e4e5f05d1d61",
          "group": "threshold met",
          "params": {
            "level": "info",
            "message": "Rule {{rule.name}} is active for group {{context.group}}:\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}\n- Timestamp: {{context.date}}",
            "connector_type_id": ".server-log"
          },
          "frequency": {
            "summary": false,
            "throttle": null,
            "notify_when": "onActionGroupChange"
          }
        }
      ],
      "enabled": true,
      "consumer": "alerts",
      "last_run": {
        "outcome": "succeeded",
        "warning": null,
        "outcome_msg": null,
        "alerts_count": {
          "new": 0,
          "active": 0,
          "ignored": 0,
          "recovered": 0
        }
      },
      "mute_all": false,
      "next_run": "2022-12-06T01:45:23.912Z",
      "revision": 1,
      "schedule": {
        "interval": "1m"
      },
      "throttle": null,
      "created_at": "2022-12-05T23:40:33.132Z",
      "created_by": "elastic",
      "updated_at": "2022-12-05T23:40:33.132Z",
      "updated_by": "elastic",
      "rule_type_id": ".index-threshold",
      "api_key_owner": "elastic",
      "muted_alert_ids": [],
      "execution_status": {
        "status": "ok",
        "last_duration": 48,
        "last_execution_date": "2022-12-06T01:44:23.983Z"
      },
      "scheduled_task_id": "3583a470-74f6-11ed-9801-35303b735aef",
      "api_key_created_by_user": false
    }
  ],
  "page": 1,
  "total": 1,
  "per_page": 10
}
A response that contains information about a security rule that has conditional actions.
{
  "data": [
    {
      "id": "6107a8f0-f401-11ed-9f8e-399c75a2deeb",
      "name": "security_rule",
      "tags": [],
      "params": {
        "to": "now",
        "from": "now-3660s",
        "meta": {
          "from": "1h",
          "kibana_siem_app_url": "https://localhost:5601/app/security"
        },
        "type": "threshold",
        "index": [
          "kibana_sample_data_logs"
        ],
        "query": "*",
        "author": [],
        "ruleId": "an_internal_rule_id",
        "threat": [],
        "filters": [],
        "license": "",
        "version": 1,
        "language": "kuery",
        "severity": "low",
        "immutable": false,
        "riskScore": 21,
        "threshold": {
          "field": [
            "bytes"
          ],
          "value": 1,
          "cardinality": []
        },
        "maxSignals": 100,
        "references": [],
        "description": "A security threshold rule.",
        "outputIndex": "",
        "exceptionsList": [],
        "falsePositives": [],
        "severityMapping": [],
        "riskScoreMapping": []
      },
      "actions": [
        {
          "id": "49eae970-f401-11ed-9f8e-399c75a2deeb",
          "uuid": "1c7a1280-f28c-4e06-96b2-e4e5f05d1d61",
          "group": "default",
          "params": {
            "documents": [
              {
                "rule_id": {
                  "[object Object]": null
                },
                "alert_id": {
                  "[object Object]": null
                },
                "rule_name": {
                  "[object Object]": null
                },
                "context_message": {
                  "[object Object]": null
                }
              }
            ]
          },
          "frequency": {
            "summary": true,
            "throttle": null,
            "notify_when": "onActiveAlert"
          },
          "alerts_filter": {
            "query": {
              "kql": "",
              "filters": [
                {
                  "meta": {
                    "key": "client.geo.region_iso_code",
                    "alias": null,
                    "field": "client.geo.region_iso_code",
                    "index": "c4bdca79-e69e-4d80-82a1-e5192c621bea",
                    "negate": false,
                    "params": {
                      "type": "phrase",
                      "query": "CA-QC"
                    },
                    "disabled": false
                  },
                  "query": {
                    "match_phrase": {
                      "client.geo.region_iso_code": "CA-QC"
                    }
                  },
                  "$state": {
                    "store": "appState"
                  }
                }
              ]
            },
            "timeframe": {
              "days": [
                7
              ],
              "hours": {
                "end": "17:00",
                "start": "08:00"
              },
              "timezone": "UTC"
            }
          },
          "connector_type_id": ".index"
        }
      ],
      "enabled": true,
      "running": false,
      "consumer": "siem",
      "last_run": {
        "outcome": "succeeded",
        "warning": null,
        "outcome_msg": [
          "Rule execution completed successfully"
        ],
        "alerts_count": {
          "new": 0,
          "active": 0,
          "ignored": 0,
          "recovered": 0
        },
        "outcome_order": 0
      },
      "mute_all": false,
      "next_run": "2023-05-16T20:27:49.507Z",
      "revision": 1,
      "schedule": {
        "interval": "1m"
      },
      "throttle": null,
      "created_at": "2023-05-16T15:50:28.358Z",
      "created_by": "elastic",
      "updated_at": "2023-05-16T20:25:42.559Z",
      "updated_by": "elastic",
      "notify_when": null,
      "rule_type_id": "siem.thresholdRule",
      "api_key_owner": "elastic",
      "muted_alert_ids": [],
      "execution_status": {
        "status": "ok",
        "last_duration": 166,
        "last_execution_date": "2023-05-16T20:26:49.590Z"
      },
      "scheduled_task_id": "6107a8f0-f401-11ed-9f8e-399c75a2deeb",
      "api_key_created_by_user": false
    }
  ],
  "page": 1,
  "total": 1,
  "per_page": 10
}

APM agent configuration

Adjust APM agent configuration without need to redeploy your application.













Get agent name for service Beta

GET /api/apm/settings/agent-configuration/agent_name

Retrieve agentName for a service.

Headers

  • elastic-api-version string Required

    The version of the API to use

    Value is 2023-10-31. Default value is 2023-10-31.

Query parameters

Responses

  • 200 application/json

    Successful response

    Hide response attribute Show response attribute object
  • 400 application/json

    Bad Request response

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

    Unauthorized response

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

    Not found response

    Hide response attributes Show response attributes object
GET /api/apm/settings/agent-configuration/agent_name
curl \
 --request GET https://<KIBANA_URL>/api/apm/settings/agent-configuration/agent_name?serviceName=node \
 --header "elastic-api-version: 2023-10-31"
Response examples (200)
{
  "agentName": "nodejs"
}
Response examples (400)
{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 400
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}
Response examples (404)
{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 404
}
































Get source maps Beta

GET /api/apm/sourcemaps

Returns an array of Fleet artifacts, including source map uploads.

Headers

  • elastic-api-version string Required

    The version of the API to use

    Value is 2023-10-31. Default value is 2023-10-31.

Query parameters

Responses

GET /api/apm/sourcemaps
curl \
 --request GET https://<KIBANA_URL>/api/apm/sourcemaps \
 --header "elastic-api-version: 2023-10-31"
Response examples (200)
{
  "artifacts": [
    {
      "body": {
        "bundleFilepath": "string",
        "serviceName": "string",
        "serviceVersion": "string",
        "sourceMap": {
          "file": "string",
          "mappings": "string",
          "sourceRoot": "string",
          "sources": [
            "string"
          ],
          "sourcesContent": [
            "string"
          ],
          "version": 42.0
        }
      },
      "compressionAlgorithm": "string",
      "created": "string",
      "decodedSha256": "string",
      "decodedSize": 42.0,
      "encodedSha256": "string",
      "encodedSize": 42.0,
      "encryptionAlgorithm": "string",
      "id": "string",
      "identifier": "string",
      "packageName": "string",
      "relative_url": "string",
      "type": "string"
    }
  ]
}
Response examples (400)
{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 400
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}
Response examples (500)
{
  "error": "Internal Server Error",
  "message": "string",
  "statusCode": 500
}
Response examples (501)
{
  "error": "Not Implemented",
  "message": "Not Implemented",
  "statusCode": 501
}

































Get all connectors Beta

GET /api/actions/connectors

Responses

  • 200 application/json

    Indicates a successful call.

GET /api/actions/connectors
curl \
 --request GET https://<KIBANA_URL>/api/actions/connectors
Response examples (200)
[
  {
    "id": "preconfigured-email-connector",
    "name": "my-preconfigured-email-notification",
    "is_deprecated": false,
    "is_preconfigured": true,
    "is_system_action": false,
    "connector_type_id": ".email",
    "referenced_by_count": 0
  },
  {
    "id": "e07d0c80-8b8b-11ed-a780-3b746c987a81",
    "name": "my-index-connector",
    "config": {
      "index": "test-index",
      "refresh": false,
      "executionTimeField": null
    },
    "is_deprecated": false,
    "is_preconfigured": false,
    "is_system_action": false,
    "connector_type_id": ".index",
    "is_missing_secrets": false,
    "referenced_by_count": 2
  }
]







































Get a data view Beta

GET /api/data_views/data_view/{viewId}

Path parameters

  • viewId string Required

    An identifier for the data view.

Responses

  • 200 application/json

    Indicates a successful call.

    Hide response attribute Show response attribute object
    • Additional properties are allowed.

      Hide data_view attributes Show data_view attributes object
      • Allows the data view saved object to exist before the data is available.

      • Hide fieldAttrs attribute Show fieldAttrs attribute object
        • * object Additional properties

          A map of field attributes by field name.

          Additional properties are allowed.

          Hide * attributes Show * attributes object
      • A map of field formats by field name.

        Additional properties are allowed.

      • fields object

        Additional properties are allowed.

      • id string
      • name string

        The data view name.

      • namespaces array[string]

        An array of space identifiers for sharing the data view between multiple spaces.

        Default value is default.

      • Hide runtimeFieldMap attribute Show runtimeFieldMap attribute object
        • * object Additional properties

          A map of runtime field definitions by field name.

          Additional properties are allowed.

          Hide * attributes Show * attributes object
          • script object Required

            Additional properties are allowed.

            Hide script attribute Show script attribute object
            • source string

              Script for the runtime field.

          • type string Required

            Mapping type of the runtime field.

      • sourceFilters array[object]

        The array of field names you want to filter out in Discover.

        Hide sourceFilters attribute Show sourceFilters attribute object
      • The timestamp field name, which you use for time-based data views.

      • title string

        Comma-separated list of data streams, indices, and aliases that you want to search. Supports wildcards (*).

      • typeMeta object | null

        When you use rollup indices, contains the field list for the rollup data view API endpoints.

        Additional properties are allowed.

        Hide typeMeta attributes Show typeMeta attributes object | null
        • aggs object

          A map of rollup restrictions by aggregation type and field name.

          Additional properties are allowed.

        • params object

          Properties for retrieving rollup fields.

          Additional properties are allowed.

      • version string
  • 404 application/json

    Object is not found.

    Hide response attributes Show response attributes object
GET /api/data_views/data_view/{viewId}
curl \
 --request GET https://<KIBANA_URL>/api/data_views/data_view/ff959d40-b880-11e8-a6d9-e546fe2bba5f
Response examples (200)
{
  "data_view": {
    "id": "ff959d40-b880-11e8-a6d9-e546fe2bba5f",
    "name": "Kibana Sample Data eCommerce",
    "title": "kibana_sample_data_ecommerce",
    "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
      },
      "sku": {
        "name": "sku",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "type": {
        "name": "type",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "user": {
        "name": "user",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "email": {
        "name": "email",
        "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
      },
      "_source": {
        "name": "_source",
        "type": "_source",
        "count": 0,
        "format": {
          "id": "_source"
        },
        "esTypes": [
          "_source"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": false,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "category": {
        "name": "category",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "text"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "currency": {
        "name": "currency",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "order_id": {
        "name": "order_id",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "order_date": {
        "name": "order_date",
        "type": "date",
        "count": 0,
        "format": {
          "id": "date"
        },
        "esTypes": [
          "date"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "customer_id": {
        "name": "customer_id",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "day_of_week": {
        "name": "day_of_week",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "manufacturer": {
        "name": "manufacturer",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "text"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "products._id": {
        "name": "products._id",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "text"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "products.sku": {
        "name": "products.sku",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "day_of_week_i": {
        "name": "day_of_week_i",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "integer"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "event.dataset": {
        "name": "event.dataset",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "customer_phone": {
        "name": "customer_phone",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "geoip.location": {
        "name": "geoip.location",
        "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
      },
      "products.price": {
        "name": "products.price",
        "type": "number",
        "count": 1,
        "format": {
          "id": "number",
          "params": {
            "pattern": "$0,0.00"
          }
        },
        "esTypes": [
          "half_float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "total_quantity": {
        "name": "total_quantity",
        "type": "number",
        "count": 1,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "integer"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "customer_gender": {
        "name": "customer_gender",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "geoip.city_name": {
        "name": "geoip.city_name",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "category.keyword": {
        "name": "category.keyword",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "subType": {
          "multi": {
            "parent": "category"
          }
        },
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "geoip.region_name": {
        "name": "geoip.region_name",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.category": {
        "name": "products.category",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "text"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "products.quantity": {
        "name": "products.quantity",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "integer"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "customer_full_name": {
        "name": "customer_full_name",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "text"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "customer_last_name": {
        "name": "customer_last_name",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "text"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "products.min_price": {
        "name": "products.min_price",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number",
          "params": {
            "pattern": "$0,0.00"
          }
        },
        "esTypes": [
          "half_float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "taxful_total_price": {
        "name": "taxful_total_price",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number",
          "params": {
            "pattern": "$0,0.[00]"
          }
        },
        "esTypes": [
          "half_float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "customer_birth_date": {
        "name": "customer_birth_date",
        "type": "date",
        "count": 0,
        "format": {
          "id": "date"
        },
        "esTypes": [
          "date"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "customer_first_name": {
        "name": "customer_first_name",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "text"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "products.base_price": {
        "name": "products.base_price",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number",
          "params": {
            "pattern": "$0,0.00"
          }
        },
        "esTypes": [
          "half_float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.created_on": {
        "name": "products.created_on",
        "type": "date",
        "count": 0,
        "format": {
          "id": "date"
        },
        "esTypes": [
          "date"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.product_id": {
        "name": "products.product_id",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "long"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.tax_amount": {
        "name": "products.tax_amount",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "half_float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "taxless_total_price": {
        "name": "taxless_total_price",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number",
          "params": {
            "pattern": "$0,0.00"
          }
        },
        "esTypes": [
          "half_float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "geoip.continent_name": {
        "name": "geoip.continent_name",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "manufacturer.keyword": {
        "name": "manufacturer.keyword",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "subType": {
          "multi": {
            "parent": "manufacturer"
          }
        },
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products._id.keyword": {
        "name": "products._id.keyword",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "subType": {
          "multi": {
            "parent": "products._id"
          }
        },
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.manufacturer": {
        "name": "products.manufacturer",
        "type": "string",
        "count": 1,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "text"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "products.product_name": {
        "name": "products.product_name",
        "type": "string",
        "count": 1,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "text"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": false,
        "shortDotsEnable": false,
        "readFromDocValues": false
      },
      "products.taxful_price": {
        "name": "products.taxful_price",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number",
          "params": {
            "pattern": "$0,0.00"
          }
        },
        "esTypes": [
          "half_float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "total_unique_products": {
        "name": "total_unique_products",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "integer"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "geoip.country_iso_code": {
        "name": "geoip.country_iso_code",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.taxless_price": {
        "name": "products.taxless_price",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number",
          "params": {
            "pattern": "$0,0.00"
          }
        },
        "esTypes": [
          "half_float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.base_unit_price": {
        "name": "products.base_unit_price",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number",
          "params": {
            "pattern": "$0,0.00"
          }
        },
        "esTypes": [
          "half_float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.discount_amount": {
        "name": "products.discount_amount",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "half_float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.category.keyword": {
        "name": "products.category.keyword",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "subType": {
          "multi": {
            "parent": "products.category"
          }
        },
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "customer_full_name.keyword": {
        "name": "customer_full_name.keyword",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "subType": {
          "multi": {
            "parent": "customer_full_name"
          }
        },
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "customer_last_name.keyword": {
        "name": "customer_last_name.keyword",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "subType": {
          "multi": {
            "parent": "customer_last_name"
          }
        },
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "customer_first_name.keyword": {
        "name": "customer_first_name.keyword",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "subType": {
          "multi": {
            "parent": "customer_first_name"
          }
        },
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.discount_percentage": {
        "name": "products.discount_percentage",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "half_float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.manufacturer.keyword": {
        "name": "products.manufacturer.keyword",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "subType": {
          "multi": {
            "parent": "products.manufacturer"
          }
        },
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.product_name.keyword": {
        "name": "products.product_name.keyword",
        "type": "string",
        "count": 0,
        "format": {
          "id": "string"
        },
        "esTypes": [
          "keyword"
        ],
        "subType": {
          "multi": {
            "parent": "products.product_name"
          }
        },
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      },
      "products.unit_discount_amount": {
        "name": "products.unit_discount_amount",
        "type": "number",
        "count": 0,
        "format": {
          "id": "number"
        },
        "esTypes": [
          "half_float"
        ],
        "isMapped": true,
        "scripted": false,
        "searchable": true,
        "aggregatable": true,
        "shortDotsEnable": false,
        "readFromDocValues": true
      }
    },
    "version": "WzUsMV0=",
    "typeMeta": {},
    "fieldAttrs": {
      "products.price": {
        "count": 1
      },
      "total_quantity": {
        "count": 1
      },
      "products.manufacturer": {
        "count": 1
      },
      "products.product_name": {
        "count": 1
      }
    },
    "namespaces": [
      "default"
    ],
    "allowNoIndex": false,
    "fieldFormats": {
      "products.price": {
        "id": "number",
        "params": {
          "pattern": "$0,0.00"
        }
      },
      "products.min_price": {
        "id": "number",
        "params": {
          "pattern": "$0,0.00"
        }
      },
      "taxful_total_price": {
        "id": "number",
        "params": {
          "pattern": "$0,0.[00]"
        }
      },
      "products.base_price": {
        "id": "number",
        "params": {
          "pattern": "$0,0.00"
        }
      },
      "taxless_total_price": {
        "id": "number",
        "params": {
          "pattern": "$0,0.00"
        }
      },
      "products.taxful_price": {
        "id": "number",
        "params": {
          "pattern": "$0,0.00"
        }
      },
      "products.taxless_price": {
        "id": "number",
        "params": {
          "pattern": "$0,0.00"
        }
      },
      "products.base_unit_price": {
        "id": "number",
        "params": {
          "pattern": "$0,0.00"
        }
      }
    },
    "sourceFilters": [],
    "timeFieldName": "order_date",
    "runtimeFieldMap": {}
  }
}
Response examples (404)
{
  "error": "Not Found",
  "message": "Saved object [index-pattern/caaad6d0-920c-11ed-b36a-874bd1548a00] not found",
  "statusCode": 404
}












































Preview a saved object reference swap Beta

POST /api/data_views/swap_references/_preview

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

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

application/json

Body Required

  • delete boolean

    Deletes referenced saved object if all references are removed.

  • forId string | array[string]

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

  • forType string

    Limit the affected saved objects by type.

  • fromId string Required

    The saved object reference to change.

  • fromType string

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

  • toId string Required

    New saved object reference value to replace the old value.

Responses

  • 200 application/json

    Indicates a successful call.

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

        A saved object identifier.

      • type string

        The saved object type.

POST /api/data_views/swap_references/_preview
curl \
 --request POST https://<KIBANA_URL>/api/data_views/swap_references/_preview \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"toId":"xyz-123","fromId":"abcd-efg"}'
Request example
{
  "toId": "xyz-123",
  "fromId": "abcd-efg"
}
Response examples (200)
{
  "result": [
    {
      "id": "string",
      "type": "string"
    }
  ]
}






















































Create an agent binary download source Beta

POST /api/fleet/agent_download_sources

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

application/json

Body

  • host string(uri) Required
  • id string
  • is_default boolean

    Default value is false.

  • name string Required
  • proxy_id string | null

    The ID of the proxy to use for this download source. See the proxies API for more information.

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • item object Required

      Additional properties are NOT allowed.

      Hide item attributes Show item attributes object
      • host string(uri) Required
      • id string Required
      • is_default boolean

        Default value is false.

      • name string Required
      • proxy_id string | null

        The ID of the proxy to use for this download source. See the proxies API for more information.

  • 400 application/json
    Hide response attributes Show response attributes object
POST /api/fleet/agent_download_sources
curl \
 --request POST https://<KIBANA_URL>/api/fleet/agent_download_sources \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"host":"https://example.com","id":"string","is_default":false,"name":"string","proxy_id":"string"}'
Request examples
# Headers
kbn-xsrf: true

# Payload
{
  "host": "https://example.com",
  "id": "string",
  "is_default": false,
  "name": "string",
  "proxy_id": "string"
}
Response examples (200)
{
  "item": {
    "host": "https://example.com",
    "id": "string",
    "is_default": false,
    "name": "string",
    "proxy_id": "string"
  }
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}





















































Get outputs for agent policies Beta

POST /api/fleet/agent_policies/outputs

Get a list of outputs associated with agent policies.

[Required authorization] Route required privileges: ALL of [fleet-agent-policies-read, fleet-settings-read].

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

application/json

Body

  • ids array[string] Required

    list of package policy ids

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • items array[object] Required
      Hide items attributes Show items attributes object
      • data object Required

        Additional properties are NOT allowed.

        Hide data attributes Show data attributes object
      • monitoring object Required

        Additional properties are NOT allowed.

        Hide monitoring attribute Show monitoring attribute object
        • output object Required

          Additional properties are NOT allowed.

          Hide output attributes Show output attributes object
  • 400 application/json
    Hide response attributes Show response attributes object
POST /api/fleet/agent_policies/outputs
curl \
 --request POST https://<KIBANA_URL>/api/fleet/agent_policies/outputs \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"ids":["string"]}'
Request examples
# Headers
kbn-xsrf: true

# Payload
{
  "ids": [
    "string"
  ]
}
Response examples (200)
{
  "items": [
    {
      "agentPolicyId": "string",
      "data": {
        "integrations": [
          {
            "id": "string",
            "integrationPolicyName": "string",
            "name": "string",
            "pkgName": "string"
          }
        ],
        "output": {
          "id": "string",
          "name": "string"
        }
      },
      "monitoring": {
        "output": {
          "id": "string",
          "name": "string"
        }
      }
    }
  ]
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}





























































Get agent tags Beta

GET /api/fleet/agents/tags

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

Query parameters

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
  • 400 application/json
    Hide response attributes Show response attributes object
GET /api/fleet/agents/tags
curl \
 --request GET https://<KIBANA_URL>/api/fleet/agents/tags
Response examples (200)
{
  "items": [
    "string"
  ]
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}












































Authorize transforms Beta

POST /api/fleet/epm/packages/{pkgName}/{pkgVersion}/transforms/authorize

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

Query parameters

application/json

Body

Responses

POST /api/fleet/epm/packages/{pkgName}/{pkgVersion}/transforms/authorize
curl \
 --request POST https://<KIBANA_URL>/api/fleet/epm/packages/{pkgName}/{pkgVersion}/transforms/authorize \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"transforms":[{"transformId":"string"}]}'
Request examples
# Headers
kbn-xsrf: true

# Payload
{
  "transforms": [
    {
      "transformId": "string"
    }
  ]
}
Response examples (200)
[
  {
    "success": true,
    "transformId": "string"
  }
]
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}










































Check Fleet Server health Beta

POST /api/fleet/health_check

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

application/json

Body

  • id string Required

Responses

POST /api/fleet/health_check
curl \
 --request POST https://<KIBANA_URL>/api/fleet/health_check \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"id":"string"}'
Request examples
# Headers
kbn-xsrf: true

# Payload
{
  "id": "string"
}
Response examples (200)
{
  "host_id": "string",
  "name": "string",
  "status": "string"
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}
Response examples (404)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}





























































Delete a package policy Beta

DELETE /api/fleet/package_policies/{packagePolicyId}

Delete a package policy by ID.

[Required authorization] Route required privileges: ALL of [fleet-agent-policies-all, integrations-all].

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
    • id string Required
  • 400 application/json
    Hide response attributes Show response attributes object
DELETE /api/fleet/package_policies/{packagePolicyId}
curl \
 --request DELETE https://<KIBANA_URL>/api/fleet/package_policies/{packagePolicyId} \
 --header "kbn-xsrf: true"
Response examples (200)
{
  "id": "string"
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}


































Get Fleet Server hosts Beta

GET /api/fleet/fleet_server_hosts

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

Responses

GET /api/fleet/fleet_server_hosts
curl \
 --request GET https://<KIBANA_URL>/api/fleet/fleet_server_hosts
Response examples (200)
{
  "items": [
    {
      "host_urls": [
        "string"
      ],
      "id": "string",
      "is_default": false,
      "is_internal": true,
      "is_preconfigured": false,
      "name": "string",
      "proxy_id": "string"
    }
  ],
  "page": 42.0,
  "perPage": 42.0,
  "total": 42.0
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}








































Roles

Manage the roles that grant Elasticsearch and Kibana privileges.

















Create or update roles Beta

POST /api/security/roles

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

application/json

Body

  • roles object Required
    Hide roles attribute Show roles attribute object
    • * object Additional properties

      Additional properties are NOT allowed.

      Hide * attributes Show * attributes object
      • A description for the role.

        Maximum length is 2048.

      • elasticsearch object Required

        Additional properties are NOT allowed.

        Hide elasticsearch attributes Show elasticsearch attributes object
        • cluster array[string]

          Cluster privileges that define the cluster level actions that users can perform.

        • indices array[object]
          Hide indices attributes Show indices attributes object
          • Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information. If for administrative purposes you need to create a role with privileges covering restricted indices, however, you can set this property to true. In that case, the names field covers the restricted indices too.

          • Hide field_security attribute Show field_security attribute object
            • * array[string] Additional properties

              The document fields that the role members have read access to.

          • names array[string] Required

            The data streams, indices, and aliases to which the permissions in this entry apply. It supports wildcards (*).

            At least 1 element.

          • privileges array[string] Required

            The index level privileges that the role members have for the data streams and indices.

            At least 1 element.

          • query string

            A search query that defines the documents the role members have read access to. A document within the specified data streams and indices must match this query in order for it to be accessible by the role members.

        • remote_cluster array[object]
          Hide remote_cluster attributes Show remote_cluster attributes object
          • clusters array[string] Required

            A list of remote cluster aliases. It supports literal strings as well as wildcards and regular expressions.

            At least 1 element.

          • privileges array[string] Required

            The cluster level privileges for the remote cluster. The allowed values are a subset of the cluster privileges.

            At least 1 element.

        • remote_indices array[object]
          Hide remote_indices attributes Show remote_indices attributes object
          • Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information. If for administrative purposes you need to create a role with privileges covering restricted indices, however, you can set this property to true. In that case, the names field will cover the restricted indices too.

          • clusters array[string] Required

            A list of remote cluster aliases. It supports literal strings as well as wildcards and regular expressions.

            At least 1 element.

          • Hide field_security attribute Show field_security attribute object
            • * array[string] Additional properties

              The document fields that the role members have read access to.

          • names array[string] Required

            A list of remote aliases, data streams, or indices to which the permissions apply. It supports wildcards (*).

            At least 1 element.

          • privileges array[string] Required

            The index level privileges that role members have for the specified indices.

            At least 1 element.

          • query string

            A search query that defines the documents the role members have read access to. A document within the specified data streams and indices must match this query in order for it to be accessible by the role members.

        • run_as array[string]

          A user name that the role member can impersonate.

      • kibana array[object]
        Hide kibana attributes Show kibana attributes object
      • metadata object

        Additional properties are allowed.

Responses

  • Indicates a successful call.

POST /api/security/roles
curl \
 --request POST https://<KIBANA_URL>/api/security/roles \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"roles":{"additionalProperty1":{"description":"string","elasticsearch":{"cluster":["string"],"indices":[{"allow_restricted_indices":true,"field_security":{"additionalProperty1":["string"],"additionalProperty2":["string"]},"names":["string"],"privileges":["string"],"query":"string"}],"remote_cluster":[{"clusters":["string"],"privileges":["string"]}],"remote_indices":[{"allow_restricted_indices":true,"clusters":["string"],"field_security":{"additionalProperty1":["string"],"additionalProperty2":["string"]},"names":["string"],"privileges":["string"],"query":"string"}],"run_as":["string"]},"kibana":[{"base":[],"feature":{"additionalProperty1":["string"],"additionalProperty2":["string"]},"spaces":["*"]}],"metadata":{}},"additionalProperty2":{"description":"string","elasticsearch":{"cluster":["string"],"indices":[{"allow_restricted_indices":true,"field_security":{"additionalProperty1":["string"],"additionalProperty2":["string"]},"names":["string"],"privileges":["string"],"query":"string"}],"remote_cluster":[{"clusters":["string"],"privileges":["string"]}],"remote_indices":[{"allow_restricted_indices":true,"clusters":["string"],"field_security":{"additionalProperty1":["string"],"additionalProperty2":["string"]},"names":["string"],"privileges":["string"],"query":"string"}],"run_as":["string"]},"kibana":[{"base":[],"feature":{"additionalProperty1":["string"],"additionalProperty2":["string"]},"spaces":["*"]}],"metadata":{}}}}'
Request examples
# Headers
kbn-xsrf: true

# Payload
{
  "roles": {
    "additionalProperty1": {
      "description": "string",
      "elasticsearch": {
        "cluster": [
          "string"
        ],
        "indices": [
          {
            "allow_restricted_indices": true,
            "field_security": {
              "additionalProperty1": [
                "string"
              ],
              "additionalProperty2": [
                "string"
              ]
            },
            "names": [
              "string"
            ],
            "privileges": [
              "string"
            ],
            "query": "string"
          }
        ],
        "remote_cluster": [
          {
            "clusters": [
              "string"
            ],
            "privileges": [
              "string"
            ]
          }
        ],
        "remote_indices": [
          {
            "allow_restricted_indices": true,
            "clusters": [
              "string"
            ],
            "field_security": {
              "additionalProperty1": [
                "string"
              ],
              "additionalProperty2": [
                "string"
              ]
            },
            "names": [
              "string"
            ],
            "privileges": [
              "string"
            ],
            "query": "string"
          }
        ],
        "run_as": [
          "string"
        ]
      },
      "kibana": [
        {
          "base": [],
          "feature": {
            "additionalProperty1": [
              "string"
            ],
            "additionalProperty2": [
              "string"
            ]
          },
          "spaces": [
            "*"
          ]
        }
      ],
      "metadata": {}
    },
    "additionalProperty2": {
      "description": "string",
      "elasticsearch": {
        "cluster": [
          "string"
        ],
        "indices": [
          {
            "allow_restricted_indices": true,
            "field_security": {
              "additionalProperty1": [
                "string"
              ],
              "additionalProperty2": [
                "string"
              ]
            },
            "names": [
              "string"
            ],
            "privileges": [
              "string"
            ],
            "query": "string"
          }
        ],
        "remote_cluster": [
          {
            "clusters": [
              "string"
            ],
            "privileges": [
              "string"
            ]
          }
        ],
        "remote_indices": [
          {
            "allow_restricted_indices": true,
            "clusters": [
              "string"
            ],
            "field_security": {
              "additionalProperty1": [
                "string"
              ],
              "additionalProperty2": [
                "string"
              ]
            },
            "names": [
              "string"
            ],
            "privileges": [
              "string"
            ],
            "query": "string"
          }
        ],
        "run_as": [
          "string"
        ]
      },
      "kibana": [
        {
          "base": [],
          "feature": {
            "additionalProperty1": [
              "string"
            ],
            "additionalProperty2": [
              "string"
            ]
          },
          "spaces": [
            "*"
          ]
        }
      ],
      "metadata": {}
    }
  }
}





Import saved objects Beta

POST /api/saved_objects/_import

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

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

  • 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

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

      Additional properties are allowed.

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

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

      Additional properties are allowed.

  • 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"
    }
  ]
}
Response examples (400)
{
  "error": "Bad Request",
  "message": "string",
  "statusCode": 400
}

























Update a conversation Beta

PUT /api/security_ai_assistant/current_user/conversations/{id}

Update an existing conversation using the conversation ID.

Path parameters

  • id string(nonempty) Required

    The conversation's id value.

    Minimum length is 1.

application/json

Body Required

  • LLM API configuration.

    Additional properties are allowed.

    Hide apiConfig attributes Show apiConfig attributes object
  • category string

    The conversation category.

    Values are assistant or insights.

  • excludeFromLastConversationStorage.

  • id string(nonempty) Required

    A string that does not contain only whitespace characters

    Minimum length is 1.

  • messages array[object]

    The conversation messages.

    Hide messages attributes Show messages attributes object
    • content string Required

      Message content.

    • isError boolean

      Is error message.

    • metadata object

      metadata

      Additional properties are allowed.

      Hide metadata attribute Show metadata attribute object
    • reader object

      Message content.

      Additional properties are allowed.

    • role string Required

      Message role.

      Values are system, user, or assistant.

    • timestamp string(nonempty) Required

      A string that does not contain only whitespace characters

      Minimum length is 1.

    • trace Data

      Additional properties are allowed.

      Hide traceData attributes Show traceData attributes object
      • traceId string

        Could be any string, not necessarily a UUID

      • Could be any string, not necessarily a UUID

  • Replacements object used to anonymize/deanomymize messsages

    Hide replacements attribute Show replacements attribute object
    • * string Additional properties
  • summary object

    Additional properties are allowed.

    Hide summary attributes Show summary attributes object
    • How confident you are about this being a correct and useful learning.

      Values are low, medium, or high.

    • content string

      Summary text of the conversation over time.

    • public boolean

      Define if summary is marked as publicly available.

    • timestamp string(nonempty)

      A string that does not contain only whitespace characters

      Minimum length is 1.

  • title string

    The conversation title.

Responses

  • 200 application/json

    Indicates a successful call.

    Hide response attributes Show response attributes object
    • LLM API configuration.

      Additional properties are allowed.

      Hide apiConfig attributes Show apiConfig attributes object
    • category string Required

      The conversation category.

      Values are assistant or insights.

    • createdAt string Required

      The last time conversation was updated.

    • excludeFromLastConversationStorage.

    • id string(nonempty) Required

      A string that does not contain only whitespace characters

      Minimum length is 1.

    • isDefault boolean

      Is default conversation.

    • messages array[object]

      The conversation messages.

      Hide messages attributes Show messages attributes object
      • content string Required

        Message content.

      • isError boolean

        Is error message.

      • metadata object

        metadata

        Additional properties are allowed.

        Hide metadata attribute Show metadata attribute object
      • reader object

        Message content.

        Additional properties are allowed.

      • role string Required

        Message role.

        Values are system, user, or assistant.

      • timestamp string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • trace Data

        Additional properties are allowed.

        Hide traceData attributes Show traceData attributes object
        • traceId string

          Could be any string, not necessarily a UUID

        • Could be any string, not necessarily a UUID

    • namespace string Required

      Kibana space

    • Replacements object used to anonymize/deanomymize messsages

      Hide replacements attribute Show replacements attribute object
      • * string Additional properties
    • summary object

      Additional properties are allowed.

      Hide summary attributes Show summary attributes object
      • How confident you are about this being a correct and useful learning.

        Values are low, medium, or high.

      • content string

        Summary text of the conversation over time.

      • public boolean

        Define if summary is marked as publicly available.

      • timestamp string(nonempty)

        A string that does not contain only whitespace characters

        Minimum length is 1.

    • timestamp string(nonempty)

      A string that does not contain only whitespace characters

      Minimum length is 1.

    • title string Required

      The conversation title.

    • The last time conversation was updated.

    • users array[object] Required
      Hide users attributes Show users attributes object
  • 400 application/json

    Generic Error

    Hide response attributes Show response attributes object
PUT /api/security_ai_assistant/current_user/conversations/{id}
curl \
 --request PUT https://<KIBANA_URL>/api/security_ai_assistant/current_user/conversations/{id} \
 --header "Content-Type: application/json" \
 --data '{"apiConfig":{"actionTypeId":"string","connectorId":"string","defaultSystemPromptId":"string","model":"string","provider":"OpenAI"},"category":"assistant","excludeFromLastConversationStorage":true,"id":"string","messages":[{"content":"string","isError":true,"metadata":{"contentReferences":{}},"reader":{},"role":"system","timestamp":"string","traceData":{"traceId":"string","transactionId":"string"}}],"replacements":{"additionalProperty1":"string","additionalProperty2":"string"},"summary":{"confidence":"low","content":"string","public":true,"timestamp":"string"},"title":"string"}'
Request examples
{
  "apiConfig": {
    "actionTypeId": "string",
    "connectorId": "string",
    "defaultSystemPromptId": "string",
    "model": "string",
    "provider": "OpenAI"
  },
  "category": "assistant",
  "excludeFromLastConversationStorage": true,
  "id": "string",
  "messages": [
    {
      "content": "string",
      "isError": true,
      "metadata": {
        "contentReferences": {}
      },
      "reader": {},
      "role": "system",
      "timestamp": "string",
      "traceData": {
        "traceId": "string",
        "transactionId": "string"
      }
    }
  ],
  "replacements": {
    "additionalProperty1": "string",
    "additionalProperty2": "string"
  },
  "summary": {
    "confidence": "low",
    "content": "string",
    "public": true,
    "timestamp": "string"
  },
  "title": "string"
}
Response examples (200)
{
  "apiConfig": {
    "actionTypeId": "string",
    "connectorId": "string",
    "defaultSystemPromptId": "string",
    "model": "string",
    "provider": "OpenAI"
  },
  "category": "assistant",
  "createdAt": "string",
  "excludeFromLastConversationStorage": true,
  "id": "string",
  "isDefault": true,
  "messages": [
    {
      "content": "string",
      "isError": true,
      "metadata": {
        "contentReferences": {}
      },
      "reader": {},
      "role": "system",
      "timestamp": "string",
      "traceData": {
        "traceId": "string",
        "transactionId": "string"
      }
    }
  ],
  "namespace": "string",
  "replacements": {
    "additionalProperty1": "string",
    "additionalProperty2": "string"
  },
  "summary": {
    "confidence": "low",
    "content": "string",
    "public": true,
    "timestamp": "string"
  },
  "timestamp": "string",
  "title": "string",
  "updatedAt": "string",
  "users": [
    {
      "id": "string",
      "name": "string"
    }
  ]
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}

Delete a conversation Beta

DELETE /api/security_ai_assistant/current_user/conversations/{id}

Delete an existing conversation using the conversation ID.

Path parameters

  • id string(nonempty) Required

    The conversation's id value.

    Minimum length is 1.

Responses

  • 200 application/json

    Indicates a successful call.

    Hide response attributes Show response attributes object
    • LLM API configuration.

      Additional properties are allowed.

      Hide apiConfig attributes Show apiConfig attributes object
    • category string Required

      The conversation category.

      Values are assistant or insights.

    • createdAt string Required

      The last time conversation was updated.

    • excludeFromLastConversationStorage.

    • id string(nonempty) Required

      A string that does not contain only whitespace characters

      Minimum length is 1.

    • isDefault boolean

      Is default conversation.

    • messages array[object]

      The conversation messages.

      Hide messages attributes Show messages attributes object
      • content string Required

        Message content.

      • isError boolean

        Is error message.

      • metadata object

        metadata

        Additional properties are allowed.

        Hide metadata attribute Show metadata attribute object
      • reader object

        Message content.

        Additional properties are allowed.

      • role string Required

        Message role.

        Values are system, user, or assistant.

      • timestamp string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • trace Data

        Additional properties are allowed.

        Hide traceData attributes Show traceData attributes object
        • traceId string

          Could be any string, not necessarily a UUID

        • Could be any string, not necessarily a UUID

    • namespace string Required

      Kibana space

    • Replacements object used to anonymize/deanomymize messsages

      Hide replacements attribute Show replacements attribute object
      • * string Additional properties
    • summary object

      Additional properties are allowed.

      Hide summary attributes Show summary attributes object
      • How confident you are about this being a correct and useful learning.

        Values are low, medium, or high.

      • content string

        Summary text of the conversation over time.

      • public boolean

        Define if summary is marked as publicly available.

      • timestamp string(nonempty)

        A string that does not contain only whitespace characters

        Minimum length is 1.

    • timestamp string(nonempty)

      A string that does not contain only whitespace characters

      Minimum length is 1.

    • title string Required

      The conversation title.

    • The last time conversation was updated.

    • users array[object] Required
      Hide users attributes Show users attributes object
  • 400 application/json

    Generic Error

    Hide response attributes Show response attributes object
DELETE /api/security_ai_assistant/current_user/conversations/{id}
curl \
 --request DELETE https://<KIBANA_URL>/api/security_ai_assistant/current_user/conversations/{id}
Response examples (200)
{
  "apiConfig": {
    "actionTypeId": "string",
    "connectorId": "string",
    "defaultSystemPromptId": "string",
    "model": "string",
    "provider": "OpenAI"
  },
  "category": "assistant",
  "createdAt": "string",
  "excludeFromLastConversationStorage": true,
  "id": "string",
  "isDefault": true,
  "messages": [
    {
      "content": "string",
      "isError": true,
      "metadata": {
        "contentReferences": {}
      },
      "reader": {},
      "role": "system",
      "timestamp": "string",
      "traceData": {
        "traceId": "string",
        "transactionId": "string"
      }
    }
  ],
  "namespace": "string",
  "replacements": {
    "additionalProperty1": "string",
    "additionalProperty2": "string"
  },
  "summary": {
    "confidence": "low",
    "content": "string",
    "public": true,
    "timestamp": "string"
  },
  "timestamp": "string",
  "title": "string",
  "updatedAt": "string",
  "users": [
    {
      "id": "string",
      "name": "string"
    }
  ]
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}

































































Apply a bulk action to detection rules Beta

POST /api/detection_engine/rules/_bulk_action

Apply a bulk action, such as bulk edit, duplicate, or delete, to multiple detection rules. The bulk action is applied to all rules that match the query or to the rules listed by their IDs.

Query parameters

  • dry_run boolean

    Enables dry run mode for the request call.

application/json

Body object

One of:
  • action string Required

    Value is delete.

  • ids array[string]

    Array of rule IDs

    At least 1 element.

  • query string

    Query to filter rules

Responses

  • 200 application/json

    OK

    One of:
    Hide attributes Show attributes
    • attributes object Required

      Additional properties are allowed.

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

          Values are IMMUTABLE, PREBUILT_CUSTOMIZATION_LICENSE, MACHINE_LEARNING_AUTH, MACHINE_LEARNING_INDEX_PATTERN, ESQL_INDEX_PATTERN, MANUAL_RULE_RUN_FEATURE, or MANUAL_RULE_RUN_DISABLED_RULE.

        • message string Required
        • rules array[object] Required
          Hide rules attributes Show rules attributes object
        • status_code integer Required
      • results object Required

        Additional properties are allowed.

        Hide results attributes Show results attributes object
        • created array[object] Required
          Any of:
          Hide attributes Show attributes
          • actions array[object] Required
            Hide actions attributes Show actions attributes object
            • action_type_id string Required

              The action type used for sending notifications.

            • Additional properties are allowed.

            • The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).

              Additional properties are allowed.

              Hide frequency attributes Show frequency attributes object
              • notifyWhen string Required

                The condition for throttling the notification: onActionGroupChange, onActiveAlert, or onThrottleInterval

                Values are onActiveAlert, onThrottleInterval, or onActionGroupChange.

              • summary boolean Required

                Action summary indicates whether we will send a summary notification about all the generate alerts or notification per individual alert

              • throttle string | null Required

                Defines how often rule actions are taken.

                One of:

                Values are no_actions or rule.

            • group string

              Optionally groups actions by use cases. Use default for alert notifications.

            • id string Required

              The connector ID.

            • params object Required

              Object containing the allowed connector fields, which varies according to the connector type.

              Additional properties are allowed.

            • uuid string(nonempty)

              A string that does not contain only whitespace characters

              Minimum length is 1.

          • Values are savedObjectConversion or savedObjectImport.

          • author array[string] Required
          • Determines if the rule acts as a building block. By default, building-block alerts are not displayed in the UI. These rules are used as a foundation for other rules that do generate alerts. Its value must be default.

          • description string Required

            Minimum length is 1.

          • enabled boolean Required

            Determines whether the rule is enabled.

          • exceptions_list array[object] Required
            Hide exceptions_list attributes Show exceptions_list attributes object
            • id string(nonempty) Required

              A string that does not contain only whitespace characters

              Minimum length is 1.

            • list_id string(nonempty) Required

              A string that does not contain only whitespace characters

              Minimum length is 1.

            • namespace_type string Required

              Determines the exceptions validity in rule's Kibana space

              Values are agnostic or single.

            • type string Required

              The exception type

              Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

          • false_positives array[string] Required
          • from string(date-math) Required

            Time from which data is analyzed each time the rule runs, using a date math range. For example, now-4200s means the rule analyzes data from 70 minutes before its start time. Defaults to now-6m (analyzes data from 6 minutes before the start time).

          • interval string Required

            Frequency of rule execution, using a date math range. For example, "1h" means the rule runs every hour. Defaults to 5m (5 minutes).

          • Schema for fields relating to investigation fields. These are user defined fields we use to highlight in various features in the UI such as alert details flyout and exceptions auto-population from alert. Added in PR #163235 Right now we only have a single field but anticipate adding more related fields to store various configuration states such as override - where a user might say if they want only these fields to display, or if they want these fields + the fields we select. When expanding this field, it may look something like:

            const investigationFields = z.object({
              field_names: NonEmptyArray(NonEmptyString),
              override: z.boolean().optional(),
            });
            

            Additional properties are allowed.

            Hide investigation_fields attribute Show investigation_fields attribute object
            • field_names array[string(nonempty)] Required

              A string that does not contain only whitespace characters

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

          • license string

            The rule's license.

          • max_signals integer Required

            Minimum value is 1.

          • meta object

            Additional properties are allowed.

          • name string Required

            Minimum length is 1.

          • Has no effect.

          • note string

            Notes to help investigate alerts produced by the rule.

          • outcome string

            Values are exactMatch, aliasMatch, or conflict.

          • output_index string Deprecated

            (deprecated) Has no effect.

          • references array[string] Required
          • required_fields array[object] Required
            Hide required_fields attributes Show required_fields attributes object
            • ecs boolean Required

              Whether the field is an ECS field

            • name string(nonempty) Required

              A string that does not contain only whitespace characters

              Minimum length is 1.

            • type string(nonempty) Required

              A string that does not contain only whitespace characters

              Minimum length is 1.

          • response_actions array[object]
            One of:
            Hide attributes Show attributes
          • risk_score integer Required

            Risk score (0 to 100)

            Minimum value is 0, maximum value is 100.

          • risk_score_mapping array[object] Required

            Overrides generated alerts' risk_score with a value from the source event

            Hide risk_score_mapping attributes Show risk_score_mapping attributes object
          • Sets the source field for the alert's signal.rule.name value

          • setup string Required
          • severity string Required

            Severity of the rule

            Values are low, medium, high, or critical.

          • severity_mapping array[object] Required

            Overrides generated alerts' severity with values from the source event

            Hide severity_mapping attributes Show severity_mapping attributes object
            • field string Required
            • operator string Required

              Value is equals.

            • severity string Required

              Severity of the rule

              Values are low, medium, high, or critical.

            • value string Required
          • tags array[string] Required

            String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

          • threat array[object] Required
            Hide threat attributes Show threat attributes object
            • framework string Required

              Relevant attack framework

            • tactic object Required

              Additional properties are allowed.

              Hide tactic attributes Show tactic attributes object
              • id string Required

                Tactic ID

              • name string Required

                Tactic name

              • reference string Required

                Tactic reference

            • technique array[object]

              Array containing information on the attack techniques (optional)

              Hide technique attributes Show technique attributes object
              • id string Required

                Technique ID

              • name string Required

                Technique name

              • reference string Required

                Technique reference

              • subtechnique array[object]

                Array containing more specific information on the attack technique

                Hide subtechnique attributes Show subtechnique attributes object
                • id string Required

                  Subtechnique ID

                • name string Required

                  Subtechnique name

                • reference string Required

                  Subtechnique reference

          • throttle string | null

            Defines how often rule actions are taken.

            One of:

            Values are no_actions or rule.

          • Timeline template ID

          • Timeline template title

          • Sets the time field used to query indices

          • Disables the fallback to the event's @timestamp field

          • to string Required
          • version integer Required

            The rule's version number.

            Minimum value is 1.

          • created_at string(date-time) Required
          • created_by string Required
          • Additional properties are allowed.

            Hide execution_summary attribute Show execution_summary attribute object
            • last_execution object Required

              Additional properties are allowed.

              Hide last_execution attributes Show last_execution attributes object
              • date string(date-time) Required

                Date of the last execution

              • message string Required
              • metrics object Required

                Additional properties are allowed.

                Hide metrics attributes Show metrics attributes object
                • Duration in seconds of execution gap

                  Minimum value is 0.

                • Range of the execution gap

                  Additional properties are allowed.

                  Hide gap_range attributes Show gap_range attributes object
                  • gte string Required

                    Start date of the execution gap

                  • lte string Required

                    End date of the execution gap

                • Total time spent enriching documents during current rule execution cycle

                  Minimum value is 0.

                • Total time spent indexing documents during current rule execution cycle

                  Minimum value is 0.

                • Total time spent performing ES searches as measured by Kibana; includes network latency and time spent serializing/deserializing request/response

                  Minimum value is 0.

              • status string Required

                Status of the last execution

                Values are going to run, running, partial failure, failed, or succeeded.

              • status_order integer Required
          • id string(uuid) Required

            A universally unique identifier

          • immutable boolean Required Deprecated

            This field determines whether the rule is a prebuilt Elastic rule. It will be replaced with the rule_source field.

          • revision integer Required

            Minimum value is 0.

          • rule_id string Required

            Could be any string, not necessarily a UUID

          • rule_source object Required

            Discriminated union that determines whether the rule is internally sourced (created within the Kibana app) or has an external source, such as the Elastic Prebuilt rules repo.

            One of:

            Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

            Hide attributes Show attributes
            • is_customized boolean Required

              Determines whether an external/prebuilt rule has been customized by the user (i.e. any of its fields have been modified and diverged from the base value).

            • type string Required Discriminator

              Value is external.

          • updated_at string(date-time) Required
          • updated_by string Required
          • language string Required

            Query language to use

            Value is eql.

          • query string Required

            EQL query to execute

          • type string Required Discriminator

            Rule type

            Value is eql.

          • Additional properties are allowed.

            Hide alert_suppression attributes Show alert_suppression attributes object
            • duration object

              Additional properties are allowed.

              Hide duration attributes Show duration attributes object
              • unit string Required

                Values are s, m, or h.

              • value integer Required

                Minimum value is 1.

            • group_by array[string] Required

              At least 1 but not more than 3 elements.

            • Describes how alerts will be generated for documents with missing suppress by fields: doNotSuppress - per each document a separate alert will be created suppress - only alert will be created per suppress by bucket

              Values are doNotSuppress or suppress.

          • filters array
          • index array[string]
          • Sets a secondary field for sorting events

          • Contains the event timestamp used for sorting a sequence of events

        • deleted array[object] Required
          Any of:
          Hide attributes Show attributes
          • actions array[object] Required
            Hide actions attributes Show actions attributes object
            • action_type_id string Required

              The action type used for sending notifications.

            • Additional properties are allowed.

            • The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).

              Additional properties are allowed.

              Hide frequency attributes Show frequency attributes object
              • notifyWhen string Required

                The condition for throttling the notification: onActionGroupChange, onActiveAlert, or onThrottleInterval

                Values are onActiveAlert, onThrottleInterval, or onActionGroupChange.

              • summary boolean Required

                Action summary indicates whether we will send a summary notification about all the generate alerts or notification per individual alert

              • throttle string | null Required

                Defines how often rule actions are taken.

                One of:

                Values are no_actions or rule.

            • group string

              Optionally groups actions by use cases. Use default for alert notifications.

            • id string Required

              The connector ID.

            • params object Required

              Object containing the allowed connector fields, which varies according to the connector type.

              Additional properties are allowed.

            • uuid string(nonempty)

              A string that does not contain only whitespace characters

              Minimum length is 1.

          • Values are savedObjectConversion or savedObjectImport.

          • author array[string] Required
          • Determines if the rule acts as a building block. By default, building-block alerts are not displayed in the UI. These rules are used as a foundation for other rules that do generate alerts. Its value must be default.

          • description string Required

            Minimum length is 1.

          • enabled boolean Required

            Determines whether the rule is enabled.

          • exceptions_list array[object] Required
            Hide exceptions_list attributes Show exceptions_list attributes object
            • id string(nonempty) Required

              A string that does not contain only whitespace characters

              Minimum length is 1.

            • list_id string(nonempty) Required

              A string that does not contain only whitespace characters

              Minimum length is 1.

            • namespace_type string Required

              Determines the exceptions validity in rule's Kibana space

              Values are agnostic or single.

            • type string Required

              The exception type

              Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

          • false_positives array[string] Required
          • from string(date-math) Required

            Time from which data is analyzed each time the rule runs, using a date math range. For example, now-4200s means the rule analyzes data from 70 minutes before its start time. Defaults to now-6m (analyzes data from 6 minutes before the start time).

          • interval string Required

            Frequency of rule execution, using a date math range. For example, "1h" means the rule runs every hour. Defaults to 5m (5 minutes).

          • Schema for fields relating to investigation fields. These are user defined fields we use to highlight in various features in the UI such as alert details flyout and exceptions auto-population from alert. Added in PR #163235 Right now we only have a single field but anticipate adding more related fields to store various configuration states such as override - where a user might say if they want only these fields to display, or if they want these fields + the fields we select. When expanding this field, it may look something like:

            const investigationFields = z.object({
              field_names: NonEmptyArray(NonEmptyString),
              override: z.boolean().optional(),
            });
            

            Additional properties are allowed.

            Hide investigation_fields attribute Show investigation_fields attribute object
            • field_names array[string(nonempty)] Required

              A string that does not contain only whitespace characters

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

          • license string

            The rule's license.

          • max_signals integer Required

            Minimum value is 1.

          • meta object

            Additional properties are allowed.

          • name string Required

            Minimum length is 1.

          • Has no effect.

          • note string

            Notes to help investigate alerts produced by the rule.

          • outcome string

            Values are exactMatch, aliasMatch, or conflict.

          • output_index string Deprecated

            (deprecated) Has no effect.

          • references array[string] Required
          • required_fields array[object] Required
            Hide required_fields attributes Show required_fields attributes object
            • ecs boolean Required

              Whether the field is an ECS field

            • name string(nonempty) Required

              A string that does not contain only whitespace characters

              Minimum length is 1.

            • type string(nonempty) Required

              A string that does not contain only whitespace characters

              Minimum length is 1.

          • response_actions array[object]
            One of:
            Hide attributes Show attributes
          • risk_score integer Required

            Risk score (0 to 100)

            Minimum value is 0, maximum value is 100.

          • risk_score_mapping array[object] Required

            Overrides generated alerts' risk_score with a value from the source event

            Hide risk_score_mapping attributes Show risk_score_mapping attributes object
          • Sets the source field for the alert's signal.rule.name value

          • setup string Required
          • severity string Required

            Severity of the rule

            Values are low, medium, high, or critical.

          • severity_mapping array[object] Required

            Overrides generated alerts' severity with values from the source event

            Hide severity_mapping attributes Show severity_mapping attributes object
            • field string Required
            • operator string Required

              Value is equals.

            • severity string Required

              Severity of the rule

              Values are low, medium, high, or critical.

            • value string Required
          • tags array[string] Required

            String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

          • threat array[object] Required
            Hide threat attributes Show threat attributes object
            • framework string Required

              Relevant attack framework

            • tactic object Required

              Additional properties are allowed.

              Hide tactic attributes Show tactic attributes object
              • id string Required

                Tactic ID

              • name string Required

                Tactic name

              • reference string Required

                Tactic reference

            • technique array[object]

              Array containing information on the attack techniques (optional)

              Hide technique attributes Show technique attributes object
              • id string Required

                Technique ID

              • name string Required

                Technique name

              • reference string Required

                Technique reference

              • subtechnique array[object]

                Array containing more specific information on the attack technique

                Hide subtechnique attributes Show subtechnique attributes object
                • id string Required

                  Subtechnique ID

                • name string Required

                  Subtechnique name

                • reference string Required

                  Subtechnique reference

          • throttle string | null

            Defines how often rule actions are taken.

            One of:

            Values are no_actions or rule.

          • Timeline template ID

          • Timeline template title

          • Sets the time field used to query indices

          • Disables the fallback to the event's @timestamp field

          • to string Required
          • version integer Required

            The rule's version number.

            Minimum value is 1.

          • created_at string(date-time) Required
          • created_by string Required
          • Additional properties are allowed.

            Hide execution_summary attribute Show execution_summary attribute object
            • last_execution object Required

              Additional properties are allowed.

              Hide last_execution attributes Show last_execution attributes object
              • date string(date-time) Required

                Date of the last execution

              • message string Required
              • metrics object Required

                Additional properties are allowed.

                Hide metrics attributes Show metrics attributes object
                • Duration in seconds of execution gap

                  Minimum value is 0.

                • Range of the execution gap

                  Additional properties are allowed.

                  Hide gap_range attributes Show gap_range attributes object
                  • gte string Required

                    Start date of the execution gap

                  • lte string Required

                    End date of the execution gap

                • Total time spent enriching documents during current rule execution cycle

                  Minimum value is 0.

                • Total time spent indexing documents during current rule execution cycle

                  Minimum value is 0.

                • Total time spent performing ES searches as measured by Kibana; includes network latency and time spent serializing/deserializing request/response

                  Minimum value is 0.

              • status string Required

                Status of the last execution

                Values are going to run, running, partial failure, failed, or succeeded.

              • status_order integer Required
          • id string(uuid) Required

            A universally unique identifier

          • immutable boolean Required Deprecated

            This field determines whether the rule is a prebuilt Elastic rule. It will be replaced with the rule_source field.

          • revision integer Required

            Minimum value is 0.

          • rule_id string Required

            Could be any string, not necessarily a UUID

          • rule_source object Required

            Discriminated union that determines whether the rule is internally sourced (created within the Kibana app) or has an external source, such as the Elastic Prebuilt rules repo.

            One of:

            Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

            Hide attributes Show attributes
            • is_customized boolean Required

              Determines whether an external/prebuilt rule has been customized by the user (i.e. any of its fields have been modified and diverged from the base value).

            • type string Required Discriminator

              Value is external.

          • updated_at string(date-time) Required
          • updated_by string Required
          • language string Required

            Query language to use

            Value is eql.

          • query string Required

            EQL query to execute

          • type string Required Discriminator

            Rule type

            Value is eql.

          • Additional properties are allowed.

            Hide alert_suppression attributes Show alert_suppression attributes object
            • duration object

              Additional properties are allowed.

              Hide duration attributes Show duration attributes object
              • unit string Required

                Values are s, m, or h.

              • value integer Required

                Minimum value is 1.

            • group_by array[string] Required

              At least 1 but not more than 3 elements.

            • Describes how alerts will be generated for documents with missing suppress by fields: doNotSuppress - per each document a separate alert will be created suppress - only alert will be created per suppress by bucket

              Values are doNotSuppress or suppress.

          • filters array
          • index array[string]
          • Sets a secondary field for sorting events

          • Contains the event timestamp used for sorting a sequence of events

        • skipped array[object] Required
          Hide skipped attributes Show skipped attributes object
        • updated array[object] Required
          Any of:
          Hide attributes Show attributes
          • actions array[object] Required
            Hide actions attributes Show actions attributes object
            • action_type_id string Required

              The action type used for sending notifications.

            • Additional properties are allowed.

            • The action frequency defines when the action runs (for example, only on rule execution or at specific time intervals).

              Additional properties are allowed.

              Hide frequency attributes Show frequency attributes object
              • notifyWhen string Required

                The condition for throttling the notification: onActionGroupChange, onActiveAlert, or onThrottleInterval

                Values are onActiveAlert, onThrottleInterval, or onActionGroupChange.

              • summary boolean Required

                Action summary indicates whether we will send a summary notification about all the generate alerts or notification per individual alert

              • throttle string | null Required

                Defines how often rule actions are taken.

                One of:

                Values are no_actions or rule.

            • group string

              Optionally groups actions by use cases. Use default for alert notifications.

            • id string Required

              The connector ID.

            • params object Required

              Object containing the allowed connector fields, which varies according to the connector type.

              Additional properties are allowed.

            • uuid string(nonempty)

              A string that does not contain only whitespace characters

              Minimum length is 1.

          • Values are savedObjectConversion or savedObjectImport.

          • author array[string] Required
          • Determines if the rule acts as a building block. By default, building-block alerts are not displayed in the UI. These rules are used as a foundation for other rules that do generate alerts. Its value must be default.

          • description string Required

            Minimum length is 1.

          • enabled boolean Required

            Determines whether the rule is enabled.

          • exceptions_list array[object] Required
            Hide exceptions_list attributes Show exceptions_list attributes object
            • id string(nonempty) Required

              A string that does not contain only whitespace characters

              Minimum length is 1.

            • list_id string(nonempty) Required

              A string that does not contain only whitespace characters

              Minimum length is 1.

            • namespace_type string Required

              Determines the exceptions validity in rule's Kibana space

              Values are agnostic or single.

            • type string Required

              The exception type

              Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

          • false_positives array[string] Required
          • from string(date-math) Required

            Time from which data is analyzed each time the rule runs, using a date math range. For example, now-4200s means the rule analyzes data from 70 minutes before its start time. Defaults to now-6m (analyzes data from 6 minutes before the start time).

          • interval string Required

            Frequency of rule execution, using a date math range. For example, "1h" means the rule runs every hour. Defaults to 5m (5 minutes).

          • Schema for fields relating to investigation fields. These are user defined fields we use to highlight in various features in the UI such as alert details flyout and exceptions auto-population from alert. Added in PR #163235 Right now we only have a single field but anticipate adding more related fields to store various configuration states such as override - where a user might say if they want only these fields to display, or if they want these fields + the fields we select. When expanding this field, it may look something like:

            const investigationFields = z.object({
              field_names: NonEmptyArray(NonEmptyString),
              override: z.boolean().optional(),
            });
            

            Additional properties are allowed.

            Hide investigation_fields attribute Show investigation_fields attribute object
            • field_names array[string(nonempty)] Required

              A string that does not contain only whitespace characters

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

          • license string

            The rule's license.

          • max_signals integer Required

            Minimum value is 1.

          • meta object

            Additional properties are allowed.

          • name string Required

            Minimum length is 1.

          • Has no effect.

          • note string

            Notes to help investigate alerts produced by the rule.

          • outcome string

            Values are exactMatch, aliasMatch, or conflict.

          • output_index string Deprecated

            (deprecated) Has no effect.

          • references array[string] Required
          • required_fields array[object] Required
            Hide required_fields attributes Show required_fields attributes object
            • ecs boolean Required

              Whether the field is an ECS field

            • name string(nonempty) Required

              A string that does not contain only whitespace characters

              Minimum length is 1.

            • type string(nonempty) Required

              A string that does not contain only whitespace characters

              Minimum length is 1.

          • response_actions array[object]
            One of:
            Hide attributes Show attributes
          • risk_score integer Required

            Risk score (0 to 100)

            Minimum value is 0, maximum value is 100.

          • risk_score_mapping array[object] Required

            Overrides generated alerts' risk_score with a value from the source event

            Hide risk_score_mapping attributes Show risk_score_mapping attributes object
          • Sets the source field for the alert's signal.rule.name value

          • setup string Required
          • severity string Required

            Severity of the rule

            Values are low, medium, high, or critical.

          • severity_mapping array[object] Required

            Overrides generated alerts' severity with values from the source event

            Hide severity_mapping attributes Show severity_mapping attributes object
            • field string Required
            • operator string Required

              Value is equals.

            • severity string Required

              Severity of the rule

              Values are low, medium, high, or critical.

            • value string Required
          • tags array[string] Required

            String array containing words and phrases to help categorize, filter, and search rules. Defaults to an empty array.

          • threat array[object] Required
            Hide threat attributes Show threat attributes object
            • framework string Required

              Relevant attack framework

            • tactic object Required

              Additional properties are allowed.

              Hide tactic attributes Show tactic attributes object
              • id string Required

                Tactic ID

              • name string Required

                Tactic name

              • reference string Required

                Tactic reference

            • technique array[object]

              Array containing information on the attack techniques (optional)

              Hide technique attributes Show technique attributes object
              • id string Required

                Technique ID

              • name string Required

                Technique name

              • reference string Required

                Technique reference

              • subtechnique array[object]

                Array containing more specific information on the attack technique

                Hide subtechnique attributes Show subtechnique attributes object
                • id string Required

                  Subtechnique ID

                • name string Required

                  Subtechnique name

                • reference string Required

                  Subtechnique reference

          • throttle string | null

            Defines how often rule actions are taken.

            One of:

            Values are no_actions or rule.

          • Timeline template ID

          • Timeline template title

          • Sets the time field used to query indices

          • Disables the fallback to the event's @timestamp field

          • to string Required
          • version integer Required

            The rule's version number.

            Minimum value is 1.

          • created_at string(date-time) Required
          • created_by string Required
          • Additional properties are allowed.

            Hide execution_summary attribute Show execution_summary attribute object
            • last_execution object Required

              Additional properties are allowed.

              Hide last_execution attributes Show last_execution attributes object
              • date string(date-time) Required

                Date of the last execution

              • message string Required
              • metrics object Required

                Additional properties are allowed.

                Hide metrics attributes Show metrics attributes object
                • Duration in seconds of execution gap

                  Minimum value is 0.

                • Range of the execution gap

                  Additional properties are allowed.

                  Hide gap_range attributes Show gap_range attributes object
                  • gte string Required

                    Start date of the execution gap

                  • lte string Required

                    End date of the execution gap

                • Total time spent enriching documents during current rule execution cycle

                  Minimum value is 0.

                • Total time spent indexing documents during current rule execution cycle

                  Minimum value is 0.

                • Total time spent performing ES searches as measured by Kibana; includes network latency and time spent serializing/deserializing request/response

                  Minimum value is 0.

              • status string Required

                Status of the last execution

                Values are going to run, running, partial failure, failed, or succeeded.

              • status_order integer Required
          • id string(uuid) Required

            A universally unique identifier

          • immutable boolean Required Deprecated

            This field determines whether the rule is a prebuilt Elastic rule. It will be replaced with the rule_source field.

          • revision integer Required

            Minimum value is 0.

          • rule_id string Required

            Could be any string, not necessarily a UUID

          • rule_source object Required

            Discriminated union that determines whether the rule is internally sourced (created within the Kibana app) or has an external source, such as the Elastic Prebuilt rules repo.

            One of:

            Type of rule source for externally sourced rules, i.e. rules that have an external source, such as the Elastic Prebuilt rules repo.

            Hide attributes Show attributes
            • is_customized boolean Required

              Determines whether an external/prebuilt rule has been customized by the user (i.e. any of its fields have been modified and diverged from the base value).

            • type string Required Discriminator

              Value is external.

          • updated_at string(date-time) Required
          • updated_by string Required
          • language string Required

            Query language to use

            Value is eql.

          • query string Required

            EQL query to execute

          • type string Required Discriminator

            Rule type

            Value is eql.

          • Additional properties are allowed.

            Hide alert_suppression attributes Show alert_suppression attributes object
            • duration object

              Additional properties are allowed.

              Hide duration attributes Show duration attributes object
              • unit string Required

                Values are s, m, or h.

              • value integer Required

                Minimum value is 1.

            • group_by array[string] Required

              At least 1 but not more than 3 elements.

            • Describes how alerts will be generated for documents with missing suppress by fields: doNotSuppress - per each document a separate alert will be created suppress - only alert will be created per suppress by bucket

              Values are doNotSuppress or suppress.

          • filters array
          • index array[string]
          • Sets a secondary field for sorting events

          • Contains the event timestamp used for sorting a sequence of events

      • summary object Required

        Additional properties are allowed.

        Hide summary attributes Show summary attributes object
    • message string
    • success boolean
POST /api/detection_engine/rules/_bulk_action
curl \
 --request POST https://<KIBANA_URL>/api/detection_engine/rules/_bulk_action \
 --header "Content-Type: application/json" \
 --data '{"action":"delete","ids":["string"],"query":"string"}'
{
  "action": "delete",
  "ids": [
    "string"
  ],
  "query": "string"
}
{
  "action": "disable",
  "ids": [
    "string"
  ],
  "query": "string"
}
{
  "action": "enable",
  "ids": [
    "string"
  ],
  "query": "string"
}
{
  "action": "export",
  "ids": [
    "string"
  ],
  "query": "string"
}
{
  "action": "duplicate",
  "duplicate": {
    "include_exceptions": true,
    "include_expired_exceptions": true
  },
  "ids": [
    "string"
  ],
  "query": "string"
}
{
  "action": "run",
  "ids": [
    "string"
  ],
  "query": "string",
  "run": {
    "end_date": "string",
    "start_date": "string"
  }
}
{
  "action": "edit",
  "edit": [
    {
      "type": "add_tags",
      "value": [
        "string"
      ]
    }
  ],
  "ids": [
    "string"
  ],
  "query": "string"
}
Response examples (200)
{
  "attributes": {
    "errors": [
      {
        "err_code": "IMMUTABLE",
        "message": "string",
        "rules": [
          {
            "id": "string",
            "name": "string"
          }
        ],
        "status_code": 42
      }
    ],
    "results": {
      "created": [
        {
          "actions": [
            {
              "action_type_id": "string",
              "alerts_filter": {},
              "frequency": {
                "notifyWhen": "onActiveAlert",
                "summary": true,
                "throttle": "no_actions"
              },
              "group": "string",
              "id": "string",
              "params": {},
              "uuid": "string"
            }
          ],
          "alias_purpose": "savedObjectConversion",
          "alias_target_id": "string",
          "author": [
            "string"
          ],
          "building_block_type": "string",
          "description": "string",
          "enabled": true,
          "exceptions_list": [
            {
              "id": "string",
              "list_id": "string",
              "namespace_type": "agnostic",
              "type": "detection"
            }
          ],
          "false_positives": [
            "string"
          ],
          "from": "string",
          "interval": "string",
          "investigation_fields": {
            "field_names": [
              "string"
            ]
          },
          "license": "string",
          "max_signals": 42,
          "meta": {},
          "name": "string",
          "namespace": "string",
          "note": "string",
          "outcome": "exactMatch",
          "output_index": "string",
          "references": [
            "string"
          ],
          "related_integrations": [
            {
              "integration": "string",
              "package": "string",
              "version": "string"
            }
          ],
          "required_fields": [
            {
              "ecs": true,
              "name": "string",
              "type": "string"
            }
          ],
          "response_actions": [
            {
              "action_type_id": ".osquery",
              "params": {
                "ecs_mapping": {
                  "additionalProperty1": {
                    "field": "string",
                    "value": "string"
                  },
                  "additionalProperty2": {
                    "field": "string",
                    "value": "string"
                  }
                },
                "pack_id": "string",
                "queries": [
                  {
                    "ecs_mapping": {
                      "additionalProperty1": {
                        "field": "string",
                        "value": "string"
                      },
                      "additionalProperty2": {
                        "field": "string",
                        "value": "string"
                      }
                    },
                    "id": "string",
                    "platform": "string",
                    "query": "string",
                    "removed": true,
                    "snapshot": true,
                    "version": "string"
                  }
                ],
                "query": "string",
                "saved_query_id": "string",
                "timeout": 42.0
              }
            }
          ],
          "risk_score": 42,
          "risk_score_mapping": [
            {
              "field": "string",
              "operator": "equals",
              "risk_score": 42,
              "value": "string"
            }
          ],
          "rule_name_override": "string",
          "setup": "string",
          "severity": "low",
          "severity_mapping": [
            {
              "field": "string",
              "operator": "equals",
              "severity": "low",
              "value": "string"
            }
          ],
          "tags": [
            "string"
          ],
          "threat": [
            {
              "framework": "string",
              "tactic": {
                "id": "string",
                "name": "string",
                "reference": "string"
              },
              "technique": [
                {
                  "id": "string",
                  "name": "string",
                  "reference": "string",
                  "subtechnique": [
                    {
                      "id": "string",
                      "name": "string",
                      "reference": "string"
                    }
                  ]
                }
              ]
            }
          ],
          "throttle": "no_actions",
          "timeline_id": "string",
          "timeline_title": "string",
          "timestamp_override": "string",
          "timestamp_override_fallback_disabled": true,
          "to": "string",
          "version": 42,
          "created_at": "2025-05-04T09:42:00+00:00",
          "created_by": "string",
          "execution_summary": {
            "last_execution": {
              "date": "2025-05-04T09:42:00+00:00",
              "message": "string",
              "metrics": {
                "execution_gap_duration_s": 42,
                "gap_range": {
                  "gte": "string",
                  "lte": "string"
                },
                "total_enrichment_duration_ms": 42,
                "total_indexing_duration_ms": 42,
                "total_search_duration_ms": 42
              },
              "status": "going to run",
              "status_order": 42
            }
          },
          "id": "string",
          "immutable": true,
          "revision": 42,
          "rule_id": "string",
          "rule_source": {
            "is_customized": true,
            "type": "external"
          },
          "updated_at": "2025-05-04T09:42:00+00:00",
          "updated_by": "string",
          "language": "eql",
          "query": "string",
          "type": "eql",
          "alert_suppression": {
            "duration": {
              "unit": "s",
              "value": 42
            },
            "group_by": [
              "string"
            ],
            "missing_fields_strategy": "doNotSuppress"
          },
          "data_view_id": "string",
          "event_category_override": "string",
          "filters": [],
          "index": [
            "string"
          ],
          "tiebreaker_field": "string",
          "timestamp_field": "string"
        }
      ],
      "deleted": [
        {
          "actions": [
            {
              "action_type_id": "string",
              "alerts_filter": {},
              "frequency": {
                "notifyWhen": "onActiveAlert",
                "summary": true,
                "throttle": "no_actions"
              },
              "group": "string",
              "id": "string",
              "params": {},
              "uuid": "string"
            }
          ],
          "alias_purpose": "savedObjectConversion",
          "alias_target_id": "string",
          "author": [
            "string"
          ],
          "building_block_type": "string",
          "description": "string",
          "enabled": true,
          "exceptions_list": [
            {
              "id": "string",
              "list_id": "string",
              "namespace_type": "agnostic",
              "type": "detection"
            }
          ],
          "false_positives": [
            "string"
          ],
          "from": "string",
          "interval": "string",
          "investigation_fields": {
            "field_names": [
              "string"
            ]
          },
          "license": "string",
          "max_signals": 42,
          "meta": {},
          "name": "string",
          "namespace": "string",
          "note": "string",
          "outcome": "exactMatch",
          "output_index": "string",
          "references": [
            "string"
          ],
          "related_integrations": [
            {
              "integration": "string",
              "package": "string",
              "version": "string"
            }
          ],
          "required_fields": [
            {
              "ecs": true,
              "name": "string",
              "type": "string"
            }
          ],
          "response_actions": [
            {
              "action_type_id": ".osquery",
              "params": {
                "ecs_mapping": {
                  "additionalProperty1": {
                    "field": "string",
                    "value": "string"
                  },
                  "additionalProperty2": {
                    "field": "string",
                    "value": "string"
                  }
                },
                "pack_id": "string",
                "queries": [
                  {
                    "ecs_mapping": {
                      "additionalProperty1": {
                        "field": "string",
                        "value": "string"
                      },
                      "additionalProperty2": {
                        "field": "string",
                        "value": "string"
                      }
                    },
                    "id": "string",
                    "platform": "string",
                    "query": "string",
                    "removed": true,
                    "snapshot": true,
                    "version": "string"
                  }
                ],
                "query": "string",
                "saved_query_id": "string",
                "timeout": 42.0
              }
            }
          ],
          "risk_score": 42,
          "risk_score_mapping": [
            {
              "field": "string",
              "operator": "equals",
              "risk_score": 42,
              "value": "string"
            }
          ],
          "rule_name_override": "string",
          "setup": "string",
          "severity": "low",
          "severity_mapping": [
            {
              "field": "string",
              "operator": "equals",
              "severity": "low",
              "value": "string"
            }
          ],
          "tags": [
            "string"
          ],
          "threat": [
            {
              "framework": "string",
              "tactic": {
                "id": "string",
                "name": "string",
                "reference": "string"
              },
              "technique": [
                {
                  "id": "string",
                  "name": "string",
                  "reference": "string",
                  "subtechnique": [
                    {
                      "id": "string",
                      "name": "string",
                      "reference": "string"
                    }
                  ]
                }
              ]
            }
          ],
          "throttle": "no_actions",
          "timeline_id": "string",
          "timeline_title": "string",
          "timestamp_override": "string",
          "timestamp_override_fallback_disabled": true,
          "to": "string",
          "version": 42,
          "created_at": "2025-05-04T09:42:00+00:00",
          "created_by": "string",
          "execution_summary": {
            "last_execution": {
              "date": "2025-05-04T09:42:00+00:00",
              "message": "string",
              "metrics": {
                "execution_gap_duration_s": 42,
                "gap_range": {
                  "gte": "string",
                  "lte": "string"
                },
                "total_enrichment_duration_ms": 42,
                "total_indexing_duration_ms": 42,
                "total_search_duration_ms": 42
              },
              "status": "going to run",
              "status_order": 42
            }
          },
          "id": "string",
          "immutable": true,
          "revision": 42,
          "rule_id": "string",
          "rule_source": {
            "is_customized": true,
            "type": "external"
          },
          "updated_at": "2025-05-04T09:42:00+00:00",
          "updated_by": "string",
          "language": "eql",
          "query": "string",
          "type": "eql",
          "alert_suppression": {
            "duration": {
              "unit": "s",
              "value": 42
            },
            "group_by": [
              "string"
            ],
            "missing_fields_strategy": "doNotSuppress"
          },
          "data_view_id": "string",
          "event_category_override": "string",
          "filters": [],
          "index": [
            "string"
          ],
          "tiebreaker_field": "string",
          "timestamp_field": "string"
        }
      ],
      "skipped": [
        {
          "id": "string",
          "name": "string",
          "skip_reason": "RULE_NOT_MODIFIED"
        }
      ],
      "updated": [
        {
          "actions": [
            {
              "action_type_id": "string",
              "alerts_filter": {},
              "frequency": {
                "notifyWhen": "onActiveAlert",
                "summary": true,
                "throttle": "no_actions"
              },
              "group": "string",
              "id": "string",
              "params": {},
              "uuid": "string"
            }
          ],
          "alias_purpose": "savedObjectConversion",
          "alias_target_id": "string",
          "author": [
            "string"
          ],
          "building_block_type": "string",
          "description": "string",
          "enabled": true,
          "exceptions_list": [
            {
              "id": "string",
              "list_id": "string",
              "namespace_type": "agnostic",
              "type": "detection"
            }
          ],
          "false_positives": [
            "string"
          ],
          "from": "string",
          "interval": "string",
          "investigation_fields": {
            "field_names": [
              "string"
            ]
          },
          "license": "string",
          "max_signals": 42,
          "meta": {},
          "name": "string",
          "namespace": "string",
          "note": "string",
          "outcome": "exactMatch",
          "output_index": "string",
          "references": [
            "string"
          ],
          "related_integrations": [
            {
              "integration": "string",
              "package": "string",
              "version": "string"
            }
          ],
          "required_fields": [
            {
              "ecs": true,
              "name": "string",
              "type": "string"
            }
          ],
          "response_actions": [
            {
              "action_type_id": ".osquery",
              "params": {
                "ecs_mapping": {
                  "additionalProperty1": {
                    "field": "string",
                    "value": "string"
                  },
                  "additionalProperty2": {
                    "field": "string",
                    "value": "string"
                  }
                },
                "pack_id": "string",
                "queries": [
                  {
                    "ecs_mapping": {
                      "additionalProperty1": {
                        "field": "string",
                        "value": "string"
                      },
                      "additionalProperty2": {
                        "field": "string",
                        "value": "string"
                      }
                    },
                    "id": "string",
                    "platform": "string",
                    "query": "string",
                    "removed": true,
                    "snapshot": true,
                    "version": "string"
                  }
                ],
                "query": "string",
                "saved_query_id": "string",
                "timeout": 42.0
              }
            }
          ],
          "risk_score": 42,
          "risk_score_mapping": [
            {
              "field": "string",
              "operator": "equals",
              "risk_score": 42,
              "value": "string"
            }
          ],
          "rule_name_override": "string",
          "setup": "string",
          "severity": "low",
          "severity_mapping": [
            {
              "field": "string",
              "operator": "equals",
              "severity": "low",
              "value": "string"
            }
          ],
          "tags": [
            "string"
          ],
          "threat": [
            {
              "framework": "string",
              "tactic": {
                "id": "string",
                "name": "string",
                "reference": "string"
              },
              "technique": [
                {
                  "id": "string",
                  "name": "string",
                  "reference": "string",
                  "subtechnique": [
                    {
                      "id": "string",
                      "name": "string",
                      "reference": "string"
                    }
                  ]
                }
              ]
            }
          ],
          "throttle": "no_actions",
          "timeline_id": "string",
          "timeline_title": "string",
          "timestamp_override": "string",
          "timestamp_override_fallback_disabled": true,
          "to": "string",
          "version": 42,
          "created_at": "2025-05-04T09:42:00+00:00",
          "created_by": "string",
          "execution_summary": {
            "last_execution": {
              "date": "2025-05-04T09:42:00+00:00",
              "message": "string",
              "metrics": {
                "execution_gap_duration_s": 42,
                "gap_range": {
                  "gte": "string",
                  "lte": "string"
                },
                "total_enrichment_duration_ms": 42,
                "total_indexing_duration_ms": 42,
                "total_search_duration_ms": 42
              },
              "status": "going to run",
              "status_order": 42
            }
          },
          "id": "string",
          "immutable": true,
          "revision": 42,
          "rule_id": "string",
          "rule_source": {
            "is_customized": true,
            "type": "external"
          },
          "updated_at": "2025-05-04T09:42:00+00:00",
          "updated_by": "string",
          "language": "eql",
          "query": "string",
          "type": "eql",
          "alert_suppression": {
            "duration": {
              "unit": "s",
              "value": 42
            },
            "group_by": [
              "string"
            ],
            "missing_fields_strategy": "doNotSuppress"
          },
          "data_view_id": "string",
          "event_category_override": "string",
          "filters": [],
          "index": [
            "string"
          ],
          "tiebreaker_field": "string",
          "timestamp_field": "string"
        }
      ]
    },
    "summary": {
      "failed": 42,
      "skipped": 42,
      "succeeded": 42,
      "total": 42
    }
  },
  "message": "string",
  "rules_count": 42,
  "status_code": 42,
  "success": true
}
string






























































































































Get a metadata list Beta

GET /api/endpoint/metadata

Query parameters

  • query object Required

    Additional properties are allowed.

    Hide query attributes Show query attributes object
    • hostStatuses array[string] Required

      Values are healthy, offline, updating, inactive, or unenrolled.

    • kuery string | null
    • page integer

      Page number

      Minimum value is 0. Default value is 0.

    • pageSize integer

      Number of items per page

      Minimum value is 1, maximum value is 10000. Default value is 10.

    • sortDirection string | null

      Values are asc or desc.

    • Values are enrolled_at, metadata.host.hostname, host_status, metadata.Endpoint.policy.applied.name, metadata.Endpoint.policy.applied.status, metadata.host.os.name, metadata.host.ip, metadata.agent.version, or last_checkin.

Responses

  • 200 application/json

    OK

    Additional properties are allowed.

GET /api/endpoint/metadata
curl \
 --request GET https://<KIBANA_URL>/api/endpoint/metadata?query=%7B%7D
Response examples (200)
{}





















Upsert an asset criticality record Beta

POST /api/asset_criticality

Create or update an asset criticality record for a specific entity.

If a record already exists for the specified entity, that record is overwritten with the specified value. If a record doesn't exist for the specified entity, a new record is created.

application/json

Body Required

  • id_field string Required

    Values are host.name, user.name, service.name, or related.entity.

  • id_value string Required

    The ID value of the asset.

  • criticality_level string Required

    The criticality level of the asset.

    Values are low_impact, medium_impact, high_impact, or extreme_impact.

  • refresh string

    If 'wait_for' the request will wait for the index refresh.

    Value is wait_for.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object

    The deleted record if it existed.

    • id_field string Required

      Values are host.name, user.name, service.name, or related.entity.

    • id_value string Required

      The ID value of the asset.

    • criticality_level string Required

      The criticality level of the asset.

      Values are low_impact, medium_impact, high_impact, or extreme_impact.

    • asset object Required

      Additional properties are allowed.

      Hide asset attribute Show asset attribute object
      • The criticality level of the asset.

        Values are low_impact, medium_impact, high_impact, or extreme_impact.

    • host object

      Additional properties are allowed.

      Hide host attributes Show host attributes object
      • asset object

        Additional properties are allowed.

        Hide asset attribute Show asset attribute object
        • criticality string Required

          The criticality level of the asset.

          Values are low_impact, medium_impact, high_impact, or extreme_impact.

      • name string Required
    • service object

      Additional properties are allowed.

      Hide service attributes Show service attributes object
      • asset object

        Additional properties are allowed.

        Hide asset attribute Show asset attribute object
        • criticality string Required

          The criticality level of the asset.

          Values are low_impact, medium_impact, high_impact, or extreme_impact.

      • name string Required
    • user object

      Additional properties are allowed.

      Hide user attributes Show user attributes object
      • asset object

        Additional properties are allowed.

        Hide asset attribute Show asset attribute object
        • criticality string Required

          The criticality level of the asset.

          Values are low_impact, medium_impact, high_impact, or extreme_impact.

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

      The time the record was created or updated.

  • Invalid request

POST /api/asset_criticality
curl \
 --request POST https://<KIBANA_URL>/api/asset_criticality \
 --header "Content-Type: application/json" \
 --data '{"id_field":"host.name","id_value":"my_host","criticality_level":"high_impact"}'
Request example
{
  "id_field": "host.name",
  "id_value": "my_host",
  "criticality_level": "high_impact"
}
Response examples (200)
{
  "host": {
    "name": "my_host",
    "asset": {
      "criticality": "high_impact"
    }
  },
  "asset": {
    "criticality": "high_impact"
  },
  "id_field": "host.name",
  "id_value": "my_host",
  "@timestamp": "2024-08-02T11:15:34.290Z",
  "criticality_level": "high_impact"
}












































List Entity Store Entities Beta

GET /api/entity_store/entities/list

List entities records, paging, sorting and filtering as needed.

Query parameters

Responses

  • 200 application/json

    Entities returned successfully

    Hide response attributes Show response attributes object
    • inspect object

      Additional properties are allowed.

      Hide inspect attributes Show inspect attributes object
    • page integer Required

      Minimum value is 1.

    • per_page integer Required

      Minimum value is 1, maximum value is 1000.

    • records array[object] Required
      One of:
      Hide attributes Show attributes
      • @timestamp string(date-time)
      • asset object

        Additional properties are allowed.

        Hide asset attribute Show asset attribute object
        • criticality string Required

          The criticality level of the asset.

          Values are low_impact, medium_impact, high_impact, or extreme_impact.

      • entity object Required

        Additional properties are allowed.

        Hide entity attributes Show entity attributes object
      • event object

        Additional properties are allowed.

        Hide event attribute Show event attribute object
      • user object Required

        Additional properties are allowed.

        Hide user attributes Show user attributes object
        • domain array[string]
        • email array[string]
        • full_name array[string]
        • hash array[string]
        • id array[string]
        • name string Required
        • risk object

          Additional properties are allowed.

          Hide risk attributes Show risk attributes object
          • @timestamp string(date-time) Required

            The time at which the risk score was calculated.

          • calculated_level string Required

            Lexical description of the entity's risk.

            Values are Unknown, Low, Moderate, High, or Critical.

          • calculated_score number(double) Required

            The raw numeric value of the given entity's risk score.

          • calculated_score_norm number(double) Required

            The normalized numeric value of the given entity's risk score. Useful for comparing with other entities.

            Minimum value is 0, maximum value is 100.

          • category_1_count number(integer) Required

            The number of risk input documents that contributed to the Category 1 score (category_1_score).

          • category_1_score number(double) Required

            The contribution of Category 1 to the overall risk score (calculated_score). Category 1 contains Detection Engine Alerts.

          • category_2_count number(integer)
          • category_2_score number(double)
          • The criticality level of the asset.

            Values are low_impact, medium_impact, high_impact, or extreme_impact.

          • criticality_modifier number(double)
          • id_field string Required

            The identifier field defining this risk score. Coupled with id_value, uniquely identifies the entity being scored.

          • id_value string Required

            The identifier value defining this risk score. Coupled with id_field, uniquely identifies the entity being scored.

          • inputs array[object] Required

            A list of the highest-risk documents contributing to this risk score. Useful for investigative purposes.

            Hide inputs attributes Show inputs attributes object
            • category string Required

              The risk category of the risk input document.

            • contribution_score number(double)
            • description string Required

              A human-readable description of the risk input document.

            • id string Required

              The unique identifier (_id) of the original source document

            • index string Required

              The unique index (_index) of the original source document

            • risk_score number(double)

              The weighted risk score of the risk input document.

              Minimum value is 0, maximum value is 100.

            • The @timestamp of the risk input document.

          • notes array[string] Required
        • roles array[string]
    • total integer Required

      Minimum value is 0.

GET /api/entity_store/entities/list
curl \
 --request GET https://<KIBANA_URL>/api/entity_store/entities/list?entity_types=user
Response examples (200)
{
  "inspect": {
    "dsl": [
      "string"
    ],
    "response": [
      "string"
    ]
  },
  "page": 42,
  "per_page": 42,
  "records": [
    {
      "@timestamp": "2025-05-04T09:42:00+00:00",
      "asset": {
        "criticality": "low_impact"
      },
      "entity": {
        "name": "string",
        "source": "string"
      },
      "event": {
        "ingested": "2025-05-04T09:42:00+00:00"
      },
      "user": {
        "domain": [
          "string"
        ],
        "email": [
          "string"
        ],
        "full_name": [
          "string"
        ],
        "hash": [
          "string"
        ],
        "id": [
          "string"
        ],
        "name": "string",
        "risk": {
          "@timestamp": "2017-07-21T17:32:28Z",
          "calculated_level": "Critical",
          "calculated_score": 42.0,
          "calculated_score_norm": 42.0,
          "category_1_count": 42.0,
          "category_1_score": 42.0,
          "category_2_count": 42.0,
          "category_2_score": 42.0,
          "criticality_level": "low_impact",
          "criticality_modifier": 42.0,
          "id_field": "host.name",
          "id_value": "example.host",
          "inputs": [
            {
              "category": "category_1",
              "contribution_score": 42.0,
              "description": "Generated from Detection Engine Rule: Malware Prevention Alert",
              "id": "91a93376a507e86cfbf282166275b89f9dbdb1f0be6c8103c6ff2909ca8e1a1c",
              "index": ".internal.alerts-security.alerts-default-000001",
              "risk_score": 42.0,
              "timestamp": "2017-07-21T17:32:28Z"
            }
          ],
          "notes": [
            "string"
          ]
        },
        "roles": [
          "string"
        ]
      }
    }
  ],
  "total": 42
}












Run the risk scoring engine Beta

POST /api/risk_score/engine/schedule_now

Schedule the risk scoring engine to run as soon as possible. You can use this to recalculate entity risk scores after updating their asset criticality.

application/json

Responses

  • 200 application/json

    Successful response

    Hide response attribute Show response attribute object
  • 400 application/json

    Task manager is unavailable

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

    Unexpected error

    Hide response attributes Show response attributes object
POST /api/risk_score/engine/schedule_now
curl \
 --request POST https://<KIBANA_URL>/api/risk_score/engine/schedule_now \
 --header "Content-Type: application/json"
Response examples (200)
{
  "success": true
}
Response examples (400)
{
  "message": "string",
  "status_code": 42
}
Response examples (default)
{
  "full_error": "string",
  "message": "string"
}

Security exceptions

Exceptions are associated with detection and endpoint rules, and are used to prevent a rule from generating an alert from incoming events, even when the rule's other criteria are met. They can help reduce the number of false positives and prevent trusted processes and network activity from generating unnecessary alerts.

Exceptions are made up of:

  • Exception containers: A container for related exceptions. Generally, a single exception container contains all the exception items relevant for a subset of rules. For example, a container can be used to group together network-related exceptions that are relevant for a large number of network rules. The container can then be associated with all the relevant rules.
  • Exception items: The query (fields, values, and logic) used to prevent rules from generating alerts. When an exception item's query evaluates to true, the rule does not generate an alert.

For detection rules, you can also use lists to define rule exceptions. A list holds multiple values of the same Elasticsearch data type, such as IP addresses. These values are used to determine when an exception prevents an alert from being generated.

You cannot use lists with endpoint rule exceptions.


Only exception containers can be associated with rules. You cannot directly associate an exception item or a list container with a rule. To use list exceptions, create an exception item that references the relevant list container.

Exceptions requirements

Before you can start working with exceptions that use value lists, you must create the .lists and .items data streams for the relevant Kibana space. To do this, use the Create list data streams endpoint. Once these data streams are created, your role needs privileges to manage rules. For a complete list of requirements, refer to Enable and access detections.

Create rule exception items Beta

POST /api/detection_engine/rules/{id}/exceptions

Create exception items that apply to a single detection rule.

Path parameters

  • id string(uuid) Required

    Detection rule's identifier

application/json

Body Required

Rule exception items.

  • items array[object] Required
    Hide items attributes Show items attributes object
    • comments array[object]

      Default value is [] (empty).

      Hide comments attribute Show comments attribute object
      • comment string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

    • description string Required

      Describes the exception list.

    • entries array[object] Required
      Any of:
      Hide attributes Show attributes
      • field string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • operator string Required

        Values are excluded or included.

      • type string Required Discriminator

        Value is match.

      • value string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

    • expire_time string(date-time)
    • item_id string(nonempty)

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

      Minimum length is 1.

    • meta object

      Additional properties are allowed.

    • name string(nonempty) Required

      Exception list name.

      Minimum length is 1.

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

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

      Values are agnostic or single. Default value is single.

    • os_types array[string]

      Use this field to specify the operating system.

      Values are linux, macos, or windows. Default value is [] (empty).

    • tags array[string(nonempty)]

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

      Minimum length of each is 1. Default value is [] (empty).

    • type string Required

      Value is simple.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • _version string

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

    • comments array[object] Required

      Array of comment fields:

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

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • created_at string(date-time) Required

        Autogenerated date of object creation.

      • created_by string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • id string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • updated_at string(date-time)

        Autogenerated date of last object update.

      • updated_by string(nonempty)

        A string that does not contain only whitespace characters

        Minimum length is 1.

    • created_at string(date-time) Required

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

    • description string Required

      Describes the exception list.

    • entries array[object] Required
      Any of:
      Hide attributes Show attributes
      • field string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • operator string Required

        Values are excluded or included.

      • type string Required Discriminator

        Value is match.

      • value string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

    • expire_time string(date-time)

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

    • id string(nonempty) Required

      Exception's identifier.

      Minimum length is 1.

    • item_id string(nonempty) Required

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

      Minimum length is 1.

    • list_id string(nonempty) Required

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

      Minimum length is 1.

    • meta object

      Additional properties are allowed.

    • name string(nonempty) Required

      Exception list name.

      Minimum length is 1.

    • namespace_type string Required

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

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

      Values are agnostic or single. Default value is single.

    • os_types array[string]

      Use this field to specify the operating system.

      Values are linux, macos, or windows. Default value is [] (empty).

    • tags array[string(nonempty)]

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

      Minimum length of each is 1. Default value is [] (empty).

    • tie_breaker_id string Required

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

    • type string Required

      Value is simple.

    • updated_at string(date-time) Required

      Autogenerated date of last object update.

    • updated_by string Required

      Autogenerated value - user that last updated object.

  • 400 application/json

    Invalid input data response

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

    Internal server error response

    Hide response attributes Show response attributes object
POST /api/detection_engine/rules/{id}/exceptions
curl \
 --request POST https://<KIBANA_URL>/api/detection_engine/rules/330bdd28-eedf-40e1-bed0-f10176c7f9e0/exceptions \
 --header "Content-Type: application/json" \
 --data '{"items":[{"name":"Sample Exception List Item","tags":["malware"],"type":"simple","entries":[{"type":"exists","field":"actingProcess.file.signer","operator":"excluded"},{"type":"match_any","field":"host.name","value":["saturn","jupiter"],"operator":"included"}],"item_id":"simple_list_item","list_id":"simple_list","os_types":["linux"],"description":"This is a sample detection type exception item.","namespace_type":"single"}]}'
Request example
{
  "items": [
    {
      "name": "Sample Exception List Item",
      "tags": [
        "malware"
      ],
      "type": "simple",
      "entries": [
        {
          "type": "exists",
          "field": "actingProcess.file.signer",
          "operator": "excluded"
        },
        {
          "type": "match_any",
          "field": "host.name",
          "value": [
            "saturn",
            "jupiter"
          ],
          "operator": "included"
        }
      ],
      "item_id": "simple_list_item",
      "list_id": "simple_list",
      "os_types": [
        "linux"
      ],
      "description": "This is a sample detection type exception item.",
      "namespace_type": "single"
    }
  ]
}
Response examples (200)
[
  {
    "id": "71a9f4b2-c85c-49b4-866f-c71eb9e67da2",
    "name": "Sample Exception List Item",
    "tags": [
      "malware"
    ],
    "type": "simple",
    "entries": [
      {
        "type": "exists",
        "field": "actingProcess.file.signer",
        "operator": "excluded"
      },
      {
        "type": "match_any",
        "field": "host.name",
        "value": [
          "saturn",
          "jupiter"
        ],
        "operator": "included"
      }
    ],
    "item_id": "simple_list_item",
    "list_id": "simple_list",
    "_version": "WzQsMV0=",
    "comments": [],
    "os_types": [
      "linux"
    ],
    "created_at": "2025-01-07T20:07:33.119Z",
    "created_by": "elastic",
    "updated_at": "2025-01-07T20:07:33.119Z",
    "updated_by": "elastic",
    "description": "This is a sample detection type exception item.",
    "namespace_type": "single",
    "tie_breaker_id": "09434836-9db9-4942-a234-5a9268e0b34c"
  }
]
Response examples (400)
{
  "error": "Bad Request",
  "message": "Invalid request payload JSON format",
  "statusCode": 400
}
{
  "error": "Bad Request",
  "message": "[request params]: id: Invalid uuid",
  "statusCode": 400
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403)
{
  "message": "Unable to create exception-list",
  "status_code": 403
}
Response examples (500)
{
  "message": "Internal Server Error",
  "status_code": 500
}




Update an exception list Beta

PUT /api/exception_lists

Update an exception list using the id or list_id field.

application/json

Body Required

Exception list's properties

  • _version string

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

  • description string Required

    Describes the exception list.

  • id string(nonempty)

    Exception list's identifier.

    Minimum length is 1.

  • list_id string(nonempty)

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

    Minimum length is 1.

  • meta object

    Placeholder for metadata about the list container.

    Additional properties are allowed.

  • name string Required

    The name of the exception list.

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

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

    Values are agnostic or single. Default value is single.

  • os_types array[string]

    Use this field to specify the operating system.

    Values are linux, macos, or windows.

  • tags array[string]

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

  • type string Required

    The type of exception list to be created. Different list types may denote where they can be utilized.

    Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

  • version integer

    The document version, automatically increasd on updates.

    Minimum value is 1.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • _version string

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

    • created_at string(date-time) Required

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

    • description string Required

      Describes the exception list.

    • id string(nonempty) Required

      Exception list's identifier.

      Minimum length is 1.

    • immutable boolean Required
    • list_id string(nonempty) Required

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

      Minimum length is 1.

    • meta object

      Placeholder for metadata about the list container.

      Additional properties are allowed.

    • name string Required

      The name of the exception list.

    • namespace_type string Required

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

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

      Values are agnostic or single. Default value is single.

    • os_types array[string]

      Use this field to specify the operating system.

      Values are linux, macos, or windows.

    • tags array[string]

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

    • tie_breaker_id string Required

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

    • type string Required

      The type of exception list to be created. Different list types may denote where they can be utilized.

      Values are detection, rule_default, endpoint, endpoint_trusted_apps, endpoint_events, endpoint_host_isolation_exceptions, or endpoint_blocklists.

    • 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, automatically increasd on updates.

      Minimum value is 1.

  • 400 application/json

    Invalid input data response

    One of:
    Hide attributes Show attributes
  • 401 application/json

    Unsuccessful authentication response

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

    Not enough privileges response

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

    Exception list not found response

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

    Internal server error response

    Hide response attributes Show response attributes object
PUT /api/exception_lists
curl \
 --request PUT https://<KIBANA_URL>/api/exception_lists \
 --header "Content-Type: application/json" \
 --data '{"name":"Updated exception list name","tags":["draft malware"],"type":"detection","list_id":"simple_list","os_types":["linux"],"description":"Different description"}'
Request example
{
  "name": "Updated exception list name",
  "tags": [
    "draft malware"
  ],
  "type": "detection",
  "list_id": "simple_list",
  "os_types": [
    "linux"
  ],
  "description": "Different description"
}
Response examples (200)
{
  "id": "fa7f545f-191b-4d32-b1f0-c7cd62a79e55",
  "name": "Updated exception list name",
  "tags": [
    "draft malware"
  ],
  "type": "detection",
  "list_id": "simple_list",
  "version": 2,
  "_version": "WzExLDFd",
  "os_types": [],
  "immutable": false,
  "created_at": "2025-01-07T20:43:55.264Z",
  "created_by": "elastic",
  "updated_at": "2025-01-07T21:32:03.726Z",
  "updated_by": "elastic",
  "description": "Different description",
  "namespace_type": "single",
  "tie_breaker_id": "319fe983-acdd-4806-b6c4-3098eae9392f"
}
Response examples (400)
{
  "error": "Bad Request",
  "message": "[request body]: list_id: Expected string, received number",
  "statusCode": 400
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403)
{
  "error": "Forbidden",
  "message": "API [PUT /api/exception_lists] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}
Response examples (404)
{
  "message\"": "exception list id: \"foo\" does not exist",
  "status_code\"": 404
}
Response examples (500)
{
  "message": "Internal Server Error",
  "status_code": 500
}





















































Get value list details Beta

GET /api/lists

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

Query parameters

  • id string(nonempty) Required

    Value list's identifier.

    Minimum length is 1.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • _version string

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

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

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

    • description string(nonempty) Required

      Describes the value list.

      Minimum length is 1.

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

    • 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:
    Hide attributes Show attributes
  • 401 application/json

    Unsuccessful authentication response

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

    Not enough privileges response

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

    List not found response

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

    Internal server error response

    Hide response attributes Show response attributes object
GET /api/lists
curl \
 --request GET https://<KIBANA_URL>/api/lists?id=21b01cfb-058d-44b9-838c-282be16c91cd
Response examples (200)
{
  "id": "ip_list",
  "name": "My bad ips",
  "type": "ip",
  "version": 1,
  "_version": "WzEsMV0=",
  "immutable": false,
  "@timestamp": "2025-01-08T04:47:34.273Z",
  "created_at": "2025-01-08T04:47:34.273Z",
  "created_by": "elastic",
  "updated_at": "2025-01-08T05:21:53.843Z",
  "updated_by": "elastic",
  "description": "This list describes bad internet ip",
  "tie_breaker_id": "f5508188-b1e9-4e6e-9662-d039a7d89899"
}
Response examples (400)
{
  "error": "Bad Request",
  "message": "[request query]: id: Required",
  "statusCode": 400
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403)
{
  "error": "Forbidden",
  "message": "API [GET /api/lists?id=ip_list] is unauthorized for user, this action is granted by the Kibana privileges [lists-read]",
  "statusCode": 403
}
Response examples (404)
{
  "message": "list id: \\\"foo\\\" not found",
  "status_code": 404
}
Response examples (500)
{
  "message": "Internal Server Error",
  "status_code": 500
}
















Get value lists Beta

GET /api/lists/_find

Get a paginated subset of value lists. By default, the first page is returned, with 20 results per page.

Query parameters

  • page integer

    The page number to return.

  • per_page integer

    The number of value lists to return per page.

  • sort_field string(nonempty)

    Determines which field is used to sort the results.

    Minimum length is 1.

  • Determines the sort order, which can be desc or asc

    Values are desc or asc.

  • cursor string(nonempty)

    Returns the lists that come after the last lists returned in the previous call (use the cursor value returned in the previous call). This parameter uses the tie_breaker_id field to ensure all lists are sorted and returned correctly.

    Minimum length is 1.

  • filter string

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

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • cursor string(nonempty) Required

      Minimum length is 1.

    • data array[object] Required
      Hide data attributes Show data 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.

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

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

    • page integer Required

      Minimum value is 0.

    • per_page integer Required

      Minimum value is 0.

    • total integer Required

      Minimum value is 0.

  • 400 application/json

    Invalid input data response

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

    Internal server error response

    Hide response attributes Show response attributes object
GET /api/lists/_find
curl \
 --request GET https://<KIBANA_URL>/api/lists/_find
Response examples (200)
{
  "data": [
    {
      "id": "ip_list",
      "name": "Simple list with an ip",
      "type": "ip",
      "version": 1,
      "_version": "WzAsMV0=",
      "immutable": false,
      "@timestamp": "2025-01-08T04:47:34.273Z\n",
      "created_at": "2025-01-08T04:47:34.273Z\n",
      "created_by": "elastic",
      "updated_at": "2025-01-08T04:47:34.273Z\n",
      "updated_by": "elastic",
      "description": "This list describes bad internet ip",
      "tie_breaker_id": "f5508188-b1e9-4e6e-9662-d039a7d89899"
    }
  ],
  "page": 1,
  "total": 1,
  "cursor": "WzIwLFsiZjU1MDgxODgtYjFlOS00ZTZlLTk2NjItZDAzOWE3ZDg5ODk5Il1d",
  "per_page": 20
}
Response examples (400)
{
  "error": "Bad Request",
  "message": "[request query]: page: Expected number, received nan",
  "statusCode": 400
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403)
{
  "error": "Forbidden",
  "message": "API [GET /api/lists/_find?page=1&per_page=20] is unauthorized for user, this action is granted by the Kibana privileges [lists-read]",
  "statusCode": 403
}
Response examples (500)
{
  "message": "Internal Server Error",
  "status_code": 500
}
















Update a value list item Beta

PUT /api/lists/items

Update a value list item using the list item ID. The original list item is replaced, and all unspecified fields are deleted.

You cannot modify the id value.

application/json

Body Required

Value list item's properties

  • _version string

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

  • id string(nonempty) Required

    Value list item's identifier.

    Minimum length is 1.

  • meta object

    Placeholder for metadata about the value list item.

    Additional properties are allowed.

  • value string(nonempty) Required

    The value used to evaluate exceptions.

    Minimum length is 1.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • _version string

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

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

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

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

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

      Value list item's identifier.

      Minimum length is 1.

    • list_id string(nonempty) Required

      Value list's identifier.

      Minimum length is 1.

    • meta object

      Placeholder for metadata about the value list item.

      Additional properties are allowed.

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

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

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

    • type string Required

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

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

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

    • updated_at string(date-time) Required

      Autogenerated date of last object update.

    • updated_by string Required

      Autogenerated value - user that last updated object.

    • value string(nonempty) Required

      The value used to evaluate exceptions.

      Minimum length is 1.

  • 400 application/json

    Invalid input data response

    One of:
    Hide attributes Show attributes
  • 401 application/json

    Unsuccessful authentication response

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

    Not enough privileges response

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

    List item not found response

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

    Internal server error response

    Hide response attributes Show response attributes object
PUT /api/lists/items
curl \
 --request PUT https://<KIBANA_URL>/api/lists/items \
 --header "Content-Type: application/json" \
 --data '{"id":"ip_item","value":"255.255.255.255"}'
Request example
{
  "id": "ip_item",
  "value": "255.255.255.255"
}
Response examples (200)
{
  "id": "pd1WRJQBs4HAK3VQeHFI",
  "type": "ip",
  "value": "255.255.255.255",
  "list_id": "ip_list",
  "_version": "WzIwLDFd",
  "@timestamp": "2025-01-08T05:15:05.159Z",
  "created_at": "2025-01-08T05:15:05.159Z",
  "created_by": "elastic",
  "updated_at": "2025-01-08T05:44:14.009Z",
  "updated_by": "elastic",
  "tie_breaker_id": "eee41dc7-1666-4876-982f-8b0f7b59eca3"
}
Response examples (400)
{
  "error": "Bad Request",
  "message": "[request body]: id: Expected string, received number",
  "statusCode": 400
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403)
{
  "error": "Forbidden",
  "message": "API [PATCH /api/lists/items] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}
Response examples (404)
{
  "message": "list item id: \\\"foo\\\" not found",
  "status_code": 404
}
Response examples (500)
{
  "message": "Internal Server Error",
  "status_code": 500
}

Create a value list item Beta

POST /api/lists/items

Create a value list item and associate it with the specified value list.

All value list items in the same list must be the same type. For example, each list item in an ip list must define a specific IP address.

Before creating a list item, you must create a list.

application/json

Body Required

Value list item's properties

  • id string(nonempty)

    Value list item's identifier.

    Minimum length is 1.

  • list_id string(nonempty) Required

    Value list's identifier.

    Minimum length is 1.

  • meta object

    Placeholder for metadata about the value list item.

    Additional properties are allowed.

  • refresh string

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

    Values are true, false, or wait_for.

  • value string(nonempty) Required

    The value used to evaluate exceptions.

    Minimum length is 1.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • _version string

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

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

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

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

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

      Value list item's identifier.

      Minimum length is 1.

    • list_id string(nonempty) Required

      Value list's identifier.

      Minimum length is 1.

    • meta object

      Placeholder for metadata about the value list item.

      Additional properties are allowed.

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

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

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

    • type string Required

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

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

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

    • updated_at string(date-time) Required

      Autogenerated date of last object update.

    • updated_by string Required

      Autogenerated value - user that last updated object.

    • value string(nonempty) Required

      The value used to evaluate exceptions.

      Minimum length is 1.

  • 400 application/json

    Invalid input data response

    One of:
    Hide attributes Show attributes
  • 401 application/json

    Unsuccessful authentication response

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

    Not enough privileges response

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

    Not enough privileges response

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

    List item 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/items
curl \
 --request POST https://<KIBANA_URL>/api/lists/items \
 --header "Content-Type: application/json" \
 --data '{"value":"127.0.0.1","list_id":"ip_list"}'
Request examples
{
  "value": "127.0.0.1",
  "list_id": "ip_list"
}
{
  "value": "192.168.0.0/16",
  "list_id": "ip_range_list"
}
{
  "value": "zeek",
  "list_id": "keyword_list"
}
Response examples (200)
{
  "id": "21b01cfb-058d-44b9-838c-282be16c91cc",
  "type": "ip",
  "value": "127.0.0.1",
  "list_id": "ip_list",
  "_version": "WzAsMV0=",
  "@timestamp": "2025-01-08T04:59:06.154Z",
  "created_at": "2025-01-08T04:59:06.154Z",
  "created_by": "elastic",
  "updated_at": "2025-01-08T04:59:06.154Z",
  "updated_by": "elastic",
  "tie_breaker_id": "b57c762c-3036-465c-9bfb-7bfb5e6e515a"
}
{
  "id": "ip_range_item",
  "type": "ip_range",
  "value": "192.168.0.0/16",
  "list_id": "ip_range_list",
  "_version": "WzEsMV0=",
  "@timestamp": "2025-01-09T18:33:08.202Z",
  "created_at": "2025-01-09T18:33:08.202Z",
  "created_by": "elastic",
  "updated_at": "2025-01-09T18:33:08.202Z",
  "updated_by": "elastic",
  "tie_breaker_id": "ea1b4189-efda-4637-b8f9-74655a5ebb61"
}
{
  "id": "7f24737d-1da8-4626-a568-33070591bb4e",
  "type": "keyword",
  "value": "zeek",
  "list_id": "keyword_list",
  "_version": "WzIsMV0=",
  "@timestamp": "2025-01-09T18:34:29.422Z",
  "created_at": "2025-01-09T18:34:29.422Z",
  "created_by": "elastic",
  "updated_at": "2025-01-09T18:34:29.422Z",
  "updated_by": "elastic",
  "tie_breaker_id": "2108ced2-5e5d-401e-a88e-4dd69fc5fa27"
}
Response examples (400)
{
  "error": "Bad Request",
  "message": "uri [/api/lists/items] with method [post] exists but is not available with the current configuration",
  "statusCode": 400
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403)
{
  "error": "Forbidden",
  "message": "API [POST /api/lists/items] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}
Response examples (404)
{
  "message": "list id: \\\"ip_list\\\" does not exist",
  "status_code": 404
}
Response examples (409)
{
  "message": "list item id: \\\"ip_item\\\" already exists",
  "status_code": 409
}
Response examples (500)
{
  "message": "Internal Server Error",
  "status_code": 500
}


























































































Add or update a note Beta

PATCH /api/note

Add a note to a Timeline or update an existing note.

application/json

Body Required

The note to add or update, along with additional metadata.

Responses

PATCH /api/note
curl \
 --request PATCH https://<KIBANA_URL>/api/note \
 --header "Content-Type: application/json" \
 --data '{"eventDataView":"string","eventIngested":"string","eventTimestamp":"string","note":{"created":42.0,"createdBy":"string","eventId":"string","note":"string","timelineId":"string","updated":42.0,"updatedBy":"string"},"noteId":"string","overrideOwner":true,"version":"string"}'
Request examples
{
  "eventDataView": "string",
  "eventIngested": "string",
  "eventTimestamp": "string",
  "note": {
    "created": 42.0,
    "createdBy": "string",
    "eventId": "string",
    "note": "string",
    "timelineId": "string",
    "updated": 42.0,
    "updatedBy": "string"
  },
  "noteId": "string",
  "overrideOwner": true,
  "version": "string"
}
Response examples (200)
{
  "note": {
    "created": 42.0,
    "createdBy": "string",
    "eventId": "string",
    "note": "string",
    "timelineId": "string",
    "updated": 42.0,
    "updatedBy": "string",
    "noteId": "string",
    "version": "string"
  }
}

Pin an event Beta

PATCH /api/pinned_event

Pin an event to an existing Timeline.

application/json

Body Required

The pinned event to add or update, along with additional metadata.

Responses

PATCH /api/pinned_event
curl \
 --request PATCH https://<KIBANA_URL>/api/pinned_event \
 --header "Content-Type: application/json" \
 --data '{"eventId":"string","pinnedEventId":"string","timelineId":"string"}'
Request examples
{
  "eventId": "string",
  "pinnedEventId": "string",
  "timelineId": "string"
}
Response examples (200)
{
  "created": 42.0,
  "createdBy": "string",
  "eventId": "string",
  "timelineId": "string",
  "updated": 42.0,
  "updatedBy": "string",
  "pinnedEventId": "string",
  "version": "string"
}
{
  "unpinned": true
}




























Export Timelines Beta

POST /api/timeline/_export

Export Timelines as an NDJSON file.

Query parameters

  • file_name string Required

    The name of the file to export

application/json

Body Required

The IDs of the Timelines to export.

  • ids array[string] | null

Responses

  • 200 application/ndjson

    Indicates the Timelines were successfully exported.

    NDJSON of the exported Timelines

  • 400 application/ndjson

    Indicates that the export size limit was exceeded.

    Hide response attributes Show response attributes object
POST /api/timeline/_export
curl \
 --request POST https://<KIBANA_URL>/api/timeline/_export?file_name=string \
 --header "Content-Type: application/json" \
 --data '{"ids":["string"]}'
Request examples
{
  "ids": [
    "string"
  ]
}
Response examples (200)
string
Response examples (400)
{
  "body": "string",
  "statusCode": 42.0
}





















































Enable an SLO Beta

POST /s/{spaceId}/api/observability/slos/{sloId}/enable

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

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

Path parameters

  • spaceId string Required

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

  • sloId string Required

    An identifier for the slo.

Responses

  • Successful request

  • 400 application/json

    Bad request

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

    Unauthorized response

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

    Unauthorized response

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

    Not found response

    Hide response attributes Show response attributes object
POST /s/{spaceId}/api/observability/slos/{sloId}/enable
curl \
 --request POST https://<KIBANA_URL>/s/default/api/observability/slos/9c235211-6834-11ea-a78c-6feb38a34414/enable \
 --header "kbn-xsrf: string"
Response examples (400)
{
  "error": "Bad Request",
  "message": "Invalid value 'foo' supplied to: [...]",
  "statusCode": 400
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastics] for REST request [/_security/_authenticate]]: unable to authenticate user [elastics] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403)
{
  "error": "Unauthorized",
  "message": "[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastics] for REST request [/_security/_authenticate]]: unable to authenticate user [elastics] for REST request [/_security/_authenticate]",
  "statusCode": 403
}
Response examples (404)
{
  "error": "Not Found",
  "message": "SLO [3749f390-03a3-11ee-8139-c7ff60a1692d] not found",
  "statusCode": 404
}