Kibana Serverless APIs
1.0.2

Base URL
https://<KIBANA_URL>

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

To interact with Kibana APIs, use the following operations:

  • GET: Fetches the information.
  • POST: Adds new information.
  • PUT: Updates the existing information.
  • DELETE: Removes the information.

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

GET kbn:/api/data_views

Documentation source and versions

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

This is version 1.0.2 of this API documentation. Last update on Feb 11, 2025.

Authentication

Api key auth (http_api_key)

You must create an API key and use the encoded value in the request header. To learn about creating keys, go to API keys.






Update a rule Beta

PUT /api/alerting/rule/{id}

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    The identifier for the rule.

application/json

Body

  • actions array[object]

    Default value is [] (empty).

    Hide actions attributes Show actions attributes object
    • 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).

      • Defines a period that limits whether the action runs.

        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

          Defines the range of time in a day that the action can run. If the start value is 00:00 and the end value is 24:00, actions be generated all day.

          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.

    • 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

      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.

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

    • Indicates whether to use alert data as a template.

    • uuid string

      A universally unique identifier (UUID) for the action.

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

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

  • name string Required

    The name of the rule. While this name does not have to be unique, a distinctive name can help you identify a 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

    The parameters for the rule.

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

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

  • tags array[string]

    The tags for the rule.

    Default value is [] (empty).

  • throttle string | null

    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.

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.

  • Indicates a rule with the given ID does not exist.

  • Indicates that the rule has already been updated by another user.

PUT /api/alerting/rule/{id}
curl \
 --request PUT https://<KIBANA_URL>/api/alerting/rule/{id} \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"name":"new name","tags":[],"params":{"index":[".updated-index"],"aggType":"avg","groupBy":"top","aggField":"sheet.version","termSize":6,"termField":"name.keyword","threshold":[1000],"timeField":"@timestamp","timeWindowSize":5,"timeWindowUnit":"m","thresholdComparator":"\u003e"},"actions":[{"id":"96b668d0-a1b6-11ed-afdf-d39a49596974","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}}"},"frequency":{"summary":false,"notify_when":"onActionGroupChange"}}],"schedule":{"interval":"1m"}}'
Request example
Update an index threshold rule that uses a server log connector to send notifications when the threshold is met.
{
  "name": "new name",
  "tags": [],
  "params": {
    "index": [
      ".updated-index"
    ],
    "aggType": "avg",
    "groupBy": "top",
    "aggField": "sheet.version",
    "termSize": 6,
    "termField": "name.keyword",
    "threshold": [
      1000
    ],
    "timeField": "@timestamp",
    "timeWindowSize": 5,
    "timeWindowUnit": "m",
    "thresholdComparator": ">"
  },
  "actions": [
    {
      "id": "96b668d0-a1b6-11ed-afdf-d39a49596974",
      "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}}"
      },
      "frequency": {
        "summary": false,
        "notify_when": "onActionGroupChange"
      }
    }
  ],
  "schedule": {
    "interval": "1m"
  }
}
Response examples (200)
The response for successfully updating an index threshold rule.
{
  "id": "ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74",
  "name": "new name",
  "tags": [],
  "params": {
    "index": [
      ".updated-index"
    ],
    "aggType": "avg",
    "groupBy": "top",
    "aggField": "sheet.version",
    "termSize": 6,
    "termField": "name.keyword",
    "threshold": [
      1000
    ],
    "timeField": "@timestamp",
    "timeWindowSize": 5,
    "timeWindowUnit": "m",
    "thresholdComparator": ">"
  },
  "actions": [
    {
      "id": "96b668d0-a1b6-11ed-afdf-d39a49596974",
      "uuid": "07aef2a0-9eed-4ef9-94ec-39ba58eb609d",
      "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}"
      },
      "frequency": {
        "summary": false,
        "throttle": null,
        "notify_when": "onActionGroupChange"
      },
      "connector_type_id": ".server-log"
    }
  ],
  "enabled": true,
  "running": false,
  "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": "2024-03-26T23:23:51.316Z",
  "revision": 1,
  "schedule": {
    "interval": "1m"
  },
  "throttle": null,
  "created_at": "2024-03-26T23:13:20.985Z",
  "created_by": "elastic",
  "updated_at": "2024-03-26T23:22:59.949Z",
  "updated_by": "elastic",
  "rule_type_id": ".index-threshold",
  "api_key_owner": "elastic",
  "muted_alert_ids": [],
  "execution_status": {
    "status": "ok",
    "last_duration": 52,
    "last_execution_date": "2024-03-26T23:22:51.390Z"
  },
  "scheduled_task_id": "4c5eda00-e74f-11ec-b72f-5b18752ff9ea",
  "api_key_created_by_user": false
}




Delete a rule Beta

DELETE /api/alerting/rule/{id}

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    The identifier for the rule.

Responses

  • Indicates a successful call.

  • Indicates an invalid schema or parameters.

  • Indicates that this call is forbidden.

  • Indicates a rule with the given ID does not exist.

DELETE /api/alerting/rule/{id}
curl \
 --request DELETE https://<KIBANA_URL>/api/alerting/rule/{id} \
 --header "kbn-xsrf: true"




Enable a rule Beta

POST /api/alerting/rule/{id}/_enable

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    The identifier for the rule.

Responses

  • Indicates a successful call.

  • Indicates an invalid schema or parameters.

  • Indicates that this call is forbidden.

  • Indicates a rule with the given ID does not exist.

POST /api/alerting/rule/{id}/_enable
curl \
 --request POST https://<KIBANA_URL>/api/alerting/rule/{id}/_enable \
 --header "kbn-xsrf: true"

Mute all alerts Beta

POST /api/alerting/rule/{id}/_mute_all

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    The identifier for the rule.

Responses

  • Indicates a successful call.

  • Indicates an invalid schema or parameters.

  • Indicates that this call is forbidden.

  • Indicates a rule with the given ID does not exist.

POST /api/alerting/rule/{id}/_mute_all
curl \
 --request POST https://<KIBANA_URL>/api/alerting/rule/{id}/_mute_all \
 --header "kbn-xsrf: true"

Unmute all alerts Beta

POST /api/alerting/rule/{id}/_unmute_all

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    The identifier for the rule.

Responses

  • Indicates a successful call.

  • Indicates an invalid schema or parameters.

  • Indicates that this call is forbidden.

  • Indicates a rule with the given ID does not exist.

POST /api/alerting/rule/{id}/_unmute_all
curl \
 --request POST https://<KIBANA_URL>/api/alerting/rule/{id}/_unmute_all \
 --header "kbn-xsrf: true"
















APM agent configuration

Adjust APM agent configuration without need to redeploy your application.





























APM agent keys

Configure APM agent keys to authorize requests from APM agents to the APM Server.




























Delete source map Beta

DELETE /api/apm/sourcemaps/{id}

Delete a previously uploaded source map.

Headers

  • elastic-api-version string Required

    The version of the API to use

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

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    Source map identifier

Responses

  • 200 application/json

    Successful response

    Additional properties are NOT allowed.

  • 400 application/json

    Bad Request response

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

    Unauthorized response

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

    Forbidden response

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

    Internal Server Error response

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

    Not Implemented response

    Hide response attributes Show response attributes object
DELETE /api/apm/sourcemaps/{id}
curl \
 --request DELETE https://<KIBANA_URL>/api/apm/sourcemaps/{id} \
 --header "elastic-api-version: 2023-10-31" \
 --header "kbn-xsrf: true"
Response examples (200)
{}
Response examples (400)
{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 400
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}
Response examples (403)
{
  "error": "Forbidden",
  "message": "string",
  "statusCode": 403
}
Response examples (500)
{
  "error": "Internal Server Error",
  "message": "string",
  "statusCode": 500
}
Response examples (501)
{
  "error": "Not Implemented",
  "message": "Not Implemented",
  "statusCode": 501
}

Connectors

Connectors provide a central place to store connection information for services and integrations with Elastic or third party systems. Alerting rules can use connectors to run actions when rule conditions are met.





Get connector information Beta

GET /api/actions/connector/{id}

Path parameters

  • id string Required

    An identifier for the connector.

Responses

  • 200 application/json

    Indicates a successful call.

    Hide response attributes Show response attributes object
    • config object

      Additional properties are allowed.

    • connector_type_id string Required

      The connector type identifier.

    • id string Required

      The identifier for the connector.

    • is_deprecated boolean Required

      Indicates whether the connector is deprecated.

    • Indicates whether the connector is missing secrets.

    • is_preconfigured boolean Required

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

    • is_system_action boolean Required

      Indicates whether the connector is used for system actions.

    • name string Required

      The name of the rule.

GET /api/actions/connector/{id}
curl \
 --request GET https://<KIBANA_URL>/api/actions/connector/{id}
Response examples (200)
{
  "id": "df770e30-8b8b-11ed-a780-3b746c987a81",
  "name": "my_server_log_connector",
  "config": {},
  "is_deprecated": false,
  "is_preconfigured": false,
  "is_system_action": false,
  "connector_type_id": ".server-log",
  "is_missing_secrets": false
}

Update a connector Beta

PUT /api/actions/connector/{id}

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    An identifier for the connector.

application/json

Body

  • name string Required

    The display name for the connector.

  • config object

    The connector configuration details.

    One of:

    Defines properties for connectors when type is .bedrock.

    Hide attributes Show attributes
    • apiUrl string Required

      The Amazon Bedrock request URL.

    • The generative artificial intelligence model for Amazon Bedrock to use. Current support is for the Anthropic Claude models.

      Default value is anthropic.claude-3-5-sonnet-20240620-v1:0.

  • secrets object

    One of:

    Defines secrets for connectors when type is .bedrock.

    Hide attributes Show attributes
    • accessKey string Required

      The AWS access key for authentication.

    • secret string Required

      The AWS secret for authentication.

Responses

  • 200 application/json

    Indicates a successful call.

    Hide response attributes Show response attributes object
    • config object

      Additional properties are allowed.

    • connector_type_id string Required

      The connector type identifier.

    • id string Required

      The identifier for the connector.

    • is_deprecated boolean Required

      Indicates whether the connector is deprecated.

    • Indicates whether the connector is missing secrets.

    • is_preconfigured boolean Required

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

    • is_system_action boolean Required

      Indicates whether the connector is used for system actions.

    • name string Required

      The name of the rule.

PUT /api/actions/connector/{id}
curl \
 --request PUT https://<KIBANA_URL>/api/actions/connector/{id} \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"name":"updated-connector","config":{"index":"updated-index"}}'
Request example
{
  "name": "updated-connector",
  "config": {
    "index": "updated-index"
  }
}
Response examples (200)
{
  "config": {},
  "connector_type_id": "string",
  "id": "string",
  "is_deprecated": true,
  "is_missing_secrets": true,
  "is_preconfigured": true,
  "is_system_action": true,
  "name": "string"
}

Create a connector Beta

POST /api/actions/connector/{id}

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    An identifier for the connector.

application/json

Body

  • connector_type_id string Required

    The type of connector.

  • name string Required

    The display name for the connector.

  • config object

    The connector configuration details.

    One of:

    Defines properties for connectors when type is .bedrock.

    Hide attributes Show attributes
    • apiUrl string Required

      The Amazon Bedrock request URL.

    • The generative artificial intelligence model for Amazon Bedrock to use. Current support is for the Anthropic Claude models.

      Default value is anthropic.claude-3-5-sonnet-20240620-v1:0.

  • secrets object

    One of:

    Defines secrets for connectors when type is .bedrock.

    Hide attributes Show attributes
    • accessKey string Required

      The AWS access key for authentication.

    • secret string Required

      The AWS secret for authentication.

Responses

  • 200 application/json

    Indicates a successful call.

    Hide response attributes Show response attributes object
    • config object

      Additional properties are allowed.

    • connector_type_id string Required

      The connector type identifier.

    • id string Required

      The identifier for the connector.

    • is_deprecated boolean Required

      Indicates whether the connector is deprecated.

    • Indicates whether the connector is missing secrets.

    • is_preconfigured boolean Required

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

    • is_system_action boolean Required

      Indicates whether the connector is used for system actions.

    • name string Required

      The name of the rule.

POST /api/actions/connector/{id}
curl \
 --request POST https://<KIBANA_URL>/api/actions/connector/{id} \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"name":"email-connector-1","config":{"from":"tester@example.com","host":"https://example.com","port":1025,"secure":false,"hasAuth":true,"service":"other"},"secrets":{"user":"username","password":"password"},"connector_type_id":".email"}'
{
  "name": "email-connector-1",
  "config": {
    "from": "tester@example.com",
    "host": "https://example.com",
    "port": 1025,
    "secure": false,
    "hasAuth": true,
    "service": "other"
  },
  "secrets": {
    "user": "username",
    "password": "password"
  },
  "connector_type_id": ".email"
}
{
  "name": "my-connector",
  "config": {
    "index": "test-index"
  },
  "connector_type_id": ".index"
}
{
  "name": "my-webhook-connector",
  "config": {
    "url": "https://example.com",
    "method": "post",
    "authType": "webhook-authentication-ssl",
    "certType": "ssl-crt-key"
  },
  "secrets": {
    "crt": "QmFnIEF0dH...",
    "key": "LS0tLS1CRUdJ...",
    "password": "my-passphrase"
  },
  "connector_type_id": ".webhook"
}
{
  "name": "my-xmatters-connector",
  "config": {
    "usesBasic": false
  },
  "secrets": {
    "secretsUrl": "https://example.com?apiKey=xxxxx"
  },
  "connector_type_id": ".xmatters"
}
{
  "id": "90a82c60-478f-11ee-a343-f98a117c727f",
  "name": "email-connector-1",
  "config": {
    "from": "tester@example.com",
    "host": "https://example.com",
    "port": 1025,
    "secure": false,
    "hasAuth": true,
    "service": "other",
    "clientId": null,
    "tenantId": null,
    "oauthTokenUrl": null
  },
  "is_deprecated": false,
  "is_preconfigured": false,
  "is_system_action": false,
  "connector_type_id": ".email",
  "is_missing_secrets": false
}
{
  "id": "c55b6eb0-6bad-11eb-9f3b-611eebc6c3ad",
  "name": "my-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
}
{
  "id": "900eb010-3b9d-11ee-a642-8ffbb94e38bd",
  "name": "my-webhook-connector",
  "config": {
    "url": "https://example.com",
    "method": "post",
    "hasAuth": true,
    "headers": null,
    "authType": "webhook-authentication-ssl",
    "certType": "ssl-crt-key",
    "verificationMode": "full"
  },
  "is_deprecated": false,
  "is_preconfigured": false,
  "is_system_action": false,
  "connector_type_id": ".webhook",
  "is_missing_secrets": false
}
{
  "id": "df770e30-8b8b-11ed-a780-3b746c987a81",
  "name": "my_server_log_connector",
  "config": {},
  "is_deprecated": false,
  "is_preconfigured": false,
  "is_system_action": false,
  "connector_type_id": ".server-log",
  "is_missing_secrets": false
}




Run a connector Beta

POST /api/actions/connector/{id}/_execute

You can use this API to test an action that involves interaction with Kibana services or integrations with third-party systems.

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    An identifier for the connector.

application/json

Body

  • params object Required

    One of:

    Test an action that acknowledges or resolves a PagerDuty alert.

    Hide attributes Show attributes
    • dedupKey string Required

      The deduplication key for the PagerDuty alert.

      Maximum length is 255.

    • eventAction string Required

      The type of event.

      Values are acknowledge or resolve.

Responses

  • 200 application/json

    Indicates a successful call.

    Hide response attributes Show response attributes object
    • config object

      Additional properties are allowed.

    • connector_type_id string Required

      The connector type identifier.

    • id string Required

      The identifier for the connector.

    • is_deprecated boolean Required

      Indicates whether the connector is deprecated.

    • Indicates whether the connector is missing secrets.

    • is_preconfigured boolean Required

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

    • is_system_action boolean Required

      Indicates whether the connector is used for system actions.

    • name string Required

      The name of the rule.

