PushWard

https://pushward.app/docs
Admin
PushWard is a developer platform and API for sending push notifications, managing iOS Live...
Tokens:83,698
Snippets:614
Trust Score:4.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Start a generic activity with PATCH

Source: https://pushward.app/docs/api/activities

Example of starting a generic activity by setting state to 'ongoing' with content. This triggers a push-to-start action. Uses merge-patch semantics; fields not sent are preserved.

```bash
curl -X PATCH https://api.pushward.app/activities/dishwasher \
  -H "Authorization: Bearer hlk_YOUR_TOKEN" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{
    "state": "ongoing",
    "content": {
      "template": "generic",
      "progress": 0.65,
      "state": "Washing",
      "icon": "washer",
      "remaining_time": 1800,
      "subtitle": "Cycle 2 of 3",
      "accent_color": "blue"
    }
  }'
```

--------------------------------

### Create, start, update, and end an activity with the Pushward API

Source: https://pushward.app/docs/examples

Uses fetch to POST a new activity and PATCH its state through ongoing to ended. Requires a valid API token in TOKEN. The example sets a generic template with progress, state text, icon, and accent_color for each update.

```JavaScript
const BASE_URL = "https://api.pushward.app";
const TOKEN = "hlk_YOUR_KEY";

const headers = {
  Authorization: `Bearer ${TOKEN}`,
  "Content-Type": "application/json",
};

// Create activity
await fetch(`${BASE_URL}/activities`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    slug: "my-build",
    name: "My Build",
  }),
});

// Start activity
await fetch(`${BASE_URL}/activities/my-build`, {
  method: "PATCH",
  headers,
  body: JSON.stringify({
    state: "ongoing",
    content: {
      template: "generic",
      progress: 0.0,
      state: "Starting...",
      icon: "arrow.triangle.branch",
      accent_color: "cyan",
    },
  }),
});

// Update progress
await fetch(`${BASE_URL}/activities/my-build`, {
  method: "PATCH",
  headers,
  body: JSON.stringify({
    state: "ongoing",
    content: {
      template: "generic",
      progress: 0.75,
      state: "Running tests...",
      icon: "arrow.triangle.branch",
      accent_color: "cyan",
    },
  }),
});

// End activity
await fetch(`${BASE_URL}/activities/my-build`, {
  method: "PATCH",
  headers,
  body: JSON.stringify({
    state: "ended",
    content: {
      template: "generic",
      progress: 1.0,
      state: "Complete",
      icon: "checkmark.circle.fill",
      accent_color: "green",
    },
  }),
});
```

--------------------------------

### Install the PushWard Unraid plugin

Source: https://pushward.app/docs/integrations/unraid

Paste this URL into the Unraid web UI under Plugins → Install Plugin. Requires Unraid 6.12 or later.

```text
https://github.com/mac-lucky/pushward-unraid-plugin/raw/main/pushward-unraid.plg
```

--------------------------------

### GET /auth/me Response

Source: https://pushward.app/docs/api/authentication

