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"
    }
  ]
}
Response examples (400) 
{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 400
}
Response examples (401) 
{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}
Response examples (500) 
{
  "error": "Internal Server Error",
  "message": "string",
  "statusCode": 500
}
Response examples (501) 
{
  "error": "Not Implemented",
  "message": "Not Implemented",
  "statusCode": 501
}

Run a connector

POST /api/actions/connector/{id}/_execute
Api key auth

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    An identifier for the connector.

application/json

Body

  • params object Required

    One of:
    run_acknowledge_resolve_pagerduty object run_documents object run_message_email object run_message_serverlog object run_message_slack object run_trigger_pagerduty object run_addevent object run_closealert object run_closeincident object run_createalert object run_fieldsbyissuetype object run_getchoices object run_getfields object run_getincident object run_issue object run_issues object run_issuetypes object run_postmessage object run_pushtoservice object run_validchannelid object

    Test an action that acknowledges or resolves a PagerDuty alert.

    Hide attributes Show attributes
    • dedupKey string Required

      The deduplication key for the PagerDuty alert.

      Maximum length is 255.

    • eventAction string Required

      The type of event.

      Values are acknowledge or resolve.

Responses

  • 200 application/json

    Indicates a successful call.

    Hide response attributes Show response attributes object
    • config object

      Additional properties are allowed.

    • connector_type_id string Required

      The connector type identifier.

    • id string Required

      The identifier for the connector.

    • is_deprecated boolean Required

      Indicates whether the connector is deprecated.

    • is_missing_secrets boolean

      Indicates whether the connector is missing secrets.

    • is_preconfigured boolean Required

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

    • is_system_action boolean Required

      Indicates whether the connector is used for system actions.

    • name string Required

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

Get data streams

GET /api/fleet/data_streams
Api key auth

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

Responses

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

Data views

Data view APIs enable you to manage data views, formerly known as Kibana index patterns.

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
}

Install a package by upload

POST /api/fleet/epm/packages
Api key auth

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Query parameters

application/gzip; application/zip

Body

string(binary) string(binary)

Responses

POST /api/fleet/epm/packages 
curl \
 --request POST 'http://localhost:5622/api/fleet/epm/packages' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/gzip; application/zip" \
 --header "kbn-xsrf: true" \
 --data-binary '@file'

Install a package from the registry

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

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

Query parameters

application/json

Body

Responses

POST /api/fleet/epm/packages/{pkgName}/{pkgVersion} 
curl \
 --request POST 'http://localhost:5622/api/fleet/epm/packages/{pkgName}/{pkgVersion}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"force":false,"ignore_constraints":false}'
Request examples 
# Headers
kbn-xsrf: true

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

Get a package policy

GET /api/fleet/package_policies/{packagePolicyId}
Api key auth

Get a package policy by ID.

Query parameters

  • format string

    Values are simplified or legacy.

Responses

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

      Additional properties are NOT allowed.

      Hide item attributes Show item attributes object
      • additional_datastreams_permissions array[string] | null

        Additional datastream permissions, that will be added to the agent policy.

      • agents number
      • created_at string Required
      • created_by string Required
      • description string

        Package policy description

      • elasticsearch object

        Additional properties are allowed.

        Hide elasticsearch attribute Show elasticsearch attribute object
        • privileges object

          Additional properties are allowed.

          Hide privileges attribute Show privileges attribute object
      • enabled boolean Required
      • id string Required

      • inputs array[object] | object Required

        Any of:
        array-1 array[object] object-2 object
        Hide attributes Show attributes object
        • config object

          Package variable (see integration documentation for more information)

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

            Additional properties are NOT allowed.

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

            Package variable (see integration documentation for more information)

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

              Additional properties are NOT allowed.

              Hide * attributes Show * attributes object
          • data_stream object Required

            Additional properties are NOT allowed.

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

            Values are ga, beta, or experimental.

          • vars object

            Package variable (see integration documentation for more information)

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

              Additional properties are NOT allowed.

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

          Package variable (see integration documentation for more information)

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

            Additional properties are NOT allowed.

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

        Package policy name (should be unique)

      • namespace string

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

      • output_id string | null
      • overrides object | null

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

        Additional properties are NOT allowed.

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

          Additional properties are allowed.

      • package object

        Additional properties are NOT allowed.

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

        Agent policy ID where that package policy will be added

      • policy_ids array[string]

        Agent policy IDs where that package policy will be added

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

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

        Default value is false.

      • updated_at string Required
      • updated_by string Required

      • vars object

        Any of:
        object-1 object object-2 object

        Package variable (see integration documentation for more information)

        Hide attribute Show attribute
        • * object Additional properties

          Additional properties are NOT allowed.

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