POST /api/actions/connector/{id}/_execute
curl \
 --request POST https://<KIBANA_URL>/api/actions/connector/{id}/_execute \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"params":{"documents":[{"id":"my_doc_id","name":"my_doc_name","message":"hello, world"}]}}'
{
  "params": {
    "documents": [
      {
        "id": "my_doc_id",
        "name": "my_doc_name",
        "message": "hello, world"
      }
    ]
  }
}
{
  "params": {
    "subAction": "issueTypes"
  }
}
{
  "params": {
    "subAction": "getChoices",
    "subActionParams": {
      "fields": [
        "severity",
        "urgency"
      ]
    }
  }
}
{
  "params": {
    "subAction": "postMessage",
    "subActionParams": {
      "text": "A test message.",
      "channelIds": [
        "C123ABC456"
      ]
    }
  }
}
{
  "params": {
    "subAction": "pushToService",
    "subActionParams": {
      "comments": [
        {
          "comment": "A comment about the incident.",
          "commentId": 1
        }
      ],
      "incident": {
        "caseId": "1000",
        "caseName": "Case name",
        "description": "Description of the incident."
      }
    }
  }
}
{
  "data": {
    "took": 135,
    "items": [
      {
        "create": {
          "_id": "4JtvwYUBrcyxt2NnfW3y",
          "_index": "my-index",
          "result": "created",
          "status": 201,
          "_seq_no": 0,
          "_shards": {
            "total": 2,
            "failed": 0,
            "successful": 1
          },
          "_version": 1,
          "_primary_term": 1
        }
      }
    ],
    "errors": false
  },
  "status": "ok",
  "connector_id": "fd38c600-96a5-11ed-bb79-353b74189cba"
}
{
  "data": [
    {
      "id": 10024,
      "name": "Improvement"
    },
    {
      "id": 10006,
      "name": "Task"
    },
    {
      "id": 10007,
      "name": "Sub-task"
    },
    {
      "id": 10025,
      "name": "New Feature"
    },
    {
      "id": 10023,
      "name": "Bug"
    },
    {
      "id": 10000,
      "name": "Epic"
    }
  ],
  "status": "ok",
  "connector_id": "b3aad810-edbe-11ec-82d1-11348ecbf4a6"
}
{
  "status": "ok",
  "connector_id": "7fc7b9a0-ecc9-11ec-8736-e7d63118c907"
}
{
  "data": [
    {
      "label": "Critical",
      "value": 1,
      "element": "severity",
      "dependent_value": ""
    },
    {
      "label": "Major",
      "value": 2,
      "element": "severity",
      "dependent_value": ""
    },
    {
      "label": "Minor",
      "value": 3,
      "element": "severity",
      "dependent_value": ""
    },
    {
      "label": "Warning",
      "value": 4,
      "element": "severity",
      "dependent_value": ""
    },
    {
      "label": "OK",
      "value": 5,
      "element": "severity",
      "dependent_value": ""
    },
    {
      "label": "Clear",
      "value": 0,
      "element": "severity",
      "dependent_value": ""
    },
    {
      "label": "1 - High",
      "value": 1,
      "element": "urgency",
      "dependent_value": ""
    },
    {
      "label": "2 - Medium",
      "value": 2,
      "element": "urgency",
      "dependent_value": ""
    },
    {
      "label": "3 - Low",
      "value": 3,
      "element": "urgency",
      "dependent_value": ""
    }
  ],
  "status": "ok",
  "connector_id": "9d9be270-2fd2-11ed-b0e0-87533c532698"
}
{
  "data": {
    "ok": true,
    "ts": "1234567890.123456",
    "channel": "C123ABC456",
    "message": {
      "ts": "1234567890.123456",
      "team": "T01ABCDE2F",
      "text": "A test message",
      "type": "message",
      "user": "U12A345BC6D",
      "app_id": "A01BC2D34EF",
      "blocks": [
        {
          "type": "rich_text",
          "block_id": "/NXe",
          "elements": [
            {
              "type": "rich_text_section",
              "elements": [
                {
                  "text": "A test message.",
                  "type": "text"
                }
              ]
            }
          ]
        }
      ],
      "bot_id": "B12BCDEFGHI",
      "bot_profile": {
        "id": "B12BCDEFGHI",
        "name": "test",
        "icons": {
          "image_36": "https://a.slack-edge.com/80588/img/plugins/app/bot_36.png"
        },
        "app_id": "A01BC2D34EF",
        "deleted": false,
        "team_id": "T01ABCDE2F",
        "updated": 1672169705
      }
    }
  },
  "status": "ok",
  "connector_id": ".slack_api"
}
{
  "data": {
    "id": "aKPmBHWzmdRQtx6Mx",
    "url": "https://elastic.swimlane.url.us/record/aNcL2xniGHGpa2AHb/aKPmBHWzmdRQtx6Mx",
    "title": "TEST-457",
    "comments": [
      {
        "commentId": 1,
        "pushedDate": "2022-09-08T16:52:27.865Z"
      }
    ],
    "pushedDate": "2022-09-08T16:52:27.866Z"
  },
  "status": "ok",
  "connector_id": "a4746470-2f94-11ed-b0e0-87533c532698"
}
















Create a dashboard Technical Preview

POST /api/dashboards/dashboard/{id}

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string

    A unique identifier for the dashboard.

application/json

Body

  • attributes object Required

    Additional properties are NOT allowed.

    Hide attributes attributes Show attributes attributes object
    • Additional properties are NOT allowed.

      Hide controlGroupInput attributes Show controlGroupInput attributes object
      • Show apply selections button in controls.

        Default value is true.

      • The chaining strategy for multiple controls. For example, "HIERARCHICAL" or "NONE".

        Values are NONE or HIERARCHICAL. Default value is HIERARCHICAL.

      • controls array[object]

        An array of control panels and their state in the control group.

        Default value is [] (empty).

        Hide controls attributes Show controls attributes object
        • Additional properties are allowed.

        • grow boolean

          Expand width of the control panel to fit available space.

          Default value is false.

        • id string

          The unique ID of the control.

        • order number Required

          The order of the control panel in the control group.

        • type string Required

          The type of the control panel.

        • width string

          Minimum width of the control panel in the control group.

          Values are small, medium, or large. Default value is medium.

      • Additional properties are allowed.

      • ignoreParentSettings object Required

        Additional properties are NOT allowed.

        Hide ignoreParentSettings attributes Show ignoreParentSettings attributes object
        • Ignore global filters in controls.

          Default value is false.

        • Ignore the global query bar in controls.

          Default value is false.

        • Ignore the global time range in controls.

          Default value is false.

        • Ignore validations in controls.

          Default value is false.

      • Position of the labels for controls. For example, "oneLine", "twoLine".

        Values are oneLine or twoLine. Default value is oneLine.

    • A short description.

      Default value is empty.

    • A container for various metadata

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

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

        Hide searchSource attributes Show searchSource attributes object
        • filter array[object]
          Hide filter attributes Show filter attributes object
          • $state object

            Additional properties are NOT allowed.

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

              Denote whether a filter is specific to an application's context (e.g. 'appState') or whether it should be applied globally (e.g. 'globalState').

              Values are appState or globalState.

          • meta object Required

            Additional properties are allowed.

            Hide meta attributes Show meta attributes object
          • query object

            Additional properties are allowed.

        • query object

          Additional properties are NOT allowed.

          Hide query attributes Show query attributes object
        • sort array[object]
        • type string
    • options object Required

      Additional properties are NOT allowed.

      Hide options attributes Show options attributes object
      • Hide the panel titles in the dashboard.

        Default value is false.

      • syncColors boolean

        Synchronize colors between related panels in the dashboard.

        Default value is true.

      • syncCursor boolean

        Synchronize cursor position between related panels in the dashboard.

        Default value is true.

      • Synchronize tooltips between related panels in the dashboard.

        Default value is true.

      • useMargins boolean

        Show margins between panels in the dashboard layout.

        Default value is true.

    • panels array[object]

      Default value is [] (empty).

      Hide panels attributes Show panels attributes object
      • gridData object Required

        Additional properties are NOT allowed.

        Hide gridData attributes Show gridData attributes object
        • h number

          The height of the panel in grid units

          Minimum value is 1. Default value is 15.

        • i string

          The unique identifier of the panel

        • w number

          The width of the panel in grid units

          Minimum value is 1, maximum value is 48. Default value is 24.

        • x number Required

          The x coordinate of the panel in grid units

        • y number Required

          The y coordinate of the panel in grid units

      • id string

        The saved object id for by reference panels

      • panelConfig object Required

        Additional properties are allowed.

        Hide panelConfig attributes Show panelConfig attributes object
      • The unique ID of the panel.

      • title string

        The title of the panel

      • type string Required

        The embeddable type

      • version string Deprecated

        The version was used to store Kibana version information from versions 7.3.0 -> 8.11.0. As of version 8.11.0, the versioning information is now per-embeddable-type and is stored on the embeddable's input. (panelConfig in this type).

    • A container for various refresh interval settings

      Additional properties are NOT allowed.

      Hide refreshInterval attributes Show refreshInterval attributes object
      • display string Deprecated

        A human-readable string indicating the refresh frequency. No longer used.

      • pause boolean Required

        Whether the refresh interval is set to be paused while viewing the dashboard.

      • section number Deprecated

        No longer used.

      • value number Required

        A numeric value indicating refresh frequency in milliseconds.

    • timeFrom string

      An ISO string indicating when to restore time from

    • Whether to restore time upon viewing this dashboard

      Default value is false.

    • timeTo string

      An ISO string indicating when to restore time from

    • title string Required

      A human-readable title for the dashboard

    • version number Deprecated
  • references array[object]
    Hide references attributes Show references attributes object
  • spaces array[string]

Responses

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

      Additional properties are allowed.

      Hide item attributes Show item attributes object
      • attributes object Required

        Additional properties are NOT allowed.

        Hide attributes attributes Show attributes attributes object
        • Additional properties are NOT allowed.

          Hide controlGroupInput attributes Show controlGroupInput attributes object
          • Show apply selections button in controls.

            Default value is true.

          • The chaining strategy for multiple controls. For example, "HIERARCHICAL" or "NONE".

            Values are NONE or HIERARCHICAL. Default value is HIERARCHICAL.

          • controls array[object]

            An array of control panels and their state in the control group.

            Default value is [] (empty).

            Hide controls attributes Show controls attributes object
            • Additional properties are allowed.

            • grow boolean

              Expand width of the control panel to fit available space.

              Default value is false.

            • id string

              The unique ID of the control.

            • order number Required

              The order of the control panel in the control group.

            • type string Required

              The type of the control panel.

            • width string

              Minimum width of the control panel in the control group.

              Values are small, medium, or large. Default value is medium.

          • Additional properties are allowed.

          • ignoreParentSettings object Required

            Additional properties are NOT allowed.

            Hide ignoreParentSettings attributes Show ignoreParentSettings attributes object
            • Ignore global filters in controls.

              Default value is false.

            • Ignore the global query bar in controls.

              Default value is false.

            • Ignore the global time range in controls.

              Default value is false.

            • Ignore validations in controls.

              Default value is false.

          • Position of the labels for controls. For example, "oneLine", "twoLine".

            Values are oneLine or twoLine. Default value is oneLine.

        • A short description.

          Default value is empty.

        • A container for various metadata

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

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

            Hide searchSource attributes Show searchSource attributes object
            • filter array[object]
              Hide filter attributes Show filter attributes object
              • $state object

                Additional properties are NOT allowed.

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

                  Denote whether a filter is specific to an application's context (e.g. 'appState') or whether it should be applied globally (e.g. 'globalState').

                  Values are appState or globalState.

              • meta object Required

                Additional properties are allowed.

                Hide meta attributes Show meta attributes object
              • query object

                Additional properties are allowed.

            • query object

              Additional properties are NOT allowed.

              Hide query attributes Show query attributes object
            • sort array[object]
            • type string
        • options object Required

          Additional properties are NOT allowed.

          Hide options attributes Show options attributes object
          • Hide the panel titles in the dashboard.

            Default value is false.

          • syncColors boolean

            Synchronize colors between related panels in the dashboard.

            Default value is true.

          • syncCursor boolean

            Synchronize cursor position between related panels in the dashboard.

            Default value is true.

          • Synchronize tooltips between related panels in the dashboard.

            Default value is true.

          • useMargins boolean

            Show margins between panels in the dashboard layout.

            Default value is true.

        • panels array[object]

          Default value is [] (empty).

          Hide panels attributes Show panels attributes object
          • gridData object Required

            Additional properties are NOT allowed.

            Hide gridData attributes Show gridData attributes object
            • h number

              The height of the panel in grid units

              Minimum value is 1. Default value is 15.

            • i string Required
            • w number

              The width of the panel in grid units

              Minimum value is 1, maximum value is 48. Default value is 24.

            • x number Required

              The x coordinate of the panel in grid units

            • y number Required

              The y coordinate of the panel in grid units

          • id string

            The saved object id for by reference panels

          • panelConfig object Required

            Additional properties are allowed.

            Hide panelConfig attributes Show panelConfig attributes object
          • panelIndex string Required
          • title string

            The title of the panel

          • type string Required

            The embeddable type

          • version string Deprecated

            The version was used to store Kibana version information from versions 7.3.0 -> 8.11.0. As of version 8.11.0, the versioning information is now per-embeddable-type and is stored on the embeddable's input. (panelConfig in this type).

        • A container for various refresh interval settings

          Additional properties are NOT allowed.

          Hide refreshInterval attributes Show refreshInterval attributes object
          • display string Deprecated

            A human-readable string indicating the refresh frequency. No longer used.

          • pause boolean Required

            Whether the refresh interval is set to be paused while viewing the dashboard.

          • section number Deprecated

            No longer used.

          • value number Required

            A numeric value indicating refresh frequency in milliseconds.

        • timeFrom string

          An ISO string indicating when to restore time from

        • Whether to restore time upon viewing this dashboard

          Default value is false.

        • timeTo string

          An ISO string indicating when to restore time from

        • title string Required

          A human-readable title for the dashboard

        • version number Deprecated
      • error object

        Additional properties are NOT allowed.

        Hide error attributes Show error attributes object
      • id string Required
      • managed boolean
      • namespaces array[string]
      • originId string
      • references array[object] Required
        Hide references attributes Show references attributes object
      • type string Required
      • version string
POST /api/dashboards/dashboard/{id}
curl \
 --request POST https://<KIBANA_URL>/api/dashboards/dashboard/{id} \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"attributes":{"controlGroupInput":{"autoApplySelections":true,"chainingSystem":"HIERARCHICAL","controls":[{"controlConfig":{},"grow":false,"id":"string","order":42.0,"type":"string","width":"medium"}],"enhancements":{},"ignoreParentSettings":{"ignoreFilters":false,"ignoreQuery":false,"ignoreTimerange":false,"ignoreValidations":false},"labelPosition":"oneLine"},"description":"","kibanaSavedObjectMeta":{"searchSource":{"filter":[{"$state":{"store":"appState"},"meta":{"alias":"string","controlledBy":"string","disabled":true,"field":"string","group":"string","index":"string","isMultiIndex":true,"key":"string","negate":true,"type":"string","value":"string"},"query":{}}],"query":{"language":"string","query":"string"},"sort":[{}],"type":"string"}},"options":{"hidePanelTitles":false,"syncColors":true,"syncCursor":true,"syncTooltips":true,"useMargins":true},"panels":[{"gridData":{"h":15,"i":"string","w":24,"x":42.0,"y":42.0},"id":"string","panelConfig":{"description":"string","enhancements":{},"hidePanelTitles":true,"savedObjectId":"string","title":"string","version":"string"},"panelIndex":"string","panelRefName":"string","title":"string","type":"string","version":"string"}],"refreshInterval":{"display":"string","pause":true,"section":42.0,"value":42.0},"timeFrom":"string","timeRestore":false,"timeTo":"string","title":"string","version":42.0},"references":[{"id":"string","name":"string","type":"string"}],"spaces":["string"]}'
Request examples
# Headers
kbn-xsrf: true

# Payload
{
  "attributes": {
    "controlGroupInput": {
      "autoApplySelections": true,
      "chainingSystem": "HIERARCHICAL",
      "controls": [
        {
          "controlConfig": {},
          "grow": false,
          "id": "string",
          "order": 42.0,
          "type": "string",
          "width": "medium"
        }
      ],
      "enhancements": {},
      "ignoreParentSettings": {
        "ignoreFilters": false,
        "ignoreQuery": false,
        "ignoreTimerange": false,
        "ignoreValidations": false
      },
      "labelPosition": "oneLine"
    },
    "description": "",
    "kibanaSavedObjectMeta": {
      "searchSource": {
        "filter": [
          {
            "$state": {
              "store": "appState"
            },
            "meta": {
              "alias": "string",
              "controlledBy": "string",
              "disabled": true,
              "field": "string",
              "group": "string",
              "index": "string",
              "isMultiIndex": true,
              "key": "string",
              "negate": true,
              "type": "string",
              "value": "string"
            },
            "query": {}
          }
        ],
        "query": {
          "language": "string",
          "query": "string"
        },
        "sort": [
          {}
        ],
        "type": "string"
      }
    },
    "options": {
      "hidePanelTitles": false,
      "syncColors": true,
      "syncCursor": true,
      "syncTooltips": true,
      "useMargins": true
    },
    "panels": [
      {
        "gridData": {
          "h": 15,
          "i": "string",
          "w": 24,
          "x": 42.0,
          "y": 42.0
        },
        "id": "string",
        "panelConfig": {
          "description": "string",
          "enhancements": {},
          "hidePanelTitles": true,
          "savedObjectId": "string",
          "title": "string",
          "version": "string"
        },
        "panelIndex": "string",
        "panelRefName": "string",
        "title": "string",
        "type": "string",
        "version": "string"
      }
    ],
    "refreshInterval": {
      "display": "string",
      "pause": true,
      "section": 42.0,
      "value": 42.0
    },
    "timeFrom": "string",
    "timeRestore": false,
    "timeTo": "string",
    "title": "string",
    "version": 42.0
  },
  "references": [
    {
      "id": "string",
      "name": "string",
      "type": "string"
    }
  ],
  "spaces": [
    "string"
  ]
}
Response examples (200)
{
  "item": {
    "attributes": {
      "controlGroupInput": {
        "autoApplySelections": true,
        "chainingSystem": "HIERARCHICAL",
        "controls": [
          {
            "controlConfig": {},
            "grow": false,
            "id": "string",
            "order": 42.0,
            "type": "string",
            "width": "medium"
          }
        ],
        "enhancements": {},
        "ignoreParentSettings": {
          "ignoreFilters": false,
          "ignoreQuery": false,
          "ignoreTimerange": false,
          "ignoreValidations": false
        },
        "labelPosition": "oneLine"
      },
      "description": "",
      "kibanaSavedObjectMeta": {
        "searchSource": {
          "filter": [
            {
              "$state": {
                "store": "appState"
              },
              "meta": {
                "alias": "string",
                "controlledBy": "string",
                "disabled": true,
                "field": "string",
                "group": "string",
                "index": "string",
                "isMultiIndex": true,
                "key": "string",
                "negate": true,
                "type": "string",
                "value": "string"
              },
              "query": {}
            }
          ],
          "query": {
            "language": "string",
            "query": "string"
          },
          "sort": [
            {}
          ],
          "type": "string"
        }
      },
      "options": {
        "hidePanelTitles": false,
        "syncColors": true,
        "syncCursor": true,
        "syncTooltips": true,
        "useMargins": true
      },
      "panels": [
        {
          "gridData": {
            "h": 15,
            "i": "string",
            "w": 24,
            "x": 42.0,
            "y": 42.0
          },
          "id": "string",
          "panelConfig": {
            "description": "string",
            "enhancements": {},
            "hidePanelTitles": true,
            "savedObjectId": "string",
            "title": "string",
            "version": "string"
          },
          "panelIndex": "string",
          "panelRefName": "string",
          "title": "string",
          "type": "string",
          "version": "string"
        }
      ],
      "refreshInterval": {
        "display": "string",
        "pause": true,
        "section": 42.0,
        "value": 42.0
      },
      "timeFrom": "string",
      "timeRestore": false,
      "timeTo": "string",
      "title": "string",
      "version": 42.0
    },
    "createdAt": "string",
    "createdBy": "string",
    "error": {
      "error": "string",
      "message": "string",
      "metadata": {},
      "statusCode": 42.0
    },
    "id": "string",
    "managed": true,
    "namespaces": [
      "string"
    ],
    "originId": "string",
    "references": [
      {
        "id": "string",
        "name": "string",
        "type": "string"
      }
    ],
    "type": "string",
    "updatedAt": "string",
    "updatedBy": "string",
    "version": "string"
  }
}

