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

Cases

List SOC cases, promote alerts into them, and read a case with its full timeline.

List cases

GET/api/v1/casescases:read

List a workspace's SOC cases, newest first.

Query parameters
workspaceIdstring (UUID)
Required with an org-scoped token; a workspace-bound token uses its own workspace.
statusstring · optional
Filter: open | investigating | resolved | false_positive. Any other value is ignored and the list is unfiltered.
Response
idstring (UUID)
titlestring
statusstring
open | investigating | resolved | false_positive
prioritystring · nullable
critical | high | medium | low
severitystring · nullable
techniqueIdstring · nullable
detectionIdstring (UUID) · nullable
createdAtstring (ISO 8601)
updatedAtstring (ISO 8601)
Returned as { data: [...] }, at most 100 rows, ordered by createdAt descending. There are no pagination parameters — use the status filter to narrow.
Request
curl -H "Authorization: Bearer tlk_…" \
  "https://<your-instance>/api/v1/cases?workspaceId=…&status=open"
Response
{
  "data": [
    {
      "id": "c1a25e40-0000-4000-8000-000000000001",
      "title": "Credential access on host WIN-01",
      "status": "investigating",
      "priority": "high",
      "severity": "high",
      "techniqueId": "T1003",
      "detectionId": "d1e2f3a4-0000-4000-8000-000000000002",
      "createdAt": "2026-06-30T09:10:00.000Z",
      "updatedAt": "2026-07-01T11:45:00.000Z"
    },
    {
      "id": "c1a25e40-0000-4000-8000-000000000003",
      "title": "Phishing email reported by user",
      "status": "resolved",
      "priority": "medium",
      "severity": "medium",
      "techniqueId": "T1566",
      "detectionId": null,
      "createdAt": "2026-06-28T08:00:00.000Z",
      "updatedAt": "2026-06-29T15:30:00.000Z"
    }
  ]
}

Promote alert to case

POST/api/v1/casescases:write

Promote an alert candidate into a SOC case — or into an existing open or investigating case it correlates with. Not available on the Community Edition: cases:write is a write scope and needs an Enterprise licence.

Request body
candidateIdstring (UUID)required
The alert to promote. It must be in candidate status.
titlestring · optional
1–200 characters. Defaults to the alert's title. Ignored when the alert folds into an existing case.
severitystring · optional
Up to 24 characters. Defaults to the alert's severity. Ignored when the alert folds into an existing case.
workspaceIdstring (UUID) · optional
Required with an org-scoped token; a workspace-bound token uses its own workspace.
Response
data.idstring (UUID)
The case the alert now belongs to — new, or an existing one it folded into.
data.statusstring
Always "open" in this response, even when the alert folded into a case that is already investigating. Read GET /cases/{id} for the real status.
Returns 201 Created. An alert that isn't in candidate status returns 409 ("Candidate is already promoted" or "… dismissed"); a candidateId from another workspace gets a uniform 404 "Alert not found". Recorded in the audit log as api.case.promoted.
Correlation folding
An alert's entity is the first of dest, user, src or host present in its metadata. If an open or investigating case in the workspace already groups the same detection and entity, the alert folds into that case instead of opening a new one, and every other still-candidate alert sharing that key is promoted into it too. Folding also crosses the mapped/unmapped line on the same entity: an alert mapped to a detection joins an existing unmapped case for that entity, and an unmapped alert (most XDR detects) joins any open or investigating case for that entity — so the returned id may be a pre-existing case mapped to a different detection. Two different detections on the same entity stay separate cases. A new case is sent to the SOC notification destinations; a new high or critical case is also sent to the enabled Slack and Teams notification integrations that subscribe to the soc_case event. Folding into an existing case sends nothing.
Request
curl -X POST -H "Authorization: Bearer tlk_…" \
  -H "Content-Type: application/json" \
  -d '{"candidateId": "a1b2c3d4-0000-4000-8000-000000000001", "workspaceId": "…"}' \
  "https://<your-instance>/api/v1/cases"
Response
{
  "data": {
    "id": "c1a25e40-0000-4000-8000-000000000002",
    "status": "open"
  }
}

Get case

GET/api/v1/cases/{id}cases:read

Fetch one case with its activity timeline, correlated alerts and linked workboard card.

