Kibana APIs
1.0.2

Base URL
https://localhost:5601

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

To interact with Kibana APIs, use the following operations:

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

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

GET kbn:/api/data_views

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

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

Documentation source and versions

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

This documentation contains work-in-progress information for future Elastic Stack releases.

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












































Update the API key for a rule

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

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.

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

POST /api/alerting/rule/{id}/_update_api_key
curl \
 --request POST https://localhost:5601/api/alerting/rule/{id}/_update_api_key \
 --header "kbn-xsrf: true"

































Lookup single agent configuration

POST /api/apm/settings/agent-configuration/search

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

Headers

  • elastic-api-version string Required

    The version of the API to use

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

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

application/json

Body Required

  • etag string

    If etags match then applied_by_agent field will be set to true

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

  • service object Required

    Service

    Additional properties are allowed.

    Hide service attributes Show service attributes object

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • _id string

      Identifier

    • _index string

      Index

    • _score number

      Score

    • _source object

      Agent configuration

      Additional properties are allowed.

      Hide _source attributes Show _source attributes object
      • @timestamp number Required

        Timestamp

      • Agent name

      • Applied by agent

      • etag string Required

        Etag

      • service object Required

        Service

        Additional properties are allowed.

        Hide service attributes Show service attributes object
      • settings object Required

        Agent configuration settings

        Hide settings attribute Show settings attribute object
        • * string Additional properties
  • 400 application/json

    Bad Request response

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

    Unauthorized response

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

    Not found response

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

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









APM annotations

Annotate visualizations in the APM app with significant events. Annotations enable you to easily see how events are impacting the performance of your applications.














APM sourcemaps

Configure APM source maps.

























































































































































Get data streams

GET /api/fleet/data_streams

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

Responses

GET /api/fleet/data_streams
curl \
 --request GET https://localhost:5601/api/fleet/data_streams
Response examples (200)
{
  "data_streams": [
    {
      "dashboards": [
        {
          "id": "string",
          "title": "string"
        }
      ],
      "dataset": "string",
      "index": "string",
      "last_activity_ms": 42.0,
      "namespace": "string",
      "package": "string",
      "package_version": "string",
      "serviceDetails": {
        "environment": "string",
        "serviceName": "string"
      },
      "size_in_bytes": 42.0,
      "size_in_bytes_formatted": 42.0,
      "type": "string"
    }
  ]
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}

























Update data view fields metadata

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

Update fields presentation metadata such as count, customLabel, customDescription, and format.

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

  • fields object Required

    The field object.

    Additional properties are allowed.

Responses

  • 200 application/json

    Indicates a successful call.

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

    Bad request

    Hide response attributes Show response attributes object
POST /api/data_views/data_view/{viewId}/fields
curl \
 --request POST https://localhost:5601/api/data_views/data_view/ff959d40-b880-11e8-a6d9-e546fe2bba5f/fields \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"fields":{"field1":{"count":123,"customLabel":"Field 1 label"},"field2":{"customLabel":"Field 2 label","customDescription":"Field 2 description"}}}'
Request example
{
  "fields": {
    "field1": {
      "count": 123,
      "customLabel": "Field 1 label"
    },
    "field2": {
      "customLabel": "Field 2 label",
      "customDescription": "Field 2 description"
    }
  }
}
Response examples (200)
{
  "acknowledged": true
}
Response examples (400)
{
  "error": "Bad Request",
  "message": "string",
  "statusCode": 400
}









































Reassign an agent

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

[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}/reassign
curl \
 --request POST https://localhost:5601/api/fleet/agents/{agentId}/reassign \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"policy_id":"string"}'
Request examples
# Headers
kbn-xsrf: true

# Payload
{
  "policy_id": "string"
}
Response examples (200)
{}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}
























Bulk request diagnostics from agents

POST /api/fleet/agents/bulk_request_diagnostics

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

application/json

Body

Responses

