Get the alerting framework health

GET /api/alerting/_health

You must have read privileges for the Management > Stack Rules feature or for at least one of the Analytics > Discover, Analytics > Machine Learning, Observability, or Security features.

Responses

  • 200 application/json

    Indicates a successful call.

    Hide response attributes Show response attributes object
    • Three substates identify the health of the alerting framework: decryption_health, execution_health, and read_health.

      Additional properties are allowed.

      Hide alerting_framework_health attributes Show alerting_framework_health attributes object
      • The timestamp and status of the rule decryption.

        Additional properties are allowed.

        Hide decryption_health attributes Show decryption_health attributes object
      • The timestamp and status of the rule run.

        Additional properties are allowed.

        Hide execution_health attributes Show execution_health attributes object
      • The timestamp and status of the rule reading events.

        Additional properties are allowed.

        Hide read_health attributes Show read_health attributes object
    • If false, the encrypted saved object plugin does not have a permanent encryption key.

    • If false, security is enabled but TLS is not.

  • 401 application/json

    Authorization information is missing or invalid.

    Hide response attributes Show response attributes object
GET /api/alerting/_health
curl \
 --request GET https://localhost:5601/api/alerting/_health
Response examples (200)
{
  "is_sufficiently_secure": true,
  "alerting_framework_health": {
    "read_health": {
      "status": "ok",
      "timestamp": "2023-01-13T01:28:00.280Z"
    },
    "execution_health": {
      "status": "ok",
      "timestamp": "2023-01-13T01:28:00.280Z"
    },
    "decryption_health": {
      "status": "ok",
      "timestamp": "2023-01-13T01:28:00.280Z"
    }
  },
  "has_permanent_encryption_key": true
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}
























Enable a rule

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    The identifier for the rule.

Responses

  • Indicates a successful call.

  • Indicates an invalid schema or parameters.

  • Indicates that this call is forbidden.

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

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












Mute an alert

POST /api/alerting/rule/{rule_id}/alert/{alert_id}/_mute

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • rule_id string Required

    The identifier for the rule.

  • alert_id string Required

    The identifier for the alert.

Responses

  • Indicates a successful call.

  • Indicates an invalid schema or parameters.

  • Indicates that this call is forbidden.

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

POST /api/alerting/rule/{rule_id}/alert/{alert_id}/_mute
curl \
 --request POST https://localhost:5601/api/alerting/rule/{rule_id}/alert/{alert_id}/_mute \
 --header "kbn-xsrf: true"








APM agent configuration

Adjust APM agent configuration without need to redeploy your application.













Get agent name for service

GET /api/apm/settings/agent-configuration/agent_name

Retrieve agentName for a 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.

Query parameters

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

    Not found response

    Hide response attributes Show response attributes object
GET /api/apm/settings/agent-configuration/agent_name
curl \
 --request GET https://localhost:5601/api/apm/settings/agent-configuration/agent_name?serviceName=node \
 --header "elastic-api-version: 2023-10-31"
Response examples (200)
{
  "agentName": "nodejs"
}
Response examples (400)
{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 400
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}
Response examples (404)
{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 404
}




Lookup single agent configuration

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

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

Headers

  • elastic-api-version string Required

    The version of the API to use

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

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

application/json

Body Required

  • etag string

    If etags match then applied_by_agent field will be set to true

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

  • service object Required

    Service

    Additional properties are allowed.

    Hide service attributes Show service attributes object

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • _id string

      Identifier

    • _index string

      Index

    • _score number

      Score

    • _source object

      Agent configuration

      Additional properties are allowed.

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

        Timestamp

      • Agent name

      • Applied by agent

      • etag string Required

        Etag

      • service object Required

        Service

        Additional properties are allowed.

        Hide service attributes Show service attributes object
      • settings object Required

        Agent configuration settings

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

    Bad Request response

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

    Unauthorized response

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

    Not found response

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

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

Get single agent configuration

GET /api/apm/settings/agent-configuration/view

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

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes 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
  • 404 application/json

    Not found response

    Hide response attributes Show response attributes object
GET /api/apm/settings/agent-configuration/view
curl \
 --request GET https://localhost:5601/api/apm/settings/agent-configuration/view \
 --header "elastic-api-version: 2023-10-31"
Response examples (200)
{
  "id": "string",
  "@timestamp": 1730194190636,
  "agent_name": "string",
  "applied_by_agent": true,
  "etag": "0bc3b5ebf18fba8163fe4c96f491e3767a358f85",
  "service": {
    "environment": "prod",
    "name": "node"
  },
  "settings": {
    "additionalProperty1": "string",
    "additionalProperty2": "string"
  }
}
Response examples (400)
{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 400
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}
Response examples (404)
{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 404
}






Create a service annotation

POST /api/apm/services/{serviceName}/annotation

Create a new annotation for 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.

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

application/json

Body Required

Responses

  • 200 application/json

    Annotation created successfully

    Hide response attributes Show response attributes 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
  • 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
POST /api/apm/services/{serviceName}/annotation
curl \
 --request POST https://localhost:5601/api/apm/services/{serviceName}/annotation \
 --header "Content-Type: application/json" \
 --header "elastic-api-version: 2023-10-31" \
 --header "kbn-xsrf: true" \
 --data '{"@timestamp":"string","message":"string","service":{"environment":"string","version":"string"},"tags":["string"]}'
Request examples
# Headers
elastic-api-version: 2023-10-31
kbn-xsrf: true

# Payload
{
  "@timestamp": "string",
  "message": "string",
  "service": {
    "environment": "string",
    "version": "string"
  },
  "tags": [
    "string"
  ]
}
Response examples (200)
{
  "_id": "string",
  "_index": "string",
  "_source": {
    "@timestamp": "string",
    "annotation": {
      "title": "string",
      "type": "string"
    },
    "event": {
      "created": "string"
    },
    "message": "string",
    "service": {
      "environment": "string",
      "name": "string",
      "version": "string"
    },
    "tags": [
      "string"
    ]
  }
}
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
}











































Get all alerts for a case Technical preview

GET /api/cases/{caseId}/alerts

You must have read privileges for the Cases feature in the Management, Observability, or Security section of the Kibana feature privileges, depending on the owner of the cases you're seeking.

Path parameters

  • caseId string Required

    The identifier for the case. To retrieve case IDs, use the find cases API. All non-ASCII characters must be URL encoded.

Responses

  • 200 application/json

    Indicates a successful call.

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

    Authorization information is missing or invalid.

    Hide response attributes Show response attributes object
GET /api/cases/{caseId}/alerts
curl \
 --request GET https://localhost:5601/api/cases/9c235210-6834-11ea-a78c-6ffb38a34414/alerts
Response examples (200)
[
  {
    "id": "f6a7d0c3-d52d-432c-b2e6-447cd7fce04d",
    "index": ".alerts-observability.logs.alerts-default",
    "attached_at": "2022-07-25T20:09:40.963Z"
  }
]
Response examples (401)
{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}












































Add case settings

POST /api/cases/configure

Case settings include external connection details, custom fields, and templates. Connectors are used to interface with external systems. You must create a connector before you can use it in your cases. If you set a default connector, it is automatically selected when you create cases in Kibana. If you use the create case API, however, you must still specify all of the connector details. You must have all privileges for the Cases feature in the Management, Observability, or Security section of the Kibana feature privileges, depending on where you are creating cases.

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

application/json

