> ## Documentation Index > Fetch the complete documentation index at: https://www.ravion.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create NotificationRule > Create a notification rule. POST /notification-rules in the Ravion API reference. ## OpenAPI ````yaml https://api.ravion.com/openapi.yaml post /notification-rules openapi: 3.0.0 info: title: Ravion version: 0.0.0 servers: - url: https://api.ravion.com security: - BearerAuth: [] tags: - name: Projects - name: Environments - name: FeatureFlags - name: Pipelines - name: PipelineRuns - name: TerraformResources - name: TerraformExecutionSummaries - name: PipelineStepExecutions - name: AwsCloudWatch - name: AwsAmp - name: PipelineVersions - name: Organizations - name: Stacks - name: StackWorkspaces - name: Auth - name: OAuth - name: User - name: Health - name: Memberships - name: ServiceAccounts - name: Integrations - name: AwsDefaultNetworks - name: AwsAccounts - name: ApiKeys - name: EksPrometheus - name: EksLoki - name: ExecutionEnvironments - name: ModuleDefinitions - name: ModuleCategories - name: ModuleVersions - name: ModuleInstances - name: DefaultValueDefinitions - name: DefaultValues - name: CodeSources - name: Github - name: GitHub Actions - name: Alerts - name: Gitlab - name: Slack - name: Git - name: MergeQueues - name: Values - name: Deployments - name: DeploymentResources - name: InfrastructureEvents - name: WebSocket - name: Domains - name: AcmCertificates - name: NotificationDestinations - name: NotificationDispatches - name: NotificationEvents - name: NotificationRules - name: Activity - name: Describe - name: Reports - name: BillingPlans - name: BillingAccounts - name: BillingCycles - name: BillingUsageSummaries - name: BillingAddOns - name: BillingInvoices - name: Authorization - name: Sandboxes - name: SandboxCommands - name: SandboxPorts - name: Apps paths: /notification-rules: post: tags: - NotificationRules summary: Create NotificationRule description: >- Create a notification rule. The rule must be able to deliver what it matches: it names at least one audience, every destination it names exists in this organization, its computed audiences and `live` delivery suit the events it watches, and every scope condition id names a project, environment, module instance or pipeline of this organization. A rule that breaks one of these is refused with 400 and the `NotificationRule` error naming the problem; see `audiences`, `delivery` and `conditions`. Available to organizations with notifications enabled; refused with 403 otherwise. operationId: CreateNotificationRule requestBody: content: application/json: schema: additionalProperties: false description: >- Request body for creating resources, excluding read-only properties properties: data: additionalProperties: false description: >- Filters a model to only include properties visible during Create lifecycle. properties: audiences: description: >- NOTIFY — recipients this rule delivers matched events to. At least one is required; an empty list is refused with 400 `NotificationRule:AUDIENCE_REQUIRED`. A destination audience must name a notification destination of this organization, or the rule is refused with 400 `NotificationRule:DESTINATION_NOT_FOUND`. A computed audience resolves only for some events: `APPROVERS` for "pipeline.run.approval_requested" alone, and `RUN_STARTER` for events about a pipeline run (the `runScoped` events of List notification events: "pipeline.run.*" and "step.*"). A computed audience on a rule watching any other event is refused with 400 `NotificationRule:COMPUTED_AUDIENCE_NOT_APPLICABLE`. items: $ref: '#/components/schemas/Events.NotificationRuleAudience' type: array conditions: description: >- IF — conditions AND-ed together; empty matches unconditionally. Every id a scope condition names must be a project, environment, module instance or pipeline of this organization; an id that names nothing is refused with 400 `NotificationRule:SCOPE_TARGET_NOT_FOUND`. items: $ref: '#/components/schemas/Events.NotificationRuleCondition' type: array content: allOf: - $ref: '#/components/schemas/Events.NotificationRuleContent' description: >- WITH — presentation options applied when rendering a matched event. delivery: allOf: - $ref: '#/components/schemas/Events.NotificationRuleDelivery' description: >- VIA — how a matched event reaches its audiences. `live` follows one pipeline run on a single card, so every event a live rule watches must be about a run (`runScoped` in List notification events), and a glob must match only such events; any other event is refused with 400 `NotificationRule:LIVE_DELIVERY_NOT_RUN_SCOPED`. An `escalate` delivery's target must be a notification destination of this organization, or the rule is refused with 400 `NotificationRule:DESTINATION_NOT_FOUND`. enabled: description: Whether this rule is evaluated against incoming events. type: boolean eventIds: description: >- WHEN — the events this rule watches: event ids from the event catalog (e.g. "pipeline.run.failed"), or family globs ending in ".*" (e.g. "module.deployment.*") that match every event id starting with the part before the ".*". An id the catalog does not declare, or a glob no event id falls under, is refused with `NotificationRule:UNKNOWN_EVENT_ID`. List notification events for the events worth offering a person. items: type: string type: array name: description: User-facing rule name. minLength: 1 type: string ownerUserId: description: >- Owning user of a personal rule; absent for an organization-wide rule, visible to and editable by anyone who can manage notification rules. Only the calling user's own id is accepted. A personal rule is listed, read, changed, test-sent and deleted by its owner alone, delivers only to its owner's own Slack DM or email, and only for events about resources its owner can still read; a Slack channel or webhook destination is refused. Fixed at creation. nullable: true type: string required: - name - enabled - eventIds - conditions - audiences - delivery - content type: object required: - data type: object required: true responses: '201': content: application/json: schema: additionalProperties: false properties: data: $ref: '#/components/schemas/NotificationRule' required: - data type: object description: >- The request has succeeded and a new resource has been created as a result. '400': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: The request is invalid or malformed. '401': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: You are not authenticated '403': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: You do not have permission to access this resource. '422': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: Client error '500': content: application/json: schema: $ref: '#/components/schemas/Errors.UserFacingErrorData' description: Server error components: schemas: Events.NotificationRuleAudience: description: >- One recipient of a NotificationRule's `NOTIFY`, discriminated by `kind`. A rule's audience list may mix fixed destinations and computed audiences. discriminator: mapping: computed: '#/components/schemas/Events.ComputedAudience' destination: '#/components/schemas/Events.DestinationAudience' propertyName: kind oneOf: - $ref: '#/components/schemas/Events.DestinationAudience' - $ref: '#/components/schemas/Events.ComputedAudience' type: object Events.NotificationRuleCondition: description: >- One clause of a NotificationRule's `IF`, discriminated by `kind`. A rule's conditions list is AND-ed together; within a single condition, the values it names (a scope condition's `in`, a time condition's `weekdays`) are OR-ed. discriminator: mapping: actor: '#/components/schemas/Events.ActorCondition' edge: '#/components/schemas/Events.EdgeCondition' payload: '#/components/schemas/Events.PayloadCondition' scope: '#/components/schemas/Events.ScopeCondition' time: '#/components/schemas/Events.TimeCondition' propertyName: kind oneOf: - $ref: '#/components/schemas/Events.ScopeCondition' - $ref: '#/components/schemas/Events.PayloadCondition' - $ref: '#/components/schemas/Events.EdgeCondition' - $ref: '#/components/schemas/Events.TimeCondition' - $ref: '#/components/schemas/Events.ActorCondition' type: object Events.NotificationRuleContent: additionalProperties: false description: |- A NotificationRule's `WITH` clause: presentation options applied when rendering a matched event for delivery. Every rule carries the same three fields, so — unlike conditions, audiences, and delivery — this is a plain model rather than a discriminated union. properties: mention: description: |- Whether delivery should `@mention` the audience in channels that support it (e.g. Slack), rather than posting silently. type: boolean verbosity: $ref: '#/components/schemas/Events.NotificationContentVerbosity' required: - mention - verbosity type: object Events.NotificationRuleDelivery: description: |- A NotificationRule's `VIA` clause: how a matched event reaches its audiences, discriminated by `mode`. discriminator: mapping: digest: '#/components/schemas/Events.DigestDelivery' each: '#/components/schemas/Events.EachDelivery' escalate: '#/components/schemas/Events.EscalateDelivery' live: '#/components/schemas/Events.LiveDelivery' oneshot: '#/components/schemas/Events.OneshotDelivery' propertyName: mode oneOf: - $ref: '#/components/schemas/Events.LiveDelivery' - $ref: '#/components/schemas/Events.EachDelivery' - $ref: '#/components/schemas/Events.OneshotDelivery' - $ref: '#/components/schemas/Events.DigestDelivery' - $ref: '#/components/schemas/Events.EscalateDelivery' type: object NotificationRule: additionalProperties: false properties: audiences: description: >- NOTIFY — recipients this rule delivers matched events to. At least one is required; an empty list is refused with 400 `NotificationRule:AUDIENCE_REQUIRED`. A destination audience must name a notification destination of this organization, or the rule is refused with 400 `NotificationRule:DESTINATION_NOT_FOUND`. A computed audience resolves only for some events: `APPROVERS` for "pipeline.run.approval_requested" alone, and `RUN_STARTER` for events about a pipeline run (the `runScoped` events of List notification events: "pipeline.run.*" and "step.*"). A computed audience on a rule watching any other event is refused with 400 `NotificationRule:COMPUTED_AUDIENCE_NOT_APPLICABLE`. items: $ref: '#/components/schemas/Events.NotificationRuleAudience' type: array conditions: description: >- IF — conditions AND-ed together; empty matches unconditionally. Every id a scope condition names must be a project, environment, module instance or pipeline of this organization; an id that names nothing is refused with 400 `NotificationRule:SCOPE_TARGET_NOT_FOUND`. items: $ref: '#/components/schemas/Events.NotificationRuleCondition' type: array content: allOf: - $ref: '#/components/schemas/Events.NotificationRuleContent' description: WITH — presentation options applied when rendering a matched event. createdAt: allOf: - $ref: '#/components/schemas/UtcDateTime' readOnly: true delivery: allOf: - $ref: '#/components/schemas/Events.NotificationRuleDelivery' description: >- VIA — how a matched event reaches its audiences. `live` follows one pipeline run on a single card, so every event a live rule watches must be about a run (`runScoped` in List notification events), and a glob must match only such events; any other event is refused with 400 `NotificationRule:LIVE_DELIVERY_NOT_RUN_SCOPED`. An `escalate` delivery's target must be a notification destination of this organization, or the rule is refused with 400 `NotificationRule:DESTINATION_NOT_FOUND`. enabled: description: Whether this rule is evaluated against incoming events. type: boolean eventIds: description: >- WHEN — the events this rule watches: event ids from the event catalog (e.g. "pipeline.run.failed"), or family globs ending in ".*" (e.g. "module.deployment.*") that match every event id starting with the part before the ".*". An id the catalog does not declare, or a glob no event id falls under, is refused with `NotificationRule:UNKNOWN_EVENT_ID`. List notification events for the events worth offering a person. items: type: string type: array id: readOnly: true type: string name: description: User-facing rule name. minLength: 1 type: string organizationId: readOnly: true type: string ownerUserId: description: >- Owning user of a personal rule; absent for an organization-wide rule, visible to and editable by anyone who can manage notification rules. Only the calling user's own id is accepted. A personal rule is listed, read, changed, test-sent and deleted by its owner alone, delivers only to its owner's own Slack DM or email, and only for events about resources its owner can still read; a Slack channel or webhook destination is refused. Fixed at creation. nullable: true type: string updatedAt: allOf: - $ref: '#/components/schemas/UtcDateTime' readOnly: true required: - id - createdAt - updatedAt - organizationId - name - enabled - eventIds - conditions - audiences - delivery - content type: object Errors.UserFacingErrorData: additionalProperties: false description: |- User-facing error presentation data. This is what the API returns to the frontend after formatting ErrorData using CEL templates from the error registry. Used for both: - Error fields on domain models (e.g., PipelineRun.error) - API error response bodies (HTTP 4xx/5xx responses) properties: action: allOf: - $ref: '#/components/schemas/Errors.Action' description: Optional action to help resolve the error code: description: Full error code, e.g., "Ravion:Pipeline:NOT_FOUND" type: string description: description: Additional description with more details type: string details: description: Structured details rendered as user-facing sections. items: $ref: '#/components/schemas/Errors.UserFacingErrorDetailSection' type: array isInternal: description: >- Indicates whether this error is internal (only set when ShowInternal=true). This allows SUPERADMINs to identify internal errors while viewing full details. type: boolean message: description: Main error message (required) type: string metadata: additionalProperties: {} description: >- Error params/metadata. Stripped for internal errors unless superadmin. type: object requestId: description: Request ID for correlating errors with server logs. type: string required: - code - message type: object Events.ComputedAudience: additionalProperties: false description: |- Sends to a set of recipients resolved from the triggering event's own context rather than a fixed destination. properties: computed_kind: $ref: '#/components/schemas/Events.ComputedAudienceType' kind: enum: - computed type: string required: - kind - computed_kind type: object Events.DestinationAudience: additionalProperties: false description: Sends to a specific, pre-configured NotificationDestination. properties: destination_id: type: string kind: enum: - destination type: string required: - kind - destination_id type: object Events.ActorCondition: additionalProperties: false description: |- Matches when the Activity entry's actor is one of `identities`. Each is written `:`, for example "member:mem_…", "api_key:apikey_…", "mcp_client:mem_…" or "service_account:svcact_…", or the bare "system" for Ravion itself. A member's key does not match that member's MCP client; name both to include both. Events that are not Activity entries carry no actor and never match. properties: identities: description: Identities to match against, OR-ed together. items: type: string maxItems: 50 minItems: 1 type: array kind: enum: - actor type: string required: - kind - identities type: object Events.EdgeCondition: additionalProperties: false description: |- Matches a transition in a subject's run history rather than a single event in isolation — the "only tell me the first time this fails" or "only tell me after 3 in a row" shape a plain event filter can't express on its own. properties: edge_kind: $ref: '#/components/schemas/Events.EdgeKind' kind: enum: - edge type: string 'n': description: >- Consecutive-occurrence threshold. Meaningful only when `edge_kind` is CONSECUTIVE. format: int32 type: integer required: - kind - edge_kind type: object Events.PayloadCondition: additionalProperties: false description: >- Matches on a field within the triggering event's enriched payload — for example a pipeline run's failed step count, or an alarm's threshold. `field` is intentionally a free string rather than a closed enum: the set of matchable fields is exactly what each event's enriched payload (see payloads.tsp) carries, which differs per catalog id. properties: field: description: Dot-path into the event's enriched payload, e.g. "failedStepCount". type: string kind: enum: - payload type: string op: $ref: '#/components/schemas/Events.PayloadConditionOperator' value: description: |- Comparison value, carried as a string regardless of the payload field's own type — `OVER`/`UNDER` parse it numerically at evaluation time. type: string required: - kind - field - op - value type: object Events.ScopeCondition: additionalProperties: false description: |- Matches when the triggering event's entity of `field` kind is one of `in` — an org's "only notify me about these projects" filter. Multiple ids in `in` are OR-ed together. properties: field: $ref: '#/components/schemas/Events.ScopeConditionField' in: description: Entity ids to match against, OR-ed together. items: type: string type: array kind: enum: - scope type: string required: - kind - field - in type: object Events.TimeCondition: additionalProperties: false description: |- Matches while the current time, in `timezone`, falls within the `from`–`to` window on one of `weekdays` — the "only page me during business hours" shape. properties: from: description: Window start, as "HH:MM" in `timezone`. type: string kind: enum: - time type: string timezone: description: >- IANA timezone name the window is evaluated in, e.g. "America/New_York". type: string to: description: Window end, as "HH:MM" in `timezone`. type: string weekdays: description: Days the window applies on. Omitted means every day. items: $ref: '#/components/schemas/Events.Weekday' type: array required: - kind - from - to - timezone type: object Events.NotificationContentVerbosity: description: How much detail a delivered notification includes. enum: - COMPACT - DETAILED type: string Events.DigestDelivery: additionalProperties: false description: |- Batches matching events and delivers them together on a fixed interval, e.g. an hourly digest instead of one notification per event. properties: digest_window_minutes: description: Length of the batching window, in minutes. format: int32 type: integer mode: enum: - digest type: string required: - mode - digest_window_minutes type: object Events.EachDelivery: additionalProperties: false description: |- Delivers every matching event immediately as its own message, even on Slack for a pipeline run, where `live` would edit one card instead. properties: mode: enum: - each type: string required: - mode type: object Events.EscalateDelivery: additionalProperties: false description: |- Delivers immediately to the rule's own audiences, then — if not acknowledged — re-sends to a fallback destination after a delay, e.g. paging a secondary on-call channel when the primary one goes unanswered. properties: escalate_after_minutes: description: Delay before escalating, in minutes. format: int32 type: integer escalate_to_destination_id: description: Destination the escalation is sent to. type: string mode: enum: - escalate type: string required: - mode - escalate_after_minutes - escalate_to_destination_id type: object Events.LiveDelivery: additionalProperties: false description: |- Delivers every matching event immediately, one notification per event. On a Slack destination, a pipeline run's events edit one card in place as the run progresses instead of posting a message each. properties: mode: enum: - live type: string required: - mode type: object Events.OneshotDelivery: additionalProperties: false description: |- Delivers a single matching event immediately and then disables further delivery from this rule until re-enabled — a one-time page. properties: mode: enum: - oneshot type: string required: - mode type: object UtcDateTime: description: UTC RFC3339 timestamp with a required Z suffix format: date-time pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?Z$ type: string x-go-type: apitypes.UTCDateTime x-go-type-import: name: apitypes path: ravion/api-go/pkg/apitypes Errors.Action: additionalProperties: false description: Action to help user resolve the error properties: label: description: Button/link label text type: string url: description: URL to navigate to for resolution type: string required: - label - url type: object Errors.UserFacingErrorDetailSection: additionalProperties: false description: Structured user-facing error detail section. properties: items: description: List of detail values for this section. items: type: string type: array object: additionalProperties: {} description: Structured detail payload for object rendering. type: object render: description: Rendering hint for clients. Valid values are list or object. type: string title: description: Detail section title shown in the UI. type: string required: - title - render type: object Events.ComputedAudienceType: description: |- A computed audience resolved at dispatch time from the triggering event's own context, rather than a fixed destination configured ahead of time. enum: - RUN_STARTER - APPROVERS type: string Events.EdgeKind: description: Which run-history transition an edge condition matches. enum: - FIRST_FAILURE - RECOVERY - CONSECUTIVE type: string Events.PayloadConditionOperator: description: |- Comparison operator a payload condition evaluates `field` with. `OVER` and `UNDER` compare `value` numerically; `IS` and `IS_NOT` compare it as an exact string match. enum: - IS - IS_NOT - OVER - UNDER type: string Events.ScopeConditionField: description: The entity kind a scope condition filters on. enum: - PROJECT - ENVIRONMENT - MODULE - PIPELINE type: string Events.Weekday: enum: - MONDAY - TUESDAY - WEDNESDAY - THURSDAY - FRIDAY - SATURDAY - SUNDAY type: string securitySchemes: BearerAuth: scheme: Bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.