Create a scheduled job

Stores name, expected interval, grace period, signing, group, client and metadata settings.

POST https://app.upfour.io/v1/heartbeats

A real request. What it creates runs in your up4 account and uses credit, like anything you add in the app.

Authorization

AuthorizationA pls_ key. It stays in this browser tab. Needs heartbeat.write.

Body

namerequired Display name

More fields6

client_id Create inside a client (agency mode)

enable_signing

expected_interval_seconds How often the job should check in grace_period_seconds Slack on top before the silence alerts heartbeat_group_id Optional folder signing_secret With enable_signing and no secret, up4 generates one.

1 more field is only available in JSON.

Headers

Idempotency-KeyheaderGenerated automatically when empty. How it works

Sent directly from your browser to https://app.upfour.io/v1. Mutating calls get an automatic Idempotency-Key when the field is empty.

Request

Responsenot sent yet

Fill in a key and press Send request (⌘↵).
The answer appears here.

scope heartbeat.write stable Idempotency-Key supported returns 201

Body

application/json required 8 fields

namestringrequired

Display name

In the app: Name

All other fields7 fields

client_iduuid · nullable

Create inside a client (agency mode)

In the app: Client

enable_signingboolean

expected_interval_secondsinteger

How often the job should check in

In the app: Expect a check-in every

grace_period_secondsinteger

Slack on top before the silence alerts

In the app: with a grace period of

heartbeat_group_iduuid · nullable

Optional folder

In the app: Group

metadatamap of stringmax 100 keyseach value max length 4096

On update, omitted or null leaves the stored metadata unchanged, {} removes all keys and any other object replaces them.

In the app: Metadata

signing_secretstring · nullable

With enable_signing and no secret, up4 generates one.

Returns

A successful request returns 201 with application/json.

Response fields 1 top-level fields

Field Type Description

data Heartbeat

Heartbeat · 26 fields

Field Type Description

created_at string (date-time)

expected_interval_seconds integer

first_ping_at string (date-time) · nullable

grace_period_seconds integer

has_signing_secret boolean

id uuid

last_outcome_cause string

last_ping_at string (date-time) · nullable

name string

organization_id uuid

slug string

status string one ofupdownpausedpending

updated_at string (date-time)

billing_paused_at string (date-time)

billing_pauses BillingPause[]

Each item · 2 fields

Field	Type	Description
`paused_at`	string (date-time) · nullable
`resumed_at`	string (date-time) · nullable

billing_resumed_at string (date-time)

client_id uuid

flapping HeartbeatFlap

HeartbeatFlap · 3 fields

Field	Type	Description
`changes_last_hour`	integer
`next_notice_at`	string (date-time)
`since`	string (date-time)

heartbeat_group_id uuid

ping_url string

signing_secret string Only in the answer to the create or update that set it; has_signing_secret says whether one is set.

Errors

Only the errors this operation can return. Every error uses the same envelope.

Status	Code	Meaning
400	`bad_request`	The request is malformed or fails validation.
402	`payment_required`	The account does not have the credit or plan required for this action.
403	`permission_denied`	The credentials do not permit this action.

Every call can also return unauthorized (401), rate_limit_exceeded (429) or internal_error (500 / 502). See Responses and errors.

curl -s -X POST "https://app.upfour.io/v1/heartbeats" \ -H "Authorization: Bearer $UP4_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "expected_interval_seconds": 86400, "grace_period_seconds": 900, "name": "Nightly backup" }'

const res = await fetch("https://app.upfour.io/v1/heartbeats", { method: "POST", headers: { Authorization: `Bearer ${process.env.UP4_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ expected_interval_seconds: 86400, grace_period_seconds: 900, name: "Nightly backup", }), }); console.log(res.status, await res.json());

import os import requests res = requests.post( "https://app.upfour.io/v1/heartbeats", headers={"Authorization": f"Bearer {os.environ['UP4_API_KEY']}"}, json={ "expected_interval_seconds": 86400, "grace_period_seconds": 900, "name": "Nightly backup", }, ) print(res.status_code, res.json())

package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "expected_interval_seconds": 86400, "grace_period_seconds": 900, "name": "Nightly backup" }`) req, _ := http.NewRequest("POST", "https://app.upfour.io/v1/heartbeats", payload) req.Header.Set("Authorization", "Bearer "+os.Getenv("UP4_API_KEY")) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() out, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(out)) }

<?php $payload = <<<'JSON' { "expected_interval_seconds": 86400, "grace_period_seconds": 900, "name": "Nightly backup" } JSON; $ch = curl_init("https://app.upfour.io/v1/heartbeats"); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("UP4_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => $payload, ]); $response = curl_exec($ch); echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), " ", $response, "\n"; curl_close($ch);

{ "data": { "created_at": "2026-10-27T09:00:00Z", "expected_interval_seconds": 86400, "first_ping_at": null, "grace_period_seconds": 900, "has_signing_secret": false, "id": "00000000-0000-4000-8000-000000000001", "last_outcome_cause": "unknown", "last_ping_at": null, "name": "Nightly backup", "organization_id": "00000000-0000-4000-8000-000000000002", "slug": "721378bc96ef2ddece4a66b447ba60d6", "status": "pending", "updated_at": "2026-10-27T09:00:00Z" } }