> ## Documentation Index > Fetch the complete documentation index at: https://docs.cotool.ai/llms.txt > Use this file to discover all available pages before exploring further. # Rename a Threat > Set the name the Threat is listed and searched by. Names are unique within the organization, ignoring case, spaces, and punctuation. A name set here is never replaced automatically. ## OpenAPI ````yaml https://app.cotool.ai/api/docs/openapi.json post /api/threats/{id}/rename openapi: 3.1.0 info: title: Cotool API version: 1.0.0 description: >- The Cotool REST API. Authenticate with an API key from `/settings/api-keys` sent as `Authorization: Bearer `. Authentication, error formats, pagination, and common integration recipes are documented in the [API overview](https://docs.cotool.ai/api-reference/introduction). Endpoints marked **Deprecated** keep working; each one's description names its replacement. servers: - url: https://app.cotool.ai description: Production server security: - ApiKeyAuth: [] tags: - name: Agents description: Create, update, run, and version agents. - name: Agent Runs description: Inspect agent runs, submit feedback, and read evaluation metrics. - name: Agent Triggers description: Webhook, schedule, and integration triggers that start agent runs. - name: Agents as Code description: Validate agents and skills defined as YAML in a Git repository. - name: Skills description: Reusable instructions and tool grants attached to agents. - name: Chat description: Chat sessions and their transcripts. - name: Alerts description: Alert triage, routing, and escalation notifications. - name: Output Destinations description: Webhook, Slack, Jira, and Linear destinations for agent output. - name: Detections description: Detection agents, detection hits, and the Cotool detection library. - name: Hunt description: Autonomous hunt threats, gaps, and settings. - name: Intel description: Threat-intelligence feed items, indicators, and sources. - name: Threat Model description: The organization threat model and its version history. - name: MITRE Coverage description: MITRE ATT&CK coverage across detections. - name: Tools description: Connected tool integrations and captured tool output. - name: CLIs description: Connected CLI integrations. - name: Artifacts description: Files and reports produced by agent runs. - name: Audit Logs description: Organization audit log export and event catalog. - name: Users description: Users, memberships, and the current session. - name: Roles description: Role-based permissions. - name: Organizations description: Organization-level metrics. paths: /api/threats/{id}/rename: post: tags: - Hunt summary: Rename a Threat description: >- Set the name the Threat is listed and searched by. Names are unique within the organization, ignoring case, spaces, and punctuation. A name set here is never replaced automatically. parameters: - in: path name: id schema: type: string required: true requestBody: content: application/json: schema: type: object properties: name: type: string required: - name responses: '200': description: Successful response content: application/json: schema: type: object properties: threat: type: object properties: id: type: string organizationId: type: string canonicalType: type: string enum: - vulnerability - campaign canonicalKeyType: type: string enum: - cve - advisory - vendor_advisory - campaign_name - malware_family canonicalKey: type: string name: type: string nameSource: type: - string - 'null' enum: - generated - fallback - user - null identifiers: type: array items: type: string title: type: string aliases: type: array items: type: string actorId: type: - string - 'null' intelItemIds: type: array items: type: string relevancyScore: type: - number - 'null' exposureScore: type: - number - 'null' exposureState: type: - string - 'null' enum: - compromise_signal_found - exposure_found - no_exposure_found - inconclusive - null coverageState: type: - string - 'null' enum: - none - partial - covered - unknown - null detectionEngineeringNote: type: - string - 'null' latestRunId: type: - string - 'null' assessmentRunningExecutionId: type: - string - 'null' assessmentFailedAt: type: - string - 'null' latestAlertId: type: - string - 'null' activeHuntAlertId: type: - string - 'null' dismissedAt: type: - string - 'null' dismissedByUserId: type: - string - 'null' dismissedReason: type: - string - 'null' createdAt: type: string updatedAt: type: string required: - id - organizationId - canonicalType - canonicalKeyType - canonicalKey - name - nameSource - identifiers - title - aliases - actorId - intelItemIds - relevancyScore - exposureScore - exposureState - coverageState - detectionEngineeringNote - latestRunId - assessmentRunningExecutionId - assessmentFailedAt - latestAlertId - activeHuntAlertId - dismissedAt - dismissedByUserId - dismissedReason - createdAt - updatedAt runs: type: array items: type: object properties: id: type: string threatId: type: string kind: type: string enum: - create - update trigger: type: string enum: - new_threat - intel_attached - manual - backfill - reclassification runAt: type: string relevancyExecutionId: type: string relevancyScore: type: number relevancyHeadline: type: - string - 'null' relevancyExplanation: type: array items: type: string exposureExecutionId: type: - string - 'null' exposureScore: type: - number - 'null' exposureState: type: - string - 'null' enum: - compromise_signal_found - exposure_found - no_exposure_found - inconclusive - null exposureStory: type: - object - 'null' properties: exposureState: type: string enum: - compromise_signal_found - exposure_found - no_exposure_found - inconclusive headline: type: string summary: type: array items: type: string exposureChecks: type: array items: type: object properties: purpose: type: string enum: - exposure - ioc - telemetry - detection_coverage indicatorId: type: string authoritative: type: boolean iocType: type: string enum: - ip - domain - url - hash - file_path - process - registry_key - certificate - cloud_id - package - email - user_agent - mutex - other indicatorRole: type: string enum: - compromise - relevance checked: type: string source: type: string scope: type: string timeWindow: type: - object - 'null' properties: start: type: string end: type: string required: - start - end outcome: type: string enum: - found - not_found - inconclusive evidence: type: string limitations: type: array items: type: string required: - purpose - checked - source - scope - timeWindow - outcome - evidence - limitations assets: type: array items: type: object properties: identifier: type: string kind: type: string enum: - repository - host - service - cloud_resource - identity - package - domain - saas_account - container_image - other default: other platform: type: - string - 'null' default: null source: type: string internetFacing: type: - boolean - 'null' evidence: type: string required: - identifier - kind - platform - source - internetFacing - evidence iocFindings: type: array items: type: object properties: indicatorId: type: string authoritative: type: boolean iocType: type: string enum: - ip - domain - url - hash - file_path - process - registry_key - certificate - cloud_id - package - email - user_agent - mutex - other role: type: string enum: - compromise - relevance default: compromise platform: type: - string - 'null' default: null iocValue: type: string evidence: type: string affectedSystems: type: array items: type: string required: - iocType - role - platform - iocValue - evidence - affectedSystems discoveredIndicators: type: array items: type: object properties: indicatorId: type: string minLength: 1 description: Unique run-local id such as discovered-1. iocType: type: string enum: - ip - domain - url - hash - file_path - process - registry_key - certificate - cloud_id - package - email - user_agent - mutex - other description: Canonical indicator type. role: type: string enum: - compromise - relevance description: Required role with no default. platform: type: string description: >- Optional registry/ecosystem for package or image indicators. iocValue: type: string minLength: 1 maxLength: 2048 description: >- One exact atomic indicator value, never a prose/composite description. roleRationale: type: string minLength: 1 description: >- Why a match alone does or does not justify a compromise claim. evidence: type: string minLength: 1 description: >- Cited evidence establishing this as a threat indicator. required: - indicatorId - iocType - role - iocValue - roleRationale - evidence observations: type: array items: type: object properties: observationId: type: string minLength: 1 description: Unique run-local observation id. kind: type: string enum: - software_presence - vulnerable_asset - configuration_exposure - exploit_attempt - suspicious_behavior - confirmed_malicious_behavior description: >- Semantic kind of customer-environment observation. summary: type: string minLength: 1 description: Concise statement of what was observed. evidence: type: string minLength: 1 description: Cited customer-environment evidence. affectedSystems: type: array items: type: string description: Affected system identifier. description: Affected customer assets; empty when none. timeWindow: type: object properties: start: type: string description: Observation window start. end: type: string description: Observation window end. required: - start - end required: - observationId - kind - summary - evidence - affectedSystems researchContext: type: array items: type: object properties: contextId: type: string minLength: 1 description: Unique run-local context id. summary: type: string minLength: 1 description: Concise public/intel fact. evidence: type: string minLength: 1 description: Cited evidence for the context fact. required: - contextId - summary - evidence conclusion: type: object properties: headline: type: string minLength: 1 description: >- 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: type: array items: type: string description: One concise cited verdict bullet. minItems: 3 maxItems: 8 description: >- 3-8 concise bullets explaining the environment verdict. supportingFindingIds: type: array items: type: string description: >- An input-catalog indicatorId that appears in indicatorChecks, or an observationId defined in observations, copied verbatim. description: >- 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: type: array items: type: string description: >- Research context id used for interpretation. description: Referenced public/intel context ids. required: - headline - summary - supportingFindingIds - contextIds detectionCoverage: type: object properties: state: type: string enum: - none - partial - covered - unknown searches: type: array items: type: object properties: source: type: string criteria: type: string resultCount: type: number evidence: type: string limitations: type: array items: type: string required: - source - criteria - resultCount - evidence - limitations matches: type: array items: type: object properties: ref: type: object properties: id: type: string name: type: string kind: type: string enum: - rule_proposal - deployed_rule - detection_agent platform: type: - string - 'null' url: type: - string - 'null' required: - id - name - kind coverage: type: string enum: - partial - covered - unknown rationale: type: string limitations: type: array items: type: string required: - ref - coverage - rationale - limitations required: - state - searches - matches gaps: type: array items: type: object properties: product: type: string logSource: type: string scopeType: type: string enum: - org - integration - account - environment - asset_group - tenant - domain scopeId: type: - string - 'null' scopeKey: type: string blocking: type: boolean description: type: string limitations: type: array items: type: string required: - product - logSource - scopeType - scopeId - scopeKey - blocking - description - limitations nextSteps: type: array items: type: string timeline: type: array items: type: object properties: timestamp: type: string description: type: string required: - timestamp - description executionId: type: string runAt: type: string required: - exposureState - summary - exposureChecks - assets - iocFindings - detectionCoverage - gaps - nextSteps - executionId - runAt coverageState: type: - string - 'null' enum: - none - partial - covered - unknown - null hasFoundIoc: type: boolean hasBlockingGap: type: boolean diff: type: - object - 'null' properties: prevRunId: type: string beforeExposureScore: type: - number - 'null' afterExposureScore: type: - number - 'null' beforeExposureState: type: - string - 'null' enum: - compromise_signal_found - exposure_found - no_exposure_found - inconclusive - null afterExposureState: type: - string - 'null' enum: - compromise_signal_found - exposure_found - no_exposure_found - inconclusive - null beforeCoverageState: type: - string - 'null' enum: - none - partial - covered - unknown - null afterCoverageState: type: - string - 'null' enum: - none - partial - covered - unknown - null reasons: type: array items: type: string required: - prevRunId - beforeExposureScore - afterExposureScore - beforeExposureState - afterExposureState - beforeCoverageState - afterCoverageState - reasons required: - id - threatId - kind - trigger - runAt - relevancyExecutionId - relevancyScore - relevancyExplanation - exposureExecutionId - exposureScore - exposureState - exposureStory - coverageState - hasFoundIoc - hasBlockingGap - diff deliverables: type: array items: oneOf: - type: object properties: id: type: string organizationId: type: string threatId: type: string executionId: type: string createdAt: type: string supersededById: type: - string - 'null' kind: type: string const: rule_proposal proposalId: type: - string - 'null' pullRequestUrl: type: - string - 'null' intent: type: string pinning: type: string enum: - ioc_pinned - behavioral - mixed pinnedIocs: type: array items: type: object properties: type: type: string value: type: string required: - type - value targetProduct: type: - string - 'null' targetLogSource: type: - string - 'null' lifecycleStatus: type: string enum: - authoring - drafted - in_review - shipped - dismissed - failed required: - id - organizationId - threatId - executionId - createdAt - supersededById - kind - proposalId - pullRequestUrl - intent - pinning - pinnedIocs - targetProduct - targetLogSource - lifecycleStatus - type: object properties: id: type: string organizationId: type: string threatId: type: string executionId: type: string createdAt: type: string supersededById: type: - string - 'null' kind: type: string const: gap gapId: type: - string - 'null' product: type: string logSource: type: string scopeType: type: string enum: - org - integration - account - environment - asset_group - tenant - domain scopeId: type: - string - 'null' scopeKey: type: string blocking: type: boolean description: type: string gapStatus: type: string enum: - open - resolved - dismissed establishedAt: type: string statusAt: type: - string - 'null' statusActor: anyOf: - type: object properties: type: type: string const: agent runId: type: string required: - type - runId - type: object properties: type: type: string const: human userId: type: string required: - type - userId - type: 'null' statusReason: type: - string - 'null' otherLinkedThreats: type: array items: type: object properties: threatId: type: string threatTitle: type: string identifiers: type: array items: type: string canonicalKey: type: string blocking: type: boolean required: - threatId - threatTitle - identifiers - canonicalKey - blocking required: - id - organizationId - threatId - executionId - createdAt - supersededById - kind - product - logSource - scopeType - scopeId - scopeKey - blocking - description - gapStatus - establishedAt - statusAt - statusActor - statusReason intelItems: type: array items: type: object properties: id: type: string title: type: string publisher: type: string sourceName: type: - string - 'null' url: type: - string - 'null' publishedAt: type: string tldr: type: - string - 'null' attackPath: type: array items: type: string summary: type: - string - 'null' attackTechniques: type: array items: type: object properties: id: type: string name: type: - string - 'null' required: - id - name malware: type: array items: type: string actors: type: array items: type: string platforms: type: array items: type: string affectedProducts: type: array items: type: object properties: name: type: string versions: type: array items: type: string required: - name - versions eventFirstSeen: type: - string - 'null' eventLastSeen: type: - string - 'null' required: - id - title - publisher - url - publishedAt - tldr - attackPath alerts: type: array items: type: object properties: id: type: string format: uuid description: Internal alert identifier displayId: type: string pattern: ^COT-\d+$ description: Human-readable alert identifier organizationId: type: string format: uuid description: Organization that owns the alert organizationName: type: string minLength: 1 description: >- URL-safe organization name used in durable alert paths title: type: string minLength: 1 description: Human-readable alert title description: type: - string - 'null' description: Markdown summary or details for the alert severity: type: - string - 'null' enum: - low - medium - high - critical - null description: Alert severity when known status: type: string enum: - open - in_progress - escalated - closed_true_positive - closed_false_positive - closed_true_positive_benign - dismissed - duplicate - expired description: >- 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: type: - string - 'null' format: uuid description: >- Canonical alert this alert duplicates, when status is duplicate duplicateCount: type: integer minimum: 0 description: >- Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring. source: type: object properties: category: type: string enum: - detection - trigger - hunt - api - agent description: >- 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: type: string enum: - cotool_detection - cotool_code - cotool_signal - hunt - hunt_v2 - api - agent - jira - jira-automation - slack - linear - cron - webhook - email - bugcrowd - hackerone - zscaler - darktrace - seon description: >- Filter-oriented alert source name. Trigger-created alerts use the trigger type. triggerType: type: - string - 'null' enum: - jira - jira-automation - slack - linear - cron - webhook - email - bugcrowd - hackerone - zscaler - darktrace - seon - null description: Trigger source when category is trigger required: - category - name - triggerType description: Filter-oriented source attribution for an alert. detection: type: - object - 'null' properties: id: type: - string - 'null' format: uuid description: Cotool detection identifier when known agentId: type: - string - 'null' format: uuid description: Cotool detection agent identifier when known codeDetectionId: type: - string - 'null' format: uuid description: >- Code detection identifier when this alert came from Code Mode ruleId: type: - string - 'null' format: uuid description: >- Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule name: type: string minLength: 1 description: Detection display name kind: type: string enum: - cotool - cotool_code - cotool_signal - external description: >- 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: type: - string - 'null' enum: - user - orchestrator - null description: >- Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature. required: - id - agentId - ruleId - name - kind description: Detection attribution for the alert, when known. createdBy: type: string enum: - agent - trigger - system description: Actor class that created the alert. originAgentId: type: - string - 'null' format: uuid description: Agent that produced or owns the source flow originTriggerId: type: - string - 'null' format: uuid description: >- Trigger that created this alert, when source is an external trigger originRunId: type: - string - 'null' format: uuid description: Run that minted the alert, stored as chats.id originDetectionHitId: type: - string - 'null' format: uuid description: >- Detection hit that produced this alert, when applicable codeDetectionId: type: - string - 'null' format: uuid description: >- Code detection that produced this alert, when applicable originCodeDetectionHitId: type: - string - 'null' format: uuid description: >- Code-detection hit that produced this alert, when applicable externalProvider: type: - string - 'null' enum: - jira - jira-automation - slack - linear - cron - webhook - email - bugcrowd - hackerone - zscaler - darktrace - seon - null description: >- External trigger provider such as jira, linear, email, or webhook externalRef: type: - string - 'null' description: >- Provider-native event, ticket, message, or alert identifier externalUrl: type: - string - 'null' format: uri description: Provider-native URL for the originating object assignedAgentId: type: - string - 'null' format: uuid description: >- Response agent currently assigned to triage this alert triageRunId: type: - string - 'null' format: uuid description: >- Latest response-agent triage run for this alert, stored as chats.id dedupeKey: type: - string - 'null' description: Stable key used for idempotent alert creation createdAt: type: string description: ISO timestamp when the alert was created updatedAt: type: string description: ISO timestamp when the alert was last updated firstTriagedAt: type: - string - 'null' description: ISO timestamp when triage first started resolvedAt: type: - string - 'null' description: >- ISO timestamp when the alert reached a terminal closed status derivedDisposition: type: - string - 'null' enum: - true_positive - false_positive - true_positive_benign - null description: Disposition derived from terminal alert status originAgentName: type: - string - 'null' description: Display name for the origin agent, when available assignedAgentName: type: - string - 'null' description: >- Display name for the assigned triage agent, when available triggerSource: type: - string - 'null' enum: - jira - jira-automation - slack - linear - cron - webhook - email - bugcrowd - hackerone - zscaler - darktrace - seon - null description: Trigger source for external-trigger alerts resolvedByType: type: - string - 'null' enum: - human - agent - system - null description: >- Actor class that moved the alert to its terminal status. Null while the alert is not closed. resolvedByUserId: type: - string - 'null' format: uuid description: User who closed the alert, when a human closed it resolvedByAgentName: type: - string - 'null' description: >- Display name of the agent that closed the alert, when an agent closed it resolvedReason: type: - string - 'null' description: >- Reason recorded with the closing status change, when provided huntQualifiedBy: type: - string - 'null' enum: - compromise_signal_found - exposure_found - null description: >- Qualifying condition that opened this Hunt alert. Null for non-hunt alerts. alternativeExplanationCount: type: integer minimum: 0 description: >- Number of alternative explanations offered on the latest escalation. Only meaningful while the alert is escalated. required: - id - displayId - organizationId - organizationName - title - description - severity - status - duplicateCount - source - detection - createdBy - originAgentId - originTriggerId - originRunId - originDetectionHitId - codeDetectionId - originCodeDetectionHitId - externalProvider - externalRef - externalUrl - assignedAgentId - triageRunId - dedupeKey - createdAt - updatedAt - firstTriagedAt - resolvedAt - derivedDisposition - originAgentName - assignedAgentName - triggerSource activeHuntAlert: type: - object - 'null' properties: id: type: string format: uuid description: Internal alert identifier displayId: type: string pattern: ^COT-\d+$ description: Human-readable alert identifier organizationId: type: string format: uuid description: Organization that owns the alert organizationName: type: string minLength: 1 description: URL-safe organization name used in durable alert paths title: type: string minLength: 1 description: Human-readable alert title description: type: - string - 'null' description: Markdown summary or details for the alert severity: type: - string - 'null' enum: - low - medium - high - critical - null description: Alert severity when known status: type: string enum: - open - in_progress - escalated - closed_true_positive - closed_false_positive - closed_true_positive_benign - dismissed - duplicate - expired description: >- 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: type: - string - 'null' format: uuid description: >- Canonical alert this alert duplicates, when status is duplicate duplicateCount: type: integer minimum: 0 description: >- Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring. source: type: object properties: category: type: string enum: - detection - trigger - hunt - api - agent description: >- 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: type: string enum: - cotool_detection - cotool_code - cotool_signal - hunt - hunt_v2 - api - agent - jira - jira-automation - slack - linear - cron - webhook - email - bugcrowd - hackerone - zscaler - darktrace - seon description: >- Filter-oriented alert source name. Trigger-created alerts use the trigger type. triggerType: type: - string - 'null' enum: - jira - jira-automation - slack - linear - cron - webhook - email - bugcrowd - hackerone - zscaler - darktrace - seon - null description: Trigger source when category is trigger required: - category - name - triggerType description: Filter-oriented source attribution for an alert. detection: type: - object - 'null' properties: id: type: - string - 'null' format: uuid description: Cotool detection identifier when known agentId: type: - string - 'null' format: uuid description: Cotool detection agent identifier when known codeDetectionId: type: - string - 'null' format: uuid description: >- Code detection identifier when this alert came from Code Mode ruleId: type: - string - 'null' format: uuid description: >- Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule name: type: string minLength: 1 description: Detection display name kind: type: string enum: - cotool - cotool_code - cotool_signal - external description: >- 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: type: - string - 'null' enum: - user - orchestrator - null description: >- Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature. required: - id - agentId - ruleId - name - kind description: Detection attribution for the alert, when known. createdBy: type: string enum: - agent - trigger - system description: Actor class that created the alert. originAgentId: type: - string - 'null' format: uuid description: Agent that produced or owns the source flow originTriggerId: type: - string - 'null' format: uuid description: >- Trigger that created this alert, when source is an external trigger originRunId: type: - string - 'null' format: uuid description: Run that minted the alert, stored as chats.id originDetectionHitId: type: - string - 'null' format: uuid description: >- Detection hit that produced this alert, when applicable codeDetectionId: type: - string - 'null' format: uuid description: >- Code detection that produced this alert, when applicable originCodeDetectionHitId: type: - string - 'null' format: uuid description: >- Code-detection hit that produced this alert, when applicable externalProvider: type: - string - 'null' enum: - jira - jira-automation - slack - linear - cron - webhook - email - bugcrowd - hackerone - zscaler - darktrace - seon - null description: >- External trigger provider such as jira, linear, email, or webhook externalRef: type: - string - 'null' description: >- Provider-native event, ticket, message, or alert identifier externalUrl: type: - string - 'null' format: uri description: Provider-native URL for the originating object assignedAgentId: type: - string - 'null' format: uuid description: Response agent currently assigned to triage this alert triageRunId: type: - string - 'null' format: uuid description: >- Latest response-agent triage run for this alert, stored as chats.id dedupeKey: type: - string - 'null' description: Stable key used for idempotent alert creation createdAt: type: string description: ISO timestamp when the alert was created updatedAt: type: string description: ISO timestamp when the alert was last updated firstTriagedAt: type: - string - 'null' description: ISO timestamp when triage first started resolvedAt: type: - string - 'null' description: >- ISO timestamp when the alert reached a terminal closed status derivedDisposition: type: - string - 'null' enum: - true_positive - false_positive - true_positive_benign - null description: Disposition derived from terminal alert status originAgentName: type: - string - 'null' description: Display name for the origin agent, when available assignedAgentName: type: - string - 'null' description: >- Display name for the assigned triage agent, when available triggerSource: type: - string - 'null' enum: - jira - jira-automation - slack - linear - cron - webhook - email - bugcrowd - hackerone - zscaler - darktrace - seon - null description: Trigger source for external-trigger alerts resolvedByType: type: - string - 'null' enum: - human - agent - system - null description: >- Actor class that moved the alert to its terminal status. Null while the alert is not closed. resolvedByUserId: type: - string - 'null' format: uuid description: User who closed the alert, when a human closed it resolvedByAgentName: type: - string - 'null' description: >- Display name of the agent that closed the alert, when an agent closed it resolvedReason: type: - string - 'null' description: >- Reason recorded with the closing status change, when provided huntQualifiedBy: type: - string - 'null' enum: - compromise_signal_found - exposure_found - null description: >- Qualifying condition that opened this Hunt alert. Null for non-hunt alerts. alternativeExplanationCount: type: integer minimum: 0 description: >- Number of alternative explanations offered on the latest escalation. Only meaningful while the alert is escalated. required: - id - displayId - organizationId - organizationName - title - description - severity - status - duplicateCount - source - detection - createdBy - originAgentId - originTriggerId - originRunId - originDetectionHitId - codeDetectionId - originCodeDetectionHitId - externalProvider - externalRef - externalUrl - assignedAgentId - triageRunId - dedupeKey - createdAt - updatedAt - firstTriagedAt - resolvedAt - derivedDisposition - originAgentName - assignedAgentName - triggerSource latestAlert: type: - object - 'null' properties: id: type: string format: uuid description: Internal alert identifier displayId: type: string pattern: ^COT-\d+$ description: Human-readable alert identifier organizationId: type: string format: uuid description: Organization that owns the alert organizationName: type: string minLength: 1 description: URL-safe organization name used in durable alert paths title: type: string minLength: 1 description: Human-readable alert title description: type: - string - 'null' description: Markdown summary or details for the alert severity: type: - string - 'null' enum: - low - medium - high - critical - null description: Alert severity when known status: type: string enum: - open - in_progress - escalated - closed_true_positive - closed_false_positive - closed_true_positive_benign - dismissed - duplicate - expired description: >- 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: type: - string - 'null' format: uuid description: >- Canonical alert this alert duplicates, when status is duplicate duplicateCount: type: integer minimum: 0 description: >- Number of alerts archived as duplicates of this alert. A high count means the same finding keeps recurring. source: type: object properties: category: type: string enum: - detection - trigger - hunt - api - agent description: >- 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: type: string enum: - cotool_detection - cotool_code - cotool_signal - hunt - hunt_v2 - api - agent - jira - jira-automation - slack - linear - cron - webhook - email - bugcrowd - hackerone - zscaler - darktrace - seon description: >- Filter-oriented alert source name. Trigger-created alerts use the trigger type. triggerType: type: - string - 'null' enum: - jira - jira-automation - slack - linear - cron - webhook - email - bugcrowd - hackerone - zscaler - darktrace - seon - null description: Trigger source when category is trigger required: - category - name - triggerType description: Filter-oriented source attribution for an alert. detection: type: - object - 'null' properties: id: type: - string - 'null' format: uuid description: Cotool detection identifier when known agentId: type: - string - 'null' format: uuid description: Cotool detection agent identifier when known codeDetectionId: type: - string - 'null' format: uuid description: >- Code detection identifier when this alert came from Code Mode ruleId: type: - string - 'null' format: uuid description: >- Platform detection rule identifier (detection_rules inventory) when an external detection was matched to a synced rule name: type: string minLength: 1 description: Detection display name kind: type: string enum: - cotool - cotool_code - cotool_signal - external description: >- 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: type: - string - 'null' enum: - user - orchestrator - null description: >- Origin of the Cotool detection agent when known. `orchestrator` marks a detection created by the retired Auto Detect feature. required: - id - agentId - ruleId - name - kind description: Detection attribution for the alert, when known. createdBy: type: string enum: - agent - trigger - system description: Actor class that created the alert. originAgentId: type: - string - 'null' format: uuid description: Agent that produced or owns the source flow originTriggerId: type: - string - 'null' format: uuid description: >- Trigger that created this alert, when source is an external trigger originRunId: type: - string - 'null' format: uuid description: Run that minted the alert, stored as chats.id originDetectionHitId: type: - string - 'null' format: uuid description: >- Detection hit that produced this alert, when applicable codeDetectionId: type: - string - 'null' format: uuid description: >- Code detection that produced this alert, when applicable originCodeDetectionHitId: type: - string - 'null' format: uuid description: >- Code-detection hit that produced this alert, when applicable externalProvider: type: - string - 'null' enum: - jira - jira-automation - slack - linear - cron - webhook - email - bugcrowd - hackerone - zscaler - darktrace - seon - null description: >- External trigger provider such as jira, linear, email, or webhook externalRef: type: - string - 'null' description: >- Provider-native event, ticket, message, or alert identifier externalUrl: type: - string - 'null' format: uri description: Provider-native URL for the originating object assignedAgentId: type: - string - 'null' format: uuid description: Response agent currently assigned to triage this alert triageRunId: type: - string - 'null' format: uuid description: >- Latest response-agent triage run for this alert, stored as chats.id dedupeKey: type: - string - 'null' description: Stable key used for idempotent alert creation createdAt: type: string description: ISO timestamp when the alert was created updatedAt: type: string description: ISO timestamp when the alert was last updated firstTriagedAt: type: - string - 'null' description: ISO timestamp when triage first started resolvedAt: type: - string - 'null' description: >- ISO timestamp when the alert reached a terminal closed status derivedDisposition: type: - string - 'null' enum: - true_positive - false_positive - true_positive_benign - null description: Disposition derived from terminal alert status originAgentName: type: - string - 'null' description: Display name for the origin agent, when available assignedAgentName: type: - string - 'null' description: >- Display name for the assigned triage agent, when available triggerSource: type: - string - 'null' enum: - jira - jira-automation - slack - linear - cron - webhook - email - bugcrowd - hackerone - zscaler - darktrace - seon - null description: Trigger source for external-trigger alerts resolvedByType: type: - string - 'null' enum: - human - agent - system - null description: >- Actor class that moved the alert to its terminal status. Null while the alert is not closed. resolvedByUserId: type: - string - 'null' format: uuid description: User who closed the alert, when a human closed it resolvedByAgentName: type: - string - 'null' description: >- Display name of the agent that closed the alert, when an agent closed it resolvedReason: type: - string - 'null' description: >- Reason recorded with the closing status change, when provided huntQualifiedBy: type: - string - 'null' enum: - compromise_signal_found - exposure_found - null description: >- Qualifying condition that opened this Hunt alert. Null for non-hunt alerts. alternativeExplanationCount: type: integer minimum: 0 description: >- Number of alternative explanations offered on the latest escalation. Only meaningful while the alert is escalated. required: - id - displayId - organizationId - organizationName - title - description - severity - status - duplicateCount - source - detection - createdBy - originAgentId - originTriggerId - originRunId - originDetectionHitId - codeDetectionId - originCodeDetectionHitId - externalProvider - externalRef - externalUrl - assignedAgentId - triageRunId - dedupeKey - createdAt - updatedAt - firstTriagedAt - resolvedAt - derivedDisposition - originAgentName - assignedAgentName - triggerSource activityEvents: type: array items: type: object properties: id: type: string threatId: type: string kind: type: string enum: - threat_created - intel_attached - reassessment_requested - assessment_started - relevancy_completed - exposure_started - assessment_failed - threat_renamed actorType: type: string enum: - system - agent - human runId: type: - string - 'null' metadata: type: - object - 'null' properties: score: type: number hunting: type: boolean executionId: type: string canonicalKey: type: string label: type: string previousLabel: type: string userId: type: string createdAt: type: string required: - id - threatId - kind - actorType - runId - metadata - createdAt capabilities: type: object properties: canReadEvidence: type: boolean canReassess: type: boolean canTriage: type: boolean required: - canReadEvidence - canReassess - canTriage required: - threat - runs - deliverables - intelItems - alerts - activeHuntAlert - latestAlert - activityEvents '400': description: The name is too short, too long, or empty. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized — missing or invalid API key / session content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Caller lacks the alert.triage permission. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Threat not found. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Another Threat already has this name. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: shell label: cURL source: |- curl -X POST "https://app.cotool.ai/api/threats/:id/rename" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"string"}' components: schemas: Error: type: object properties: error: type: string description: Error message describing what went wrong code: type: string description: >- Machine-readable error code, present when the error has one. Branch on this instead of the message. details: type: object description: Structured details for `code`, whose shape depends on the code required: - error securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API Key description: >- API Key authentication for programmatic access. Include your API key in the Authorization header as: `Bearer your_api_key_here` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.