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

Search & MCP

Run governed searches over Cribl Lake and connected SIEMs, and plug Talon into your own AI agents as an MCP server.

List search sources

GET/api/v1/search/sourcessearch:read

Which Cribl Lake connections and connected SIEMs have search access enabled for a workspace, whether federation (searching more than one at once) is available, and the dataset names you can search. No log query runs. Returned as a flat object, with no data envelope.

Query parameters
workspaceIdstring (UUID)
Required with an org-scoped token; a workspace-bound token uses its own workspace.
Response
federationEntitledboolean
True with an Enterprise licence.
sources[]object[]
id (pass it in sourceIds), kind (siem | cribl_lake), type (the SIEM type, or cribl), label ("<type> · <host>" for a SIEM, "Cribl Lake · <name>" for a lake).
datasetsstring[]
The workspace's known sourcetypes plus the datasets each Cribl Lake reports, sorted. Lake datasets are fetched live from each lake, best-effort.
Request
curl -H "Authorization: Bearer tlk_…" \
  "https://<your-instance>/api/v1/search/sources?workspaceId=…"
Response
{
  "federationEntitled": false,
  "sources": [
    { "id": "3a1f9c22-…", "kind": "siem", "type": "splunk", "label": "splunk · splunk.example.internal" }
  ],
  "datasets": ["pan:traffic", "wineventlog"]
}

Run a search

POST/api/v1/searchsearch:execute

A live query against a workspace's Cribl Lake and/or connected SIEMs. Results can include raw log content (Splunk _raw, for example), not just Talon metadata. Not available on the Community Edition: search:execute is a write scope and needs an Enterprise licence.

Request body
workspaceIdstring (UUID) · optional
Required with an org-scoped token; a workspace-bound token uses its own workspace.
datasetstring · optional
Guided search: a dataset or sourcetype, 1–200 characters of letters, digits and : . _ / -. Either dataset or rawQuery is required.
containsstring · optional
Free-text filter, up to 200 characters.
limitinteger · optional
Rows per source, 1–25. Default 25.
earlieststring · optional
Relative lookback: a number and m, h or d, e.g. -15m, -24h, -7d. Default -24h. Anything longer than 7 days returns 400.
sourceIdsstring[] · optional
Up to 20 source ids from GET /search/sources. Without it, every source with search access is queried.
rawQuerystring · optional
Raw search: a Cribl/KQL query, 1–4,000 characters. Runs only against Cribl Lake sources.
Response
federatedboolean
True when more than one source was queried.
specobject
The capped query that actually ran: dataset, contains, limit, earliest, latest ("now"), rawQuery.
providerCountinteger
mergedRowCountinteger
results[]object[]
Per source: provider { id, kind, label }, status (running | done | error | skipped | cancelled), rows, rowCount, truncated, message.
Returned as a flat object. No source with search access enabled returns 404 (an admin turns search access on for a connection in Connect → Integrations). A rawQuery whose sourceIds name no Cribl Lake returns 400; with no Cribl Lake search source at all it returns 404. Each search is recorded in the audit log as api.search.executed.
Tighter caps than the Search page
API searches are capped at 25 rows and a 7-day lookback (the Search page in the app allows 500 rows and 30 days) because a token is an unattended credential. They also draw on a second per-token budget, PUBLIC_API_SEARCH_RATE_LIMIT (default 20 a minute), on top of the usual one. Querying more than one source at once is federation, an Enterprise feature — pass a single id in sourceIds when you want exactly one source.
Request
curl -X POST -H "Authorization: Bearer tlk_…" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId": "…", "dataset": "wineventlog", "contains": "185.220.101.4", "earliest": "-24h"}' \
  "https://<your-instance>/api/v1/search"

MCP server

POST/api/v1/mcp

Talon as an MCP (Model Context Protocol) server, so your own AI agents and MCP clients — Claude Desktop, Claude Code, or any other MCP-aware tool — can use Talon's tools. It is stateless Streamable HTTP with JSON responses: every call re-authenticates the bearer token and builds the tool list from the token's effective scopes, so a tool only appears, and is only callable, if its scope is in the grant. Any valid token connects; no single scope is required.

Request body
(MCP protocol)JSON-RPC
Standard MCP Streamable HTTP messages. Point an MCP client at this URL with the token in an Authorization: Bearer header. The in-app copy of the URL is under Settings → API, on the Auth tab.
Enterprise only
The MCP server needs an Enterprise licence — on the Community Edition every call returns 403 "The MCP server requires an Enterprise license.", read tools included. Each HTTP request counts once against the token's rate limit, and execute_search also draws on the search budget.
Request
# Any MCP client that speaks Streamable HTTP:
#   URL:     https://<your-instance>/api/v1/mcp
#   Header:  Authorization: Bearer tlk_…
#
# Or by hand:
curl -X POST -H "Authorization: Bearer tlk_…" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' \
  "https://<your-instance>/api/v1/mcp"