Roles

Manage the roles that grant Elasticsearch and Kibana privileges.

Kibana role management

Create or update a role

PUT /api/security/role/{name}
Api key auth

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • name string Required

    The role name.

    Minimum length is 1, maximum length is 1024.

Query parameters

  • createOnly boolean

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

    Default value is false.

application/json

Body

  • description string

    A description for the role.

    Maximum length is 2048.

  • elasticsearch object Required

    Additional properties are NOT allowed.

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

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

    • indices array[object]
      Hide indices attributes Show indices attributes object
      • allow_restricted_indices boolean

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

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

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

      • names array[string] Required

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

        At least 1 element.

      • privileges array[string] Required

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

        At least 1 element.

      • query string

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

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

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

        At least 1 element.

      • privileges array[string] Required

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

        At least 1 element.

    • remote_indices array[object]
      Hide remote_indices attributes Show remote_indices attributes object
      • allow_restricted_indices boolean

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

      • clusters array[string] Required

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

        At least 1 element.

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

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

      • names array[string] Required

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

        At least 1 element.

      • privileges array[string] Required

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

        At least 1 element.

      • query string

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

    • run_as array[string]

      A user name that the role member can impersonate.

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

    Additional properties are allowed.

Responses

  • 204

    Indicates a successful call.

PUT /api/security/role/{name} 
curl \
 --request PUT 'http://localhost:5622/api/security/role/{name}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"description":"string","elasticsearch":{"cluster":["string"],"indices":[{"allow_restricted_indices":true,"field_security":{"additionalProperty1":["string"],"additionalProperty2":["string"]},"names":["string"],"privileges":["string"],"query":"string"}],"remote_cluster":[{"clusters":["string"],"privileges":["string"]}],"remote_indices":[{"allow_restricted_indices":true,"clusters":["string"],"field_security":{"additionalProperty1":["string"],"additionalProperty2":["string"]},"names":["string"],"privileges":["string"],"query":"string"}],"run_as":["string"]},"kibana":[{"base":[],"feature":{"additionalProperty1":["string"],"additionalProperty2":["string"]},"spaces":["*"]}],"metadata":{}}'
Request examples 
# Headers
kbn-xsrf: true

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

Get an endpoint exception list item

GET /api/endpoint_list/items
Api key auth

Get the details of an endpoint exception list item using the id or item_id field.

Query parameters

  • id string(nonempty)

    Either id or item_id must be specified

    Minimum length is 1.

  • item_id string(nonempty)

    Either id or item_id must be specified

    Minimum length is 1.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • _version string

      The version id, normally returned by the API when the 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_Endpoint_Exceptions_API_ExceptionListItemEntryMatch object Security_Endpoint_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Endpoint_Exceptions_API_ExceptionListItemEntryList object Security_Endpoint_Exceptions_API_ExceptionListItemEntryExists object Security_Endpoint_Exceptions_API_ExceptionListItemEntryNested object Security_Endpoint_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.

    • os_types array[string]

      Use this field to specify the operating system.

      Values are linux, macos, or windows.

    • tags array[string(nonempty)]

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

      Minimum length of each is 1.

    • 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

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

    Endpoint list item not found

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

    Internal server error

    Hide response attributes Show response attributes object
GET /api/endpoint_list/items 
curl \
 --request GET 'http://localhost:5622/api/endpoint_list/items' \
 --header "Authorization: $API_KEY"
