API Reference

Complete reference for the HTTP API, CLI, notification payload, style properties, and environment variables.

HTTP endpoints

syncfu runs an HTTP server on port 9868 by default.

MethodPathDescription
POST/notifySend a notification. Returns {"id":"..."}
POST/notify/{id}/updateUpdate body, progress, or actions of an existing notification
POST/notify/{id}/actionTrigger an action button (fires webhook, dismisses)
POST/notify/{id}/dismissDismiss a specific notification
GET/notify/{id}/waitSSE stream — blocks until action or dismiss
POST/dismiss-allDismiss all active notifications
GET/healthServer status + active notification count
GET/activeList all active notifications (JSON array)

Notification payload

POST /notify
Content-Type: application/json

{
  "sender": "my-app",
  "title": "Build Complete",
  "body": "All 142 tests passed — coverage 87%",
  "icon": "circle-check",
  "font": "JetBrains Mono",
  "priority": "normal",
  "timeout": { "seconds": 15 },
  "actions": [
    { "id": "open", "label": "Open PR", "style": "primary" },
    { "id": "dismiss", "label": "Dismiss", "style": "secondary" }
  ],
  "progress": { "value": 0.75, "label": "3 of 4", "style": "bar" },
  "group": "ci-builds",
  "theme": "dark",
  "sound": "success",
  "callback_url": "http://localhost:8080/callback",
  "style": {
    "accentColor": "#22c55e",
    "cardBg": "rgba(10, 40, 20, 0.96)"
  }
}

Field reference

FieldTypeRequiredDescription
senderstringyesIdentifier for the sending process
titlestringyesNotification title
bodystringyesBody text (plain text)
iconstringnoLucide icon name (e.g. rocket, bell)
fontstringnoGoogle Font name (e.g. Space Grotesk)
prioritystringnolow, normal (default), high, critical
timeoutobjectno{"seconds": N} or "never" or "default"
actionsarraynoUp to 3 action buttons (see below)
progressobjectnoProgress indicator (bar or ring style)
groupstringnoGroup key for related notifications
themestringnolight or dark (auto-follows system)
soundstringnoSound name (accepted, playback planned)
callback_urlstringnoURL to POST when an action is clicked
styleobjectnoPer-notification style overrides (27 properties)

Action button format

{
  "id": "deploy",        // returned as action_id
  "label": "Deploy",     // button text
  "style": "primary",    // primary | secondary | danger
  "icon": "rocket",      // optional Lucide icon
  "bg": "#22c55e",       // optional background color
  "color": "#ffffff",    // optional text color
  "borderColor": "#16a34a"  // optional border color
}

Progress format

{
  "value": 0.75,          // 0.0 to 1.0
  "label": "3 of 4",     // optional text label
  "style": "bar"         // "bar" (default) or "ring"
}

Priority levels & timeouts

PriorityDefault timeoutVisual behavior
low6 secondsStandard appearance
normal8 secondsStandard appearance
high12 secondsEmphasized styling
criticalNever (manual dismiss)Pulsing glow border (Siri-style)

Style properties (27)

Override any visual property per notification via the style object:

{
  "style": {
    "accentColor": "#22c55e",
    "cardBg": "rgba(10, 40, 20, 0.96)",
    "cardBorderRadius": "16px",
    "iconColor": "#4ade80",
    "iconBg": "rgba(34, 197, 94, 0.15)",
    "iconBorderColor": "#22c55e",
    "titleColor": "#bbf7d0",
    "titleFontSize": "15px",
    "bodyColor": "#86efac",
    "bodyFontSize": "13px",
    "senderColor": "#67e8f9",
    "timeColor": "#9ca3af",
    "btnBg": "#7c3aed",
    "btnColor": "#ffffff",
    "btnBorderColor": "#6d28d9",
    "btn2Bg": "transparent",
    "btn2Color": "#c084fc",
    "btn2BorderColor": "#7c3aed",
    "dangerBg": "#dc2626",
    "dangerColor": "#ffffff",
    "dangerBorderColor": "#b91c1c",
    "progressColor": "#22c55e",
    "progressTrackColor": "rgba(255,255,255,0.1)",
    "countdownColor": "#ef4444",
    "closeBg": "transparent",
    "closeColor": "#9ca3af",
    "closeBorderColor": "transparent"
  }
}

CLI shorthand: --style-json '{...}'

CLI reference

syncfu send [OPTIONS] <BODY>
syncfu update <ID> [OPTIONS]
syncfu dismiss <ID>
syncfu dismiss-all
syncfu list
syncfu health

syncfu send flags

FlagShortDescription
--title-tNotification title
--priority-plow, normal, high, critical
--icon-iLucide icon name
--sender-sSender identifier
--action-aAction button (id:label or id:label:style)
--waitBlock until user responds (SSE)
--wait-timeoutTimeout in seconds for --wait
--progressInitial progress value (0.0–1.0)
--progress-labelText label for progress indicator
--progress-stylebar (default) or ring
--timeoutAuto-dismiss seconds, or "never"
--fontGoogle Font name
--callback-urlWebhook URL for action clicks
--style-jsonJSON string of style overrides
--groupGroup key
--jsonOutput JSON response (includes notification id)

Exit codes (with --wait)

OutcomestdoutExit code
Action button clickedaction_id0
Dismissed (X button)dismissed1
Timeout (--wait-timeout)timeout2

Recommended icons (Lucide v1.x)

syncfu supports all 1400+ Lucide icons. Here are the most useful for notification workflows:

rocket  circle-check  circle-x  triangle-alert  bell
mail  terminal  git-pull-request  shield-alert  flame
siren  trending-up  calendar-clock  message-circle  eye
pen-tool  loader  server-crash  webhook  trophy
newspaper  info  pill  coffee  lightbulb  user
folder  repeat  clock  brain  cpu  hard-drive

Environment variables

VariableDefaultDescription
SYNCFU_SERVERhttp://localhost:9868Point CLI at a remote syncfu instance

SSE wait endpoint (custom clients)

# Send notification, get ID
ID=$(curl -s -X POST localhost:9868/notify \
  -H "Content-Type: application/json" \
  -d '{"sender":"ci","title":"Approve?","body":"Deploy v2","actions":[{"id":"yes","label":"Yes","style":"primary"}]}' \
  | jq -r .id)

# Open SSE stream — blocks until user responds
curl -N "localhost:9868/notify/$ID/wait"
# event: message
# data: {"event":"connected"}
#
# event: message
# data: {"event":"action","action_id":"yes"}

Start building

Full API, 27 style properties, 1400+ icons. Everything you need to integrate syncfu into your workflow.

Get started →