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

Platform

Org roster, notification integrations, licence state, classified sourcetypes and Forge blueprints — the read surfaces around the core detection API.

List users

GET/api/v1/usersusers:read

List the org's active members, oldest account first. Disabled users are left out. Not available on the Community Edition: users:read needs the administer capability, so it counts as a write scope and needs an Enterprise licence.

Response
idstring (UUID)
namestring
displayNamestring · nullable
emailstring
rolestring
admin | engineer | analyst | readonly
createdAtstring (ISO 8601)
updatedAtstring (ISO 8601)
Returned as { data: [...] }. Only these columns are returned — never password or MFA material.
Org-scoped and admin-only
Requires an org-scoped token (a workspace-bound token gets 403 "User access requires an org-scoped token"). Only an admin can grant users:read, and a personal token keeps it only while its owner is still an admin — the role is re-checked on every request.
Request
curl -H "Authorization: Bearer tlk_…" \
  "https://<your-instance>/api/v1/users"
Response
{
  "data": [
    {
      "id": "0e100000-0000-4000-8000-000000000001",
      "name": "jane",
      "displayName": "Jane Doe",
      "email": "jane.doe@example.com",
      "role": "admin",
      "createdAt": "2026-05-01T09:00:00.000Z",
      "updatedAt": "2026-09-02T12:30:00.000Z"
    }
  ]
}

List notification integrations

GET/api/v1/notificationsnotifications:read

List the org's Slack and Teams notification integrations — routing configuration and health, never the webhook URLs, which are stored encrypted and not returned.

Response
idstring (UUID)
integrationIdstring
slack | teams
namestring
enabledboolean
connectionStatusstring
untested | success | failed
eventTypesstring[]
The events it is sent, e.g. pipeline_failure, validation_failure, coverage_gap.
minSeveritystring
info | success | warning | critical — the lowest severity delivered. Defaults to warning.
workspaceIdsstring[]
Workspaces it is limited to; empty means every workspace. Org-level events are delivered regardless.
branchFilterstring[]
Branches whose push events it receives; empty means every branch.
lastTestedAtstring (ISO 8601) · nullable
lastErrorstring · nullable
createdAtstring (ISO 8601)
updatedAtstring (ISO 8601)
Returned as { data: [...] }, ordered by name, at most 100. Org-wide — a workspace-bound token gets 403.
Request
curl -H "Authorization: Bearer tlk_…" \
  "https://<your-instance>/api/v1/notifications"

Get licence state

GET/api/v1/licenselicense:read

The org's licence and entitlement state — useful for monitoring a key's expiry from your own tooling. Returned as a flat object, with no data envelope. Org-wide — a workspace-bound token gets 403. On an unlicensed instance this endpoint is never reached: every API call answers 403 licence_required first.

Response
activeboolean
Always true in a response: an unlicensed instance answers 403 licence_required before this handler runs.
statusstring
missing — the Community Edition: a Community key, or an Enterprise key that has expired, been revoked or is bound to another instance (the name means no paid licence in force) · active — an Enterprise key in force. The type also has unlicensed (no key, or one that does not verify), which this endpoint cannot return for the reason above, and expired, invalid and bypassed, which nothing produces any more.
reasonstring
A readable explanation of the state, e.g. why a stored key no longer applies.
expiresAtstring (ISO 8601) · nullable
The key's expiry. Still set after a key has expired, while status reads missing.
maxStreamsinteger · nullable
Stream limit carried by the key; 3 on the Community Edition. Reported for information — no endpoint enforces it.
maxDetectionsinteger · nullable
Detection limit carried by the key; null (unlimited) on the Community Edition.
trialboolean
Whether the active key was signed as a time-limited trial key. No trial is offered today.
trialExpiredboolean
True when a trial key has lapsed and the instance is back on the Community Edition.
tierstring · nullable
The tier the active key carries, e.g. enterprise; null on the Community Edition.
Request
curl -H "Authorization: Bearer tlk_…" \
  "https://<your-instance>/api/v1/license"