Body

  • closure_type string Required

    Indicates whether a case is automatically closed when it is pushed to external systems (close-by-pushing) or not automatically closed (close-by-user).

    Values are close-by-pushing or close-by-user.

  • connector object Required

    An object that contains the connector configuration.

    Additional properties are allowed.

    Hide connector attributes Show connector attributes object
    • fields object | null Required

      The fields specified in the case configuration are not used and are not propagated to individual cases, therefore it is recommended to set it to null.

      Additional properties are allowed.

    • id string Required

      The identifier for the connector. If you do not want a default connector, use none. To retrieve connector IDs, use the find connectors API.

    • name string Required

      The name of the connector. If you do not want a default connector, use none. To retrieve connector names, use the find connectors API.

    • type string Required

      The type of connector.

      Values are .cases-webhook, .jira, .none, .resilient, .servicenow, .servicenow-sir, or .swimlane.

  • customFields array[object]

    Custom fields case configuration.

    At least 0 but not more than 10 elements.

    Hide customFields attributes Show customFields attributes object
    • defaultValue string | boolean

      A default value for the custom field. If the type is text, the default value must be a string. If the type is toggle, the default value must be boolean.

    • key string Required

      A unique key for the custom field. Must be lower case and composed only of a-z, 0-9, '_', and '-' characters. It is used in API calls to refer to a specific custom field.

      Minimum length is 1, maximum length is 36.

    • label string Required

      The custom field label that is displayed in the case.

      Minimum length is 1, maximum length is 50.

    • type string Required

      The type of the custom field.

      Values are text or toggle.

    • required boolean Required

      Indicates whether the field is required. If false, the custom field can be set to null or omitted when a case is created or updated.

  • owner string Required

    The application that owns the cases: Stack Management, Observability, or Elastic Security.

    Values are cases, observability, or securitySolution.

  • templates array[object] Technical preview
    Hide templates attributes Show templates attributes object
    • Additional properties are allowed.

      Hide caseFields attributes Show caseFields attributes object
      • assignees array[object] | null

        An array containing users that are assigned to the case.

        Not more than 10 elements.

        Hide assignees attribute Show assignees attribute object
        • uid string Required

          A unique identifier for the user profile. These identifiers can be found by using the suggest user profile API.

      • category string

        A word or phrase that categorizes the case.

        Maximum length is 50.

      • Additional properties are allowed.

        Hide connector attributes Show connector attributes object
        • fields object | null

          The fields specified in the case configuration are not used and are not propagated to individual cases, therefore it is recommended to set it to null.

          Additional properties are allowed.

        • id string

          The identifier for the connector. If you do not want a default connector, use none. To retrieve connector IDs, use the find connectors API.

        • name string

          The name of the connector. If you do not want a default connector, use none. To retrieve connector names, use the find connectors API.

        • type string

          The type of connector.

          Values are .cases-webhook, .jira, .none, .resilient, .servicenow, .servicenow-sir, or .swimlane.

      • customFields array[object] Technical preview

        Custom field values in the template.

        Hide customFields attributes Show customFields attributes object
        • key string

          The unique key for the custom field.

        • type string

          The type of the custom field.

          Values are text or toggle.

        • value string | boolean

          The default value for the custom field when a case uses the template. If the type is text, the default value must be a string. If the type is toggle, the default value must be boolean.

      • The description for the case.

        Maximum length is 30000.

      • settings object

        An object that contains the case settings.

        Additional properties are allowed.

        Hide settings attribute Show settings attribute object
        • syncAlerts boolean Required

          Turns alert syncing on or off.

      • severity string

        The severity of the case.

        Values are critical, high, low, or medium. Default value is low.

      • tags array[string]

        The words and phrases that help categorize cases. It can be an empty array.

        Not more than 200 elements. Maximum length of each is 256.

      • title string

        A title for the case.

        Maximum length is 160.

    • A description for the template.

    • key string

      A unique key for the template. Must be lower case and composed only of a-z, 0-9, '_', and '-' characters. It is used in API calls to refer to a specific template.

    • name string

      The name of the template.

    • tags array[string]

      The words and phrases that help categorize templates. It can be an empty array.

      Not more than 200 elements. Maximum length of each is 256.

Responses

  • 200 application/json

    Indicates a successful call.

    Hide response attributes Show response attributes object
    • Indicates whether a case is automatically closed when it is pushed to external systems (close-by-pushing) or not automatically closed (close-by-user).

      Values are close-by-pushing or close-by-user.

    • Additional properties are allowed.

      Hide connector attributes Show connector attributes object
      • fields object | null

        The fields specified in the case configuration are not used and are not propagated to individual cases, therefore it is recommended to set it to null.

        Additional properties are allowed.

      • id string

        The identifier for the connector. If you do not want a default connector, use none. To retrieve connector IDs, use the find connectors API.

      • name string

        The name of the connector. If you do not want a default connector, use none. To retrieve connector names, use the find connectors API.

      • type string

        The type of connector.

        Values are .cases-webhook, .jira, .none, .resilient, .servicenow, .servicenow-sir, or .swimlane.

    • created_at string(date-time)
    • Additional properties are allowed.

      Hide created_by attributes Show created_by attributes object
    • customFields array[object]

      Custom fields configuration details.

      Hide customFields attributes Show customFields attributes object
      • defaultValue string | boolean

        A default value for the custom field. If the type is text, the default value must be a string. If the type is toggle, the default value must be boolean.

      • key string

        A unique key for the custom field. Must be lower case and composed only of a-z, 0-9, '_', and '-' characters. It is used in API calls to refer to a specific custom field.

        Minimum length is 1, maximum length is 36.

      • label string

        The custom field label that is displayed in the case.

        Minimum length is 1, maximum length is 50.

      • type string

        The type of the custom field.

        Values are text or toggle.

      • required boolean

        Indicates whether the field is required. If false, the custom field can be set to null or omitted when a case is created or updated.

    • error string | null
    • id string
    • mappings array[object]
      Hide mappings attributes Show mappings attributes object
    • owner string

      The application that owns the cases: Stack Management, Observability, or Elastic Security.

      Values are cases, observability, or securitySolution.

    • templates array[object] Technical preview
      Hide templates attributes Show templates attributes object
      • Additional properties are allowed.

        Hide caseFields attributes Show caseFields attributes object
        • assignees array[object] | null

          An array containing users that are assigned to the case.

          Not more than 10 elements.

          Hide assignees attribute Show assignees attribute object
          • uid string Required

            A unique identifier for the user profile. These identifiers can be found by using the suggest user profile API.

        • category string

          A word or phrase that categorizes the case.

          Maximum length is 50.

        • Additional properties are allowed.

          Hide connector attributes Show connector attributes object
          • fields object | null

            The fields specified in the case configuration are not used and are not propagated to individual cases, therefore it is recommended to set it to null.

            Additional properties are allowed.

          • id string

            The identifier for the connector. If you do not want a default connector, use none. To retrieve connector IDs, use the find connectors API.

          • name string

            The name of the connector. If you do not want a default connector, use none. To retrieve connector names, use the find connectors API.

          • type string

            The type of connector.

            Values are .cases-webhook, .jira, .none, .resilient, .servicenow, .servicenow-sir, or .swimlane.

        • customFields array[object] Technical preview

          Custom field values in the template.

          Hide customFields attributes Show customFields attributes object
          • key string

            The unique key for the custom field.

          • type string

            The type of the custom field.

            Values are text or toggle.

          • value string | boolean

            The default value for the custom field when a case uses the template. If the type is text, the default value must be a string. If the type is toggle, the default value must be boolean.

        • The description for the case.

          Maximum length is 30000.

        • settings object

          An object that contains the case settings.

          Additional properties are allowed.

          Hide settings attribute Show settings attribute object
          • syncAlerts boolean Required

            Turns alert syncing on or off.

        • severity string

          The severity of the case.

          Values are critical, high, low, or medium. Default value is low.

        • tags array[string]

          The words and phrases that help categorize cases. It can be an empty array.

          Not more than 200 elements. Maximum length of each is 256.

        • title string

          A title for the case.

          Maximum length is 160.

      • A description for the template.

      • key string

        A unique key for the template. Must be lower case and composed only of a-z, 0-9, '_', and '-' characters. It is used in API calls to refer to a specific template.

      • name string

        The name of the template.

      • tags array[string]

        The words and phrases that help categorize templates. It can be an empty array.

        Not more than 200 elements. Maximum length of each is 256.

    • updated_at string(date-time) | null
    • updated_by object | null

      Additional properties are allowed.

      Hide updated_by attributes Show updated_by attributes object | null
    • version string
  • 401 application/json

    Authorization information is missing or invalid.

    Hide response attributes Show response attributes object
