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

Detections

List and read detections, and propose new detections or edits as governed change requests.

List detections

GET/api/v1/detectionsdetections:read

Paginated list of detections in the token's reach.

Query parameters
workspaceIdstring (UUID)
Filter to one workspace. Never required: an org service token with no workspaceId sees detections across the whole org, and a personal org token with no workspaceId sees only its owner's accessible workspaces. A workspace-bound token passing a different workspace's id gets 403.
pageinteger
Page number, default 1.
perPageinteger
Items per page, 1–100, default 25.
Response
idstring (UUID)
namestring
descriptionstring · nullable
workspaceIdstring (UUID)
statusstring
Lifecycle status — one of draft, validated, degraded, deployed, deprecated, git_sync_failed.
mitreTacticstring · nullable
mitreTechniqueIdstring · nullable
Primary technique.
mitreTechniqueIdsstring[]
All mapped techniques.
confidencestring · nullable
One of high, medium, low.
sourcetypestring · nullable
The sourcetype of the stream the detection is built on.
createdAtstring (ISO 8601)
updatedAtstring (ISO 8601)
Returned with meta { page, perPage, total, totalPages } and links { next, prev }. The underlying query is capped at the 500 most recently updated detections (updatedAt descending) before paging is applied, so total never exceeds 500 and anything older than that window isn't reachable through this endpoint. The links carry only page and perPage — add workspaceId back when you follow one.
Request
curl -H "Authorization: Bearer tlk_…" \
  "https://<your-instance>/api/v1/detections?workspaceId=…&perPage=25"
Response
{
  "data": [
    { "id": "7c2a…", "name": "Suspicious PowerShell", "status": "deployed" },
    { "id": "9d4f…", "name": "Anomalous OAuth Grant", "status": "validated" }
  ],
  "meta": { "page": 1, "perPage": 25, "total": 2, "totalPages": 1 },
  "links": { "next": null, "prev": null }
}

Get detection

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

Fetch one detection, including its rule bodies. Returned as a flat object, with no data envelope.

Path parameters
idstring (UUID)required
Response
idstring (UUID)
namestring
descriptionstring · nullable
workspaceIdstring (UUID)
statusstring
draft | validated | degraded | deployed | deprecated | git_sync_failed
mitreTacticstring · nullable
mitreTechniqueIdstring · nullable
mitreTechniqueIdsstring[]
severitystring · nullable
One of informational, low, medium, high, critical.
riskScoreinteger · nullable
sourcetypestring · nullable
splstring · nullable
Splunk SPL.
kqlstring · nullable
Sentinel KQL.
sigmastring · nullable
Canonical Sigma YAML.
eqlstring · nullable
Elastic EQL.
yaraLstring · nullable
Chronicle YARA-L.
createdAtstring (ISO 8601)
updatedAtstring (ISO 8601)
Scoped 404
Workspace-bound tokens get a uniform 404 for detections outside their workspace, and a personal org token likewise gets a 404 for detections in workspaces its owner can't access — the response never confirms whether the id exists.
Request
curl -H "Authorization: Bearer tlk_…" \
  "https://<your-instance>/api/v1/detections/{id}"
Response
{
  "id": "7c2a…",
  "name": "Suspicious PowerShell",
  "workspaceId": "d41f…",
  "status": "deployed",
  "mitreTechniqueId": "T1059.001",
  "severity": "high",
  "sigma": "title: Suspicious PowerShell\n…",
  "spl": "index=win …"
}

Propose detection

POST/api/v1/detectionsdetections:propose

Propose a new detection. Propose-only: it validates the detection, then stages it on a new branch as a draft change request for a human to review and merge — it never writes to main or deploys. Personal tokens only; a service token is refused with 403. Not available on the Community Edition: detections:propose is a write scope and needs an Enterprise licence.

