# Getting started

You need two things: the service's **base URL** and a **send token**.

1. **Install NoticeFox** on your iPhone (and Apple Watch). On first launch the app creates
   your account and registers the device. There's no sign-in: the account key lives in your
   iCloud Keychain, so your other Apple devices can join the same account.
2. **Create a send token** in the app, with a label that says who will use it, for example
   "Home Assistant" or "CI". Every notification it sends shows "via <label>". The token
   (`nfx_send_` followed by 32 letters and digits) is shown **once**; copy it into your
   password manager or secret store. You can also link the NoticeFox CLI, which gets its own
   labeled token.
3. **Note the base URL** of the service the token belongs to: `https://api.noticefox.app` for
   NoticeFox itself (a test service has its own). A token works only with the service that
   issued it.

## Send a notification

```bash
export NOTICEFOX_URL=https://api.noticefox.app
export NOTICEFOX_TOKEN=nfx_send_…   # your token

curl -s "$NOTICEFOX_URL/v1/notifications" \
  -H "Authorization: Bearer $NOTICEFOX_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"title": "Backup", "message": "Nightly backup finished"}' | tee response.json
```

The answer is `202 Accepted`:

```json
{ "id": "ntf_01JABCDEFGHJKMNPQRSTVWXYZ0", "status": "accepted", "request_id": "req_8hT2kLm4Qw9Zx1Cv3Bn5" }
```

"Accepted" means stored and queued for delivery. To check what happened to it, take the
`id` from that answer (here with [`jq`](https://jqlang.org), from the `response.json` the
command saved) and ask for its status:

```bash
MESSAGE_ID=$(jq -r .id response.json)

curl "$NOTICEFOX_URL/v1/notifications/$MESSAGE_ID/status" \
  -H "Authorization: Bearer $NOTICEFOX_TOKEN"
```

## The one-line version

Where a tool can only fetch a URL, put the token in the path. This is the **simple
endpoint**:

```bash
curl -d "Build finished" "$NOTICEFOX_URL/v1/send/$NOTICEFOX_TOKEN"
```

A URL with a token in it can leak through logs, browser history and link previews, so prefer
the `Authorization` header wherever your tool supports it. See [Security](security.md).

## Next

- [curl examples](curl.md) for scenes, levels, links and the simple endpoint's sources.
- [Fields and limits](fields.md) for every field.
- [Home Assistant](home-assistant.md) and [Apprise](apprise.md).
- [Error codes](errors.md) and [Quotas](quotas.md).