Delete a dashboard Technical Preview

DELETE /api/dashboards/dashboard/{id}

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    A unique identifier for the dashboard.

DELETE /api/dashboards/dashboard/{id}
curl \
 --request DELETE https://<KIBANA_URL>/api/dashboards/dashboard/{id} \
 --header "kbn-xsrf: true"














Create a data view Beta

POST /api/data_views/data_view

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

application/json

Body Required

  • data_view object Required

    The data view 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 Required

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

    • type string

      When set to rollup, identifies the rollup data views.

    • typeMeta object

      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
      • aggs object Required

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

        Additional properties are allowed.

      • params object Required

        Properties for retrieving rollup fields.

        Additional properties are allowed.

    • version string
  • override boolean

    Override an existing data view if a data view with the provided title already exists.

    Default value is false.

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

    Bad request

    Hide response attributes Show response attributes object
POST /api/data_views/data_view
curl \
 --request POST https://<KIBANA_URL>/api/data_views/data_view \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"data_view":{"name":"My Logstash data view","title":"logstash-*","runtimeFieldMap":{"runtime_shape_name":{"type":"keyword","script":{"source":"emit(doc['shape_name'].value)"}}}}}'
Request example
{
  "data_view": {
    "name": "My Logstash data view",
    "title": "logstash-*",
    "runtimeFieldMap": {
      "runtime_shape_name": {
        "type": "keyword",
        "script": {
          "source": "emit(doc['shape_name'].value)"
        }
      }
    }
  }
}
Response examples (200)
{
  "data_view": {
    "allowNoIndex": true,
    "fieldAttrs": {
      "additionalProperty1": {
        "count": 42,
        "customDescription": "string",
        "customLabel": "string"
      },
      "additionalProperty2": {
        "count": 42,
        "customDescription": "string",
        "customLabel": "string"
      }
    },
    "fieldFormats": {},
    "fields": {},
    "id": "ff959d40-b880-11e8-a6d9-e546fe2bba5f",
    "name": "string",
    "namespaces": [
      "default"
    ],
    "runtimeFieldMap": {
      "additionalProperty1": {
        "script": {
          "source": "string"
        },
        "type": "string"
      },
      "additionalProperty2": {
        "script": {
          "source": "string"
        },
        "type": "string"
      }
    },
    "sourceFilters": [
      {
        "value": "string"
      }
    ],
    "timeFieldName": "string",
    "title": "string",
    "typeMeta": {
      "aggs": {},
      "params": {}
    },
    "version": "WzQ2LDJd"
  }
}
Response examples (400)
{
  "error": "Bad Request",
  "message": "string",
  "statusCode": 400
}

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
}

Update a data view Beta

POST /api/data_views/data_view/{viewId}

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

Path parameters

  • viewId string Required

    An identifier for the data view.

application/json

Body Required

  • data_view object Required

    The data view properties you want to update. Only the specified properties are updated in the data view. Unspecified fields stay as they are persisted.

    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.

    • A map of field formats by field name.

      Additional properties are allowed.

    • fields object

      Additional properties are allowed.

    • name string
    • 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 (*).

    • type string

      When set to rollup, identifies the rollup data views.

    • typeMeta object

      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
      • aggs object Required

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

        Additional properties are allowed.

      • params object Required

        Properties for retrieving rollup fields.

        Additional properties are allowed.

  • Reloads the data view fields after the data view is updated.

    Default value is false.

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

    Bad request

    Hide response attributes Show response attributes object
POST /api/data_views/data_view/{viewId}
curl \
 --request POST https://<KIBANA_URL>/api/data_views/data_view/ff959d40-b880-11e8-a6d9-e546fe2bba5f \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"data_view":{"name":"Kibana Sample Data eCommerce","title":"kibana_sample_data_ecommerce","allowNoIndex":false,"timeFieldName":"order_date"},"refresh_fields":true}'
Request example
{
  "data_view": {
    "name": "Kibana Sample Data eCommerce",
    "title": "kibana_sample_data_ecommerce",
    "allowNoIndex": false,
    "timeFieldName": "order_date"
  },
  "refresh_fields": true
}
Response examples (200)
{
  "data_view": {
    "allowNoIndex": true,
    "fieldAttrs": {
      "additionalProperty1": {
        "count": 42,
        "customDescription": "string",
        "customLabel": "string"
      },
      "additionalProperty2": {
        "count": 42,
        "customDescription": "string",
        "customLabel": "string"
      }
    },
    "fieldFormats": {},
    "fields": {},
    "id": "ff959d40-b880-11e8-a6d9-e546fe2bba5f",
    "name": "string",
    "namespaces": [
      "default"
    ],
    "runtimeFieldMap": {
      "additionalProperty1": {
        "script": {
          "source": "string"
        },
        "type": "string"
      },
      "additionalProperty2": {
        "script": {
          "source": "string"
        },
        "type": "string"
      }
    },
    "sourceFilters": [
      {
        "value": "string"
      }
    ],
    "timeFieldName": "string",
    "title": "string",
    "typeMeta": {
      "aggs": {},
      "params": {}
    },
    "version": "WzQ2LDJd"
  }
}
Response examples (400)
{
  "error": "Bad Request",
  "message": "string",
  "statusCode": 400
}








Create or update a runtime field Beta

PUT /api/data_views/data_view/{viewId}/runtime_field

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

Path parameters

  • viewId string Required

    The ID of the data view fields you want to update.

application/json

Body Required

  • name string Required

    The name for a runtime field.

  • runtimeField object Required

    The runtime field definition object.

    Additional properties are allowed.

Responses

  • 200 application/json

    Indicates a successful call.

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

    • fields array[object]

      Additional properties are allowed.

  • 400 application/json

    Bad request

    Hide response attributes Show response attributes object
PUT /api/data_views/data_view/{viewId}/runtime_field
curl \
 --request PUT https://<KIBANA_URL>/api/data_views/data_view/{viewId}/runtime_field \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"name":"runtimeFoo","runtimeField":{"type":"long","script":{"source":"emit(doc[\"foo\"].value)"}}}'
Request example
{
  "name": "runtimeFoo",
  "runtimeField": {
    "type": "long",
    "script": {
      "source": "emit(doc[\"foo\"].value)"
    }
  }
}
Response examples (200)
{
  "data_view": {},
  "fields": [
    {}
  ]
}
Response examples (400)
{
  "error": "Bad Request",
  "message": "string",
  "statusCode": 400
}

Create a runtime field Beta

POST /api/data_views/data_view/{viewId}/runtime_field

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

Path parameters

  • viewId string Required

    An identifier for the data view.

application/json

Body Required

  • name string Required

    The name for a runtime field.

  • runtimeField object Required

    The runtime field definition object.

    Additional properties are allowed.

Responses

  • 200 application/json

    Indicates a successful call.

    Additional properties are allowed.

POST /api/data_views/data_view/{viewId}/runtime_field
curl \
 --request POST https://<KIBANA_URL>/api/data_views/data_view/ff959d40-b880-11e8-a6d9-e546fe2bba5f/runtime_field \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"name":"runtimeFoo","runtimeField":{"type":"long","script":{"source":"emit(doc[\"foo\"].value)"}}}'
Request example
{
  "name": "runtimeFoo",
  "runtimeField": {
    "type": "long",
    "script": {
      "source": "emit(doc[\"foo\"].value)"
    }
  }
}
Response examples (200)
{}












































Upgrade an agent Beta

POST /api/fleet/agents/{agentId}/upgrade

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

application/json

Body

Responses

  • 200 application/json

    Additional properties are NOT allowed.

  • 400 application/json
    Hide response attributes Show response attributes object
POST /api/fleet/agents/{agentId}/upgrade
curl \
 --request POST https://<KIBANA_URL>/api/fleet/agents/{agentId}/upgrade \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"force":true,"skipRateLimitCheck":true,"source_uri":"string","version":"string"}'
Request examples
# Headers
kbn-xsrf: true

# Payload
{
  "force": true,
  "skipRateLimitCheck": true,
  "source_uri": "string",
  "version": "string"
}
Response examples (200)
{}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}
























Bulk upgrade agents Beta

POST /api/fleet/agents/bulk_upgrade

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

application/json

Body

Responses

POST /api/fleet/agents/bulk_upgrade
curl \
 --request POST https://<KIBANA_URL>/api/fleet/agents/bulk_upgrade \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"agents":["string"],"batchSize":42.0,"force":true,"includeInactive":false,"rollout_duration_seconds":42.0,"skipRateLimitCheck":true,"source_uri":"string","start_time":"string","version":"string"}'
Request examples
# Headers
kbn-xsrf: true

# Payload
{
  "agents": [
    "string"
  ],
  "batchSize": 42.0,
  "force": true,
  "includeInactive": false,
  "rollout_duration_seconds": 42.0,
  "skipRateLimitCheck": true,
  "source_uri": "string",
  "start_time": "string",
  "version": "string"
}
Response examples (200)
{
  "actionId": "string"
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}

Get agent binary download sources Beta

GET /api/fleet/agent_download_sources

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

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • items array[object] Required
      Hide items attributes Show items attributes object
      • host 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.

    • page number Required
    • perPage number Required
    • total number Required
  • 400 application/json
    Hide response attributes Show response attributes object
GET /api/fleet/agent_download_sources
curl \
 --request GET https://<KIBANA_URL>/api/fleet/agent_download_sources
Response examples (200)
{
  "items": [
    {
      "host": "https://example.com",
      "id": "string",
      "is_default": 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
}








Update an agent binary download source Beta

PUT /api/fleet/agent_download_sources/{sourceId}

Update an agent binary download source by ID.

[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
PUT /api/fleet/agent_download_sources/{sourceId}
curl \
 --request PUT https://<KIBANA_URL>/api/fleet/agent_download_sources/{sourceId} \
 --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
}













Bulk get agent policies Beta

POST /api/fleet/agent_policies/_bulk_get

[Required authorization] Route required privileges: ANY of [fleet-agent-policies-read OR fleet-agents-read OR fleet-setup].

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Query parameters

  • format string

    Values are simplified or legacy.

application/json

Body

  • full boolean

    get full policies with package policies populated

  • ids array[string] Required

    list of package policy ids

Responses

POST /api/fleet/agent_policies/_bulk_get
curl \
 --request POST https://<KIBANA_URL>/api/fleet/agent_policies/_bulk_get \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"full":true,"ids":["string"],"ignoreMissing":true}'
Request examples
# Headers
kbn-xsrf: true

# Payload
{
  "full": true,
  "ids": [
    "string"
  ],
  "ignoreMissing": true
}
Response examples (200)
{
  "items": [
    {
      "advanced_settings": {},
      "agent_features": [
        {
          "enabled": true,
          "name": "string"
        }
      ],
      "agentless": {
        "resources": {
          "requests": {
            "cpu": "string",
            "memory": "string"
          }
        }
      },
      "agents": 42.0,
      "data_output_id": "string",
      "description": "string",
      "download_source_id": "string",
      "fleet_server_host_id": "string",
      "global_data_tags": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "has_fleet_server": true,
      "id": "string",
      "inactivity_timeout": 1209600,
      "is_default": true,
      "is_default_fleet_server": true,
      "is_managed": true,
      "is_preconfigured": true,
      "is_protected": true,
      "keep_monitoring_alive": false,
      "monitoring_diagnostics": {
        "limit": {
          "burst": 42.0,
          "interval": "string"
        },
        "uploader": {
          "init_dur": "string",
          "max_dur": "string",
          "max_retries": 42.0
        }
      },
      "monitoring_enabled": [
        "logs"
      ],
      "monitoring_http": {
        "buffer": {
          "enabled": false
        },
        "enabled": true,
        "host": "string",
        "port": 42.0
      },
      "monitoring_output_id": "string",
      "monitoring_pprof_enabled": true,
      "name": "string",
      "namespace": "string",
      "overrides": {},
      "package_policies": [
        "string"
      ],
      "required_versions": [
        {
          "percentage": 42.0,
          "version": "string"
        }
      ],
      "revision": 42.0,
      "schema_version": "string",
      "space_ids": [
        "string"
      ],
      "status": "active",
      "supports_agentless": false,
      "unenroll_timeout": 42.0,
      "unprivileged_agents": 42.0,
      "updated_at": "string",
      "updated_by": "string",
      "version": "string"
    }
  ]
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}

Get an agent policy Beta

GET /api/fleet/agent_policies/{agentPolicyId}

Get an agent policy by ID.

[Required authorization] Route required privileges: ANY of [fleet-agent-policies-read OR fleet-agents-read OR fleet-setup].

Query parameters

  • format string

    Values are simplified or legacy.

Responses

GET /api/fleet/agent_policies/{agentPolicyId}
curl \
 --request GET https://<KIBANA_URL>/api/fleet/agent_policies/{agentPolicyId}
Response examples (200)
{
  "item": {
    "advanced_settings": {},
    "agent_features": [
      {
        "enabled": true,
        "name": "string"
      }
    ],
    "agentless": {
      "resources": {
        "requests": {
          "cpu": "string",
          "memory": "string"
        }
      }
    },
    "agents": 42.0,
    "data_output_id": "string",
    "description": "string",
    "download_source_id": "string",
    "fleet_server_host_id": "string",
    "global_data_tags": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "has_fleet_server": true,
    "id": "string",
    "inactivity_timeout": 1209600,
    "is_default": true,
    "is_default_fleet_server": true,
    "is_managed": true,
    "is_preconfigured": true,
    "is_protected": true,
    "keep_monitoring_alive": false,
    "monitoring_diagnostics": {
      "limit": {
        "burst": 42.0,
        "interval": "string"
      },
      "uploader": {
        "init_dur": "string",
        "max_dur": "string",
        "max_retries": 42.0
      }
    },
    "monitoring_enabled": [
      "logs"
    ],
    "monitoring_http": {
      "buffer": {
        "enabled": false
      },
      "enabled": true,
      "host": "string",
      "port": 42.0
    },
    "monitoring_output_id": "string",
    "monitoring_pprof_enabled": true,
    "name": "string",
    "namespace": "string",
    "overrides": {},
    "package_policies": [
      "string"
    ],
    "required_versions": [
      {
        "percentage": 42.0,
        "version": "string"
      }
    ],
    "revision": 42.0,
    "schema_version": "string",
    "space_ids": [
      "string"
    ],
    "status": "active",
    "supports_agentless": false,
    "unenroll_timeout": 42.0,
    "unprivileged_agents": 42.0,
    "updated_at": "string",
    "updated_by": "string",
    "version": "string"
  }
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}








Download an agent policy Beta

GET /api/fleet/agent_policies/{agentPolicyId}/download

Download an agent policy by ID.

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

Responses

GET /api/fleet/agent_policies/{agentPolicyId}/download
curl \
 --request GET https://<KIBANA_URL>/api/fleet/agent_policies/{agentPolicyId}/download
Response examples (200)
string
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}
Response examples (404)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}
















Get a full K8s agent manifest Beta

GET /api/fleet/kubernetes

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

Responses

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














Get agents Beta

GET /api/fleet/agents

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

Query parameters

Responses

GET /api/fleet/agents
curl \
 --request GET https://<KIBANA_URL>/api/fleet/agents
Response examples (200)
{
  "items": [
    {
      "access_api_key": "string",
      "access_api_key_id": "string",
      "active": true,
      "agent": {
        "id": "string",
        "version": "string"
      },
      "audit_unenrolled_reason": "string",
      "components": [
        {
          "id": "string",
          "message": "string",
          "status": "STARTING",
          "type": "string",
          "units": [
            {
              "id": "string",
              "message": "string",
              "payload": {},
              "status": "STARTING",
              "type": "input"
            }
          ]
        }
      ],
      "default_api_key": "string",
      "default_api_key_history": [
        {
          "id": "string",
          "retired_at": "string"
        }
      ],
      "default_api_key_id": "string",
      "enrolled_at": "string",
      "id": "string",
      "last_checkin": "string",
      "last_checkin_message": "string",
      "last_checkin_status": "error",
      "local_metadata": {},
      "metrics": {
        "cpu_avg": 42.0,
        "memory_size_byte_avg": 42.0
      },
      "namespaces": [
        "string"
      ],
      "outputs": {
        "additionalProperty1": {
          "api_key_id": "string",
          "to_retire_api_key_ids": [
            {
              "id": "string",
              "retired_at": "string"
            }
          ],
          "type": "string"
        },
        "additionalProperty2": {
          "api_key_id": "string",
          "to_retire_api_key_ids": [
            {
              "id": "string",
              "retired_at": "string"
            }
          ],
          "type": "string"
        }
      },
      "packages": [
        "string"
      ],
      "policy_id": "string",
      "policy_revision": 42.0,
      "sort": [
        42.0
      ],
      "status": "offline",
      "tags": [
        "string"
      ],
      "type": "PERMANENT",
      "unenrolled_at": "string",
      "unenrollment_started_at": "string",
      "unhealthy_reason": [
        "input"
      ],
      "upgrade_details": {
        "action_id": "string",
        "metadata": {
          "download_percent": 42.0,
          "download_rate": 42.0,
          "error_msg": "string",
          "failed_state": "UPG_REQUESTED",
          "retry_error_msg": "string",
          "retry_until": "string",
          "scheduled_at": "string"
        },
        "state": "UPG_REQUESTED",
        "target_version": "string"
      },
      "upgrade_started_at": "string",
      "upgraded_at": "string",
      "user_provided_metadata": {}
    }
  ],
  "page": 42.0,
  "perPage": 42.0,
  "statusSummary": {
    "additionalProperty1": 42.0,
    "additionalProperty2": 42.0
  },
  "total": 42.0
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}