Response examples (200) 
[
  {
    "_version": "string",
    "comments": [
      {
        "comment": "string",
        "created_at": "2025-05-04T09:42:00Z",
        "created_by": "string",
        "id": "string",
        "updated_at": "2025-05-04T09:42:00Z",
        "updated_by": "string"
      }
    ],
    "created_at": "2025-05-04T09:42:00Z",
    "created_by": "string",
    "description": "string",
    "entries": [
      {
        "field": "string",
        "operator": "excluded",
        "type": "match",
        "value": "string"
      }
    ],
    "expire_time": "2025-05-04T09:42:00Z",
    "id": "71a9f4b2-c85c-49b4-866f-c71eb9e67da2",
    "item_id": "simple_list_item",
    "list_id": "simple_list",
    "meta": {},
    "name": "string",
    "namespace_type": "agnostic",
    "os_types": [
      "linux"
    ],
    "tags": [
      "string"
    ],
    "tie_breaker_id": "string",
    "type": "simple",
    "updated_at": "2025-05-04T09:42:00Z",
    "updated_by": "string"
  }
]
Response examples (400) 
{
  "error": "string",
  "message": "string",
  "statusCode": 42
}
{
  "message": "string",
  "status_code": 42
}
Response examples (401) 
{
  "error": "string",
  "message": "string",
  "statusCode": 42
}
Response examples (403) 
{
  "error": "string",
  "message": "string",
  "statusCode": 42
}
Response examples (404) 
{
  "message": "string",
  "status_code": 42
}
Response examples (500) 
{
  "message": "string",
  "status_code": 42
}

Download a file

GET /api/endpoint/action/{action_id}/file/{file_id}/download
Api key auth

Download a file from an endpoint.

Path parameters

Responses

  • 200 application/json

    OK
GET /api/endpoint/action/{action_id}/file/{file_id}/download 
curl \
 --request GET 'http://localhost:5622/api/endpoint/action/{action_id}/file/{file_id}/download' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{}

Get a metadata list

GET /api/endpoint/metadata
Api key auth

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.

  • kuery string

    A KQL string.

  • hostStatuses array[string] Required

    A set of agent health statuses to filter by.

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

  • sortField string

    Determines which field is used to sort the results.

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

  • sortDirection string

    Determines the sort order.

    Values are asc or desc.

Responses

  • 200 application/json

    OK