POST /api/cases/configure
curl \
 --request POST https://localhost:5601/api/cases/configure \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: string" \
 --data '{"owner":"cases","connector":{"id":"5e656730-e1ca-11ec-be9b-9b1838238ee6","name":"my-jira-connector","type":".jira","fields":null},"templates":[{"key":"505932fe-ee3a-4960-a661-c781b5acdb05","name":"template-1","tags":["Template tag 1"],"caseFields":{"tags":["Default case tag"],"title":"Default case title","category":"Default-category","assignees":[{"uid":"u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"}],"description":"A default description for cases.","customFields":[{"key":"d312efda-ec2b-42ec-9e2c-84981795c581","type":"text","value":"A text field value for the template."}]},"description":"A description of the template."}],"closure_type":"close-by-user","customFields":[{"key":"d312efda-ec2b-42ec-9e2c-84981795c581","type":"text","label":"my-text-field","required":false,"defaultValue":"My custom field default value."}]}'
Request example
{
  "owner": "cases",
  "connector": {
    "id": "5e656730-e1ca-11ec-be9b-9b1838238ee6",
    "name": "my-jira-connector",
    "type": ".jira",
    "fields": null
  },
  "templates": [
    {
      "key": "505932fe-ee3a-4960-a661-c781b5acdb05",
      "name": "template-1",
      "tags": [
        "Template tag 1"
      ],
      "caseFields": {
        "tags": [
          "Default case tag"
        ],
        "title": "Default case title",
        "category": "Default-category",
        "assignees": [
          {
            "uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
          }
        ],
        "description": "A default description for cases.",
        "customFields": [
          {
            "key": "d312efda-ec2b-42ec-9e2c-84981795c581",
            "type": "text",
            "value": "A text field value for the template."
          }
        ]
      },
      "description": "A description of the template."
    }
  ],
  "closure_type": "close-by-user",
  "customFields": [
    {
      "key": "d312efda-ec2b-42ec-9e2c-84981795c581",
      "type": "text",
      "label": "my-text-field",
      "required": false,
      "defaultValue": "My custom field default value."
    }
  ]
}
Response examples (200)
{
  "id": "4a97a440-e1cd-11ec-be9b-9b1838238ee6",
  "error": null,
  "owner": "cases",
  "version": "WzIwNzMsMV0=",
  "mappings": [
    {
      "source": "title",
      "target": "summary",
      "action_type": "overwrite"
    },
    {
      "source": "description",
      "target": "description",
      "action_type": "overwrite"
    },
    {
      "source": "comments",
      "target": "comments",
      "action_type": "append"
    },
    {
      "source": "tags",
      "target": "labels",
      "action_type": "overwrite"
    }
  ],
  "connector": {
    "id": "5e656730-e1ca-11ec-be9b-9b1838238ee6",
    "name": "my-jira-connector",
    "type": ".jira",
    "fields": null
  },
  "templates": [
    {
      "key": "505932fe-ee3a-4960-a661-c781b5acdb05",
      "name": "template-1",
      "tags": [
        "Template tag 1"
      ],
      "caseFields": {
        "tags": [
          "Default case tag"
        ],
        "title": "Default case title",
        "category": "Default-category",
        "assignees": [
          {
            "uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
          }
        ],
        "description": "A default description for cases.",
        "customFields": [
          {
            "key": "d312efda-ec2b-42ec-9e2c-84981795c581",
            "type": "text",
            "value": "A text field value for the template."
          }
        ]
      },
      "description": "A description of the template."
    }
  ],
  "created_at": "2024-07-01T17:07:17.767Z",
  "created_by": {
    "email": "null,",
    "username": "elastic",
    "full_name": null,
    "profile_uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
  },
  "updated_at": null,
  "updated_by": null,
  "closure_type": "close-by-user",
  "customFields": [
    {
      "key": "d312efda-ec2b-42ec-9e2c-84981795c581",
      "type": "text",
      "label": "my-text-field",
      "required": false,
      "defaultValue": "My custom field default value."
    }
  ]
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}




Get case connectors

GET /api/cases/configure/connectors/_find

Get information about connectors that are supported for use in cases. You must have read privileges for the Actions and Connectors feature in the Management section of the Kibana feature privileges.

Responses

GET /api/cases/configure/connectors/_find
curl \
 --request GET https://localhost:5601/api/cases/configure/connectors/_find
Response examples (200)
[
  {
    "id": "61787f53-4eee-4741-8df6-8fe84fa616f7",
    "name": "my-Jira",
    "config": {
      "apiUrl": "https://elastic.atlassian.net/",
      "projectKey": "ES"
    },
    "actionTypeId": ".jira",
    "isDeprecated": false,
    "isPreconfigured": false,
    "isMissingSecrets": false,
    "referencedByCount": 0
  }
]
Response examples (401)
{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}

Get case creators

GET /api/cases/reporters

Returns information about the users who opened cases. You must have read privileges for the Cases feature in the Management, Observability, or Security section of the Kibana feature privileges, depending on the owner of the cases. The API returns information about the users as they existed at the time of the case creation, including their name, full name, and email address. If any of those details change thereafter or if a user is deleted, the information returned by this API is unchanged.

Query parameters

  • owner string | array[string]

    A filter to limit the response to a specific set of applications. If this parameter is omitted, the response contains information about all the cases that the user has access to read.

Responses

  • 200 application/json

    Indicates a successful call.

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

    Authorization information is missing or invalid.

    Hide response attributes Show response attributes object
GET /api/cases/reporters
curl \
 --request GET https://localhost:5601/api/cases/reporters
Response examples (200)
[
  {
    "email": null,
    "username": "elastic",
    "full_name": null,
    "profile_uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
  },
  {
    "email": "jdoe@example.com",
    "username": "jdoe",
    "full_name": "Jane Doe",
    "profile_uid": "u_0wpfV1MqYDaXzLtRVY-gLMrddKDEmfz51Fszhj7hWC8_0"
  }
]
Response examples (401)
{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}










































Update an existing dashboard Technical Preview

PUT /api/dashboards/dashboard/{id}

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    A unique identifier for the dashboard.

application/json

