---
title: "Create Heartbeat"
method: POST
path: "/v1/heartbeats"
tags: ["Heartbeats"]
---

# Create Heartbeat

`POST /v1/heartbeats`

## Request

- Base URL: `https://api.fettle.sh` (the document declares no server; this is the origin it was published from)
- URL: `https://api.fettle.sh/v1/heartbeats`
- Auth: API key in header `Authorization`

Create a new heartbeat for the active organization.

## Headers

- `X-Organization-Id` string, uuid, nullable

## Request body

- HeartbeatCreate: Create payload for a heartbeat.
  - `name` string, required
  - `period_seconds` integer, required
  - `grace_seconds` integer, required
  - `notification_cooldown_seconds` integer, nullable
  - `channel_ids` string[], nullable
  - `tags` string[]

## Response `201`

Successful Response

- HeartbeatRead: Response model for a heartbeat, including the full ping-URL.
  - `id` string, uuid, required
  - `name` string, required
  - `state` 'PENDING' | 'UP' | 'DOWN' | 'PAUSED', required: Lifecycle state of a heartbeat. ``PENDING`` — created, never pinged; the sweep skips it (``overdue_at`` is NULL) so a freshly created heartbeat does not false-alarm. ``UP`` — pinged within ``period + grace``; the only state the sweep can flip to ``DOWN``. ``DOWN`` — a ping was missed or the job sent ``/fail``; an incident is open. ``PAUSED`` — owner-paused; inactive, never alerts.
  - `period_seconds` integer, required
  - `grace_seconds` integer, required
  - `ping_url` string, required
  - `last_ping_at` string, date-time, nullable, required
  - `last_success_at` string, date-time, nullable, required
  - `last_start_at` string, date-time, nullable, required
  - `last_duration_ms` integer, nullable, required
  - `overdue_at` string, date-time, nullable, required
  - `notification_cooldown_seconds` integer, required
  - `is_active` boolean, required
  - `channel_ids` string[]
  - `tags` string[]
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/fettle/apis/fettle-sh.md) · [All operations](https://skmtc.dev/fettle/apis/fettle-sh/llms.txt) · [OpenAPI document](https://skmtc.dev/fettle/apis/fettle-sh/revisions/f32c8a18606f?raw)