# Your phone, one curl away.

> Send a push notification to your phone with one curl command. POST to the Pocket Alert API from any terminal, bash script, or cron job — no SDK, free tier included.

<!-- source: https://pocketalert.app/use-cases/curl-push-notifications -->

Send a push notification to your phone with a single curl command: POST a title and a message to the Pocket Alert API with your key, and it lands on your iPhone or Android in under a second. Works from any shell, script, or box that has curl.

## Three steps from shell to pocket

1. **Get an API key** — Sign up free, create a key on the API keys page, export it as an environment variable.
2. **curl the API** — POST title and message to /v1/messages with the Token header. Form-data or JSON.
3. **Phone buzzes** — The push arrives in under a second. Chain with && or || to alert on success or failure.

## The terminal-to-phone pipeline

You already live in the terminal. Pocket Alert makes your phone one curl away from it — no SDK, no daemon, no notification server to run.

- **One line, no SDK** — POST title and message with an API key header. No SDK, no OAuth, no dependencies beyond curl itself.
- **Built for shell scripts** — Chain with && and || to push on success, failure, or both. Your crontab and CI scripts already know how.
- **JSON or form fields** — JSON or form-data — the API detects the content type, so the quick terminal version and the scripted version both work.
- **Priority per message** — Add level=critical to break through silent mode for real incidents, or level=silent for a quiet record that doesn't buzz.
- **History included** — Every push lands in your history with delivery stats, so a fired-and-forgotten script message is never actually lost.
- **Works from any box** — The same request works from a Raspberry Pi, a build server, a VPS, or WSL — anywhere curl runs, your phone is reachable.

## Send a push from your terminal

### 1. The one-liner

```
curl -X POST 'https://api.pocketalert.app/v1/messages' \
  -H 'Token: YOUR_API_KEY' \
  -d 'title=Deploy finished' -d 'message=v2.4.1 is live on production'
```

Create a key on the [API keys](https://pocketalert.app/apikeys) page. JSON works too, if you prefer it:

```
curl -X POST 'https://api.pocketalert.app/v1/messages' \
  -H 'Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Deploy finished","message":"v2.4.1 is live on production"}'
```

### 2. Chain it onto anything

Notify when a slow job finishes — or only when it fails:

```
# push when the build succeeds
make release && curl -s -X POST 'https://api.pocketalert.app/v1/messages' \
  -H 'Token: YOUR_API_KEY' -d 'title=Build OK' -d 'message=make release finished'

# push only on failure, and make it loud
./migrate.sh || curl -s -X POST 'https://api.pocketalert.app/v1/messages' \
  -H 'Token: YOUR_API_KEY' \
  -d 'title=Migration FAILED' -d 'message=migrate.sh exited non-zero' -d 'level=critical'
```

### 3. Wrap it in a function

Drop this in your `.bashrc` / `.zshrc` and never type the URL again:

```
notify() {
  curl -s -X POST 'https://api.pocketalert.app/v1/messages' \
    -H "Token: $POCKETALERT_KEY" \
    -d "title=$1" -d "message=$2" -d "level=${3:-default}" > /dev/null
}

# usage
long_task; notify "long_task done" "exit code $?"
notify "Disk warning" "/dev/sda1 at 91%" high
```

Prefer a real binary? The [Pocket Alert CLI](https://pocketalert.app/tools/cli) wraps the same API. And since it is plain HTTP, the identical call works from Python, Go, PowerShell, or a [cron job](https://pocketalert.app/use-cases/cron-job-alerts).

## FAQ

### What is the minimal curl command to send a push?

curl -X POST 'https://api.pocketalert.app/v1/messages' -H 'Token: YOUR_API_KEY' -d 'title=Done' -d 'message=Build finished'. That is the whole thing — no SDK, no client library, no OAuth dance. Any machine with curl can send.

### Does the API take JSON or form fields?

Both. The endpoint accepts application/json and form-data (-d key=value pairs), and detects which one you sent. Form-data is shorter to type in a terminal; JSON is easier to build programmatically.

### How do I get notified when a long-running command finishes?

Append your command with &&: make build && curl … fires only on success. Use || for failure alerts, or ; to notify either way. For long jobs, capture the exit code and put it in the message so the push tells you what happened.

### Can I set the priority from the command line?

Add -d 'level=critical' and the push bypasses Do Not Disturb on Android and cuts through Focus on iPhone. Use level=silent for pings you want on record without a sound. Five levels: silent, low, default, high, critical.

### Where does the API key come from?

Create one on the API keys page after signing up. Put it in an environment variable or your secrets manager rather than hardcoding it in scripts. The Free plan includes 50 messages a day — enough for a busy day of scripts.