{ "openapi": "3.1.0", "info": { "title": "Talon Studio API", "version": "1.0.0", "license": { "name": "Talon Labs Community Edition Licence", "url": "https://www.talonlabs.dev/company/licence" }, "description": "Token-authenticated REST API for Talon Studio. Authenticate with `Authorization: Bearer tlk_…` over HTTPS — session cookies are never accepted. Tokens carry least-privilege scopes and are org- or workspace-scoped. Scopes: me:read, workspaces:read, detections:read, detections:propose, coverage:read, alerts:read, alerts:write, change_requests:read, threat_feeds:read, standards:read, deployments:read, integrations:read, cases:read, cases:write, kanban:read, kanban:write, agents:read, audit:read, users:read, notifications:read, license:read, sourcetypes:read, blueprints:read, validate:read, search:read, search:execute. \n\nAll list/filter endpoints use `GET` with query-string parameters. The HTTP `QUERY` method (RFC 10008, June 2026) is a safe/cacheable way to send complex filter bodies and is a candidate for future filter-heavy endpoints, but isn't adopted yet — OpenAPI 3.1 doesn't recognize `query` as a Path Item Object key, and Next.js route handlers have no `QUERY` export convention." }, "servers": [ { "url": "https://{instance}/api/v1", "variables": { "instance": { "default": "studio.example.com", "description": "The host your Talon Studio is served on." } } } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Identity", "description": "Who the presented token is." }, { "name": "Workspaces", "description": "Projects and their metadata." }, { "name": "Detections", "description": "Detection content (read + propose)." }, { "name": "Coverage", "description": "MITRE ATT&CK coverage for a workspace." }, { "name": "Adversaries", "description": "ATT&CK groups/campaigns vs. workspace coverage." }, { "name": "MITRE", "description": "The synced ATT&CK reference catalogue." }, { "name": "Alerts", "description": "SOC alert candidates." }, { "name": "SOC Cases", "description": "Promoted SOC cases." }, { "name": "Deployments", "description": "SIEM deployment targets and deploy state." }, { "name": "Integrations", "description": "Connected SIEMs." }, { "name": "Workboard", "description": "Kanban cards." }, { "name": "Agents", "description": "AI agent runs." }, { "name": "Change Requests", "description": "Git-backed change requests." }, { "name": "Threat Intel", "description": "Threat-intel feeds." }, { "name": "Standards", "description": "Detection standards." }, { "name": "Audit", "description": "Organisation audit trail." }, { "name": "Users", "description": "Organisation member roster (admin-gated)." }, { "name": "Notifications", "description": "Slack/Teams notification integrations." }, { "name": "License", "description": "Org license and entitlement state." }, { "name": "Sourcetypes", "description": "Workspace data sourcetype classification." }, { "name": "Blueprints", "description": "Forge blueprints and standards." }, { "name": "Validate", "description": "Detection validation readiness." }, { "name": "Search", "description": "Federated log search (Cribl Lake + connected SIEMs)." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "tlk" } }, "headers": { "RateLimitLimit": { "description": "Requests allowed in the current window.", "schema": { "type": "integer" } }, "RateLimitRemaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimitReset": { "description": "Unix epoch seconds when the current window resets.", "schema": { "type": "integer" } }, "RetryAfter": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "schemas": { "Error": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "code": { "type": "string", "description": "A stable reason to branch on, when there is one. `licence_required`: this instance has no Talon key, and every route answers 403 until an admin adds one on the License page." }, "error": { "type": "string", "description": "The same text as `message`, sent alongside `code` for the app's own clients." } }, "required": [ "message" ] }, "PageMeta": { "type": "object", "properties": { "page": { "type": "integer" }, "perPage": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "required": [ "page", "perPage", "total", "totalPages" ] }, "DetectionListItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "workspaceId": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "mitreTactic": { "type": [ "string", "null" ] }, "mitreTechniqueId": { "type": [ "string", "null" ] }, "mitreTechniqueIds": { "type": "array", "items": { "type": "string" } }, "confidence": { "type": [ "string", "null" ] }, "sourcetype": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "description", "workspaceId", "status", "mitreTactic", "mitreTechniqueId", "mitreTechniqueIds", "confidence", "sourcetype", "createdAt", "updatedAt" ] }, "DetectionDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "workspaceId": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "mitreTactic": { "type": [ "string", "null" ] }, "mitreTechniqueId": { "type": [ "string", "null" ] }, "mitreTechniqueIds": { "type": "array", "items": { "type": "string" } }, "severity": { "type": [ "string", "null" ] }, "riskScore": { "type": [ "integer", "null" ] }, "sourcetype": { "type": [ "string", "null" ] }, "spl": { "type": [ "string", "null" ] }, "kql": { "type": [ "string", "null" ] }, "sigma": { "type": [ "string", "null" ] }, "eql": { "type": [ "string", "null" ] }, "yaraL": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "workspaceId", "status", "mitreTechniqueIds" ] }, "Workspace": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "siemTarget": { "type": [ "string", "null" ] }, "requiresChangeRequests": { "type": "boolean" }, "detectionCount": { "type": "integer" }, "sourcetypeCount": { "type": "integer" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "description", "siemTarget", "requiresChangeRequests", "detectionCount", "sourcetypeCount", "createdAt", "updatedAt" ] }, "Alert": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "source": { "type": "string" }, "severity": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "candidate", "promoted", "dismissed" ] }, "techniqueId": { "type": [ "string", "null" ] }, "detectionId": { "type": [ "string", "null" ], "format": "uuid" }, "occurredAt": { "type": "string" } }, "required": [ "id", "title", "source", "severity", "status", "techniqueId", "detectionId", "occurredAt" ] }, "Case": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "investigating", "resolved", "false_positive" ] }, "priority": { "type": [ "string", "null" ] }, "severity": { "type": [ "string", "null" ] }, "techniqueId": { "type": [ "string", "null" ] }, "detectionId": { "type": [ "string", "null" ], "format": "uuid" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "title", "status", "priority", "severity", "techniqueId", "detectionId", "createdAt", "updatedAt" ] }, "DeploymentTarget": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "endpoint": { "type": "string" }, "kind": { "type": "string" }, "siemType": { "type": "string" }, "scope": { "type": "string", "enum": [ "workspace", "org" ] }, "isDefault": { "type": "boolean" }, "autoDeploy": { "type": "boolean" }, "deployBranch": { "type": "string" }, "healthStatus": { "type": "string" }, "lastUsedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "endpoint", "kind", "siemType", "scope", "isDefault", "autoDeploy", "deployBranch", "healthStatus", "lastUsedAt", "createdAt", "updatedAt" ] }, "Integration": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "transport": { "type": "string" }, "endpoint": { "type": "string" }, "scope": { "type": "string", "enum": [ "workspace", "org" ] }, "status": { "type": "string" }, "agentAccess": { "type": "string" }, "lastSyncedAt": { "type": [ "string", "null" ] }, "lastError": { "type": [ "string", "null" ] } }, "required": [ "id", "type", "transport", "endpoint", "scope", "status", "agentAccess", "lastSyncedAt", "lastError" ] }, "KanbanCard": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "columnId": { "type": "string", "format": "uuid" }, "columnTitle": { "type": "string" }, "columnStatus": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "priority": { "type": "string" }, "progress": { "type": "integer" }, "source": { "type": "string", "enum": [ "human", "agent" ] }, "agentName": { "type": [ "string", "null" ] }, "assignees": { "type": "array", "items": { "type": "string" } }, "dueDate": { "type": [ "string", "null" ] } }, "required": [ "id", "columnId", "columnTitle", "columnStatus", "title", "type", "priority", "progress", "source", "agentName", "assignees", "dueDate" ] }, "AgentRun": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": [ "string", "null" ], "format": "uuid" }, "agentName": { "type": "string" }, "trigger": { "type": "string" }, "status": { "type": "string" }, "summary": { "type": [ "string", "null" ] }, "proposals": { "type": "integer" }, "staged": { "type": "integer" }, "failures": { "type": "integer" }, "changeRequestIds": { "type": "array", "items": { "type": "string" } }, "startedAt": { "type": "string" }, "finishedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "workspaceId", "agentName", "trigger", "status", "summary", "proposals", "staged", "failures", "changeRequestIds", "startedAt", "finishedAt" ] }, "AgentRunStep": { "type": "object", "properties": { "seq": { "type": "integer" }, "kind": { "type": "string" }, "status": { "type": "string" }, "label": { "type": "string" }, "toolName": { "type": [ "string", "null" ] }, "detail": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "seq", "kind", "status", "label", "toolName", "detail", "createdAt" ] }, "AgentRunDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": [ "string", "null" ], "format": "uuid" }, "agentName": { "type": "string" }, "trigger": { "type": "string" }, "status": { "type": "string" }, "summary": { "type": [ "string", "null" ] }, "task": { "type": [ "string", "null" ] }, "proposals": { "type": "integer" }, "staged": { "type": "integer" }, "failures": { "type": "integer" }, "changeRequestIds": { "type": "array", "items": { "type": "string" } }, "inputTokens": { "type": [ "integer", "null" ] }, "outputTokens": { "type": [ "integer", "null" ] }, "startedAt": { "type": "string" }, "finishedAt": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/AgentRunStep" } } }, "required": [ "id", "workspaceId", "agentName", "trigger", "status", "summary", "task", "proposals", "staged", "failures", "changeRequestIds", "inputTokens", "outputTokens", "startedAt", "finishedAt", "steps" ] }, "AuditLog": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "action": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "actorName": { "type": [ "string", "null" ] }, "actorEmail": { "type": [ "string", "null" ] }, "targetName": { "type": [ "string", "null" ] }, "targetEmail": { "type": [ "string", "null" ] }, "ipAddress": { "type": [ "string", "null" ] }, "userAgent": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" } }, "required": [ "id", "action", "category", "status", "message", "metadata", "actorName", "actorEmail", "targetName", "targetEmail", "ipAddress", "userAgent", "createdAt" ] }, "User": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "displayName": { "type": [ "string", "null" ] }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "engineer", "analyst", "readonly" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "displayName", "email", "role", "createdAt", "updatedAt" ] }, "TokenIdentity": { "type": "object", "properties": { "token": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "user", "service" ] }, "scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "kind", "scopes" ] }, "orgId": { "type": "string", "format": "uuid" }, "workspaceId": { "type": [ "string", "null" ], "format": "uuid" }, "userId": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "token", "orgId", "workspaceId", "userId" ] }, "CoverageSummary": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "defaultSiemType": { "type": [ "string", "null" ] }, "totals": { "type": "object", "additionalProperties": true } }, "required": [ "workspaceId", "defaultSiemType", "totals" ] }, "TechniqueGap": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "groupCount": { "type": "integer" }, "campaignCount": { "type": "integer" }, "adversaryCount": { "type": "integer" }, "covered": { "type": "boolean" } }, "required": [ "id", "name", "groupCount", "campaignCount", "adversaryCount", "covered" ] }, "AdversaryTechniqueRef": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "covered": { "type": "boolean" } }, "required": [ "id", "name", "covered" ] }, "AdversarySummary": { "type": "object", "properties": { "id": { "type": "string", "description": "ATT&CK group (G####) or campaign (C####) id." }, "name": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "techniqueCount": { "type": "integer" }, "coveredCount": { "type": "integer" }, "attributedTo": { "type": "array", "items": { "type": "string" } }, "relevantToProfile": { "type": "boolean" }, "pinned": { "type": "boolean" } }, "required": [ "id", "name", "aliases", "techniqueCount", "coveredCount" ] }, "AdversaryDetail": { "allOf": [ { "$ref": "#/components/schemas/AdversarySummary" }, { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "techniques": { "type": "array", "items": { "$ref": "#/components/schemas/AdversaryTechniqueRef" } }, "procedureExamples": { "type": "array", "items": { "$ref": "#/components/schemas/ProcedureExample" } } }, "required": [ "techniques", "procedureExamples" ] } ] }, "AdversaryComparison": { "type": "object", "properties": { "adversaries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "techniqueCount": { "type": "integer" }, "coveredCount": { "type": "integer" }, "uncoveredCount": { "type": "integer" } }, "required": [ "id", "name", "techniqueCount", "coveredCount", "uncoveredCount" ] } }, "sharedGaps": { "type": "array", "description": "Uncovered techniques every compared adversary uses — closing one closes a gap against all of them.", "items": { "$ref": "#/components/schemas/AdversaryTechniqueRef" } }, "uniqueGaps": { "type": "array", "items": { "type": "object", "properties": { "adversaryId": { "type": "string" }, "adversaryName": { "type": "string" }, "techniques": { "type": "array", "items": { "$ref": "#/components/schemas/AdversaryTechniqueRef" } } }, "required": [ "adversaryId", "adversaryName", "techniques" ] } } }, "required": [ "adversaries", "sharedGaps", "uniqueGaps" ] }, "ProcedureExample": { "type": "object", "properties": { "adversaryId": { "type": "string" }, "adversaryName": { "type": "string" }, "techniqueId": { "type": "string" }, "description": { "type": "string" } }, "required": [ "adversaryId", "adversaryName", "techniqueId", "description" ] }, "MitreTechniqueDetail": { "type": "object", "description": "One technique from the synced ATT&CK catalogue, with adversary/defence context and MITRE procedure examples.", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "tactic": { "type": "string" }, "tacticsList": { "type": "array", "items": { "type": "string" } }, "dataComponents": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "threatGroups": { "type": "array", "items": { "type": "string" } }, "campaigns": { "type": "array", "items": { "type": "string" } }, "software": { "type": "array", "items": { "type": "string" } }, "mitigations": { "type": "array", "items": { "type": "string" } }, "nistControls": { "type": "array", "items": { "type": "string" } }, "procedureExamples": { "type": "array", "items": { "$ref": "#/components/schemas/ProcedureExample" } } }, "required": [ "id", "name", "tactic", "procedureExamples" ] }, "NavigatorLayer": { "type": "object", "description": "An ATT&CK Navigator layer (layer format 4.5). The response body is the layer JSON itself — save it and open it in Navigator.", "properties": { "name": { "type": "string" }, "versions": { "type": "object", "additionalProperties": true }, "domain": { "type": "string" }, "techniques": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "name", "versions", "domain", "techniques" ], "additionalProperties": true }, "ChangeRequestListItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" }, "author": { "type": [ "string", "null" ] }, "files": { "type": "integer" }, "updatedAt": { "type": "string" } }, "required": [ "id", "title", "status", "author", "files", "updatedAt" ] }, "ThreatFeed": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "indicatorCount": { "type": "integer" } }, "required": [ "slug", "name", "enabled", "indicatorCount" ] }, "DetectionStandard": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "enforcement": { "type": "string", "enum": [ "warn", "block" ] }, "isActiveStandard": { "type": "boolean" }, "isOrgDefault": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "name", "description", "enforcement", "isActiveStandard", "isOrgDefault", "createdAt" ] }, "NotificationIntegration": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "integrationId": { "type": "string", "enum": [ "slack", "teams" ] }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "connectionStatus": { "type": "string" }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "minSeverity": { "type": [ "string", "null" ] }, "workspaceIds": { "type": [ "array", "null" ], "items": { "type": "string" } }, "branchFilter": { "type": [ "array", "null" ], "items": { "type": "string" } }, "lastTestedAt": { "type": [ "string", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "integrationId", "name", "enabled", "connectionStatus", "eventTypes", "minSeverity", "workspaceIds", "branchFilter", "lastTestedAt", "lastError", "createdAt", "updatedAt" ] }, "LicenseState": { "type": "object", "properties": { "active": { "type": "boolean" }, "status": { "type": "string", "enum": [ "missing", "active" ], "description": "`missing` is the Community Edition: a Community key, or a paid key that stopped counting. `active` is a paid key in force. With no key at all the instance answers 403 `licence_required` instead of this object." }, "reason": { "type": "string", "examples": [ "Community Edition, licensed to Acme Security Ltd." ] }, "expiresAt": { "type": [ "string", "null" ] }, "maxStreams": { "type": [ "integer", "null" ] }, "maxDetections": { "type": [ "integer", "null" ] }, "trial": { "type": "boolean" }, "trialExpired": { "type": "boolean" }, "tier": { "type": [ "string", "null" ], "enum": [ "team", "enterprise", null ], "description": "The paid tier; null on the Community Edition. `team` is still honoured for keys already issued but is not an edition on sale." } }, "required": [ "active", "status", "reason", "expiresAt", "maxStreams", "maxDetections", "trial", "trialExpired", "tier" ] }, "Sourcetype": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "sourceType": { "type": "string" }, "sourceStatus": { "type": "string" }, "sourcetype": { "type": "string" }, "schemaType": { "type": "string", "enum": [ "CIM", "ECS", "OCSF", "ASIM", "UNKNOWN" ] }, "fieldsPresent": { "type": "array", "items": { "type": "string" } }, "fieldsMissing": { "type": "array", "items": { "type": "string" } }, "mitreDetectable": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "mitreNotDetectable": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "normalizationStatus": { "type": [ "string", "null" ] }, "retentionDays": { "type": [ "integer", "null" ] }, "dataClassification": { "type": [ "string", "null" ], "enum": [ "public", "internal", "confidential", "restricted", null ] }, "lastSeenAt": { "type": [ "string", "null" ] }, "lastClassifiedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "description", "sourceType", "sourceStatus", "sourcetype", "schemaType", "fieldsPresent", "fieldsMissing", "mitreDetectable", "mitreNotDetectable", "normalizationStatus", "retentionDays", "dataClassification", "lastSeenAt", "lastClassifiedAt", "createdAt", "updatedAt" ] }, "Blueprint": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "streamId": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "template", "standard" ] }, "isActiveStandard": { "type": "boolean" }, "enforcement": { "type": "string", "enum": [ "warn", "block" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "workspaceId", "streamId", "name", "description", "kind", "isActiveStandard", "enforcement", "createdAt", "updatedAt" ] }, "BlueprintDetail": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "streamId": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "template", "standard" ] }, "graph": { "type": "object", "additionalProperties": true }, "preview": { "type": [ "object", "null" ], "additionalProperties": true }, "conformance": { "type": [ "object", "null" ], "additionalProperties": true }, "isActiveStandard": { "type": "boolean" }, "enforcement": { "type": "string", "enum": [ "warn", "block" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "workspaceId", "streamId", "name", "description", "kind", "graph", "preview", "conformance", "isActiveStandard", "enforcement", "createdAt", "updatedAt" ] }, "ValidationSummary": { "type": "object", "properties": { "total": { "type": "integer" }, "ready": { "type": "integer" }, "notReady": { "type": "integer" }, "readinessUnknown": { "type": "integer" }, "readinessScore": { "type": "number" }, "simPassing": { "type": "integer" }, "simFailing": { "type": "integer" }, "simNotRun": { "type": "integer" }, "driftDetected": { "type": "integer" }, "degraded": { "type": "integer" }, "openGaps": { "type": "integer" } }, "required": [ "total", "ready", "notReady", "readinessUnknown", "readinessScore", "simPassing", "simFailing", "simNotRun", "driftDetected", "degraded", "openGaps" ], "additionalProperties": true }, "DeploymentState": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "deployed", "ready", "blocked", "in_progress", "empty" ] }, "ready": { "type": "boolean" }, "deployed": { "type": "boolean" }, "blockers": { "type": "array", "items": { "type": "string" } }, "checks": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "latestRelease": { "type": [ "object", "null" ], "properties": { "siemType": { "type": "string" }, "buildId": { "type": [ "string", "null" ] }, "deployedAt": { "type": [ "string", "null" ] } } } }, "required": [ "state", "ready", "deployed", "blockers", "checks", "latestRelease" ] }, "SearchSources": { "type": "object", "properties": { "federationEntitled": { "type": "boolean" }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "siem", "cribl_lake" ] }, "type": { "type": "string" }, "label": { "type": "string" } }, "required": [ "id", "kind", "type", "label" ] } }, "datasets": { "type": "array", "items": { "type": "string" } } }, "required": [ "federationEntitled", "sources", "datasets" ] }, "SearchProviderResult": { "type": "object", "properties": { "provider": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "label": { "type": "string" } }, "required": [ "id", "kind", "label" ] }, "status": { "type": "string", "enum": [ "running", "done", "error", "skipped", "cancelled" ] }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } }, "description": "Raw provider rows (e.g. Splunk/Cribl fields, may include `_raw`)." }, "rowCount": { "type": "integer" }, "truncated": { "type": "boolean" }, "message": { "type": [ "string", "null" ] } }, "required": [ "provider", "status", "rows", "rowCount", "truncated" ] }, "SearchResult": { "type": "object", "properties": { "federated": { "type": "boolean" }, "spec": { "type": "object", "additionalProperties": true }, "providerCount": { "type": "integer" }, "mergedRowCount": { "type": "integer" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchProviderResult" } } }, "required": [ "federated", "spec", "providerCount", "mergedRowCount", "results" ] } } }, "paths": { "/me": { "get": { "tags": [ "Identity" ], "summary": "Token identity", "operationId": "getMe", "responses": { "200": { "description": "The presented token identity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenIdentity" }, "examples": { "workspaceToken": { "summary": "A workspace-scoped service token", "value": { "token": { "id": "9b2d6c1e-4f3a-4e8b-9d7c-1a2b3c4d5e6f", "kind": "service", "scopes": [ "me:read", "detections:read", "coverage:read" ] }, "orgId": "2f6e8a4c-1b3d-4c5e-8f7a-9b0c1d2e3f4a", "workspaceId": "7c1a9e3b-5d2f-4a6c-8e0b-3f4a5b6c7d8e", "userId": null } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "me:read" } }, "/workspaces": { "get": { "tags": [ "Workspaces" ], "summary": "List workspaces", "operationId": "listWorkspaces", "responses": { "200": { "description": "Workspaces in the token reach", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Workspace" } } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "workspaces:read" } }, "/workspaces/{id}": { "get": { "tags": [ "Workspaces" ], "summary": "Get a workspace", "operationId": "getWorkspace", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Workspace" } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "workspaces:read" } }, "/detections": { "get": { "tags": [ "Detections" ], "summary": "List detections (paginated)", "operationId": "listDetections", "parameters": [ { "name": "workspaceId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Target workspace (required for org-scoped tokens on this route)." }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "perPage", "in": "query", "schema": { "type": "integer", "maximum": 100 } } ], "responses": { "200": { "description": "A page of detections", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DetectionListItem" } }, "meta": { "$ref": "#/components/schemas/PageMeta" }, "links": { "type": "object" } }, "required": [ "data", "meta", "links" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "detections:read" }, "post": { "tags": [ "Detections" ], "summary": "Propose a detection (stages a draft change request)", "operationId": "proposeDetection", "description": "Propose-only: stages a draft change request for human review. Requires a user-scoped token. Exactly one of `sigma` or `spl` must be provided.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "name", "streamId" ], "properties": { "name": { "type": "string", "maxLength": 200 }, "streamId": { "type": "string", "format": "uuid" }, "sigma": { "type": "string", "maxLength": 20000 }, "spl": { "type": "string", "maxLength": 20000 }, "mitreTechniqueId": { "type": "string", "maxLength": 24 }, "description": { "type": "string", "maxLength": 2000 }, "workspaceId": { "type": "string", "format": "uuid" } } }, { "anyOf": [ { "required": [ "sigma" ] }, { "required": [ "spl" ] } ] } ] } } } }, "responses": { "201": { "description": "A draft change request was staged", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "detections:propose" } }, "/detections/{id}": { "get": { "tags": [ "Detections" ], "summary": "Get a detection", "operationId": "getDetection", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The detection, returned as a flat object (no data envelope), including its query content per language (spl/kql/sigma/eql/yaraL).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetectionDetail" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "detections:read" }, "patch": { "tags": [ "Detections" ], "summary": "Propose an edit to a detection (stages a draft change request)", "operationId": "proposeDetectionEdit", "description": "Propose-only: stages a draft change request for human review, exactly like POST /detections. Requires a user-scoped token and at least one field.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "name": { "type": "string", "maxLength": 200 }, "sigma": { "type": "string", "maxLength": 20000 }, "spl": { "type": "string", "maxLength": 20000 }, "mitreTechniqueId": { "type": "string", "maxLength": 24 }, "description": { "type": "string", "maxLength": 2000 } } } } } }, "responses": { "202": { "description": "A draft change request was staged for this edit", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "detections:propose" } }, "/coverage": { "get": { "tags": [ "Coverage" ], "summary": "Coverage totals for a workspace", "operationId": "getCoverage", "parameters": [ { "name": "workspaceId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Target workspace (required for org-scoped tokens on this route)." } ], "responses": { "200": { "description": "Coverage totals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CoverageSummary" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "coverage:read" } }, "/coverage/gaps": { "get": { "tags": [ "Coverage" ], "summary": "Uncovered techniques ranked by adversary leverage", "description": "Which detection is highest-value to write next: uncovered ATT&CK techniques ordered by how many groups and campaigns use each.", "operationId": "listCoverageGaps", "parameters": [ { "name": "workspaceId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Target workspace (required for org-scoped tokens on this route)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Ranked coverage gaps", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TechniqueGap" } } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "coverage:read" } }, "/coverage/navigator-layer": { "get": { "tags": [ "Coverage" ], "summary": "ATT&CK Navigator layer of workspace coverage", "description": "Coverage as a Navigator layer (format 4.5), scored by validation evidence. With `adversary`, restricted to that adversary’s techniques with red gap cells. The response body is the layer JSON itself.", "operationId": "getNavigatorLayer", "parameters": [ { "name": "workspaceId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Target workspace (required for org-scoped tokens on this route)." }, { "name": "adversary", "in": "query", "schema": { "type": "string" }, "description": "An ATT&CK group/campaign id, name, or alias." } ], "responses": { "200": { "description": "The Navigator layer JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NavigatorLayer" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "coverage:read" } }, "/adversaries": { "get": { "tags": [ "Adversaries" ], "summary": "List adversaries with coverage, or fetch one in full", "description": "Summary rows for every ATT&CK group and campaign with the workspace’s coverage counts. With `name` (a G/C id, canonical name, or alias) returns that one adversary in full — techniques, coverage, and MITRE procedure examples.", "operationId": "listAdversaries", "parameters": [ { "name": "workspaceId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Target workspace (required for org-scoped tokens on this route)." }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Resolve one adversary by id, name, or alias." } ], "responses": { "200": { "description": "Adversary summaries, or one adversary in full", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "oneOf": [ { "type": "object", "properties": { "groups": { "type": "array", "items": { "$ref": "#/components/schemas/AdversarySummary" } }, "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/AdversarySummary" } } }, "required": [ "groups", "campaigns" ] }, { "$ref": "#/components/schemas/AdversaryDetail" } ] } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "coverage:read" } }, "/adversaries/compare": { "get": { "tags": [ "Adversaries" ], "summary": "Compare coverage against 2–5 adversaries", "description": "Set algebra over the compared adversaries’ techniques: `sharedGaps` are uncovered techniques every one of them uses; `uniqueGaps` the uncovered techniques exclusive to each.", "operationId": "compareAdversaries", "parameters": [ { "name": "workspaceId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Target workspace (required for org-scoped tokens on this route)." }, { "name": "adversaries", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma-separated ids, names, or aliases (2–5)." } ], "responses": { "200": { "description": "The comparison", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdversaryComparison" } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "coverage:read" } }, "/mitre/techniques/{techniqueId}": { "get": { "tags": [ "MITRE" ], "summary": "One ATT&CK technique from the synced catalogue", "description": "Definition, tactics, data components, adversary/defence context, and MITRE’s per-adversary procedure examples. 404s carry near-match suggestions.", "operationId": "getMitreTechnique", "parameters": [ { "name": "techniqueId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A technique or sub-technique id, e.g. T1059.001." } ], "responses": { "200": { "description": "The technique", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MitreTechniqueDetail" } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "coverage:read" } }, "/alerts": { "get": { "tags": [ "Alerts" ], "summary": "List SOC alert candidates", "operationId": "listAlerts", "parameters": [ { "name": "workspaceId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Target workspace (required for org-scoped tokens on this route)." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "candidate", "promoted", "dismissed" ] } } ], "responses": { "200": { "description": "Alert candidates", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Alert" } } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "alerts:read" } }, "/alerts/{id}": { "patch": { "tags": [ "Alerts" ], "summary": "Dismiss (close) an alert", "operationId": "dismissAlert", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "dismissed" ] }, "workspaceId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "The alert was dismissed", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "alerts:write" } }, "/cases": { "get": { "tags": [ "SOC Cases" ], "summary": "List SOC cases", "operationId": "listCases", "parameters": [ { "name": "workspaceId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Target workspace (required for org-scoped tokens on this route)." }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "investigating", "resolved", "false_positive" ] } } ], "responses": { "200": { "description": "Cases for the workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Case" } } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "cases:read" }, "post": { "tags": [ "SOC Cases" ], "summary": "Promote an alert to a case", "operationId": "promoteCase", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "candidateId" ], "properties": { "candidateId": { "type": "string", "format": "uuid" }, "title": { "type": "string", "maxLength": 200 }, "severity": { "type": "string", "maxLength": 24 }, "workspaceId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "description": "The candidate was promoted to a case", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "cases:write" } }, "/cases/{id}": { "get": { "tags": [ "SOC Cases" ], "summary": "Get a case (with activity + linked alerts)", "operationId": "getCase", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workspaceId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Target workspace (required for org-scoped tokens on this route)." } ], "responses": { "200": { "description": "The case detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Case" } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "cases:read" } }, "/deployment-targets": { "get": { "tags": [ "Deployments" ], "summary": "List deployment targets for a workspace", "operationId": "listDeploymentTargets", "parameters": [ { "name": "workspaceId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Target workspace (required for org-scoped tokens on this route)." } ], "responses": { "200": { "description": "Deployment targets (no credentials)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeploymentTarget" } } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "deployments:read" } }, "/deployments": { "get": { "tags": [ "Deployments" ], "summary": "Get a workspace's deploy-readiness state", "operationId": "getDeploymentState", "parameters": [ { "name": "workspaceId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Target workspace (required for org-scoped tokens on this route)." } ], "responses": { "200": { "description": "Deploy state, blockers, and latest release", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentState" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "deployments:read" } }, "/integrations": { "get": { "tags": [ "Integrations" ], "summary": "List connected SIEMs for a workspace", "operationId": "listIntegrations", "parameters": [ { "name": "workspaceId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Target workspace (required for org-scoped tokens on this route)." } ], "responses": { "200": { "description": "Connected SIEMs (no credentials)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Integration" } } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "integrations:read" } }, "/kanban/cards": { "get": { "tags": [ "Workboard" ], "summary": "List workboard cards", "operationId": "listKanbanCards", "parameters": [ { "name": "workspaceId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Target workspace (required for org-scoped tokens on this route)." } ], "responses": { "200": { "description": "Cards flattened with their column", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/KanbanCard" } } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "kanban:read" }, "post": { "tags": [ "Workboard" ], "summary": "Create a workboard card", "operationId": "createKanbanCard", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "columnId", "title" ], "properties": { "columnId": { "type": "string", "format": "uuid" }, "title": { "type": "string", "maxLength": 200 }, "description": { "type": "string", "maxLength": 4000 }, "type": { "type": "string", "enum": [ "epic", "task", "investigation", "bug", "incident", "improvement", "hardening" ] }, "priority": { "type": "string", "enum": [ "High", "Medium", "Low" ] }, "workspaceId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "description": "The card was created", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "kanban:write" } }, "/agent-runs": { "get": { "tags": [ "Agents" ], "summary": "List agent runs", "operationId": "listAgentRuns", "parameters": [ { "name": "workspaceId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Target workspace (required for org-scoped tokens on this route)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 200 } } ], "responses": { "200": { "description": "Recent agent runs, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentRun" } } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "agents:read" } }, "/agent-runs/{id}": { "get": { "tags": [ "Agents" ], "summary": "Get an agent run (with step timeline)", "operationId": "getAgentRun", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "workspaceId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Target workspace (required for org-scoped tokens on this route)." } ], "responses": { "200": { "description": "The agent run detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AgentRunDetail" } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "agents:read" } }, "/change-requests": { "get": { "tags": [ "Change Requests" ], "summary": "List change requests", "operationId": "listChangeRequests", "parameters": [ { "name": "workspaceId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Target workspace (required for org-scoped tokens on this route)." } ], "responses": { "200": { "description": "Change requests for the workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChangeRequestListItem" } } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "change_requests:read" } }, "/threat-feeds": { "get": { "tags": [ "Threat Intel" ], "summary": "List threat-intel feeds", "operationId": "listThreatFeeds", "parameters": [ { "name": "workspaceId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Target workspace (required for org-scoped tokens on this route)." } ], "responses": { "200": { "description": "Threat-intel feeds", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ThreatFeed" } } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "threat_feeds:read" } }, "/standards": { "get": { "tags": [ "Standards" ], "summary": "List detection standards", "operationId": "listStandards", "parameters": [ { "name": "workspaceId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Target workspace (required for org-scoped tokens on this route)." } ], "responses": { "200": { "description": "Detection standards for the workspace", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DetectionStandard" } } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "standards:read" } }, "/audit-logs": { "get": { "tags": [ "Audit" ], "summary": "List the organisation audit log", "operationId": "listAuditLogs", "description": "Requires an org-scoped token with the audit:read scope. Walk the full trail by passing the previous page's nextCursor as cursor.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 2000, "default": 200 } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Only entries created at or after this time." }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Only entries created at or before this time." }, { "name": "cursor", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "The previous page's nextCursor (its oldest createdAt); returns entries older than it." } ], "responses": { "200": { "description": "Audit log entries, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLog" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as cursor for the next page; null when the page was not full." } }, "required": [ "data", "nextCursor" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "audit:read" } }, "/users": { "get": { "tags": [ "Users" ], "summary": "List the org's member roster", "operationId": "listUsers", "description": "Requires an org-scoped token with the `users:read` scope, which is `administer`-capability-gated — only an admin-created token can ever hold it. Known limitation: the scope grant is checked against the live `role` enum only and does not currently honour custom roles.", "responses": { "200": { "description": "Active org members, ordered by creation date", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "users:read" } }, "/notifications": { "get": { "tags": [ "Notifications" ], "summary": "List notification integrations", "operationId": "listNotifications", "description": "Requires an org-scoped token — notification integrations are org-wide, not workspace-partitioned. Webhook URLs are encrypted and never returned.", "responses": { "200": { "description": "The org's Slack/Teams notification integrations", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationIntegration" } } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "notifications:read" } }, "/license": { "get": { "tags": [ "License" ], "summary": "Get the org license/entitlement state", "operationId": "getLicense", "description": "Requires an org-scoped token.", "responses": { "200": { "description": "License tier, expiry, and stream/detection caps", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseState" }, "examples": { "community": { "summary": "The Community Edition", "value": { "active": true, "status": "missing", "reason": "Community Edition, licensed to Acme Security Ltd.", "expiresAt": null, "maxStreams": 3, "maxDetections": null, "trial": false, "trialExpired": false, "tier": null } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "license:read" } }, "/sourcetypes": { "get": { "tags": [ "Sourcetypes" ], "summary": "List a workspace's classified data sourcetypes", "operationId": "listSourcetypes", "parameters": [ { "name": "workspaceId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Target workspace (required for org-scoped tokens on this route)." } ], "responses": { "200": { "description": "Sourcetypes with schema-type and field coverage", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Sourcetype" } } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "sourcetypes:read" } }, "/blueprints": { "get": { "tags": [ "Blueprints" ], "summary": "List Forge blueprints", "operationId": "listBlueprints", "parameters": [ { "name": "workspaceId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Target workspace (required for org-scoped tokens on this route)." } ], "responses": { "200": { "description": "Blueprints and standards (excludes stream-less templates)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Blueprint" } } }, "required": [ "data" ] } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "blueprints:read" } }, "/blueprints/{id}": { "get": { "tags": [ "Blueprints" ], "summary": "Get a Forge blueprint", "operationId": "getBlueprint", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The blueprint, including its graph and conformance spec", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintDetail" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "blueprints:read" } }, "/validate/summary": { "get": { "tags": [ "Validate" ], "summary": "Get a workspace's validation readiness summary", "operationId": "getValidationSummary", "parameters": [ { "name": "workspaceId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Target workspace (required for org-scoped tokens on this route)." } ], "responses": { "200": { "description": "Readiness spine + simulation bonus + drift/gap signals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationSummary" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "validate:read" } }, "/search/sources": { "get": { "tags": [ "Search" ], "summary": "List searchable sources for a workspace", "operationId": "listSearchSources", "description": "DB metadata only — no live query, no raw log content. Lists which Cribl Lake connections and connected SIEMs have search access enabled, and whether federation (searching more than one at once) is entitled.", "parameters": [ { "name": "workspaceId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Target workspace (required for org-scoped tokens on this route)." } ], "responses": { "200": { "description": "Searchable sources, federation entitlement, known datasets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchSources" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "search:read" } }, "/search": { "post": { "tags": [ "Search" ], "summary": "Run a federated log search", "operationId": "executeSearch", "description": "Live query against Cribl Lake and/or connected SIEMs — results may include raw log content (e.g. Splunk `_raw`), not just Talon metadata. Row/lookback caps match the AI-agent tool tier (25 rows, 7-day lookback max), tighter than the human Search page (500 rows, 30 days), since this is an unattended credential. Rate-limited by a dedicated, tighter per-token bucket in addition to the standard one. Searching more than one source at once (`federated: true` in the response) requires an Enterprise license. Conceptually a candidate for the HTTP `QUERY` method (safe, no Talon-side mutation) once tooling supports it — see the API description's note on RFC 10008; implemented as POST today.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "dataset": { "type": "string", "maxLength": 200 }, "contains": { "type": "string", "maxLength": 200 }, "limit": { "type": "integer", "minimum": 1, "maximum": 25 }, "earliest": { "type": "string", "description": "Relative lookback like -1h or -7d. Capped at -7d." }, "sourceIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20 }, "rawQuery": { "type": "string", "maxLength": 4000, "description": "Cribl/KQL passthrough. Honoured by Cribl Lake sources only." } }, "description": "Exactly one of `dataset` (guided) or `rawQuery` (raw) is required." } } } }, "responses": { "200": { "description": "Merged per-provider results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized: no bearer token, or one that is invalid, expired or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing": { "summary": "No bearer token", "value": { "message": "Missing bearer token" } }, "invalid": { "summary": "Unknown or revoked token", "value": { "message": "Invalid or revoked token" } } } } } }, "403": { "description": "Forbidden. With `code: licence_required`, this instance has no Talon key and every route answers this until an admin adds one — the most likely first error on a fresh install. Otherwise the token lacks the scope, the workspace or the source IP.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "licence_required": { "summary": "This instance has no Talon key", "value": { "message": "This instance needs a Talon key. An admin can add one on the License page.", "error": "This instance needs a Talon key. An admin can add one on the License page.", "code": "licence_required" } }, "scope": { "summary": "The token lacks the scope", "value": { "message": "Token lacks the \"detections:read\" scope" } } } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "limited": { "summary": "Too many requests", "value": { "message": "Rate limit exceeded" } } } } }, "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } } } }, "x-scope": "search:execute" } } } }