# Introduction

ActivitySmith API reference

## Features



### [Push Notifications](/docs/api-reference/endpoint/push-notification)

Send a push notification to all of your paired devices.



### [Live Activities](/docs/api-reference/endpoint/live-activity-stream)

Start, update, and dismiss a Live Activity stream.



### [Widgets](/docs/api-reference/endpoint/metric-value-update)

Create metrics and update the values shown in ActivitySmith widgets.



### [App Icon Badge](/docs/api-reference/endpoint/app-icon-badge-count)

Show the number you care about on your ActivitySmith app icon.

## Base URL

All requests contain the following base URL:

```bash
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](/docs/api-keys).

```bash
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.

## Character encoding

Send JSON request bodies as UTF-8. If a body has bytes that are not valid UTF-8, the API returns `400` with the code `invalid_utf8` and sends nothing. You can send the request again with a UTF-8 body.

### Accented characters and emoji on Windows

Some Windows tools send your text in a legacy code page instead of UTF-8:

- `curl` in Git Bash, when the JSON is on the command line.
- `Invoke-RestMethod`, `Invoke-WebRequest`, and the `curl` alias in Windows PowerShell 5.1, when the body is a string.

This causes two problems:

- Accented characters such as `é` become invalid bytes, and the API returns `invalid_utf8`.
- Emoji become `??`. The API cannot detect this because `??` is valid text, so the Push Notification shows `??`.

Plain ASCII text is not affected. To send other characters, use one of these options.

**Use an SDK or the CLI.** This is the simplest option. Use an [SDK or the CLI](/docs/sdks/overview) instead of cURL.

**Send the JSON through stdin in Git Bash.** `curl` sends stdin unchanged, so the text stays UTF-8:

```bash Git Bash
YOUR_API_KEY="your-api-key"

curl -X POST https://activitysmith.com/api/push-notification \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{"title":"Commande reçue 🚀","message":"Paiement confirmé"}
JSON
```

**Send UTF-8 bytes from PowerShell.** This example works in Windows PowerShell 5.1 and PowerShell 7:

```bash PowerShell
$YOUR_API_KEY = "your-api-key"

$body = @{
  title = "Commande reçue 🚀"
  message = "Paiement confirmé"
} | ConvertTo-Json -Compress

Invoke-RestMethod -Method Post `
  -Uri "https://activitysmith.com/api/push-notification" `
  -Headers @{ Authorization = "Bearer $YOUR_API_KEY" } `
  -ContentType "application/json; charset=utf-8" `
  -Body ([System.Text.Encoding]::UTF8.GetBytes($body))
```

Do not pass the JSON string directly to `-Body`. PowerShell versions before 7.4 do not encode it as UTF-8 by default.

If you save this example as a `.ps1` file for Windows PowerShell 5.1, save the file as UTF-8 with a BOM. Without a BOM, Windows PowerShell 5.1 misreads the accented characters and emoji in the script, and the API cannot detect the wrong text.

**Send a file with `curl.exe` from PowerShell.** Write each non-ASCII character as a JSON escape, such as `\u00e7` for `ç` and `\ud83d\ude80` for 🚀. The file is then plain ASCII, so no code page can change it:

```bash PowerShell
$YOUR_API_KEY = "your-api-key"

'{"title":"Commande re\u00e7ue \ud83d\ude80","message":"Paiement confirm\u00e9"}' | Set-Content -Encoding UTF8 body.json

curl.exe -X POST https://activitysmith.com/api/push-notification `
  -H "Authorization: Bearer $YOUR_API_KEY" `
  -H "Content-Type: application/json" `
  --data-binary "@body.json"
```

Follow these rules when you use `curl.exe`:

- Type `curl.exe`. In Windows PowerShell 5.1, `curl` runs `Invoke-WebRequest`.
- Send the JSON from a file. Windows PowerShell 5.1 removes the double quotes from JSON on the command line, and the API returns `invalid_json`.
- Put quotes around `"@body.json"`. PowerShell gives `@` a special meaning.
- In Command Prompt, save the same JSON as `body.json` with a text editor, then run the `curl.exe` command on one line.

## Channels

Channels let you target specific subsets of recipients instead of broadcasting to everyone in an account.

- Use channels when teams, environments, or workflows need separate delivery groups.
- Keep [API keys](/docs/api-keys) broad or channel-scoped depending on how strict you want targeting to be.

Read the full [channels guide](/docs/channels).

## Rate limit

The ActivitySmith API has a [rate limit](/docs/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.