Example JSON response from the /auth/me endpoint, showing user profile details and current usage quotas.

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "nickname": "Alice",
  "activity_count": 3,
  "subscribed": false,
  "quota_period_month": 202606,
  "notifications_used": 128,
  "notifications_limit": 500,
  "live_activity_updates_used": 86,
  "live_activity_updates_limit": 250,
  "widget_updates_used": 12,
  "widget_updates_limit": 50,
  "emails_used": 3,
  "emails_limit": 50,
  "quota_resets_at": "2026-07-01T00:00:00Z"
}
```

--------------------------------

### PATCH /widgets/power - Home energy flow example

Source: https://pushward.app/docs/widgets/templates/flow

Example request body for the flow widget showing solar input, home output, battery storage, and grid exchange. The exchange rate is negative (-1400) to indicate exporting to the grid. Only the slots sent are drawn.

```json
{
  "content": {
    "template": "flow",
    "label": "Power",
    "subtitle": "Solar · grid · home",
    "icon": "point.3.filled.connected.trianglepath.dotted",
    "unit": "W",
    "accent_color": "mint",
    "flow": {
      "inputs": [
        { "name": "Solar", "rate": 3200, "total": 12.4, "icon": "sun.max.fill", "color": "yellow" }
      ],
      "output":   { "name": "Home",    "rate": 1000, "total": 9.8, "icon": "house.fill" },
      "storage":  { "name": "Battery", "rate": 800,  "level": 76,  "icon": "battery.75percent", "color": "green" },
      "exchange": { "name": "Grid",    "rate": -1400, "total": 3.1, "icon": "bolt.fill", "color": "cyan" }
    }
  }
}
```

--------------------------------

### PATCH /widgets/deploys

Source: https://pushward.app/docs/widgets/templates/value

Example configuration for a Value widget displaying daily deployment counts with a trend indicator.

```json
{
  "content": {
    "template": "value",
    "value": 18,
    "label": "Deploys",
    "subtitle": "Today · 14 prod · 4 staging",
    "icon": "shippingbox.fill",
    "accent_color": "cyan",
    "trend": "up"
  }
}
```

--------------------------------

### PATCH /widgets/devices - battery template example

Source: https://pushward.app/docs/widgets/templates/battery

Example request body for the battery widget with four devices. The template field must be "battery", and devices is required with 1 to 8 objects. The icon field uses SF Symbols or MDI icons prefixed with mdi:.

```json
{
  "content": {
    "template": "battery",
    "label": "Devices",
    "icon": "battery.75percent",
    "accent_color": "green",
    "devices": [
      { "name": "Vacuum",     "level": 68, "icon": "fan.fill" },
      { "name": "Front lock", "level": 45, "icon": "lock.fill", "charging": true },
      { "name": "Doorbell",   "level": 18, "icon": "video.fill" },
      { "name": "Sensor hub", "level": 92, "icon": "sensor.fill" }
    ]
  }
}
```

--------------------------------

### Single Value Timeline Example

Source: https://pushward.app/docs/live-activities/timeline

A basic implementation for monitoring a single value, such as temperature, with smoothing enabled.

```json
{
  "state": "ongoing",
  "content": {
    "template": "timeline",
    "value": {"Temperature": 13.7},
    "unit": "°C",
    "state": "Heating",
    "icon": "thermometer.medium",
    "accent_color": "orange",
    "smoothing": true
  }
}
```

--------------------------------

### Manage Pushward activities with Go

Source: https://pushward.app/docs/examples

Demonstrates how to create, start, update, and end an activity using the standard net/http package. Replace the token constant with your actual API key.

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

const (
	baseURL = "https://api.pushward.app"
	token   = "hlk_YOUR_KEY"
)

func main() {
	// Create activity
	post("/activities", map[string]any{
		"slug": "my-build",
		"name": "My Build",
	})

	// Start activity
	patch("/activities/my-build", map[string]any{
		"state": "ongoing",
		"content": map[string]any{
			"template":     "generic",
			"progress":     0.0,
			"state":        "Starting...",
			"icon":         "arrow.triangle.branch",
			"accent_color": "cyan",
		},
	})

	// Update progress
	patch("/activities/my-build", map[string]any{
		"state": "ongoing",
		"content": map[string]any{
			"template":     "generic",
			"progress":     0.75,
			"state":        "Running tests...",
			"icon":         "arrow.triangle.branch",
			"accent_color": "cyan",
		},
	})

	// End activity
	patch("/activities/my-build", map[string]any{
		"state": "ended",
		"content": map[string]any{
			"template":     "generic",
			"progress":     1.0,
			"state":        "Complete",
			"icon":         "checkmark.circle.fill",
			"accent_color": "green",
		},
	})
}

func post(path string, body map[string]any) {
	doRequest("POST", path, body)
}

func patch(path string, body map[string]any) {
	doRequest("PATCH", path, body)
}

func doRequest(method, path string, body map[string]any) {
	data, _ := json.Marshal(body)
	req, _ := http.NewRequest(method, baseURL+path, bytes.NewReader(data))
	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}
	defer resp.Body.Close()
	fmt.Printf("%s %s -> %d\n", method, path, resp.StatusCode)
}
```

--------------------------------

### device_sort example - lowest battery first, then alphabetical

Source: https://pushward.app/docs/widgets/templates/battery

Example request body with device_sort keys to order devices by level ascending, then by name ascending. The same field may not appear in both keys. The server stores the sorted array, so responses and GET requests return reordered devices.

```json
{
  "content": {
    "template": "battery",
    "device_sort": [
      { "field": "level", "direction": "asc" },
      { "field": "name",  "direction": "asc" }
    ],
    "devices": [
      { "name": "Vacuum",     "level": 68 },
      { "name": "Front lock", "level": 45 },
      { "name": "Doorbell",   "level": 45 },
      { "name": "Sensor hub", "level": 92 }
    ]
  }
}
```

