Search for annotations

Get the rule types

GET /api/alerting/rule_types

If you have read privileges for one or more Kibana features, the API response contains information about the appropriate rule types. For example, there are rule types associated with the Management > Stack Rules feature, Analytics > Discover and Machine Learning features, Observability features, and Security features. To get rule types associated with the Stack Monitoring feature, use the monitoring_user built-in role.

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- action_groups array[object]
  
  An explicit list of groups for which the rule type can schedule actions, each with the action group's unique ID and human readable name. Rule actions validation uses this configuration to ensure that groups are valid.
  
  Hide action_groups attributes Show action_groups attributes object
  
  id string
  
  name string
- action_variables object
  
  A list of action variables that the rule type makes available via context and state in action parameter templates, and a short human readable description. When you create a rule in Kibana, it uses this information to prompt you for these variables in action parameter editors.
  
  Hide action_variables attributes Show action_variables attributes object
  
  context array[object]
  
  Hide context attributes Show context attributes object
  
  description string
  
  name string
  
  useWithTripleBracesInTemplates boolean
  
  params array[object]
  
  Hide params attributes Show params attributes object
  
  description string
  
  name string
  
  state array[object]
  
  Hide state attributes Show state attributes object
  
  description string
  
  name string
- alerts object
  
  Details for writing alerts as data documents for this rule type.
  
  Hide alerts attributes Show alerts attributes object
  
  context string
  
  The namespace for this rule type.
  
  Values are ml.anomaly-detection, observability.apm, observability.logs, observability.metrics, observability.slo, observability.threshold, observability.uptime, security, or stack.
  
  dynamic string
  
  Indicates whether new fields are added dynamically.
  
  Values are false, runtime, strict, or true.
  
  isSpaceAware boolean
  
  Indicates whether the alerts are space-aware. If true, space-specific alert indices are used.
  
  mappings object
  
  Hide mappings attribute Show mappings attribute object
  
  fieldMap object
  
  Mapping information for each field supported in alerts as data documents for this rule type. For more information about mapping parameters, refer to the Elasticsearch documentation.
  
  Hide fieldMap attribute Show fieldMap attribute object
  
  * object Additional properties
  
  Hide * attributes Show * attributes object
  
  array boolean
  
  Indicates whether the field is an array.
  
  dynamic boolean
  
  Indicates whether it is a dynamic field mapping.
  
  format string
  
  Indicates the format of the field. For example, if the type is date_range, the format can be epoch_millis||strict_date_optional_time.
  
  ignore_above integer
  
  Specifies the maximum length of a string field. Longer strings are not indexed or stored.
  
  index boolean
  
  Indicates whether field values are indexed.
  
  path string
  
  TBD
  
  properties object
  
  Details about the object properties. This property is applicable when type is object.
  
  Hide properties attribute Show properties attribute object
  
  * object Additional properties
  
  Hide * attribute Show * attribute object
  
  type string
  
  The data type for each object property.
  
  required boolean
  
  Indicates whether the field is required.
  
  scaling_factor integer
  
  The scaling factor to use when encoding values. This property is applicable when type is scaled_float. Values will be multiplied by this factor at index time and rounded to the closest long value.
  
  type string
  
  Specifies the data type for the field.
  
  secondaryAlias string
  
  A secondary alias. It is typically used to support the signals alias for detection rules.
  
  shouldWrite boolean
  
  Indicates whether the rule should write out alerts as data.
  
  useEcs boolean
  
  Indicates whether to include the ECS component template for the alerts.
  
  useLegacyAlerts boolean
  
  Indicates whether to include the legacy component template for the alerts.
  
  Default value is false.
