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.

Delete a rule

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    The identifier for the rule.

Responses

  • 204

    Indicates a successful call.

  • 400

    Indicates an invalid schema or parameters.

  • 403

    Indicates that this call is forbidden.

  • 404

    Indicates a rule with the given ID does not exist.

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

Get source maps

GET /api/apm/sourcemaps
Api key auth

Get an array of Fleet artifacts, including source map uploads. You must have read or all Kibana privileges for the APM and User Experience feature.

Headers

  • elastic-api-version string Required

    The version of the API to use

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

Query parameters

Responses

GET /api/apm/sourcemaps 
curl -X GET "http://localhost:5601/api/apm/sourcemaps" \
-H 'Content-Type: application/json' \
-H 'kbn-xsrf: true' \
-H 'Authorization: ApiKey ${YOUR_API_KEY}'
Response examples (200)
A successful response from `GET /api/apm/sourcemaps`. 
{
  "artifacts": [
    {
      "type": "sourcemap",
      "identifier": "foo-1.0.0",
      "relative_url": "/api/fleet/artifacts/foo-1.0.0/644fd5a997d1ddd90ee131ba18e2b3d03931d89dd1fe4599143c0b3264b3e456",
      "body": {
        "serviceName": "foo",
        "serviceVersion": "1.0.0",
        "bundleFilepath": "/test/e2e/general-usecase/bundle.js",
        "sourceMap": {
          "version": 3,
          "file": "static/js/main.chunk.js",
          "sources": [
            "fleet-source-map-client/src/index.css",
            "fleet-source-map-client/src/App.js",
            "webpack:///./src/index.css?bb0a",
            "fleet-source-map-client/src/index.js",
            "fleet-source-map-client/src/reportWebVitals.js"
          ],
          "sourcesContent": [
            "content"
          ],
          "mappings": "mapping",
          "sourceRoot": ""
        }
      },
      "created": "2021-07-09T20:47:44.812Z",
      "id": "apm:foo-1.0.0-644fd5a997d1ddd90ee131ba18e2b3d03931d89dd1fe4599143c0b3264b3e456",
      "compressionAlgorithm": "zlib",
      "decodedSha256": "644fd5a997d1ddd90ee131ba18e2b3d03931d89dd1fe4599143c0b3264b3e456",
      "decodedSize": 441,
      "encodedSha256": "024c72749c3e3dd411b103f7040ae62633558608f480bce4b108cf5b2275bd24",
      "encodedSize": 237,
      "encryptionAlgorithm": "none",
      "packageName": "apm"
    }
  ]
}

Create an agent action

POST /api/fleet/agents/{agentId}/actions
Api key auth

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

application/json

Body

  • action object Required

    Any of:
    object-1 object object-2 object
    Hide attribute Show attribute
    • type string Required

      Values are UNENROLL, UPGRADE, or POLICY_REASSIGN.

Responses

POST /api/fleet/agents/{agentId}/actions 
curl \
 --request POST 'https://<KIBANA_URL>/api/fleet/agents/{agentId}/actions' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"action":{"type":"UNENROLL"}}'

Delete an agent binary download source

DELETE /api/fleet/agent_download_sources/{sourceId}
Api key auth

Delete an agent binary download source by ID.

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Responses

DELETE /api/fleet/agent_download_sources/{sourceId} 
curl \
 --request DELETE 'https://<KIBANA_URL>/api/fleet/agent_download_sources/{sourceId}' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Get an agent status summary

GET /api/fleet/agent_status
Api key auth

Query parameters

Responses

GET /api/fleet/agent_status 
curl \
 --request GET 'https://<KIBANA_URL>/api/fleet/agent_status' \
 --header "Authorization: $API_KEY"

Export saved objects

POST /api/saved_objects/_export
Api key auth

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

    A required header to protect against CSRF attacks

application/json

Body

Responses

  • 200 application/x-ndjson

    Indicates a successfull call.

  • 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 "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --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"
}

Security AI assistant

Manage and interact with Security Assistant resources.

Apply a bulk action to anonymization fields

POST /api/security_ai_assistant/anonymization_fields/_bulk_action
Api key auth

Apply a bulk action to multiple anonymization fields. The bulk action is applied to all anonymization fields that match the filter or to the list of anonymization fields by their IDs.

application/json

Body

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

      Array of anonymization fields IDs

      At least 1 element.

    • query string

      Query to filter anonymization fields

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

Responses

POST /api/security_ai_assistant/anonymization_fields/_bulk_action 
curl \
 --request POST 'https://<KIBANA_URL>/api/security_ai_assistant/anonymization_fields/_bulk_action' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"create":[{"allowed":true,"anonymized":true,"field":"string"}],"delete":{"ids":["string"],"query":"string"},"update":[{"allowed":true,"anonymized":true,"id":"string"}]}'

Create an endpoint exception list

POST /api/endpoint_list
Api key auth

Create an endpoint exception list, which groups endpoint exception list items. If an endpoint exception list already exists, an empty response is returned.

