Create or update agent configuration

PUT /api/apm/settings/agent-configuration
Api key auth

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

Query parameters

  • overwrite boolean

    If the config exists ?overwrite=true is required

application/json

Body Required

  • agent_name string

    The agent name is used by the UI to determine which settings to display.

  • service object Required

    Service

    Hide service attributes Show service attributes object
  • settings object Required

    Agent configuration settings

    Hide settings attribute Show settings attribute object
    • * string Additional properties

Responses

  • 200 application/json

    Successful response

    Additional properties are NOT allowed.
  • 400 application/json

    Bad Request response

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

    Unauthorized response

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

    Forbidden response

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

    Not found response

    Hide response attributes Show response attributes object
PUT /api/apm/settings/agent-configuration 
curl \
 --request PUT 'http://localhost:5622/api/apm/settings/agent-configuration' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "elastic-api-version: 2023-10-31" \
 --header "kbn-xsrf: true" \
 --data '"{\n    \"service\": {\n        \"name\": \"frontend\",\n        \"environment\": \"production\"\n    },\n    \"settings\": {\n        \"transaction_sample_rate\": \"0.4\",\n        \"capture_body\": \"off\",\n        \"transaction_max_spans\": \"500\"\n    },\n    \"agent_name\": \"nodejs\"\n}\n"'
Request example
Run `PUT /api/apm/settings/agent-configuration` to create or update configuration details. 
{
    "service": {
        "name": "frontend",
        "environment": "production"
    },
    "settings": {
        "transaction_sample_rate": "0.4",
        "capture_body": "off",
        "transaction_max_spans": "500"
    },
    "agent_name": "nodejs"
}
Response examples (200) 
{}
Response examples (400) 
{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 400
}
Response examples (401) 
{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}
Response examples (403) 
{
  "error": "Forbidden",
  "message": "string",
  "statusCode": 403
}
Response examples (404) 
{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 404
}

Search for annotations

GET /api/apm/services/{serviceName}/annotation/search
Api key auth

Search for annotations related to a specific service.

Headers

  • elastic-api-version string Required

    The version of the API to use

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

Path parameters

Query parameters

  • environment string

    The environment to filter annotations by

  • start string

    The start date for the search

  • end string

    The end date for the search

Responses

  • 200 application/json

    Successful response

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

    Bad Request response

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

    Unauthorized response

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

    Internal Server Error response

    Hide response attributes Show response attributes object
GET /api/apm/services/{serviceName}/annotation/search 
curl \
 --request GET 'http://localhost:5622/api/apm/services/{serviceName}/annotation/search' \
 --header "Authorization: $API_KEY" \
 --header "elastic-api-version: 2023-10-31"
Response examples (200) 
{
  "annotations": [
    {
      "@timestamp": 42.0,
      "id": "string",
      "text": "string",
      "type": "version"
    }
  ]
}
Response examples (400) 
{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 400
}
Response examples (401) 
{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}
Response examples (500) 
{
  "error": "Internal Server Error",
  "message": "string",
  "statusCode": 500
}

Get connector types

GET /api/actions/connector_types
Api key auth

You do not need any Kibana feature privileges to run this API.

Query parameters

  • feature_id string

    A filter to limit the retrieved connector types to those that support a specific feature (such as alerting or cases).

Responses

  • 200 application/json

    Indicates a successful call.

GET /api/actions/connector_types 
curl \
 --request GET 'http://localhost:5622/api/actions/connector_types' \
 --header "Authorization: $API_KEY"
Response examples (200) 
[
  {
    "id": ".gen-ai",
    "name": "OpenAI",
    "enabled": true,
    "enabled_in_config": true,
    "enabled_in_license": true,
    "is_system_action_type": false,
    "supported_feature_ids": [
      "generativeAIForSecurity",
      "generativeAIForObservability",
      "generativeAIForSearchPlayground"
    ],
    "minimum_license_required": "enterprise"
  },
  {
    "id": ".bedrock",
    "name": "AWS Bedrock",
    "enabled": true,
    "enabled_in_config": true,
    "enabled_in_license": true,
    "is_system_action_type": false,
    "supported_feature_ids": [
      "generativeAIForSecurity",
      "generativeAIForObservability",
      "generativeAIForSearchPlayground"
    ],
    "minimum_license_required": "enterprise"
  },
  {
    "id": ".gemini",
    "name": "Google Gemini",
    "enabled": true,
    "enabled_in_config": true,
    "enabled_in_license": true,
    "is_system_action_type": false,
    "supported_feature_ids": [
      "generativeAIForSecurity"
    ],
    "minimum_license_required": "enterprise"
  }
]

