---
title: "Replace alert templates for a check"
method: PUT
path: "/api/v1/checks/{id}/templates"
tags: ["Checks"]
---

# Replace alert templates for a check

`PUT /api/v1/checks/{id}/templates`

## Request

- Base URL: `https://app.lastping.dev`
- URL: `https://app.lastping.dev/api/v1/checks/{id}/templates`
- Auth: API key in header `X-Api-Key`

Replaces the complete set of custom alert message templates for the check
(**replace-the-set** semantics).

- Keys present in the body with a non-empty string → stored as the custom
  template for that key.
- Keys absent from the body or mapped to an empty string → the custom
  template is **deleted** and the built-in default text is used instead.

All entries are validated before any writes: if any key is invalid or any
template body references an unknown `{variable}`, the entire request is
rejected with `400` and **nothing is written**.

**Key format:** bare event type (`down`, `recovery`, `fail`, `every-run`,
`success`, `started`, `blocked`, `note`) or `event_type/cause` for a
per-cause override (e.g. `"down/silence"`, `"down/overrun"`,
`"down/never_started"`, `"fail/runaway"`).  Per-cause entries take
priority over the event-type-wide entry for that event.

Returns the resulting set (same shape as `GET`) on success.

## Request body

- object
  - `templates` object, required: Map of template key → template body. Keys are a bare event type (`down`, `recovery`, `fail`, `every-run`, `success`, `started`, `blocked`, `note`) or `event_type/cause` (e.g. `"down/silence"`, `"down/overrun"`, `"down/never_started"`, `"fail/runaway"`). Absent keys or empty-string values reset that key to the built-in plain-language default.

## Response `200`

Resulting custom templates after applying the replace-the-set operation.

- AlertTemplatesResponse: Custom alert message templates for a check, keyed by event type or event-type/cause.
  - `templates` object, required: Map of template key → custom template body. **Key format:** - Event-type-wide: `"down"`, `"fail"`, `"recovery"`, `"every-run"`, `"success"`, `"started"`, `"blocked"`, `"note"`. - Per-cause override: `"event_type/cause"`, e.g. `"down/silence"`, `"down/overrun"`, `"down/never_started"`, `"fail/runaway"`. Per-cause keys take priority over the event-type-wide key. Only keys with a custom template are included; absent keys fall back to the per-cause built-in default, then to the event-type-wide custom template, then to the built-in default text.

## Other responses

- `400`: Invalid request — one of: - Invalid key: event type part must be `down`, `recovery`, `fail`, `every-run`, `success`, `started`, `blocked`, or `note` (e.g. `"down"` or `"down/silence"`). - Template body references an unknown `{variable}`. - Malformed JSON body. Nothing is written when any entry fails validation.
- `401`: Missing or invalid API key.
- `404`: Check not found in this project.
- `429`: Too many requests. The per-principal fixed-window rate limit has been exceeded. Retry after the number of seconds indicated by the `Retry-After` response header. The problem body's `code` is `RATE_LIMITED`. It names this limiter specifically, so a client can tell it apart from the application-level throttles that also answer 429 with their own codes and their own, much longer, `Retry-After` values (`TEST_PING_RATE_LIMITED`, `TOO_MANY_ATTEMPTS`). Back off globally on `RATE_LIMITED`; back off on the one operation for the others. The principal is the API key for a key-authenticated request and the USER for a browser session, so every tab one person has open shares one budget.

---

[API](https://skmtc.dev/lastping/apis/lastping-management-api.md) · [All operations](https://skmtc.dev/lastping/apis/lastping-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/lastping/apis/lastping-management-api/revisions/bbc6eda91c46?raw)