Responses

  • 200 application/json

    Successful response

    One of:
    Security_Endpoint_Exceptions_API_ExceptionList object object-2 object
    Hide attributes Show attributes
    • _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.

    • os_types array[string]

      Use this field to specify the operating system. Only enter one value.

      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

    One of:
    Security_Endpoint_Exceptions_API_PlatformErrorResponse object Security_Endpoint_Exceptions_API_SiemErrorResponse object
    Hide attributes Show attributes
  • 401 application/json

    Unsuccessful authentication

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

    Insufficient privileges

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

    Internal server error

    Hide response attributes Show response attributes object
POST /api/endpoint_list 
curl \
 --request POST 'https://<KIBANA_URL>/api/endpoint_list' \
 --header "Authorization: $API_KEY"

Run a command

POST /api/endpoint/action/execute
Api key auth

Run a shell command on an endpoint.

application/json

Body Required

  • agent_type string

    List of agent types to retrieve. Defaults to endpoint.

    Values are endpoint, sentinel_one, crowdstrike, or microsoft_defender_endpoint.

  • alert_ids array[string(nonempty)]

    A list of alerts ids.

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

  • case_ids array[string]

    Case IDs to be updated (cannot contain empty strings)

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

  • comment string

    Optional comment

  • endpoint_ids array[string] Required

    List of endpoint IDs (cannot contain empty strings)

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

  • parameters object Required

    Optional parameters object

    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
POST /api/endpoint/action/execute 
curl \
 --request POST 'https://<KIBANA_URL>/api/endpoint/action/execute' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"comment":"Get list of all files","parameters":{"command":"ls -al","timeout":600},"endpoint_ids":["b3d6de74-36b0-4fa8-be46-c375bf1771bf"]}'
Request example 
{
  "comment": "Get list of all files",
  "parameters": {
    "command": "ls -al",
    "timeout": 600
  },
  "endpoint_ids": [
    "b3d6de74-36b0-4fa8-be46-c375bf1771bf"
  ]
}
Response examples (200) 
{
  "data": {
    "id": "9f934028-2300-4927-b531-b26376793dc4",
    "hosts": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "name": "gke-endpoint-gke-clu-endpoint-node-po-e1a3ab89-4c4r"
      }
    },
    "agents": [
      "ed518850-681a-4d60-bb98-e22640cae2a8"
    ],
    "status": "pending",
    "command": "execute",
    "comment": "Get list of all files",
    "outputs": {},
    "agentType": "endpoint",
    "createdBy": "myuser",
    "isExpired": false,
    "startedAt": "2023-07-28T18:43:27.362Z",
    "agentState": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "isCompleted": false,
        "wasSuccessful": false
      }
    },
    "parameters": {
      "command": "ls -al",
      "timeout": 600
    },
    "isCompleted": false,
    "wasSuccessful": false
  }
}

Get running processes

POST /api/endpoint/action/running_procs
Api key auth

Get a list of all processes running on an endpoint.

application/json

Body Required

  • agent_type string

    List of agent types to retrieve. Defaults to endpoint.

    Values are endpoint, sentinel_one, crowdstrike, or microsoft_defender_endpoint.

  • alert_ids array[string(nonempty)]

    A list of alerts ids.

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

  • case_ids array[string]

    Case IDs to be updated (cannot contain empty strings)

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

  • comment string

    Optional comment

  • endpoint_ids array[string] Required

    List of endpoint IDs (cannot contain empty strings)

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

  • parameters object

    Optional parameters object

Responses

  • 200 application/json

    OK
POST /api/endpoint/action/running_procs 
curl \
 --request POST 'https://<KIBANA_URL>/api/endpoint/action/running_procs' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"endpoint_ids":["ed518850-681a-4d60-bb98-e22640cae2a8"]}'
Request example 
{
  "endpoint_ids": [
    "ed518850-681a-4d60-bb98-e22640cae2a8"
  ]
}
Response examples (200) 
{
  "data": {
    "id": "233db9ea-6733-4849-9226-5a7039c7161d",
    "agents": [
      "ed518850-681a-4d60-bb98-e22640cae2a8"
    ],
    "errors": [],
    "command": "running-processes",
    "comment": "",
    "outputs": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "type": "json",
        "content": {
          "key": "value"
        }
      }
    },
    "agentType": "endpoint",
    "createdBy": "myuser",
    "isExpired": false,
    "startedAt": "2022-07-29T19:08:49.126Z",
    "parameters": {},
    "completedAt": "2022-07-29T19:09:44.961Z",
    "isCompleted": true,
    "wasSuccessful": true
  }
}

Create rule exception items

POST /api/detection_engine/rules/{id}/exceptions
Api key auth

Create exception items that apply to a single detection rule.

Path parameters

  • id string(uuid) Required

    Detection rule's identifier

application/json

Body Required

