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

# Create a notifier

> Creates a notifier destination in a project. Choose `NOTIFIER_TYPE_EMAIL`, `NOTIFIER_TYPE_SLACK_WEBHOOK`, or `NOTIFIER_TYPE_WEBHOOK` and provide the matching destination fields.

<Note>
  **Related guide**: Notifiers guide. See the [Notifiers guide](/ai-studio/observability/notifiers) for a walkthrough with examples.
</Note>


## OpenAPI

````yaml post /v2/notifiers
openapi: 3.1.0
info:
  title: orq.ai API
  version: '2.0'
  description: orq.ai API documentation
servers:
  - url: https://my.orq.ai
security:
  - ApiKey: []
tags:
  - name: Chunking
    description: Split text into smaller chunks for retrieval and generation workflows.
  - name: File Systems
    description: >-
      Create and manage persistent file systems that agents and MCP clients read
      from and write to.
  - name: Knowledge Bases
    description: Create and manage knowledge bases used by agents and retrieval workflows.
  - name: Memory Stores
    description: Create and manage memory stores, memories, and memory documents.
  - name: Evals
    description: Run an evaluator against a conversation and its result
  - name: Logs
    description: >-
      OpenTelemetry log query API. Search, filter, aggregate, and facet log
      records ingested via OTLP.
  - name: Reporting
    description: >-
      GenAI reporting API over canonical analytics rollups. Accepts a metric
      name, time range, grain, group-by, and filters; returns a typed time
      series and optional totals.
  - name: Traces
    description: >-
      Query and inspect ingested trace data: search trace summaries, aggregate
      metrics, and read individual traces and their spans.
  - description: List models available through the AI Router.
    name: Models
  - name: Policies
  - name: Alerts
    description: >-
      Alerts evaluate a Reporting API metric on a fixed interval and fire
      notifications through notifiers when the value breaches a threshold. Each
      breach opens a trigger that tracks the incident until the value recovers.
  - name: Annotation Queues
    description: Annotation queues collect spans for human review.
  - name: API keys
    description: >-
      API keys authenticate programmatic access to the workspace. They expose
      opaque tokens, per-domain access grants, and budget and rate-limit
      constraints.
  - name: Audit Logs
    description: Audit logs record workspace entity changes and access-relevant events.
  - name: Budgets
    description: >-
      Budgets govern spend, token usage, and request rate across six scopes:
      workspace, project, identity, API key, provider, and model. Every
      applicable budget is enforced, and the most restrictive limit applies per
      dimension.
  - name: Files
    description: File upload and retrieval operations.
  - name: Guardrail Rules
    description: >-
      Guardrail Rules conditionally enforce evaluators and plugins for AI
      Gateway traffic. Rules may be scoped to a project or the whole workspace.
  - name: Hub
    description: Hub items are reusable templates available to a workspace.
  - name: Identities
    description: >-
      Identities represent end users from your system for usage and engagement
      tracking.
  - name: Management keys
    description: >-
      Management keys are workspace-scoped credentials that authenticate
      programmatic access to workspace administration surfaces (API keys,
      budgets). Unlike project-scoped API keys, a management key always operates
      at the workspace level.
  - name: MCP Gateway
    description: >-
      Register upstream MCP servers, discover and sync their tools, and assemble
      gateways that expose a curated tool surface to MCP clients.
  - name: Model Catalog
    description: >-
      Browse the orq.ai model catalog: every model orq offers, across every
      provider, with pricing, capabilities and benchmark data. List endpoints
      only return models that are not deprecated. This API is public, requires
      no authentication, and is rate limited to 120 requests per minute per IP.
      Responses carry a 5-minute cache-control max-age.
  - name: Notifiers
    description: Notifier destinations used to send delivery and workflow notifications.
  - name: Projects
    description: Projects organize resources within a workspace
  - name: Routing Rules
    description: >-
      Routing Rules conditionally select models and enforce request plugins for
      AI Gateway traffic. Rules are evaluated by ascending priority and may be
      scoped to a project or the whole workspace.
  - name: Threads
    description: Threads group related trace invocations and their aggregate usage
  - name: Skills
    description: >-
      Skills are modular instructions you can use to codify processes and
      conventions
  - name: Smart Routers
    description: >-
      Create and manage workspace Smart Routers. A Smart Router selects a model
      from an eligible pool for each request according to a quality, balanced,
      or cost profile.
  - name: Webhooks
    description: >-
      Create and manage webhooks that deliver workspace events to external HTTPS
      endpoints.
  - name: Workspaces
    description: >-
      A workspace is the tenant. Create is called from a user session during
      onboarding; Get, List, and Update are the public management surface.
  - name: Workspace Security
    description: >-
      Workspace-level domain verification and IP allowlist controls. These
      operations are restricted to workspace administrators.
  - name: Workspace Settings
    description: >-
      Workspace-level settings managed with a workspace credential. A workspace
      is the tenant, so these settings are a singleton — there is nothing to
      create or delete, only read and update.
  - name: Responses
  - description: Run agents on a cron cadence. Minimum firing interval is 1 hour.
    name: Agent Schedules
  - name: Embeddings
  - name: Telemetry
    description: >-
      Unified query envelope for traces, metrics, and logs. One request shape,
      one filter dialect, and one response shape per source, validated by a
      per-source registry.
  - description: Beta. Run typed classification questions against a classify model.
    name: Classify
  - description: Search Gateway with managed credits or BYOK.
    name: Web Search