Get an agent Beta

GET /api/fleet/agents/{agentId}

Get an agent by ID.

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

Query parameters

Responses

GET /api/fleet/agents/{agentId}
curl \
 --request GET https://<KIBANA_URL>/api/fleet/agents/{agentId}
Response examples (200)
{
  "item": {
    "access_api_key": "string",
    "access_api_key_id": "string",
    "active": true,
    "agent": {
      "id": "string",
      "version": "string"
    },
    "audit_unenrolled_reason": "string",
    "components": [
      {
        "id": "string",
        "message": "string",
        "status": "STARTING",
        "type": "string",
        "units": [
          {
            "id": "string",
            "message": "string",
            "payload": {},
            "status": "STARTING",
            "type": "input"
          }
        ]
      }
    ],
    "default_api_key": "string",
    "default_api_key_history": [
      {
        "id": "string",
        "retired_at": "string"
      }
    ],
    "default_api_key_id": "string",
    "enrolled_at": "string",
    "id": "string",
    "last_checkin": "string",
    "last_checkin_message": "string",
    "last_checkin_status": "error",
    "local_metadata": {},
    "metrics": {
      "cpu_avg": 42.0,
      "memory_size_byte_avg": 42.0
    },
    "namespaces": [
      "string"
    ],
    "outputs": {
      "additionalProperty1": {
        "api_key_id": "string",
        "to_retire_api_key_ids": [
          {
            "id": "string",
            "retired_at": "string"
          }
        ],
        "type": "string"
      },
      "additionalProperty2": {
        "api_key_id": "string",
        "to_retire_api_key_ids": [
          {
            "id": "string",
            "retired_at": "string"
          }
        ],
        "type": "string"
      }
    },
    "packages": [
      "string"
    ],
    "policy_id": "string",
    "policy_revision": 42.0,
    "sort": [
      42.0
    ],
    "status": "offline",
    "tags": [
      "string"
    ],
    "type": "PERMANENT",
    "unenrolled_at": "string",
    "unenrollment_started_at": "string",
    "unhealthy_reason": [
      "input"
    ],
    "upgrade_details": {
      "action_id": "string",
      "metadata": {
        "download_percent": 42.0,
        "download_rate": 42.0,
        "error_msg": "string",
        "failed_state": "UPG_REQUESTED",
        "retry_error_msg": "string",
        "retry_until": "string",
        "scheduled_at": "string"
      },
      "state": "UPG_REQUESTED",
      "target_version": "string"
    },
    "upgrade_started_at": "string",
    "upgraded_at": "string",
    "user_provided_metadata": {}
  }
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}




Delete an agent Beta

DELETE /api/fleet/agents/{agentId}

Delete an agent by ID.