POST /api/fleet/agents/bulk_request_diagnostics
curl \
 --request POST https://localhost:5601/api/fleet/agents/bulk_request_diagnostics \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"additional_metrics":["CPU"],"agents":["string"],"batchSize":42.0}'
Request examples
# Headers
kbn-xsrf: true

# Payload
{
  "additional_metrics": [
    "CPU"
  ],
  "agents": [
    "string"
  ],
  "batchSize": 42.0
}
Response examples (200)
{
  "actionId": "string"
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}





















Get an agent binary download source

GET /api/fleet/agent_download_sources/{sourceId}

Get an agent binary download source by ID.

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

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
GET /api/fleet/agent_download_sources/{sourceId}
curl \
 --request GET https://localhost:5601/api/fleet/agent_download_sources/{sourceId}
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
}


























































































































































































































Update settings

PUT /api/fleet/settings

[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/settings
curl \
 --request PUT https://localhost:5601/api/fleet/settings \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"additional_yaml_config":"string","delete_unenrolled_agents":{"enabled":true,"is_preconfigured":true},"has_seen_add_data_notice":true,"kibana_ca_sha256":"string","kibana_urls":["https://example.com"],"prerelease_integrations_enabled":true}'
Request examples
# Headers
kbn-xsrf: true

# Payload
{
  "additional_yaml_config": "string",
  "delete_unenrolled_agents": {
    "enabled": true,
    "is_preconfigured": true
  },
  "has_seen_add_data_notice": true,
  "kibana_ca_sha256": "string",
  "kibana_urls": [
    "https://example.com"
  ],
  "prerelease_integrations_enabled": true
}
Response examples (200)
{
  "item": {
    "delete_unenrolled_agents": {
      "enabled": true,
      "is_preconfigured": true
    },
    "has_seen_add_data_notice": true,
    "id": "string",
    "output_secret_storage_requirements_met": true,
    "preconfigured_fields": [
      "fleet_server_hosts"
    ],
    "prerelease_integrations_enabled": true,
    "secret_storage_requirements_met": true,
    "use_space_awareness_migration_started_at": "string",
    "use_space_awareness_migration_status": "pending",
    "version": "string"
  }
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}
Response examples (404)
{
  "message": "string"
}


































Get package policies

GET /api/fleet/package_policies

Query parameters

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • items array[object] Required
      Hide items attributes Show items attributes object
      • agents number
      • created_at string Required
      • created_by string Required
      • Package policy description

      • Additional properties are allowed.

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

          Hide privileges attribute Show privileges attribute object
      • enabled boolean Required
      • id string Required
      • inputs array[object] | object Required

        Any of:
        Hide attributes Show attributes object
        • config object

          Package variable (see integration documentation for more information)

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

            Additional properties are NOT allowed.

            Hide * attributes Show * attributes object
        • enabled boolean Required
        • id string
        • streams array[object] Required
          Hide streams attributes Show streams attributes object
          • config object

            Package variable (see integration documentation for more information)

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

              Additional properties are NOT allowed.

              Hide * attributes Show * attributes object
          • data_stream object Required

            Additional properties are NOT allowed.

            Hide data_stream attributes Show data_stream attributes object
          • enabled boolean Required
          • id string
          • release string

            Values are ga, beta, or experimental.

          • vars object

            Package variable (see integration documentation for more information)

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

              Additional properties are NOT allowed.

              Hide * attributes Show * attributes object
        • type string Required
        • vars object

          Package variable (see integration documentation for more information)

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

            Additional properties are NOT allowed.

            Hide * attributes Show * attributes object
      • is_managed boolean
      • name string Required

        Package policy name (should be unique)

      • The package policy namespace. Leave blank to inherit the agent policy's namespace.

      • output_id string | null
      • overrides object | null

        Override settings that are defined in the package policy. The override option should be used only in unusual circumstances and not as a routine procedure.

        Additional properties are NOT allowed.

        Hide overrides attribute Show overrides attribute object | null
        • inputs object

          Additional properties are allowed.

      • package object

        Additional properties are NOT allowed.

        Hide package attributes Show package attributes object
      • policy_id string | null Deprecated

        Agent policy ID where that package policy will be added

      • policy_ids array[string]

        Agent policy IDs where that package policy will be added

      • revision number Required
      • secret_references array[object]
        Hide secret_references attribute Show secret_references attribute object
        • id string Required
      • spaceIds array[string]
      • supports_agentless boolean | null

        Indicates whether the package policy belongs to an agentless agent policy.

        Default value is false.

      • updated_at string Required
      • updated_by string Required
      • vars object

        Any of:

        Package variable (see integration documentation for more information)

        Hide attribute Show attribute
        • * object Additional properties

          Additional properties are NOT allowed.

          Hide * attributes Show * attributes object
      • version string
    • page number Required
    • perPage number Required
    • total number Required
  • 400 application/json
    Hide response attributes Show response attributes object
GET /api/fleet/package_policies
curl \
 --request GET https://localhost:5601/api/fleet/package_policies
Response examples (200)
{
  "items": [
    {
      "agents": 42.0,
      "created_at": "string",
      "created_by": "string",
      "description": "string",
      "elasticsearch": {
        "privileges": {
          "cluster": [
            "string"
          ]
        }
      },
      "enabled": true,
      "id": "string",
      "inputs": [
        {
          "config": {
            "additionalProperty1": {
              "frozen": true,
              "type": "string"
            },
            "additionalProperty2": {
              "frozen": true,
              "type": "string"
            }
          },
          "enabled": true,
          "id": "string",
          "keep_enabled": true,
          "policy_template": "string",
          "streams": [
            {
              "config": {
                "additionalProperty1": {
                  "frozen": true,
                  "type": "string"
                },
                "additionalProperty2": {
                  "frozen": true,
                  "type": "string"
                }
              },
              "data_stream": {
                "dataset": "string",
                "elasticsearch": {
                  "dynamic_dataset": true,
                  "dynamic_namespace": true,
                  "privileges": {
                    "indices": [
                      "string"
                    ]
                  }
                },
                "type": "string"
              },
              "enabled": true,
              "id": "string",
              "keep_enabled": true,
              "release": "ga",
              "vars": {
                "additionalProperty1": {
                  "frozen": true,
                  "type": "string"
                },
                "additionalProperty2": {
                  "frozen": true,
                  "type": "string"
                }
              }
            }
          ],
          "type": "string",
          "vars": {
            "additionalProperty1": {
              "frozen": true,
              "type": "string"
            },
            "additionalProperty2": {
              "frozen": true,
              "type": "string"
            }
          }
        }
      ],
      "is_managed": true,
      "name": "string",
      "namespace": "string",
      "output_id": "string",
      "overrides": {
        "inputs": {}
      },
      "package": {
        "experimental_data_stream_features": [
          {
            "data_stream": "string",
            "features": {
              "doc_value_only_numeric": true,
              "doc_value_only_other": true,
              "synthetic_source": true,
              "tsdb": true
            }
          }
        ],
        "name": "string",
        "requires_root": true,
        "title": "string",
        "version": "string"
      },
      "policy_id": "string",
      "policy_ids": [
        "string"
      ],
      "revision": 42.0,
      "secret_references": [
        {
          "id": "string"
        }
      ],
      "spaceIds": [
        "string"
      ],
      "supports_agentless": false,
      "updated_at": "string",
      "updated_by": "string",
      "vars": {
        "additionalProperty1": {
          "frozen": true,
          "type": "string"
        },
        "additionalProperty2": {
          "frozen": true,
          "type": "string"
        }
      },
      "version": "string"
    }
  ],
  "page": 42.0,
  "perPage": 42.0,
  "total": 42.0
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}
















Delete a package policy

DELETE /api/fleet/package_policies/{packagePolicyId}

Delete a package policy by ID.

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Responses

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








Dry run a package policy upgrade

POST /api/fleet/package_policies/upgrade/dryrun

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

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

        Additional properties are allowed.

        Hide data_stream attribute Show data_stream attribute object
      • id string Required
      • meta object

        Additional properties are allowed.

        Hide meta attribute Show meta attribute object
        • package object Required

          Additional properties are allowed.

          Hide package attributes Show package attributes object
      • name string Required
      • package_policy_id string Required
      • processors array[object]
        Hide processors attribute Show processors attribute object
        • add_fields object Required

          Additional properties are allowed.

          Hide add_fields attributes Show add_fields attributes object
      • revision number Required
      • streams array[object]
        Hide streams attributes Show streams attributes object
        • data_stream object Required

          Additional properties are allowed.

          Hide data_stream attributes Show data_stream attributes object
        • id string Required
      • type string Required
      • use_output string Required
    • body object

      Additional properties are NOT allowed.

      Hide body attribute Show body attribute object
    • diff array[object]
      Any of:
      Hide attributes Show attributes
      • agents number
      • created_at string Required
      • created_by string Required
      • Package policy description

      • Additional properties are allowed.

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

          Hide privileges attribute Show privileges attribute object
      • enabled boolean Required
      • id string
      • inputs array[object] | object Required

        Any of:
        Hide attributes Show attributes object
        • config object

          Package variable (see integration documentation for more information)

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

            Additional properties are NOT allowed.

            Hide * attributes Show * attributes object
        • enabled boolean Required
        • id string
        • streams array[object] Required
          Hide streams attributes Show streams attributes object
          • config object

            Package variable (see integration documentation for more information)

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

              Additional properties are NOT allowed.

              Hide * attributes Show * attributes object
          • data_stream object Required

            Additional properties are NOT allowed.

            Hide data_stream attributes Show data_stream attributes object
          • enabled boolean Required
          • id string
          • release string

            Values are ga, beta, or experimental.

          • vars object

            Package variable (see integration documentation for more information)

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

              Additional properties are NOT allowed.

              Hide * attributes Show * attributes object
        • type string Required
        • vars object

          Package variable (see integration documentation for more information)

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

            Additional properties are NOT allowed.

            Hide * attributes Show * attributes object
      • is_managed boolean
      • name string Required

        Package policy name (should be unique)

      • The package policy namespace. Leave blank to inherit the agent policy's namespace.

      • output_id string | null
      • overrides object | null

        Override settings that are defined in the package policy. The override option should be used only in unusual circumstances and not as a routine procedure.

        Additional properties are NOT allowed.

        Hide overrides attribute Show overrides attribute object | null
        • inputs object

          Additional properties are allowed.

      • package object

        Additional properties are NOT allowed.

        Hide package attributes Show package attributes object
      • policy_id string | null Deprecated

        Agent policy ID where that package policy will be added

      • policy_ids array[string]

        Agent policy IDs where that package policy will be added

      • revision number Required
      • secret_references array[object]
        Hide secret_references attribute Show secret_references attribute object
        • id string Required
      • spaceIds array[string]
      • supports_agentless boolean | null

        Indicates whether the package policy belongs to an agentless agent policy.

        Default value is false.

      • updated_at string Required
      • updated_by string Required
      • vars object

        Any of:

        Package variable (see integration documentation for more information)

        Hide attribute Show attribute
        • * object Additional properties

          Additional properties are NOT allowed.

          Hide * attributes Show * attributes object
      • version string
    • hasErrors boolean Required
    • name string
  • 400 application/json
    Hide response attributes Show response attributes object
POST /api/fleet/package_policies/upgrade/dryrun
curl \
 --request POST https://localhost:5601/api/fleet/package_policies/upgrade/dryrun \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"packagePolicyIds":["string"],"packageVersion":"string"}'
Request examples
# Headers
kbn-xsrf: true

# Payload
{
  "packagePolicyIds": [
    "string"
  ],
  "packageVersion": "string"
}
Response examples (200)
[
  {
    "agent_diff": [
      [
        {
          "data_stream": {
            "namespace": "string"
          },
          "id": "string",
          "meta": {
            "package": {
              "name": "string",
              "version": "string"
            }
          },
          "name": "string",
          "package_policy_id": "string",
          "processors": [
            {
              "add_fields": {
                "fields": {},
                "target": "string"
              }
            }
          ],
          "revision": 42.0,
          "streams": [
            {
              "data_stream": {
                "dataset": "string",
                "type": "string"
              },
              "id": "string"
            }
          ],
          "type": "string",
          "use_output": "string"
        }
      ]
    ],
    "body": {
      "message": "string"
    },
    "diff": [
      {
        "agents": 42.0,
        "created_at": "string",
        "created_by": "string",
        "description": "string",
        "elasticsearch": {
          "privileges": {
            "cluster": [
              "string"
            ]
          }
        },
        "enabled": true,
        "id": "string",
        "inputs": [
          {
            "config": {
              "additionalProperty1": {
                "frozen": true,
                "type": "string"
              },
              "additionalProperty2": {
                "frozen": true,
                "type": "string"
              }
            },
            "enabled": true,
            "id": "string",
            "keep_enabled": true,
            "policy_template": "string",
            "streams": [
              {
                "config": {
                  "additionalProperty1": {
                    "frozen": true,
                    "type": "string"
                  },
                  "additionalProperty2": {
                    "frozen": true,
                    "type": "string"
                  }
                },
                "data_stream": {
                  "dataset": "string",
                  "elasticsearch": {
                    "dynamic_dataset": true,
                    "dynamic_namespace": true,
                    "privileges": {
                      "indices": [
                        "string"
                      ]
                    }
                  },
                  "type": "string"
                },
                "enabled": true,
                "id": "string",
                "keep_enabled": true,
                "release": "ga",
                "vars": {
                  "additionalProperty1": {
                    "frozen": true,
                    "type": "string"
                  },
                  "additionalProperty2": {
                    "frozen": true,
                    "type": "string"
                  }
                }
              }
            ],
            "type": "string",
            "vars": {
              "additionalProperty1": {
                "frozen": true,
                "type": "string"
              },
              "additionalProperty2": {
                "frozen": true,
                "type": "string"
              }
            }
          }
        ],
        "is_managed": true,
        "name": "string",
        "namespace": "string",
        "output_id": "string",
        "overrides": {
          "inputs": {}
        },
        "package": {
          "experimental_data_stream_features": [
            {
              "data_stream": "string",
              "features": {
                "doc_value_only_numeric": true,
                "doc_value_only_other": true,
                "synthetic_source": true,
                "tsdb": true
              }
            }
          ],
          "name": "string",
          "requires_root": true,
          "title": "string",
          "version": "string"
        },
        "policy_id": "string",
        "policy_ids": [
          "string"
        ],
        "revision": 42.0,
        "secret_references": [
          {
            "id": "string"
          }
        ],
        "spaceIds": [
          "string"
        ],
        "supports_agentless": false,
        "updated_at": "string",
        "updated_by": "string",
        "vars": {
          "additionalProperty1": {
            "frozen": true,
            "type": "string"
          },
          "additionalProperty2": {
            "frozen": true,
            "type": "string"
          }
        },
        "version": "string"
      }
    ],
    "hasErrors": true,
    "name": "string",
    "statusCode": 42.0
  }
]
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}

























































