> ## 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 and configure webhook notification delivery (including Slack). ## 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.** Every endpoint on `api.formo.so` requires a workspace API key with the appropriate scopes (see `x-api-scopes`). The one exception is `POST /v0/raw_events`, which runs on `events.formo.so` and authenticates with the project SDK write key instead. **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.** Non-2xx responses from `api.formo.so` use the `Error` envelope, with two exceptions: some rate-limit rejections reply in plain text, and `POST /v0/raw_events` returns a plain `{ "error": "..." }` object. Treat the HTTP status as authoritative and parse defensively: `{ 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 write requests to alerts, boards, charts, contracts, segments, and import to make retries safe; the response is cached for 24 h and replayed on duplicate keys. Profile writes and `POST /v0/query` do not support it. 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 parameters: - $ref: '#/components/parameters/IdempotencyKey' 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: $ref: '#/components/schemas/AlertFilter' 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: - value: swap field: type op: eq - value: mobile field: device op: eq - value: '1000' numericThreshold: '1000' field: volume op: gt 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: - value: purchase field: type - value: google field: utm_source op: eq - value: cpc field: utm_medium op: eq 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: - value: US field: location op: eq - value: '10000' numericThreshold: '10000' field: net_worth_usd op: gte 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: - value: uniswap numericThreshold: '5' field: apps op: gt - value: '1' numericThreshold: '3' field: chains op: gte recipient: - type: webhook value: - https://hooks.myapp.com/token-alerts responses: '201': description: Alert created content: application/json: schema: $ref: '#/components/schemas/Alert' '400': $ref: '#/components/responses/BadRequest' '409': $ref: '#/components/responses/Conflict' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false schema: type: string maxLength: 255 description: >- Optional unique value (e.g. a UUID v4) that lets you safely retry POST/PUT/PATCH/DELETE requests. The first request runs normally; subsequent requests with the same key replay the stored response (status + body) for 24 hours, so retries can never double-create or double-charge. Two concurrent requests with the same key return `409 IDEMPOTENCY_IN_PROGRESS`. Generate a fresh key per logical operation. schemas: AlertFilter: type: object description: A project-alert trigger filter using the canonical envelope. properties: field: type: string description: Column or property targeted by this filter. op: type: string enum: - eq - neq - gt - lt - gte - lte - in - nin - startsWith - endsWith - contains - notEmpty - isEmpty description: Canonical comparison operator token. value: type: string numericThreshold: type: string required: - field - op - value 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: $ref: '#/components/schemas/AlertFilter' 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 Error: type: object description: >- Standard error envelope returned by every public API endpoint for any non-2xx response. The HTTP status code carries success/failure; the body provides a machine-readable `code`, a human-readable `message`, and a `doc_url` pointing at the matching section of the docs so agents can fetch context on the fly. properties: error: type: object required: - code - message - doc_url properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: >- Human-readable error description. Wording may change between releases, so branch on `code`, not `message`. doc_url: type: string format: uri description: >- Link to the matching section of the errors reference at https://docs.formo.so/api/errors. param: type: string description: >- When the error pertains to a specific request field, the dotted path to that field (e.g. `body.trigger_filters.0.value`). details: type: object additionalProperties: true description: >- Code-specific extra context. For `INVALID_VALIDATION_REQUEST` this is a `{ fieldPath: message }` map of every Zod validation failure. required: - error ErrorCode: type: string description: >- Stable, enumerated error codes. New codes may be added in any release; clients should treat unknown codes as the closest matching HTTP status family. enum: - INTERNAL_SERVER_ERROR - INVALID_VALIDATION_REQUEST - UNAUTHORIZED - BAD_REQUEST - FORBIDDEN - NOT_FOUND - CONFLICT - INVALID_CHAIN_ID - CONTEXT_LIMIT_EXCEEDED - SERVICE_UNAVAILABLE - TOO_MANY_REQUESTS - IDEMPOTENCY_IN_PROGRESS - INVALID_IDEMPOTENCY_KEY responses: BadRequest: description: >- The request was rejected. `code` is either `INVALID_VALIDATION_REQUEST` (Zod schema mismatch; `details` carries a `{ fieldPath: message }` map) or `BAD_REQUEST` (semantic validation failure outside Zod, e.g. mismatched IDs, business-rule violations). Branch on `code`, not status, to tell the two apart. content: application/json: schema: $ref: '#/components/schemas/Error' examples: validation: summary: Zod schema mismatch value: error: code: INVALID_VALIDATION_REQUEST message: Invalid request data doc_url: https://docs.formo.so/api/errors#invalid_validation_request details: body.name: String must contain at least 1 character(s) semantic: summary: Semantic validation failure value: error: code: BAD_REQUEST message: Target board must be different from the current board doc_url: https://docs.formo.so/api/errors#bad_request Conflict: description: >- The request conflicts with current resource state, or an `Idempotency-Key` request with the same key is currently in flight. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: IDEMPOTENCY_IN_PROGRESS message: >- A request with this Idempotency-Key is already in progress. Retry shortly. doc_url: https://docs.formo.so/api/errors#idempotency_in_progress securitySchemes: WorkspaceApiKey: type: http scheme: bearer description: >- Workspace API key (e.g. `formo_xxx`). Create one in the Formo dashboard under Team Settings > API. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.