[Required authorization] Route required privileges: ALL of [fleet-agents-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
    • action string Required

      Value is deleted.

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








Delete an uploaded file Beta

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

Delete a file uploaded by an agent.

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Responses

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




Get agent setup info Beta

GET /api/fleet/agents/setup

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

Responses

GET /api/fleet/agents/setup
curl \
 --request GET https://<KIBANA_URL>/api/fleet/agents/setup
Response examples (200)
{
  "is_secrets_storage_enabled": true,
  "is_space_awareness_enabled": true,
  "isReady": true,
  "missing_optional_features": [
    "encrypted_saved_object_encryption_key_required"
  ],
  "missing_requirements": [
    "security_required"
  ],
  "package_verification_key_id": "string"
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}

Initiate agent setup Beta

POST /api/fleet/agents/setup

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Responses

POST /api/fleet/agents/setup
curl \
 --request POST https://<KIBANA_URL>/api/fleet/agents/setup \
 --header "kbn-xsrf: true"
Response examples (200)
{
  "isInitialized": true,
  "nonFatalErrors": [
    {
      "message": "string",
      "name": "string"
    }
  ]
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}




































Install a package from the registry Beta

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

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

Query parameters

application/json

Body

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • _meta object Required

      Additional properties are NOT allowed.

      Hide _meta attribute Show _meta attribute object
    • items array[object] Required
      Any of:
      Hide attributes Show attributes
      • id string Required
      • originId string
      • type string Required

        Values are dashboard, lens, visualization, search, index-pattern, map, ml-module, security-rule, csp-rule-template, osquery-pack-asset, osquery-saved-query, or tag.

  • 400 application/json
    Hide response attributes Show response attributes object
POST /api/fleet/epm/packages/{pkgName}/{pkgVersion}
curl \
 --request POST https://<KIBANA_URL>/api/fleet/epm/packages/{pkgName}/{pkgVersion} \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"force":false,"ignore_constraints":false}'
Request examples
# Headers
kbn-xsrf: true

# Payload
{
  "force": false,
  "ignore_constraints": false
}
Response examples (200)
{
  "_meta": {
    "install_source": "string"
  },
  "items": [
    {
      "id": "string",
      "originId": "string",
      "type": "dashboard"
    }
  ]
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}

Delete a package Beta

DELETE /api/fleet/epm/packages/{pkgName}/{pkgVersion}

[Required authorization] Route required privileges: ALL of [integrations-all, fleet-agent-policies-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
    • items array[object] Required
      Any of:
      Hide attributes Show attributes
      • id string Required
      • originId string
      • type string Required

        Values are dashboard, lens, visualization, search, index-pattern, map, ml-module, security-rule, csp-rule-template, osquery-pack-asset, osquery-saved-query, or tag.

  • 400 application/json
    Hide response attributes Show response attributes object
DELETE /api/fleet/epm/packages/{pkgName}/{pkgVersion}
curl \
 --request DELETE https://<KIBANA_URL>/api/fleet/epm/packages/{pkgName}/{pkgVersion} \
 --header "kbn-xsrf: true"
Response examples (200)
{
  "items": [
    {
      "id": "string",
      "originId": "string",
      "type": "dashboard"
    }
  ]
}
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
}





















Get enrollment API keys Beta

GET /api/fleet/enrollment_api_keys

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

Query parameters

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • items array[object] Required
      Hide items attributes Show items attributes object
      • active boolean Required

        When false, the enrollment API key is revoked and cannot be used for enrolling Elastic Agents.

      • api_key string Required

        The enrollment API key (token) used for enrolling Elastic Agents.

      • api_key_id string Required

        The ID of the API key in the Security API.

      • created_at string Required
      • id string Required
      • name string

        The name of the enrollment API key.

      • The ID of the agent policy the Elastic Agent will be enrolled in.

    • list array[object] Required Deprecated
      Hide list attributes Show list attributes object
      • active boolean Required

        When false, the enrollment API key is revoked and cannot be used for enrolling Elastic Agents.

      • api_key string Required

        The enrollment API key (token) used for enrolling Elastic Agents.

      • api_key_id string Required

        The ID of the API key in the Security API.

      • created_at string Required
      • id string Required
      • name string

        The name of the enrollment API key.

      • The ID of the agent policy the Elastic Agent will be enrolled in.

    • page number Required
    • perPage number Required
    • total number Required
  • 400 application/json
    Hide response attributes Show response attributes object
GET /api/fleet/enrollment_api_keys
curl \
 --request GET https://<KIBANA_URL>/api/fleet/enrollment_api_keys
Response examples (200)
{
  "items": [
    {
      "active": true,
      "api_key": "string",
      "api_key_id": "string",
      "created_at": "string",
      "id": "string",
      "name": "string",
      "policy_id": "string"
    }
  ],
  "list": [
    {
      "active": true,
      "api_key": "string",
      "api_key_id": "string",
      "created_at": "string",
      "id": "string",
      "name": "string",
      "policy_id": "string"
    }
  ],
  "page": 42.0,
  "perPage": 42.0,
  "total": 42.0
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}

Create an enrollment API key Beta

POST /api/fleet/enrollment_api_keys

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

application/json

Body

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • action string Required

      Value is created.

    • item object Required

      Additional properties are NOT allowed.

      Hide item attributes Show item attributes object
      • active boolean Required

        When false, the enrollment API key is revoked and cannot be used for enrolling Elastic Agents.

      • api_key string Required

        The enrollment API key (token) used for enrolling Elastic Agents.

      • api_key_id string Required

        The ID of the API key in the Security API.

      • created_at string Required
      • id string Required
      • name string

        The name of the enrollment API key.

      • The ID of the agent policy the Elastic Agent will be enrolled in.

  • 400 application/json
    Hide response attributes Show response attributes object
POST /api/fleet/enrollment_api_keys
curl \
 --request POST https://<KIBANA_URL>/api/fleet/enrollment_api_keys \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"expiration":"string","name":"string","policy_id":"string"}'
Request examples
# Headers
kbn-xsrf: true

# Payload
{
  "expiration": "string",
  "name": "string",
  "policy_id": "string"
}
Response examples (200)
{
  "action": "created",
  "item": {
    "active": true,
    "api_key": "string",
    "api_key_id": "string",
    "created_at": "string",
    "id": "string",
    "name": "string",
    "policy_id": "string"
  }
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}

Get an enrollment API key Beta

GET /api/fleet/enrollment_api_keys/{keyId}

Get an enrollment API key by ID.

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

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
      • active boolean Required

        When false, the enrollment API key is revoked and cannot be used for enrolling Elastic Agents.

      • api_key string Required

        The enrollment API key (token) used for enrolling Elastic Agents.

      • api_key_id string Required

        The ID of the API key in the Security API.

      • created_at string Required
      • id string Required
      • name string

        The name of the enrollment API key.

      • The ID of the agent policy the Elastic Agent will be enrolled in.

  • 400 application/json
    Hide response attributes Show response attributes object
GET /api/fleet/enrollment_api_keys/{keyId}
curl \
 --request GET https://<KIBANA_URL>/api/fleet/enrollment_api_keys/{keyId}
Response examples (200)
{
  "item": {
    "active": true,
    "api_key": "string",
    "api_key_id": "string",
    "created_at": "string",
    "id": "string",
    "name": "string",
    "policy_id": "string"
  }
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}








































































































Update a proxy Beta

PUT /api/fleet/proxies/{itemId}

Update a proxy by ID.

[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

Responses

PUT /api/fleet/proxies/{itemId}
curl \
 --request PUT https://<KIBANA_URL>/api/fleet/proxies/{itemId} \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"certificate":"string","certificate_authorities":"string","certificate_key":"string","name":"string","proxy_headers":{},"url":"string"}'
Request examples
# Headers
kbn-xsrf: true

# Payload
{
  "certificate": "string",
  "certificate_authorities": "string",
  "certificate_key": "string",
  "name": "string",
  "proxy_headers": {},
  "url": "string"
}
Response examples (200)
{
  "item": {
    "certificate": "string",
    "certificate_authorities": "string",
    "certificate_key": "string",
    "id": "string",
    "is_preconfigured": false,
    "name": "string",
    "proxy_headers": {},
    "url": "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
}












Delete a Fleet Server host Beta

DELETE /api/fleet/fleet_server_hosts/{itemId}

Delete a Fleet Server host by ID.

[Required authorization] Route required privileges: ALL of [fleet-settings-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/fleet_server_hosts/{itemId}
curl \
 --request DELETE https://<KIBANA_URL>/api/fleet/fleet_server_hosts/{itemId} \
 --header "kbn-xsrf: true"
Response examples (200)
{
  "id": "string"
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}










Get a decrypted uninstall token Beta

GET /api/fleet/uninstall_tokens/{uninstallTokenId}

Get one decrypted uninstall token by its ID.

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

Responses

GET /api/fleet/uninstall_tokens/{uninstallTokenId}
curl \
 --request GET https://<KIBANA_URL>/api/fleet/uninstall_tokens/{uninstallTokenId}
Response examples (200)
{
  "item": {
    "created_at": "string",
    "id": "string",
    "namespaces": [
      "string"
    ],
    "policy_id": "string",
    "policy_name": "string",
    "token": "string"
  }
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}






Sync machine learning saved objects Beta

GET /api/ml/saved_objects/sync

Synchronizes Kibana saved objects for machine learning jobs and trained models. This API runs automatically when you start Kibana and periodically thereafter.

Query parameters

  • simulate boolean

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

Responses

  • 200 application/json

    Indicates a successful call

    Hide response attributes Show response attributes object
    • If a saved object for an anomaly detection job is missing a datafeed identifier, it is added when you run the sync machine learning saved objects API.

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

        The sync machine learning saved objects API response contains this object when there are datafeeds affected by the synchronization. There is an object for each relevant datafeed, which contains the synchronization status.

        Additional properties are allowed.

        Hide * attribute Show * attribute object
        • success boolean

          The success or failure of the synchronization.

    • If a saved object for an anomaly detection job references a datafeed that no longer exists, it is deleted when you run the sync machine learning saved objects API.

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

        The sync machine learning saved objects API response contains this object when there are datafeeds affected by the synchronization. There is an object for each relevant datafeed, which contains the synchronization status.

        Additional properties are allowed.

        Hide * attribute Show * attribute object
        • success boolean

          The success or failure of the synchronization.

    • If saved objects are missing for machine learning jobs or trained models, they are created when you run the sync machine learning saved objects API.

      Additional properties are allowed.

      Hide savedObjectsCreated attributes Show savedObjectsCreated attributes object
      • If saved objects are missing for anomaly detection jobs, they are created.

        Hide anomaly-detector attribute Show anomaly-detector attribute object
        • * object Additional properties

          The sync machine learning saved objects API response contains this object when there are anomaly detection jobs affected by the synchronization. There is an object for each relevant job, which contains the synchronization status.

          Additional properties are allowed.

          Hide * attribute Show * attribute object
          • success boolean

            The success or failure of the synchronization.

      • If saved objects are missing for data frame analytics jobs, they are created.

        Hide data-frame-analytics attribute Show data-frame-analytics attribute object
        • * object Additional properties

          The sync machine learning saved objects API response contains this object when there are data frame analytics jobs affected by the synchronization. There is an object for each relevant job, which contains the synchronization status.

          Additional properties are allowed.

          Hide * attribute Show * attribute object
          • success boolean

            The success or failure of the synchronization.

      • If saved objects are missing for trained models, they are created.

        Hide trained-model attribute Show trained-model attribute object
        • * object Additional properties

          The sync machine learning saved objects API response contains this object when there are trained models affected by the synchronization. There is an object for each relevant trained model, which contains the synchronization status.

          Additional properties are allowed.

          Hide * attribute Show * attribute object
          • success boolean

            The success or failure of the synchronization.

    • If saved objects exist for machine learning jobs or trained models that no longer exist, they are deleted when you run the sync machine learning saved objects API.

      Additional properties are allowed.

      Hide savedObjectsDeleted attributes Show savedObjectsDeleted attributes object
      • If there are saved objects exist for nonexistent anomaly detection jobs, they are deleted.

        Hide anomaly-detector attribute Show anomaly-detector attribute object
        • * object Additional properties

          The sync machine learning saved objects API response contains this object when there are anomaly detection jobs affected by the synchronization. There is an object for each relevant job, which contains the synchronization status.

          Additional properties are allowed.

          Hide * attribute Show * attribute object
          • success boolean

            The success or failure of the synchronization.

      • If there are saved objects exist for nonexistent data frame analytics jobs, they are deleted.

        Hide data-frame-analytics attribute Show data-frame-analytics attribute object
        • * object Additional properties

          The sync machine learning saved objects API response contains this object when there are data frame analytics jobs affected by the synchronization. There is an object for each relevant job, which contains the synchronization status.

          Additional properties are allowed.

          Hide * attribute Show * attribute object
          • success boolean

            The success or failure of the synchronization.

      • If there are saved objects exist for nonexistent trained models, they are deleted.

        Hide trained-model attribute Show trained-model attribute object
        • * object Additional properties

          The sync machine learning saved objects API response contains this object when there are trained models affected by the synchronization. There is an object for each relevant trained model, which contains the synchronization status.

          Additional properties are allowed.

          Hide * attribute Show * attribute object
          • success boolean

            The success or failure of the synchronization.

  • 401 application/json

    Authorization information is missing or invalid.

    Hide response attributes Show response attributes object
GET /api/ml/saved_objects/sync
curl \
 --request GET https://<KIBANA_URL>/api/ml/saved_objects/sync
Response examples (200)
{
  "datafeedsAdded": {},
  "datafeedsRemoved": {},
  "savedObjectsCreated": {
    "anomaly-detector": {
      "myjob1": {
        "success": true
      },
      "myjob2": {
        "success": true
      }
    }
  },
  "savedObjectsDeleted": {}
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}





Get a role Beta

GET /api/security/role/{name}

Path parameters

  • name string Required

    The role name.

    Minimum length is 1.

Query parameters

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

Responses

  • Indicates a successful call.

GET /api/security/role/{name}
curl \
 --request GET https://<KIBANA_URL>/api/security/role/{name}

Create or update a role Beta

PUT /api/security/role/{name}

Create a new Kibana role or update the attributes of an existing role. Kibana roles are stored in the Elasticsearch native realm.

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • name string Required

    The role name.

    Minimum length is 1, maximum length is 1024.

Query parameters

  • createOnly boolean

    When true, a role is not overwritten if it already exists.

    Default value is false.

application/json

Body

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

PUT /api/security/role/{name}
curl \
 --request PUT https://<KIBANA_URL>/api/security/role/{name} \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"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
{
  "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": {}
}









Export saved objects Beta

POST /api/saved_objects/_export

Retrieve sets of saved objects that you want to import into Kibana. You must include type or objects in the request body.

Exported saved objects are not backwards compatible and cannot be imported into an older version of Kibana.

NOTE: The savedObjects.maxImportExportSize configuration setting limits the number of saved objects which may be exported.

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

application/json

Body Required

Responses

  • 200 application/x-ndjson

    Indicates a successful call.

    Additional properties are allowed.

  • 400 application/json

    Bad request.

    Hide response attributes Show response attributes object
POST /api/saved_objects/_export
curl \
 --request POST https://<KIBANA_URL>/api/saved_objects/_export \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"objects":[{"id":"de71f4f0-1902-11e9-919b-ffe5949a18d2","type":"map"}],"excludeExportDetails":true,"includeReferencesDeep":false}'
Request example
{
  "objects": [
    {
      "id": "de71f4f0-1902-11e9-919b-ffe5949a18d2",
      "type": "map"
    }
  ],
  "excludeExportDetails": true,
  "includeReferencesDeep": false
}
Response examples (200)
{
  "id": "de71f4f0-1902-11e9-919b-ffe5949a18d2",
  "type": "map",
  "managed": false,
  "version": "WzEzLDFd",
  "attributes": {
    "title": "[Logs] Total Requests and Bytes",
    "description": "",
    "uiStateJSON": "{\"isDarkMode\":false}",
    "mapStateJSON": "{\"zoom\":3.64,\"center\":{\"lon\":-88.92107,\"lat\":42.16337},\"timeFilters\":{\"from\":\"now-7d\",\"to\":\"now\"},\"refreshConfig\":{\"isPaused\":true,\"interval\":0},\"query\":{\"language\":\"kuery\",\"query\":\"\"},\"settings\":{\"autoFitToDataBounds\":false}}",
    "layerListJSON": "[{\"id\":\"0hmz5\",\"alpha\":1,\"sourceDescriptor\":{\"type\":\"EMS_TMS\",\"isAutoSelect\":true,\"lightModeDefault\":\"road_map_desaturated\"},\"visible\":true,\"style\":{},\"type\":\"EMS_VECTOR_TILE\",\"minZoom\":0,\"maxZoom\":24},{\"id\":\"edh66\",\"label\":\"Total Requests by Destination\",\"minZoom\":0,\"maxZoom\":24,\"alpha\":0.5,\"sourceDescriptor\":{\"type\":\"EMS_FILE\",\"id\":\"world_countries\",\"tooltipProperties\":[\"name\",\"iso2\"]},\"visible\":true,\"style\":{\"type\":\"VECTOR\",\"properties\":{\"fillColor\":{\"type\":\"DYNAMIC\",\"options\":{\"field\":{\"name\":\"__kbnjoin__count__673ff994-fc75-4c67-909b-69fcb0e1060e\",\"origin\":\"join\"},\"color\":\"Greys\",\"fieldMetaOptions\":{\"isEnabled\":false,\"sigma\":3}}},\"lineColor\":{\"type\":\"STATIC\",\"options\":{\"color\":\"#FFFFFF\"}},\"lineWidth\":{\"type\":\"STATIC\",\"options\":{\"size\":1}},\"iconSize\":{\"type\":\"STATIC\",\"options\":{\"size\":10}},\"symbolizeAs\":{\"options\":{\"value\":\"circle\"}},\"icon\":{\"type\":\"STATIC\",\"options\":{\"value\":\"marker\"}}}},\"type\":\"GEOJSON_VECTOR\",\"joins\":[{\"leftField\":\"iso2\",\"right\":{\"type\":\"ES_TERM_SOURCE\",\"id\":\"673ff994-fc75-4c67-909b-69fcb0e1060e\",\"indexPatternTitle\":\"kibana_sample_data_logs\",\"term\":\"geo.dest\",\"indexPatternRefName\":\"layer_1_join_0_index_pattern\",\"metrics\":[{\"type\":\"count\",\"label\":\"web logs count\"}],\"applyGlobalQuery\":true}}]},{\"id\":\"gaxya\",\"label\":\"Actual Requests\",\"minZoom\":9,\"maxZoom\":24,\"alpha\":1,\"sourceDescriptor\":{\"id\":\"b7486535-171b-4d3b-bb2e-33c1a0a2854c\",\"type\":\"ES_SEARCH\",\"geoField\":\"geo.coordinates\",\"limit\":2048,\"filterByMapBounds\":true,\"tooltipProperties\":[\"clientip\",\"timestamp\",\"host\",\"request\",\"response\",\"machine.os\",\"agent\",\"bytes\"],\"indexPatternRefName\":\"layer_2_source_index_pattern\",\"applyGlobalQuery\":true,\"scalingType\":\"LIMIT\"},\"visible\":true,\"style\":{\"type\":\"VECTOR\",\"properties\":{\"fillColor\":{\"type\":\"STATIC\",\"options\":{\"color\":\"#2200ff\"}},\"lineColor\":{\"type\":\"STATIC\",\"options\":{\"color\":\"#FFFFFF\"}},\"lineWidth\":{\"type\":\"STATIC\",\"options\":{\"size\":2}},\"iconSize\":{\"type\":\"DYNAMIC\",\"options\":{\"field\":{\"name\":\"bytes\",\"origin\":\"source\"},\"minSize\":1,\"maxSize\":23,\"fieldMetaOptions\":{\"isEnabled\":false,\"sigma\":3}}},\"symbolizeAs\":{\"options\":{\"value\":\"circle\"}},\"icon\":{\"type\":\"STATIC\",\"options\":{\"value\":\"marker\"}}}},\"type\":\"GEOJSON_VECTOR\"},{\"id\":\"tfi3f\",\"label\":\"Total Requests and Bytes\",\"minZoom\":0,\"maxZoom\":9,\"alpha\":1,\"sourceDescriptor\":{\"type\":\"ES_GEO_GRID\",\"resolution\":\"COARSE\",\"id\":\"8aaa65b5-a4e9-448b-9560-c98cb1c5ac5b\",\"geoField\":\"geo.coordinates\",\"requestType\":\"point\",\"metrics\":[{\"type\":\"count\",\"label\":\"web logs count\"},{\"type\":\"sum\",\"field\":\"bytes\"}],\"indexPatternRefName\":\"layer_3_source_index_pattern\",\"applyGlobalQuery\":true},\"visible\":true,\"style\":{\"type\":\"VECTOR\",\"properties\":{\"fillColor\":{\"type\":\"DYNAMIC\",\"options\":{\"field\":{\"name\":\"doc_count\",\"origin\":\"source\"},\"color\":\"Blues\",\"fieldMetaOptions\":{\"isEnabled\":false,\"sigma\":3}}},\"lineColor\":{\"type\":\"STATIC\",\"options\":{\"color\":\"#cccccc\"}},\"lineWidth\":{\"type\":\"STATIC\",\"options\":{\"size\":1}},\"iconSize\":{\"type\":\"DYNAMIC\",\"options\":{\"field\":{\"name\":\"sum_of_bytes\",\"origin\":\"source\"},\"minSize\":7,\"maxSize\":25,\"fieldMetaOptions\":{\"isEnabled\":false,\"sigma\":3}}},\"labelText\":{\"type\":\"DYNAMIC\",\"options\":{\"field\":{\"name\":\"doc_count\",\"origin\":\"source\"},\"fieldMetaOptions\":{\"isEnabled\":false,\"sigma\":3}}},\"labelSize\":{\"type\":\"DYNAMIC\",\"options\":{\"field\":{\"name\":\"doc_count\",\"origin\":\"source\"},\"minSize\":12,\"maxSize\":24,\"fieldMetaOptions\":{\"isEnabled\":false,\"sigma\":3}}},\"symbolizeAs\":{\"options\":{\"value\":\"circle\"}},\"icon\":{\"type\":\"STATIC\",\"options\":{\"value\":\"marker\"}}}},\"type\":\"GEOJSON_VECTOR\"}]"
  },
  "created_at": "2023-08-23T20:03:32.204Z",
  "references": [
    {
      "id": "90943e30-9a47-11e8-b64d-95841ca0b247",
      "name": "layer_1_join_0_index_pattern",
      "type": "index-pattern"
    },
    {
      "id": "90943e30-9a47-11e8-b64d-95841ca0b247",
      "name": "layer_2_source_index_pattern",
      "type": "index-pattern"
    },
    {
      "id": "90943e30-9a47-11e8-b64d-95841ca0b247",
      "name": "layer_3_source_index_pattern",
      "type": "index-pattern"
    }
  ],
  "updated_at": "2023-08-23T20:03:32.204Z",
  "coreMigrationVersion": "8.8.0",
  "typeMigrationVersion": "8.4.0"
}
Response examples (400)
{
  "error": "Bad Request",
  "message": "string",
  "statusCode": 400
}

















Create a conversation Beta

POST /api/security_ai_assistant/current_user/conversations

Create a new Security AI Assistant conversation.

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

    The conversation id.

  • 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

  • Replacements object used to anonymize/deanomymize messsages

    Hide replacements attribute Show replacements attribute object
    • * string Additional properties
  • title string Required

    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
POST /api/security_ai_assistant/current_user/conversations
curl \
 --request POST https://<KIBANA_URL>/api/security_ai_assistant/current_user/conversations \
 --header "Content-Type: application/json" \
 --data '{"apiConfig":{"actionTypeId":"string","connectorId":"string","defaultSystemPromptId":"string","model":"string","provider":"OpenAI"},"category":"assistant","excludeFromLastConversationStorage":true,"id":"string","isDefault":true,"messages":[{"content":"string","isError":true,"metadata":{"contentReferences":{}},"reader":{},"role":"system","timestamp":"string","traceData":{"traceId":"string","transactionId":"string"}}],"replacements":{"additionalProperty1":"string","additionalProperty2":"string"},"title":"string"}'
Request examples
{
  "apiConfig": {
    "actionTypeId": "string",
    "connectorId": "string",
    "defaultSystemPromptId": "string",
    "model": "string",
    "provider": "OpenAI"
  },
  "category": "assistant",
  "excludeFromLastConversationStorage": true,
  "id": "string",
  "isDefault": true,
  "messages": [
    {
      "content": "string",
      "isError": true,
      "metadata": {
        "contentReferences": {}
      },
      "reader": {},
      "role": "system",
      "timestamp": "string",
      "traceData": {
        "traceId": "string",
        "transactionId": "string"
      }
    }
  ],
  "replacements": {
    "additionalProperty1": "string",
    "additionalProperty2": "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
}








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
}




Read a KnowledgeBase Beta

GET /api/security_ai_assistant/knowledge_base/{resource}

Read a single KB

Path parameters

  • resource string

    The KnowledgeBase resource value.

Responses

GET /api/security_ai_assistant/knowledge_base/{resource}
curl \
 --request GET https://<KIBANA_URL>/api/security_ai_assistant/knowledge_base/{resource}
Response examples (200)
{
  "elser_exists": true,
  "index_exists": true,
  "is_setup_available": true,
  "is_setup_in_progress": true,
  "pipeline_exists": true,
  "security_labs_exists": true,
  "user_data_exists": true
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}












Finds Knowledge Base Entries that match the given query. Beta

GET /api/security_ai_assistant/knowledge_base/entries/_find

Finds Knowledge Base Entries that match the given query.

Query parameters

  • fields array[string]
  • filter string

    Search query

  • Field to sort by

    Values are created_at, is_default, title, or updated_at.

  • Sort order

    Values are asc or desc.

  • page integer

    Page number

    Minimum value is 1. Default value is 1.

  • per_page integer

    Knowledge Base Entries per page

    Minimum value is 0. Default value is 20.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • data array[object] Required
      Any of:
      Hide attributes Show attributes
      • name string Required

        Name of the Knowledge Base Entry

      • namespace string Required

        Kibana Space, defaults to 'default' space

      • users array[object] Required

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

        Hide users attributes Show users attributes object
      • createdAt string Required

        Time the Knowledge Base Entry was created

      • createdBy string Required

        User who created the Knowledge Base Entry

      • id string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • updatedAt string Required

        Time the Knowledge Base Entry was last updated

      • updatedBy string Required

        User who last updated the Knowledge Base Entry

      • kbResource string Required

        Knowledge Base resource name for grouping entries, e.g. 'esql', 'lens-docs', etc

      • source string Required

        Source document name or filepath

      • text string Required

        Knowledge Base Entry content

      • type string Required Discriminator

        Entry type

        Value is document.

      • required boolean

        Whether this resource should always be included, defaults to false

      • vector object

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

        Additional properties are allowed.

        Hide vector attributes Show vector attributes object
        • modelId string Required

          ID of the model used to create the embeddings

        • tokens object Required

          Tokens with their corresponding values

          Hide tokens attribute Show tokens attribute object
          • * number Additional properties
    • page integer Required
    • perPage integer Required
    • total integer Required
  • 400 application/json

    Generic Error

    Hide response attributes Show response attributes object
GET /api/security_ai_assistant/knowledge_base/entries/_find
curl \
 --request GET https://<KIBANA_URL>/api/security_ai_assistant/knowledge_base/entries/_find
Response examples (200)
{
  "data": [
    {
      "name": "string",
      "namespace": "string",
      "users": [
        {
          "id": "string",
          "name": "string"
        }
      ],
      "createdAt": "string",
      "createdBy": "string",
      "id": "string",
      "updatedAt": "string",
      "updatedBy": "string",
      "kbResource": "string",
      "source": "string",
      "text": "string",
      "type": "document",
      "required": true,
      "vector": {
        "modelId": "string",
        "tokens": {
          "additionalProperty1": 42.0,
          "additionalProperty2": 42.0
        }
      }
    }
  ],
  "page": 42,
  "perPage": 42,
  "total": 42
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}

Read a Knowledge Base Entry Beta

GET /api/security_ai_assistant/knowledge_base/entries/{id}

Read a Knowledge Base Entry

Path parameters

  • id string(nonempty) Required

    The Knowledge Base Entry's id value.

    Minimum length is 1.

Responses

  • 200 application/json

    Successful request returning a Knowledge Base Entry

    Any of:
    Hide attributes Show attributes
    • name string Required

      Name of the Knowledge Base Entry

    • namespace string Required

      Kibana Space, defaults to 'default' space

    • users array[object] Required

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

      Hide users attributes Show users attributes object
    • createdAt string Required

      Time the Knowledge Base Entry was created

    • createdBy string Required

      User who created the Knowledge Base Entry

    • id string(nonempty) Required

      A string that does not contain only whitespace characters

      Minimum length is 1.

    • updatedAt string Required

      Time the Knowledge Base Entry was last updated

    • updatedBy string Required

      User who last updated the Knowledge Base Entry

    • kbResource string Required

      Knowledge Base resource name for grouping entries, e.g. 'esql', 'lens-docs', etc

    • source string Required

      Source document name or filepath

    • text string Required

      Knowledge Base Entry content

    • type string Required Discriminator

      Entry type

      Value is document.

    • required boolean

      Whether this resource should always be included, defaults to false

    • vector object

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

      Additional properties are allowed.

      Hide vector attributes Show vector attributes object
      • modelId string Required

        ID of the model used to create the embeddings

      • tokens object Required

        Tokens with their corresponding values

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

    Generic Error

    Hide response attributes Show response attributes object
GET /api/security_ai_assistant/knowledge_base/entries/{id}
curl \
 --request GET https://<KIBANA_URL>/api/security_ai_assistant/knowledge_base/entries/{id}
Response examples (200)
{
  "name": "string",
  "namespace": "string",
  "users": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "createdAt": "string",
  "createdBy": "string",
  "id": "string",
  "updatedAt": "string",
  "updatedBy": "string",
  "kbResource": "string",
  "source": "string",
  "text": "string",
  "type": "document",
  "required": true,
  "vector": {
    "modelId": "string",
    "tokens": {
      "additionalProperty1": 42.0,
      "additionalProperty2": 42.0
    }
  }
}
{
  "name": "string",
  "namespace": "string",
  "users": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "createdAt": "string",
  "createdBy": "string",
  "id": "string",
  "updatedAt": "string",
  "updatedBy": "string",
  "description": "string",
  "field": "string",
  "index": "string",
  "queryDescription": "string",
  "type": "index",
  "inputSchema": [
    {
      "description": "string",
      "fieldName": "string",
      "fieldType": "string"
    }
  ],
  "outputFields": [
    "string"
  ]
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}

Update a Knowledge Base Entry Beta

PUT /api/security_ai_assistant/knowledge_base/entries/{id}

Update a Knowledge Base Entry

Path parameters

  • id string(nonempty) Required

    The Knowledge Base Entry's id value

    Minimum length is 1.

application/json

Body object Required

Any of:
  • id string(nonempty) Required

    A string that does not contain only whitespace characters

    Minimum length is 1.

  • name string Required

    Name of the Knowledge Base Entry

  • Kibana Space, defaults to 'default' space

  • users array[object]

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

    Hide users attributes Show users attributes object
  • kbResource string Required

    Knowledge Base resource name for grouping entries, e.g. 'esql', 'lens-docs', etc

  • source string Required

    Source document name or filepath

  • text string Required

    Knowledge Base Entry content

  • type string Required Discriminator

    Entry type

    Value is document.

  • required boolean

    Whether this resource should always be included, defaults to false

  • vector object

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

    Additional properties are allowed.

    Hide vector attributes Show vector attributes object
    • modelId string Required

      ID of the model used to create the embeddings

    • tokens object Required

      Tokens with their corresponding values

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

Responses

  • 200 application/json

    Successful request returning the updated Knowledge Base Entry

    Any of:
    Hide attributes Show attributes
    • name string Required

      Name of the Knowledge Base Entry

    • namespace string Required

      Kibana Space, defaults to 'default' space

    • users array[object] Required

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

      Hide users attributes Show users attributes object
    • createdAt string Required

      Time the Knowledge Base Entry was created

    • createdBy string Required

      User who created the Knowledge Base Entry

    • id string(nonempty) Required

      A string that does not contain only whitespace characters

      Minimum length is 1.

    • updatedAt string Required

      Time the Knowledge Base Entry was last updated

    • updatedBy string Required

      User who last updated the Knowledge Base Entry

    • kbResource string Required

      Knowledge Base resource name for grouping entries, e.g. 'esql', 'lens-docs', etc

    • source string Required

      Source document name or filepath

    • text string Required

      Knowledge Base Entry content

    • type string Required Discriminator

      Entry type

      Value is document.

    • required boolean

      Whether this resource should always be included, defaults to false

    • vector object

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

      Additional properties are allowed.

      Hide vector attributes Show vector attributes object
      • modelId string Required

        ID of the model used to create the embeddings

      • tokens object Required

        Tokens with their corresponding values

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

    Generic Error

    Hide response attributes Show response attributes object
PUT /api/security_ai_assistant/knowledge_base/entries/{id}
curl \
 --request PUT https://<KIBANA_URL>/api/security_ai_assistant/knowledge_base/entries/{id} \
 --header "Content-Type: application/json" \
 --data '{"id":"string","name":"string","namespace":"string","users":[{"id":"string","name":"string"}],"kbResource":"string","source":"string","text":"string","type":"document","required":true,"vector":{"modelId":"string","tokens":{"additionalProperty1":42.0,"additionalProperty2":42.0}}}'
{
  "id": "string",
  "name": "string",
  "namespace": "string",
  "users": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "kbResource": "string",
  "source": "string",
  "text": "string",
  "type": "document",
  "required": true,
  "vector": {
    "modelId": "string",
    "tokens": {
      "additionalProperty1": 42.0,
      "additionalProperty2": 42.0
    }
  }
}
{
  "id": "string",
  "name": "string",
  "namespace": "string",
  "users": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "description": "string",
  "field": "string",
  "index": "string",
  "queryDescription": "string",
  "type": "index",
  "inputSchema": [
    {
      "description": "string",
      "fieldName": "string",
      "fieldType": "string"
    }
  ],
  "outputFields": [
    "string"
  ]
}
Response examples (200)
{
  "name": "string",
  "namespace": "string",
  "users": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "createdAt": "string",
  "createdBy": "string",
  "id": "string",
  "updatedAt": "string",
  "updatedBy": "string",
  "kbResource": "string",
  "source": "string",
  "text": "string",
  "type": "document",
  "required": true,
  "vector": {
    "modelId": "string",
    "tokens": {
      "additionalProperty1": 42.0,
      "additionalProperty2": 42.0
    }
  }
}
{
  "name": "string",
  "namespace": "string",
  "users": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "createdAt": "string",
  "createdBy": "string",
  "id": "string",
  "updatedAt": "string",
  "updatedBy": "string",
  "description": "string",
  "field": "string",
  "index": "string",
  "queryDescription": "string",
  "type": "index",
  "inputSchema": [
    {
      "description": "string",
      "fieldName": "string",
      "fieldType": "string"
    }
  ],
  "outputFields": [
    "string"
  ]
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}








Get prompts Beta

GET /api/security_ai_assistant/prompts/_find

Get a list of all prompts.

Query parameters

  • fields array[string]
  • filter string

    Search query

  • Field to sort by

    Values are created_at, is_default, name, or updated_at.

  • Sort order

    Values are asc or desc.

  • page integer

    Page number

    Minimum value is 1. Default value is 1.

  • per_page integer

    Prompts per page

    Minimum value is 0. Default value is 20.

Responses

GET /api/security_ai_assistant/prompts/_find
curl \
 --request GET https://<KIBANA_URL>/api/security_ai_assistant/prompts/_find
Response examples (200)
{
  "data": [
    {
      "categories": [
        "string"
      ],
      "color": "string",
      "consumer": "string",
      "content": "string",
      "createdAt": "string",
      "createdBy": "string",
      "id": "string",
      "isDefault": true,
      "isNewConversationDefault": true,
      "name": "string",
      "namespace": "string",
      "promptType": "system",
      "timestamp": "string",
      "updatedAt": "string",
      "updatedBy": "string",
      "users": [
        {
          "id": "string",
          "name": "string"
        }
      ]
    }
  ],
  "page": 42,
  "perPage": 42,
  "total": 42
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}

























































Add and remove detection alert tags Beta

POST /api/detection_engine/signals/tags

And tags to detection alerts, and remove them from alerts.

You cannot add and remove the same alert tag in the same request.

application/json

Body Required

An object containing tags to add or remove and alert ids the changes will be applied

  • ids array[string(nonempty)] Required

    A list of alerts ids.

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

  • tags object Required

    Object with list of tags to add and remove.

    Additional properties are allowed.

    Hide tags attributes Show tags attributes object
    • tags_to_add array[string(nonempty)] Required

      Use alert tags to organize related alerts into categories that you can filter and group.

      Minimum length of each is 1.

    • tags_to_remove array[string(nonempty)] Required

      Use alert tags to organize related alerts into categories that you can filter and group.

      Minimum length of each is 1.

Responses

POST /api/detection_engine/signals/tags
curl \
 --request POST https://<KIBANA_URL>/api/detection_engine/signals/tags \
 --header "Content-Type: application/json" \
 --data '{"ids":["549c7129c76cbd554aba1bd638f8a49dde95088f5832e50218358e7eca1cf16e"],"tags":{"tags_to_add":["Duplicate"],"tags_to_remove":[]}}'
Request examples
{
  "ids": [
    "549c7129c76cbd554aba1bd638f8a49dde95088f5832e50218358e7eca1cf16e"
  ],
  "tags": {
    "tags_to_add": [
      "Duplicate"
    ],
    "tags_to_remove": []
  }
}
{
  "ids": [
    "549c7129c76cbd554aba1bd638f8a49dde95088f5832e50218358e7eca1cf16e"
  ],
  "tags": {
    "tags_to_add": [],
    "tags_to_remove": [
      "Duplicate"
    ]
  }
}
Response examples (200)
{
  "took": "68,",
  "noops": 0,
  "total": "1,",
  "batches": "1,",
  "deleted": 0,
  "retries": {
    "bulk": 0,
    "search": 0
  },
  "updated": "1,",
  "failures": [],
  "timed_out": "false,",
  "throttled_millis": 0,
  "version_conflicts": 0,
  "requests_per_second": "-1,",
  "throttled_until_millis": 0
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42
}
{
  "message": "string",
  "status_code": 42
}
Response examples (401)
{
  "error": "string",
  "message": "string",
  "statusCode": 42
}
Response examples (500)
{
  "message": "string",
  "status_code": 42
}




Security endpoint exceptions

Endpoint Exceptions API allows you to manage detection rule endpoint exceptions to prevent a rule from generating an alert from incoming events even when the rule's other criteria are met.


























Get response actions Beta

GET /api/endpoint/action

Get a list of all response actions.

Query parameters

  • query object Required

    Additional properties are allowed.

    Hide query attributes Show query attributes object

Responses

  • 200 application/json

    OK

    Additional properties are allowed.

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




Get action details Beta

GET /api/endpoint/action/{action_id}

Get the details of a response action using the action ID.

Responses

  • 200 application/json

    OK

    Additional properties are allowed.

GET /api/endpoint/action/{action_id}
curl \
 --request GET https://<KIBANA_URL>/api/endpoint/action/{action_id}
Response examples (200)
{}








Run a command Beta

POST /api/endpoint/action/execute

Run a shell command on an endpoint.

application/json

Body Required

  • The host agent type (optional). Defaults to endpoint.

    Values are endpoint, sentinel_one, crowdstrike, or microsoft_defender_endpoint.

  • alert_ids array[string(nonempty)]

    A list of alerts ids.

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

  • case_ids array[string]

    Case IDs to be updated (cannot contain empty strings)

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

  • comment string

    Optional comment

  • endpoint_ids array[string] Required

    List of endpoint IDs (cannot contain empty strings)

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

  • parameters object Required

    Additional properties are allowed.

    Hide parameters attributes Show parameters attributes object
    • command string Required

      The command to be executed (cannot be an empty string)

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

    • timeout integer

      The maximum timeout value in milliseconds (optional)

      Minimum value is 1.

Responses

  • 200 application/json

    OK

    Additional properties are allowed.

POST /api/endpoint/action/execute
curl \
 --request POST https://<KIBANA_URL>/api/endpoint/action/execute \
 --header "Content-Type: application/json" \
 --data '{"agent_type":"endpoint","alert_ids":["string"],"case_ids":["string"],"comment":"string","endpoint_ids":["string"],"parameters":{"command":"isolate","timeout":42}}'
Request examples
{
  "agent_type": "endpoint",
  "alert_ids": [
    "string"
  ],
  "case_ids": [
    "string"
  ],
  "comment": "string",
  "endpoint_ids": [
    "string"
  ],
  "parameters": {
    "command": "isolate",
    "timeout": 42
  }
}
Response examples (200)
{}








Terminate a process Beta

POST /api/endpoint/action/kill_process

Terminate a running process on an endpoint.

application/json

Body Required

Responses

  • 200 application/json

    OK

    Additional properties are allowed.

POST /api/endpoint/action/kill_process
curl \
 --request POST https://<KIBANA_URL>/api/endpoint/action/kill_process \
 --header "Content-Type: application/json" \
 --data '{"agent_type":"endpoint","alert_ids":["string"],"case_ids":["string"],"comment":"string","endpoint_ids":["string"],"parameters":{"pid":42}}'
Request examples
{
  "agent_type": "endpoint",
  "alert_ids": [
    "string"
  ],
  "case_ids": [
    "string"
  ],
  "comment": "string",
  "endpoint_ids": [
    "string"
  ],
  "parameters": {
    "pid": 42
  }
}
Response examples (200)
{}




Run a script Beta

POST /api/endpoint/action/runscript

Run a shell command on an endpoint.

application/json

Body Required

Responses

  • 200 application/json

    OK

    Additional properties are allowed.

POST /api/endpoint/action/runscript
curl \
 --request POST https://<KIBANA_URL>/api/endpoint/action/runscript \
 --header "Content-Type: application/json" \
 --data '{"parameters":{"commandLine":"string","raw":"string","timeout":42}}'
Request examples
{
  "parameters": {
    "commandLine": "string",
    "raw": "string",
    "timeout": 42
  }
}
Response examples (200)
{}
























Get metadata Beta

GET /api/endpoint/metadata/{id}

Path parameters

  • id string Required

Responses

  • 200 application/json

    OK

    Additional properties are allowed.

GET /api/endpoint/metadata/{id}
curl \
 --request GET https://<KIBANA_URL>/api/endpoint/metadata/{id}
Response examples (200)
{}




Get a protection updates note Beta

GET /api/endpoint/protection_updates_note/{package_policy_id}

Responses

  • 200 application/json

    OK

    Hide response attribute Show response attribute object
GET /api/endpoint/protection_updates_note/{package_policy_id}
curl \
 --request GET https://<KIBANA_URL>/api/endpoint/protection_updates_note/{package_policy_id}
Response examples (200)
{
  "note": "string"
}





























List the Entity Engines Beta

GET /api/entity_store/engines

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • count integer
    • engines array[object]
      Hide engines attributes Show engines attributes object
      • delay string

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

      • error object

        Additional properties are allowed.

      • fieldHistoryLength integer Required
      • filter string
      • Format should match the following pattern: [smdh]$. Default value is 1m.

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

      • status string Required

        Values are installing, started, stopped, updating, or error.

      • timeout string

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

      • type string Required

        Values are user, host, service, or universal.

GET /api/entity_store/engines
curl \
 --request GET https://<KIBANA_URL>/api/entity_store/engines
Response examples (200)
{
  "count": 42,
  "engines": [
    {
      "delay": "1m",
      "docsPerSecond": 42,
      "error": {},
      "fieldHistoryLength": 42,
      "filter": "string",
      "frequency": "1m",
      "indexPattern": "string",
      "lookbackPeriod": "24h",
      "status": "installing",
      "timeout": "180s",
      "timestampField": "string",
      "type": "user"
    }
  ]
}

Get an Entity Engine Beta

GET /api/entity_store/engines/{entityType}

Path parameters

  • entityType string Required

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

    Values are user, host, service, or universal.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • delay string

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

    • error object

      Additional properties are allowed.

    • fieldHistoryLength integer Required
    • filter string
    • Format should match the following pattern: [smdh]$. Default value is 1m.

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

    • status string Required

      Values are installing, started, stopped, updating, or error.

    • timeout string

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

    • type string Required

      Values are user, host, service, or universal.

GET /api/entity_store/engines/{entityType}
curl \
 --request GET https://<KIBANA_URL>/api/entity_store/engines/{entityType}
Response examples (200)
{
  "delay": "1m",
  "docsPerSecond": 42,
  "error": {},
  "fieldHistoryLength": 42,
  "filter": "string",
  "frequency": "1m",
  "indexPattern": "string",
  "lookbackPeriod": "24h",
  "status": "installing",
  "timeout": "180s",
  "timestampField": "string",
  "type": "user"
}

Delete the Entity Engine Beta

DELETE /api/entity_store/engines/{entityType}

Path parameters

  • entityType string Required

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

    Values are user, host, service, or universal.

Query parameters

  • data boolean

    Control flag to also delete the entity data.

Responses

  • 200 application/json

    Successful response

    Hide response attribute Show response attribute object
DELETE /api/entity_store/engines/{entityType}
curl \
 --request DELETE https://<KIBANA_URL>/api/entity_store/engines/{entityType}
Response examples (200)
{
  "deleted": true
}




Start an Entity Engine Beta

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

Path parameters

  • entityType string Required

    The entity type of the engine

    Values are user, host, service, or universal.

Responses

  • 200 application/json

    Successful response

    Hide response attribute Show response attribute object
POST /api/entity_store/engines/{entityType}/start
curl \
 --request POST https://<KIBANA_URL>/api/entity_store/engines/{entityType}/start
Response examples (200)
{
  "started": true
}












Get the status of the Entity Store Beta

GET /api/entity_store/status

Query parameters

  • If true returns a detailed status of the engine including all it's components

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • engines array[object] Required
      Hide engines attributes Show engines attributes object
      • delay string

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

      • error object

        Additional properties are allowed.

      • fieldHistoryLength integer Required
      • filter string
      • Format should match the following pattern: [smdh]$. Default value is 1m.

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

      • status string Required

        Values are installing, started, stopped, updating, or error.

      • timeout string

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

      • type string Required

        Values are user, host, service, or universal.

      • components array[object]
        Hide components attributes Show components attributes object
        • errors array[object]
          Hide errors attributes Show errors attributes object
        • health string

          Values are green, yellow, red, or unknown.

        • id string Required
        • installed boolean Required
        • resource string Required

          Values are entity_engine, entity_definition, index, component_template, index_template, ingest_pipeline, enrich_policy, task, or transform.

    • status string Required

      Values are not_installed, installing, running, stopped, or error.

GET /api/entity_store/status
curl \
 --request GET https://<KIBANA_URL>/api/entity_store/status
Response examples (200)
{
  "engines": [
    {
      "delay": "1m",
      "docsPerSecond": 42,
      "error": {},
      "fieldHistoryLength": 42,
      "filter": "string",
      "frequency": "1m",
      "indexPattern": "string",
      "lookbackPeriod": "24h",
      "status": "installing",
      "timeout": "180s",
      "timestampField": "string",
      "type": "user",
      "components": [
        {
          "errors": [
            {
              "message": "string",
              "title": "string"
            }
          ],
          "health": "green",
          "id": "string",
          "installed": true,
          "resource": "entity_engine"
        }
      ]
    }
  ],
  "status": "not_installed"
}

























Create an exception list Beta

POST /api/exception_lists

An exception list groups exception items and can be associated with detection rules. You can assign exception lists to multiple detection rules.

All exception items added to the same list are evaluated using OR logic. That is, if any of the items in a list evaluate to true, the exception prevents the rule from generating an alert. Likewise, OR logic is used for evaluating exceptions when more than one exception list is assigned to a rule. To use the AND operator, you can define multiple clauses (entries) in a single exception item.

application/json

Body Required

Exception list's properties

  • description string Required

    Describes the exception list.

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

    Exception list already exists response

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

    Internal server error response

    Hide response attributes Show response attributes object
POST /api/exception_lists
curl \
 --request POST https://<KIBANA_URL>/api/exception_lists \
 --header "Content-Type: application/json" \
 --data '{"name":"Sample Detection Exception List","tags":["malware"],"type":"detection","list_id":"simple_list","os_types":["linux"],"description":"This is a sample detection type exception list.","namespace_type":"single"}'
Request example
{
  "name": "Sample Detection Exception List",
  "tags": [
    "malware"
  ],
  "type": "detection",
  "list_id": "simple_list",
  "os_types": [
    "linux"
  ],
  "description": "This is a sample detection type exception list.",
  "namespace_type": "single"
}
{
  "id": "28243c2f-624a-4443-823d-c0b894880931",
  "name": "Sample Detection Exception List",
  "tags": [
    "malware"
  ],
  "type": "detection",
  "list_id": "8c1aae4c-1ef5-4bce-a2e3-16584b501783",
  "version": 1,
  "_version": "WzMsMV0=",
  "os_types": [],
  "immutable": false,
  "created_at": "2025-01-09T01:05:23.019Z",
  "created_by": "elastic",
  "updated_at": "2025-01-09T01:05:23.020Z",
  "updated_by": "elastic",
  "description": "This is a sample detection type exception with an autogenerated list_id.",
  "namespace_type": "single",
  "tie_breaker_id": "ad94de31-39f7-4ad7-b8e4-988bfa95f338"
}
{
  "id": "1a744e77-22ca-4b6b-9085-54f55275ebe5",
  "name": "Sample Agnostic Endpoint Exception List",
  "tags": [
    "malware"
  ],
  "type": "endpoint",
  "list_id": "b935eb55-7b21-4c1c-b235-faa1df23b3d6",
  "version": 1,
  "_version": "WzUsMV0=",
  "os_types": [
    "linux"
  ],
  "immutable": false,
  "created_at": "2025-01-09T01:10:36.369Z",
  "created_by": "elastic",
  "updated_at": "2025-01-09T01:10:36.369Z",
  "updated_by": "elastic",
  "description": "This is a sample agnostic endpoint type exception.",
  "namespace_type": "agnostic",
  "tie_breaker_id": "49ea0adc-a2b8-4d83-a8f3-2fb98301dea3"
}
{
  "id": "9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85",
  "name": "Sample Detection Exception List",
  "tags": [
    "malware"
  ],
  "type": "detection",
  "list_id": "simple_list",
  "version": 1,
  "_version": "WzIsMV0=",
  "os_types": [
    "linux"
  ],
  "immutable": false,
  "created_at": "2025-01-07T19:34:27.942Z",
  "created_by": "elastic",
  "updated_at": "2025-01-07T19:34:27.942Z",
  "updated_by": "elastic",
  "description": "This is a sample detection type exception list.",
  "namespace_type": "single",
  "tie_breaker_id": "78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3"
}
{
  "id": "a79f4730-6e32-4278-abfc-349c0add7d54",
  "name": "Sample Endpoint Exception List",
  "tags": [
    "malware"
  ],
  "type": "endpoint",
  "list_id": "endpoint_list",
  "version": 1,
  "_version": "WzQsMV0=",
  "os_types": [
    "linux"
  ],
  "immutable": false,
  "created_at": "2025-01-09T01:07:49.658Z",
  "created_by": "elastic",
  "updated_at": "2025-01-09T01:07:49.658Z",
  "updated_by": "elastic",
  "description": "This is a sample endpoint type exception list.",
  "namespace_type": "single",
  "tie_breaker_id": "94a028af-8f47-427a-aca5-ffaf829e64ee"
}
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 [POST /api/exception_lists] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}
Response examples (409)
{
  "message": "exception list id: \"simple_list\" already exists",
  "status_code": 409
}
Response examples (500)
{
  "message": "Internal Server Error",
  "status_code": 500
}
















Import an exception list Beta

POST /api/exception_lists/_import

Import an exception list and its associated items from an NDJSON file.

Query parameters

  • overwrite boolean

    Determines whether existing exception lists with the same list_id are overwritten. If any exception items have the same item_id, those are also overwritten.

    Default value is false.

  • Determines whether the list being imported will have a new list_id generated. Additional item_id's are generated for each exception item. Both the exception list and its items are overwritten.

    Default value is false.

multipart/form-data

Body Required

  • file string(binary)

    A .ndjson file containing the exception list

Responses

POST /api/exception_lists/_import
curl \
 --request POST https://<KIBANA_URL>/api/exception_lists/_import \
 --header "Content-Type: multipart/form-data" \
 --form "file={"_version":"WzExNDU5LDFd","created_at":"2025-01-09T16:18:17.757Z","created_by":"elastic","description":"This is a sample detection type exception","id":"c86c2da0-2ab6-4343-b81c-216ef27e8d75","immutable":false,"list_id":"simple_list","name":"Sample Detection Exception List","namespace_type":"single","os_types":[],"tags":["user added string for a tag","malware"],"tie_breaker_id":"cf4a7b92-732d-47f0-a0d5-49a35a1736bf","type":"detection","updated_at":"2025-01-09T16:18:17.757Z","updated_by":"elastic","version":1}
{"_version":"WzExNDYxLDFd","comments":[],"created_at":"2025-01-09T16:18:42.308Z","created_by":"elastic","description":"This is a sample endpoint type exception","entries":[{"type":"exists","field":"actingProcess.file.signer","operator":"excluded"},{"type":"match_any","field":"host.name","value":["some host","another host"],"operator":"included"}],"id":"f37597ce-eaa7-4b64-9100-4301118f6806","item_id":"simple_list_item","list_id":"simple_list","name":"Sample Endpoint Exception List","namespace_type":"single","os_types":["linux"],"tags":["user added string for a tag","malware"],"tie_breaker_id":"4ca3ef3e-9721-42c0-8107-cf47e094d40f","type":"simple","updated_at":"2025-01-09T16:18:42.308Z","updated_by":"elastic"}
"
Response examples (200)
{
  "errors": [
    {
      "error": {
        "message": "Error found importing exception list: Invalid value \\\"4\\\" supplied to \\\"list_id\\\"",
        "status_code": 400
      },
      "list_id": "(unknown list_id)"
    },
    {
      "error": {
        "message": "Found that item_id: \\\"f7fd00bb-dba8-4c93-9d59-6cbd427b6330\\\" already exists. Import of item_id: \\\"f7fd00bb-dba8-4c93-9d59-6cbd427b6330\\\" skipped.",
        "status_code": 409
      },
      "item_id": "f7fd00bb-dba8-4c93-9d59-6cbd427b6330",
      "list_id": "7d7cccb8-db72-4667-b1f3-648efad7c1ee"
    }
  ],
  "success": "false,",
  "success_count": 0,
  "success_exception_lists": "false,",
  "success_exception_list_items": "false,",
  "success_count_exception_lists": 0,
  "success_count_exception_list_items": 0
}
{
  "errors": [],
  "success": true,
  "success_count": 2,
  "success_exception_lists": "true,",
  "success_exception_list_items": true,
  "success_count_exception_lists": 1,
  "success_count_exception_list_items": 1
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42
}
{
  "message": "string",
  "status_code": 42
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403)
{
  "error": "Forbidden",
  "message": "API [POST /api/exception_lists/_import] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}
Response examples (500)
{
  "message": "Internal Server Error",
  "status_code": 500
}












Delete an exception list item Beta

DELETE /api/exception_lists/items

Delete an exception list item using the id or item_id field.

Query parameters

  • id string(nonempty)

    Exception item's identifier. Either id or item_id must be specified

    Minimum length is 1.

  • item_id string(nonempty)

    Human readable exception item string identifier, e.g. trusted-linux-processes. Either id or item_id must be specified

    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.

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

    Exception 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
DELETE /api/exception_lists/items
curl \
 --request DELETE https://<KIBANA_URL>/api/exception_lists/items
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": "[request query]: namespace_type.0: Invalid enum value. Expected 'agnostic' | 'single', received 'blob'",
  "statusCode": 400
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403)
{
  "error": "Forbidden",
  "message": "API [DELETE /api/exception_lists/items?item_id=simple_list&namespace_type=single] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}
Response examples (404)
{
  "message": "exception list item item_id: \\\"foo\\\" does not exist",
  "status_code": 404
}
Response examples (500)
{
  "message": "Internal Server Error",
  "status_code": 500
}

Get exception list items Beta

GET /api/exception_lists/items/_find

Get a list of all exception list items in the specified list.

Query parameters

  • list_id array[string(nonempty)] Required

    The list_ids of the items to fetch.

    Minimum length of each is 1.

  • filter array[string(nonempty)]

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

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

  • namespace_type array[string]

    Determines whether the returned containers are Kibana associated with a Kibana space or available in all spaces (agnostic or single)

    Values are agnostic or single. Default value is ["single"].

  • page integer

    The page number to return

    Minimum value is 0.

  • per_page integer

    The number of exception list items to return per page

    Minimum value is 0.

  • sort_field string(nonempty)

    Determines which field is used to sort the results.

    Minimum length is 1.

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

    Values are desc or asc.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • data array[object] Required
      Hide data attributes Show data attributes object
      • _version string

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

      • comments array[object] Required

        Array of comment fields:

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

          A string that does not contain only whitespace characters

          Minimum length is 1.

        • created_at string(date-time) Required

          Autogenerated date of object creation.

        • created_by string(nonempty) Required

          A string that does not contain only whitespace characters

          Minimum length is 1.

        • id string(nonempty) Required

          A string that does not contain only whitespace characters

          Minimum length is 1.

        • updated_at string(date-time)

          Autogenerated date of last object update.

        • updated_by string(nonempty)

          A string that does not contain only whitespace characters

          Minimum length is 1.

      • created_at string(date-time) Required

        Autogenerated date of object creation.

      • created_by string Required

        Autogenerated value - user that created object.

      • description string Required

        Describes the exception list.

      • entries array[object] Required
        Any of:
        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.

    • page integer Required

      Minimum value is 1.

    • per_page integer Required

      Minimum value is 1.

    • pit string
    • 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
  • 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
GET /api/exception_lists/items/_find
curl \
 --request GET https://<KIBANA_URL>/api/exception_lists/items/_find?list_id=simple_list
Response examples (200)
{
  "data": [
    {
      "id": "459c5e7e-f8b2-4f0b-b136-c1fc702f72da",
      "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": [
            "jupiter",
            "saturn"
          ],
          "operator": "included"
        }
      ],
      "item_id": "simple_list_item",
      "list_id": "simple_list",
      "_version": "WzgsMV0=",
      "comments": [],
      "os_types": [
        "linux"
      ],
      "created_at": "2025-01-07T21:12:25.512Z",
      "created_by": "elastic",
      "updated_at": "2025-01-07T21:12:25.512Z",
      "updated_by": "elastic",
      "description": "This is a sample exception item.",
      "namespace_type": "single",
      "tie_breaker_id": "ad0754ff-7b19-49ca-b73e-e6aff6bfa2d0"
    }
  ],
  "page": 1,
  "total": 1,
  "per_page": 20
}
Response examples (400)
{
  "error": "Bad Request",
  "message": "[request query]: namespace_type.0: Invalid enum value. Expected 'agnostic' | 'single', received 'blob'",
  "statusCode": 400
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403)
{
  "error": "Forbidden",
  "message": "API [GET /api/exception_lists/items/_find?list_id=simple_list&namespace_type=single] is unauthorized for user, this action is granted by the Kibana privileges [lists-read]",
  "statusCode": 403
}
Response examples (404)
{
  "message": "exception list list_id: \"foo\" does not exist",
  "status_code": 404
}
Response examples (500)
{
  "message": "Internal Server Error",
  "status_code": 500
}

Get an exception list summary Beta

GET /api/exception_lists/summary

Get a summary of the specified exception list.

Query parameters

  • id string(nonempty)

    Exception list's identifier generated upon creation.

    Minimum length is 1.

  • list_id string(nonempty)

    Exception list's human readable identifier.

    Minimum length is 1.

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

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

    Values are agnostic or single. Default value is single.

  • filter string

    Search filter clause

Responses

GET /api/exception_lists/summary
curl \
 --request GET https://<KIBANA_URL>/api/exception_lists/summary
Response examples (200)
{
  "linux": 0,
  "macos": 0,
  "total": 0,
  "windows": 0
}
Response examples (400)
{
  "error": "Bad Request",
  "message": "[request query]: namespace_type.0: Invalid enum value. Expected 'agnostic' | 'single', received 'blob'",
  "statusCode": 400
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403)
{
  "error": "Forbidden",
  "message": "API [GET /api/exception_lists/summary?list_id=simple_list&namespace_type=agnostic] is unauthorized for user, this action is granted by the Kibana privileges [lists-summary]",
  "statusCode": 403
}
Response examples (404)
{
  "message\"": "exception list id: \"foo\" does not exist",
  "status_code\"": 404
}
Response examples (500)
{
  "message": "Internal Server Error",
  "status_code": 500
}

Create a shared exception list Beta

POST /api/exceptions/shared

An exception list groups exception items and can be associated with detection rules. A shared exception list can apply to multiple detection rules.

All exception items added to the same list are evaluated using OR logic. That is, if any of the items in a list evaluate to true, the exception prevents the rule from generating an alert. Likewise, OR logic is used for evaluating exceptions when more than one exception list is assigned to a rule. To use the AND operator, you can define multiple clauses (entries) in a single exception item.

application/json

Body Required

  • description string Required

    Describes the exception list.

  • name string Required

    The name of the exception list.

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

    Exception list already exists response

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

    Internal server error response

    Hide response attributes Show response attributes object
POST /api/exceptions/shared
curl \
 --request POST https://<KIBANA_URL>/api/exceptions/shared \
 --header "Content-Type: application/json" \
 --data '{"name":"Sample Detection Exception List","tags":["malware"],"list_id":"simple_list","os_types":["linux"],"description":"This is a sample detection type exception list.","namespace_type":"single"}'
Request example
{
  "name": "Sample Detection Exception List",
  "tags": [
    "malware"
  ],
  "list_id": "simple_list",
  "os_types": [
    "linux"
  ],
  "description": "This is a sample detection type exception list.",
  "namespace_type": "single"
}
Response examples (200)
{
  "id": "9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85",
  "name": "Sample Detection Exception List",
  "tags": [
    "malware"
  ],
  "type": "detection",
  "list_id": "simple_list",
  "version": 1,
  "_version": "WzIsMV0=",
  "os_types": [
    "linux"
  ],
  "immutable": false,
  "created_at": "2025-01-07T19:34:27.942Z",
  "created_by": "elastic",
  "updated_at": "2025-01-07T19:34:27.942Z",
  "updated_by": "elastic",
  "description": "This is a sample detection type exception list.",
  "namespace_type": "single",
  "tie_breaker_id": "78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3"
}
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)
{
  "message": "Unable to create exception-list",
  "status_code": 403
}
Response examples (409)
{
  "message": "exception list id: \"simple_list\" already exists",
  "status_code": 409
}
Response examples (500)
{
  "message": "Internal Server Error",
  "status_code": 500
}





Update a value list Beta

PUT /api/lists

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

You cannot modify the id value.

application/json

Body Required

Value list's properties

  • _version string

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

  • description string(nonempty) Required

    Describes the value list.

    Minimum length is 1.

  • id string(nonempty) Required

    Value list's identifier.

    Minimum length is 1.

  • meta object

    Placeholder for metadata about the value list.

    Additional properties are allowed.

  • name string(nonempty) Required

    Value list's name.

    Minimum length is 1.

  • version integer

    The document version number.

    Minimum value is 1.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • _version string

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

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

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

    • description string(nonempty) Required

      Describes the value list.

      Minimum length is 1.

    • 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
PUT /api/lists
curl \
 --request PUT https://<KIBANA_URL>/api/lists \
 --header "Content-Type: application/json" \
 --data '{"id":"ip_list","name":"Bad ips - updated","description":"Latest list of bad ips"}'
Request example
{
  "id": "ip_list",
  "name": "Bad ips - updated",
  "description": "Latest list of bad ips"
}
Response examples (200)
{
  "id": "ip_list",
  "name": "Bad ips - updated",
  "type": "ip",
  "version": 3,
  "_version": "WzIsMV0=",
  "immutable": false,
  "@timestamp": "2025-01-08T04:47:34.273Z",
  "created_at": "2025-01-08T04:47:34.273Z",
  "created_by": "elastic",
  "updated_at": "2025-01-08T05:39:39.292Z",
  "updated_by": "elastic",
  "description": "Latest list of bad ips",
  "tie_breaker_id": "f5508188-b1e9-4e6e-9662-d039a7d89899"
}
Response examples (400)
{
  "error": "Bad Request",
  "message": "[request body]: id: Expected string, received number",
  "statusCode": 400
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403)
{
  "error": "Forbidden",
  "message": "API [PUT /api/lists] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}
Response examples (404)
{
  "message": "list id: \\\"foo\\\" not found",
  "status_code": 404
}
Response examples (500)
{
  "message": "Internal Server Error",
  "status_code": 500
}

Create a value list Beta

POST /api/lists

Create a new value list.

application/json

Body Required

Value list's properties

  • description string(nonempty) Required

    Describes the value list.

    Minimum length is 1.

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

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

    Value list's identifier.

    Minimum length is 1.

  • meta object

    Placeholder for metadata about the value list.

    Additional properties are allowed.

  • name string(nonempty) Required

    Value list's name.

    Minimum length is 1.

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

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

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

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

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

  • version integer

    Minimum value is 1. Default value is 1.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • _version string

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

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

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

    • description string(nonempty) Required

      Describes the value list.

      Minimum length is 1.

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

    List already exists response

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

    Internal server error response

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

Delete a value list Beta

DELETE /api/lists

Delete a value list using the list ID.

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

Query parameters

  • id string(nonempty) Required

    Value list's identifier.

    Minimum length is 1.

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

    Default value is false.

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

    Default value is false.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • _version string

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

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

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

    • description string(nonempty) Required

      Describes the value list.

      Minimum length is 1.

    • 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
DELETE /api/lists
curl \
 --request DELETE https://<KIBANA_URL>/api/lists?id=21b01cfb-058d-44b9-838c-282be16c91cd
Response examples (200)
{
  "id": "21b01cfb-058d-44b9-838c-282be16c91cd",
  "name": "Bad ips",
  "type": "ip",
  "version": 3,
  "_version": "WzIsMV0=",
  "immutable": false,
  "@timestamp": "2025-01-08T04:47:34.273Z",
  "created_at": "2025-01-08T04:47:34.273Z",
  "created_by": "elastic",
  "updated_at": "2025-01-08T05:39:39.292Z",
  "updated_by": "elastic",
  "description": "List of bad internet ips.",
  "tie_breaker_id": "f5508188-b1e9-4e6e-9662-d039a7d89899"
}
Response examples (400)
{
  "error": "Bad Request",
  "message": "[request query]: id: Required",
  "statusCode": 400
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403)
{
  "error": "Forbidden",
  "message": "API [DELETE /api/lists?id=ip_list] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}
Response examples (404)
{
  "message": "list id: \\\"ip_list\\\" was not found",
  "status_code": 404
}
Response examples (500)
{
  "message": "Internal Server Error",
  "status_code": 500
}
















Delete value list data streams Beta

DELETE /api/lists/index

Delete the .lists and .items data streams.

Responses

DELETE /api/lists/index
curl \
 --request DELETE https://<KIBANA_URL>/api/lists/index
Response examples (200)
{
  "acknowledged": true
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42
}
{
  "message": "string",
  "status_code": 42
}
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": "string",
  "message": "string",
  "statusCode": 42
}
Response examples (404)
{
  "message": "string",
  "status_code": 42
}
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
}




Delete a value list item Beta

DELETE /api/lists/items

Delete a value list item using its id, or its list_id and value fields.

Query parameters

  • id string(nonempty)

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

    Minimum length is 1.

  • list_id string(nonempty)

    Value list's identifier. Required if id is not specified.

    Minimum length is 1.

  • value string

    The value used to evaluate exceptions. Required if id is not specified.

  • refresh string

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

    Values are true, false, or wait_for. Default value is false.

Responses

  • 200 application/json

    Successful response

    One of:
    Hide attributes Show attributes
    • _version string

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

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

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

    • 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
DELETE /api/lists/items
curl \
 --request DELETE https://<KIBANA_URL>/api/lists/items
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)
{
  "message": "Either \\\"list_id\\\" or \\\"id\\\" needs to be defined in the request",
  "status_code": 400
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403)
{
  "error": "Forbidden",
  "message": "API [DELETE /api/lists/items?id=pd1WRJQBs4HAK3VQeHFI] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}
Response examples (404)
{
  "message": "list item with id: \\\"pd1WRJQBs4HAK3VQeHFI\\\" not found",
  "status_code": 404
}
Response examples (500)
{
  "message": "Internal Server Error",
  "status_code": 500
}

Patch a value list item Beta

PATCH /api/lists/items

Update specific fields of an existing value list item using the item id.

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.

  • refresh string

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

    Values are true, false, or wait_for.

  • value string(nonempty)

    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
PATCH /api/lists/items
curl \
 --request PATCH https://<KIBANA_URL>/api/lists/items \
 --header "Content-Type: application/json" \
 --data '{"id":"pd1WRJQBs4HAK3VQeHFI","value":"255.255.255.255"}'
Request example
{
  "id": "pd1WRJQBs4HAK3VQeHFI",
  "value": "255.255.255.255"
}
Response examples (200)
{
  "id": "pd1WRJQBs4HAK3VQeHFI",
  "type": "ip",
  "value": "255.255.255.255",
  "list_id": "ip_list",
  "_version": "WzE5LDFd",
  "@timestamp": "2025-01-08T05:15:05.159Z",
  "created_at": "2025-01-08T05:15:05.159Z",
  "created_by": "elastic",
  "updated_at": "2025-01-08T05:23:37.602Z",
  "updated_by": "elastic",
  "tie_breaker_id": "eee41dc7-1666-4876-982f-8b0f7b59eca3"
}
Response examples (400)
{
  "message": "{\"took\":15,\"timed_out\":false,\"total\":1,\"updated\":0,\"deleted\":0,\"batches\":1,\"version_conflicts\":0,\"noops\":0,\"retries\":{\"bulk\":0,\"search\":0},\"throttled_millis\":0,\"requests_per_second\":-1,\"throttled_until_millis\":0,\"failures\":[{\"index\":\".ds-.items-default-2025.01.09-000001\",\"id\":\"ip_item\",\"cause\":{\"type\":\"document_parsing_exception\",\"reason\":\"[1:107] failed to parse field [ip] of type [ip] in document with id ip_item. Preview of fields value: 2\",\"caused_by\":{\"type\":\"illegal_argument_exception\",\"reason\":\"2 is not an IP string literal.\"}},\"status\":400}]}",
  "status_code": 400
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403)
{
  "error": "Forbidden",
  "message": "API [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
}




Get value list items Beta

GET /api/lists/items/_find

Get all value list items in the specified list.

Query parameters

  • list_id string(nonempty) Required

    Value list's identifier.

    Minimum length is 1.

  • page integer

    The page number to return.

  • per_page integer

    The number of list items 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 items that come after the last item 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 items 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

      Returns the items that come after the last item 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 items are sorted and returned correctly.

      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.

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

    • 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/items/_find
curl \
 --request GET https://<KIBANA_URL>/api/lists/items/_find?list_id=21b01cfb-058d-44b9-838c-282be16c91cd
Response examples (200)
{
  "data": [
    {
      "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"
    }
  ],
  "page": 1,
  "total": 1,
  "cursor": "WzIwLFsiYjU3Yzc2MmMtMzAzNi00NjVjLTliZmItN2JmYjVlNmU1MTVhIl1d",
  "per_page": 20
}
Response examples (400)
{
  "error": "Bad Request,",
  "message": "[request query]: list_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/items/_find?list_id=ip_list&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
}

Import value list items Beta

POST /api/lists/items/_import

Import value list items from a TXT or CSV file. The maximum file size is 9 million bytes.

You can import items to a new or existing list.

Query parameters

  • list_id string(nonempty)

    List's id.

    Required when importing to an existing list.

    Minimum length is 1.

  • type string

    Type of the importing list.

    Required when importing a new list whose list id is not specified.

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

  • 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.
  • Determines how retrieved list item values are presented. By default list items are presented using these Handelbar expressions:

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

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

    Values are true, false, or wait_for.

multipart/form-data

Body Required

  • file string(binary)

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

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • _version string

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

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

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

    • description string(nonempty) Required

      Describes the value list.

      Minimum length is 1.

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

    List with specified list_id does not exist response

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

    Internal server error response

    Hide response attributes Show response attributes object
POST /api/lists/items/_import
curl \
 --request POST https://<KIBANA_URL>/api/lists/items/_import \
 --header "Content-Type: multipart/form-data" \
 --form "file=127.0.0.1
127.0.0.2
127.0.0.3
127.0.0.4
127.0.0.5
127.0.0.6
127.0.0.7
127.0.0.8
127.0.0.9
"
Response examples (200)
{
  "id": "ip_list",
  "name": "Simple list with an ip",
  "type": "ip",
  "version": 1,
  "_version": "WzAsMV0=",
  "immutable": false,
  "@timestamp": "2025-01-08T04:47:34.273Z",
  "created_at": "2025-01-08T04:47:34.273Z",
  "created_by": "elastic",
  "updated_at": "2025-01-08T04:47:34.273Z",
  "updated_by": "elastic",
  "description": "This list describes bad internet ip",
  "tie_breaker_id": "f5508188-b1e9-4e6e-9662-d039a7d89899"
}
Response examples (400)
{
  "message": "Either type or list_id need to be defined in the query",
  "status_code": 400
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403)
{
  "error": "Forbidden",
  "message": "API [POST /api/lists/items/_import?list_id=ip_list] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}
Response examples (409)
{
  "message": "string",
  "status_code": 42
}
Response examples (500)
{
  "message": "Internal Server Error",
  "status_code": 500
}

Get value list privileges Beta

GET /api/lists/privileges

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • is_authenticated boolean Required
    • listItems object Required

      Additional properties are allowed.

      Hide listItems attributes Show listItems attributes object
      • application object Required
        Hide application attribute Show application attribute object
        • * boolean Additional properties
      • cluster object Required
        Hide cluster attribute Show cluster attribute object
        • * boolean Additional properties
      • has_all_requested boolean Required
      • index object Required
        Hide index attribute Show index attribute object
        • * object Additional properties
          Hide * attribute Show * attribute object
          • * boolean Additional properties
      • username string Required
    • lists object Required

      Additional properties are allowed.

      Hide lists attributes Show lists attributes object
      • application object Required
        Hide application attribute Show application attribute object
        • * boolean Additional properties
      • cluster object Required
        Hide cluster attribute Show cluster attribute object
        • * boolean Additional properties
      • has_all_requested boolean Required
      • index object Required
        Hide index attribute Show index attribute object
        • * object Additional properties
          Hide * attribute Show * attribute object
          • * boolean Additional properties
      • username string Required
  • 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/privileges
curl \
 --request GET https://<KIBANA_URL>/api/lists/privileges
Response examples (200)
{
  "lists": {
    "index": {
      ".lists-default": {
        "all": true,
        "read": true,
        "index": true,
        "write": true,
        "create": true,
        "delete": true,
        "manage": true,
        "monitor": true,
        "create_doc": true,
        "maintenance": true,
        "create_index": true,
        "delete_index": true,
        "view_index_metadata": true
      }
    },
    "cluster": {
      "all": true,
      "manage": true,
      "monitor": true,
      "manage_ml": true,
      "monitor_ml": true,
      "manage_api_key": true,
      "manage_pipeline": true,
      "manage_security": true,
      "manage_transform": true,
      "monitor_transform": true,
      "manage_own_api_key": true,
      "manage_index_templates": true
    },
    "username": "elastic",
    "application": {},
    "has_all_requested": true
  },
  "listItems": {
    "index": {
      ".items-default": {
        "all": true,
        "read": true,
        "index": true,
        "write": true,
        "create": true,
        "delete": true,
        "manage": true,
        "monitor": true,
        "create_doc": true,
        "maintenance": true,
        "create_index": true,
        "delete_index": true,
        "view_index_metadata": true
      }
    },
    "cluster": {
      "all": true,
      "manage": true,
      "monitor": true,
      "manage_ml": true,
      "monitor_ml": true,
      "manage_api_key": true,
      "manage_pipeline": true,
      "manage_security": true,
      "manage_transform": true,
      "monitor_transform": true,
      "manage_own_api_key": true,
      "manage_index_templates": true
    },
    "username": "elastic",
    "application": {},
    "has_all_requested": true
  },
  "is_authenticated": true
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42
}
{
  "message": "string",
  "status_code": 42
}
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/privileges] 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
}

