GET /api/endpoint/metadata 
curl \
 --request GET 'http://localhost:5622/api/endpoint/metadata?hostStatuses=healthy&hostStatuses=updating' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "data": [
    {
      "metadata": {
        "ecs": {
          "version": "1.11.0"
        },
        "host": {
          "id": "0cfead88e2024bd8a27476352b5ab264",
          "ip": [
            "127.0.0.1",
            "::1",
            "10.0.2.15",
            "fe80::2ac7:8e15:b957:2fa1"
          ],
          "os": {
            "Ext": {
              "variant": "Ubuntu"
            },
            "full": "Ubuntu 20.04.2",
            "name": "Linux",
            "type": "linux",
            "family": "ubuntu",
            "kernel": "5.8.0-59-generic #66~20.04.1-Ubuntu SMP Thu Jun 17 11:14:10 UTC 2021",
            "version": "20.04.2",
            "platform": "ubuntu"
          },
          "mac": [
            "08:00:27:e6:78:8b"
          ],
          "name": "david-Xubuntu",
          "hostname": "david-Xubuntu",
          "architecture": "x86_64"
        },
        "agent": {
          "id": "285297c6-3bff-4b83-9a07-f3e749801123",
          "type": "endpoint",
          "build": {
            "original": "version: 7.16.0, compiled: Tue Nov 16 16:00:00 2021, branch: 7.16, commit: 73a51033db85e0fb3be1c934697ef6a2b08979ab"
          },
          "version": "7.16.0"
        },
        "event": {
          "id": "MNtSXK/SkhEBnmgt++++++7S",
          "kind": "metric",
          "type": [
            "info"
          ],
          "action": "endpoint_metadata",
          "module": "endpoint",
          "created": "2023-07-04T15:47:57.432173535Z",
          "dataset": "endpoint.metadata",
          "category": [
            "host"
          ],
          "ingested": "2023-07-04T15:47:58Z",
          "sequence": 400,
          "agent_id_status": "verified"
        },
        "elastic": {
          "agent": {
            "id": "285297c6-3bff-4b83-9a07-f3e749801123"
          }
        },
        "message": "Endpoint metadata",
        "Endpoint": {
          "state": {
            "isolation": false
          },
          "policy": {
            "applied": {
              "id": "d5371dcd-93b7-4627-af88-4084f7d6aa3e",
              "name": "test",
              "status": "success",
              "version": "3",
              "endpoint_policy_version": "2"
            }
          },
          "status": "enrolled",
          "capabilities": [
            "isolation"
          ],
          "configuration": {
            "isolation": false
          }
        },
        "@timestamp": "2023-07-04T15:47:57.432173535Z",
        "data_stream": {
          "type": "metrics",
          "dataset": "endpoint.metadata",
          "namespace": "default"
        }
      },
      "host_status": "healthy",
      "policy_info": {
        "agent": {
          "applied": {
            "id": "ed7e3720-4bad-11ec-a2a8-fb22e62a5753",
            "revision": 0
          },
          "configured": {
            "id": "ed7e3720-4bad-11ec-a2a8-fb22e62a5753",
            "revision": 3
          }
        },
        "endpoint": {
          "id": "d5371dcd-93b7-4627-af88-4084f7d6aa3e",
          "revision": 2
        }
      },
      "last_checkin": "2023-07-04T15:47:57.432Z"
    },
    {
      "metadata": {
        "ecs": {
          "version": "1.11.0"
        },
        "host": {
          "id": "17d9cabc-7edd-43bc-bacb-8da5f5e6c0e5",
          "ip": [
            "10.0.2.15",
            "fe80::21a6:63d3:d70e:e3ad",
            "127.0.0.1",
            "::1"
          ],
          "os": {
            "Ext": {
              "variant": "Windows 10 Enterprise Evaluation"
            },
            "full": "Windows 10 Enterprise Evaluation 20H2 (10.0.19042.906)",
            "name": "Windows",
            "type": "windows",
            "family": "windows",
            "kernel": "20H2 (10.0.19042.906)",
            "version": "20H2 (10.0.19042.906)",
            "platform": "windows"
          },
          "mac": [
            "08:00:27:b1:1d:5a"
          ],
          "name": "WinDev2104Eval",
          "hostname": "WinDev2104Eval",
          "architecture": "x86_64"
        },
        "agent": {
          "id": "abb8a826-6812-448c-a571-6d8269b51449",
          "type": "endpoint",
          "build": {
            "original": "version: 7.16.0, compiled: Tue Nov 16 17:00:00 2021, branch: 7.16, commit: 73a51033db85e0fb3be1c934697ef6a2b08979ab"
          },
          "version": "7.16.0"
        },
        "event": {
          "id": "MNtRc++KoKHXXwlj+++++/N9",
          "kind": "metric",
          "type": [
            "info"
          ],
          "action": "endpoint_metadata",
          "module": "endpoint",
          "created": "2023-07-04T15:44:31.4917849Z",
          "dataset": "endpoint.metadata",
          "category": [
            "host"
          ],
          "ingested": "2023-07-04T15:44:33Z",
          "sequence": 5159,
          "agent_id_status": "verified"
        },
        "elastic": {
          "agent": {
            "id": "abb8a826-6812-448c-a571-6d8269b51449"
          }
        },
        "message": "Endpoint metadata",
        "Endpoint": {
          "state": {
            "isolation": false
          },
          "policy": {
            "applied": {
              "id": "d5371dcd-93b7-4627-af88-4084f7d6aa3e",
              "name": "test",
              "status": "success",
              "version": "3",
              "endpoint_policy_version": "2"
            }
          },
          "status": "enrolled",
          "capabilities": [
            "isolation"
          ],
          "configuration": {
            "isolation": false
          }
        },
        "@timestamp": "2023-07-04T15:44:31.4917849Z",
        "data_stream": {
          "type": "metrics",
          "dataset": "endpoint.metadata",
          "namespace": "default"
        }
      },
      "host_status": "healthy",
      "policy_info": {
        "agent": {
          "applied": {
            "id": "ed7e3720-4bad-11ec-a2a8-fb22e62a5753",
            "revision": 0
          },
          "configured": {
            "id": "ed7e3720-4bad-11ec-a2a8-fb22e62a5753",
            "revision": 3
          }
        },
        "endpoint": {
          "id": "d5371dcd-93b7-4627-af88-4084f7d6aa3e",
          "revision": 2
        }
      },
      "last_checkin": "2023-07-04T15:44:31.491Z"
    }
  ],
  "page": 0,
  "total": 2,
  "pageSize": 10,
  "sortField": "enrolled_at",
  "sortDirection": "desc"
}