Rule exception items.

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

      Default value is [] (empty).

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

        A string that does not contain only whitespace characters

        Minimum length is 1.

    • description string Required

      Describes the exception list.

    • entries array[object] Required
      Any of:
      Security_Exceptions_API_ExceptionListItemEntryMatch object Security_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Exceptions_API_ExceptionListItemEntryList object Security_Exceptions_API_ExceptionListItemEntryExists object Security_Exceptions_API_ExceptionListItemEntryNested object Security_Exceptions_API_ExceptionListItemEntryMatchWildcard object
      Hide attributes Show attributes
      • field string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • operator string Required

        Values are excluded or included.

      • type string Required Discriminator

        Value is match.

      • value string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

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

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

      Minimum length is 1.

    • meta object

      Additional properties are allowed.

    • name string(nonempty) Required

      Exception list name.

      Minimum length is 1.

    • namespace_type string

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

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

      Values are agnostic or single. Default value is single.

    • os_types array[string]

      Use this field to specify the operating system.

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

    • tags array[string(nonempty)]

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

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

    • type string Required

      Value is simple.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • _version string

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

    • comments array[object] Required

      Array of comment fields:

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

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • created_at string(date-time) Required

        Autogenerated date of object creation.

      • created_by string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • id string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • updated_at string(date-time)

        Autogenerated date of last object update.

      • updated_by string(nonempty)

        A string that does not contain only whitespace characters

        Minimum length is 1.

    • created_at string(date-time) Required

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

    • description string Required

      Describes the exception list.

    • entries array[object] Required
      Any of:
      Security_Exceptions_API_ExceptionListItemEntryMatch object Security_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Exceptions_API_ExceptionListItemEntryList object Security_Exceptions_API_ExceptionListItemEntryExists object Security_Exceptions_API_ExceptionListItemEntryNested object Security_Exceptions_API_ExceptionListItemEntryMatchWildcard object
      Hide attributes Show attributes
      • field string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • operator string Required

        Values are excluded or included.

      • type string Required Discriminator

        Value is match.

      • value string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

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

    Unsuccessful authentication response

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

    Not enough privileges response

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

    Internal server error response

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

Delete an exception list item

DELETE /api/exception_lists/items
Api key auth

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.

  • namespace_type string

    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:
      Security_Exceptions_API_ExceptionListItemEntryMatch object Security_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Exceptions_API_ExceptionListItemEntryList object Security_Exceptions_API_ExceptionListItemEntryExists object Security_Exceptions_API_ExceptionListItemEntryNested object Security_Exceptions_API_ExceptionListItemEntryMatchWildcard object
      Hide attributes Show attributes
      • field string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • operator string Required

        Values are excluded or included.

      • type string Required Discriminator

        Value is match.

      • value string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

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

    Unsuccessful authentication response

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

    Not enough privileges response

    Hide response attributes Show response attributes object
  • 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' \
 --header "Authorization: $API_KEY"
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
}

Update a value list

PUT /api/lists
Api key auth

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.

    • deserializer string

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

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

      Value list's identifier.

      Minimum length is 1.

    • immutable boolean Required
    • meta object

      Placeholder for metadata about the value list.

      Additional properties are allowed.

    • name string(nonempty) Required

      Value list's name.

      Minimum length is 1.

    • serializer string

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

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

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

    • type string Required

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

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

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

    • updated_at string(date-time) Required

      Autogenerated date of last object update.

    • updated_by string Required

      Autogenerated value - user that last updated object.

    • version integer Required

      The document version number.

      Minimum value is 1.
  • 400 application/json

    Invalid input data response

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

    Unsuccessful authentication response

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

    Not enough privileges response

    Hide response attributes Show response attributes object
  • 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 "Authorization: $API_KEY" \
 --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 saved query

POST /api/osquery/saved_queries
Api key auth

Create and run a saved query.

application/json

Body Required

  • description string | null

    The saved query description.

  • ecs_mapping object | null

    Map osquery results columns or static values to Elastic Common Schema (ECS) fields

    Hide ecs_mapping attribute Show ecs_mapping attribute object | null
  • id string | null

    The ID of a saved query.

  • interval string

    An interval, in seconds, on which to run the query.

  • platform string | null

    Restricts the query to a specified platform. The default is all platforms. To specify multiple platforms, use commas. For example, linux,darwin.

  • query string

    The SQL query you want to run.

  • removed boolean | null

    Indicates whether the query is removed.

  • snapshot boolean | null

    Indicates whether the query is a snapshot.

  • version string | null

    Uses the Osquery versions greater than or equal to the specified version string.

Responses

  • 200 application/json

    OK
POST /api/osquery/saved_queries 
curl \
 --request POST 'https://<KIBANA_URL>/api/osquery/saved_queries' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"id":"saved_query_id","query":"select * from uptime;","timeout":120,"version":"2.8.0","interval":"60","platform":"linux,darwin","description":"Saved query description","ecs_mapping":{"host.uptime":{"field":"total_seconds"}}}'
Request example 
{
  "id": "saved_query_id",
  "query": "select * from uptime;",
  "timeout": 120,
  "version": "2.8.0",
  "interval": "60",
  "platform": "linux,darwin",
  "description": "Saved query description",
  "ecs_mapping": {
    "host.uptime": {
      "field": "total_seconds"
    }
  }
}
Response examples (200) 
{
  "data": {}
}