Rotate a Fleet message signing key pair

POST /api/fleet/message_signing_service/rotate_key_pair

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Query parameters

Responses

POST /api/fleet/message_signing_service/rotate_key_pair
curl \
 --request POST https://localhost:5601/api/fleet/message_signing_service/rotate_key_pair \
 --header "kbn-xsrf: true"
Response examples (200)
{
  "message": "string"
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}
Response examples (500)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}



































Delete saved objects Deprecated

POST /api/saved_objects/_bulk_delete

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

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

Query parameters

  • force boolean

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

application/json

Body Required

object object

Additional properties are allowed.

Responses

  • 200 application/json

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

    Additional properties are allowed.

  • 400 application/json

    Bad request

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

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








Update saved objects Deprecated

POST /api/saved_objects/_bulk_update

Update the attributes for multiple Kibana saved objects.

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

application/json

Body Required

object object

Additional properties are allowed.

Responses

  • 200 application/json

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

    Additional properties are allowed.

  • 400 application/json

    Bad request

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

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

























































Get a conversation

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

Get the details of an existing conversation using the conversation ID.

Path parameters

  • id string(nonempty) Required

    The conversation's id value.

    Minimum length is 1.

Responses

  • 200 application/json

    Indicates a successful call.

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

      Additional properties are allowed.

      Hide apiConfig attributes Show apiConfig attributes object
    • category string Required

      The conversation category.

      Values are assistant or insights.

    • createdAt string Required

      The last time conversation was updated.

    • excludeFromLastConversationStorage.

    • id string(nonempty) Required

      A string that does not contain only whitespace characters

      Minimum length is 1.

    • isDefault boolean

      Is default conversation.

    • messages array[object]

      The conversation messages.

      Hide messages attributes Show messages attributes object
      • content string Required

        Message content.

      • isError boolean

        Is error message.

      • metadata object

        metadata

        Additional properties are allowed.

        Hide metadata attribute Show metadata attribute object
      • reader object

        Message content.

        Additional properties are allowed.

      • role string Required

        Message role.

        Values are system, user, or assistant.

      • timestamp string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • trace Data

        Additional properties are allowed.

        Hide traceData attributes Show traceData attributes object
        • traceId string

          Could be any string, not necessarily a UUID

        • Could be any string, not necessarily a UUID

    • namespace string Required

      Kibana space

    • Replacements object used to anonymize/deanomymize messsages

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

      Additional properties are allowed.

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

        Values are low, medium, or high.

      • content string

        Summary text of the conversation over time.

      • public boolean

        Define if summary is marked as publicly available.

      • timestamp string(nonempty)

        A string that does not contain only whitespace characters

        Minimum length is 1.

    • timestamp string(nonempty)

      A string that does not contain only whitespace characters

      Minimum length is 1.

    • title string Required

      The conversation title.

    • The last time conversation was updated.

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

    Generic Error

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








