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
- Install I Need Alerts on your iPhone, sign in and allow notifications.
- Create an API key in the app (Settings → API keys) or on the web at ineedalerts.com/dashboard.
- 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
| Field | What it does |
|---|---|
channel | Required. 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_icon | The 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. |
title | Required. The notification title. Up to 120 characters; keep it under about 60 to fit the Lock Screen. |
body | Longer text, up to 2,000 characters. Supports **bold**, *italic*, `code`, [links](https://…) and line breaks. |
level | info (default), success, warning or critical. Shown as a colour in the Inbox. |
icon | One emoji, shown before the title. |
fields | Up 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. |
url | The main link, opened from the alert in the Inbox. |
links | Up to 3 more buttons, as [{"label": "View customer", "url": "https://…"}]. Labels up to 30 characters. |
images | Up to 4 https image URLs, as ["https://…"] or [{"url": "https://…", "caption": "Front"}]. They show in the alert in the Inbox. |
key | Stops duplicates: the same key within 24 hours is recorded once. Use an order, ticket or job ID. |
sound | default, alarm for a loud alarm-clock sound, or none for a silent alert. |
alarm | true 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_sensitive | true 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
202with{"id": "…", "channel": "Orders", "devices": 1}: recorded, and pushed to that many phones.200with"duplicate": true: the samekeyarrived 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
| Plan | Alerts a month | Kept for |
|---|---|---|
| Free | 100 | 30 days |
| 7-day trial | 10,000 | 30 days |
| Basic | 1,000 | 30 days |
| Premium, Premium + SMS | 50,000 | 90 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"
| Method | What happens |
|---|---|
sendMessage | An 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. |
sendPhotosendMediaGroup | 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_markup | inline_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. |
editMessageTexteditMessageCaptioneditMessageReplyMarkupdeleteMessage | Change or remove an alert by its message_id. As in Telegram, an edit without reply_markup removes the buttons. |
answerCallbackQuery | Its text shows in the app under the button that was tapped. |
setWebhookdeleteWebhookgetWebhookInfogetUpdates | 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. |
getMesendChatAction | 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,tableandimages.channel,channel_icon,level,key,time_sensitive,soundandalarmstay 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
GET /api/v1/private/recipients?channel=Paymentswith your key. It returnsrecipients: each apublic_key(X25519, 32 bytes, base64url) and itskey_id(the first 12 bytes of SHA-256 of the key, base64url).- 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.ctis nonce ‖ ciphertext ‖ tag, base64url. - 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 dataina-e2e-1:key): 60 bytes, base64url. - POST to
/api/v1/eventswith 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.
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
bodyfor a sentence,fieldsfor facts andtablefor lists. - Pick the level honestly. Save
criticalfor 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
keywhenever 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/mcpto 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. Withalarm: trueyour 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.
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.