Skip to content

Subscribe via API

You can create and subscribe to a topic in the web UI, via the phone app, via the ntfy CLI, or in your own app or script by subscribing the API. This page describes how to subscribe via API. You may also want to check out the page that describes how to publish messages.

You can consume the subscription API as either a simple HTTP stream (JSON, SSE or raw), or via WebSockets. Both are incredibly simple to use.

HTTP stream

The HTTP stream-based API relies on a simple GET request with a streaming HTTP response, i.e you open a GET request and the connection stays open forever, sending messages back as they come in. There are three different API endpoints, which only differ in the response format:

Subscribe as JSON stream

Here are a few examples of how to consume the JSON endpoint (<topic>/json). For almost all languages, this is the recommended way to subscribe to a topic. The notable exception is JavaScript, for which the SSE/EventSource stream is much easier to work with.

$ curl -s ntfy.sh/disk-alerts/json
{"id":"SLiKI64DOt","time":1635528757,"event":"open","topic":"mytopic"}
{"id":"hwQ2YpKdmg","time":1635528741,"event":"message","topic":"mytopic","message":"Disk full"}
{"id":"DGUDShMCsc","time":1635528787,"event":"keepalive","topic":"mytopic"}
...

$ ntfy subcribe disk-alerts
{"id":"hwQ2YpKdmg","time":1635528741,"event":"message","topic":"mytopic","message":"Disk full"}
...

GET /disk-alerts/json HTTP/1.1
Host: ntfy.sh

HTTP/1.1 200 OK
Content-Type: application/x-ndjson; charset=utf-8
Transfer-Encoding: chunked

{"id":"SLiKI64DOt","time":1635528757,"event":"open","topic":"mytopic"}
{"id":"hwQ2YpKdmg","time":1635528741,"event":"message","topic":"mytopic","message":"Disk full"}
{"id":"DGUDShMCsc","time":1635528787,"event":"keepalive","topic":"mytopic"}
...

resp, err := http.Get("https://ntfy.sh/disk-alerts/json")
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()
scanner := bufio.NewScanner(resp.Body)
for scanner.Scan() {
    println(scanner.Text())
}

resp = requests.get("https://ntfy.sh/disk-alerts/json", stream=True)
for line in resp.iter_lines():
  if line:
    print(line)

$fp = fopen('https://ntfy.sh/disk-alerts/json', 'r');
if (!$fp) die('cannot open stream');
while (!feof($fp)) {
    echo fgets($fp, 2048);
    flush();
}
fclose($fp);

Subscribe as SSE stream

Using EventSource in JavaScript, you can consume notifications via a Server-Sent Events (SSE) stream. It's incredibly easy to use. Here's what it looks like. You may also want to check out the full example on GitHub.

$ curl -s ntfy.sh/mytopic/sse
event: open
data: {"id":"weSj9RtNkj","time":1635528898,"event":"open","topic":"mytopic"}

data: {"id":"p0M5y6gcCY","time":1635528909,"event":"message","topic":"mytopic","message":"Hi!"}

event: keepalive
data: {"id":"VNxNIg5fpt","time":1635528928,"event":"keepalive","topic":"test"}
...

GET /mytopic/sse HTTP/1.1
Host: ntfy.sh

HTTP/1.1 200 OK
Content-Type: text/event-stream; charset=utf-8
Transfer-Encoding: chunked

event: open
data: {"id":"weSj9RtNkj","time":1635528898,"event":"open","topic":"mytopic"}

data: {"id":"p0M5y6gcCY","time":1635528909,"event":"message","topic":"mytopic","message":"Hi!"}

event: keepalive
data: {"id":"VNxNIg5fpt","time":1635528928,"event":"keepalive","topic":"test"}
...

const eventSource = new EventSource('https://ntfy.sh/mytopic/sse');
eventSource.onmessage = (e) => {
  console.log(e.data);
};

Subscribe as raw stream

The /raw endpoint will output one line per message, and will only include the message body. It's useful for extremely simple scripts, and doesn't include all the data. Additional fields such as priority, tags or message title are not included in this output format. Keepalive messages are sent as empty lines.

$ curl -s ntfy.sh/disk-alerts/raw

Disk full
...

GET /disk-alerts/raw HTTP/1.1
Host: ntfy.sh

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked

Disk full
...

resp, err := http.Get("https://ntfy.sh/disk-alerts/raw")
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()
scanner := bufio.NewScanner(resp.Body)
for scanner.Scan() {
    println(scanner.Text())
}

