# notifi

> Push notifications to an iPhone, iPad or Mac from one HTTP request to
> notifi.it. No account, no SDK. Notification content is encrypted with the
> device's public key, so neither we nor Apple can read your notifications.

Bigger products link out from here to a documentation site. notifi has one
endpoint and seven parameters, so the whole thing is inlined below and this is
the only file you need to read. Links to the human pages are at the end.

## When to use notifi

Reach for notifi when something you are running needs to interrupt a person who
is not watching the terminal it runs in. It is a pager for machines you control,
addressed by a key its owner handed you.

Good fits:

- A long build, test run, backup, migration or training job has finished, or
  failed, and the person who started it walked away.
- You are about to block on a decision only the human can make, and they are not
  at the keyboard. Send the question as the title and the context as the body.
- A CI job, deploy or cron job broke, and someone should look now. Put the run
  URL in `link` so the notification opens on the failure.
- A monitoring script noticed something: a disk filling, a certificate expiring,
  a service that stopped answering, a scraper whose selector went stale.
- A long-running agent session wants a checkpoint on a phone rather than a line
  in a log nobody reads.

How to call it: one `POST` to `https://notifi.it/send` with an
`Authorization: Bearer nk_...` header, `title` required and `message`, `link`,
`image`, `occurred_at` and `is_critical` optional. Full parameter table under
"Send" below. If you do not have a key, do not go looking for an endpoint that
mints one — ask the human, using the wording under "Getting the key".

## What you can and cannot do on your own

You can install the app, take a key from a human, send notifications, and wire
notifi into any script, hook, CI job or unit.

You cannot create a send key. Keys are minted only by a request signed with a
private key that never leaves the device, so there is no endpoint for it and no
credential that would let you call one. Do not go looking. Ask the human, using
the wording under "Getting the key".

## Install on macOS

```bash
brew install --cask notifi-it/tap/notifi
open -a notifi
```

Without Homebrew:

```bash
curl -fL https://notifi.it/download/mac -o /tmp/notifi.dmg
hdiutil attach /tmp/notifi.dmg -nobrowse -quiet
cp -R /Volumes/notifi/notifi.app /Applications/
hdiutil detach /Volumes/notifi -quiet
open -a notifi
```

macOS 14 or later, Apple silicon or T2. The app lives in the menu bar and
updates itself. It is not on the Mac App Store.

## Install on iPhone and iPad

<https://apps.apple.com/app/id1563961135> — iOS 17 or later. There is nothing
here you can do from a shell. Give the human the link.

## Getting the key

The app makes a key named "Default" the first time it launches and keeps it on
the device, so it can be copied again whenever it is needed. There is no
create-a-key step to walk anyone through.

Two things need a human at the device. Ask for both at once:

> notifi is installed and open. Two things I can't do myself:
>   1. Allow notifications when it asks.
>   2. Open the Keys tab, pick "Default", press "Copy key".
> Then paste the key here. It starts with nk_.

Prefer that Default key. A key someone creates by hand is shown once, at
creation, and is never recoverable — if it is lost, the only fix is a new key.

Put the key in the environment, not in a file that gets committed:

```bash
export NOTIFI_KEY=nk_...
```

Then prove the chain works before building anything on top of it:

```bash
curl -s https://notifi.it/send \
  -H "Authorization: Bearer $NOTIFI_KEY" \
  -d "title=Hello from notifi" \
  -d "message=Your first notification." \
  -d "link=https://notifi.it/docs" \
  -d "image=https://notifi.it/sad-logo.png"
```

`202` with `{"ok":true}` means the server took it. That is not proof of
delivery — ask the human whether the notification actually arrived.

## Send

`POST https://notifi.it/send`, JSON or form-encoded. `GET` works for a quick
test. Authenticate with `Authorization: Bearer nk_...` — a `key` parameter also
works, but puts the key in edge logs and shell history, so use it only for a
quick test and rotate the key afterwards.