Get packs Beta

GET /api/osquery/packs

Get a list of all query packs.

Query parameters

Responses

  • 200 application/json

    OK

    Additional properties are allowed.

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

Create a pack Beta

POST /api/osquery/packs

Create a query pack.

application/json

Body Required

Responses

  • 200 application/json

    OK

    Additional properties are allowed.

POST /api/osquery/packs
curl \
 --request POST https://<KIBANA_URL>/api/osquery/packs \
 --header "Content-Type: application/json" \
 --data '{"description":"string","enabled":true,"name":"string","policy_ids":["string"],"queries":{"additionalProperty1":{"ecs_mapping":{"additionalProperty1":{"field":"string","value":"string"},"additionalProperty2":{"field":"string","value":"string"}},"id":"string","platform":"string","query":"string","removed":true,"saved_query_id":"string","snapshot":true,"version":"string"},"additionalProperty2":{"ecs_mapping":{"additionalProperty1":{"field":"string","value":"string"},"additionalProperty2":{"field":"string","value":"string"}},"id":"string","platform":"string","query":"string","removed":true,"saved_query_id":"string","snapshot":true,"version":"string"}},"shards":{"additionalProperty1":42.0,"additionalProperty2":42.0}}'
Request examples
{
  "description": "string",
  "enabled": true,
  "name": "string",
  "policy_ids": [
    "string"
  ],
  "queries": {
    "additionalProperty1": {
      "ecs_mapping": {
        "additionalProperty1": {
          "field": "string",
          "value": "string"
        },
        "additionalProperty2": {
          "field": "string",
          "value": "string"
        }
      },
      "id": "string",
      "platform": "string",
      "query": "string",
      "removed": true,
      "saved_query_id": "string",
      "snapshot": true,
      "version": "string"
    },
    "additionalProperty2": {
      "ecs_mapping": {
        "additionalProperty1": {
          "field": "string",
          "value": "string"
        },
        "additionalProperty2": {
          "field": "string",
          "value": "string"
        }
      },
      "id": "string",
      "platform": "string",
      "query": "string",
      "removed": true,
      "saved_query_id": "string",
      "snapshot": true,
      "version": "string"
    }
  },
  "shards": {
    "additionalProperty1": 42.0,
    "additionalProperty2": 42.0
  }
}
Response examples (200)
{}