Get exception lists

GET /api/exception_lists/_find
Api key auth

Get a list of all exception list containers.

Query parameters

  • filter string

    Filters the returned results according to the value of the specified field.

    Uses the so type.field name:field value syntax, where so type can be:

    • exception-list: Specify a space-aware exception list.
    • exception-list-agnostic: Specify an exception list that is shared across spaces.
  • namespace_type array[string]

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

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

  • page integer

    The page number to return

    Minimum value is 1.

  • per_page integer

    The number of exception lists to return per page

    Minimum value is 1.

  • sort_field string

    Determines which field is used to sort the results.

  • sort_order string

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

    Values are desc or asc.

Responses

  • 200 application/json

    Successful response

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

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

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

    • page integer Required

      Minimum value is 1.

    • per_page integer Required

      Minimum value is 1.

    • total integer Required

      Minimum value is 0.
  • 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
GET /api/exception_lists/_find 
curl \
 --request GET 'http://localhost:5622/api/exception_lists/_find' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "data": [
    {
      "id": "9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85",
      "name": "Detection Exception List",
      "tags": [
        "malware"
      ],
      "type": "detection",
      "list_id": "simple_list",
      "version": 1,
      "_version": "WzIsMV0=",
      "os_types": [],
      "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"
    }
  ],
  "page": 1,
  "total": 1,
  "per_page": 20
}
Response examples (400) 
{
  "error": "Bad Request",
  "message": "[request query]: namespace_type.0: Invalid enum value. Expected 'agnostic' | 'single', received 'blob'",
  "statusCode": 400
}
Response examples (401) 
{
  "error": "Unauthorized",
  "message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403) 
{
  "error": "Forbidden",
  "message": "API [GET /api/exception_lists/_find?namespace_type=single] is unauthorized for user, this action is granted by the Kibana privileges [lists-read]",
  "statusCode": 403
}
Response examples (500) 
{
  "message": "Internal Server Error",
  "status_code": 500
}

Patch a value list item

PATCH /api/lists/items
Api key auth

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

application/json

Body Required

Value list item's properties

  • _version string

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

  • id string(nonempty) Required

    Value list item's identifier.

    Minimum length is 1.

  • meta object

    Placeholder for metadata about the value list item.

    Additional properties are allowed.

  • refresh string

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

    Values are true, false, or wait_for.

  • value string(nonempty)

    The value used to evaluate exceptions.

    Minimum length is 1.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • _version string

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

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

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

    • 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 item's identifier.

      Minimum length is 1.

    • list_id string(nonempty) Required

      Value list's identifier.

      Minimum length is 1.

    • meta object

      Placeholder for metadata about the value list item.

      Additional properties are allowed.

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

    • value string(nonempty) Required

      The value used to evaluate exceptions.

      Minimum length 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 item not found response

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

    Internal server error response

    Hide response attributes Show response attributes object
PATCH /api/lists/items 
curl \
 --request PATCH 'http://localhost:5622/api/lists/items' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"id":"pd1WRJQBs4HAK3VQeHFI","value":"255.255.255.255"}'