Dashboards

Update an existing dashboard Technical Preview

PUT /api/dashboards/dashboard/{id}
Api key auth

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    A unique identifier for the dashboard.

application/json

Body

  • attributes object Required

    Additional properties are NOT allowed.

    Hide attributes attributes Show attributes attributes object
    • controlGroupInput object

      Additional properties are NOT allowed.

      Hide controlGroupInput attributes Show controlGroupInput attributes object
      • autoApplySelections boolean

        Show apply selections button in controls.

        Default value is true.

      • chainingSystem string

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

        Values are NONE or HIERARCHICAL. Default value is HIERARCHICAL.

      • controls array[object]

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

        Default value is [] (empty).

        Hide controls attributes Show controls attributes object
        • controlConfig object

          Additional properties are allowed.

        • grow boolean

          Expand width of the control panel to fit available space.

          Default value is false.

        • id string

          The unique ID of the control.

        • order number Required

          The order of the control panel in the control group.

        • type string Required

          The type of the control panel.

        • width string

          Minimum width of the control panel in the control group.

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

      • enhancements object

        Additional properties are allowed.

      • ignoreParentSettings object Required

        Additional properties are NOT allowed.

        Hide ignoreParentSettings attributes Show ignoreParentSettings attributes object
        • ignoreFilters boolean

          Ignore global filters in controls.

          Default value is false.

        • ignoreQuery boolean

          Ignore the global query bar in controls.

          Default value is false.

        • ignoreTimerange boolean

          Ignore the global time range in controls.

          Default value is false.

        • ignoreValidations boolean

          Ignore validations in controls.

          Default value is false.

      • labelPosition string

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

        Values are oneLine or twoLine. Default value is oneLine.

    • description string

      A short description.

      Default value is empty.

    • kibanaSavedObjectMeta object

      A container for various metadata

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

      Hide kibanaSavedObjectMeta attribute Show kibanaSavedObjectMeta attribute object
      • searchSource object

        Additional properties are allowed.

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

          A filter for the search source.

          Hide filter attributes Show filter attributes object
          • $state object

            Additional properties are NOT allowed.

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

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

              Values are appState or globalState.

          • meta object Required

            Additional properties are allowed.

            Hide meta attributes Show meta attributes object
          • query object

            Additional properties are allowed.

        • query object

          Additional properties are NOT allowed.

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

      Additional properties are NOT allowed.

      Hide options attributes Show options attributes object
      • hidePanelTitles boolean

        Hide the panel titles in the dashboard.

        Default value is false.

      • syncColors boolean

        Synchronize colors between related panels in the dashboard.

        Default value is true.

      • syncCursor boolean

        Synchronize cursor position between related panels in the dashboard.

        Default value is true.

      • syncTooltips boolean

        Synchronize tooltips between related panels in the dashboard.

        Default value is true.

      • useMargins boolean

        Show margins between panels in the dashboard layout.

        Default value is true.

    • panels array[object]

      Default value is [] (empty).

      Hide panels attributes Show panels attributes object
      • gridData object Required

        Additional properties are NOT allowed.

        Hide gridData attributes Show gridData attributes object
        • h number

          The height of the panel in grid units

          Minimum value is 1. Default value is 15.

        • i string

          The unique identifier of the panel

        • w number

          The width of the panel in grid units

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

        • x number Required

          The x coordinate of the panel in grid units

        • y number Required

          The y coordinate of the panel in grid units

      • id string

        The saved object id for by reference panels

      • panelConfig object Required

        Additional properties are allowed.

        Hide panelConfig attributes Show panelConfig attributes object
      • panelIndex string

        The unique ID of the panel.

      • panelRefName string
      • title string

        The title of the panel

      • type string Required

        The embeddable type

      • version string Deprecated

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

    • refreshInterval object

      A container for various refresh interval settings

      Additional properties are NOT allowed.

      Hide refreshInterval attributes Show refreshInterval attributes object
      • display string Deprecated

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

      • pause boolean Required

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

      • section number Deprecated

        No longer used.

      • value number Required

        A numeric value indicating refresh frequency in milliseconds.

    • tags array[string]

      An array of tags applied to this dashboard

    • timeFrom string

      An ISO string indicating when to restore time from

    • timeRestore boolean

      Whether to restore time upon viewing this dashboard

      Default value is false.

    • timeTo string

      An ISO string indicating when to restore time from

    • title string Required

      A human-readable title for the dashboard

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

