Version: 1.3

Managing alerts

Overview

Beyond receiving and querying alerts, ToBeAlert provides endpoints to change an alert's status, apply actions, manage tags and attributes, add notes, and delete alerts.

Authorization: Key YOUR_API_KEY_HERE

Change alert status

PUT /api/alert/<alert_id>/status
Content-Type: application/json
Authorization: Key YOUR_API_KEY

Manually sets the status of an alert. Requires write:alerts scope.

Path parameters

Parameter	Description
`alert_id`	The ID of the alert to update

Request body

Field	Type	Required	Description
`status`	String	Yes	New status to assign
`text`	String	No	Optional comment explaining the change
`timeout`	Integer	No	Override the alert timeout (seconds)

Supported status values

Status	Description
`open`	Alert is active and unacknowledged
`ack`	Alert has been acknowledged
`closed`	Alert has been manually closed
`expired`	Alert has timed out
`shelved`	Alert is temporarily suppressed

Example

Acknowledge an alert with a comment

Bash
Python

curl -X PUT "http://your-tobealert.com:9000/api/alert/ALERT_ID/status" \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_API_KEY" \
  -d '{
         "status": "ack",
         "text": "Investigating the issue on web-01"
     }'

import requests

response = requests.put(
    "http://your-tobealert.com:9000/api/alert/ALERT_ID/status",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Key YOUR_API_KEY"
    },
    json={
        "status": "ack",
        "text": "Investigating the issue on web-01"
    }
)

if response.status_code in [200, 201]:
    print("Request successful")
    print(response.json())
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Response

{
  "status": "ok"
}

Errors

Code	Reason
`400`	Missing or invalid `status` field, or transition rejected by policy
`404`	Alert not found

Effects are released

Setting a cause alert to closed or expired releases its effects: each one gets causeId: null and suppressed: false, plus a history entry by system. Changing the status of an effect does not touch its cause. See Sending alerts — Cause and effect.

Apply actions to alerts

PUT /api/alert/action
Content-Type: application/json
Authorization: Key YOUR_API_KEY

Applies operator actions (e.g. acknowledge, close, watch) to one or more alerts in a single request. Requires write:alerts scope.

Request body

Field	Type	Required	Description
`alerts`	Array	Yes	List of alert action objects

Each item in alerts:

Field	Type	Required	Description
`id`	String	Yes	Alert ID
`action`	String	Yes	Action to apply
`text`	String	No	Comment for the action. Defaults to `"<action> operator action"`
`timeout`	Integer	No	Override the alert timeout

Example

Apply actions to multiple alerts in a single request

Bash
Python

curl -X PUT "http://your-tobealert.com:9000/api/alert/action" \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_API_KEY" \
  -d '{
         "alerts": [
             {
                 "id": "alert-uuid-1",
                 "action": "ack",
                 "text": "On-call engineer notified"
             },
             {
                 "id": "alert-uuid-2",
                 "action": "close"
             }
         ]
     }'

import requests

response = requests.put(
    "http://your-tobealert.com:9000/api/alert/action",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Key YOUR_API_KEY"
    },
    json={
        "alerts": [
            {
                "id": "alert-uuid-1",
                "action": "ack",
                "text": "On-call engineer notified"
            },
            {
                "id": "alert-uuid-2",
                "action": "close"
            }
        ]
    }
)

if response.status_code in [200, 201]:
    print("Request successful")
    print(response.json())
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Response

Returns a result per alert:

[
  {
    "id": "alert-uuid-1",
    "status": "ok"
  },
  {
    "id": "alert-uuid-2",
    "status": "ok"
  }
]

Failed items include a message field:

[
  {
    "id": "bad-uuid",
    "status": "error",
    "message": "alert not found"
  }
]

note

Individual failures do not abort the entire batch. All alerts in the request are processed and each gets its own result entry.

Add tags to an alert

PUT /api/alert/<alert_id>/tag
Content-Type: application/json
Authorization: Key YOUR_API_KEY

Adds tags to an existing alert. Requires write:alerts scope.

Request body

Field	Type	Required	Description
`tags`	Array	Yes	List of tag strings to add

Example

Add tags to an alert

Bash
Python

curl -X PUT "http://your-tobealert.com:9000/api/alert/ALERT_ID/tag" \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_API_KEY" \
  -d '{
         "tags": [
             "escalated",
             "sev1",
             "on-call-paged"
         ]
     }'

import requests

response = requests.put(
    "http://your-tobealert.com:9000/api/alert/ALERT_ID/tag",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Key YOUR_API_KEY"
    },
    json={
        "tags": [
            "escalated",
            "sev1",
            "on-call-paged"
        ]
    }
)