resp = requests.get("https://ntfy.sh/disk-alerts/raw", stream=True)
for line in resp.iter_lines():
  if line:
    print(line)

$fp = fopen('https://ntfy.sh/disk-alerts/raw', 'r');
if (!$fp) die('cannot open stream');
while (!feof($fp)) {
    echo fgets($fp, 2048);
    flush();
}
fclose($fp);

WebSockets

You may also subscribe to topics via WebSockets, which is also widely supported in many languages. Most notably, WebSockets are natively supported in JavaScript. You may also want to check out the full example on GitHub. On the command line, I recommend websocat, a fantastic tool similar to socat or curl, but specifically for WebSockets.

The WebSockets endpoint is available at <topic>/ws and returns messages as JSON objects similar to the JSON stream endpoint. 

$ websocat wss://ntfy.sh/mytopic/ws
{"id":"qRHUCCvjj8","time":1642307388,"event":"open","topic":"mytopic"}
{"id":"eOWoUBJ14x","time":1642307754,"event":"message","topic":"mytopic","message":"hi there"}

GET /disk-alerts/ws HTTP/1.1
Host: ntfy.sh
Upgrade: websocket
Connection: Upgrade

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
...

import "github.com/gorilla/websocket"
ws, _, _ := websocket.DefaultDialer.Dial("wss://ntfy.sh/mytopic/ws", nil)
messageType, data, err := ws.ReadMessage()
...

const socket = new WebSocket('wss://ntfy.sh/mytopic/ws');
socket.addEventListener('message', function (event) {
    console.log(event.data);
});

Advanced features

Poll for messages

You can also just poll for messages if you don't like the long-standing connection using the poll=1 query parameter. The connection will end after all available messages have been read. This parameter can be combined with since= (defaults to since=all).

curl -s "ntfy.sh/mytopic/json?poll=1"

Fetch cached messages

Messages may be cached for a couple of hours (see message caching) to account for network interruptions of subscribers. If the server has configured message caching, you can read back what you missed by using the since= query parameter. It takes a duration (e.g. 10m or 30s), a Unix timestamp (e.g. 1635528757), a message ID (e.g. nFS3knfcQ1xe), or all (all cached messages).

curl -s "ntfy.sh/mytopic/json?since=10m"
curl -s "ntfy.sh/mytopic/json?since=1645970742"
curl -s "ntfy.sh/mytopic/json?since=nFS3knfcQ1xe"

Fetch scheduled messages

Messages that are scheduled to be delivered at a later date are not typically returned when subscribing via the API, which makes sense, because after all, the messages have technically not been delivered yet. To also return scheduled messages from the API, you can use the scheduled=1 (alias: sched=1) parameter (makes most sense with the poll=1 parameter):

curl -s "ntfy.sh/mytopic/json?poll=1&sched=1"

Filter messages

You can filter which messages are returned based on the well-known message fields id, message, title, priority and tags. Here's an example that only returns messages of high or urgent priority that contains the both tags "zfs-error" and "error". Note that the priority filter is a logical OR and the tags filter is a logical AND. 

$ curl "ntfy.sh/alerts/json?priority=high&tags=zfs-error"
{"id":"0TIkJpBcxR","time":1640122627,"event":"open","topic":"alerts"}
{"id":"X3Uzz9O1sM","time":1640122674,"event":"message","topic":"alerts","priority":4,
  "tags":["error", "zfs-error"], "message":"ZFS pool corruption detected"}

Available filters (all case-insensitive):

Filter variable Alias Example Description
id X-ID ntfy.sh/mytopic/json?poll=1&id=pbkiz8SD7ZxG Only return messages that match this exact message ID
message X-Message, m ntfy.sh/mytopic/json?message=lalala Only return messages that match this exact message string
title X-Title, t ntfy.sh/mytopic/json?title=some+title Only return messages that match this exact title string
priority X-Priority, prio, p ntfy.sh/mytopic/json?p=high,urgent Only return messages that match any priority listed (comma-separated)
tags X-Tags, tag, ta ntfy.sh/mytopic?/jsontags=error,alert Only return messages that match all listed tags (comma-separated)

Subscribe to multiple topics

It's possible to subscribe to multiple topics in one HTTP call by providing a comma-separated list of topics in the URL. This allows you to reduce the number of connections you have to maintain:

