Replace a scheduled job

Changes name, timing, signing, group, client or metadata settings.

PUT https://app.upfour.io/v1/heartbeats/{heartbeatID}

A real request. Sending it changes data in your up4 account.

Authorization

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

Path

heartbeatIDpath · requiredPart of the request path.

Body

namerequired

More fields6

client_id

enable_signing

expected_interval_seconds grace_period_seconds heartbeat_group_id signing_secret With enable_signing and no secret, up4 generates one.

1 more field is only available in JSON.

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 returns 200

Parameters

Field	Type	Description
`heartbeatID` required	uuid	path parameter

Body

application/json required 8 fields

namestringrequired

All other fields7 fields

client_iduuid · nullable

enable_signingboolean

expected_interval_secondsinteger

grace_period_secondsinteger

heartbeat_group_iduuid · nullable

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.

signing_secretstring · nullable

With enable_signing and no secret, up4 generates one.

Returns

A successful request returns 200 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.
404	`not_found`	The requested resource does not exist or is outside the caller's scope.
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 PUT "https://app.upfour.io/v1/heartbeats/00000000-0000-4000-8000-000000000001" \ -H "Authorization: Bearer $UP4_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "expected_interval_seconds": 86400, "grace_period_seconds": 1800, "name": "Nightly backup" }'

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

import os import requests res = requests.put( "https://app.upfour.io/v1/heartbeats/00000000-0000-4000-8000-000000000001", headers={"Authorization": f"Bearer {os.environ['UP4_API_KEY']}"}, json={ "expected_interval_seconds": 86400, "grace_period_seconds": 1800, "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": 1800, "name": "Nightly backup" }`) req, _ := http.NewRequest("PUT", "https://app.upfour.io/v1/heartbeats/00000000-0000-4000-8000-000000000001", 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": 1800, "name": "Nightly backup" } JSON; $ch = curl_init("https://app.upfour.io/v1/heartbeats/00000000-0000-4000-8000-000000000001"); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => "PUT", 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": "2026-10-27T09:00:00Z", "grace_period_seconds": 1800, "has_signing_secret": false, "id": "00000000-0000-4000-8000-000000000001", "last_outcome_cause": "reported_success", "last_ping_at": "2026-10-27T09:00:00Z", "name": "Nightly backup", "organization_id": "00000000-0000-4000-8000-000000000002", "slug": "721378bc96ef2ddece4a66b447ba60d6", "status": "up", "updated_at": "2026-10-27T09:00:00Z" } }