Read a KnowledgeBase

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://localhost:5601/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
}

























































































































Assign and unassign users from detection alerts

POST /api/detection_engine/signals/assignees

Assign users to detection alerts, and unassign them from alerts.

You cannot add and remove the same assignee in the same request.

application/json

Body Required

  • assignees object Required

    Details about the assignees to assign and unassign.

    Additional properties are allowed.

    Hide assignees attributes Show assignees attributes object
    • add array[string(nonempty)] Required

      A list of users ids to assign.

      Minimum length of each is 1.

    • remove array[string(nonempty)] Required

      A list of users ids to unassign.

      Minimum length of each is 1.

  • ids array[string(nonempty)] Required

    A list of alerts ids.

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

Responses

  • 200 application/ndjson

    Indicates a successful call.

  • Invalid request.

POST /api/detection_engine/signals/assignees
curl \
 --request POST https://localhost:5601/api/detection_engine/signals/assignees \
 --header "Content-Type: application/json" \
 --data '{"ids":["681c2a707335aa7df5f349b70013d87254746191712ecf0ced9b3e2d538503a6"],"assignees":{"add":["u_MxY0jbrft7EcfC6iNZSUGeI_n6iYrSwZj5mWF5EqmSU_0"],"remove":[]}}'
Request examples
{
  "ids": [
    "681c2a707335aa7df5f349b70013d87254746191712ecf0ced9b3e2d538503a6"
  ],
  "assignees": {
    "add": [
      "u_MxY0jbrft7EcfC6iNZSUGeI_n6iYrSwZj5mWF5EqmSU_0"
    ],
    "remove": []
  }
}
{
  "ids": [
    "681c2a707335aa7df5f349b70013d87254746191712ecf0ced9b3e2d538503a6"
  ],
  "assignees": {
    "add": [],
    "remove": [
      "u_MxY0jbrft7EcfC6iNZSUGeI_n6iYrSwZj5mWF5EqmSU_0"
    ]
  }
}
Response examples (200)
{
  "took": "76,",
  "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
}




