- authorized_consumers object
  
  The list of the plugins IDs that have access to the rule type.
  
  Hide authorized_consumers attributes Show authorized_consumers attributes object
  
  alerts object
  
  Hide alerts attributes Show alerts attributes object
  
  all boolean
  
  read boolean
  
  apm object
  
  Hide apm attributes Show apm attributes object
  
  all boolean
  
  read boolean
  
  discover object
  
  Hide discover attributes Show discover attributes object
  
  all boolean
  
  read boolean
  
  infrastructure object
  
  Hide infrastructure attributes Show infrastructure attributes object
  
  all boolean
  
  read boolean
  
  logs object
  
  Hide logs attributes Show logs attributes object
  
  all boolean
  
  read boolean
  
  ml object
  
  Hide ml attributes Show ml attributes object
  
  all boolean
  
  read boolean
  
  monitoring object
  
  Hide monitoring attributes Show monitoring attributes object
  
  all boolean
  
  read boolean
  
  siem object
  
  Hide siem attributes Show siem attributes object
  
  all boolean
  
  read boolean
  
  slo object
  
  Hide slo attributes Show slo attributes object
  
  all boolean
  
  read boolean
  
  stackAlerts object
  
  Hide stackAlerts attributes Show stackAlerts attributes object
  
  all boolean
  
  read boolean
  
  uptime object
  
  Hide uptime attributes Show uptime attributes object
  
  all boolean
  
  read boolean
- category string
  
  The rule category, which is used by features such as category-specific maintenance windows.
  
  Values are management, observability, or securitySolution.
- default_action_group_id string
  
  The default identifier for the rule type group.
- does_set_recovery_context boolean
  
  Indicates whether the rule passes context variables to its recovery action.
- enabled_in_license boolean
  
  Indicates whether the rule type is enabled or disabled based on the subscription.
- has_alerts_mappings boolean
  
  Indicates whether the rule type has custom mappings for the alert data.
- has_fields_for_a_a_d boolean
- id string
  
  The unique identifier for the rule type.
- is_exportable boolean
  
  Indicates whether the rule type is exportable in Stack Management > Saved Objects.
- minimum_license_required string
  
  The subscriptions required to use the rule type.
- name string
  
  The descriptive name of the rule type.
- producer string
  
  An identifier for the application that produces this rule type.
- recovery_action_group object
  
  An action group to use when an alert goes from an active state to an inactive one.
  
  Hide recovery_action_group attributes Show recovery_action_group attributes object
  
  id string
  
  name string
- rule_task_timeout string
401 application/json

Authorization information is missing or invalid.
Hide response attributes Show response attributes object
- error string
  
  Value is Unauthorized.
- message string
- statusCode integer
  
  Value is 401.

GET /api/alerting/rule_types

curl \
 --request GET 'https://localhost:5601/api/alerting/rule_types' \
 --header "Authorization: $API_KEY"

Response examples (200)

