# End Live Activity
Source: https://activitysmith.com/docs/api-reference/endpoint/live-activity-end

POST /live-activity/end
Ends a Live Activity and archives its lifecycle.



# Start Live Activity
Source: https://activitysmith.com/docs/api-reference/endpoint/live-activity-start

POST /live-activity/start
Starts a Live Activity on all registered devices and returns an activity_id.



# Update Live Activity
Source: https://activitysmith.com/docs/api-reference/endpoint/live-activity-update

POST /live-activity/update
Updates an existing Live Activity. If the per-activity token is not registered yet, the update is queued.



# Send Push Notification
Source: https://activitysmith.com/docs/api-reference/endpoint/push-notification

POST /push-notification
Sends a push notification to every paired device in your account.



# Introduction
Source: https://activitysmith.com/docs/api-reference/introduction

ActivitySmith API reference

## Features

<CardGroup>
  <Card title="Push Notifications" icon="bell" href="/api-reference/endpoint/push-notification">
    Send a push notification to all of your paired devices.
  </Card>

  <Card title="Live Activities" icon="bolt" href="/api-reference/endpoint/live-activity-start">
    Start, update and end a Live Activity.
  </Card>
</CardGroup>

## Base URL

All requests contain the following base URL:

```bash theme={null}
https://activitysmith.com/api/
```

## Authentication

For authentication, it's required to include an Authorization header. The header should contain `Bearer ask_123456789`, where `ask_123456789` represents your API Key.

```bash theme={null}
Authorization: Bearer ask_123456789
```

## Response codes

ActivitySmith employs conventional HTTP status codes to signify the outcome of your requests.

Typically, 2xx HTTP status codes denote success, 4xx codes represent failures related to the user, and 5xx codes signal infrastructure problems.

| Status | Description                                  |
| ------ | -------------------------------------------- |
| 200    | Request was successful.                      |
| 400    | Verify the correctness of the parameters.    |
| 401    | The API key is invalid or was not provided.  |
| 404    | The requested resource could not be located. |
| 429    | The rate limit has been surpassed.           |
| 5xx    | Signifies a server error with ActivitySmith. |

Refer to the Error Codes section for a detailed explanation of all potential API errors.

## Rate limit

The ActivitySmith API has a [rate limit](/rate-limits) to ensure the stability and reliability of the service. The rate limit is applied to all endpoints and is based on the number of requests made within a specific time frame.

When you exceed the rate limit, you will receive a 429 response code.


# Live Activity Colors
Source: https://activitysmith.com/docs/colors

Colors can be used to customize the appearance of your Live Activities. You can choose from the following colors(default is `blue`):

### `lime`

<img alt="Lime Live Activity" />

### `green`

<img alt="Green Live Activity" />

### `cyan`

<img alt="Cyan Live Activity" />

### `blue`

<img alt="Blue Live Activity" />

### `purple`

<img alt="Purple Live Activity" />

### `magenta`

<img alt="Magenta Live Activity" />

### `red`

<img alt="Red Live Activity" />

### `orange`

<img alt="Orange Live Activity" />

### `yellow`

<img alt="Yellow Live Activity" />


# Quickstart
Source: https://activitysmith.com/docs/index

Send Live Activities and push notifications to your iOS devices from any backend

<div>
  <img alt="ActivitySmith Live Activities" />

  <img alt="ActivitySmith Push Notifications" />
</div>

## Welcome to ActivitySmith

