Alerts API

Send alerts from your apps to your iPhone.

New sales, signups, failed jobs, support tickets: anything your servers know about can buzz your phone with one HTTPS request. Each alert also lands in the Inbox in the I Need Alerts app.

Quick start

  1. Install I Need Alerts on your iPhone, sign in and allow notifications.
  2. Create an API key in the app (Settings → API keys) or on the web at ineedalerts.com/dashboard.
  3. Send your first alert:
curl https://ineedalerts.com/api/v1/events \
  -H "Authorization: Bearer $INEEDALERTS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"payments","title":"New payment: $24.99"}'

Your phone buzzes within a second or two. Only channel and title are required.

Get an API key

Keys belong to your I Need Alerts account and start with ina_. Make one per app or server, named after it (for example InmateDB or Billing worker), so you can see where each alert came from and revoke one without touching the others.

  • In the app: Settings → API keys → New key.
  • On the web: sign in at ineedalerts.com/dashboard with the same account (email, Apple or Google) and choose Create key.

The full key is shown once. Store it as a secret on your server, for example INEEDALERTS_KEY, and never put it in a website or a mobile app that others download. If a key leaks, revoke it and make a new one.

Send an alert

POST https://ineedalerts.com/api/v1/events with the key as a bearer token and a JSON body.

{
  "channel": "Orders",
  "title": "New order: $48.00 · 3 prints",
  "icon": "🖼️",
  "level": "success",
  "body": "**Rush shipping** requested. Notes: *gift wrap*",
  "fields": {"Customer": "Jane D.", "Plan": "Monthly", "Country": "United States"},
  "images": [{"url": "https://cdn.example.com/orders/1042/1.jpg", "caption": "Front"}],
  "url": "https://example.com/admin/orders/1042",
  "links": [{"label": "View customer", "url": "https://example.com/admin/customers/88"}],
  "key": "order-1042"
}

A report about several things reads best as a table:

{
  "channel": "Workers",
  "title": "Workers: all 4 healthy",
  "icon": "✅",
  "level": "success",
  "table": {
    "columns": ["Worker", "Queue", "Done", "Failed"],
    "rows": [["worker-1", "emails", 1204, 0], ["worker-2", "images", 388, 2]]
  }
}

Fields

FieldWhat it does
channelRequired. Groups alerts, such as payments, signups or errors. It's created the first time you use it, and each channel can be muted or have its push turned off in the app. Up to 50 characters.
channel_iconThe channel's icon in the app: one emoji, such as "💳", or an https image URL for your logo. Used until the person picks their own icon for the channel in the app.
titleRequired. The notification title. Up to 120 characters; keep it under about 60 to fit the Lock Screen.
bodyLonger text, up to 2,000 characters. Supports **bold**, *italic*, `code`, [links](https://…) and line breaks.
levelinfo (default), success, warning or critical. Shown as a colour in the Inbox.
iconOne emoji, shown before the title.
fieldsUp to 20 labels and values, as {"Plan": "Monthly"} or [{"label": "Plan", "value": "Monthly"}]. Without a body, the first three become the notification text.
table{"columns": [...], "rows": [[...]]}. Up to 6 columns and 50 rows, one value per column in each row.
urlThe main link, opened from the alert in the Inbox.
linksUp to 3 more buttons, as [{"label": "View customer", "url": "https://…"}]. Labels up to 30 characters.
imagesUp to 4 https image URLs, as ["https://…"] or [{"url": "https://…", "caption": "Front"}]. They show in the alert in the Inbox.
keyStops duplicates: the same key within 24 hours is recorded once. Use an order, ticket or job ID.
sounddefault, alarm for a loud alarm-clock sound, or none for a silent alert.
alarmtrue rings the iPhone like an alarm clock: full screen, through silent mode and Focus, until it's stopped. Use it for anything that can't wait: the site is down, payments are failing, or "alarm me when the job is done, even at 4am". It needs Alarms allowed in the app (Account) and iOS 26; otherwise it arrives as a Time Sensitive alert with the alarm sound. People can also set a channel to Ring as alarm for its critical alerts, or all of them, without the sender changing anything.
time_sensitivetrue or false to override the channel's Time Sensitive setting. By default only critical alerts ask for it.

Examples

Laravel

Http::withToken(config('services.ineedalerts.key'))
    ->timeout(5)
    ->post('https://ineedalerts.com/api/v1/events', [
        'channel' => 'payments',
        'title' => "New payment: {$amount}",
        'fields' => ['Customer' => $name, 'Plan' => $plan],
        'url' => route('admin.orders.show', $order),
        'key' => "order-{$order->id}",
    ]);

Node

await fetch("https://ineedalerts.com/api/v1/events", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.INEEDALERTS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ channel: "signups", title: "New signup", fields: { Email: user.email } }),
});

Python

import os, requests