Path parameters
idstring (UUID)required
Query parameters
workspaceIdstring (UUID)
Required with an org-scoped token; a workspace-bound token uses its own workspace.
Response
idstring (UUID)
workspaceIdstring (UUID)
candidateIdstring (UUID) · nullable
The alert the case was opened from; null if that alert has since been deleted.
detectionIdstring (UUID) · nullable
techniqueIdstring · nullable
titlestring
statusstring
open | investigating | resolved | false_positive
prioritystring · nullable
critical | high | medium | low
dispositionstring · nullable
true_positive | false_positive | benign | duplicate
severitystring · nullable
notesstring · nullable
clawRunIdstring (UUID) · nullable
The AI agent run investigating the case, if one was started — readable at GET /agent-runs/{id}.
assetContextobject · nullable
CMDB context for the case's entity, when a ServiceNow integration is connected and the entity matched a CI: entity, ciSysId, ciName, ciClass, owner, businessService, criticality, location, syncedAt.
resolvedAtstring (ISO 8601) · nullable
Set when the status becomes resolved or false_positive, cleared on any other status change. v1 has no case-update endpoint — status, priority and disposition are changed in the app.
createdAtstring (ISO 8601)
updatedAtstring (ISO 8601)
candidateMetadataobject · nullable
The originating alert's raw metadata. Correlation reads its dest, user, src and host keys.
candidateSourcestring · nullable
backtest | scheduled | notable | xdr | sentinel_incident | elastic_alert | chronicle_alert | servicenow
candidateOccurredAtstring (ISO 8601) · nullable
candidateCountrystring · nullable
Country as reported by the source, when the alert carried geo fields.
candidateGeoobject · nullable
region, city, lat, lon — when the alert carried them.
detectionNamestring · nullable
assigneeobject · nullable
{ id, name }
activityarray
The latest 200 timeline entries, oldest first: id, kind (comment | event), body, actor, createdAt. actor may be a system label such as "Talon" or the fallback "Someone" rather than a person.
linkedAlertsarray
The alerts correlated into the case: id, title, severity, occurredAt, country — newest first, at most 50, and not filtered by the alert's own status (a dismissed alert can still appear).
linkedCardobject · nullable
{ id, title } — the workboard card linked to this case, if one has been created.
Returned as { data: { … } }. A case id outside the resolved workspace gets a uniform 404 "Case not found", so ids can't be probed.
Request
curl -H "Authorization: Bearer tlk_…" \
  "https://<your-instance>/api/v1/cases/c1a25e40-0000-4000-8000-000000000001?workspaceId=…"
Response
{
  "data": {
    "id": "c1a25e40-0000-4000-8000-000000000001",
    "workspaceId": "d41f0000-0000-4000-8000-000000000000",
    "candidateId": "a1b2c3d4-0000-4000-8000-000000000001",
    "detectionId": "d1e2f3a4-0000-4000-8000-000000000002",
    "techniqueId": "T1003",
    "title": "Credential access on host WIN-01",
    "status": "investigating",
    "priority": "high",
    "disposition": null,
    "severity": "high",
    "notes": null,
    "clawRunId": null,
    "assetContext": null,
    "resolvedAt": null,
    "createdAt": "2026-06-30T09:10:00.000Z",
    "updatedAt": "2026-07-01T11:45:00.000Z",
    "candidateMetadata": { "host": "WIN-01", "user": "jdoe" },
    "candidateSource": "notable",
    "candidateOccurredAt": "2026-06-30T09:05:00.000Z",
    "candidateCountry": null,
    "candidateGeo": null,
    "detectionName": "Suspicious LSASS Access",
    "assignee": { "id": "0e100000-0000-4000-8000-000000000001", "name": "Jane Doe" },
    "activity": [
      {
        "id": "e71a2b3c-0000-4000-8000-000000000001",
        "kind": "event",
        "body": "moved this to investigating",
        "actor": "Alex Chen",
        "createdAt": "2026-06-30T09:12:00.000Z"
      }
    ],
    "linkedAlerts": [
      {
        "id": "a1b2c3d4-0000-4000-8000-000000000001",
        "title": "Suspicious PowerShell download",
        "severity": "high",
        "occurredAt": "2026-06-30T09:05:00.000Z",
        "country": null
      }
    ],
    "linkedCard": null
  }
}