Skip to main content
Manage finding comments and retrieve the complete event timeline for a security finding.

​
Add Comment

Add a comment to a finding to document observations, questions, or triage decisions.
This endpoint requires authentication. Comments are associated with the authenticated user.

​
Path Parameters

​
id
string
required
The unique UUID of the finding to comment on

​
Request Body

​
comment
string
required
The comment text to add. Markdown formatting is preserved.
{
  "comment": "Reviewed with security team. This appears to be a false positive due to input validation happening in the middleware layer."
}

​
Response

Returns the created comment event.
​
data
object
The finding event object representing the comment
{
  "success": true,
  "data": {
    "id": "987e6543-e89b-12d3-a456-426614174999",
    "finding_id": "123e4567-e89b-12d3-a456-426614174000",
    "user_id": "555e5555-e89b-12d3-a456-426614175555",
    "event_type": "comment",
    "old_value": null,
    "new_value": null,
    "comment": "Reviewed with security team. This appears to be a false positive due to input validation happening in the middleware layer.",
    "metadata": null,
    "created_at": "2026-03-12T16:20:00Z"
  }
}

​
Error Responses

​
404 Not Found

Returned when the specified finding does not exist. 
{
  "success": false,
  "code": 404,
  "message": "Finding '123e4567-e89b-12d3-a456-426614174000' not found"
}

​
500 Internal Server Error

Returned when the comment cannot be created. 
{
  "success": false,
  "code": 500,
  "message": "Failed to add comment: database connection error"
}

​
List Events

Retrieve the complete event history for a finding, including status changes, severity updates, comments, patch applications, and AI reviews.

​
Path Parameters

​
id
string
required
The unique UUID of the finding whose events should be retrieved

​
Response

Returns an array of all events associated with the finding, ordered chronologically.
​
data
array
Array of finding events
{
  "success": true,
  "data": [
    {
      "id": "111e1111-e89b-12d3-a456-426614174001",
      "finding_id": "123e4567-e89b-12d3-a456-426614174000",
      "user_id": null,
      "event_type": "status_change",
      "old_value": null,
      "new_value": "open",
      "comment": "Finding created",
      "metadata": null,
      "created_at": "2026-03-12T10:30:00Z"
    },
    {
      "id": "222e2222-e89b-12d3-a456-426614174002",
      "finding_id": "123e4567-e89b-12d3-a456-426614174000",
      "user_id": "555e5555-e89b-12d3-a456-426614175555",
      "event_type": "severity_change",
      "old_value": "medium",
      "new_value": "high",
      "comment": null,
      "metadata": null,
      "created_at": "2026-03-12T14:30:00Z"
    },
    {
      "id": "333e3333-e89b-12d3-a456-426614174003",
      "finding_id": "123e4567-e89b-12d3-a456-426614174000",
      "user_id": "555e5555-e89b-12d3-a456-426614175555",
      "event_type": "comment",
      "old_value": null,
      "new_value": null,
      "comment": "Reviewed with security team. This appears to be a false positive.",
      "metadata": null,
      "created_at": "2026-03-12T16:20:00Z"
    },
    {
      "id": "444e4444-e89b-12d3-a456-426614174004",
      "finding_id": "123e4567-e89b-12d3-a456-426614174000",
      "user_id": "555e5555-e89b-12d3-a456-426614175555",
      "event_type": "status_change",
      "old_value": "open",
      "new_value": "false_positive",
      "comment": null,
      "metadata": null,
      "created_at": "2026-03-12T16:25:00Z"
    }
  ]
}

​
Error Responses

​
500 Internal Server Error

Returned when the events cannot be retrieved. 
{
  "success": false,
  "code": 500,
  "message": "Failed to list finding events: database connection error"
}
The events endpoint does not return a 404 error if the finding doesn’t exist. Instead, it returns an empty array. To verify a finding exists, use the Get Finding endpoint.

​
Event Types Reference

Here’s a complete reference of all event types you may encounter:
Triggered when a finding’s triage status is updated. The old_value and new_value fields contain the previous and new status values.
Triggered when a finding’s severity level is modified. The old_value and new_value fields contain the previous and new severity values.
Triggered when a user adds a comment to a finding. The comment text is stored in the comment field.
Triggered when a security patch is marked as applied. The new_value field contains the patch UUID.
Triggered when AI generates a plain-language explanation of the finding. The metadata field contains the AI’s analysis including summary, why it was flagged, what to review, and remediation focus.
Triggered when AI performs a verification review to determine if the finding is a true positive. The metadata field contains verdict, rationale, signals, and recommended status.
Triggered when a repository issue (GitHub/GitLab) is linked to the finding. The metadata field contains provider, issue URL, issue number, and creation status.

Build docs developers (and LLMs) love

Get started for freeTalk to us