--------------------------------

### Streaming Deploy Log Example

Source: https://pushward.app/docs/live-activities/log

A JSON payload demonstrating the structure of a log template Live Activity, including state, icon, accent color, and a list of log lines.

```json
{
  "state": "ongoing",
  "content": {
    "template": "log",
    "state": "pushward-server",
    "icon": "doc.text",
    "accent_color": "purple",
    "lines": [
      { "text": "Rollout complete — 3/3 pods healthy", "at": 1718990000, "level": "info" },
      { "text": "Image pull slow on node arm-2", "at": 1718989950, "level": "warn" },
      { "text": "Applied manifest revision d86246c", "at": 1718989930, "level": "info" },
      { "text": "Sync started by webhook", "at": 1718989900, "level": "info" }
    ]
  }
}
```

--------------------------------

### Manage Pushward activities with Python

Source: https://pushward.app/docs/examples

Demonstrates how to create, start, update, and end an activity using the requests library. Ensure the TOKEN variable is replaced with your actual API key.

```python
import requests

BASE_URL = "https://api.pushward.app"
TOKEN = "hlk_YOUR_KEY"
HEADERS = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json",
}

# Create activity
requests.post(f"{BASE_URL}/activities", headers=HEADERS, json={
    "slug": "my-build",
    "name": "My Build",
})

# Start activity
requests.patch(f"{BASE_URL}/activities/my-build", headers=HEADERS, json={
    "state": "ongoing",
    "content": {
        "template": "generic",
        "progress": 0.0,
        "state": "Starting...",
        "icon": "arrow.triangle.branch",
        "accent_color": "cyan",
    },
})

# Update progress
requests.patch(f"{BASE_URL}/activities/my-build", headers=HEADERS, json={
    "state": "ongoing",
    "content": {
        "template": "generic",
        "progress": 0.75,
        "state": "Running tests...",
        "icon": "arrow.triangle.branch",
        "accent_color": "cyan",
    },
})

# End activity
requests.patch(f"{BASE_URL}/activities/my-build", headers=HEADERS, json={
    "state": "ended",
    "content": {
        "template": "generic",
        "progress": 1.0,
        "state": "Complete",
        "icon": "checkmark.circle.fill",
        "accent_color": "green",
    },
})
```

--------------------------------

### GET /auth/me

Source: https://pushward.app/docs/api/authentication

Get the current user's profile, activity count, and current quota usage. Integration keys read their own live usage here; the iOS app polls this endpoint for its Usage screen.

```APIDOC
## GET /auth/me

### Description
Get the current user's profile, activity count, and current quota usage. Integration keys read their own live usage here; the iOS app polls this endpoint for its Usage screen.

### Method
GET

### Endpoint
/auth/me

### Response
#### Success Response (200)
- **id** (string) - User ID
- **nickname** (string | null) - Display name
- **activity_count** (integer) - Number of activities owned by the user
- **subscribed** (boolean) - Whether the user has an active subscription
- **quota_period_month** (integer) - `YYYYMM` bucket for the current monthly usage period (UTC)
- **notifications_used** / **notifications_limit** (integer) - Notifications sent this period and your tier's cap. `*_limit` is omitted when uncapped.
- **live_activity_updates_used** / **live_activity_updates_limit** (integer) - Live Activity updates this month and your tier's cap
- **widget_updates_used** / **widget_updates_limit** (integer) - Widget updates this month and your tier's cap
- **emails_used** / **emails_limit** (integer) - Emails sent this month and your tier's cap (free 50, paid 200)
- **quota_resets_at** (string) - ISO 8601 instant the active counters reset

#### Response Example
```
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "nickname": "Alice",
  "activity_count": 3,
  "subscribed": false,
  "quota_period_month": 202606,
  "notifications_used": 128,
  "notifications_limit": 500,
  "live_activity_updates_used": 86,
  "live_activity_updates_limit": 250,
  "widget_updates_used": 12,
  "widget_updates_limit": 50,
  "emails_used": 3,
  "emails_limit": 50,
  "quota_resets_at": "2026-07-01T00:00:00Z"
}
```

```

--------------------------------

### Gauge complete JSON example

Source: https://pushward.app/docs/live-activities/gauge