Responses

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

      Additional properties are allowed.

      Hide item attributes Show item attributes object
      • attributes object Required

        Additional properties are NOT allowed.

        Hide attributes attributes Show attributes attributes object
        • controlGroupInput object

          Additional properties are NOT allowed.

          Hide controlGroupInput attributes Show controlGroupInput attributes object
          • autoApplySelections boolean

            Show apply selections button in controls.

            Default value is true.

          • chainingSystem string

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

            Values are NONE or HIERARCHICAL. Default value is HIERARCHICAL.

          • controls array[object]

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

            Default value is [] (empty).

            Hide controls attributes Show controls attributes object
            • controlConfig object

              Additional properties are allowed.

            • grow boolean

              Expand width of the control panel to fit available space.

              Default value is false.

            • id string

              The unique ID of the control.

            • order number Required

              The order of the control panel in the control group.

            • type string Required

              The type of the control panel.

            • width string

              Minimum width of the control panel in the control group.

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

          • enhancements object

            Additional properties are allowed.

          • ignoreParentSettings object Required

            Additional properties are NOT allowed.

            Hide ignoreParentSettings attributes Show ignoreParentSettings attributes object
            • ignoreFilters boolean

              Ignore global filters in controls.

              Default value is false.

            • ignoreQuery boolean

              Ignore the global query bar in controls.

              Default value is false.

            • ignoreTimerange boolean

              Ignore the global time range in controls.

              Default value is false.

            • ignoreValidations boolean

              Ignore validations in controls.

              Default value is false.

          • labelPosition string

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

            Values are oneLine or twoLine. Default value is oneLine.

        • description string

          A short description.

          Default value is empty.

        • kibanaSavedObjectMeta object

          A container for various metadata

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

          Hide kibanaSavedObjectMeta attribute Show kibanaSavedObjectMeta attribute object
          • searchSource object

            Additional properties are allowed.

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

              A filter for the search source.

              Hide filter attributes Show filter attributes object
              • $state object

                Additional properties are NOT allowed.

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

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

                  Values are appState or globalState.

              • meta object Required

                Additional properties are allowed.

                Hide meta attributes Show meta attributes object
              • query object

                Additional properties are allowed.

            • query object

              Additional properties are NOT allowed.

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

          Additional properties are NOT allowed.

          Hide options attributes Show options attributes object
          • hidePanelTitles boolean

            Hide the panel titles in the dashboard.

            Default value is false.

          • syncColors boolean

            Synchronize colors between related panels in the dashboard.

            Default value is true.

          • syncCursor boolean

            Synchronize cursor position between related panels in the dashboard.

            Default value is true.

          • syncTooltips boolean

            Synchronize tooltips between related panels in the dashboard.

            Default value is true.

          • useMargins boolean

            Show margins between panels in the dashboard layout.

            Default value is true.

        • panels array[object]

          Default value is [] (empty).

          Hide panels attributes Show panels attributes object
          • gridData object Required

            Additional properties are NOT allowed.

            Hide gridData attributes Show gridData attributes object
            • h number

              The height of the panel in grid units

              Minimum value is 1. Default value is 15.

            • i string Required
            • w number

              The width of the panel in grid units

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

            • x number Required

              The x coordinate of the panel in grid units

            • y number Required

              The y coordinate of the panel in grid units

          • id string

            The saved object id for by reference panels

          • panelConfig object Required

            Additional properties are allowed.

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

            The title of the panel

          • type string Required

            The embeddable type

          • version string Deprecated

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

        • refreshInterval object

          A container for various refresh interval settings

          Additional properties are NOT allowed.

          Hide refreshInterval attributes Show refreshInterval attributes object
          • display string Deprecated

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

          • pause boolean Required

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

          • section number Deprecated

            No longer used.

          • value number Required

            A numeric value indicating refresh frequency in milliseconds.

        • tags array[string]

          An array of tags applied to this dashboard

        • timeFrom string

          An ISO string indicating when to restore time from

        • timeRestore boolean

          Whether to restore time upon viewing this dashboard

          Default value is false.

        • timeTo string

          An ISO string indicating when to restore time from

        • title string Required

          A human-readable title for the dashboard

        • version number Deprecated
      • createdAt string
      • createdBy string
      • error object

        Additional properties are NOT allowed.

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

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

