> ## 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.

# Apprise API

> Client-mode REST API connector for a curated Apprise API slice: health status, supported services, stateless notify with urls, stateful notify by config key, save configuration, and list URLs

Technical Preview

## Overview

A client-mode connector for a **curated messaging** slice of the [Apprise API](https://github.com/caronc/apprise-api) (Docker `caronc/apprise`), the lightweight REST wrapper around the [Apprise](https://github.com/caronc/apprise) notification library (100+ services):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST notify/\{key} | `POST /notify/{key}` | Stateful send through a saved Config ID (`title`, `body`, `type`) |
| POST notify | `POST /notify` | Stateless send with explicit `urls` list (+ `body`) |
| GET status (smoke) | `GET /status` | Health → **200** OK / JSON (or **417** on config issues) |
| GET details | `GET /details` | Supported Apprise URL schemas (`Accept: application/json`) |
| POST add/\{key} | `POST /add/{key}` | Persist URLs/config under a key |
| GET json/urls/\{key} | `GET /json/urls/{key}` | Inspect saved URLs/tags (`privacy=1` redacts secrets) |

Default `BASE_ADDRESS` placeholder is `https://apprise.example.com`. Replace with your self-hosted origin via `APPRISE_BASE_URL` (common local Docker: `http://localhost:8000`). Topics use `messaging/apprise-api/<object>/<verb>`.

> [!NOTE]
>
> Auth is **deployment-dependent**: many lab containers expose endpoints with no credentials. When the server sets `APPRISE_AUTH_REQUIRED`, use HTTP Basic (`APPRISE_USER` / `APPRISE_PASSWORD`) or per-key Basic. Prefer Hub secrets. Status remains **blocked** until a live instance smoke succeeds (`GET /status` → 200 on a reachable host).

## Basic Syntax

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — Apprise API
# BASE_ADDRESS: set from APPRISE_BASE_URL (placeholder below)
# Optional Basic Auth when APPRISE_AUTH_REQUIRED

DEFINE ROUTE AppriseApiRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://apprise.example.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT Getstatus
        WITH SOURCE_TOPIC "messaging/apprise-api/status/get"
        WITH DESTINATION_TOPIC "messaging/apprise-api/status/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/status"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Getdetails
        WITH SOURCE_TOPIC "messaging/apprise-api/details/get"
        WITH DESTINATION_TOPIC "messaging/apprise-api/details/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/details"
        WITH HEADERS
            ADD "Accept" "application/json"
    ADD EVENT Notifystateless
        WITH SOURCE_TOPIC "messaging/apprise-api/notify/stateless"
        WITH DESTINATION_TOPIC "messaging/apprise-api/notify/stateless/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/notify"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Notifybykey
        WITH SOURCE_TOPIC "messaging/apprise-api/notify/by-key"
        WITH DESTINATION_TOPIC "messaging/apprise-api/notify/by-key/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/notify/{value.json.key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Addconfiguration
        WITH SOURCE_TOPIC "messaging/apprise-api/config/add"
        WITH DESTINATION_TOPIC "messaging/apprise-api/config/add/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/add/{value.json.key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
        WITH BODY "{payload}"
    ADD EVENT Geturls
        WITH SOURCE_TOPIC "messaging/apprise-api/urls/get"
        WITH DESTINATION_TOPIC "messaging/apprise-api/urls/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/json/urls/{value.json.key}?privacy={value.json.privacy}"
        WITH HEADERS
            ADD "Accept" "application/json"
```

## Events

| Event | Method | Endpoint | Request topic | Response topic |
| - | - | - | - | - |
| Getstatus | GET | `/status` | `messaging/apprise-api/status/get` | `messaging/apprise-api/status/get/response` |
| Getdetails | GET | `/details` | `messaging/apprise-api/details/get` | `messaging/apprise-api/details/get/response` |
| Notifystateless | POST | `/notify` | `messaging/apprise-api/notify/stateless` | `messaging/apprise-api/notify/stateless/response` |
| Notifybykey | POST | `/notify/{key}` | `messaging/apprise-api/notify/by-key` | `messaging/apprise-api/notify/by-key/response` |
| Addconfiguration | POST | `/add/{key}` | `messaging/apprise-api/config/add` | `messaging/apprise-api/config/add/response` |
| Geturls | GET | `/json/urls/{key}` | `messaging/apprise-api/urls/get` | `messaging/apprise-api/urls/get/response` |

## Auth

| Mode | How |
| - | - |
| Open lab instance | No credentials; smoke with `GET /status` |
| Global Basic Auth | `APPRISE_USER` + `APPRISE_PASSWORD` (Hub `GET SECRET`) on the connector config |
| Per-key Basic | Credentials assigned to a Config ID; still use Basic header |
| Stateful key | Path `{key}` from MQTT `value.json.key` (env alias `APPRISE_KEY` / `APPRISE_CONFIG_ID`) |

Never put real passwords in the `.lot` file. Optional Basic:

```lot theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
WITH USERNAME "YOUR_APPRISE_USER"
WITH PASSWORD GET SECRET "APPRISE_PASSWORD"
```

## Example payloads

**Stateless notify** (urls in body):

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "urls": ["json://localhost"],
  "title": "Zone A",
  "body": "RMS high",
  "type": "warning"
}
```

**Stateful notify** (saved key):

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "key": "plant-alerts",
  "title": "Zone A trip",
  "body": "E-stop engaged",
  "type": "failure"
}
```

**Add configuration:**

```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "key": "plant-alerts",
  "urls": ["tgram://BOT_TOKEN/CHAT_ID/"]
}
```

## BASE\_ADDRESS

Self-hosted only — there is no shared public Apprise API tenant for Coreflux smoke:

| Env / setting | Example |
| - | - |
| `APPRISE_BASE_URL` → `BASE_ADDRESS` | `http://localhost:8000` |
| HTTPS reverse proxy | `https://apprise.your-plant.local` |
| Placeholder in package | `https://apprise.example.com` |

If you use plain HTTP, set `WITH USE_SSL "false"`.

## Server / inbound companion

This package is **client-mode first** (MQTT → HTTP to Apprise). Apprise API does not provide a general inbound webhook-to-MQTT surface for Coreflux; notification *destinations* are Apprise URLs (Slack, Telegram, email, …). If you need HTTP callbacks into the broker, use a separate `ENABLE_SERVER` companion connector (e.g. ntfy action buttons or your own webhook) — not included here.

## Deploy notes

* Deploy `AppriseApiRestApi.lot` only (no `ADD METADATA`).
* Hub catalog metadata lives in `hub-metadata.lot` (`WITH STATUS "beta"`, icon, doclink).
* Docs: [https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/apprise-api](https://docs.coreflux.org/latest/lot-language/routes/rest-api-apps/apprise-api)

## Sources

* [Apprise API](https://github.com/caronc/apprise-api)
* [OpenAPI / swagger.yaml](https://github.com/caronc/apprise-api/blob/master/swagger.yaml)
* [API Endpoints](https://appriseit.com/api/endpoints/)
* [Apprise library](https://github.com/caronc/apprise)
* Docker image `caronc/apprise`


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