[
  {
    "id": "xpack.ml.anomaly_detection_alert",
    "name": "Anomaly detection alert",
    "alerts": {
      "context": "ml.anomaly-detection",
      "mappings": {
        "fieldMap": {
          "kibana.alert.job_id": {
            "type": "keyword",
            "array": false,
            "required": true
          },
          "kibana.alert.is_interim": {
            "type": "boolean",
            "array": false,
            "required": false
          },
          "kibana.alert.top_records": {
            "type": "object",
            "array": true,
            "dynamic": false,
            "required": false,
            "properties": {
              "actual": {
                "type": "double"
              },
              "job_id": {
                "type": "keyword"
              },
              "typical": {
                "type": "double"
              },
              "function": {
                "type": "keyword"
              },
              "timestamp": {
                "type": "date"
              },
              "field_name": {
                "type": "keyword"
              },
              "is_interim": {
                "type": "boolean"
              },
              "record_score": {
                "type": "double"
              },
              "by_field_name": {
                "type": "keyword"
              },
              "by_field_value": {
                "type": "keyword"
              },
              "detector_index": {
                "type": "integer"
              },
              "over_field_name": {
                "type": "keyword"
              },
              "over_field_value": {
                "type": "keyword"
              },
              "initial_record_score": {
                "type": "double"
              },
              "partition_field_name": {
                "type": "keyword"
              },
              "partition_field_value": {
                "type": "keyword"
              }
            }
          },
          "kibana.alert.anomaly_score": {
            "type": "double",
            "array": false,
            "required": false
          },
          "kibana.alert.top_influencers": {
            "type": "object",
            "array": true,
            "dynamic": false,
            "required": false,
            "properties": {
              "job_id": {
                "type": "keyword"
              },
              "timestamp": {
                "type": "date"
              },
              "is_interim": {
                "type": "boolean"
              },
              "influencer_score": {
                "type": "double"
              },
              "influencer_field_name": {
                "type": "keyword"
              },
              "influencer_field_value": {
                "type": "keyword"
              },
              "initial_influencer_score": {
                "type": "double"
              }
            }
          },
          "kibana.alert.anomaly_timestamp": {
            "type": "date",
            "array": false,
            "required": false
          }
        }
      },
      "shouldWrite": true
    },
    "category": "management",
    "producer": "ml",
    "action_groups": [
      {
        "id": "anomaly_score_match",
        "name": "Anomaly score matched the condition"
      },
      {
        "id": "recovered",
        "name": "Recovered"
      }
    ],
    "is_exportable": true,
    "action_variables": {
      "state": [],
      "params": [],
      "context": [
        {
          "name": "timestamp",
          "description": "The bucket timestamp of the anomaly"
        },
        {
          "name": "timestampIso8601",
          "description": "The bucket time of the anomaly in ISO8601 format"
        },
        {
          "name": "jobIds",
          "description": "List of job IDs that triggered the alert"
        },
        {
          "name": "message",
          "description": "Alert info message"
        },
        {
          "name": "isInterim",
          "description": "Indicate if top hits contain interim results"
        },
        {
          "name": "score",
          "description": "Anomaly score at the time of the notification action"
        },
        {
          "name": "topRecords",
          "description": "Top records"
        },
        {
          "name": "topInfluencers",
          "description": "Top influencers"
        },
        {
          "name": "anomalyExplorerUrl",
          "description": "URL to open in the Anomaly Explorer",
          "useWithTripleBracesInTemplates": true
        }
      ]
    },
    "rule_task_timeout": "5m",
    "enabled_in_license": true,
    "has_alerts_mappings": true,
    "authorized_consumers": {
      "ml": {
        "all": true,
        "read": true
      },
      "apm": {
        "all": true,
        "read": true
      },
      "slo": {
        "all": true,
        "read": true
      },
      "logs": {
        "all": true,
        "read": true
      },
      "siem": {
        "all": true,
        "read": true
      },
      "alerts": {
        "all": true,
        "read": true
      },
      "uptime": {
        "all": true,
        "read": true
      },
      "discover": {
        "all": true,
        "read": true
      },
      "monitoring": {
        "all": true,
        "read": true
      },
      "stackAlerts": {
        "all": true,
        "read": true
      },
      "infrastructure": {
        "all": true,
        "read": true
      }
    },
    "has_fields_for_a_a_d": false,
    "recovery_action_group": {
      "id": "recovered",
      "name": "Recovered"
    },
    "default_action_group_id": "anomaly_score_match",
    "minimum_license_required": "platinum",
    "does_set_recovery_context": true
  },
  {
    "id": "xpack.ml.anomaly_detection_jobs_health",
    "name": "Anomaly detection jobs health",
    "category": "management",
    "producer": "ml",
    "action_groups": [
      {
        "id": "anomaly_detection_realtime_issue",
        "name": "Issue detected"
      },
      {
        "id": "recovered",
        "name": "Recovered"
      }
    ],
    "is_exportable": true,
    "action_variables": {
      "state": [],
      "params": [],
      "context": [
        {
          "name": "results",
          "description": "Results of the rule execution"
        },
        {
          "name": "message",
          "description": "Alert info message"
        }
      ]
    },
    "rule_task_timeout": "5m",
    "enabled_in_license": true,
    "has_alerts_mappings": false,
    "authorized_consumers": {
      "ml": {
        "all": true,
        "read": true
      },
      "apm": {
        "all": true,
        "read": true
      },
      "slo": {
        "all": true,
        "read": true
      },
      "logs": {
        "all": true,
        "read": true
      },
      "siem": {
        "all": true,
        "read": true
      },
      "alerts": {
        "all": true,
        "read": true
      },
      "uptime": {
        "all": true,
        "read": true
      },
      "discover": {
        "all": true,
        "read": true
      },
      "monitoring": {
        "all": true,
        "read": true
      },
      "stackAlerts": {
        "all": true,
        "read": true
      },
      "infrastructure": {
        "all": true,
        "read": true
      }
    },
    "has_fields_for_a_a_d": false,
    "recovery_action_group": {
      "id": "recovered",
      "name": "Recovered"
    },
    "default_action_group_id": "anomaly_detection_realtime_issue",
    "minimum_license_required": "platinum",
    "does_set_recovery_context": true
  }
]

Response examples (401)

{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}

Update the API key for a rule

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