Get pack details Beta

GET /api/osquery/packs/{id}

Get the details of a query pack using the pack ID.

Path parameters

  • id string | null Required

Responses

  • 200 application/json

    OK

    Additional properties are allowed.

GET /api/osquery/packs/{id}
curl \
 --request GET https://<KIBANA_URL>/api/osquery/packs/{id}
Response examples (200)
{}








Get saved queries Beta

GET /api/osquery/saved_queries

Get a list of all saved queries.

Query parameters

Responses

  • 200 application/json

    OK

    Additional properties are allowed.

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












Delete a saved query Beta

DELETE /api/osquery/saved_queries/{id}

Delete a saved query using the query ID.

Path parameters

  • id string | null Required

Responses

  • 200 application/json

    OK

    Additional properties are allowed.

DELETE /api/osquery/saved_queries/{id}
curl \
 --request DELETE https://<KIBANA_URL>/api/osquery/saved_queries/{id}
Response examples (200)
{}













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
}
















































Get Timelines or Timeline templates Beta

GET /api/timelines

Get a list of all saved Timelines or Timeline templates.

Query parameters

  • only_user_favorite string | null

    If true, only timelines that are marked as favorites by the user are returned.

    Values are true or false.

  • timeline_type string | null

    The type of timeline to create. Valid values are default and template.

    Values are default or template.

  • The field to sort the timelines by.

    Values are title, description, updated, or created.

  • Values are asc or desc.

  • page_size string | null
  • page_index string | null
  • status string | null

    The status of the timeline. Valid values are active, draft, and immutable.

    Values are active, draft, or immutable.