Delete a dashboard Technical Preview

DELETE /api/dashboards/dashboard/{id}
Api key auth

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    A unique identifier for the dashboard.

DELETE /api/dashboards/dashboard/{id} 
curl \
 --request DELETE 'http://localhost:5622/api/dashboards/dashboard/{id}' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"

Bulk update agent tags

POST /api/fleet/agents/bulk_update_agent_tags
Api key auth

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

application/json

Body

Responses

POST /api/fleet/agents/bulk_update_agent_tags 
curl \
 --request POST 'http://localhost:5622/api/fleet/agents/bulk_update_agent_tags' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"agents":["string"],"batchSize":42.0,"includeInactive":false,"tagsToAdd":["string"],"tagsToRemove":["string"]}'
Request examples 
# Headers
kbn-xsrf: true

# Payload
{
  "agents": [
    "string"
  ],
  "batchSize": 42.0,
  "includeInactive": false,
  "tagsToAdd": [
    "string"
  ],
  "tagsToRemove": [
    "string"
  ]
}
Response examples (200) 
{
  "actionId": "string"
}
Response examples (400) 
{
  "error": "string",
  "errorType": "string",
  "message": "string",
  "statusCode": 42.0
}

Elastic Agents

Get agent uploads

GET /api/fleet/agents/{agentId}/uploads
Api key auth

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

Responses

GET /api/fleet/agents/{agentId}/uploads 
curl \
 --request GET 'http://localhost:5622/api/fleet/agents/{agentId}/uploads' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "items": [
    {
      "actionId": "string",
      "createTime": "string",
      "error": "string",
      "filePath": "string",
      "id": "string",
      "name": "string",
      "status": "READY"
    }
  ]
}
Response examples (400) 
{
  "error": "string",
  "errorType": "string",
  "message": "string",
  "statusCode": 42.0
}

Get agent setup info

GET /api/fleet/agents/setup
Api key auth

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

Responses

GET /api/fleet/agents/setup 
curl \
 --request GET 'http://localhost:5622/api/fleet/agents/setup' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "is_secrets_storage_enabled": true,
  "is_space_awareness_enabled": true,
  "isReady": true,
  "missing_optional_features": [
    "encrypted_saved_object_encryption_key_required"
  ],
  "missing_requirements": [
    "security_required"
  ],
  "package_verification_key_id": "string"
}
Response examples (400) 
{
  "error": "string",
  "errorType": "string",
  "message": "string",
  "statusCode": 42.0
}

Authorize transforms

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

Query parameters

application/json

Body

Responses

POST /api/fleet/epm/packages/{pkgName}/{pkgVersion}/transforms/authorize 
curl \
 --request POST 'http://localhost:5622/api/fleet/epm/packages/{pkgName}/{pkgVersion}/transforms/authorize' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"transforms":[{"transformId":"string"}]}'
Request examples 
# Headers
kbn-xsrf: true

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

Generate a Logstash API key

POST /api/fleet/logstash_api_keys
Api key auth

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Responses

POST /api/fleet/logstash_api_keys 
curl \
 --request POST 'http://localhost:5622/api/fleet/logstash_api_keys' \
 --header "Authorization: $API_KEY" \
 --header "kbn-xsrf: true"
Response examples (200) 
{
  "api_key": "string"
}
Response examples (400) 
{
  "error": "string",
  "errorType": "string",
  "message": "string",
  "statusCode": 42.0
}

Upgrade a package policy

POST /api/fleet/package_policies/upgrade
Api key auth

Upgrade a package policy to a newer package version.

[Required authorization] Route required privileges: fleet-agent-policies-all AND integrations-all.

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

application/json

Body

Responses

POST /api/fleet/package_policies/upgrade 
curl \
 --request POST 'http://localhost:5622/api/fleet/package_policies/upgrade' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"packagePolicyIds":["string"]}'
Request examples 
# Headers
kbn-xsrf: true

# Payload
{
  "packagePolicyIds": [
    "string"
  ]
}
Response examples (200) 
[
  {
    "body": {
      "message": "string"
    },
    "id": "string",
    "name": "string",
    "statusCode": 42.0,
    "success": true
  }
]
Response examples (400) 
{
  "error": "string",
  "errorType": "string",
  "message": "string",
  "statusCode": 42.0
}

