Payload Reference

Use this as the single source of truth for the /notify request body.

Authentication (required)

Send your secret as a Bearer token on every request:

POST /notify
Authorization: Bearer <uniqueID>
Content-Type: application/json

Complete JSON example

{
  "job_id": "deploy-prod",
  "title": "Production Deploy",
  "message": "Running migrations...",
  "status": "running",
  "action": "update",
  "layout": "progress",
  "theme": "default",
  "metric": "Step 2/5",
  "progress": 0.4,
  "secondaryMetric": "LIVE",
  "metricA": "3",
  "metricB": "1",
  "subA": "HOME",
  "subB": "AWAY",
  "icon": "bolt.fill",
  "accentColor": "#00CFFF"
}

Field reference

Field	Type	Required	Allowed / format	Default	Availability	Notes
job_id	string	Yes	1-64 chars, A-Z a-z 0-9 _ -	none	All tiers	Routing key only; not displayed as title.
title	string	No	non-empty text recommended	derived from message or "Island Pulse"	All tiers	Display title in Live Activity UI.
message	string	Yes*	non-empty string	none	All tiers	Primary body text. Required for start/update; not required for end.
status	string	No	running | success | failed	running	All tiers	Visual status state.
action	string	No	start | update | end	auto-selected	All tiers	Omit for normal auto-routing behavior.
layout	string	No	default | progress | score | sports	default	Pro for non-default	Free requests are normalized to default.
theme	string	No	implementation-defined	default	App feature dependent	Optional visual theme hint.
metric	string	No	short text	none	All tiers	KPI/auxiliary metric.
progress	number	No	0.0-1.0 (or 0-100)	none	All tiers	Values above 1 are normalized as percentages.
secondaryMetric	string	No	short text	none	All tiers	Secondary badge/label text.
metricA	string	No	short text	none	All tiers	Sports/dual metric left value.
metricB	string	No	short text	none	All tiers	Sports/dual metric right value.
subA	string	No	short text	none	All tiers	Sports/dual metric left sublabel.
subB	string	No	short text	none	All tiers	Sports/dual metric right sublabel.
icon	string	No	SF Symbol name	layout default	All tiers	Per-push icon override.
accentColor	string	No	CSS color or hex	app/theme default	All tiers	Per-push accent override.

Tier behavior notes

• Free tier allows one active job_id at a time per token.
• Free tier uses default layout only; non-default layout values are coerced to default.
• Sending a different active job_id on free returns 403 FREE_TIER_JOB_LOCKED (TIER_LIMIT_EXCEEDED support code).
• Sending start for a job_id that is already running returns 409 ACTIVITY_ALREADY_RUNNING (all tiers). Send updates instead, or end the activity first.
• Pro tier supports multiple concurrent job streams (up to iOS system limits).

Common errors

HTTP	Error	Meaning
400	MISSING_UNIQUE_ID	Missing or invalid Bearer token.
400	MISSING_JOB_ID	job_id missing or empty.
400	INVALID_JOB_ID	job_id format invalid.
400	INVALID_ACTION	action is not start/update/end.
403	FREE_TIER_JOB_LOCKED	Free tier: a different job_id is already active. End it first.
409	ACTIVITY_ALREADY_RUNNING	A Live Activity for this job_id is already running. Send updates or end it before starting again.
502	APNS_PUSH_FAILED	APNs rejected delivery.
502	APNS_RECOVERY_FAILED	Update token was dead and start recovery failed too.