Responses

GET /api/timelines
curl \
 --request GET https://<KIBANA_URL>/api/timelines
Response examples (200)
{
  "customTemplateTimelineCount": 42.0,
  "defaultTimelineCount": 42.0,
  "elasticTemplateTimelineCount": 42.0,
  "favoriteCount": 42.0,
  "templateTimelineCount": 42.0,
  "timeline": [
    {
      "columns": [
        {
          "aggregatable": true,
          "category": "string",
          "columnHeaderType": "string",
          "description": "string",
          "example": "string",
          "id": "string",
          "indexes": [
            "string"
          ],
          "name": "string",
          "placeholder": "string",
          "searchable": true,
          "type": "string"
        }
      ],
      "created": 42.0,
      "createdBy": "string",
      "dataProviders": [
        {
          "and": [
            {
              "enabled": true,
              "excluded": true,
              "id": "string",
              "kqlQuery": "string",
              "name": "string",
              "queryMatch": {
                "displayField": "string",
                "displayValue": "string",
                "field": "string",
                "operator": "string",
                "value": "string"
              },
              "type": "default"
            }
          ],
          "enabled": true,
          "excluded": true,
          "id": "string",
          "kqlQuery": "string",
          "name": "string",
          "queryMatch": {
            "displayField": "string",
            "displayValue": "string",
            "field": "string",
            "operator": "string",
            "value": "string"
          },
          "type": "default"
        }
      ],
      "dataViewId": "string",
      "dateRange": {
        "end": "string",
        "start": "string"
      },
      "description": "string",
      "eqlOptions": {
        "eventCategoryField": "string",
        "query": "string",
        "size": "string",
        "tiebreakerField": "string",
        "timestampField": "string"
      },
      "eventType": "string",
      "excludedRowRendererIds": [
        "alert"
      ],
      "favorite": [
        {
          "favoriteDate": 42.0,
          "fullName": "string",
          "userName": "string"
        }
      ],
      "filters": [
        {
          "exists": "string",
          "match_all": "string",
          "meta": {
            "alias": "string",
            "controlledBy": "string",
            "disabled": true,
            "field": "string",
            "formattedValue": "string",
            "index": "string",
            "key": "string",
            "negate": true,
            "params": "string",
            "type": "string",
            "value": "string"
          },
          "missing": "string",
          "query": "string",
          "range": "string",
          "script": "string"
        }
      ],
      "indexNames": [
        "string"
      ],
      "kqlMode": "string",
      "kqlQuery": {
        "filterQuery": {
          "kuery": {
            "expression": "string",
            "kind": "string"
          },
          "serializedQuery": "string"
        }
      },
      "savedQueryId": "string",
      "savedSearchId": "string",
      "sort": {
        "columnId": "string",
        "columnType": "string",
        "sortDirection": "string"
      },
      "status": "active",
      "templateTimelineId": "string",
      "templateTimelineVersion": 42.0,
      "timelineType": "default",
      "title": "string",
      "updated": 42.0,
      "updatedBy": "string",
      "savedObjectId": "string",
      "version": "string",
      "eventIdToNoteIds": [
        {
          "created": 42.0,
          "createdBy": "string",
          "eventId": "string",
          "note": "string",
          "timelineId": "string",
          "updated": 42.0,
          "updatedBy": "string",
          "noteId": "string",
          "version": "string"
        }
      ],
      "noteIds": [
        "string"
      ],
      "notes": [
        {
          "created": 42.0,
          "createdBy": "string",
          "eventId": "string",
          "note": "string",
          "timelineId": "string",
          "updated": 42.0,
          "updatedBy": "string",
          "noteId": "string",
          "version": "string"
        }
      ],
      "pinnedEventIds": [
        "string"
      ],
      "pinnedEventsSaveObject": [
        {
          "created": 42.0,
          "createdBy": "string",
          "eventId": "string",
          "timelineId": "string",
          "updated": 42.0,
          "updatedBy": "string",
          "pinnedEventId": "string",
          "version": "string"
        }
      ]
    }
  ],
  "totalCount": 42.0
}
Response examples (400)
{
  "body": "string",
  "statusCode": 42.0
}

Service level objectives

SLO APIs enable you to define, manage and track service-level objectives









Batch delete rollup and summary data Beta

POST /s/{spaceId}/api/observability/slos/_delete_instances

The deletion occurs for the specified list of sloId and instanceId. You must have all 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.

application/json

Body Required

  • list array[object] Required

    An array of slo id and instance id

    Hide list attributes Show list attributes object
    • instanceId string Required

      The SLO instance identifier

    • sloId string Required

      The SLO unique identifier

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
POST /s/{spaceId}/api/observability/slos/_delete_instances
curl \
 --request POST https://<KIBANA_URL>/s/default/api/observability/slos/_delete_instances \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"list":[{"instanceId":"8853df00-ae2e-11ed-90af-09bb6422b258","sloId":"8853df00-ae2e-11ed-90af-09bb6422b258"}]}'
Request examples
# Headers
kbn-xsrf: string

# Payload
{
  "list": [
    {
      "instanceId": "8853df00-ae2e-11ed-90af-09bb6422b258",
      "sloId": "8853df00-ae2e-11ed-90af-09bb6422b258"
    }
  ]
}
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
}