Get Fleet Server hosts

GET /api/fleet/fleet_server_hosts
Api key auth

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

Responses

GET /api/fleet/fleet_server_hosts 
curl \
 --request GET 'http://localhost:5622/api/fleet/fleet_server_hosts' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "items": [
    {
      "host_urls": [
        "string"
      ],
      "id": "string",
      "is_default": false,
      "is_internal": true,
      "is_preconfigured": false,
      "name": "string",
      "proxy_id": "string",
      "secrets": {
        "ssl": {
          "es_key": {
            "id": "string"
          },
          "key": {
            "id": "string"
          }
        }
      },
      "ssl": {
        "certificate": "string",
        "certificate_authorities": [
          "string"
        ],
        "client_auth": "optional",
        "es_certificate": "string",
        "es_certificate_authorities": [
          "string"
        ],
        "es_key": "string",
        "key": "string"
      }
    }
  ],
  "page": 42.0,
  "perPage": 42.0,
  "total": 42.0
}
Response examples (400) 
{
  "error": "string",
  "errorType": "string",
  "message": "string",
  "statusCode": 42.0
}

Get a conversation

GET /api/security_ai_assistant/current_user/conversations/{id}
Api key auth

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

      LLM API configuration.

      Hide apiConfig attributes Show apiConfig attributes object
    • category string Required

      The conversation category.

      Values are assistant or insights.

    • createdAt string Required

      The time conversation was created.

    • excludeFromLastConversationStorage boolean

      excludeFromLastConversationStorage.

    • id string(nonempty) Required

      A string that does not contain only whitespace characters

      Minimum length is 1.

    • messages array[object]

      The conversation messages.

      AI assistant conversation message.

      Hide messages attributes Show messages attributes object
      • content string Required

        Message content.

      • isError boolean

        Is error message.

      • metadata object

        metadata

        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.

      • traceData object

        trace Data

        Hide traceData attributes Show traceData attributes object
        • traceId string

          Could be any string, not necessarily a UUID

        • transactionId string

          Could be any string, not necessarily a UUID

    • namespace string Required

      Kibana space

    • replacements object

      Replacements object used to anonymize/deanomymize messsages

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

        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.

    • updatedAt string

      The last time conversation was updated.

    • users array[object] Required

      Could be any string, not necessarily a UUID

      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 'http://localhost:5622/api/security_ai_assistant/current_user/conversations/{id}' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "apiConfig": {
    "actionTypeId": "string",
    "connectorId": "string",
    "defaultSystemPromptId": "string",
    "model": "string",
    "provider": "OpenAI"
  },
  "category": "assistant",
  "createdAt": "string",
  "excludeFromLastConversationStorage": true,
  "id": "string",
  "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
}

Get response actions

GET /api/endpoint/action
Api key auth

Get a list of all response actions.

Query parameters

  • page integer

    Page number

    Minimum value is 1. Default value is 1.

  • pageSize integer

    Number of items per page

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

  • commands array[string]

    A list of response action command names.

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

  • agentIds array[string] | string

    A list of agent IDs. Max of 50.

  • userIds array[string] | string

    A list of user IDs.

  • startDate string

    A start date in ISO 8601 format or Date Math format.

  • endDate string

    An end date in ISO format or Date Math format.

  • agentTypes string

    List of agent types to retrieve. Defaults to endpoint.

    Values are endpoint, sentinel_one, crowdstrike, or microsoft_defender_endpoint.

  • withOutputs array[string] | string

    A list of action IDs that should include the complete output of the action.

  • types array[string]

    List of types of response actions

    Values are automated or manual.

Responses

  • 200 application/json

    OK