Response
{
  "active": true,
  "status": "missing",
  "reason": "Community Edition, licensed to Example Ltd.",
  "expiresAt": null,
  "maxStreams": 3,
  "maxDetections": null,
  "trial": false,
  "trialExpired": false,
  "tier": null
}

List sourcetypes

GET/api/v1/sourcetypessourcetypes:read

A workspace's classified data streams (sourcetypes) — schema type, field presence, detectable ATT&CK techniques and normalisation status, as the Evidence Grid shows them. Each row's id is the streamId that POST /detections needs.

Query parameters
workspaceIdstring (UUID)
Required with an org-scoped token; a workspace-bound token uses its own workspace.
Response
idstring (UUID)
The stream id — pass it as streamId when proposing a detection.
namestring · nullable
descriptionstring · nullable
sourceTypestring
http | s3_lakehouse | broker_stream | siem_schema | manual
sourceStatusstring
active | pending | planned | paused | error
sourcetypestring
schemaTypestring
CIM | ECS | OCSF | ASIM | UNKNOWN
fieldsPresentstring[]
fieldsMissingstring[]
mitreDetectableobject[]
mitreNotDetectableobject[]
normalizationStatusstring · nullable
conformant | partial | non_conformant | raw
retentionDaysinteger · nullable
Null inherits the default policy.
dataClassificationstring · nullable
public | internal | confidential | restricted
lastSeenAtstring (ISO 8601) · nullable
lastClassifiedAtstring (ISO 8601) · nullable
createdAtstring (ISO 8601)
updatedAtstring (ISO 8601)
Returned as { data: [...] }. Sourcetypes pending deletion are left out, and so are the heavy fields — sample events, field history and raw source configuration.
Request
curl -H "Authorization: Bearer tlk_…" \
  "https://<your-instance>/api/v1/sourcetypes?workspaceId=…"

List blueprints

GET/api/v1/blueprintsblueprints:read

List Forge blueprints and detection standards in the token's reach. Stream-less, code-first templates are left out, as in the app's blueprint list.

Query parameters
workspaceIdstring (UUID) · optional
Filter to one workspace. Without it, an org service token sees every workspace's blueprints and a personal org token sees its owner's accessible workspaces.
Response
idstring (UUID)
workspaceIdstring (UUID)
streamIdstring (UUID)
The stream the blueprint is anchored to.
namestring
descriptionstring · nullable
kindstring
template | standard
isActiveStandardboolean
Whether this standard is the workspace's active override.
enforcementstring
warn | block — how a standard treats a detection that doesn't conform.
createdAtstring (ISO 8601)
updatedAtstring (ISO 8601)
Returned as { data: [...] }. The graph, preview and conformance definitions are left out — fetch GET /blueprints/{id} for them.
Request
curl -H "Authorization: Bearer tlk_…" \
  "https://<your-instance>/api/v1/blueprints?workspaceId=…"

Get blueprint

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

One blueprint in full — including its graph definition, preview and, for a standard, its conformance spec. Returned as a flat object, with no data envelope.

Path parameters
idstring (UUID)required
Response
idstring (UUID)
workspaceIdstring (UUID)
streamIdstring (UUID) · nullable
Null for a code-first template.
namestring
descriptionstring · nullable
kindstring
template | standard
graphobject
The blueprint's node graph.
previewobject · nullable
conformanceobject · nullable
The rules detections are graded against, for a standard.
isActiveStandardboolean
enforcementstring
warn | block
createdAtstring (ISO 8601)
updatedAtstring (ISO 8601)
A blueprint in a workspace outside the token's reach gets a uniform 404, the same as detections.
Request
curl -H "Authorization: Bearer tlk_…" \
  "https://<your-instance>/api/v1/blueprints/{id}"