externalDocs:
  url: https://docs.orq.ai
  description: orq.ai Documentation
paths:
  /v2/notifiers:
    post:
      tags:
        - Notifiers
      summary: Create a notifier
      description: >-
        Creates a notifier destination in a project. Choose
        `NOTIFIER_TYPE_EMAIL`, `NOTIFIER_TYPE_SLACK_WEBHOOK`, or
        `NOTIFIER_TYPE_WEBHOOK` and provide the matching destination fields.
      operationId: NotifierCreate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNotifierRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateNotifierResponse'
      x-code-samples:
        - lang: curl
          label: Core - Create email notifier
          source: |
            curl --request POST \
              --url 'https://my.orq.ai/v2/notifiers' \
              --header "Authorization: Bearer $ORQ_API_KEY" \
              --header 'Content-Type: application/json' \
              --data '{
                "project_id": "proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V",
                "display_name": "Production alerts",
                "type": "NOTIFIER_TYPE_EMAIL",
                "emails": ["ops@example.com", "alerts@example.com"],
                "metadata": {"environment": "production"}
              }'
        - lang: python
          label: Python - Create email notifier
          source: |
            import os
            from orq_ai_sdk import Orq

            client = Orq(api_key=os.environ["ORQ_API_KEY"])

            result = client.notifiers.create(
                project_id="proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V",
                display_name="Production alerts",
                type="NOTIFIER_TYPE_EMAIL",
                emails=["ops@example.com", "alerts@example.com"],
                metadata={"environment": "production"},
            )

            print(result.notifier._id)
        - lang: typescript
          label: Node.js - Create email notifier
          source: |
            import { Orq } from '@orq-ai/node';

            const client = new Orq({
              apiKey: process.env.ORQ_API_KEY,
            });

            const result = await client.notifiers.create({
              projectId: 'proj_01HZXW2K7Y8Q9M0N1P2R3S4T5V',
              displayName: 'Production alerts',
              type: 'NOTIFIER_TYPE_EMAIL',
              emails: ['ops@example.com', 'alerts@example.com'],
              metadata: { environment: 'production' },
            });

            console.log(result.notifier._id);