requests.post(
    "https://ineedalerts.com/api/v1/events",
    headers={"Authorization": f"Bearer {os.environ['INEEDALERTS_KEY']}"},
    json={"channel": "errors", "title": "Nightly import failed", "level": "critical",
          "body": "3 files rejected. See the log for details."},
    timeout=5,
)

Shell (cron jobs, deploy scripts)

curl -fsS https://ineedalerts.com/api/v1/events \
  -H "Authorization: Bearer $INEEDALERTS_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"channel\":\"deploys\",\"title\":\"Deployed $(git rev-parse --short HEAD)\"}"

Responses and errors

  • 202 with {"id": "…", "channel": "Orders", "devices": 1}: recorded, and pushed to that many phones.
  • 200 with "duplicate": true: the same key arrived within 24 hours, so nothing new was recorded.
  • 401: the key is wrong or was revoked.
  • 422: a field is invalid. The answer names each field: {"message": "…", "errors": {"title": ["…"]}}.
  • 429: more than 120 alerts a minute from one key, or this month's alerts are used up.

devices is 0 when no phone is signed in with notifications allowed, or the channel is muted. The alert is still kept in the Inbox.

Limits

PlanAlerts a monthKept for
Free10030 days
7-day trial10,00030 days
Basic1,00030 days
Premium, Premium + SMS50,00090 days

After the trial an account moves to Free until a plan is chosen in the app. Each key can send up to 120 alerts a minute. Usage resets on the 1st of each month (UTC), and the app and dashboard show how much you've used.

Moving from Telegram

If your code already talks to a Telegram bot, change only the host and the token. I Need Alerts answers Telegram's Bot API in the same shape: formatting, photos, buttons, edits, and the taps and replies that come back. The rest of your code stays as it is.

# Before
https://api.telegram.org/bot<telegram-token>/sendMessage
# After
https://ineedalerts.com/bot0:<your ina_ key>/sendMessage

The token is your key with 0: in front, because Telegram libraries such as Nutgram and python-telegram-bot check that a token looks like 123:abc. The bare key works too. chat_id is kept and given back on updates, but alerts always go to the key's own account.

curl "https://ineedalerts.com/bot0:$INEEDALERTS_KEY/sendMessage" \
  -d chat_id=0 -d parse_mode=HTML \
  --data-urlencode "text=<b>Backup finished</b>