Example JSON payload for a gauge update with state 'ended', value 250, range 0-250, unit '°C', state 'Ready', icon 'checkmark.circle.fill', and accent color 'green'.

```json
{
  "state": "ended",
  "content": {
    "template": "gauge",
    "value": 250,
    "min_value": 0,
    "max_value": 250,
    "unit": "°C",
    "state": "Ready",
    "icon": "checkmark.circle.fill",
    "accent_color": "green"
  }
}
```

--------------------------------

### Create a CPU-load widget with curl

Source: https://pushward.app/docs/widgets/api

POST /widgets registers a widget by slug. Requires an integration key (hlk_) with the widgets flag enabled. Re-POSTing the same slug refreshes fields and still returns 201. The response always includes the X-Resource-Action header indicating created or updated.

```bash
curl -X POST https://api.pushward.app/widgets \
  -H "Authorization: Bearer hlk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "cpu-load",
    "name": "CPU Load",
    "content": {
      "template": "progress",
      "value": 0.42,
      "label": "load avg",
      "icon": "cpu",
      "accent_color": "cyan"
    }
  }'
```

```json
{
  "slug": "cpu-load",
  "name": "CPU Load",
  "content": {
    "template": "progress",
    "value": 0.42,
    "label": "load avg",
    "icon": "cpu",
    "accent_color": "cyan"
  },
  "created_at": "2026-05-10T12:00:00Z",
  "updated_at": "2026-05-10T12:00:00Z"
}
```

--------------------------------

### Gauge update JSON example

Source: https://pushward.app/docs/live-activities/gauge

Example JSON payload for a gauge update with state 'ongoing', value 125, range 0-250, unit '°C', state 'Heating', icon 'thermometer.medium', and accent color 'orange'.

```json
{
  "state": "ongoing",
  "content": {
    "template": "gauge",
    "value": 125,
    "min_value": 0,
    "max_value": 250,
    "unit": "°C",
    "state": "Heating",
    "icon": "thermometer.medium",
    "accent_color": "orange"
  }
}
```

--------------------------------

### Create the player activity with curl POST to /activities

Source: https://pushward.app/docs/live-activities/media

Creates the activity 'living-room-player' once with a bearer token. The same activity is then patched with player state. URL is https://api.pushward.app/activities; must include the 'Authorization: Bearer hlk_YOUR_TOKEN' header.

```shell
curl -X POST https://api.pushward.app/activities \
  -H "Authorization: Bearer hlk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "living-room-player",
    "name": "Living Room"
  }'
```

--------------------------------

### Now playing with cover art and ThumbHash

Source: https://pushward.app/docs/live-activities/generic

Example of a generic template configuration including an image URL, poster shape, and ThumbHash for fallback rendering.

```json
{
  "state": "ongoing",
  "content": {
    "template": "generic",
    "progress": 0.35,
    "state": "Playing",
    "subtitle": "S02E04 - The Constant",
    "icon": "play.fill",
    "image_url": "https://images.example.com/lost/s02e04.jpg",
    "image_shape": "poster",
    "image_thumbhash": "GYpSpSh4eHt4eHh4eHh4eHh4iIeH",
    "accent_color": "indigo"
  }
}
```

--------------------------------

### PATCH /widgets/oncall-pages - Progress widget example

Source: https://pushward.app/docs/widgets/templates/progress

Example request body for a progress widget showing incident acknowledgements. Uses template "progress", value 0.6, label, subtitle, icon, accent_color, and stat_rows with three rows.

```json
{
  "content": {
    "template": "progress",
    "value": 0.6,
    "label": "Pages",
    "subtitle": "6 of 10 acked · INC-2841",
    "icon": "checklist",
    "accent_color": "green",
    "stat_rows": [
      { "label": "Acked",    "value": "6" },
      { "label": "Total",    "value": "10" },
      { "label": "Severity", "value": "SEV-2" }
    ]
  }
}
```

--------------------------------

### List Activities Response (200)

Source: https://pushward.app/docs/api/activities

Example response body for listing activities. Contains an 'items' array and a 'next_cursor' for pagination. Pass 'next_cursor' back as 'after' until it is null or empty.