Request body
namestringrequired
1–200 characters.
streamIdstring (UUID)required
The stream (sourcetype) the detection runs on — the id field from GET /sourcetypes. It must belong to the target workspace; an id from another workspace, or an unknown id, returns 404 "Stream not found in this workspace".
sigmastring · optional
Sigma YAML, 1–20,000 characters. At least one of sigma or spl is required; both may be sent.
splstring · optional
Splunk SPL, 1–20,000 characters.
mitreTechniqueIdstring · optional
Up to 24 characters, e.g. T1059.001. Upper-cased before use; the tactic is filled in from the ATT&CK catalogue.
descriptionstring · optional
Up to 2,000 characters.
workspaceIdstring (UUID) · optional
Required with an org-scoped token; a workspace-bound token uses its own workspace.
Response
changeRequestIdstring (UUID)
branchNamestring
agent/, then a slug of the change request title "API: <name>" (up to 48 characters), then the first 8 characters of the change request id.
statusstring
Always "draft".
Returns 201 Created. If the detection fails Sigma, SPL or rule validation the call returns 400 with only the generic message "Proposed detection failed validation" — the field-level reasons aren't included, so check the detection in the app. The change request's title is "API: <name>" and its author is the token's owner.
Propose, don't write
Every API-created detection lands as a reviewable draft change request, never straight to main. A successful proposal is recorded in the audit log as api.detection.proposed, with the change request id and the token id.
Request
curl -X POST -H "Authorization: Bearer tlk_…" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Suspicious PowerShell", "streamId": "6a9c…", "sigma": "title: …" }' \
  "https://<your-instance>/api/v1/detections"
Response
{
  "changeRequestId": "b19e1c2d-…",
  "branchName": "agent/api-suspicious-powershell-b19e1c2d",
  "status": "draft"
}

Propose an edit

PATCH/api/v1/detections/{id}detections:propose

Propose an edit to an existing detection. Governed and propose-only, like POST /detections: it stages a draft change request for human review and merge, and never writes to main or deploys. Personal tokens only; a service token is refused with 403. Not available on the Community Edition: detections:propose needs an Enterprise licence.

Path parameters
idstring (UUID)required
Request body
sigmastring · optional
Sigma YAML, 1–20,000 characters. Changing it re-derives the stored SPL, KQL, EQL and YARA-L from the new Sigma, except any native query you send in the same call or one that was hand-edited to differ from the old Sigma's translation.
splstring · optional
Splunk SPL, 1–20,000 characters.
descriptionstring · optional
Up to 2,000 characters.
namestring · optional
1–200 characters. See the note below — a rename is refused.
mitreTechniqueIdstring · optional
Up to 24 characters. See the note below — re-mapping is refused.
Response
changeRequestIdstring (UUID)
branchNamestring
agent/, then a slug of the change request title "API: updated <name>" (up to 48 characters), then the first 8 characters of the change request id.
statusstring
Always "draft".
Returns 202 Accepted — the edit is staged as a draft change request titled "API: updated <name>", not applied. At least one body field is required (422 otherwise). If the edited YAML fails validation the call returns 400 "Proposed YAML failed validation". If the Sigma changed and the Sigma translation sidecar is down, the call returns 503 and nothing is staged. Recorded in the audit log as api.detection.edit_proposed.
Name and technique are fixed
A detection's file in Git is named from its ATT&CK technique and its name. An edit that changes either would move the file, so it is refused with 409 "This edit would move the detection source file (name or MITRE technique changed). Keep them stable." Use this endpoint for the rule bodies and description.
Request
curl -X PATCH -H "Authorization: Bearer tlk_…" \
  -H "Content-Type: application/json" \
  -d '{"description": "Tuned for service accounts"}' \
  "https://<your-instance>/api/v1/detections/{id}"
Response
{
  "changeRequestId": "9f41a2c3-…",
  "branchName": "agent/api-updated-suspicious-powershell-9f41a2c3",
  "status": "draft"
}