Push Notifications

When notications are enabled, Swiftcam devices automatically register with the push server at https://push.swiftcam.app and receive a static 128-bit USER_ID token.

Use that USER_ID to send notifications to: https://push.swiftcam.app/api/push/notify

Multiple devices

Mutiple devices can be registerd with the same USER_ID. Just copy the USER_ID from your first devices, and paste it in the Change User ID form on your other devices.

Send Notification from command line

The following curl command sends a notification and a live snapshot from the configured snapshot provider for the camera named "Garden" is attached. Tapping the notifications directly opens the live stream for the camera.

curl -X POST "https://push.swiftcam.app/api/push/notify" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "YOUR_USER_ID",
    "title": "Bird detected",
    "body": "Garden",
    "camera_name": "Garden",
    "snapshot_kind": "live",
    "open": "live"
  }'

Send Notification from Home Assistant

Home Assistant rest_command

The following rest_command provides a shared command that can be used as action in Home Assistant.

rest_command:
  swiftcam_notify:
    url: "https://push.swiftcam.app/api/push/notify"
    method: post
    content_type: "application/json"
    payload: >
      {
        "user_id": "{{ user_id }}",
        "title": "{{ title }}",
        "body": "{{ body }}",
        "camera_name": "{{ camera_name }}",
        "event_id": "{{ event_id }}",
        "snapshot_kind": "{{ snapshot_kind }}",
        "open": "{{ open }}"
      }

Home Assistant Live Snapshot Notification

Below is an example automation to send a notification if a binary_sensor changes to on. The app will show a fresh snapshot from the configured snapshot provider and directly open the camera live stream, if the notification is tapped.

automation:
  - alias: "Swiftcam live snapshot on garden motion"
    trigger:
      - platform: state
        entity_id: binary_sensor.garden_motion
        to: "on"
    action:
      - service: rest_command.swiftcam_notify
        data:
          user_id: "YOUR_USER_ID"
          title: "Motion detected"
          body: "Garden"
          camera_name: "Garden"
          snapshot_kind: "live"
          open: "live"

Home Assistant Frigate Event Notification

Below is an example automation to send a notification for a Frigate event snapshot to Swiftcam. The app connects to Frigate server and loads the event snapshot. Tapping the notification opens the Frigate event details.

automation:
  - alias: "Swiftcam push from Frigate MQTT events"
    mode: parallel
    trigger:
      - platform: mqtt
        topic: frigate/events
    condition:
      # Send only on new tracked object events.
      - condition: template
        value_template: "{{ trigger.payload_json.type == 'new' }}"
      # Optional: only notify for selected labels.
      - condition: template
        value_template: "{{ trigger.payload_json.after.label in ['person', 'car', 'dog', 'cat', 'bird'] }}"
    action:
      - variables:
          event: "{{ trigger.payload_json.after }}"
          camera: "{{ event.camera }}"
          label: "{{ event.label | title }}"
          event_id: "{{ event.id }}"
      - service: rest_command.swiftcam_notify
        data:
          user_id: "YOUR_USER_ID"
          title: "{{ label }} detected"
          body: "{{ camera }}"
          camera_name: "{{ camera }}"
          event_id: "{{ event_id }}"
          snapshot_kind: "frigate_event"
          open: "event"

API: /api/push/notify

POST https://push.swiftcam.app/api/push/notify

Request Body

{
  "user_id": "64-char-hex-user-id",
  "title": "Bird detected",
  "body": "Front Door",
  "camera_name": "Front Door",
  "event_id": "1739987.123",
  "snapshot_kind": "frigate_event",
  "open": "event"
}

Fields

• user_id (string, required): static 128-bit user token as 64 hex chars.
• title (string, required): push title.
• body (string, required): push body text.
• snapshot_kind (string, optional): live, frigate_event, or url.
• open (string, optional): live (default) or event.
• event_id (string, required when snapshot_kind=frigate_event).
• camera_id (string, optional): camera identifier.
• camera_name (string, optional): camera name.
• camera (string, optional): compatibility alias for camera name.
• snapshot_url (string, required when snapshot_kind=url).
• badge (integer, optional).
• sound (string, optional).
• payload (object, optional): custom payload values.
• collapse_id (string, optional).
• thread_id (string, optional).
• expires_in_seconds (integer, optional).

Validation Rules

• title and body must be present.
• open=event requires snapshot_kind=frigate_event.
• snapshot_kind=live requires camera_id or camera_name (or camera).
• snapshot_kind=url requires snapshot_url.
• Unsupported snapshot_kind values are rejected.

Responses

• 200 OK: delivered to at least one device (status: "sent" with counts).
• 202 Accepted: user unknown (accepted response, no user existence leak).
• 400 Bad Request: invalid JSON or validation failure.
• 409 Conflict: no devices currently registered for the user.
• 410 Gone: all device tokens became unregistered.
• 429 Too Many Requests: rate limit exceeded.
• 502 Bad Gateway: APNs delivery failed for all devices.