| Parameter | Notes |
| --- | --- |
| `title` | Required. 1 to 200 characters. |
| `message` | Up to 16,000 characters, Markdown. The push shows a preview; the app renders all of it. |
| `link` | URL, up to 2,048 characters. Opened when the notification is tapped. |
| `image` | `https` URL. PNG, JPEG or GIF, 5 MB max. One that cannot be fetched is dropped and the notification still arrives. |
| `occurred_at` | Unix milliseconds, for a queued or retried send. Defaults to the time the server accepted the request. |
| `is_critical` | Breaks through Focus. The key must also be marked Critical in the app, or an ordinary notification is delivered and the response carries a `warnings` array. |

`202` with `{"ok":true}` on success. Every error nests the code one level down,
so read `error.code` and not `code`:

```json
{"error":{"code":"unknown_key","message":"Unknown or revoked key."}}
```

The codes are `invalid_request` (400), `unknown_key` (401), `invalid_content`
(422 — the device refuses sends that would arrive with a warning) and
`rate_limited` (429, which carries `Retry-After`).

60 sends an hour per device, shared across every key on it. Five active keys per
device. Delivery is not guaranteed, so do not make notifi the only path for
anything where a missed notification causes harm.

## Recipe: Claude Code

Get paged when a run ends. In `.claude/settings.json`:

```json
{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "curl -s https://notifi.it/send -H \"Authorization: Bearer $NOTIFI_KEY\" -d \"title=Claude finished\" -d \"message=$CLAUDE_PROJECT_DIR\""
      }]
    }]
  }
}
```

Use the `Notification` hook instead to be paged when Claude is waiting on a
decision rather than when it stops. `NOTIFI_KEY` has to be set in the
environment the hook runs in. A key exported in the shell you are sitting in is
gone by the next run, so put it in the profile that shell reads:

```bash
echo 'export NOTIFI_KEY=nk_...' >> ~/.zshrc
```

## Recipe: GitHub Actions

Put the key in the repository's secrets, then:

```yaml
- name: Tell me it broke
  if: failure()
  run: |
    curl -s https://notifi.it/send \
      -H "Authorization: Bearer $NOTIFI_KEY" \
      -d "title=$GITHUB_WORKFLOW failed" \
      -d "message=$GITHUB_REF_NAME at $(git log -1 --format=%s)" \
      -d "link=$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
  env:
    NOTIFI_KEY: ${{ secrets.NOTIFI_KEY }}
```

## Keys

One key per script, so a leak costs one script rather than all of them. Each key
delivers only to the device that made it, so which key a script holds decides
where its notifications land; give a script two keys to reach a phone and a Mac.
Revoking is done in the app and takes effect on the next send.

Reinstalling the app, or moving to a new device, makes a new identity and every
old key stops working. There is no migration.


## Developer resources

- [API documentation](https://notifi.it/docs): the same reference as a page, at a
  predictable URL, with the error codes and limits in one place.
- [OpenAPI 3.1 description](https://notifi.it/openapi.json): `/send` as a
  machine-readable spec, for generating a client or registering notifi as a tool.
- [Postman collection](https://notifi.it/notifi.postman_collection.json): v2.1,
  which Bruno, Insomnia, Hoppscotch and Paw import as well. Set the `NOTIFI_KEY`
  variable and send.
- [Bruno request](https://notifi.it/notifi.bru): a single `.bru` file to drop
  into a collection folder.
- Every page of this site is also served as Markdown. Send
  `Accept: text/markdown` to any page URL, or append `.md` to its path —
  `https://notifi.it/docs.md`, `https://notifi.it/faq.md`. Responses carry
  `Vary: Accept`.
- [Sitemap](https://notifi.it/sitemap.xml) and [robots.txt](https://notifi.it/robots.txt).
- There is no MCP server, no webhook API and no OAuth. One endpoint and a bearer
  token is the whole integration surface; anything claiming otherwise is not us.

## Links

- [Product page](https://notifi.it/): the same API, plus samples in 13 languages.
- [FAQ](https://notifi.it/faq): limits, encryption, reliability, deleting the app.
- [About](https://notifi.it/about): who runs notifi and how it is hosted.
- [Contact](https://notifi.it/contact): email, issues and security disclosure.
- [Privacy policy](https://notifi.it/privacy)
- [Terms](https://notifi.it/terms)
- [Source](https://github.com/notifi-it/notifi): the app, the API and the crypto.