> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# ntfy

> Client-mode REST API connector for ntfy: publish plain-text or JSON notifications with Priority/Tags/Actions, poll cached JSON, and health

Technical Preview

## Overview

A client-mode connector for a **curated publish/subscribe** slice of [ntfy](https://docs.ntfy.sh/):

| Catalog connector event | Entity / path | Notes | |
| - | - | - | - |
| PUT / POST `{topic}` | \`PUT | POST /{topic}\` | Plain-text body; `Title`, `Priority`, `Tags` headers |
| POST with action buttons | `POST /` JSON or `Actions` header | `http` actions can callback a Coreflux REST server connector | |
| GET `{topic}/json` | `GET /{topic}/json?poll=1` | Poll cached messages (not a long-lived stream in this package) | |
| GET health (smoke) | `GET /v1/health` | Public; no auth | |

Default `BASE_ADDRESS` is `https://ntfy.sh` (replace with your self-hosted origin). Topics use `messaging/ntfy/<object>/<verb>`.

> [!NOTE]
>
> Public **ntfy.sh** topics allow **anonymous** publish/subscribe. Self-hosted servers may enforce ACLs with Bearer tokens or Basic auth — pass `Authorization` via `{value.json.token}` / `{value.json.basic_b64}` placeholders and Hub secrets. Prefer hard-to-guess topic names; treat the topic as a shared secret on public hosts.

## Basic Syntax

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — ntfy
# Auth: none on public topics; optional Bearer {value.json.token} for ACLs
# BASE_ADDRESS: https://ntfy.sh

DEFINE ROUTE NtfyRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://ntfy.sh"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "text/plain"
    ADD EVENT Publishmessage
        WITH SOURCE_TOPIC "messaging/ntfy/message/publish"
        WITH DESTINATION_TOPIC "messaging/ntfy/message/publish/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/{value.json.topic}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "text/plain"
            ADD "Title" "{value.json.title}"
            ADD "Priority" "{value.json.priority}"
            ADD "Tags" "{value.json.tags}"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{payload}"
    ADD EVENT Publishwithheaders
        WITH SOURCE_TOPIC "messaging/ntfy/message/publish-headers"
        WITH DESTINATION_TOPIC "messaging/ntfy/message/publish-headers/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/{value.json.topic}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "text/plain"
            ADD "Title" "{value.json.title}"
            ADD "Priority" "{value.json.priority}"
            ADD "Tags" "{value.json.tags}"
            ADD "Actions" "{value.json.actions}"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{payload}"
    ADD EVENT Publishjson
        WITH SOURCE_TOPIC "messaging/ntfy/message/publish-json"
        WITH DESTINATION_TOPIC "messaging/ntfy/message/publish-json/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
        WITH BODY "{payload}"
    ADD EVENT Getcached
        WITH SOURCE_TOPIC "messaging/ntfy/message/get-cached"
        WITH DESTINATION_TOPIC "messaging/ntfy/message/get-cached/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/{value.json.topic}/json?poll=1&since={value.json.since}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT Getlatest
        WITH SOURCE_TOPIC "messaging/ntfy/message/get-latest"
        WITH DESTINATION_TOPIC "messaging/ntfy/message/get-latest/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/{value.json.topic}/json?poll=1&since=latest"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "Bearer {value.json.token}"
    ADD EVENT Health
        WITH SOURCE_TOPIC "messaging/ntfy/health/get"
        WITH DESTINATION_TOPIC "messaging/ntfy/health/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/v1/health"
        WITH HEADERS
            ADD "Accept" "application/json"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Publishmessage | PUT | `/{topic}` | `messaging/ntfy/message/publish` | `messaging/ntfy/message/publish/response` |
| Publishwithheaders | POST | `/{topic}` | `messaging/ntfy/message/publish-headers` | `messaging/ntfy/message/publish-headers/response` |
| Publishjson | POST | `/` | `messaging/ntfy/message/publish-json` | `messaging/ntfy/message/publish-json/response` |
| Getcached | GET | `/{topic}/json?poll=1&since=` | `messaging/ntfy/message/get-cached` | `messaging/ntfy/message/get-cached/response` |
| Getlatest | GET | `/{topic}/json?poll=1&since=latest` | `messaging/ntfy/message/get-latest` | `messaging/ntfy/message/get-latest/response` |
| Health | GET | `/v1/health` | `messaging/ntfy/health/get` | `messaging/ntfy/health/get/response` |

## Auth

1. For **public ntfy.sh** topics: no credentials. Pick a hard-to-guess topic (`[-_A-Za-z0-9]`, ≤64 chars).
2. Set connector `BASE_ADDRESS` to `https://ntfy.sh` or your self-hosted URL.
3. For **self-hosted ACLs**, pass `token` (Bearer) or `basic_b64` on the MQTT payload; store secrets with Hub / `GET SECRET "NTFY_TOKEN"`.
4. Successful publish returns **HTTP 200** with a JSON message object. Health returns **HTTP 200** and `{"healthy":true}`.

## Example payloads

**PublishMessage** (path/header placeholders on MQTT JSON; HTTP body is plain text via `{payload}`):

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "topic": "coreflux-alerts-lab",
  "title": "Zone A vibration",
  "priority": "high",
  "tags": "warning,rotating_light",
  "token": ""
}
```

HTTP body example: `Coreflux alarm: vibration above threshold — Zone A`

**PublishJson** (full JSON body including actions that HTTP-callback a Coreflux REST server):

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "topic": "coreflux-alerts-lab",
  "message": "Garage door open > 15 min. Close it?",
  "title": "Facility alert",
  "priority": 4,
  "tags": ["warning", "door"],
  "actions": [
    {
      "action": "http",
      "label": "Ack in Coreflux",
      "url": "https://your-coreflux-rest.example/routes/ack",
      "method": "POST",
      "body": "{\"alarm\":\"door-open\"}"
    }
  ]
}
```

**GetLatest:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "topic": "coreflux-alerts-lab",
  "token": ""
}
```

**Health:** empty payload / no placeholders required.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)
* [ntfy publish](https://docs.ntfy.sh/publish/)
* [ntfy subscribe API](https://docs.ntfy.sh/subscribe/api/)
* [ntfy access control](https://docs.ntfy.sh/config/#access-control)
* [Action buttons](https://docs.ntfy.sh/publish/#action-buttons)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.