Api key auth Basic auth

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

The identifier for the rule.

Responses

204

Indicates a successful call.
400

Indicates an invalid schema or parameters.
403

Indicates that this call is forbidden.
404

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

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

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

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

Create or update agent configuration

PUT /api/apm/settings/agent-configuration

Api key auth Basic auth

Headers

elastic-api-version string Required

The version of the API to use

Value is 2023-10-31. Default value is 2023-10-31.
kbn-xsrf string Required

A required header to protect against CSRF attacks

Query parameters

overwrite boolean

If the config exists ?overwrite=true is required

application/json

Body Required

agent_name string

Agent name
service object Required

Service
Hide service attributes Show service attributes object
- environment string
  
  Environment
- name string
  
  Name
settings object Required

Agent configuration settings
Hide settings attribute Show settings attribute object
- * string Additional properties

Responses

200 application/json

Successful response

Additional properties are NOT allowed.
400 application/json

Bad Request response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
401 application/json

Unauthorized response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
403 application/json

Forbidden response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
404 application/json

Not found response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code

PUT /api/apm/settings/agent-configuration

curl \
 --request PUT 'https://localhost:5601/api/apm/settings/agent-configuration' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "elastic-api-version: 2023-10-31" \
 --header "kbn-xsrf: true" \
 --data '{"agent_name":"string","service":{"environment":"prod","name":"node"},"settings":{"additionalProperty1":"string","additionalProperty2":"string"}}'

Request examples

# Headers
elastic-api-version: 2023-10-31
kbn-xsrf: true

# Payload
{
  "agent_name": "string",
  "service": {
    "environment": "prod",
    "name": "node"
  },
  "settings": {
    "additionalProperty1": "string",
    "additionalProperty2": "string"
  }
}

Response examples (200)

{}

Response examples (400)

{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 400
}

Response examples (401)

{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}

Response examples (403)

{
  "error": "Forbidden",
  "message": "string",
  "statusCode": 403
}

Response examples (404)

{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 404
}

Get single agent configuration

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

Api key auth Basic auth

Headers

elastic-api-version string Required

The version of the API to use

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

Query parameters

name string

Service name
environment string

Service environment

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- id string Required
- @timestamp number Required
  
  Timestamp
- agent_name string
  
  Agent name
- applied_by_agent boolean
  
  Applied by agent
- etag string Required
  
  Etag
- service object Required
  
  Service
  
  Hide service attributes Show service attributes object
  
  environment string
  
  Environment
  
  name string
  
  Name
- 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
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
401 application/json

Unauthorized response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
404 application/json

Not found response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code

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

curl \
 --request GET 'https://localhost:5601/api/apm/settings/agent-configuration/view' \
 --header "Authorization: $API_KEY" \
 --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
}

GET /api/apm/services/{serviceName}/annotation/search

Api key auth Basic auth

Search for annotations related to a specific service.

Headers

elastic-api-version string Required

The version of the API to use

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

Path parameters

serviceName string Required

The name of the service

Query parameters

environment string

The environment to filter annotations by
start string

The start date for the search
end string

The end date for the search

Responses

200 application/json

Successful response
Hide response attribute Show response attribute object
- annotations array[object]
  
  Annotations
  
  Hide annotations attributes Show annotations attributes object
  
  @timestamp number
  
  id string
  
  text string
  
  type string
  
  Value is version.
400 application/json

Bad Request response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
401 application/json

Unauthorized response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code
500 application/json

Internal Server Error response
Hide response attributes Show response attributes object
- error string
  
  Error type
- message string
  
  Error message
- statusCode number
  
  Error status code

GET /api/apm/services/{serviceName}/annotation/search

curl \
 --request GET 'https://localhost:5601/api/apm/services/{serviceName}/annotation/search' \
 --header "Authorization: $API_KEY" \
 --header "elastic-api-version: 2023-10-31"

Response examples (200)

{
  "annotations": [
    {
      "@timestamp": 42.0,
      "id": "string",
      "text": "string",
      "type": "version"
    }
  ]
}

Response examples (400)

{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 400
}

Response examples (401)

{
  "error": "Unauthorized",
  "message": "string",
  "statusCode": 401
}

Response examples (500)

{
  "error": "Internal Server Error",
  "message": "string",
  "statusCode": 500
}