GET /api/endpoint/action 
curl \
 --request GET 'http://localhost:5622/api/endpoint/action' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "data": [
    {
      "id": "b3d6de74-36b0-4fa8-be46-c375bf1771bf",
      "agents": [
        "afdc366c-e2e0-4cdb-ae1d-94575bd2d8e0"
      ],
      "command": "running-processes",
      "agentType": "endpoint",
      "createdBy": "elastic",
      "isExpired": false,
      "startedAt": "2022-08-08T15:24:57.402Z",
      "completedAt": "2022-08-08T09:50:47.672Z",
      "isCompleted": true,
      "wasSuccessful": true
    },
    {
      "id": "43b4098b-8752-4fbb-a7a7-6df7c74d0ee3",
      "agents": [
        "afdc366c-e2e0-4cdb-ae1d-94575bd2d8e0"
      ],
      "command": "isolate",
      "agentType": "endpoint",
      "createdBy": "elastic",
      "isExpired": false,
      "startedAt": "2022-08-08T15:23:37.359Z",
      "completedAt": "2022-08-08T10:41:57.352Z",
      "isCompleted": true,
      "wasSuccessful": true
    },
    {
      "id": "5bc92c86-b8e6-42dd-837f-12ad29e09caa",
      "agents": [
        "afdc366c-e2e0-4cdb-ae1d-94575bd2d8e0"
      ],
      "command": "kill-process",
      "comment": "bad process - taking up too much cpu",
      "agentType": "endpoint",
      "createdBy": "elastic",
      "isExpired": false,
      "startedAt": "2022-08-08T14:38:44.125Z",
      "completedAt": "2022-08-08T09:44:50.952Z",
      "isCompleted": true,
      "wasSuccessful": true
    },
    {
      "id": "790d54e0-3aa3-4e5b-8255-3ce9d851246a",
      "agents": [
        "afdc366c-e2e0-4cdb-ae1d-94575bd2d8e0"
      ],
      "command": "unisolate",
      "comment": "Not a threat to the network",
      "agentType": "endpoint",
      "createdBy": "elastic",
      "isExpired": false,
      "startedAt": "2022-08-08T14:38:15.391Z",
      "completedAt": "2022-08-08T09:40:47.398Z",
      "isCompleted": true,
      "wasSuccessful": true
    }
  ],
  "page": 1,
  "total": 4,
  "endDate": "now",
  "pageSize": 10,
  "startDate": "now-24h/h",
  "elasticAgentIds": [
    "afdc366c-e2e0-4cdb-ae1d-94575bd2d8e0"
  ]
}

Suspend a process

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

Suspend a running process 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

    One of:
    object-1 object object-2 object
    Hide attribute Show attribute
    • pid integer

      The process ID (PID) of the process to suspend.

      Minimum value is 1.

  • parameters object

    Optional parameters object

Responses

  • 200 application/json

    OK
POST /api/endpoint/action/suspend_process 
curl \
 --request POST 'http://localhost:5622/api/endpoint/action/suspend_process' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"comment":"suspend the process","parameters":{"entity_id":"abc123"},"endpoint_ids":["ed518850-681a-4d60-bb98-e22640cae2a8"]}'
Request example 
{
  "comment": "suspend the process",
  "parameters": {
    "entity_id": "abc123"
  },
  "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": "suspend-process",
    "comment": "suspend the process",
    "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": {
      "entity_id": "abc123"
    },
    "completedAt": "2022-07-29T19:09:44.961Z",
    "isCompleted": true,
    "wasSuccessful": true
  }
}

Health check on Privilege Monitoring

GET /api/entity_analytics/monitoring/privileges/health
Api key auth

Responses

  • 200 application/json

    Successful response

    Hide response attribute Show response attribute object
GET /api/entity_analytics/monitoring/privileges/health 
curl \
 --request GET 'http://localhost:5622/api/entity_analytics/monitoring/privileges/health' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "ok": true
}

Delete the Entity Engine

DELETE /api/entity_store/engines/{entityType}
Api key auth

Path parameters

  • entityType string Required

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

    Values are user, host, service, or generic.

Query parameters

  • data boolean

    Control flag to also delete the entity data.

Responses

  • 200 application/json

    Successful response

    Hide response attribute Show response attribute object
DELETE /api/entity_store/engines/{entityType} 
curl \
 --request DELETE 'http://localhost:5622/api/entity_store/engines/{entityType}' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "deleted": true
}

Delete an exception list

DELETE /api/exception_lists
Api key auth

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.

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

    • 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. 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 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 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 'http://localhost:5622/api/exception_lists' \
 --header "Authorization: $API_KEY"
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
}

Duplicate an exception list

POST /api/exception_lists/_duplicate
Api key auth

Duplicate an existing exception list.

Query parameters

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

  • include_expired_exceptions string Required

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

    Values are true or false. Default value is true.

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. 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 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 not found

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

    Exception list to duplicate not found 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/_duplicate 
