> ## Documentation Index
> Fetch the complete documentation index at: https://docs.warrn.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Alert

> Create a new alert in Warrn.

Create an alert and route it through Warrn's triage pipeline. Every alert must belong to a `team_id` - that's how Warrn decides who gets paged.

`service_id` is optional but recommended; setting it scopes the alert to one service so it picks up service-level integrations and the per-service AI Triage setting.

## Deduplication with `alert_alias`

Pass an optional `alert_alias` to make the alert idempotent. Repeated creates with the same alias, while the prior alert is still `open` or `acknowledged`, increment its `occurrence_count` and update its `last_occurred_at` instead of creating a new alert. Once the alert is resolved, the next call with the same alias creates a fresh alert.

The same alias is also accepted by the resolve endpoint, so you can manage an alert's lifecycle without ever storing its Warrn UUID:

```bash theme={null}
curl -X POST "https://api.warrn.io/alerts/prod_system_web-01_cpu_usage_Infra/resolve/?identifierType=alias" \
  -H "Authorization: Bearer warrn_xxx"
```


## OpenAPI

````yaml POST /alerts/
openapi: 3.0.3
info:
  title: Warrn API
  version: '1.0'
  description: |
    Public REST API for Warrn. All endpoints are authenticated with an API key
    issued from Settings → API Keys in the Warrn dashboard.
servers:
  - url: https://api.warrn.io
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Alerts
    description: Native Warrn alert endpoints.
  - name: OpsGenie Compatible
    description: Drop-in OpsGenie Alert API v2 compatibility layer.
paths:
  /alerts/:
    post:
      tags:
        - Alerts
      summary: Create Alert
      description: Create a new alert and route it through Warrn's triage pipeline.
      operationId: createAlert
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AlertCreateRequest'
            examples:
              checkout:
                summary: High error rate on a service
                value:
                  name: High error rate on checkout-service
                  description: Error rate exceeded 5% threshold for the past 3 minutes.
                  severity: high
                  team_id: f1e2d3c4-b5a6-7890-1234-567890abcdef
                  service_id: d4e5f6a7-b8c9-0123-4567-89abcdef0123
                  tags:
                    - checkout
                    - production
                    - error-rate
                  metadata:
                    error_rate: 7.2%
                    threshold: 5%
      responses:
        '200':
          description: Alert created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    AlertCreateRequest:
      type: object
      required:
        - name
        - description
        - severity
        - team_id
      properties:
        name:
          type: string
          maxLength: 255
          description: Short summary of the alert.
        description:
          type: string
          description: Detailed description of the issue.
        severity:
          $ref: '#/components/schemas/Severity'
        team_id:
          type: string
          format: uuid
          description: Team this alert is routed to. Required.
        service_id:
          type: string
          format: uuid
          description: Service this alert belongs to. Optional.
        tags:
          type: array
          items:
            type: string
          default: []
        metadata:
          type: object
          additionalProperties: true
          default: {}
          description: >-
            Arbitrary key-value pairs (runbook URLs, affected hosts, metric
            values).
        alert_alias:
          type: string
          nullable: true
          description: >-
            Dedup key. While an alert with this alias is `open` or
            `acknowledged`, repeat creates with the same alias increment its
            `occurrence_count` instead of creating a new alert. Once resolved,
            the next create with the same alias makes a new alert. Also accepted
            as the path identifier on
            `/alerts/{identifier}/resolve/?identifierType=alias`.
    Alert:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        severity:
          $ref: '#/components/schemas/Severity'
        status:
          $ref: '#/components/schemas/AlertStatus'
        source:
          type: string
          example: integration
        service_id:
          type: string
          format: uuid
          nullable: true
        service_name:
          type: string
          nullable: true
        team_id:
          type: string
          format: uuid
          nullable: true
        team_name:
          type: string
          nullable: true
        tags:
          type: array
          items:
            type: string
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        acknowledged_at:
          type: string
          format: date-time
          nullable: true
        resolved_at:
          type: string
          format: date-time
          nullable: true
        alert_alias:
          type: string
          nullable: true
        occurrence_count:
          type: integer
    Severity:
      type: string
      enum:
        - low
        - medium
        - high
        - critical
    AlertStatus:
      type: string
      enum:
        - open
        - acknowledged
        - resolved
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
                example: Unauthorized
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: warrn_xxx
      description: Bearer token using your Warrn API key.

````