Body

  • attributes object Required

    Additional properties are NOT allowed.

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

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

        Default value is true.

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

        Values are NONE or HIERARCHICAL. Default value is HIERARCHICAL.

      • controls array[object]

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

        Default value is [] (empty).

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

        • grow boolean

          Expand width of the control panel to fit available space.

          Default value is false.

        • id string

          The unique ID of the control.

        • order number Required

          The order of the control panel in the control group.

        • type string Required

          The type of the control panel.

        • width string

          Minimum width of the control panel in the control group.

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

      • Additional properties are allowed.

      • ignoreParentSettings object Required

        Additional properties are NOT allowed.

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

          Default value is false.

        • Ignore the global query bar in controls.

          Default value is false.

        • Ignore the global time range in controls.

          Default value is false.

        • Ignore validations in controls.

          Default value is false.

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

        Values are oneLine or twoLine. Default value is oneLine.

    • A short description.

      Default value is empty.

    • A container for various metadata

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

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

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

            Additional properties are NOT allowed.

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

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

              Values are appState or globalState.

          • meta object Required

            Additional properties are allowed.

            Hide meta attributes Show meta attributes object
          • query object

            Additional properties are allowed.

        • query object

          Additional properties are NOT allowed.

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

      Additional properties are NOT allowed.

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

        Default value is false.

      • syncColors boolean

        Synchronize colors between related panels in the dashboard.

        Default value is true.

      • syncCursor boolean

        Synchronize cursor position between related panels in the dashboard.

        Default value is true.

      • Synchronize tooltips between related panels in the dashboard.

        Default value is true.

      • useMargins boolean

        Show margins between panels in the dashboard layout.

        Default value is true.

    • panels array[object]

      Default value is [] (empty).

      Hide panels attributes Show panels attributes object
      • gridData object Required

        Additional properties are NOT allowed.

        Hide gridData attributes Show gridData attributes object
        • h number

          The height of the panel in grid units

          Minimum value is 1. Default value is 15.

        • i string

          The unique identifier of the panel

        • w number

          The width of the panel in grid units

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

        • x number Required

          The x coordinate of the panel in grid units

        • y number Required

          The y coordinate of the panel in grid units

      • id string

        The saved object id for by reference panels

      • panelConfig object Required

        Additional properties are allowed.

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

      • title string

        The title of the panel

      • type string Required

        The embeddable type

      • version string Deprecated

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

    • A container for various refresh interval settings

      Additional properties are NOT allowed.

      Hide refreshInterval attributes Show refreshInterval attributes object
      • display string Deprecated

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

      • pause boolean Required

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

      • section number Deprecated

        No longer used.

      • value number Required

        A numeric value indicating refresh frequency in milliseconds.

    • timeFrom string

      An ISO string indicating when to restore time from

    • Whether to restore time upon viewing this dashboard

      Default value is false.

    • timeTo string

      An ISO string indicating when to restore time from

    • title string Required

      A human-readable title for the dashboard

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

Responses

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

      Additional properties are allowed.

      Hide item attributes Show item attributes object
      • attributes object Required

        Additional properties are NOT allowed.

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

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

            Default value is true.

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

            Values are NONE or HIERARCHICAL. Default value is HIERARCHICAL.

          • controls array[object]

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

            Default value is [] (empty).

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

            • grow boolean

              Expand width of the control panel to fit available space.

              Default value is false.

            • id string

              The unique ID of the control.

            • order number Required

              The order of the control panel in the control group.

            • type string Required

              The type of the control panel.

            • width string

              Minimum width of the control panel in the control group.

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

          • Additional properties are allowed.

          • ignoreParentSettings object Required

            Additional properties are NOT allowed.

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

              Default value is false.

            • Ignore the global query bar in controls.

              Default value is false.

            • Ignore the global time range in controls.

              Default value is false.

            • Ignore validations in controls.

              Default value is false.

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

            Values are oneLine or twoLine. Default value is oneLine.

        • A short description.

          Default value is empty.

        • A container for various metadata

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

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

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

                Additional properties are NOT allowed.

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

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

                  Values are appState or globalState.

              • meta object Required

                Additional properties are allowed.

                Hide meta attributes Show meta attributes object
              • query object

                Additional properties are allowed.

            • query object

              Additional properties are NOT allowed.

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

          Additional properties are NOT allowed.

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

            Default value is false.

          • syncColors boolean

            Synchronize colors between related panels in the dashboard.

            Default value is true.

          • syncCursor boolean

            Synchronize cursor position between related panels in the dashboard.

            Default value is true.

          • Synchronize tooltips between related panels in the dashboard.

            Default value is true.

          • useMargins boolean

            Show margins between panels in the dashboard layout.

            Default value is true.

        • panels array[object]

          Default value is [] (empty).

          Hide panels attributes Show panels attributes object
          • gridData object Required

            Additional properties are NOT allowed.

            Hide gridData attributes Show gridData attributes object
            • h number

              The height of the panel in grid units

              Minimum value is 1. Default value is 15.

            • i string Required
            • w number

              The width of the panel in grid units

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

            • x number Required

              The x coordinate of the panel in grid units

            • y number Required

              The y coordinate of the panel in grid units

          • id string

            The saved object id for by reference panels

          • panelConfig object Required

            Additional properties are allowed.

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

            The title of the panel

          • type string Required

            The embeddable type

          • version string Deprecated

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

        • A container for various refresh interval settings

          Additional properties are NOT allowed.

          Hide refreshInterval attributes Show refreshInterval attributes object
          • display string Deprecated

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

          • pause boolean Required

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

          • section number Deprecated

            No longer used.

          • value number Required

            A numeric value indicating refresh frequency in milliseconds.

        • timeFrom string

          An ISO string indicating when to restore time from

        • Whether to restore time upon viewing this dashboard

          Default value is false.

        • timeTo string

          An ISO string indicating when to restore time from

        • title string Required

          A human-readable title for the dashboard

        • version number Deprecated
      • error object

        Additional properties are NOT allowed.

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

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























































































Request agent diagnostics

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

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

application/json

Body

Responses

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

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














































































Copy an agent policy

POST /api/fleet/agent_policies/{agentPolicyId}/copy

Copy an agent policy by ID.

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

Query parameters

  • format string

    Values are simplified or legacy.

application/json

Body

Responses

POST /api/fleet/agent_policies/{agentPolicyId}/copy
curl \
 --request POST https://localhost:5601/api/fleet/agent_policies/{agentPolicyId}/copy \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"description":"string","name":"string"}'
Request examples
# Headers
kbn-xsrf: true

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








































































Get agent setup info

GET /api/fleet/agents/setup

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

Responses

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









































Install a package from the registry

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

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

Query parameters

application/json

Body

Responses

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

      Additional properties are NOT allowed.

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

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

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

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




















Get a limited package list

GET /api/fleet/epm/packages/limited

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

Responses

  • 200 application/json
    Hide response attribute Show response attribute object
  • 400 application/json
    Hide response attributes Show response attributes object
GET /api/fleet/epm/packages/limited
curl \
 --request GET https://localhost:5601/api/fleet/epm/packages/limited
Response examples (200)
{
  "items": [
    "string"
  ]
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}

Get an inputs template

GET /api/fleet/epm/templates/{pkgName}/{pkgVersion}/inputs

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

Path parameters

Query parameters

Responses

GET /api/fleet/epm/templates/{pkgName}/{pkgVersion}/inputs
curl \
 --request GET https://localhost:5601/api/fleet/epm/templates/{pkgName}/{pkgVersion}/inputs
Response examples (200)
string
{
  "inputs": [
    {
      "id": "string",
      "streams": [
        {
          "data_stream": {
            "dataset": "string",
            "type": "string"
          },
          "id": "string"
        }
      ],
      "type": "string"
    }
  ]
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}






































Initiate Fleet setup

POST /api/fleet/setup

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
  • 400 application/json
    Hide response attributes Show response attributes object
  • 500 application/json
    Hide response attribute Show response attribute object
POST /api/fleet/setup
curl \
 --request POST https://localhost:5601/api/fleet/setup \
 --header "kbn-xsrf: true"
Response examples (200)
{
  "isInitialized": true,
  "nonFatalErrors": [
    {
      "message": "string",
      "name": "string"
    }
  ]
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}
Response examples (500)
{
  "message": "string"
}


























































Upgrade a package policy

POST /api/fleet/package_policies/upgrade

Upgrade a package policy to a newer package version.

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

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

application/json

Body

Responses

POST /api/fleet/package_policies/upgrade
curl \
 --request POST https://localhost:5601/api/fleet/package_policies/upgrade \
 --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",
  "message": "string",
  "statusCode": 42.0
}


























Get Fleet Server hosts

GET /api/fleet/fleet_server_hosts

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

Responses

GET /api/fleet/fleet_server_hosts
curl \
 --request GET https://localhost:5601/api/fleet/fleet_server_hosts
Response examples (200)
{
  "items": [
    {
      "host_urls": [
        "string"
      ],
      "id": "string",
      "is_default": false,
      "is_internal": true,
      "is_preconfigured": false,
      "name": "string",
      "proxy_id": "string"
    }
  ],
  "page": 42.0,
  "perPage": 42.0,
  "total": 42.0
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}

































































Create saved objects Deprecated

POST /api/saved_objects/_bulk_create