if response.status_code in [200, 201]:
    print("Request successful")
    print(response.json())
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Response

{
  "status": "ok"
}

Remove tags from an alert

PUT /api/alert/<alert_id>/untag
Content-Type: application/json
Authorization: Key YOUR_API_KEY

Removes specific tags from an alert. Requires write:alerts scope.

Request body

Field	Type	Required	Description
`tags`	Array	Yes	List of tag strings to remove

Example

Remove tags from an alert

Bash
Python

curl -X PUT "http://your-tobealert.com:9000/api/alert/ALERT_ID/untag" \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_API_KEY" \
  -d '{
         "tags": [
             "escalated"
         ]
     }'

import requests

response = requests.put(
    "http://your-tobealert.com:9000/api/alert/ALERT_ID/untag",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Key YOUR_API_KEY"
    },
    json={
        "tags": [
            "escalated"
        ]
    }
)

if response.status_code in [200, 201]:
    print("Request successful")
    print(response.json())
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Response

{
  "status": "ok"
}

Update alert attributes

PUT /api/alert/<alert_id>/attributes
Content-Type: application/json
Authorization: Key YOUR_API_KEY

Merges new key-value pairs into an alert's attributes object. Existing keys are updated; new keys are added. Requires write:alerts scope.

Request body

Field	Type	Required	Description
`attributes`	Object	Yes	Key-value pairs to merge into the alert attributes

Example

Merge new attributes into an alert

Bash
Python

curl -X PUT "http://your-tobealert.com:9000/api/alert/ALERT_ID/attributes" \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_API_KEY" \
  -d '{
         "attributes": {
             "jira_ticket": "INFRA-4512",
             "resolved_by": "john.doe",
             "postmortem_url": "https://wiki.example.com/postmortems/INFRA-4512"
         }
     }'

import requests

response = requests.put(
    "http://your-tobealert.com:9000/api/alert/ALERT_ID/attributes",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Key YOUR_API_KEY"
    },
    json={
        "attributes": {
            "jira_ticket": "INFRA-4512",
            "resolved_by": "john.doe",
            "postmortem_url": "https://wiki.example.com/postmortems/INFRA-4512"
        }
    }
)

if response.status_code in [200, 201]:
    print("Request successful")
    print(response.json())
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Response

{
  "status": "ok"
}

Notes

Attribute keys cannot contain . or $ characters.
Values can be strings, arrays, or objects (including link objects — see Sending Alerts).

Delete an alert

DELETE /api/alert/<alert_id>
Authorization: Key YOUR_API_KEY

Permanently deletes an alert. Requires delete:alerts scope.

Deleting a cause alert releases its effects (causeId: null, suppressed: false, history entry by system). Deleting an effect does not change its cause. See Sending alerts — Cause and effect.

Example

Permanently delete an alert

Bash
Python

curl -X DELETE "http://your-tobealert.com:9000/api/alert/ALERT_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_API_KEY"

import requests

response = requests.delete(
    "http://your-tobealert.com:9000/api/alert/ALERT_ID",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Key YOUR_API_KEY"
    }
)

if response.status_code in [200, 201]:
    print("Request successful")
    print(response.json())
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Response

{
  "status": "ok"
}

Errors

Code	Reason
`400`	Deletion rejected by a policy plugin
`404`	Alert not found

Notes

Notes are free-text annotations that operators can attach to alerts for collaboration and tracking.

List notes for an alert

GET /api/alert/<alert_id>/notes
Authorization: Key YOUR_API_KEY

Example

List all notes for an alert

Bash
Python

curl -X GET "http://your-tobealert.com:9000/api/alert/ALERT_ID/notes" \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_API_KEY"

import requests

response = requests.get(
    "http://your-tobealert.com:9000/api/alert/ALERT_ID/notes",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Key YOUR_API_KEY"
    }
)

if response.status_code in [200, 201]:
    print("Request successful")
    print(response.json())
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Response

{
  "status": "ok",
  "total": 2,
  "notes": [
    {
      "id": "note-uuid-1",
      "text": "Escalated to the infrastructure team",
      "user": "alice",
      "createTime": "2025-04-15T11:00:00Z",
      "updateTime": "2025-04-15T11:00:00Z"
    },
    {
      "id": "note-uuid-2",
      "text": "Root cause identified: misconfigured load balancer",
      "user": "bob",
      "createTime": "2025-04-15T12:30:00Z",
      "updateTime": "2025-04-15T12:35:00Z"
    }
  ]
}

Add a note

POST /api/alert/<alert_id>/note
Content-Type: application/json
Authorization: Key YOUR_API_KEY

Requires write:alerts scope.

Request body

Field	Type	Required	Description
`text`	String	Yes	The note content (also accepted as `note`)