Set a detection alert status

POST /api/detection_engine/signals/status

Set the status of one or more detection alerts.

application/json

Body object Required

An object containing desired status and explicit alert ids or a query to select alerts

One of:
  • signal_ids array[string(nonempty)] Required

    List of alert ids.

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

  • status string Required

    The status of an alert, which can be open, acknowledged, in-progress, or closed.

    Values are open, closed, acknowledged, or in-progress.

Responses

POST /api/detection_engine/signals/status
curl \
 --request POST https://localhost:5601/api/detection_engine/signals/status \
 --header "Content-Type: application/json" \
 --data '{"status":"closed","signal_ids":["80e1383f856e67c1b7f7a1634744fa6d66b6e2ef7aa26d226e57afb5a7b2b4a1"]}'
Request examples
{
  "status": "closed",
  "signal_ids": [
    "80e1383f856e67c1b7f7a1634744fa6d66b6e2ef7aa26d226e57afb5a7b2b4a1"
  ]
}
{
  "query": {
    "bool": {
      "must": [],
      "filter": [
        {
          "range": null,
          "@timestamp": {
            "gte": "2024-10-23T07:00:00.000Z",
            "lte": "2025-01-21T20:12:11.704Z",
            "format": "strict_date_optional_time"
          }
        },
        {
          "bool": {
            "filter": {
              "bool": {
                "must": [],
                "filter": [
                  {
                    "match_phrase": {
                      "kibana.alert.workflow_status": "open"
                    }
                  },
                  {
                    "range": null,
                    "@timestamp": {
                      "gte": "2024-10-23T07:00:00.000Z",
                      "lte": "2025-01-21T20:12:11.704Z",
                      "format": "strict_date_optional_time"
                    }
                  }
                ],
                "should": [],
                "must_not": [
                  {
                    "exists": {
                      "field": "kibana.alert.building_block_type"
                    }
                  }
                ]
              }
            }
          }
        }
      ],
      "should": [],
      "must_not": []
    }
  },
  "status": "closed",
  "conflicts": "proceed"
}
Response examples (200)
{
  "took": 81,
  "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
}
{
  "took": 100,
  "noops": 0,
  "total": 17,
  "batches": 1,
  "deleted": 0,
  "retries": {
    "bulk": 0,
    "search": 0
  },
  "updated": 17,
  "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
}






















































