[ActivitySmith](https://activitysmith.com) is API service that lets you trigger and update Live Activities and send push notifications directly from your own infrastructure. Pair your iOS device(s), authenticate with an API key, and send real-time alerts from any backend, cron, agent, or automation. Without building or maintaining your own iOS app or dealing directly with APNs.

## How to use it?

We provide an easy to use API. You can download the iOS app from the [App Store](https://apps.apple.com/us/app/activitysmith/id6752254835).

Check out the following resources to get started:

* **API**: [Documentation](https://activitysmith.com/docs/api-reference/introduction)
* **SDKs**: [Node](https://activitysmith.com/docs/sdks/node), [Python](https://activitysmith.com/docs/sdks/python), [CLI](https://activitysmith.com/docs/sdks/cli)
* **Others**: [Zapier](https://zapier.com/apps/activitysmith/integrations)

Want an SDK or Integration? Let us know at [adam@activitysmith.com](mailto:adam@activitysmith.com).

### API Key

To use the API, you need to sign up on [ActivitySmith](https://activitysmith.com/) and get an API key.

### Features

* [**Push Notifications**](#push-notifications): send a push notifications to all of your paired devices.
* [**Live Activities**](#live-activities): start, update and end a Live Activity on your lock screen or dynamic island.

### Powerful Capabilities

* **Glanceable observability**: monitor real-time system state and long-running operations directly on your lock screen or dynamic island.
* **The hard stuff**: APNs(Apple Push Notification service), certificates, orchestration
* **Customizability**: adapt the experience to fit your unique needs.
* **Works with any backend**: use with any backend, cron, agent, automation or AI tool.
* **iOS app**: ready to use native iOS app for your iPhone or iPad. No need to build your own.

## Push Notifications

To send a push notification, use the `push-notification` endpoint. It takes the title and message as parameters and sends a push notification to all of your paired devices.

<img alt="Push Notification" />

```bash theme={null}
curl -X POST https://activitysmith.com/api/push-notification \
  -H "Authorization: Bearer $ACTIVITYSMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Build Failed 🚨",
    "message": "CI pipeline failed on main branch"
  }'
```

**Response**

```json theme={null}
{
  "success": true,
  "devices_notified": 3,
  "users_notified": 1,
  "timestamp": "2025-08-12T12:00:00.000Z"
}
```

## Live Activities

### /start endpoint

To start a Live Activity, use the `live-activity/start` endpoint. It takes a `content_state` payload and starts a Live Activity on your lock screen or dynamic island. For a segmented progress activity, include `title`, `current_step`, `type`, and `number_of_steps`.

<img alt="Live Activity Start" />

```bash theme={null}
curl -X POST https://activitysmith.com/api/live-activity/start \
  -H "Authorization: Bearer $ACTIVITYSMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content_state": {
      "title": "ActivitySmith API Deployment",
      "subtitle": "start",
      "number_of_steps": 4,
      "current_step": 1,
      "type": "segmented_progress",
      "color": "yellow"
    }
  }'
```

### Response

It returns a `activity_id` that you can use to update or end the Live Activity.

```json theme={null}
{
  "success": true,
  "activity_id": "pLAr-Hnq9ZFW4sxlk43Lhbuok4GLh7UW",
  "devices_notified": 2,
  "users_notified": 1,
  "timestamp": "2026-01-28T09:57:22.929Z"
}
```

### /update endpoint

To update the Live Activity, call `live-activity/update` with the `activity_id` and a `content_state` payload (minimum: `title`, `current_step`).

<img alt="Live Activity Update" />

```bash theme={null}
curl -X POST https://activitysmith.com/api/live-activity/update \
  -H "Authorization: Bearer $ACTIVITYSMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "activity_id": "pLAr-Hnq9ZFW4sxlk43Lhbuok4GLh7UW",
    "content_state": {
      "title": "ActivitySmith API Deployment",
      "subtitle": "npm i & pm2",
      "current_step": 3
    }
  }'
```

### Response

```json theme={null}
{
  "success": true,
  "activity_id": "pLAr-Hnq9ZFW4sxlk43Lhbuok4GLh7UW",
  "devices_notified": 2,
  "timestamp": "2026-01-28T09:57:26.056Z"
}
```

### /end endpoint

To end the Live Activity, call `live-activity/end` with the `activity_id` and the content state.

<img alt="Live Activity End" />

```bash theme={null}
curl -X POST https://activitysmith.com/api/live-activity/end \
  -H "Authorization: Bearer $ACTIVITYSMITH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "activity_id": "pLAr-Hnq9ZFW4sxlk43Lhbuok4GLh7UW",
    "content_state": {
      "title": "ActivitySmith API Deployment",
      "subtitle": "done",
      "current_step": 4
    }
  }'
```

### Response

```json theme={null}
{
  "success": true,
  "activity_id": "pLAr-Hnq9ZFW4sxlk43Lhbuok4GLh7UW",
  "devices_notified": 2,
  "timestamp": "2026-01-28T09:57:29.258Z"
}
```


# Rate Limits
Source: https://activitysmith.com/docs/rate-limits

Rate limits for API requests

## Concurrent Live Activities Limits

Concurrent Live Activities represent how many live activities ActivitySmith can process for you at the same time.
Number of concurrent live activities is limited to 4. This limit mimics the number of concurrent live activities that can be processed by the iOS. If you exceed this limit, additional live activities will be ignored until resources become available.

In the future, we will allow you to increase this limit by upgrading to a paid plan.

If you require higher concurrency limits, please contact us at [adam@activitysmith.com](mailto:adam@activitysmith.com).

## API Rate Limits

Rate limits are measured in requests per minute and are primarily in place to prevent abuse. When configured correctly, your real bottleneck will be concurrent live activities.

**Shared account limit**: 60 requests per minute across these endpoints:

* `POST /push-notification`
* `POST /live-activity/start`
* `POST /live-activity/update`
* `POST /live-activity/end`

These rate limits are enforced to ensure fair usage and availability of the API for all users. If you require higher limits, please contact us at [adam@activitysmith.com](mailto:adam@activitysmith.com).


# CLI
Source: https://activitysmith.com/docs/sdks/cli

ActivitySmith CLI lets you send push notifications and manage Live Activities from the terminal.

## Installation

Install the ActivitySmith CLI globally using npm:

```bash CLI theme={null}
# Install globally with npm
npm install -g activitysmith-cli

# Authenticate
export ACTIVITYSMITH_API_KEY="YOUR-API-KEY"

# Verify
activitysmith --status
```

## Authentication

Set your API key as an environment variable before running commands:

```bash CLI theme={null}
export ACTIVITYSMITH_API_KEY="YOUR-API-KEY"
```

Verify the CLI is installed:

```bash CLI theme={null}
activitysmith --help
```

## Quickstart

Send a push notification:

```bash CLI theme={null}
activitysmith push \
  --title "Build Failed 🚨" \
  --message "CI pipeline failed on main branch"
```

## Commands

### Push Notification

Sends a push notification to every paired device in your account.

```bash CLI theme={null}
activitysmith push \
  --title "Build Failed 🚨" \
  --message "CI pipeline failed on main branch" \
  --subtitle "main"
```

### Live Activity: Start

Start a Live Activity and get back an `activityId` for updates.

```bash CLI theme={null}
activitysmith activity start \
  --content-state '{"title":"ActivitySmith API Deployment","subtitle":"start","numberOfSteps":4,"currentStep":1,"type":"segmented_progress","color":"yellow"}'
```

Or use flags:

```bash CLI theme={null}
activitysmith activity start \
  --title "ActivitySmith API Deployment" \
  --subtitle "start" \
  --number-of-steps 4 \
  --current-step 1 \
  --type segmented_progress \
  --color yellow
```

### Live Activity: Update

Update an existing Live Activity using its `activityId`.

```bash CLI theme={null}
activitysmith activity update \
  --activity-id "<activityId>" \
  --content-state '{"title":"ActivitySmith API Deployment","subtitle":"npm i & pm2","currentStep":3}'
```

Or use flags:

```bash CLI theme={null}
activitysmith activity update \
  --activity-id "<activityId>" \
  --title "ActivitySmith API Deployment" \
  --subtitle "npm i & pm2" \
  --current-step 3
```

### Live Activity: End

End a Live Activity and optionally control its dismissal timing.

```bash CLI theme={null}
activitysmith activity end \
  --activity-id "<activityId>" \
  --content-state '{"title":"ActivitySmith API Deployment","subtitle":"done","currentStep":4,"autoDismissMinutes":3}'
```

Or use flags:

```bash CLI theme={null}
activitysmith activity end \
  --activity-id "<activityId>" \
  --title "ActivitySmith API Deployment" \
  --subtitle "done" \
  --current-step 4 \
  --auto-dismiss-minutes 3
```

## Content State

You can provide content state in two ways:

* JSON: `--content-state '{...}'` or `--content-state-file path/to/payload.json`
* Flags: `--title`, `--subtitle`, `--type`, `--number-of-steps`, `--current-step`, `--color`, `--step-color`, `--auto-dismiss-minutes`

Use camelCase keys in JSON (for example: `numberOfSteps`, `currentStep`, `autoDismissMinutes`).

### Required Fields

* `activity start`: `title`, `numberOfSteps`, `currentStep`, `type`
* `activity update`: `title`, `currentStep`
* `activity end`: `title`, `currentStep`

### Field Reference

| Field                | Description                                                                                     |
| -------------------- | ----------------------------------------------------------------------------------------------- |
| `title`              | Primary label shown in the Live Activity.                                                       |
| `subtitle`           | Secondary label shown in the Live Activity.                                                     |
| `type`               | Layout type. For now: `segmented_progress`.                                                     |
| `numberOfSteps`      | Total steps in the progress flow.                                                               |
| `currentStep`        | Current step index (1-based).                                                                   |
| `color`              | Accent color (`lime`, `green`, `cyan`, `blue`, `purple`, `magenta`, `red`, `orange`, `yellow`). |
| `stepColor`          | Color for step segments (same values as `color`).                                               |
| `autoDismissMinutes` | Minutes before dismissal after ending (default `3`, `0` for immediate).                         |

## Output

Use `--json` to output machine-readable JSON.

## Error Handling

The CLI exits non-zero on non-2xx responses and prints the API error body (for example, rate limit or Live Activity limit errors).


# Node
Source: https://activitysmith.com/docs/sdks/node

ActivitySmith Node SDK is a wrapper around the ActivitySmith API to help you easily send push notifications and Live Activities to your iOS devices.

## Installation

To install the ActivitySmith Node SDK, you can use npm:

```js Node theme={null}
# npm install activitysmith

import ActivitySmith from "activitysmith";

const activitysmith = new ActivitySmith({ apiKey: "YOUR-API-KEY" });
```

## Usage

1. Get an API key from [ActivitySmith](https://activitysmith.com)
2. Set the API key as an environment variable named `ACTIVITYSMITH_API_KEY` or pass it as `apiKey` when creating the client.

Here's an example of how to use the SDK with error handling:

```js Node theme={null}
import ActivitySmith from "activitysmith";

const activitysmith = new ActivitySmith({
  apiKey: process.env.ACTIVITYSMITH_API_KEY,
});

try {
  const push = await activitysmith.notifications.sendPushNotification({
    pushNotificationRequest: {
      title: "Build Failed",
      message: "CI pipeline failed on main branch",
    },
  });

  const start = await activitysmith.liveActivities.startLiveActivity({
    liveActivityStartRequest: {
      contentState: {
        title: "ActivitySmith API Deployment",
        subtitle: "start",
        numberOfSteps: 4,
        currentStep: 1,
        type: "segmented_progress",
        color: "yellow",
      },
    },
  });

  const activityId = start.activityId;

  await activitysmith.liveActivities.updateLiveActivity({
    liveActivityUpdateRequest: {
      activityId,
      contentState: {
        title: "ActivitySmith API Deployment",
        subtitle: "npm i & pm2",
        currentStep: 3,
      },
    },
  });

  await activitysmith.liveActivities.endLiveActivity({
    liveActivityEndRequest: {
      activityId,
      contentState: {
        title: "ActivitySmith API Deployment",
        subtitle: "done",
        currentStep: 4,
        autoDismissMinutes: 3,
      },
    },
  });

  console.log("Push sent:", push.success);
} catch (error) {
  console.error(error);
}
```

### Send a Push Notification

Use `activitysmith.notifications.sendPushNotification` with a `pushNotificationRequest`. `title` is required; `message` and `subtitle` are optional.

```js Node theme={null}
const response = await activitysmith.notifications.sendPushNotification({
  pushNotificationRequest: {
    title: "Build Failed",
    message: "CI pipeline failed on main branch",
  },
});

console.log(response.devicesNotified, response.timestamp);
```

### Start a Live Activity

Use `activitysmith.liveActivities.startLiveActivity` with a `contentState` payload. For the segmented progress type, `title`, `numberOfSteps`, `currentStep`, and `type` are required. Use camelCase fields in the SDK (`numberOfSteps`, `currentStep`, `stepColor`, `autoDismissMinutes`).

```js Node theme={null}
const start = await activitysmith.liveActivities.startLiveActivity({
  liveActivityStartRequest: {
    contentState: {
      title: "ActivitySmith API Deployment",
      subtitle: "start",
      numberOfSteps: 4,
      currentStep: 1,
      type: "segmented_progress",
      color: "yellow",
    },
  },
});

const activityId = start.activityId;
```

### Update a Live Activity

Use `activitysmith.liveActivities.updateLiveActivity` with the `activityId` you received from `startLiveActivity`.

```js Node theme={null}
await activitysmith.liveActivities.updateLiveActivity({
  liveActivityUpdateRequest: {
    activityId,
    contentState: {
      title: "ActivitySmith API Deployment",
      subtitle: "npm i & pm2",
      currentStep: 3,
    },
  },
});
```

### End a Live Activity

Use `activitysmith.liveActivities.endLiveActivity` with the `activityId`. You can optionally control how long the ended Live Activity stays visible using `autoDismissMinutes` (default `3`, `0` for immediate dismissal).

```js Node theme={null}
await activitysmith.liveActivities.endLiveActivity({
  liveActivityEndRequest: {
    activityId,
    contentState: {
      title: "ActivitySmith API Deployment",
      subtitle: "done",
      currentStep: 4,
      autoDismissMinutes: 3,
    },
  },
});
```

## Error Handling

Handle errors with `try/catch` around API calls:

```js Node theme={null}
try {
  await activitysmith.notifications.sendPushNotification({
    pushNotificationRequest: { title: "Hello" },
  });
} catch (error) {
  console.error(error);
}
```


# Overview
Source: https://activitysmith.com/docs/sdks/overview

ActivitySmith SDKs are wrappers around the ActivitySmith API to help you easily send push notifications and Live Activities to your iOS devices.

## Official SDKs

<CardGroup>
  <Card title="Node SDK" icon="node" href="node">
    Explore the Node SDK for ActivitySmith.
  </Card>

  <Card title="Python SDK" icon="python" href="python">
    Explore the Python SDK for ActivitySmith.
  </Card>

  <Card title="CLI" icon="terminal" href="cli">
    Use ActivitySmith directly from the command line.
  </Card>
</CardGroup>


# Python
Source: https://activitysmith.com/docs/sdks/python

ActivitySmith Python SDK is a wrapper around the ActivitySmith API to help you easily send push notifications and Live Activities to your iOS devices.

## Installation

To install the ActivitySmith Python SDK, you can use pip:

```python Python theme={null}
# pip install activitysmith

from activitysmith import ActivitySmith

activitysmith = ActivitySmith(api_key="YOUR-API-KEY")
```

## Usage

1. Get an API key from [ActivitySmith](https://activitysmith.com)
2. Set the API key as an environment variable named `ACTIVITYSMITH_API_KEY` or pass it as a parameter to the `ActivitySmith` class.

Here's an example of how to use the SDK with error handling:

```python Python theme={null}
import os
from activitysmith import ActivitySmith

activitysmith = ActivitySmith(api_key=os.environ.get("ACTIVITYSMITH_API_KEY", "YOUR-API-KEY"))

try:
    response = activitysmith.notifications.send_push_notification(
        push_notification_request={
            "title": "Build Failed 🚨",
            "message": "CI pipeline failed on main branch",
        }
    )
    print("Notified:", response.devices_notified)
except Exception as err:
    print("Request failed:", err)
```

### Send a Push Notification

Use `activitysmith.notifications.send_push_notification` with a `push_notification_request` payload. `title` is required; `message` and `subtitle` are optional.

```python Python theme={null}
response = activitysmith.notifications.send_push_notification(
    push_notification_request={
        "title": "Build Failed 🚨",
        "message": "CI pipeline failed on main branch",
    }
)

print(response.success)
print(response.devices_notified)
```

### Start a Live Activity

Start a Live Activity with `activitysmith.live_activities.start_live_activity`. For a segmented progress activity, include `title`, `number_of_steps`, `current_step`, and `type`.

```python Python theme={null}
start = activitysmith.live_activities.start_live_activity(
    live_activity_start_request={
        "content_state": {
            "title": "ActivitySmith API Deployment",
            "subtitle": "start",
            "number_of_steps": 4,
            "current_step": 1,
            "type": "segmented_progress",
            "color": "yellow",
        }
    }
)

activity_id = start.activity_id
```

### Update a Live Activity

Update a Live Activity with `activitysmith.live_activities.update_live_activity`. The `content_state` requires at least `title` and `current_step`.

```python Python theme={null}
update = activitysmith.live_activities.update_live_activity(
    live_activity_update_request={
        "activity_id": activity_id,
        "content_state": {
            "title": "ActivitySmith API Deployment",
            "subtitle": "npm i & pm2",
            "current_step": 3,
        }
    }
)

print(update.devices_notified)
```

### End a Live Activity

End a Live Activity with `activitysmith.live_activities.end_live_activity`. You can optionally set `auto_dismiss_minutes` in the `content_state`.

```python Python theme={null}
end = activitysmith.live_activities.end_live_activity(
    live_activity_end_request={
        "activity_id": activity_id,
        "content_state": {
            "title": "ActivitySmith API Deployment",
            "subtitle": "done",
            "current_step": 4,
            "auto_dismiss_minutes": 3,
        }
    }
)

print(end.success)
```

## Error Handling

The SDK raises exceptions for non-2xx responses. Rate limit errors use the `error` and `message` fields, and Live Activity limits include `limit` and `active`. See [Rate Limits](/rate-limits) for details.