API ReferenceTalon Studio v1.0.2-beta

Introduction

A token-authenticated REST API for Talon Studio — the same data you see in the UI, exposed as predictable HTTP endpoints under /api/v1 on your own instance.

What it is

The Talon Studio API gives you programmatic access to your workspaces — detections, coverage, adversaries, alerts, cases, deployments and more — as JSON over HTTP. Every request is authenticated with a scoped API token; session cookies are never accepted by the data endpoints (only the OpenAPI document also opens for a logged-in session), so the API is safe to call from scripts, CI and integrations.

It is a read-and-propose surface by design. Reads mirror the UI. The few write endpoints are deliberately narrow: proposing a detection stages a draft change request for a human to review and merge, and the triage writes (dismiss an alert, promote it to a case, create a workboard card) are the same reversible actions the UI allows. Nothing in the API merges to main or deploys to a SIEM.

Every endpoint behind a read scope works on the Community Edition. The write scopes (which include the admin-only audit-log and user-roster reads) and the MCP server need an Enterprise licence key, and Enterprise is in development and not on sale — see Authentication → Community Edition and Enterprise.

Base URL

Talon Studio is self-hosted, so the API lives on your own instance, under the versioned base path:

Base URL

https://<your-instance>/api/v1

Replace <your-instance> with the hostname your appliance is served on. Every path in this reference is relative to that base: GET /detections means GET https://<your-instance>/api/v1/detections.

Serve it over HTTPS

The API itself does not refuse plain HTTP. A bearer token sent over HTTP can be read by anything on the path, so put the instance behind TLS before you hand a token to a script.

Request conventions

JSON in, JSON out. POST and PATCH bodies are parsed as JSON — send Content-Type: application/json. A missing or malformed body fails validation with a 422.

Workspace routing. A token is either org-scoped or bound to one workspace. Endpoints that work on a single workspace take a workspaceId — in the query string for GET, in the body for POST/PATCH. An org-scoped token must send it (omitting it returns 400); a workspace-bound token can leave it out, and sending a different workspace's id returns 403. The lists that can span workspaces — /detections, /agent-runs and /blueprints — treat it as an optional filter; on /threat-feeds, leaving it out returns the org-level feeds.

Envelopes vary by endpoint. Lists come back as { data: [...] } (GET /detections adds meta and links; GET /audit-logs adds nextCursor). Single resources are either wrapped in data or returned flat — each endpoint page says which. GET /coverage/navigator-layer returns the raw Navigator layer with no envelope.

Identifiers are UUIDs, except ATT&CK ids (T1059.001, G0016, C0024). Timestamps are ISO 8601 strings in UTC.

Versioning

The API uses path-based versioning, and v1 is the only version. The design commits breaking changes to a new prefix (/api/v2) rather than changing v1 in place. No v2 exists yet and no deprecation schedule has been published. Additive changes — a new endpoint, a new field on a response — land in v1, so a client should ignore fields it does not recognise.

OpenAPI spec

Every appliance serves its own OpenAPI 3.1 document — every path, parameter, schema and scope — maintained in the same codebase that serves the API:

GET/api/v1/openapi.json

Point Postman, Insomnia or a client generator at https://<your-instance>/api/v1/openapi.json to scaffold a typed client. Inside the app, Settings → API renders the same document as a read-only endpoint reference on its API tab; tokens live on the Auth tab next to it.

This endpoint isn't anonymous

GET /openapi.json still requires a caller: either a logged-in app session or any valid, unexpired, unrevoked bearer token (no scope is checked). An unauthenticated request gets 401 with { "message": "Unauthorized" }.

Every operation in the document carries an x-scope vendor extension naming the exact scope it requires — one source of truth a codegen or tooling step can read per operation.

The document's servers[0].url is computed from the request that fetched it, so the spec describes whichever host served it.

The outbound MCP server (/mcp) is not in the document — it speaks JSON-RPC, not REST. See Search & MCP.

You can also download a copy from this site without an instance:

Download OpenAPI spec

Prefer your appliance's copy

The download is a snapshot that uses a <your-instance> placeholder for its server URL. The copy your own appliance serves always matches the version you are running, so generate clients from that one.