Headers

  • kbn-xsrf string Required

    Cross-site request forgery protection

Query parameters

  • overwrite boolean

    When true, overwrites the document with the same identifier.

application/json

Body Required

object object

Additional properties are allowed.

Responses

  • 200 application/json

    Indicates a successful call.

    Additional properties are allowed.

  • 400 application/json

    Bad request

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

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





















































































Read a KnowledgeBase

GET /api/security_ai_assistant/knowledge_base/{resource}

Read a single KB

Path parameters

  • resource string

    The KnowledgeBase resource value.

Responses

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








Applies a bulk action to multiple Knowledge Base Entries

POST /api/security_ai_assistant/knowledge_base/entries/_bulk_action

The bulk action is applied to all Knowledge Base Entries that match the filter or to the list of Knowledge Base Entries by their IDs

application/json

Body

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

      Name of the Knowledge Base Entry

    • Kibana Space, defaults to 'default' space

    • users array[object]

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

      Hide users attributes Show users attributes object
    • kbResource string Required

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

    • source string Required

      Source document name or filepath

    • text string Required

      Knowledge Base Entry content

    • type string Required Discriminator

      Entry type

      Value is document.

    • required boolean

      Whether this resource should always be included, defaults to false

    • vector object

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

      Additional properties are allowed.

      Hide vector attributes Show vector attributes object
      • modelId string Required

        ID of the model used to create the embeddings

      • tokens object Required

        Tokens with their corresponding values

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

    Additional properties are allowed.

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

      Array of Knowledge base Entry IDs

      At least 1 element.

    • query string

      Query to filter Knowledge Base Entries

  • update array[object]
    Any of:
    Hide attributes Show attributes
    • id string(nonempty) Required

      A string that does not contain only whitespace characters

      Minimum length is 1.

    • name string Required

      Name of the Knowledge Base Entry

    • Kibana Space, defaults to 'default' space

    • users array[object]

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

      Hide users attributes Show users attributes object
    • kbResource string Required

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

    • source string Required

      Source document name or filepath

    • text string Required

      Knowledge Base Entry content

    • type string Required Discriminator

      Entry type

      Value is document.

    • required boolean

      Whether this resource should always be included, defaults to false

    • vector object

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

      Additional properties are allowed.

      Hide vector attributes Show vector attributes object
      • modelId string Required

        ID of the model used to create the embeddings

      • tokens object Required

        Tokens with their corresponding values

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

Responses

  • 200 application/json

    Successful bulk operation request

    Hide response attributes Show response attributes object
    • attributes object Required

      Additional properties are allowed.

      Hide attributes attributes Show attributes attributes object
      • errors array[object]
        Hide errors attributes Show errors attributes object
      • results object Required

        Additional properties are allowed.

        Hide results attributes Show results attributes object
        • created array[object] Required
          Any of:
          Hide attributes Show attributes
          • name string Required

            Name of the Knowledge Base Entry

          • namespace string Required

            Kibana Space, defaults to 'default' space

          • users array[object] Required

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

            Hide users attributes Show users attributes object
          • createdAt string Required

            Time the Knowledge Base Entry was created

          • createdBy string Required

            User who created the Knowledge Base Entry

          • id string(nonempty) Required

            A string that does not contain only whitespace characters

            Minimum length is 1.

          • updatedAt string Required

            Time the Knowledge Base Entry was last updated

          • updatedBy string Required

            User who last updated the Knowledge Base Entry

          • kbResource string Required

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

          • source string Required

            Source document name or filepath

          • text string Required

            Knowledge Base Entry content

          • type string Required Discriminator

            Entry type

            Value is document.

          • required boolean

            Whether this resource should always be included, defaults to false

          • vector object

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

            Additional properties are allowed.

            Hide vector attributes Show vector attributes object
            • modelId string Required

              ID of the model used to create the embeddings

            • tokens object Required

              Tokens with their corresponding values

              Hide tokens attribute Show tokens attribute object
              • * number Additional properties
        • deleted array[string] Required
        • skipped array[object] Required
          Hide skipped attributes Show skipped attributes object
        • updated array[object] Required
          Any of:
          Hide attributes Show attributes
          • name string Required

            Name of the Knowledge Base Entry

          • namespace string Required

            Kibana Space, defaults to 'default' space

          • users array[object] Required

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

            Hide users attributes Show users attributes object
          • createdAt string Required

            Time the Knowledge Base Entry was created

          • createdBy string Required

            User who created the Knowledge Base Entry

          • id string(nonempty) Required

            A string that does not contain only whitespace characters

            Minimum length is 1.

          • updatedAt string Required

            Time the Knowledge Base Entry was last updated

          • updatedBy string Required

            User who last updated the Knowledge Base Entry

          • kbResource string Required

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

          • source string Required

            Source document name or filepath

          • text string Required

            Knowledge Base Entry content

          • type string Required Discriminator

            Entry type

            Value is document.

          • required boolean

            Whether this resource should always be included, defaults to false

          • vector object

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

            Additional properties are allowed.

            Hide vector attributes Show vector attributes object
            • modelId string Required

              ID of the model used to create the embeddings

            • tokens object Required

              Tokens with their corresponding values

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

        Additional properties are allowed.

        Hide summary attributes Show summary attributes object
    • message string
    • statusCode integer
    • success boolean
  • 400 application/json

    Generic Error

    Hide response attributes Show response attributes object
POST /api/security_ai_assistant/knowledge_base/entries/_bulk_action
curl \
 --request POST https://localhost:5601/api/security_ai_assistant/knowledge_base/entries/_bulk_action \
 --header "Content-Type: application/json" \
 --data '{"create":[{"name":"string","namespace":"string","users":[{"id":"string","name":"string"}],"kbResource":"string","source":"string","text":"string","type":"document","required":true,"vector":{"modelId":"string","tokens":{"additionalProperty1":42.0,"additionalProperty2":42.0}}}],"delete":{"ids":["string"],"query":"string"},"update":[{"id":"string","name":"string","namespace":"string","users":[{"id":"string","name":"string"}],"kbResource":"string","source":"string","text":"string","type":"document","required":true,"vector":{"modelId":"string","tokens":{"additionalProperty1":42.0,"additionalProperty2":42.0}}}]}'
Request examples
{
  "create": [
    {
      "name": "string",
      "namespace": "string",
      "users": [
        {
          "id": "string",
          "name": "string"
        }
      ],
      "kbResource": "string",
      "source": "string",
      "text": "string",
      "type": "document",
      "required": true,
      "vector": {
        "modelId": "string",
        "tokens": {
          "additionalProperty1": 42.0,
          "additionalProperty2": 42.0
        }
      }
    }
  ],
  "delete": {
    "ids": [
      "string"
    ],
    "query": "string"
  },
  "update": [
    {
      "id": "string",
      "name": "string",
      "namespace": "string",
      "users": [
        {
          "id": "string",
          "name": "string"
        }
      ],
      "kbResource": "string",
      "source": "string",
      "text": "string",
      "type": "document",
      "required": true,
      "vector": {
        "modelId": "string",
        "tokens": {
          "additionalProperty1": 42.0,
          "additionalProperty2": 42.0
        }
      }
    }
  ]
}
Response examples (200)
{
  "attributes": {
    "errors": [
      {
        "err_code": "string",
        "knowledgeBaseEntries": [
          {
            "id": "string",
            "name": "string"
          }
        ],
        "message": "string",
        "statusCode": 42
      }
    ],
    "results": {
      "created": [
        {
          "name": "string",
          "namespace": "string",
          "users": [
            {
              "id": "string",
              "name": "string"
            }
          ],
          "createdAt": "string",
          "createdBy": "string",
          "id": "string",
          "updatedAt": "string",
          "updatedBy": "string",
          "kbResource": "string",
          "source": "string",
          "text": "string",
          "type": "document",
          "required": true,
          "vector": {
            "modelId": "string",
            "tokens": {
              "additionalProperty1": 42.0,
              "additionalProperty2": 42.0
            }
          }
        }
      ],
      "deleted": [
        "string"
      ],
      "skipped": [
        {
          "id": "string",
          "name": "string",
          "skip_reason": "KNOWLEDGE_BASE_ENTRY_NOT_MODIFIED"
        }
      ],
      "updated": [
        {
          "name": "string",
          "namespace": "string",
          "users": [
            {
              "id": "string",
              "name": "string"
            }
          ],
          "createdAt": "string",
          "createdBy": "string",
          "id": "string",
          "updatedAt": "string",
          "updatedBy": "string",
          "kbResource": "string",
          "source": "string",
          "text": "string",
          "type": "document",
          "required": true,
          "vector": {
            "modelId": "string",
            "tokens": {
              "additionalProperty1": 42.0,
              "additionalProperty2": 42.0
            }
          }
        }
      ]
    },
    "summary": {
      "failed": 42,
      "skipped": 42,
      "succeeded": 42,
      "total": 42
    }
  },
  "knowledgeBaseEntriesCount": 42,
  "message": "string",
  "statusCode": 42,
  "success": true
}
Response examples (400)
{
  "error": "string",
  "message": "string",
  "statusCode": 42.0
}










































































































































