$ curl -s ntfy.sh/mytopic1,mytopic2/json
{"id":"0OkXIryH3H","time":1637182619,"event":"open","topic":"mytopic1,mytopic2,mytopic3"}
{"id":"dzJJm7BCWs","time":1637182634,"event":"message","topic":"mytopic1","message":"for topic 1"}
{"id":"Cm02DsxUHb","time":1637182643,"event":"message","topic":"mytopic2","message":"for topic 2"}

Authentication

Depending on whether the server is configured to support access control, some topics may be read/write protected so that only users with the correct credentials can subscribe or publish to them. To publish/subscribe to protected topics, you can:

  • Use basic auth, e.g. Authorization: Basic dGVzdHVzZXI6ZmFrZXBhc3N3b3Jk
  • or use the auth query parameter, e.g. ?auth=QmFzaWMgZEdWemRIVnpaWEk2Wm1GclpYQmhjM04zYjNKaw

Please refer to the publishing documentation for additional details.

JSON message format

Both the /json endpoint and the /sse endpoint return a JSON format of the message. It's very straight forward:

Message:

Field Required Type Example Description
id ✔️ string hwQ2YpKdmg Randomly chosen message identifier
time ✔️ number 1635528741 Message date time, as Unix time stamp
expires (✔)️ number 1673542291 Unix time stamp indicating when the message will be deleted, not set if Cache: no is sent
event ✔️ open, keepalive, message, or poll_request message Message type, typically you'd be only interested in message
topic ✔️ string topic1,topic2 Comma-separated list of topics the message is associated with; only one for all message events, but may be a list in open events
message - string Some message Message body; always present in message events
title - string Some title Message title; if not set defaults to ntfy.sh/<topic>
tags - string array ["tag1","tag2"] List of tags that may or not map to emojis
priority - 1, 2, 3, 4, or 5 4 Message priority with 1=min, 3=default and 5=max
click - URL https://example.com Website opened when notification is clicked
actions - JSON array see actions buttons Action buttons that can be displayed in the notification
attachment - JSON object see below Details about an attachment (name, URL, size, ...)

Attachment (part of the message, see attachments for details):

Field Required Type Example Description
name ✔️ string attachment.jpg Name of the attachment, can be overridden with X-Filename, see attachments
url ✔️ URL https://example.com/file.jpg URL of the attachment
type -️ mime type image/jpeg Mime type of the attachment, only defined if attachment was uploaded to ntfy server
size -️ number 33848 Size of the attachment in bytes, only defined if attachment was uploaded to ntfy server
expires -️ number 1635528741 Attachment expiry date as Unix time stamp, only defined if attachment was uploaded to ntfy server

Here's an example for each message type:

{
    "id": "sPs71M8A2T",
    "time": 1643935928,
    "expires": 1643936928,
    "event": "message",
    "topic": "mytopic",
    "priority": 5,
    "tags": [
        "warning",
        "skull"
    ],
    "click": "https://homecam.mynet.lan/incident/1234",
    "attachment": {
        "name": "camera.jpg",
        "type": "image/png",
        "size": 33848,
        "expires": 1643946728,
        "url": "https://ntfy.sh/file/sPs71M8A2T.png"
    },
    "title": "Unauthorized access detected",
    "message": "Movement detected in the yard. You better go check"
}

{
    "id": "wze9zgqK41",
    "time": 1638542110,
    "expires": 1638543112,
    "event": "message",
    "topic": "phil_alerts",
    "message": "Remote access to phils-laptop detected. Act right away."
}

{
    "id": "2pgIAaGrQ8",
    "time": 1638542215,
    "event": "open",
    "topic": "phil_alerts"
}

{
    "id": "371sevb0pD",
    "time": 1638542275,
    "event": "keepalive",
    "topic": "phil_alerts"
}

{
    "id": "371sevb0pD",
    "time": 1638542275,
    "event": "poll_request",
    "topic": "phil_alerts"
}

List of all parameters

The following is a list of all parameters that can be passed when subscribing to a message. Parameter names are case-insensitive, and can be passed as HTTP headers or query parameters in the URL. They are listed in the table in their canonical form.

Parameter Aliases (case-insensitive) Description
poll X-Poll, po Return cached messages and close connection
since X-Since, si Return cached messages since timestamp, duration or message ID
scheduled X-Scheduled, sched Include scheduled/delayed messages in message list
id X-ID Filter: Only return messages that match this exact message ID
message X-Message, m Filter: Only return messages that match this exact message string
title X-Title, t Filter: Only return messages that match this exact title string
priority X-Priority, prio, p Filter: Only return messages that match any priority listed (comma-separated)
tags X-Tags, tag, ta Filter: Only return messages that match all listed tags (comma-separated)