Suspend a process

POST /api/endpoint/action/suspend_process

Suspend a running process on an endpoint.

application/json

Body Required

Responses

  • 200 application/json

    OK

    Additional properties are allowed.

POST /api/endpoint/action/suspend_process
curl \
 --request POST https://localhost:5601/api/endpoint/action/suspend_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)
{}




















Get a protection updates note

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://localhost:5601/api/endpoint/protection_updates_note/{package_policy_id}
Response examples (200)
{
  "note": "string"
}


























































































Create an exception list

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://localhost:5601/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
}

Delete an exception list

DELETE /api/exception_lists

Delete an exception list using the id or list_id field.

Query parameters

  • id string(nonempty)

    Exception list's identifier. Either id or list_id must be specified.

    Minimum length is 1.

  • list_id string(nonempty)

    Human readable exception list string identifier, e.g. trusted-linux-processes. Either id or list_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.

    • created_at string(date-time) Required

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

    • description string Required

      Describes the exception list.

    • id string(nonempty) Required

      Exception list's identifier.

      Minimum length is 1.

    • immutable boolean Required
    • list_id string(nonempty) Required

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

      Minimum length is 1.

    • meta object

      Placeholder for metadata about the list container.

      Additional properties are allowed.

    • name string Required

      The name of the exception list.

    • namespace_type string Required

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

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

      Values are agnostic or single. Default value is single.

    • os_types array[string]

      Use this field to specify the operating system.

      Values are linux, macos, or windows.

    • tags array[string]

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

    • tie_breaker_id string Required

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

    • type string Required

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

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

    • updated_at string(date-time) Required

      Autogenerated date of last object update.

    • updated_by string Required

      Autogenerated value - user that last updated object.

    • version integer Required

      The document version, automatically increasd on updates.

      Minimum value is 1.

  • 400 application/json

    Invalid input data response

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

    Unsuccessful authentication response

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

    Not enough privileges response

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

    Exception list not found response

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

    Internal server error response

    Hide response attributes Show response attributes object