Security endpoint management

Interact with and manage endpoints running the Elastic Defend integration.

Get response actions

GET /api/endpoint/action

Get a list of all response actions.

Query parameters

  • query object Required

    Additional properties are allowed.

    Hide query attributes Show query attributes object

Responses

  • 200 application/json

    OK

    Additional properties are allowed.

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












Download a file

GET /api/endpoint/action/{action_id}/file/{file_id}/download

Download a file from an endpoint.

Path parameters

Responses

  • 200 application/json

    OK

    Additional properties are allowed.

GET /api/endpoint/action/{action_id}/file/{file_id}/download
curl \
 --request GET https://localhost:5601/api/endpoint/action/{action_id}/file/{file_id}/download
Response examples (200)
{}




























Get actions state

GET /api/endpoint/action/state

Get a response actions state, which reports whether encryption is enabled.

Responses

  • 200 application/json

    OK

    Hide response attribute Show response attribute object
    • body object Required

      Additional properties are allowed.

      Hide body attribute Show body attribute object
      • data object Required

        Additional properties are allowed.

        Hide data attribute Show data attribute object
GET /api/endpoint/action/state
curl \
 --request GET https://localhost:5601/api/endpoint/action/state
Response examples (200)
{
  "body": {
    "data": {
      "canEncrypt": true
    }
  }
}

















































List asset criticality records

GET /api/asset_criticality/list

List asset criticality records, paging, sorting and filtering as needed.

Query parameters

  • The field to sort by.

    Values are id_value, id_field, criticality_level, or \@timestamp.

  • The order to sort by.

    Values are asc or desc.

  • page integer

    The page number to return.

    Minimum value is 1.

  • per_page integer

    The number of records to return per page.

    Minimum value is 1, maximum value is 1000.

  • kuery string

    The kuery to filter by.

Responses

  • 200 application/json

    Successfully retrieved asset criticality records

    Hide response attributes Show response attributes object
    • page integer Required

      Minimum value is 1.

    • per_page integer Required

      Minimum value is 1, maximum value is 1000.

    • records array[object] Required
      Hide records attributes Show records attributes object

      The deleted record if it existed.

      • id_field string Required

        Values are host.name, user.name, service.name, or related.entity.

      • id_value string Required

        The ID value of the asset.

      • criticality_level string Required

        The criticality level of the asset.

        Values are low_impact, medium_impact, high_impact, or extreme_impact.

      • asset object Required

        Additional properties are allowed.

        Hide asset attribute Show asset attribute object
        • The criticality level of the asset.

          Values are low_impact, medium_impact, high_impact, or extreme_impact.

      • host object

        Additional properties are allowed.

        Hide host attributes Show host attributes object
        • asset object

          Additional properties are allowed.

          Hide asset attribute Show asset attribute object
          • criticality string Required

            The criticality level of the asset.

            Values are low_impact, medium_impact, high_impact, or extreme_impact.

        • name string Required
      • service object

        Additional properties are allowed.

        Hide service attributes Show service attributes object
        • asset object

          Additional properties are allowed.

          Hide asset attribute Show asset attribute object
          • criticality string Required

            The criticality level of the asset.

            Values are low_impact, medium_impact, high_impact, or extreme_impact.

        • name string Required
      • user object

        Additional properties are allowed.

        Hide user attributes Show user attributes object
        • asset object

          Additional properties are allowed.

          Hide asset attribute Show asset attribute object
          • criticality string Required

            The criticality level of the asset.

            Values are low_impact, medium_impact, high_impact, or extreme_impact.

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

        The time the record was created or updated.

    • total integer Required

      Minimum value is 0.

GET /api/asset_criticality/list
curl \
 --request GET https://localhost:5601/api/asset_criticality/list
Response examples (200)
{
  "page": 1,
  "total": 2,
  "records": [
    {
      "host": {
        "name": "my_other_host",
        "asset": {
          "criticality": "medium_impact"
        }
      },
      "asset": {
        "criticality": "medium_impact"
      },
      "id_field": "host.name",
      "id_value": "my_other_host",
      "@timestamp": "2024-08-02T14:40:35.705Z",
      "criticality_level": "medium_impact"
    },
    {
      "host": {
        "name": "my_host",
        "asset": {
          "criticality": "high_impact"
        }
      },
      "asset": {
        "criticality": "high_impact"
      },
      "id_field": "host.name",
      "id_value": "my_host",
      "@timestamp": "2024-08-02T11:15:34.290Z",
      "criticality_level": "high_impact"
    }
  ],
  "per_page": 10
}
































List Entity Store Entities

GET /api/entity_store/entities/list

List entities records, paging, sorting and filtering as needed.

Query parameters

Responses

  • 200 application/json

    Entities returned successfully

    Hide response attributes Show response attributes object
    • inspect object

      Additional properties are allowed.

      Hide inspect attributes Show inspect attributes object
    • page integer Required

      Minimum value is 1.

    • per_page integer Required

      Minimum value is 1, maximum value is 1000.

    • records array[object] Required
      One of:
      Hide attributes Show attributes
      • @timestamp string(date-time)
      • asset object

        Additional properties are allowed.

        Hide asset attribute Show asset attribute object
        • criticality string Required

          The criticality level of the asset.

          Values are low_impact, medium_impact, high_impact, or extreme_impact.

      • entity object Required

        Additional properties are allowed.

        Hide entity attributes Show entity attributes object
      • event object

        Additional properties are allowed.

        Hide event attribute Show event attribute object
      • user object Required

        Additional properties are allowed.

        Hide user attributes Show user attributes object
        • domain array[string]
        • email array[string]
        • full_name array[string]
        • hash array[string]
        • id array[string]
        • name string Required
        • risk object

          Additional properties are allowed.

          Hide risk attributes Show risk attributes object
          • @timestamp string(date-time) Required

            The time at which the risk score was calculated.

          • calculated_level string Required

            Lexical description of the entity's risk.

            Values are Unknown, Low, Moderate, High, or Critical.

          • calculated_score number(double) Required

            The raw numeric value of the given entity's risk score.

          • calculated_score_norm number(double) Required

            The normalized numeric value of the given entity's risk score. Useful for comparing with other entities.

            Minimum value is 0, maximum value is 100.

          • category_1_count number(integer) Required

            The number of risk input documents that contributed to the Category 1 score (category_1_score).

          • category_1_score number(double) Required

            The contribution of Category 1 to the overall risk score (calculated_score). Category 1 contains Detection Engine Alerts.

          • category_2_count number(integer)
          • category_2_score number(double)
          • The criticality level of the asset.

            Values are low_impact, medium_impact, high_impact, or extreme_impact.

          • criticality_modifier number(double)
          • id_field string Required

            The identifier field defining this risk score. Coupled with id_value, uniquely identifies the entity being scored.

          • id_value string Required

            The identifier value defining this risk score. Coupled with id_field, uniquely identifies the entity being scored.

          • inputs array[object] Required

            A list of the highest-risk documents contributing to this risk score. Useful for investigative purposes.

            Hide inputs attributes Show inputs attributes object
            • category string Required

              The risk category of the risk input document.

            • contribution_score number(double)
            • description string Required

              A human-readable description of the risk input document.

            • id string Required

              The unique identifier (_id) of the original source document

            • index string Required

              The unique index (_index) of the original source document

            • risk_score number(double)

              The weighted risk score of the risk input document.

              Minimum value is 0, maximum value is 100.

            • The @timestamp of the risk input document.

          • notes array[string] Required
        • roles array[string]
    • total integer Required

      Minimum value is 0.