Request example 
{
  "id": "pd1WRJQBs4HAK3VQeHFI",
  "value": "255.255.255.255"
}
Response examples (200) 
{
  "id": "pd1WRJQBs4HAK3VQeHFI",
  "type": "ip",
  "value": "255.255.255.255",
  "list_id": "ip_list",
  "_version": "WzE5LDFd",
  "@timestamp": "2025-01-08T05:15:05.159Z",
  "created_at": "2025-01-08T05:15:05.159Z",
  "created_by": "elastic",
  "updated_at": "2025-01-08T05:23:37.602Z",
  "updated_by": "elastic",
  "tie_breaker_id": "eee41dc7-1666-4876-982f-8b0f7b59eca3"
}
Response examples (400) 
{
  "message": "{\"took\":15,\"timed_out\":false,\"total\":1,\"updated\":0,\"deleted\":0,\"batches\":1,\"version_conflicts\":0,\"noops\":0,\"retries\":{\"bulk\":0,\"search\":0},\"throttled_millis\":0,\"requests_per_second\":-1,\"throttled_until_millis\":0,\"failures\":[{\"index\":\".ds-.items-default-2025.01.09-000001\",\"id\":\"ip_item\",\"cause\":{\"type\":\"document_parsing_exception\",\"reason\":\"[1:107] failed to parse field [ip] of type [ip] in document with id ip_item. Preview of fields value: 2\",\"caused_by\":{\"type\":\"illegal_argument_exception\",\"reason\":\"2 is not an IP string literal.\"}},\"status\":400}]}",
  "status_code": 400
}
Response examples (401) 
{
  "error": "Unauthorized",
  "message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403) 
{
  "error": "Forbidden",
  "message": "API [PATCH /api/lists/items] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}
Response examples (404) 
{
  "message": "list item id: \\\"foo\\\" not found",
  "status_code": 404
}
Response examples (500) 
{
  "message": "Internal Server Error",
  "status_code": 500
}

Get saved query details

GET /api/osquery/saved_queries/{id}
Api key auth

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

Path parameters

  • id string | null Required

    The ID of a saved query.

Responses

  • 200 application/json

    OK
GET /api/osquery/saved_queries/{id} 
curl \
 --request GET 'http://localhost:5622/api/osquery/saved_queries/3c42c847-eb30-4452-80e0-728584042334' \
 --header "Authorization: $API_KEY"
Response examples (200) 
{
  "data": {
    "id": "3c42c847-eb30-4452-80e0-728584042334",
    "type": "osquery-saved-query",
    "version": "WzQzMTcsMV0=",
    "attributes": {
      "id": "saved_query_id",
      "query": "select * from uptime;",
      "version": "2.8.0",
      "interval": "60",
      "platform": "linux,darwin",
      "prebuilt": false,
      "created_at": "2022-07-26T09:28:08.597Z",
      "created_by": "elastic",
      "updated_at": "2022-07-26T09:28:08.597Z",
      "updated_by": "elastic",
      "description": "Saved query description",
      "ecs_mapping": {
        "host.uptime": {
          "field": "total_seconds"
        }
      }
    },
    "namespaces": [
      "default"
    ],
    "references": [],
    "updated_at": "2022-07-26T09:28:08.600Z",
    "coreMigrationVersion": "8.4.0"
  }
}

Create a clean draft Timeline or Timeline template

POST /api/timeline/_draft
Api key auth

Create a clean draft Timeline or Timeline template for the current user.

If the user already has a draft Timeline, the existing draft Timeline is cleared and returned.

application/json

Body Required

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

  • timelineType string | null Required

    The type of Timeline.

    Values are default or template.

Responses

POST /api/timeline/_draft 
curl \
 --request POST 'http://localhost:5622/api/timeline/_draft' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"timelineType":"default"}'
Request examples 
{
  "timelineType": "default"
}
Response examples (200) 
{
  "columns": [
    {
      "id": "@timestamp",
      "columnHeaderType": "not-filtered"
    },
    {
      "id": "event.category",
      "columnHeaderType": "not-filtered"
    }
  ],
  "created": 1587468588922,
  "createdBy": "casetester",
  "dataProviders": [
    {
      "id": "id-d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b",
      "name": "d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b",
      "enabled": true,
      "excluded": false,
      "queryMatch": {
        "field": "_id,",
        "value": "d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bcbf66f57d124dcc739c98e6b,",
        "operator": ":"
      }
    }
  ],
  "dataViewId": "security-solution-default",
  "dateRange": {
    "end": 1587456479201,
    "start": 1587370079200
  },
  "description": "Investigating exposure of CVE XYZ",
  "eqlOptions": {
    "size": 100,
    "query": "sequence\\n[process where process.name == \"sudo\"]\\n[any where true]",
    "timestampField": "@timestamp",
    "eventCategoryField": "event.category"
  },
  "eventType": "all",
  "excludedRowRendererIds": [
    "alert"
  ],
  "favorite": [
    {
      "userName": "elastic",
      "favoriteDate": 1741337636741
    }
  ],
  "filters": [
    {
      "meta": {
        "key": "@timestamp",
        "type": "exists",
        "alias": "Custom filter name",
        "index": ".alerts-security.alerts-default,logs-*",
        "value": "exists",
        "negate": "false,",
        "disabled": false
      },
      "query": "{\"exists\":{\"field\":\"@timestamp\"}}"
    }
  ],
  "indexNames": [
    ".logs*"
  ],
  "kqlMode": "search",
  "kqlQuery": {
    "kuery": {
      "kind": "kuery",
      "expression": "_id : *"
    },
    "filterQuery": null,
    "serializedQuery": "{\"bool\":{\"should\":[{\"exists\":{\"field\":\"_id\"}}],\"minimum_should_match\":1}}"
  },
  "savedQueryId": "c7b16904-02d7-4f32-b8f2-cc20f9625d6e",
  "savedSearchId": "6ce1b592-84e3-4b4a-9552-f189d4b82075",
  "sort": {
    "columnId": "@timestamp",
    "sortDirection": "desc"
  },
  "status": "active",
  "templateTimelineId": "6ce1b592-84e3-4b4a-9552-f189d4b82075",
  "templateTimelineVersion": 12,
  "timelineType": "default",
  "title": "CVE XYZ investigation",
  "updated": 1741344876825,
  "updatedBy": "casetester",
  "savedObjectId": "15c1929b-0af7-42bd-85a8-56e234cc7c4e",
  "version": "WzE0LDFd",
  "eventIdToNoteIds": [
    {
      "created": 1587468588922,
      "createdBy": "casetester",
      "updated": 1741344876825,
      "updatedBy": "casetester",
      "eventId": "d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc",
      "note": "This is an example text",
      "timelineId": "15c1929b-0af7-42bd-85a8-56e234cc7c4e",
      "noteId": "709f99c6-89b6-4953-9160-35945c8e174e",
      "version": "WzQ2LDFd"
    }
  ],
  "noteIds": [
    "709f99c6-89b6-4953-9160-35945c8e174e"
  ],
  "notes": [
    {
      "created": 1587468588922,
      "createdBy": "casetester",
      "updated": 1741344876825,
      "updatedBy": "casetester",
      "eventId": "d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc",
      "note": "This is an example text",
      "timelineId": "15c1929b-0af7-42bd-85a8-56e234cc7c4e",
      "noteId": "709f99c6-89b6-4953-9160-35945c8e174e",
      "version": "WzQ2LDFd"
    }
  ],
  "pinnedEventIds": [
    "983f99c6-89b6-4953-9160-35945c8a194f"
  ],
  "pinnedEventsSaveObject": [
    {
      "created": 1587468588922,
      "createdBy": "casetester",
      "updated": 1741344876825,
      "updatedBy": "casetester",
      "eventId": "d3a1d35a3e84a81b2f8f3859e064c224cdee1b4bc",
      "timelineId": "15c1929b-0af7-42bd-85a8-56e234cc7c4e",
      "pinnedEventId": "10r1929b-0af7-42bd-85a8-56e234f98h2f3",
      "version": "WzQ2LDFe"
    }
  ]
}
Response examples (403) 
{
  "message": "string",
  "status_code": 42.0
}
Response examples (409) 
{
  "message": "string",
  "status_code": 42.0
}

Delete a space

DELETE /api/spaces/space/{id}
Api key auth

When you delete a space, all saved objects that belong to the space are automatically deleted, which is permanent and cannot be undone.

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    The space identifier.

Responses

  • 204

    Indicates a successful call.

  • 404

    Indicates that the request failed.

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

Unlink a dashboard from a stream Technical Preview

DELETE /api/streams/{name}/dashboards/{dashboardId}
Api key auth

Unlinks a dashboard from a stream. Noop if the dashboard is not linked to the stream.

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

application/json

Body

object object

Additional properties are NOT allowed.
DELETE /api/streams/{name}/dashboards/{dashboardId} 
curl \
 --request DELETE 'http://localhost:5622/api/streams/{name}/dashboards/{dashboardId}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true"
Request examples 
# Headers
kbn-xsrf: true

# Payload
{}