DELETE /api/exception_lists
curl \
 --request DELETE https://localhost:5601/api/exception_lists
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 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?list_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 list_id: \"foo\" does not exist",
  "status_code": 404
}
Response examples (500)
{
  "message": "Internal Server Error",
  "status_code": 500
}




Export an exception list

POST /api/exception_lists/_export

Export an exception list and its associated items to an NDJSON file.

Query parameters

  • id string(nonempty) Required

    Exception list's identifier.

    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.

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

  • Determines whether to include expired exceptions in the exported list. Expiration date defined by expire_time.

    Values are true or false. Default value is true.

Responses

POST /api/exception_lists/_export
curl \
 --request POST https://localhost:5601/api/exception_lists/_export?id=9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85&list_id=simple_list&namespace_type=agnostic&include_expired_exceptions=true
Response examples (200)
{"_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"}
{"exported_exception_list_count":1,"exported_exception_list_item_count":1,"missing_exception_list_item_count":0,"missing_exception_list_items":[],"missing_exception_lists":[],"missing_exception_lists_count":0}
Response examples (400)
{
  "error": "Bad Request",
  "message": "[request query]: list_id: Required, namespace_type: 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 [POST /api/exception_lists/_export] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}
Response examples (404)
{
  "message\"": "exception list id: \"foo\" does not exist",
  "status_code\"": 404
}
Response examples (500)
{
  "message": "Internal Server Error",
  "status_code": 500
}













































Create a value list

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://localhost:5601/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 value list data streams

DELETE /api/lists/index

Delete the .lists and .items data streams.

Responses

DELETE /api/lists/index
curl \
 --request DELETE https://localhost:5601/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
}

Get a value list item

GET /api/lists/items

Get the details of a value list item.

Query parameters

  • id string(nonempty)

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

    Minimum length is 1.

  • list_id string(nonempty)

    Value list item list's id identfier. Required if id is not specified.

    Minimum length is 1.

  • value string

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

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
GET /api/lists/items
curl \
 --request GET https://localhost:5601/api/lists/items
Response examples (200)
{
  "id": "qN1XRJQBs4HAK3VQs3Gc",
  "type": "ip",
  "value": "127.0.0.2",
  "list_id": "ip_list",
  "_version": "WzExLDFd",
  "@timestamp": "2025-01-08T05:16:25.882Z",
  "created_at": "2025-01-08T05:16:25.882Z",
  "created_by": "elastic",
  "updated_at": "2025-01-08T05:16:25.882Z",
  "updated_by": "elastic",
  "tie_breaker_id": "a9a34c02-a385-436e-86a0-02a3942f3537"
}
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 [GET /api/lists/items?id=qN1XRJQBs4HAK3VQs3Gc] is unauthorized for user, this action is granted by the Kibana privileges [lists-read]",
  "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
}
































Security Osquery

Run live queries, manage packs and saved queries.