Alert comments#

Alert comments let responders keep human context directly inside an alert group: investigation notes, decisions, links, handover details and follow-up information.

Open:

Alerts -> Alert details -> Comments

Comments are attached to an alert group. In the current Alerts API, the path parameter named alert_id is the alert group id used by the alert details endpoint.

What comments are for#

Use comments to record information that should stay with the alert history:

• what was checked;
• who is investigating;
• temporary mitigation steps;
• links to dashboards, logs, tickets or runbooks;
• handover notes between responders;
• post-resolution notes.

Comments are different from alert events. Alert events are timeline/audit entries generated by the system, while comments are user-written notes. Creating, editing or deleting a comment also writes an alert event so the timeline shows that a comment action happened.

Permissions#

Reading comments requires alert read access for the alert group team.

Creating, editing and deleting comments require responder access for the alert group team.

Allowed users:

Team responder Team manager Global admin

Users with only viewer access can read comments but cannot create, edit or delete them.

Comment body rules#

The comment body is plain text.

Validation rules:

• body is required;
• body is trimmed before saving;
• empty or whitespace-only body is rejected;
• maximum length is 5000 characters.

UI behavior#

The Comments block in alert details should show:

• existing comments ordered by creation time;
• author name or fallback identity;
• creation time;
• edited marker when updated_at is later than created_at;
• Add comment form for users with responder permissions;
• Edit and Delete buttons for users with responder permissions;
• Refresh button to reload comments without closing the modal.

After creating, editing or deleting a comment, the UI should refresh both:

• the comments list;
• the alert events timeline.

API endpoints#

List comments#

GET /api/alert-groups/{alert_id}/comments

Returns comments for the alert group.

Required permission:

alert group team read access

Example:

curl -X GET \ http://127.0.0.1:8080/api/alert-groups/123/comments \ -H 'Authorization: Bearer API_TOKEN'

Example response:

[ { "id": 10, "group_id": 123, "alert_id": null, "user_id": 5, "user": { "id": 5, "username": "alice", "email": "alice@example.com", "display_name": "Alice" }, "body": "Checking RabbitMQ cluster state and network links.", "created_at": "2026-06-05T11:30:00", "updated_at": "2026-06-05T11:30:00", "edited": false } ]

Create comment#

POST /api/alert-groups/{alert_id}/comments

Required permission:

Team responder, Team manager, or global admin

Request body:

{ "body": "Investigating. Disk usage increased after backup job." }

Example:

curl -X POST \ http://127.0.0.1:8080/api/alert-groups/123/comments \ -H 'Authorization: Bearer API_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"body":"Investigating. Disk usage increased after backup job."}'

Success response:

201 Created

{ "id": 11, "group_id": 123, "alert_id": null, "user_id": 5, "user": { "id": 5, "username": "alice", "email": "alice@example.com", "display_name": "Alice" }, "body": "Investigating. Disk usage increased after backup job.", "created_at": "2026-06-05T11:35:00", "updated_at": "2026-06-05T11:35:00", "edited": false }

Validation error:

400 Bad Request

{ "error": "validation_error", "message": "comment body is required" }

Update comment#

PUT /api/alert-groups/{alert_id}/comments/{comment_id}

Updates an existing non-deleted comment in the alert group.

Required permission:

Team responder, Team manager, or global admin

Request body:

{ "body": "Updated investigation note. Backup job is confirmed as the trigger." }

Example:

curl -X PUT \ http://127.0.0.1:8080/api/alert-groups/123/comments/11 \ -H 'Authorization: Bearer API_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"body":"Updated investigation note. Backup job is confirmed as the trigger."}'

Success response:

200 OK

{ "id": 11, "group_id": 123, "alert_id": null, "user_id": 5, "user": { "id": 5, "username": "alice", "email": "alice@example.com", "display_name": "Alice" }, "body": "Updated investigation note. Backup job is confirmed as the trigger.", "created_at": "2026-06-05T11:35:00", "updated_at": "2026-06-05T11:42:00", "edited": true }

Delete comment#

DELETE /api/alert-groups/{alert_id}/comments/{comment_id}

Deletes a comment from the visible comments list. The recommended implementation is soft delete, so historical integrity is preserved.

Required permission:

Team responder, Team manager, or global admin

Example:

curl -X DELETE \ http://127.0.0.1:8080/api/alert-groups/123/comments/11 \ -H 'Authorization: Bearer API_TOKEN'

Success response:

200 OK

{ "deleted": true, "id": 11 }

Events and audit#

Comment actions should create alert events:

Action Event type Create commented Update comment_updated Delete comment_deleted

Comment actions should also write audit records:

Action Audit action Create alert_group.comment Update alert_group.comment.update Delete alert_group.comment.delete

Troubleshooting#

If comments are not visible:

• Check that the alert group exists.
• Check that the user can read the alert group team.
• Check that deleted comments are filtered from the default list query.
• Check browser console for frontend errors.
• Check that GET /api/alert-groups/{alert_id}/comments returns JSON.

If creating, editing or deleting comments fails:

• Check that the user has Team responder or Team manager role.
• Check that the request has Content-Type: application/json.
• Check that body is not empty.
• Check that body is not longer than 5000 characters.
• Check server logs by error_id if the API returns an unexpected error.