> ## Documentation Index > Fetch the complete documentation index at: https://docs.qumo-deploy.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a notification policy > Routes the organization's events of a category and severity to a channel. For a `webhook` policy the response carries the signing secret, shown only this once. The recipient is masked in every response. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/notifications/policies openapi: 3.1.0 info: title: Qumo Deploy REST API description: > The Qumo Deploy control plane: organizations, projects, signing keys, machine identities, access control, audit and billing. Relay credentials are not issued here: your app signs them with its own [signing keys](/guides/signing-keys). Every operation here is generated against the routes the server registers and checked in CI, so an operation in this reference exists and a route missing from it is deliberately internal (relay mesh, webhooks, probes, operator-only and browser sign-in routes). Errors are JSON objects with one `error` field. What each status code means is in [Error codes](/guides/error-codes); the token scope each permission needs is in [Scopes and permissions](/guides/scopes-permissions). version: 1.0.0 servers: - url: https://api.qumo-deploy.com description: Public API (Bearer tokens only; cookies are ignored) security: [] tags: - name: Account description: The signed-in user's own sessions, tokens, security settings and data. - name: Device flow description: OAuth 2.0 device authorization, used by `qumod login`. - name: Organizations description: Organizations, their members and usage. - name: Projects description: Projects inside an organization. - name: Signing keys description: Keys your app signs relay credentials with. - name: Relays description: Where clients of a broadcast path connect. - name: Identities description: Machine identities, their tokens and IP allowlists. - name: Access control description: Roles, IAM bindings and invitations. - name: Audit description: The audit log and its webhook. - name: Notifications description: Notification policies. - name: Billing description: Plans, usage cost, budgets, invoices and payment methods. - name: Pricing description: Public price list. paths: /v1/notifications/policies: post: tags: - Notifications summary: Create a notification policy description: > Routes the organization's events of a category and severity to a channel. For a `webhook` policy the response carries the signing secret, shown only this once. The recipient is masked in every response. operationId: createNotificationPolicy parameters: - $ref: '#/components/parameters/OrganizationIdQuery' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NotificationPolicyCreateRequest' responses: '201': description: The created policy. content: application/json: schema: $ref: '#/components/schemas/NotificationPolicyCreated' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' security: - token: [] - cliSession: [] - sessionCookie: [] csrfToken: [] components: parameters: OrganizationIdQuery: name: organization_id in: query required: false description: > The organization the request acts in. Required with a personal token or a session, which name no organization themselves; an identity token's organization is implied. schema: type: string format: uuid example: 3f8c2a1e-7b4d-4e9a-9c61-2d5e8f0a1b7c schemas: NotificationPolicyCreateRequest: type: object required: - organization_id - event_category - severity - channel - recipient properties: organization_id: type: string format: uuid description: >- The organization the policy belongs to; must be the organization the request acts in. example: 3f8c2a1e-7b4d-4e9a-9c61-2d5e8f0a1b7c name: type: string description: Display name. example: Security alerts to Slack event_category: type: string description: The event type the policy matches, or `all`. enum: - all - project.delete - iam.binding_create - iam.binding_delete - audit - billing.budget example: audit severity: type: string description: >- The lowest severity the policy sends; a `warning` policy also gets `critical` events. enum: - info - warning - critical example: warning channel: type: string enum: - email - slack - discord - webhook example: slack recipient: type: string description: | The destination: an email address for `email`, a public `https` URL for `webhook`, a `https://hooks.slack.com/` URL for `slack`, a `https://discord.com/api/webhooks/` URL for `discord`. example: https://hooks.slack.com/services/T0000/B0000/XXXXXXXXXXXXXXXX enabled: type: boolean default: false description: Whether the policy sends anything. Omitted means a disabled policy. example: true rate_limit: $ref: '#/components/schemas/NotificationPolicyRateLimit' locale: type: string enum: - ja - en default: en description: The language the notifications are written in. example: en NotificationPolicyCreated: description: A created policy; for a `webhook` policy, with its signing secret. allOf: - $ref: '#/components/schemas/NotificationPolicy' - type: object properties: signing_secret: type: string description: | The secret a `webhook` policy's deliveries are signed with, shown only this once. Each delivery carries `X-Notification-Timestamp` (Unix seconds) and `X-Notification-Signature-256`, the hex HMAC-SHA256 of `.` keyed with this secret. Absent for other channels. example: 9d2f4a6c8e0b1d3f5a7c9e1b3d5f7a9c2e4a6c8f0b1d3e5a7c9f1b3d5e7a9c0b NotificationPolicyRateLimit: type: object description: At most `count` notifications per `period`. required: - count - period properties: count: type: integer example: 10 period: type: string description: A duration such as `30m` or `1h`, or a number of days such as `1d`. example: 1h NotificationPolicy: type: object description: A rule that routes organization events to a notification channel. required: - id - organization_id - name - event_category - severity - channel - recipient - enabled - locale - created_at - updated_at properties: id: type: string format: uuid example: 8f0b2d4e-6a8c-4e1f-a3b5-7c9e1f3a5b7d organization_id: type: string format: uuid example: 3f8c2a1e-7b4d-4e9a-9c61-2d5e8f0a1b7c name: type: string example: Security alerts to Slack event_category: type: string enum: - all - project.delete - iam.binding_create - iam.binding_delete - audit - billing.budget example: audit severity: type: string enum: - info - warning - critical example: warning channel: type: string enum: - email - slack - discord - webhook example: slack recipient: type: string description: Always masked. example: '********' enabled: type: boolean example: true rate_limit: $ref: '#/components/schemas/NotificationPolicyRateLimit' locale: type: string enum: - ja - en example: en invalid_reason: type: string description: | Why the stored recipient no longer passes validation. Present only when it fails; such a policy delivers nothing until it is replaced. example: a Slack recipient must be a https://hooks.slack.com/ URL created_at: type: string format: date-time example: '2026-10-14T09:30:00Z' updated_at: type: string format: date-time example: '2026-10-14T09:30:00Z' Error: type: object required: - error properties: error: type: string description: A human-readable message. example: organization_id is required responses: BadRequest: description: >- Malformed request or failed validation. See [Error codes](/guides/error-codes). content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid credentials. See [Error codes](/guides/error-codes). content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- Authenticated but not allowed (permission, token scope, IP allowlist or CSRF). See [Error codes](/guides/error-codes). content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: token: type: http scheme: bearer bearerFormat: qumo_pat_ description: > A personal access token (`POST /v1/auth/tokens`) or a machine identity token (`POST /v1/projects/{project_id}/identities/{identity_id}/tokens`), both prefixed `qumo_pat_`. A token's scopes cap what it can do; see [Scopes and permissions](/guides/scopes-permissions). A personal token names no organization: on a route whose path names no project or organization, pass `?organization_id=`. cliSession: type: http scheme: bearer description: | The session token `qumod login` obtains through the device flow (`POST /v1/auth/device/token`). It acts as the signed-in user, like a console session, and needs no CSRF token. sessionCookie: type: apiKey in: cookie name: __Host-qumo_session description: | The console's browser session. Accepted only on the console origin (`https://console.qumo-deploy.com`), never on `api.qumo-deploy.com`. A request that changes state must also send `X-CSRF-Token`. csrfToken: type: apiKey in: header name: X-CSRF-Token description: | CSRF token paired with `sessionCookie` on POST, PUT, PATCH and DELETE. Bearer requests do not send it. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.