GET /api/entity_store/entities/list
curl \
 --request GET https://localhost:5601/api/entity_store/entities/list?entity_types=user
Response examples (200)
{
  "inspect": {
    "dsl": [
      "string"
    ],
    "response": [
      "string"
    ]
  },
  "page": 42,
  "per_page": 42,
  "records": [
    {
      "@timestamp": "2025-05-04T09:42:00+00:00",
      "asset": {
        "criticality": "low_impact"
      },
      "entity": {
        "name": "string",
        "source": "string"
      },
      "event": {
        "ingested": "2025-05-04T09:42:00+00:00"
      },
      "user": {
        "domain": [
          "string"
        ],
        "email": [
          "string"
        ],
        "full_name": [
          "string"
        ],
        "hash": [
          "string"
        ],
        "id": [
          "string"
        ],
        "name": "string",
        "risk": {
          "@timestamp": "2017-07-21T17:32:28Z",
          "calculated_level": "Critical",
          "calculated_score": 42.0,
          "calculated_score_norm": 42.0,
          "category_1_count": 42.0,
          "category_1_score": 42.0,
          "category_2_count": 42.0,
          "category_2_score": 42.0,
          "criticality_level": "low_impact",
          "criticality_modifier": 42.0,
          "id_field": "host.name",
          "id_value": "example.host",
          "inputs": [
            {
              "category": "category_1",
              "contribution_score": 42.0,
              "description": "Generated from Detection Engine Rule: Malware Prevention Alert",
              "id": "91a93376a507e86cfbf282166275b89f9dbdb1f0be6c8103c6ff2909ca8e1a1c",
              "index": ".internal.alerts-security.alerts-default-000001",
              "risk_score": 42.0,
              "timestamp": "2017-07-21T17:32:28Z"
            }
          ],
          "notes": [
            "string"
          ]
        },
        "roles": [
          "string"
        ]
      }
    }
  ],
  "total": 42
}

Get the status of the Entity Store

GET /api/entity_store/status

Query parameters

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

Responses

  • 200 application/json

    Successful response

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

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

      • error object

        Additional properties are allowed.

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

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

      • status string Required

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

      • timeout string

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

      • type string Required

        Values are user, host, service, or universal.

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

          Values are green, yellow, red, or unknown.

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

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

    • status string Required

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

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





























Delete an exception list

DELETE /api/exception_lists

Delete an exception list using the id or list_id field.

Query parameters

  • id string(nonempty)

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

    Minimum length is 1.

  • list_id string(nonempty)

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

    Minimum length is 1.

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

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

    Values are agnostic or single. Default value is single.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • _version string

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

    • created_at string(date-time) Required

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

    • description string Required

      Describes the exception list.

    • id string(nonempty) Required

      Exception list's identifier.

      Minimum length is 1.

    • immutable boolean Required
    • list_id string(nonempty) Required

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

      Minimum length is 1.

    • meta object

      Placeholder for metadata about the list container.

      Additional properties are allowed.

    • name string Required

      The name of the exception list.

    • namespace_type string Required

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

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

      Values are agnostic or single. Default value is single.

    • os_types array[string]

      Use this field to specify the operating system.

      Values are linux, macos, or windows.

    • tags array[string]

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

    • tie_breaker_id string Required

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

    • type string Required

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

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

    • updated_at string(date-time) Required

      Autogenerated date of last object update.

    • updated_by string Required

      Autogenerated value - user that last updated object.

    • version integer Required

      The document version, automatically increasd on updates.

      Minimum value is 1.

  • 400 application/json

    Invalid input data response

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

    Unsuccessful authentication response

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

    Not enough privileges response

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

    Exception list not found response

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

    Internal server error response

    Hide response attributes Show response attributes object
DELETE /api/exception_lists
curl \
 --request DELETE https://localhost:5601/api/exception_lists
Response examples (200)
{
  "id": "9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85",
  "name": "Sample Detection Exception List",
  "tags": [
    "malware"
  ],
  "type": "detection",
  "list_id": "simple_list",
  "version": 1,
  "_version": "WzIsMV0=",
  "os_types": [
    "linux"
  ],
  "immutable": false,
  "created_at": "2025-01-07T19:34:27.942Z",
  "created_by": "elastic",
  "updated_at": "2025-01-07T19:34:27.942Z",
  "updated_by": "elastic",
  "description": "This is a sample detection type exception list.",
  "namespace_type": "single",
  "tie_breaker_id": "78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3"
}
Response examples (400)
{
  "error": "Bad Request",
  "message": "[request query]: namespace_type.0: Invalid enum value. Expected 'agnostic' | 'single', received 'blob'",
  "statusCode": 400
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403)
{
  "error": "Forbidden",
  "message": "API [DELETE /api/exception_lists?list_id=simple_list&namespace_type=single] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}
Response examples (404)
{
  "message": "exception list list_id: \"foo\" does not exist",
  "status_code": 404
}
Response examples (500)
{
  "message": "Internal Server Error",
  "status_code": 500
}

Duplicate an exception list

POST /api/exception_lists/_duplicate

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.

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

      Values are linux, macos, or windows.

    • tags array[string]

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

    • tie_breaker_id string Required

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

    • type string Required

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

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

    • updated_at string(date-time) Required

      Autogenerated date of last object update.

    • updated_by string Required

      Autogenerated value - user that last updated object.

    • version integer Required

      The document version, automatically increasd on updates.

      Minimum value is 1.

  • 400 application/json

    Invalid input data response

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

    Unsuccessful authentication response

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

    Not enough privileges response

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

    Exception list not found

    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 https://localhost:5601/api/exception_lists/_duplicate?list_id=simple_list&namespace_type=agnostic&include_expired_exceptions=true
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
}
















Update an exception list item

PUT /api/exception_lists/items

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

application/json

Body Required