Example

Add a note to an alert

Bash
Python

curl -X POST "http://your-tobealert.com:9000/api/alert/ALERT_ID/note" \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_API_KEY" \
  -d '{
         "text": "Paged the on-call engineer at 10:35 UTC"
     }'

import requests

response = requests.post(
    "http://your-tobealert.com:9000/api/alert/ALERT_ID/note",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Key YOUR_API_KEY"
    },
    json={
        "text": "Paged the on-call engineer at 10:35 UTC"
    }
)

if response.status_code in [200, 201]:
    print("Request successful")
    print(response.json())
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Response

{
  "status": "ok",
  "id": "note-uuid-3",
  "note": {
    "id": "note-uuid-3",
    "text": "Paged the on-call engineer at 10:35 UTC",
    "user": "alice",
    "createTime": "2025-04-15T10:35:00Z",
    "updateTime": "2025-04-15T10:35:00Z"
  }
}

Update a note

PUT /api/alert/<alert_id>/note/<note_id>
Content-Type: application/json
Authorization: Key YOUR_API_KEY

Updates the text of an existing note. Requires write:alerts. Only the note author can update it: the caller's login must match the note user. The admin scope does not allow editing another user's note.

When the new text differs from the stored text, alert history gains a note_edited entry (shown as Note edited) that stores the new text, the same way note_added stores the note text. When the text is unchanged, the note is left as-is and no history row is written. The Web UI shows (edited) on the note when updateTime is more than one second after createTime.

Request body

Field	Type	Required	Description
`text`	String	Yes	Updated note content (also accepted as `note`)

Example

Update the text of an existing note

Bash
Python

curl -X PUT "http://your-tobealert.com:9000/api/alert/ALERT_ID/note/NOTE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_API_KEY" \
  -d '{
         "text": "Paged the on-call engineer at 10:35 UTC — resolved at 11:10 UTC"
     }'

import requests

response = requests.put(
    "http://your-tobealert.com:9000/api/alert/ALERT_ID/note/NOTE_ID",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Key YOUR_API_KEY"
    },
    json={
        "text": "Paged the on-call engineer at 10:35 UTC — resolved at 11:10 UTC"
    }
)

if response.status_code in [200, 201]:
    print("Request successful")
    print(response.json())
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Response

{
  "status": "ok",
  "note": {
    "id": "note-uuid-3",
    "text": "Paged the on-call engineer at 10:35 UTC — resolved at 11:10 UTC",
    "user": "alice",
    "updateTime": "2025-04-15T11:15:00Z"
  }
}

Errors

Code	Reason
`400`	Missing note text
`403`	Caller is not the note author (`admin` does not bypass this)
`404`	Alert or note not found

Delete a note

DELETE /api/alert/<alert_id>/note/<note_id>
Authorization: Key YOUR_API_KEY

Permanently removes a note from an alert. Requires write:alerts scope. Users can only delete their own notes unless they have admin scope.

Example

Delete a note from an alert

Bash
Python

curl -X DELETE "http://your-tobealert.com:9000/api/alert/ALERT_ID/note/NOTE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_API_KEY"

import requests

response = requests.delete(
    "http://your-tobealert.com:9000/api/alert/ALERT_ID/note/NOTE_ID",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Key YOUR_API_KEY"
    }
)

if response.status_code in [200, 201]:
    print("Request successful")
    print(response.json())
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Response

{
  "status": "ok"
}

Errors

Code	Reason
`403`	Trying to delete another user's note without `admin` scope
`404`	Alert or note not found

Overview​

Change alert status​

Path parameters​

Request body​

Supported status values​

Example​

Response​

Errors​

Apply actions to alerts​

Request body​

Example​

Response​

Add tags to an alert​

Request body​

Example​

Response​

Remove tags from an alert​

Request body​

Example​

Response​

Update alert attributes​

Request body​

Example​

Response​

Notes​

Delete an alert​

Example​

Response​

Errors​

Notes​

List notes for an alert​

Example​

Response​

Add a note​

Request body​

Example​

Response​

Update a note​

Request body​

Example​

Response​

Errors​

Delete a note​

Example​

Response​

Errors​

Overview

Change alert status

Path parameters

Request body

Supported status values

Example

Response

Errors

Apply actions to alerts

Request body

Example

Response

Add tags to an alert

Request body

Example

Response

Remove tags from an alert

Request body

Example

Response

Update alert attributes

Request body

Example

Response

Notes

Delete an alert

Example

Response

Errors

Notes

List notes for an alert

Example

Response

Add a note

Request body

Example

Response

Update a note

Request body

Example

Response

Errors

Delete a note

Example

Response

Errors