curl \
 --request POST 'http://localhost:5622/api/exception_lists/_duplicate?list_id=simple_list&namespace_type=agnostic&include_expired_exceptions=true' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "id": "b2f4a715-6ab1-444c-8b1e-3fa1b1049429",
  "name": "Sample Detection Exception List [Duplicate]",
  "tags": [
    "malware"
  ],
  "type": "detection",
  "list_id": "d6390d60-bce3-4a48-9002-52db600f329c",
  "version": 1,
  "_version": "WzExNDY1LDFd",
  "os_types": [],
  "immutable": false,
  "created_at": "2025-01-09T16:19:50.280Z",
  "created_by": "elastic",
  "updated_at": "2025-01-09T16:19:50.280Z",
  "updated_by": "elastic",
  "description": "This is a sample detection type exception",
  "namespace_type": "single",
  "tie_breaker_id": "6fa670bd-666d-4c9c-9f1e-d1dbc516e985"
}
Response examples (400) 
{
  "error": "Bad Request",
  "message": "[request query]: namespace_type: Invalid enum value. Expected 'agnostic' | 'single', received 'foo'",
  "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/_duplicate] 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 (405) 
{
  "message": "string",
  "status_code": 42
}
Response examples (500) 
{
  "message": "Internal Server Error",
  "status_code": 500
}

Export an exception list

POST /api/exception_lists/_export
Api key auth

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.

  • include_expired_exceptions string Required

    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 'http://localhost:5622/api/exception_lists/_export?id=9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85&list_id=simple_list&namespace_type=agnostic&include_expired_exceptions=true' \
 --header "Authorization: $API_KEY"
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
}

Import value list items

POST /api/lists/items/_import
Api key auth

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

You can import items to a new or existing list.

Query parameters

  • list_id string(nonempty)

    List's id.

    Required when importing to an existing list.

    Minimum length is 1.

  • type string

    Type of the importing list.

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

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

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

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

    Values are true, false, or wait_for.

multipart/form-data

Body Required

  • file string(binary)

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

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • _version string

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

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

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

    • description string(nonempty) Required

      Describes the value list.

      Minimum length is 1.

    • deserializer string

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

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

      Value list's identifier.

      Minimum length is 1.

    • immutable boolean Required
    • meta object

      Placeholder for metadata about the value list.

      Additional properties are allowed.

    • name string(nonempty) Required

      Value list's name.

      Minimum length is 1.

    • serializer string

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

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

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

    • type string Required

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

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

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

    • updated_at string(date-time) Required

      Autogenerated date of last object update.

    • updated_by string Required

      Autogenerated value - user that last updated object.

    • version integer Required

      The document version number.

      Minimum value is 1.
  • 400 application/json

    Invalid input data response

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

    Unsuccessful authentication response

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

    Not enough privileges response

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

    List with specified list_id does not exist response

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

    Internal server error response

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

Security Osquery

Run live queries, manage packs and saved queries.

Spaces

Manage your Kibana spaces.

Get a stream Technical Preview

GET /api/streams/{name}
Api key auth

Fetches a stream definition and associated dashboards

application/json

Body

object object

Additional properties are NOT allowed.
GET /api/streams/{name} 
curl \
 --request GET 'http://localhost:5622/api/streams/{name}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json"
Request examples 
{}

Export stream content

POST /api/streams/{name}/content/export
Api key auth

Exports the content associated to a stream.

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

application/json

Body

POST /api/streams/{name}/content/export 
curl \
 --request POST 'http://localhost:5622/api/streams/{name}/content/export' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"description":"string","include":{"objects":{"dashboards":["string"]}},"name":"string","replaced_patterns":["string"],"version":"string"}'
Request examples 
# Headers
kbn-xsrf: true

# Payload
{
  "description": "string",
  "include": {
    "objects": {
      "dashboards": [
        "string"
      ]
    }
  },
  "name": "string",
  "replaced_patterns": [
    "string"
  ],
  "version": "string"
}

Get stream queries Technical Preview

GET /api/streams/{name}/queries
Api key auth

Fetches all queries linked to a stream that are visible to the current user in the current space.

application/json

Body

object object

Additional properties are NOT allowed.
GET /api/streams/{name}/queries 
curl \
 --request GET 'http://localhost:5622/api/streams/{name}/queries' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json"
Request examples 
{}