Tag an alert Generally available; added in 9.6.0

POST /api/alerting/v2/alerts/{id}/_tag

Spaces method and path for this operation:

post /s/{space_id}/api/alerting/v2/alerts/{id}/_tag

Refer to Spaces for more information.

Create an action for a specific alert.

[Required authorization] Route required privileges: manage_alerting-v2-alerts.

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

    Identifier of the alert to apply the action to.

    Minimum length is 1, maximum length is 150.

application/json

Body

  • tags array[string] | null Required

    Replaces the alert's tags. Send null to clear them. An empty array is rejected.

    At least 1 but not more than 20 elements. Minimum length of each is 1, maximum length of each is 128.

Responses

  • 204

    Indicates the action was created.

  • 400 application/json

    Indicates an invalid schema or parameters.

    Hide response attributes Show response attributes object
    • code string Required

      Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.

    • details object

      Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.

      Additional properties are allowed.

    • error string Required

      A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.

    • message string Required

      A readable explanation of the error. The wording can change without notice. Do not parse this field.

  • 401 application/json

    Indicates the request was not authenticated.

    Hide response attributes Show response attributes object
    • code string Required

      Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.

    • details object

      Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.

      Additional properties are allowed.

    • error string Required

      A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.

    • message string Required

      A readable explanation of the error. The wording can change without notice. Do not parse this field.

  • 403 application/json

    Indicates the user does not have the required privileges to perform the request.

    Hide response attributes Show response attributes object
    • code string Required

      Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.

    • details object

      Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.

      Additional properties are allowed.

    • error string Required

      A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.

    • message string Required

      A readable explanation of the error. The wording can change without notice. Do not parse this field.

  • 404 application/json

    Indicates the alert was not found.

    Hide response attributes Show response attributes object
    • code string Required

      Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.

    • details object

      Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.

      Additional properties are allowed.

    • error string Required

      A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.

    • message string Required

      A readable explanation of the error. The wording can change without notice. Do not parse this field.

  • 409 application/json

    Indicates the alert already carries exactly the requested tags.

    Hide response attributes Show response attributes object
    • code string Required

      Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.

    • details object

      Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.

      Additional properties are allowed.

    • error string Required

      A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.

    • message string Required

      A readable explanation of the error. The wording can change without notice. Do not parse this field.

  • 500 application/json

    Indicates an unexpected server-side error.

    Hide response attributes Show response attributes object
    • code string Required

      Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.

    • details object

      Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.

      Additional properties are allowed.

    • error string Required

      A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.

    • message string Required

      A readable explanation of the error. The wording can change without notice. Do not parse this field.

  • 503 application/json

    Indicates the alerting engine is disabled by the alerting:v2:enabled advanced setting.

    Hide response attributes Show response attributes object
    • code string Required

      Stable error code you can branch on, for example INVALID_SCHEDULE or RULE_ALREADY_EXISTS.

    • details object

      Optional structured context whose keys depend on code. Identifier keys such as rule_id, action_policy_id and group_hash are stable, permanent public identifiers. On a 400 request-validation error, details.source (params, query, or body) names the failing part and is the only guaranteed key. The sibling details.errors may change. Do not branch on it.

      Additional properties are allowed.

    • error string Required

      A short human-readable summary of the error category (e.g., "Not Found", "Bad Request"). Subject to change without notice. Do not parse or rely on its content.

    • message string Required

      A readable explanation of the error. The wording can change without notice. Do not parse this field.

POST /api/alerting/v2/alerts/{id}/_tag
curl \
 --request POST 'https://localhost:5601/api/alerting/v2/alerts/{id}/_tag' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{
  "tags": [
    "production",
    "investigating"
  ]
}'
Request example
{
  "tags": [
    "production",
    "investigating"
  ]
}
Response examples (400)
{
  "code": "BAD_REQUEST",
  "details": {
    "errors": {
      "id": [
        "Required"
      ]
    }
  },
  "error": "Bad Request",
  "message": "id: Required"
}
Response examples (401)
{
  "code": "UNAUTHORIZED",
  "error": "Unauthorized",
  "message": "Authentication required to access this API."
}
Response examples (403)
{
  "code": "FORBIDDEN",
  "error": "Forbidden",
  "message": "The current user does not have the required privileges for this request."
}
Response examples (404)
{
  "code": "ALERT_NOT_FOUND",
  "details": {
    "alert_id": "alert-1"
  },
  "error": "Not Found",
  "message": "Alert with alert_id [alert-1] not found"
}
Response examples (409)
{
  "code": "ALERT_ACTION_NO_OP",
  "details": {
    "action_type": "tag",
    "alert_id": "alert-1",
    "group_hash": "98058cb569017ecb6b08b554ecbcb2524ff7dd8971828f4f2e5939c1e6667e56"
  },
  "error": "Conflict",
  "message": "[alert-1] already has these tags."
}
Response examples (500)
{
  "code": "INTERNAL_SERVER_ERROR",
  "error": "Internal Server Error",
  "message": "An unexpected error occurred."
}
Response examples (503)
{
  "code": "ALERTING_DISABLED",
  "error": "Service Unavailable",
  "message": "Alerting is disabled."
}