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

# Create Alert

> Create a new alert for your project. Define trigger conditions based on events or thresholds and configure notification delivery via webhooks or email.



## OpenAPI

````yaml POST /v0/alerts
openapi: 3.1.0
info:
  title: Formo Public API
  description: >-
    REST API for managing Formo projects, analytics, alerts, boards, charts,
    contracts, segments, and AI chat.


    **Auth.** All endpoints require a workspace API key with the appropriate
    scopes (see `x-api-scopes`).


    **Response shape.** Successful responses return the resource directly (or `{
    data: [...], total, page, size, has_more }` for paginated lists). HTTP
    status carries success/failure; there is no envelope wrapping success
    bodies.


    **Errors.** Every non-2xx response uses the `Error` envelope: `{ error: {
    code, message, doc_url, param?, details? } }`. Branch on the
    machine-readable `code` (see `ErrorCode` enum) and follow `doc_url` to the
    matching section of the [errors
    reference](https://docs.formo.so/api/errors).


    **Idempotency.** Pass an `Idempotency-Key` header on POST/PUT/PATCH/DELETE
    to make retries safe; the response is cached for 24 h and replayed on
    duplicate keys.
  version: 0.1.0
  contact:
    name: Formo
    url: https://formo.so
servers:
  - url: https://api.formo.so
    description: API Server (boards, alerts, contracts, segments, profiles, query, import)
  - url: https://events.formo.so
    description: Events Server (event ingestion)
security:
  - WorkspaceApiKey: []
tags:
  - name: Alerts
    description: Manage project alerts and notifications
  - name: Boards
    description: Manage dashboard boards
  - name: Charts
    description: Manage charts within boards
  - name: Contracts
    description: Manage blockchain contract monitoring
  - name: Segments
    description: Manage user segments
  - name: Profiles
    description: Wallet profiles and import
  - name: Query
    description: >-
      Execute SQL queries and call pre-built analytics endpoints (KPIs, top
      pages, lifecycle, retention, revenue). Requires the query:read scope.
  - name: Events
    description: Event ingestion API (events.formo.so)
paths:
  /v0/alerts:
    post:
      tags:
        - Alerts
      summary: Create alert
      description: Create a new alert for the project.
      operationId: createAlert
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                trigger_type:
                  type: string
                  enum:
                    - event
                    - user
                trigger_filters:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      operator:
                        type: string
                      value:
                        type: string
                      numericThreshold:
                        type: string
                    required:
                      - name
                      - value
                recipient:
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - email
                          - slack
                          - webhook
                      value:
                        type: array
                        items:
                          type: string
                secret:
                  type: string
                  description: Webhook signing secret
              required:
                - name
                - trigger_type
                - trigger_filters
            examples:
              eventAlertWithWebhook:
                summary: Alert on swap events from mobile devices with webhook
                value:
                  name: Mobile swap alert
                  trigger_type: event
                  trigger_filters:
                    - name: type
                      value: swap
                      operator: equals
                    - name: device
                      value: mobile
                      operator: equals
                    - name: volume
                      value: '1000'
                      operator: greater
                      numericThreshold: '1000'
                  recipient:
                    - type: webhook
                      value:
                        - https://hooks.myapp.com/formo-alerts
                    - type: email
                      value:
                        - alerts@myapp.com
                  secret: whsec_mysigningsecret123
              eventAlertWithUtmFilter:
                summary: Alert on events from specific UTM campaigns
                value:
                  name: Paid campaign activity
                  trigger_type: event
                  trigger_filters:
                    - name: type
                      value: purchase
                    - name: utm_source
                      value: google
                      operator: equals
                    - name: utm_medium
                      value: cpc
                      operator: equals
                  recipient:
                    - type: slack
                      value:
                        - >-
                          #marketing-alerts|https://hooks.slack.com/services/T00/B00/xxx
              userAlertWithLocationFilter:
                summary: Alert when new users spike from a specific country
                value:
                  name: US user spike
                  trigger_type: user
                  trigger_filters:
                    - name: location
                      value: US
                      operator: equals
                    - name: net_worth_usd
                      value: '10000'
                      operator: greaterOrEqual
                      numericThreshold: '10000'
                  recipient:
                    - type: email
                      value:
                        - team@myapp.com
              eventAlertWithNumericThreshold:
                summary: Alert when users hold >5 tokens in a specific app
                value:
                  name: High token holder alert
                  trigger_type: event
                  trigger_filters:
                    - name: apps
                      value: uniswap
                      operator: greater
                      numericThreshold: '5'
                    - name: chains
                      value: '1'
                      operator: greaterOrEqual
                      numericThreshold: '3'
                  recipient:
                    - type: webhook
                      value:
                        - https://hooks.myapp.com/token-alerts
      responses:
        '201':
          description: Alert created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
components:
  schemas:
    Alert:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
          nullable: true
        trigger_type:
          type: string
          enum:
            - event
            - user
        status:
          type: string
          enum:
            - active
            - inactive
        trigger_filters:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              operator:
                type: string
              value:
                type: string
              numericThreshold:
                type: string
            required:
              - name
              - value
        recipient:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - email
                  - slack
                  - webhook
              value:
                type: array
                items:
                  type: string
            required:
              - type
              - value
        project_id:
          type: string
        has_secret:
          type: boolean
      required:
        - id
        - name
        - trigger_type
        - status
        - project_id
  securitySchemes:
    WorkspaceApiKey:
      type: http
      scheme: bearer
      description: >-
        Workspace API key (e.g. `formo_xxx`). Create one in the Formo dashboard
        under Team Settings > API Keys.

````