All 12 databases copied"
MethodWhat happens
sendMessageAn alert. The first line is the title, the rest the body. parse_mode HTML, Markdown and MarkdownV2 keep bold, italic, code and links. disable_notification makes it silent. It goes in a channel named after your key; add channel and channel_icon (not Telegram fields) to pick another channel and its icon.
sendPhoto
sendMediaGroup
Photos as uploads (multipart, attach:// in a group), https URLs or a file_id you got back. Up to 10 MB each. Uploaded photos are stored privately and shown only to you. An album is one alert.
reply_markupinline_keyboard buttons appear under the alert: url buttons open the link, callback_data buttons send a callback_query back to you. force_reply opens a reply box, with its input_field_placeholder.
editMessageText
editMessageCaption
editMessageReplyMarkup
deleteMessage
Change or remove an alert by its message_id. As in Telegram, an edit without reply_markup removes the buttons.
answerCallbackQueryIts text shows in the app under the button that was tapped.
setWebhook
deleteWebhook
getWebhookInfo
getUpdates
How taps and replies reach you. A webhook gets each update POSTed with your secret_token in X-Telegram-Bot-Api-Secret-Token, retried for a while if it fails. Without one, collect them with getUpdates (an offset confirms the ones before it). Updates are kept for 24 hours.
getMe
sendChatAction
Answered so libraries that call them keep working.

Once a key has a webhook or polls getUpdates, alerts sent with force_reply get a reply box in the app. A reply arrives as a Telegram message whose reply_to_message is the alert, so a bot that answers replies in Telegram works the same here. Methods that aren't listed answer 404 with ok: false.

Private alerts (end-to-end encrypted)

A private alert is sealed on your server before it's sent, for your iPhone's key and any agents you pair, so I Need Alerts stores and delivers only ciphertext. Turn it on in the app (Account → Private alerts), then send with the CLI or the Node library. What it's for and what we can still see: ineedalerts.com/private.

npx ineedalerts send --private --channel Payments --title "Payout failed" \
  --body "Acme Supply LLC · Stripe: account_closed" --field "Amount=\$1,240.00" --level critical
import { IneedAlerts } from 'ineedalerts';

const alerts = new IneedAlerts({ apiKey: process.env.INEEDALERTS_API_KEY });
await alerts.sendPrivate({ channel: 'Payments', title: 'Payout failed', body: '…', fields: { Amount: '$1,240.00' } });
  • Channels: a channel's first private alert makes it private, or turn on Private in its settings. A private channel refuses plain alerts (409, code: channel_private), and a normal channel refuses sealed ones (channel_not_private). Channel names aren't encrypted.
  • What's sealed: title, body, icon, url, fields, links, table and images. channel, channel_icon, level, key, time_sensitive, sound and alarm stay outside so we can route and ring it.
  • Not available on private channels: search, the website dashboard, and hosted AI connectors, because we can't read them. Pair an agent instead (below).

Agents

In the app, Account → Private alerts → Add an agent makes a one-time code. On the agent's computer, npx ineedalerts pair <code> makes its key (kept in ~/.config/ineedalerts/agent.json); then npx ineedalerts read shows its alerts, and claude mcp add ineedalerts-private -- npx -y ineedalerts mcp gives Claude Code the tools list_private_alerts and send_private_alert. Senders seal for each agent allowed on the channel; alerts from before an agent was paired stay sealed for it.

The format, for other languages

  1. GET /api/v1/private/recipients?channel=Payments with your key. It returns recipients: each a public_key (X25519, 32 bytes, base64url) and its key_id (the first 12 bytes of SHA-256 of the key, base64url).
  2. Make a random 32-byte content key and seal the alert's JSON with ChaCha20-Poly1305, a random 12-byte nonce and the associated data ina-e2e-1:content. ct is nonce ‖ ciphertext ‖ tag, base64url.
  3. Make a one-time X25519 key pair (epk). For each recipient: X25519 with its public key, then HKDF-SHA256 (salt: epk ‖ recipient key, info: ina-e2e-1:wrap, 32 bytes) gives a wrapping key. Seal the content key with it (ChaCha20-Poly1305, random nonce, associated data ina-e2e-1:key): 60 bytes, base64url.
  4. POST to /api/v1/events with the outside fields and "encrypted": {"v": 1, "epk": "…", "ct": "…", "keys": [{"kid": "…", "key": "…"}]}.

The reference code is src/crypto.js in the ineedalerts package (about 100 lines, no dependencies).

On your iPhone

  • Inbox: every alert, newest first, with its fields, table, images and buttons. Unread alerts show a red dot.
  • Channels: mute a channel for an hour, eight hours or a day, turn its push off and keep it in the Inbox only, or make it silent.
  • Grouping: notifications from the same channel stack together on the Lock Screen.
  • Test it: Send test alert in the app or on the dashboard checks your phone buzzes.
Privacy: alerts are kept only as long as your plan says, then deleted. Send what you need to act on, and leave out passwords, card numbers and other secrets.

Writing good alerts

  • Put the news in the title. It's all most people read. Lead with what happened and the number: "New order: $48.00 · 3 prints", not "Order notification".
  • Order fields by importance. The first three appear on the Lock Screen when there's no body.
  • Use body for a sentence, fields for facts and table for lists.
  • Pick the level honestly. Save critical for things that need someone now.
  • One channel per kind of alert, such as Payments, Signups and Errors, so each can be muted on its own.
  • Link to where you'd act, and send a key whenever a retry could repeat the alert.

Connect an AI agent (MCP)

Claude, ChatGPT, Cursor and other agents can work with your I Need Alerts account through its MCP server. Ask them to set reminders, check what's due, mark things done, or tell you when a long task finishes by push, email or text.

https://ineedalerts.com/mcp
  • Claude: Settings, Connectors, Add custom connector. Paste the address and leave the advanced fields empty. It then works in Claude on the web, desktop and phone.
  • ChatGPT: Settings, Apps and Connectors, Advanced settings, turn on developer mode, then create a connector with the address.
  • Claude Code: claude mcp add --transport http ineedalerts https://ineedalerts.com/mcp, then /mcp to sign in.
  • Cursor and others: add a remote MCP server with the address. Any client that supports OAuth works.

The first time, the agent opens ineedalerts.com so you can sign in and allow it. You choose the account; the agent never sees your password. Step-by-step guides for every app are on AI agents.

What agents can do

  • get_account, list_reminders, whats_due, get_reminder: read your reminders, time zone and plan.
  • create_reminder, update_reminder, delete_reminder: add and change reminders, with repeats and early nudges like the day before.
  • mark_reminder: done, skip, dismiss or snooze.
  • send_notification: message you now by push, or by email and text when your plan includes them. It lands in the app in the agent's own channel. With alarm: true your iPhone rings like an alarm clock, for anything you asked to be alarmed about.
  • list_alert_channels, list_app_alerts: see what your apps and agents sent you, by channel, by search, or only what's unread, and page back through older alerts.
  • get_app_alert: one alert in full, with its fields, links, table and buttons.
  • mark_app_alerts_read: mark alerts read by id, by channel or all at once.
Only ever you: agents can notify only the account that connected them, never anyone else. Disconnect any agent in the app under Account, AI agents. Plan limits apply the same as in the app.

For developers: OAuth 2.1 with dynamic client registration and PKCE (S256). Discovery is at /.well-known/oauth-protected-resource/mcp and /.well-known/oauth-authorization-server. Streamable HTTP, protocol versions 2025-11-25 and 2025-06-18.