Skip to content
DocumentationAPI ReferenceChangelog
API ReferenceTalon Studio v1.0.2-beta

Alerts

List and dismiss SOC alert candidates raised by your detections and connected SIEM, XDR and ITSM sources.

List alerts

GET/api/v1/alertsalerts:read

List a workspace's alert candidates, newest occurrence first.

Query parameters
workspaceIdstring (UUID)
Required with an org-scoped token; a workspace-bound token uses its own workspace.
statusstring · optional
Filter: candidate | promoted | dismissed. Any other value is ignored and the list is unfiltered.
Response
idstring (UUID)
titlestring
sourcestring
backtest | scheduled | notable | xdr | sentinel_incident | elastic_alert | chronicle_alert | servicenow
severitystring · nullable
Passed through from the source system as-is (not normalised); up to 32 characters.
statusstring
candidate | promoted | dismissed
techniqueIdstring · nullable
detectionIdstring (UUID) · nullable
The Talon detection the alert maps to, when it maps to one.
occurredAtstring (ISO 8601)
Returned as { data: [...] }, at most 100 rows, ordered by occurredAt descending. There are no pagination parameters — use the status filter to narrow.
Request
curl -H "Authorization: Bearer tlk_…" \
  "https://<your-instance>/api/v1/alerts?workspaceId=…&status=candidate"
Response
{
  "data": [
    {
      "id": "a1b2c3d4-0000-4000-8000-000000000001",
      "title": "Suspicious PowerShell download",
      "source": "notable",
      "severity": "high",
      "status": "candidate",
      "techniqueId": "T1059.001",
      "detectionId": "d1e2f3a4-0000-4000-8000-000000000002",
      "occurredAt": "2026-07-01T14:22:05.000Z"
    },
    {
      "id": "a1b2c3d4-0000-4000-8000-000000000003",
      "title": "Ransomware behavior detected on host FIN-07",
      "source": "xdr",
      "severity": "critical",
      "status": "promoted",
      "techniqueId": "T1486",
      "detectionId": null,
      "occurredAt": "2026-07-02T03:11:42.000Z"
    }
  ]
}

Dismiss alert

PATCH/api/v1/alerts/{id}alerts:write

Dismiss (close) an alert candidate. This is the only change v1 makes to an alert; promoting one is POST /cases. Not available on the Community Edition: alerts:write is a write scope and needs an Enterprise licence.

Path parameters
idstring (UUID)required
Request body
statusstringrequired
Must be the literal "dismissed".
workspaceIdstring (UUID) · optional
Required with an org-scoped token; a workspace-bound token uses its own workspace.
Response
idstring (UUID)
statusstring
"dismissed"
Returned as a flat object. An alert id outside the resolved workspace gets a uniform 404 "Alert not found". Recorded in the audit log as api.alert.dismissed.
Dismiss is unconditional
There's no status guard: dismissing an alert that has already been promoted into a case still succeeds, and the alert stays in that case's linkedAlerts with nothing there to show it was dismissed (linked-alert entries carry no status). It never clears the alert's link to the case, and dismissing an already-dismissed alert succeeds again.
Request
curl -X PATCH -H "Authorization: Bearer tlk_…" \
  -H "Content-Type: application/json" \
  -d '{"status": "dismissed", "workspaceId": "…"}' \
  "https://<your-instance>/api/v1/alerts/a1b2c3d4-0000-4000-8000-000000000001"
Response
{
  "id": "a1b2c3d4-0000-4000-8000-000000000001",
  "status": "dismissed"
}