--- title: "Fire a notification from an alert template" method: POST path: "/api/v1/notifications/from-template/{slug}" tags: ["Notifications"] --- # Fire a notification from an alert template `POST /api/v1/notifications/from-template/{slug}` ## Request - Base URL: `https://wardenpoint.com` (the document declares no server; this is the origin it was published from) - URL: `https://wardenpoint.com/api/v1/notifications/from-template/{slug}` - Auth: API key in header `X-API-Key` Renders a stored alert template with the variables you supply and queues the result down the same path as `POST /api/v1/notifications/send-async` — escalation, channel fallback, retries and audit all behave identically. The point of the template is that the message wording, the priority and the addressee live on the server: you send the few values that differ per incident. **Always asynchronous.** The answer is 202 the moment the job is queued, and it says nothing about delivery. On the single-recipient path the response carries `notification_uuid` — poll `GET /api/v1/notifications/{notification}/status` with that to learn what happened. On the group path there is no single notification to name: the response returns `group_uuid` only, and the individual notifications have to be found through `GET /api/v1/notifications`. **Addressing: the group always wins.** The endpoint resolves a group first — `override.group_uuid` if given, otherwise the template's default group — and if a group comes out of that, the alert goes to the group and any recipient is ignored, including one you passed as `override.recipient_uuid`. To send a group-defaulted template to one person you must clear the group, which this endpoint cannot do; change the template instead. Only when no group resolves does the recipient path run, and with neither a group nor a recipient the call answers 422. **Not idempotent.** Every call fires. There is no dedup key, no "only if not already sent" and no way to cancel from here — repeating the request after a timeout pages the same people twice. Each successful fire also increments the template's lifetime `fired_count` and stamps `last_fired_at`. The slug is looked up inside the company of the API key, so a template of another tenant is simply not found. Firing consumes the same notification quota and the same rate limit as a direct send. ## Path parameters - `slug` string, required ## Request body - NotificationFromTemplateRequest: Every field is optional. An empty body fires the template exactly as configured — current version, template defaults for priority and addressee — provided the template needs no required variables. - `vars` object: Values for the placeholders in the template body, by name. A variable the template marks required and you omit fails the call with 422; a variable the template does not declare is ignored. Values are substituted as text — nothing here changes routing or priority. - `version` integer, nullable: Pin the render to a specific stored version of the template body. Omit to use the current version, which is what you normally want — pinning is for reproducing an older wording. A version number the template never had answers 404. - `override` object, nullable: Per-call overrides of the template defaults. Omitted keys keep the template's own values; nothing here is persisted back to the template. - `priority` 'low' | 'normal' | 'high' | 'critical': Replaces the template's default priority for this fire only. - `recipient_uuid` string, uuid: Send to this recipient instead of the template default. Ignored when the template has a default group and you do not override the group too — the group path always wins, see the endpoint description. - `group_uuid` string, uuid: Send to this group instead of the template default. Takes precedence over any recipient, whether the recipient came from the template or from `override.recipient_uuid`. ## Response `202` Rendered and queued. `notification_uuid` is present on the single-recipient path only; the group path returns `group_uuid` instead. - object - `success` boolean - `queued` boolean - `notification_uuid` string, uuid: The queued notification. Single-recipient path only — poll its status endpoint with this. Absent on the group path. - `recipient_uuid` string, uuid: Who it went to. Single-recipient path only. - `group_uuid` string, uuid: Which group it went to. Group path only. - `template_slug` string - `template_version` integer: Version number actually rendered — the current one unless you pinned `version`. - `priority` 'low' | 'normal' | 'high' | 'critical': Priority actually used, after any override. - `rendered_message_preview` string: First 200 characters of the rendered body — enough to confirm the variables substituted as intended. The full text is what was queued. ## Other responses - `401`: API key missing, invalid, revoked or expired. - `402`: The company subscription is inactive. No notification is queued until billing is settled. - `403`: API key lacks the notifications.send ability. Reading abilities are not enough — firing a template is sending. - `404`: No template with this slug in this company, or the pinned `version` never existed, or alert templates are switched off for this installation. The body distinguishes the first two in `error`; the feature-flag case has no body of its own. - `422`: A variable the template marks required was not supplied (the message arrives under `vars`), an override value is not a valid priority or UUID, the overridden group or recipient does not exist in this company, or the template has neither a default recipient nor a default group and the request overrode neither. - `429`: Either more than 10 notification calls a minute from this IP, or the plan's notification quota is spent — the quota case answers with `code: LIMIT_EXCEEDED` and an `upgrade_url`. --- [API](https://skmtc.dev/wardenpoint/apis/wardenpoint-api.md) · [All operations](https://skmtc.dev/wardenpoint/apis/wardenpoint-api/llms.txt) · [OpenAPI document](https://skmtc.dev/wardenpoint/apis/wardenpoint-api/revisions/259ee445728e?raw)