API reference menu
Getting started
OverviewAuthentication and rate limitExamplesSending
Send a notificationPriority and repeatLinks, images and buttonsSourcesScheduled sendsWebhook templatesReceipts and replies
Receipts and callbacksRepliesTeams
Teams, roles and endpointsChannels and escalationWebhooks and emailAlert email and timelineTeam formsPlans, audit log and transferCompany sign‑in and SCIMThe web consoleAccount
Identity and moving phonesDevices, keys and historyThe Upgrade PassCompatibility
ntfy's publish APIProwl's APIAppendix
Endpoint indexErrors and status codesLimitsPriorities and fieldsGlossaryLimits
Each limit, quoted from where it is explained and linked there.
Sending#
| Limit | What the reference says |
|---|---|
Hourly limit | 1000 notifications per hour, per keyIn Authentication and rate limit: Rate limit |
Scheduled sends waiting | too many waiting ( 429 too_many_scheduled, 200 per account)In Scheduled sends: Scheduled sends |
Recurring series at once | 20 series at once per accountIn Scheduled sends: Recurring sends |
Scheduled delivery precision | Delivered within one scheduler tick (15 seconds) after its time, never before.In Scheduled sends: Scheduled sends |
Repeat until opened, default | by default every 5 minutes for up to an hourIn Priority and repeat: Repeat Until Opened |
Repeat until opened, choices | every 1, 2, 5 or 15 minutes, or off) and how long it keeps going (15 minutes, 1 hour or 3 hours)In Priority and repeat: Repeat Until Opened |
Repeating at once | At most 5 notifications repeat at once per account; a newer one stops the oldest.In Priority and repeat: Repeat Until Opened |
Sources per account | 409 too_many_sources past 500 names on one account.In Sources: POST /v1/sources |
Webhook template body | A body over 256 KB is 413.In Webhook templates |
Alerts summarised per group | A firing or resolved group, up to 5 alerts summarisedIn Webhook templates |
Field limits on a send#
The Limit column of the send fields: a length in characters, a count, or a range.
| Field | Limit |
|---|---|
source | 256 |
title | 1024 |
body | 10000 |
url | 512 |
image | 512 |
actions | 3 |
copy_text | 512 |
priority | −2…2 |
group_key | 128 |
dedupe_key | 128 |
replace_key | 128 |
delay | 10 s to 7 days |
at | 10 s to 7 days ahead |
callback_url | 512 |
callback_secret | 16 to 128 |
reply_within | 10 s to 7 days |
ttl | 10 s to 7 days |
tags | 5, 32 chars each |
every | 60 s to 7 days |
count | 1 to 1000 |
until | at most a year |
Callbacks#
| Limit | What the reference says |
|---|---|
Callback retries | Tried again after 30 s, 5 min, 30 min and 2 h on anything but a 2xx, then given up onIn Receipts and callbacks |
Callback deadline | the whole request (name lookup, connecting and the reply) has one 5 second deadlineIn Receipts and callbacks |
Teams#
| Limit | What the reference says |
|---|---|
Teams per owner | 5 teams per ownerIn Teams, roles and endpoints |
Invite redemption | 20 attempts an hourIn Teams, roles and endpoints |
Invite lifetime and uses | 60 s to 30 days; 1 to 100 usesIn Teams, roles and endpoints |
Channel members at creation | a list of at most 25 member idsIn Teams, roles and endpoints |
Escalation tiers | 60 s to 24 h, up to 5 tiersIn Channels and escalation: Escalation |
Destinations per channel | each channel may have 10In Webhooks and email |
Destination retries | A failure is retried after 30 s, 5 min, 30 min, 2 h and 12 h, then given up on.In Webhooks and email |
Destination switched off | A destination whose deliveries fail 20 times in a row is switched offIn Webhooks and email |
Email verification | 3 per address and 20 per team a dayIn Webhooks and email |
Email volume | An address receives at most 60 emails an hour and a team 500 a dayIn Webhooks and email |
Forms | 3 forms on Team, any number on Team Plus; each form accepts 500 submissions a day; 50 MB of attachments per teamIn Team forms |
Form slug | 3 to 40 lowercase letters, digits and hyphensIn Team forms |
Form origins | up to 10 exact https:/ values, no wildcards, no pathsIn Team forms |
Form retention | retention_days 30 to 730In Team forms |
Audit log page | GET /In Plans, audit log and transfer: Audit log |
Ownership offer | An offer lasts 7 days.In Plans, audit log and transfer: Ownership transfer |
Plan grace | active, trialing and comped work until period_end, then for a 14-day graceIn Plans, audit log and transfer: Plans and billing |
Console#
| Limit | What the reference says |
|---|---|
Pairing code | The code is single use, lasts 10 minutesIn The web console |
Session length | A session ends after 2 hours idle or 8 hours in all.In The web console |
Account#
| Limit | What the reference says |
|---|---|
Moving code | Returns a code like K4M2-P7QX, valid 10 minutes, single useIn Identity and moving phones: Moving to a phone on another Apple Account |
History length | 30 days by default, or 90, 180 or 365 with the Upgrade PassIn Devices, keys and history |
Compatibility#
| Limit | What the reference says |
|---|---|
Prowl keys per call | Up to five, comma separated, as Prowl allowedIn Prowl's API: GET|POST /publicapi/add |
Prowl rate limit | The key's 1000/hour is spent. Not 429: Prowl used 406 and clients back off on itIn Prowl's API: Status codes |