components:
  schemas:
    CreateNotifierRequest:
      required:
        - display_name
        - type
      type: object
      properties:
        project_id:
          type: string
          description: >-
            Optional. Workspace-scoped callers may set this to create a
            project-scoped notifier, or omit it for a workspace-wide notifier.
            Project-scoped API keys create in the API key's project.
        display_name:
          type: string
          description: Required. Human-readable notifier name.
        metadata:
          type: object
          description: Optional. Custom JSON metadata stored with the notifier.
        type:
          $ref: '#/components/schemas/NotifierType'
          description: >-
            Required. Destination type. Use `NOTIFIER_TYPE_EMAIL`,
            `NOTIFIER_TYPE_SLACK_WEBHOOK`, or `NOTIFIER_TYPE_WEBHOOK`.
        emails:
          type: array
          items:
            type: string
          description: >-
            Required when `type` is `NOTIFIER_TYPE_EMAIL`. Omit for other
            notifier types.
        incoming_webhook_url:
          type: string
          description: >-
            Required when `type` is `NOTIFIER_TYPE_SLACK_WEBHOOK`. Omit for
            other notifier types.
        webhook_url:
          type: string
          description: >-
            Required when `type` is `NOTIFIER_TYPE_WEBHOOK`. Omit for other
            notifier types.
        headers:
          type: object
          description: >-
            Optional generic webhook headers. Each value may be a string or `{
            "secret": true, "value": "..." }`.
      description: >-
        Create notifier request. `project_id`, `display_name`, and `type` are
        always required. The destination field required by `type` is captured in
        `oneOf`.
      oneOf:
        - title: Email notifier create request
          type: object
          description: '`emails` is required when `type` is `NOTIFIER_TYPE_EMAIL`.'
          required:
            - type
            - emails
          properties:
            type:
              type: string
              enum:
                - NOTIFIER_TYPE_EMAIL
            emails:
              type: array
              items:
                type: string
              description: >-
                Required when `type` is `NOTIFIER_TYPE_EMAIL`. Omit for other
                notifier types.
        - title: Slack webhook notifier create request
          type: object
          description: >-
            `incoming_webhook_url` is required when `type` is
            `NOTIFIER_TYPE_SLACK_WEBHOOK`.
          required:
            - type
            - incoming_webhook_url
          properties:
            type:
              type: string
              enum:
                - NOTIFIER_TYPE_SLACK_WEBHOOK
            incoming_webhook_url:
              type: string
              description: >-
                Required when `type` is `NOTIFIER_TYPE_SLACK_WEBHOOK`. Omit for
                other notifier types.
        - title: Generic webhook notifier create request
          type: object
          description: >-
            `webhook_url` is required when `type` is `NOTIFIER_TYPE_WEBHOOK`;
            `headers` is optional.
          required:
            - type
            - webhook_url
          properties:
            type:
              type: string
              enum:
                - NOTIFIER_TYPE_WEBHOOK
            webhook_url:
              type: string
              description: >-
                Required when `type` is `NOTIFIER_TYPE_WEBHOOK`. Omit for other
                notifier types.
    CreateNotifierResponse:
      required:
        - notifier
      type: object
      properties:
        notifier:
          $ref: '#/components/schemas/Notifier'
    NotifierType:
      type: string
      enum:
        - NOTIFIER_TYPE_UNSPECIFIED
        - NOTIFIER_TYPE_EMAIL
        - NOTIFIER_TYPE_SLACK_WEBHOOK
        - NOTIFIER_TYPE_WEBHOOK
    Notifier:
      required:
        - _id
        - display_name
        - created_at
        - updated_at
        - type
      type: object
      properties:
        _id:
          type: string
          description: Unique notifier identifier assigned by ORQ.
        project_id:
          type: string
          description: >-
            Project that contains the notifier. Empty for workspace-wide
            notifiers.
        display_name:
          type: string
          description: Human-readable notifier name.
        created_at:
          type: string
          description: Time when the notifier was created.
          format: date-time
        updated_at:
          type: string
          description: Time when the notifier was last updated.
          format: date-time
        created_by_id:
          type: string
          description: User ID that created the notifier.
        updated_by_id:
          type: string
          description: User ID that last updated the notifier.
        metadata:
          type: object
          description: Custom JSON metadata stored with the notifier.
        type:
          $ref: '#/components/schemas/NotifierType'
          description: >-
            Notifier destination type. Use `NOTIFIER_TYPE_EMAIL`,
            `NOTIFIER_TYPE_SLACK_WEBHOOK`, or `NOTIFIER_TYPE_WEBHOOK`.
        emails:
          type: array
          items:
            type: string
          description: Email addresses notified when `type` is `NOTIFIER_TYPE_EMAIL`.
        incoming_webhook_url:
          type: string
          description: >-
            Slack incoming webhook URL used when `type` is
            `NOTIFIER_TYPE_SLACK_WEBHOOK`.
        webhook_url:
          type: string
          description: Generic webhook URL used when `type` is `NOTIFIER_TYPE_WEBHOOK`.
        headers:
          type: object
          description: >-
            Optional HTTP headers for generic webhooks. Each entry may be a
            string value or an object with `secret` and `value`.
      description: >-
        Notifier resource. The destination field present on the resource depends
        on `type` and is captured in `oneOf`.
      oneOf:
        - title: Email notifier
          type: object
          description: '`emails` is present for email notifiers.'
          required:
            - type
            - emails
          properties:
            type:
              type: string
              enum:
                - NOTIFIER_TYPE_EMAIL
            emails:
              type: array
              items:
                type: string
              description: Email addresses notified when `type` is `NOTIFIER_TYPE_EMAIL`.
        - title: Slack webhook notifier
          type: object
          description: '`incoming_webhook_url` is present for Slack webhook notifiers.'
          required:
            - type
            - incoming_webhook_url
          properties:
            type:
              type: string
              enum:
                - NOTIFIER_TYPE_SLACK_WEBHOOK
            incoming_webhook_url:
              type: string
              description: >-
                Slack incoming webhook URL used when `type` is
                `NOTIFIER_TYPE_SLACK_WEBHOOK`.
        - title: Generic webhook notifier
          type: object
          description: >-
            `webhook_url` is present for generic webhook notifiers; `headers` is
            optional.
          required:
            - type
            - webhook_url
          properties:
            type:
              type: string
              enum:
                - NOTIFIER_TYPE_WEBHOOK
            webhook_url:
              type: string
              description: Generic webhook URL used when `type` is `NOTIFIER_TYPE_WEBHOOK`.
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.