> ## 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. # List alerts > Retrieve first-class alert work items for the current organization. Returns alerts of every status unless a status filter is provided. ## OpenAPI ````yaml https://app.cotool.ai/api/docs/openapi.json get /api/alerts openapi: 3.1.0 info: title: Cotool API version: 1.0.0 description: >- # Cotool API Documentation The Cotool API allows you to interact with the Cotool platform programmatically, enabling you to build powerful integrations and automate your workflows. ## Getting an API Key Follow these steps to generate your API key: 1. **Log in** to the Cotool web interface 2. **Navigate** to `/settings/api-keys` 3. **Click** "Generate Key" 4. **Copy and store** your API key securely ⚠️ *It won't be shown again* ## API Key Authentication For programmatic access and integrations, use your API key with the Authorization header: ```http Authorization: Bearer your_api_key_here ``` ```bash curl -X GET "https://app.cotool.ai/api/endpoint" \ -H "Authorization: Bearer your_api_key_here" \ -H "Content-Type: application/json" ``` servers: - url: https://app.cotool.ai description: Production server security: - ApiKeyAuth: [] paths: /api/alerts: get: tags: - Alerts summary: List alerts description: >- Retrieve first-class alert work items for the current organization. Returns alerts of every status unless a status filter is provided. parameters: - in: query name: limit description: Maximum number of alerts to return per page schema: type: integer minimum: 1 maximum: 200 default: 100 description: Maximum number of alerts to return per page - in: query name: offset description: Number of alerts to skip for pagination schema: type: integer minimum: 0 default: 0 description: Number of alerts to skip for pagination - in: query name: status description: Comma-separated alert statuses to include schema: type: string description: Comma-separated alert statuses to include - in: query name: source description: Comma-separated alert source names to include schema: type: string description: Comma-separated alert source names to include - in: query name: severity description: Comma-separated severities to include schema: type: string description: Comma-separated severities to include - in: query name: assignedAgentId description: Only include alerts assigned to this response agent schema: type: string format: uuid description: Only include alerts assigned to this response agent - in: query name: detection description: Alert detection filter key returned by /api/alerts/filter-options schema: type: string description: Alert detection filter key returned by /api/alerts/filter-options - in: query name: detectionId description: Only include alerts tied to this Cotool detection schema: type: string format: uuid description: Only include alerts tied to this Cotool detection - in: query name: originAgentId description: Only include alerts created by this origin agent schema: type: string format: uuid description: Only include alerts created by this origin agent - in: query name: originDetectionHitId description: Only include the alert created from this detection hit schema: type: string format: uuid description: Only include the alert created from this detection hit - in: query name: q description: >- Free-text search over alert title, description, detection name, and origin references schema: type: string minLength: 1 maxLength: 500 description: >- Free-text search over alert title, description, detection name, and origin references responses: '200': description: Successful response content: application/json: schema: type: object properties: 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 description: >- Lifecycle status for a first-class alert. Terminal closed statuses include final disposition. source: type: object properties: category: type: string enum: - detection - trigger - hunting description: >- Broad alert source category. Hunting is reserved for future threat-intel exposure alerts. name: type: string enum: - cotool_detection - hunting - jira - jira-automation - slack - linear - cron - webhook - email - bugcrowd - hackerone 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 - 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 name: type: string minLength: 1 description: Detection display name kind: type: string enum: - cotool - external description: >- Whether this detection attribution is internal or extracted required: - id - agentId - 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 externalProvider: type: - string - 'null' enum: - jira - jira-automation - slack - linear - cron - webhook - email - bugcrowd - hackerone - 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 - null description: Trigger source for external-trigger alerts required: - id - displayId - organizationId - organizationName - title - description - severity - status - source - detection - createdBy - originAgentId - originTriggerId - originRunId - originDetectionHitId - externalProvider - externalRef - externalUrl - assignedAgentId - triageRunId - dedupeKey - createdAt - updatedAt - firstTriagedAt - resolvedAt - derivedDisposition - originAgentName - assignedAgentName - triggerSource totalCount: type: integer minimum: 0 description: Total number of matching alerts for pagination required: - alerts - totalCount '400': description: Bad request — input validation failed or the request was malformed content: application/json: schema: $ref: '#/components/schemas/ValidationError' '401': description: Unauthorized — missing or invalid API key / session content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden — the authenticated user lacks the required permissions content: application/json: schema: $ref: '#/components/schemas/PermissionError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: shell label: cURL source: |- curl -X GET "https://app.cotool.ai/api/alerts" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" components: schemas: ValidationError: type: object properties: error: type: string description: Error message describing what went wrong issues: type: array description: >- Detailed validation issues, present when request or response schema validation fails items: type: object additionalProperties: true required: - error Error: type: object properties: error: type: string description: Error message describing what went wrong required: - error PermissionError: type: object properties: error: type: string description: Error message describing what went wrong missingPerms: type: array description: Permissions the authenticated user is missing for this operation items: type: string 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` ````