Exception list item's properties

  • _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]

    Default value is [] (empty).

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

      A string that does not contain only whitespace characters

      Minimum length is 1.

    • id string(nonempty)

      A string that does not contain only whitespace characters

      Minimum length is 1.

  • description string Required

    Describes the exception list.

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

    Exception's identifier.

    Minimum length is 1.

  • item_id string(nonempty)

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

    Minimum length is 1.

  • list_id string(nonempty)

    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.

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

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

    Values are agnostic or single. Default value is single.

  • os_types array[string]

    Use this field to specify the operating system.

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

  • tags array[string(nonempty)]

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

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

  • type string Required

    Value is simple.

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • _version string

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

    • comments array[object] Required

      Array of comment fields:

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

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • created_at string(date-time) Required

        Autogenerated date of object creation.

      • created_by string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • id string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • updated_at string(date-time)

        Autogenerated date of last object update.

      • updated_by string(nonempty)

        A string that does not contain only whitespace characters

        Minimum length is 1.

    • created_at string(date-time) Required

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

    • description string Required

      Describes the exception list.

    • entries array[object] Required
      Any of:
      Hide attributes Show attributes
      • field string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

      • operator string Required

        Values are excluded or included.

      • type string Required Discriminator

        Value is match.

      • value string(nonempty) Required

        A string that does not contain only whitespace characters

        Minimum length is 1.

    • expire_time string(date-time)

      The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.

    • id string(nonempty) Required

      Exception's identifier.

      Minimum length is 1.

    • item_id string(nonempty) Required

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

      Minimum length is 1.

    • list_id string(nonempty) Required

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

      Minimum length is 1.

    • meta object

      Additional properties are allowed.

    • name string(nonempty) Required

      Exception list name.

      Minimum length is 1.

    • namespace_type string Required

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

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

      Values are agnostic or single. Default value is single.

    • os_types array[string]

      Use this field to specify the operating system.

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

    • tags array[string(nonempty)]

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

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

    • tie_breaker_id string Required

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

    • type string Required

      Value is simple.

    • updated_at string(date-time) Required

      Autogenerated date of last object update.

    • updated_by string Required

      Autogenerated value - user that last updated object.

  • 400 application/json

    Invalid input data response

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

    Unsuccessful authentication response

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

    Not enough privileges response

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

    Exception list item not found response

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

    Internal server error response

    Hide response attributes Show response attributes object
PUT /api/exception_lists/items
curl \
 --request PUT https://localhost:5601/api/exception_lists/items \
 --header "Content-Type: application/json" \
 --data '{"name":"Updated name","tags":[],"type":"simple","entries":[{"type":"match","field":"host.name","value":"rock01","operator":"included"}],"item_id":"simple_list_item","comments":[],"description":"Updated description","namespace_type":"single"}'
Request example
{
  "name": "Updated name",
  "tags": [],
  "type": "simple",
  "entries": [
    {
      "type": "match",
      "field": "host.name",
      "value": "rock01",
      "operator": "included"
    }
  ],
  "item_id": "simple_list_item",
  "comments": [],
  "description": "Updated description",
  "namespace_type": "single"
}
Response examples (200)
{
  "id": "459c5e7e-f8b2-4f0b-b136-c1fc702f72da",
  "name": "Updated name",
  "tags": [],
  "type": "simple",
  "entries": [
    {
      "type": "match",
      "field": "host.name",
      "value": "rock01",
      "operator": "included"
    }
  ],
  "item_id": "simple_list_item",
  "list_id": "simple_list",
  "_version": "WzEyLDFd",
  "comments": [],
  "os_types": [],
  "created_at": "2025-01-07T21:12:25.512Z",
  "created_by": "elastic",
  "updated_at": "2025-01-07T21:34:50.233Z",
  "updated_by": "elastic",
  "description": "Updated description",
  "namespace_type": "single",
  "tie_breaker_id": "ad0754ff-7b19-49ca-b73e-e6aff6bfa2d0"
}
Response examples (400)
{
  "error": "Bad Request",
  "message": "[request body]: item_id: Expected string, received number",
  "statusCode": 400
}
Response examples (401)
{
  "error": "Unauthorized",
  "message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}
Response examples (403)
{
  "error": "Forbidden",
  "message": "API [PUT /api/exception_lists/items] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]",
  "statusCode": 403
}
Response examples (404)
{
  "message": "exception list item item_id: \\\"foo\\\" does not exist",
  "status_code": 404
}
Response examples (500)
{
  "message": "Internal Server Error",
  "status_code": 500
}








Get exception list items

GET /api/exception_lists/items/_find

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

Query parameters

  • list_id array[string(nonempty)] Required

    The list_ids of the items to fetch.

    Minimum length of each is 1.

  • filter array[string(nonempty)]

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

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

  • namespace_type array[string]

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

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

  • page integer

    The page number to return

    Minimum value is 0.

  • per_page integer

    The number of exception list items to return per page

    Minimum value is 0.

  • sort_field string(nonempty)

    Determines which field is used to sort the results.

    Minimum length is 1.

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

    Values are desc or asc.

Responses

  • 200 application/json

    Successful response

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

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

      • comments array[object] Required

        Array of comment fields:

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

          A string that does not contain only whitespace characters

          Minimum length is 1.

        • created_at string(date-time) Required

          Autogenerated date of object creation.

        • created_by string(nonempty) Required

          A string that does not contain only whitespace characters

          Minimum length is 1.

        • id string(nonempty) Required

          A string that does not contain only whitespace characters

          Minimum length is 1.

        • updated_at string(date-time)

          Autogenerated date of last object update.

        • updated_by string(nonempty)

          A string that does not contain only whitespace characters

          Minimum length is 1.

      • created_at string(date-time) Required

        Autogenerated date of object creation.

      • created_by string Required

        Autogenerated value - user that created object.

      • description string Required

        Describes the exception list.

      • entries array[object] Required
        Any of:
        Hide attributes Show attributes
        • field string(nonempty) Required

          A string that does not contain only whitespace characters

          Minimum length is 1.

        • operator string Required

          Values are excluded or included.

        • type string Required Discriminator

          Value is match.

        • value string(nonempty) Required

          A string that does not contain only whitespace characters

          Minimum length is 1.

      • expire_time string(date-time)

        The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.

      • id string(nonempty) Required

        Exception's identifier.

        Minimum length is 1.

      • item_id string(nonempty) Required

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

        Minimum length is 1.

      • list_id string(nonempty) Required

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

        Minimum length is 1.

      • meta object

        Additional properties are allowed.

      • name string(nonempty) Required

        Exception list name.

        Minimum length is 1.

      • namespace_type string Required

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

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

        Values are agnostic or single. Default value is single.

      • os_types array[string]

        Use this field to specify the operating system.

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

      • tags array[string(nonempty)]

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

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

      • tie_breaker_id string Required

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

      • type string Required

        Value is simple.

      • updated_at string(date-time) Required

        Autogenerated date of last object update.

      • updated_by string Required

        Autogenerated value - user that last updated object.

    • page integer Required

      Minimum value is 1.

    • per_page integer Required

      Minimum value is 1.

    • pit string
    • total integer Required

      Minimum value is 0.

  • 400 application/json

    Invalid input data response

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

    Unsuccessful authentication response

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

    Not enough privileges response

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

    Exception list not found response

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

    Internal server error response

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









































































Import value list items

POST /api/lists/items/_import

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

You can import items to a new or existing list.

Query parameters

  • list_id string(nonempty)

    List's id.

    Required when importing to an existing list.

    Minimum length is 1.

  • type string

    Type of the importing list.

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

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

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

    • (?<value>.+) - Single value item types, such as ip, long, date, keyword, and text.
    • (?<gte>.+)-(?<lte>.+)|(?<value>.+) - Range value item types, such as date_range, ip_range, double_range, float_range, integer_range, and long_range.
  • Determines how retrieved list item values are presented. By default list items are presented using these Handelbar expressions:

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

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

    Values are true, false, or wait_for.

multipart/form-data

Body Required

  • file string(binary)

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

Responses

  • 200 application/json

    Successful response

    Hide response attributes Show response attributes object
    • _version string

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

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

      Autogenerated date of object creation.

    • created_by string Required

      Autogenerated value - user that created object.

    • description string(nonempty) Required

      Describes the value list.

      Minimum length is 1.

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

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

      Value list's identifier.

      Minimum length is 1.

    • immutable boolean Required
    • meta object

      Placeholder for metadata about the value list.

      Additional properties are allowed.

    • name string(nonempty) Required

      Value list's name.

      Minimum length is 1.

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

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

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

    • type string Required

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

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

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

    • updated_at string(date-time) Required

      Autogenerated date of last object update.

    • updated_by string Required

      Autogenerated value - user that last updated object.

    • version integer Required

      The document version number.

      Minimum value is 1.

  • 400 application/json

    Invalid input data response

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

    Unsuccessful authentication response

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

    Not enough privileges response

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

    List with specified list_id does not exist response

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

    Internal server error response

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