Skip to content
Yagra

Render a template against a representative alert, without saving anything.

POST
/api/v1/notification-channels/preview
curl --request POST \
  --url https://example.com/api/v1/notification-channels/preview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "body": "example", "event": "fire", "free_layout": true, "kind": "webhook", "sample": "threshold", "subject": "example" }'

A template is code that first runs during an outage, so being able to see its output while writing it is part of the feature rather than a convenience. Takes no channel id, so a template can be checked before the channel it belongs to exists.

Problems come back in the 200 response, not as a 400: they are notes about the text being typed, and a failed request would render as “the preview is broken” instead.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

A template to render against a representative alert.

object
body
string | null
event

Which point in an alert’s life to render: fire, resolve, or suppress.

string
Allowed values: fire resolve suppress
free_layout

As on the saved template: line breaks and indentation around the tags are layout.

boolean
kind
required

The channel kind the template is for. Decides whether the body has to be valid JSON.

string
Allowed values: webhook email pagerduty jsm
sample

Which representative alert to render against: threshold (a port over its threshold, every optional variable present — the default) or liveness (a node that stopped answering, with no metric, value, threshold, direction or port).

string
Allowed values: threshold liveness
subject
string | null

Responses

Section titled “Responses”

200

Section titled “200”

What this template would send; a template that cannot be used is reported in-band alongside the built-in text that would go instead

Media typeapplication/json

What the template produces, or what stopped it.

object
body
required

The rendered body, under the same rule.

string
json_valid

Whether the rendered body parses as JSON. null when this channel kind sends the body as plain text, where the question does not apply.

boolean | null
problems
required

One entry per field that could not be rendered and fell back. Empty on success.

Array<object>

One field that could not be used.

object
field
required

subject or body.

string
message
required

The engine’s message, including the offending line where it knows it.

string
reason
required

compile, render, too_large, or not_json.

string
subject
required

The rendered subject. Yagra’s built-in wording when the subject is not overridden, or when rendering it failed — which is exactly what would be sent.

string
Examplegenerated
{
  "body": "example",
  "json_valid": true,
  "problems": [
    {
      "field": "example",
      "message": "example",
      "reason": "example"
    }
  ],
  "subject": "example"
}

401

Section titled “401”

No valid bearer token

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object
error
required
object
code
required

Stable machine-readable code. Clients branch on this, never on the message.

string
message
required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}

403

Section titled “403”

Role lacks ManageSystem

Media typeapplication/json

The ADR-019 envelope every failure renders as. pub(crate) and schema-bearing so the OpenAPI document can name one error shape for every endpoint (ADR-035) instead of leaving 4xx/5xx bodies undescribed — a client that has to guess the failure shape ends up parsing the success shape and reading undefined.

object
error
required
object
code
required

Stable machine-readable code. Clients branch on this, never on the message.

string
message
required

Operator-facing sentence. Safe to display; never carries an internal error’s own text.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}