Introduction

Features#

Base URL#

All requests contain the following base URL:

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.

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.

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 instead of cURL.

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

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:

$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:

$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 broad or channel-scoped depending on how strict you want targeting to be.

Read the full channels guide.

Rate limit#

The ActivitySmith API has a rate limit 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.