```json
{
  "items": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "kind": "owned",
      "slug": "ci-pipeline",
      "name": "CI Pipeline",
      "state": "ended",
      "priority": 0,
      "content": {},
      "ended_ttl": 3600,
      "stale_ttl": null,
      "dismissal_ttl": null,
      "delete_at": "2025-06-15T12:00:00Z",
      "created_at": "2025-06-15T10:00:00Z",
      "updated_at": "2025-06-15T11:00:00Z",
      "ended_at": "2025-06-15T11:00:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "kind": "owned",
      "slug": "dishwasher",
      "name": "Dishwasher",
      "state": "ongoing",
      "priority": 3,
      "content": {
        "template": "generic",
        "progress": 0.65,
        "state": "Washing",
        "icon": "washer",
        "remaining_time": 1800,
        "subtitle": "Cycle 2 of 3",
        "accent_color": "blue"
      },
      "ended_ttl": null,
      "stale_ttl": null,
      "dismissal_ttl": null,
      "delete_at": null,
      "created_at": "2025-06-15T10:30:00Z",
      "updated_at": "2025-06-15T11:00:00Z",
      "ended_at": null
    }
  ],
  "next_cursor": "eyJzIjoib3Zlbi10aW1lciIsImkiOjE5fQ"
}
```

--------------------------------

### PATCH trend widget: p95 latency example

Source: https://pushward.app/docs/widgets/templates/trend

PATCH request body for the trend widget, showing a p95 latency example. The value is the current reading, points are the sparkline history (oldest first), and trend is an annotation, not derived from points.

```json
{
  "content": {
    "template": "trend",
    "value": 371,
    "unit": "ms",
    "points": [312, 305, 298, 310, 322, 331, 340, 336, 329, 348, 355, 362, 371],
    "label": "p95 latency",
    "subtitle": "api-gateway · last hour",
    "icon": "waveform.path.ecg",
    "accent_color": "teal",
    "trend": "up"
  }
}
```

--------------------------------

### PATCH /widgets/incident - status widget example

Source: https://pushward.app/docs/widgets/templates/status

Example request body for setting a status widget to a warning incident state. The severity 'warning' picks a triangle icon and warning color. The subtitle is split into tag pills by separators like '·' and ','.

```json
{
  "content": {
    "template": "status",
    "severity": "warning",
    "label": "Incident",
    "subtitle": "INC-2841 · api-gateway · investigating",
    "url_action": { "title": "Ack", "icon": "checkmark.circle.fill", "url": "https://example.com/ack/2841" }
  }
}
```

--------------------------------

### Create the approval activity

Source: https://pushward.app/docs/live-activities/approval

Initializes a new activity with the slug 'approval-request' using a POST request to the activities endpoint.

```bash
curl -X POST https://api.pushward.app/activities \
  -H "Authorization: Bearer hlk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "approval-request",
    "name": "Approval Needed"
  }'
```

--------------------------------

### Create activity with curl

Source: https://pushward.app/docs/examples

Creates a new activity with slug 'my-build' and name 'My Build'. Requires an integration key (replace hlk_YOUR_KEY).

```bash
curl -X POST https://api.pushward.app/activities \
  -H "Authorization: Bearer hlk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug": "my-build", "name": "My Build"}'
```

--------------------------------

### stat_list row with timer: backup example

Source: https://pushward.app/docs/widgets/templates/stat-list

Example content for a stat_list widget with a timer on the first row. The timer uses a relative style and a past date to count up. The value field remains required and serves as the static fallback for builds before 1.6.

```json
{
  "content": {
    "template": "stat_list",
    "label": "Backups",
    "stat_rows": [
      { "label": "Last run", "value": "12 min ago", "timer": { "date": "2027-05-10T08:00:00Z", "style": "relative" } },
      { "label": "Repos",    "value": "14" },
      { "label": "Failed",   "value": "0" }
    ]
  }
}
```

--------------------------------

### GET /activities/{slug}

Source: https://pushward.app/docs/api/activities

Retrieves a single activity by its slug.

```APIDOC
## GET /activities/{slug}

### Description
Retrieves a single activity by its slug.

### Method
GET

### Endpoint
/activities/{slug}

### Parameters
#### Path Parameters
- **slug** (string) - Required - The unique identifier of the activity.

### Request Example
curl https://api.pushward.app/activities/dishwasher \
  -H "Authorization: Bearer hlk_YOUR_TOKEN"

### Response
#### Success Response (200)
- **activity** (object) - The activity object.

#### Response Example
{
  "slug": "dishwasher",
  "state": "ongoing",
  "content": {}
}
```
Tokens:
Raw