---
title: "List Threats"
method: GET
path: "/api/threats"
tags: ["Hunt"]
---

# List Threats

`GET /api/threats`

## Request

- Base URL: `https://app.cotool.ai`
- URL: `https://app.cotool.ai/api/threats`
- Auth: HTTP bearer

The durable Threat catalog. Filterable by derived status, canonical type, coverage state, exposure state, hunt result badge, actor, linked Alert state, and free-text query.

## Query parameters

- `q` string
- `status` 'active' | 'assessing' | 'assessment_failed' | 'blocked' | 'monitoring' | 'covered' | 'clear' | 'not_relevant' | 'resolved' | 'dismissed'
- `canonicalType` 'vulnerability' | 'campaign'
- `coverageState` 'none' | 'partial' | 'covered' | 'unknown'
- `exposureState` 'compromise_signal_found' | 'exposure_found' | 'no_exposure_found' | 'inconclusive'
- `huntResultBadge` 'compromise_signal_found' | 'exposure_found' | 'covered_by_existing_detection' | 'no_exposure_found' | 'inconclusive'
- `actorId` string
- `linkedAlertState` 'active' | 'terminal' | 'none'

## Response `200`

Successful response

- object
  - `threats` object[], required
    - `threat` object, required
      - `id` string, required
      - `organizationId` string, required
      - `canonicalType` 'vulnerability' | 'campaign', required
      - `canonicalKeyType` 'cve' | 'advisory' | 'vendor_advisory' | 'campaign_name' | 'malware_family', required
      - `canonicalKey` string, required
      - `title` string, required
      - `aliases` string[], required
      - `actorId` string, nullable, required
      - `intelItemIds` string[], required
      - `relevancyScore` number, nullable, required
      - `exposureScore` number, nullable, required
      - `exposureState` 'compromise_signal_found' | 'exposure_found' | 'no_exposure_found' | 'inconclusive' | 'null', nullable, required
      - `coverageState` 'none' | 'partial' | 'covered' | 'unknown' | 'null', nullable, required
      - `detectionEngineeringNote` string, nullable, required
      - `latestRunId` string, nullable, required
      - `assessmentRunningExecutionId` string, nullable, required
      - `assessmentFailedAt` string, nullable, required
      - `latestAlertId` string, nullable, required
      - `activeHuntAlertId` string, nullable, required
      - `dismissedAt` string, nullable, required
      - `dismissedByUserId` string, nullable, required
      - `dismissedReason` string, nullable, required
      - `createdAt` string, required
      - `updatedAt` string, required
    - `runs` object[], required
      - `id` string, required
      - `threatId` string, required
      - `kind` 'create' | 'update', required
      - `trigger` 'new_threat' | 'intel_attached' | 'manual' | 'backfill' | 'reclassification', required
      - `runAt` string, required
      - `relevancyExecutionId` string, required
      - `relevancyScore` number, required
      - `relevancyHeadline` string, nullable
      - `relevancyExplanation` string[], required
      - `exposureExecutionId` string, nullable, required
      - `exposureScore` number, nullable, required
      - `exposureState` 'compromise_signal_found' | 'exposure_found' | 'no_exposure_found' | 'inconclusive' | 'null', nullable, required
      - `exposureStory` object, nullable, required
        - `exposureState` 'compromise_signal_found' | 'exposure_found' | 'no_exposure_found' | 'inconclusive', required
        - `headline` string
        - `summary` string[], required
        - `exposureChecks` object[], required
          - `purpose` 'exposure' | 'ioc' | 'telemetry' | 'detection_coverage', required
          - `indicatorId` string
          - `authoritative` boolean
          - `iocType` 'ip' | 'domain' | 'url' | 'hash' | 'file_path' | 'process' | 'registry_key' | 'certificate' | 'cloud_id' | 'package' | 'email' | 'user_agent' | 'mutex' | 'other'
          - `indicatorRole` 'compromise' | 'relevance'
          - `checked` string, required
          - `source` string, required
          - `scope` string, required
          - `timeWindow` object, nullable, required
            - `start` string, required
            - `end` string, required
          - `outcome` 'found' | 'not_found' | 'inconclusive', required
          - `evidence` string, required
          - `limitations` string[], required
        - `assets` object[], required
          - `identifier` string, required
          - `kind` 'repository' | 'host' | 'service' | 'cloud_resource' | 'identity' | 'package' | 'domain' | 'saas_account' | 'container_image' | 'other', required
          - `platform` string, nullable, required
          - `source` string, required
          - `internetFacing` boolean, nullable, required
          - `evidence` string, required
        - `iocFindings` object[], required
          - `indicatorId` string
          - `authoritative` boolean
          - `iocType` 'ip' | 'domain' | 'url' | 'hash' | 'file_path' | 'process' | 'registry_key' | 'certificate' | 'cloud_id' | 'package' | 'email' | 'user_agent' | 'mutex' | 'other', required
          - `role` 'compromise' | 'relevance', required
          - `platform` string, nullable, required
          - `iocValue` string, required
          - `evidence` string, required
          - `affectedSystems` string[], required
        - `discoveredIndicators` object[]
          - `indicatorId` string, required: Unique run-local id such as discovered-1.
          - `iocType` 'ip' | 'domain' | 'url' | 'hash' | 'file_path' | 'process' | 'registry_key' | 'certificate' | 'cloud_id' | 'package' | 'email' | 'user_agent' | 'mutex' | 'other', required: Canonical indicator type.
          - `role` 'compromise' | 'relevance', required: Required role with no default.
          - `platform` string: Optional registry/ecosystem for package or image indicators.
          - `iocValue` string, required: One exact atomic indicator value, never a prose/composite description.
          - `roleRationale` string, required: Why a match alone does or does not justify a compromise claim.
          - `evidence` string, required: Cited evidence establishing this as a threat indicator.
        - `observations` object[]
          - `observationId` string, required: Unique run-local observation id.
          - `kind` 'software_presence' | 'vulnerable_asset' | 'configuration_exposure' | 'exploit_attempt' | 'suspicious_behavior' | 'confirmed_malicious_behavior', required: Semantic kind of customer-environment observation.
          - `summary` string, required: Concise statement of what was observed.
          - `evidence` string, required: Cited customer-environment evidence.
          - `affectedSystems` string[], required: Affected customer assets; empty when none.
          - `timeWindow` object
            - `start` string, required: Observation window start.
            - `end` string, required: Observation window end.
        - `researchContext` object[]
          - `contextId` string, required: Unique run-local context id.
          - `summary` string, required: Concise public/intel fact.
          - `evidence` string, required: Cited evidence for the context fact.
        - `conclusion` object
          - `headline` string, required: One self-contained sentence stating the environment verdict and the evidence-based interpretation that determines the score. Never merely report that an indicator matched: if activity is attributable to security inspection, scanning, testing, or another evidenced benign cause, state both the match and that interpretation so the reader immediately understands why it is not concerning. When the exposure score is in the residual band (35-59), state the residual condition — what concretely remains exposed, unpatched, or unverified — never a bare "no exposure found".
          - `summary` string[], required: 3-8 concise bullets explaining the environment verdict.
          - `supportingFindingIds` string[], required: Authoritative input-check or environment-observation ids supporting the verdict, copied verbatim from ids defined in this output; never discovered-indicator ids, context ids, or invented shorthand ids.
          - `contextIds` string[], required: Referenced public/intel context ids.
        - `detectionCoverage` object, required
          - `state` 'none' | 'partial' | 'covered' | 'unknown', required
          - `searches` object[], required
            - `source` string, required
            - `criteria` string, required
            - `resultCount` number, required
            - `evidence` string, required
            - `limitations` string[], required
          - `matches` object[], required
            - `ref` object, required
              - …
            - `coverage` 'partial' | 'covered' | 'unknown', required
            - `rationale` string, required
            - `limitations` string[], required
        - `gaps` object[], required
          - `product` string, required
          - `logSource` string, required
          - `scopeType` 'org' | 'integration' | 'account' | 'environment' | 'asset_group' | 'tenant' | 'domain', required
          - `scopeId` string, nullable, required
          - `scopeKey` string, required
          - `blocking` boolean, required
          - `description` string, required
          - `limitations` string[], required
        - `nextSteps` string[], required
        - `timeline` object[]
          - `timestamp` string, required
          - `description` string, required
        - `executionId` string, required
        - `runAt` string, required
      - `coverageState` 'none' | 'partial' | 'covered' | 'unknown' | 'null', nullable, required
      - `hasFoundIoc` boolean, required
      - `hasBlockingGap` boolean, required
      - `diff` object, nullable, required
        - `prevRunId` string, required
        - `beforeExposureScore` number, nullable, required
        - `afterExposureScore` number, nullable, required
        - `beforeExposureState` 'compromise_signal_found' | 'exposure_found' | 'no_exposure_found' | 'inconclusive' | 'null', nullable, required
        - `afterExposureState` 'compromise_signal_found' | 'exposure_found' | 'no_exposure_found' | 'inconclusive' | 'null', nullable, required
        - `beforeCoverageState` 'none' | 'partial' | 'covered' | 'unknown' | 'null', nullable, required
        - `afterCoverageState` 'none' | 'partial' | 'covered' | 'unknown' | 'null', nullable, required
        - `reasons` string[], required
    - `deliverables` union[], required
      - union
        - object
          - `id` string, required
          - `organizationId` string, required
          - `threatId` string, required
          - `executionId` string, required
          - `createdAt` string, required
          - `supersededById` string, nullable, required
          - `kind` 'rule_proposal', required
          - `proposalId` string, nullable, required
          - `pullRequestUrl` string, nullable, required
          - `intent` string, required
          - `pinning` 'ioc_pinned' | 'behavioral' | 'mixed', required
          - `pinnedIocs` object[], required
            - `type` string, required
            - `value` string, required
          - `targetProduct` string, nullable, required
          - `targetLogSource` string, nullable, required
          - `lifecycleStatus` 'authoring' | 'drafted' | 'in_review' | 'shipped' | 'dismissed' | 'failed', required
        - object
          - `id` string, required
          - `organizationId` string, required
          - `threatId` string, required
          - `executionId` string, required
          - `createdAt` string, required
          - `supersededById` string, nullable, required
          - `kind` 'gap', required
          - `gapId` string, nullable
          - `product` string, required
          - `logSource` string, required
          - `scopeType` 'org' | 'integration' | 'account' | 'environment' | 'asset_group' | 'tenant' | 'domain', required
          - `scopeId` string, nullable, required
          - `scopeKey` string, required
          - `blocking` boolean, required
          - `description` string, required
          - `gapStatus` 'open' | 'resolved' | 'dismissed', required
          - `establishedAt` string, required
          - `statusAt` string, nullable, required
          - `statusActor` union, required
            - object
              - …
            - object
              - …
          - `statusReason` string, nullable, required
          - `otherLinkedThreats` object[]
            - `threatId` string, required
            - `threatTitle` string, required
            - `canonicalKey` string, required
            - `blocking` boolean, required
    - `intelItems` object[], required
      - `id` string, required
      - `title` string, required
      - `publisher` string, required
      - `sourceName` string, nullable
      - `url` string, nullable, required
      - `publishedAt` string, required
      - `tldr` string, nullable, required
      - `attackPath` string[], required
      - `summary` string, nullable
      - `attackTechniques` object[]
        - `id` string, required
        - `name` string, nullable, required
      - `malware` string[]
      - `actors` string[]
      - `platforms` string[]
      - `affectedProducts` object[]
        - `name` string, required
        - `versions` string[], required
      - `eventFirstSeen` string, nullable
      - `eventLastSeen` string, nullable
    - `alerts` object[], required
      - `id` string, uuid, required: Internal alert identifier
      - `displayId` string, required: Human-readable alert identifier
      - `organizationId` string, uuid, required: Organization that owns the alert
      - `organizationName` string, required: URL-safe organization name used in durable alert paths
      - `title` string, required: Human-readable alert title
      - `description` string, nullable, required: Markdown summary or details for the alert
      - `severity` 'low' | 'medium' | 'high' | 'critical' | 'null', nullable, required: Alert severity when known
      - `status` 'open' | 'in_progress' | 'escalated' | 'closed_true_positive' | 'closed_false_positive' | 'closed_true_positive_benign' | 'dismissed' | 'duplicate' | 'expired', required: Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists.
      - `duplicateOfAlertId` string, uuid, nullable: Canonical alert this alert duplicates, when status is duplicate
      - `duplicateCount` integer, required: Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring.
      - `source` object, required: Filter-oriented source attribution for an alert.
        - `category` 'detection' | 'trigger' | 'hunt' | 'api' | 'agent', required: Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent.
        - `name` 'cotool_detection' | 'cotool_code' | 'cotool_signal' | 'hunt' | 'hunt_v2' | 'api' | 'agent' | 'jira' | 'jira-automation' | 'slack' | 'linear' | 'cron' | 'webhook' | 'email' | 'bugcrowd' | 'hackerone' | 'zscaler' | 'darktrace' | 'seon', required: Filter-oriented alert source name. Trigger-created alerts use the trigger type.
        - `triggerType` 'jira' | 'jira-automation' | 'slack' | 'linear' | 'cron' | 'webhook' | 'email' | 'bugcrowd' | 'hackerone' | 'zscaler' | 'darktrace' | 'seon' | 'null', nullable, required: Trigger source when category is trigger
      - `detection` object, nullable, required: Detection attribution for the alert, when known.
        - `id` string, uuid, nullable, required: Cotool detection identifier when known
        - `agentId` string, uuid, nullable, required: Cotool detection agent identifier when known
        - `codeDetectionId` string, uuid, nullable: Code detection identifier when this alert came from Code Mode
        - `ruleId` string, uuid, nullable, required: Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule
        - `name` string, required: Detection display name
        - `kind` 'cotool' | 'cotool_code' | 'cotool_signal' | 'external', required: Whether this detection attribution is internal or extracted. `cotool_signal` alerts were promoted from a signal; their name is the signal type, and `codeDetectionId` is the streaming detection that emitted it.
        - `origin` 'user' | 'orchestrator' | 'null', nullable: Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature.
      - `createdBy` 'agent' | 'trigger' | 'system', required: Actor class that created the alert.
      - `originAgentId` string, uuid, nullable, required: Agent that produced or owns the source flow
      - `originTriggerId` string, uuid, nullable, required: Trigger that created this alert, when source is an external trigger
      - `originRunId` string, uuid, nullable, required: Run that minted the alert, stored as chats.id
      - `originDetectionHitId` string, uuid, nullable, required: Detection hit that produced this alert, when applicable
      - `codeDetectionId` string, uuid, nullable, required: Code detection that produced this alert, when applicable
      - `originCodeDetectionHitId` string, uuid, nullable, required: Code-detection hit that produced this alert, when applicable
      - `externalProvider` 'jira' | 'jira-automation' | 'slack' | 'linear' | 'cron' | 'webhook' | 'email' | 'bugcrowd' | 'hackerone' | 'zscaler' | 'darktrace' | 'seon' | 'null', nullable, required: External trigger provider such as jira, linear, email, or webhook
      - `externalRef` string, nullable, required: Provider-native event, ticket, message, or alert identifier
      - `externalUrl` string, uri, nullable, required: Provider-native URL for the originating object
      - `assignedAgentId` string, uuid, nullable, required: Response agent currently assigned to triage this alert
      - `triageRunId` string, uuid, nullable, required: Latest response-agent triage run for this alert, stored as chats.id
      - `dedupeKey` string, nullable, required: Stable key used for idempotent alert creation
      - `createdAt` string, required: ISO timestamp when the alert was created
      - `updatedAt` string, required: ISO timestamp when the alert was last updated
      - `firstTriagedAt` string, nullable, required: ISO timestamp when triage first started
      - `resolvedAt` string, nullable, required: ISO timestamp when the alert reached a terminal closed status
      - `derivedDisposition` 'true_positive' | 'false_positive' | 'true_positive_benign' | 'null', nullable, required: Disposition derived from terminal alert status
      - `originAgentName` string, nullable, required: Display name for the origin agent, when available
      - `assignedAgentName` string, nullable, required: Display name for the assigned triage agent, when available
      - `triggerSource` 'jira' | 'jira-automation' | 'slack' | 'linear' | 'cron' | 'webhook' | 'email' | 'bugcrowd' | 'hackerone' | 'zscaler' | 'darktrace' | 'seon' | 'null', nullable, required: Trigger source for external-trigger alerts
      - `resolvedByType` 'human' | 'agent' | 'system' | 'null', nullable: Actor class that moved the alert to its terminal status. Null while the alert is not closed.
      - `resolvedByUserId` string, uuid, nullable: User who closed the alert, when a human closed it
      - `resolvedByAgentName` string, nullable: Display name of the agent that closed the alert, when an agent closed it
      - `resolvedReason` string, nullable: Reason recorded with the closing status change, when provided
      - `huntQualifiedBy` 'compromise_signal_found' | 'exposure_found' | 'null', nullable: Qualifying condition that opened this Hunt alert. Null for non-hunt alerts.
      - `alternativeExplanationCount` integer: Number of alternative explanations offered on the latest escalation. Only meaningful while the alert is escalated.
    - `activeHuntAlert` object, nullable, required
      - `id` string, uuid, required: Internal alert identifier
      - `displayId` string, required: Human-readable alert identifier
      - `organizationId` string, uuid, required: Organization that owns the alert
      - `organizationName` string, required: URL-safe organization name used in durable alert paths
      - `title` string, required: Human-readable alert title
      - `description` string, nullable, required: Markdown summary or details for the alert
      - `severity` 'low' | 'medium' | 'high' | 'critical' | 'null', nullable, required: Alert severity when known
      - `status` 'open' | 'in_progress' | 'escalated' | 'closed_true_positive' | 'closed_false_positive' | 'closed_true_positive_benign' | 'dismissed' | 'duplicate' | 'expired', required: Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists.
      - `duplicateOfAlertId` string, uuid, nullable: Canonical alert this alert duplicates, when status is duplicate
      - `duplicateCount` integer, required: Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring.
      - `source` object, required: Filter-oriented source attribution for an alert.
        - `category` 'detection' | 'trigger' | 'hunt' | 'api' | 'agent', required: Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent.
        - `name` 'cotool_detection' | 'cotool_code' | 'cotool_signal' | 'hunt' | 'hunt_v2' | 'api' | 'agent' | 'jira' | 'jira-automation' | 'slack' | 'linear' | 'cron' | 'webhook' | 'email' | 'bugcrowd' | 'hackerone' | 'zscaler' | 'darktrace' | 'seon', required: Filter-oriented alert source name. Trigger-created alerts use the trigger type.
        - `triggerType` 'jira' | 'jira-automation' | 'slack' | 'linear' | 'cron' | 'webhook' | 'email' | 'bugcrowd' | 'hackerone' | 'zscaler' | 'darktrace' | 'seon' | 'null', nullable, required: Trigger source when category is trigger
      - `detection` object, nullable, required: Detection attribution for the alert, when known.
        - `id` string, uuid, nullable, required: Cotool detection identifier when known
        - `agentId` string, uuid, nullable, required: Cotool detection agent identifier when known
        - `codeDetectionId` string, uuid, nullable: Code detection identifier when this alert came from Code Mode
        - `ruleId` string, uuid, nullable, required: Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule
        - `name` string, required: Detection display name
        - `kind` 'cotool' | 'cotool_code' | 'cotool_signal' | 'external', required: Whether this detection attribution is internal or extracted. `cotool_signal` alerts were promoted from a signal; their name is the signal type, and `codeDetectionId` is the streaming detection that emitted it.
        - `origin` 'user' | 'orchestrator' | 'null', nullable: Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature.
      - `createdBy` 'agent' | 'trigger' | 'system', required: Actor class that created the alert.
      - `originAgentId` string, uuid, nullable, required: Agent that produced or owns the source flow
      - `originTriggerId` string, uuid, nullable, required: Trigger that created this alert, when source is an external trigger
      - `originRunId` string, uuid, nullable, required: Run that minted the alert, stored as chats.id
      - `originDetectionHitId` string, uuid, nullable, required: Detection hit that produced this alert, when applicable
      - `codeDetectionId` string, uuid, nullable, required: Code detection that produced this alert, when applicable
      - `originCodeDetectionHitId` string, uuid, nullable, required: Code-detection hit that produced this alert, when applicable
      - `externalProvider` 'jira' | 'jira-automation' | 'slack' | 'linear' | 'cron' | 'webhook' | 'email' | 'bugcrowd' | 'hackerone' | 'zscaler' | 'darktrace' | 'seon' | 'null', nullable, required: External trigger provider such as jira, linear, email, or webhook
      - `externalRef` string, nullable, required: Provider-native event, ticket, message, or alert identifier
      - `externalUrl` string, uri, nullable, required: Provider-native URL for the originating object
      - `assignedAgentId` string, uuid, nullable, required: Response agent currently assigned to triage this alert
      - `triageRunId` string, uuid, nullable, required: Latest response-agent triage run for this alert, stored as chats.id
      - `dedupeKey` string, nullable, required: Stable key used for idempotent alert creation
      - `createdAt` string, required: ISO timestamp when the alert was created
      - `updatedAt` string, required: ISO timestamp when the alert was last updated
      - `firstTriagedAt` string, nullable, required: ISO timestamp when triage first started
      - `resolvedAt` string, nullable, required: ISO timestamp when the alert reached a terminal closed status
      - `derivedDisposition` 'true_positive' | 'false_positive' | 'true_positive_benign' | 'null', nullable, required: Disposition derived from terminal alert status
      - `originAgentName` string, nullable, required: Display name for the origin agent, when available
      - `assignedAgentName` string, nullable, required: Display name for the assigned triage agent, when available
      - `triggerSource` 'jira' | 'jira-automation' | 'slack' | 'linear' | 'cron' | 'webhook' | 'email' | 'bugcrowd' | 'hackerone' | 'zscaler' | 'darktrace' | 'seon' | 'null', nullable, required: Trigger source for external-trigger alerts
      - `resolvedByType` 'human' | 'agent' | 'system' | 'null', nullable: Actor class that moved the alert to its terminal status. Null while the alert is not closed.
      - `resolvedByUserId` string, uuid, nullable: User who closed the alert, when a human closed it
      - `resolvedByAgentName` string, nullable: Display name of the agent that closed the alert, when an agent closed it
      - `resolvedReason` string, nullable: Reason recorded with the closing status change, when provided
      - `huntQualifiedBy` 'compromise_signal_found' | 'exposure_found' | 'null', nullable: Qualifying condition that opened this Hunt alert. Null for non-hunt alerts.
      - `alternativeExplanationCount` integer: Number of alternative explanations offered on the latest escalation. Only meaningful while the alert is escalated.
    - `latestAlert` object, nullable, required
      - `id` string, uuid, required: Internal alert identifier
      - `displayId` string, required: Human-readable alert identifier
      - `organizationId` string, uuid, required: Organization that owns the alert
      - `organizationName` string, required: URL-safe organization name used in durable alert paths
      - `title` string, required: Human-readable alert title
      - `description` string, nullable, required: Markdown summary or details for the alert
      - `severity` 'low' | 'medium' | 'high' | 'critical' | 'null', nullable, required: Alert severity when known
      - `status` 'open' | 'in_progress' | 'escalated' | 'closed_true_positive' | 'closed_false_positive' | 'closed_true_positive_benign' | 'dismissed' | 'duplicate' | 'expired', required: Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. Dismissed, duplicate, and expired alerts are archived and hidden from alert lists.
      - `duplicateOfAlertId` string, uuid, nullable: Canonical alert this alert duplicates, when status is duplicate
      - `duplicateCount` integer, required: Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring.
      - `source` object, required: Filter-oriented source attribution for an alert.
        - `category` 'detection' | 'trigger' | 'hunt' | 'api' | 'agent', required: Broad alert source category. Hunt covers threat-intel exposure alerts minted by the Hunt surface; api covers alerts submitted through an API source; agent covers alerts deliberately created by an agent.
        - `name` 'cotool_detection' | 'cotool_code' | 'cotool_signal' | 'hunt' | 'hunt_v2' | 'api' | 'agent' | 'jira' | 'jira-automation' | 'slack' | 'linear' | 'cron' | 'webhook' | 'email' | 'bugcrowd' | 'hackerone' | 'zscaler' | 'darktrace' | 'seon', required: Filter-oriented alert source name. Trigger-created alerts use the trigger type.
        - `triggerType` 'jira' | 'jira-automation' | 'slack' | 'linear' | 'cron' | 'webhook' | 'email' | 'bugcrowd' | 'hackerone' | 'zscaler' | 'darktrace' | 'seon' | 'null', nullable, required: Trigger source when category is trigger
      - `detection` object, nullable, required: Detection attribution for the alert, when known.
        - `id` string, uuid, nullable, required: Cotool detection identifier when known
        - `agentId` string, uuid, nullable, required: Cotool detection agent identifier when known
        - `codeDetectionId` string, uuid, nullable: Code detection identifier when this alert came from Code Mode
        - `ruleId` string, uuid, nullable, required: Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule
        - `name` string, required: Detection display name
        - `kind` 'cotool' | 'cotool_code' | 'cotool_signal' | 'external', required: Whether this detection attribution is internal or extracted. `cotool_signal` alerts were promoted from a signal; their name is the signal type, and `codeDetectionId` is the streaming detection that emitted it.
        - `origin` 'user' | 'orchestrator' | 'null', nullable: Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature.
      - `createdBy` 'agent' | 'trigger' | 'system', required: Actor class that created the alert.
      - `originAgentId` string, uuid, nullable, required: Agent that produced or owns the source flow
      - `originTriggerId` string, uuid, nullable, required: Trigger that created this alert, when source is an external trigger
      - `originRunId` string, uuid, nullable, required: Run that minted the alert, stored as chats.id
      - `originDetectionHitId` string, uuid, nullable, required: Detection hit that produced this alert, when applicable
      - `codeDetectionId` string, uuid, nullable, required: Code detection that produced this alert, when applicable
      - `originCodeDetectionHitId` string, uuid, nullable, required: Code-detection hit that produced this alert, when applicable
      - `externalProvider` 'jira' | 'jira-automation' | 'slack' | 'linear' | 'cron' | 'webhook' | 'email' | 'bugcrowd' | 'hackerone' | 'zscaler' | 'darktrace' | 'seon' | 'null', nullable, required: External trigger provider such as jira, linear, email, or webhook
      - `externalRef` string, nullable, required: Provider-native event, ticket, message, or alert identifier
      - `externalUrl` string, uri, nullable, required: Provider-native URL for the originating object
      - `assignedAgentId` string, uuid, nullable, required: Response agent currently assigned to triage this alert
      - `triageRunId` string, uuid, nullable, required: Latest response-agent triage run for this alert, stored as chats.id
      - `dedupeKey` string, nullable, required: Stable key used for idempotent alert creation
      - `createdAt` string, required: ISO timestamp when the alert was created
      - `updatedAt` string, required: ISO timestamp when the alert was last updated
      - `firstTriagedAt` string, nullable, required: ISO timestamp when triage first started
      - `resolvedAt` string, nullable, required: ISO timestamp when the alert reached a terminal closed status
      - `derivedDisposition` 'true_positive' | 'false_positive' | 'true_positive_benign' | 'null', nullable, required: Disposition derived from terminal alert status
      - `originAgentName` string, nullable, required: Display name for the origin agent, when available
      - `assignedAgentName` string, nullable, required: Display name for the assigned triage agent, when available
      - `triggerSource` 'jira' | 'jira-automation' | 'slack' | 'linear' | 'cron' | 'webhook' | 'email' | 'bugcrowd' | 'hackerone' | 'zscaler' | 'darktrace' | 'seon' | 'null', nullable, required: Trigger source for external-trigger alerts
      - `resolvedByType` 'human' | 'agent' | 'system' | 'null', nullable: Actor class that moved the alert to its terminal status. Null while the alert is not closed.
      - `resolvedByUserId` string, uuid, nullable: User who closed the alert, when a human closed it
      - `resolvedByAgentName` string, nullable: Display name of the agent that closed the alert, when an agent closed it
      - `resolvedReason` string, nullable: Reason recorded with the closing status change, when provided
      - `huntQualifiedBy` 'compromise_signal_found' | 'exposure_found' | 'null', nullable: Qualifying condition that opened this Hunt alert. Null for non-hunt alerts.
      - `alternativeExplanationCount` integer: Number of alternative explanations offered on the latest escalation. Only meaningful while the alert is escalated.
    - `activityEvents` object[], required
      - `id` string, required
      - `threatId` string, required
      - `kind` 'threat_created' | 'intel_attached' | 'reassessment_requested' | 'assessment_started' | 'relevancy_completed' | 'exposure_started' | 'assessment_failed', required
      - `actorType` 'system' | 'agent' | 'human', required
      - `runId` string, nullable, required
      - `metadata` object, nullable, required
        - `score` number
        - `hunting` boolean
        - `executionId` string
        - `canonicalKey` string
        - `label` string
        - `userId` string
      - `createdAt` string, required
    - `capabilities` object
      - `canReadEvidence` boolean, required
      - `canReassess` boolean, required
      - `canTriage` boolean, required

## Other responses

- `400`: Bad request — input validation failed or the request was malformed
- `401`: Unauthorized — missing or invalid API key / session
- `403`: Forbidden — the authenticated user lacks the required permissions
- `500`: Internal server error

---

[API](https://skmtc.dev/cotool/apis/cotool-api.md) - [All operations](https://skmtc.dev/cotool/apis/cotool-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cotool/apis/cotool-api/revisions/f5abe0add203?raw)