Apprise API, a REST gateway in front of the Apprise library

One endpoint for many notification services

The design starts with Apprise itself, which provides one consistent notification interface for applications, automation and infrastructure. You generate an Apprise URL, pass it to the library, and the message goes to whichever service that URL describes. The library is a Python package, which means any script that can import it can send notifications, but it also means every application has to carry the dependency, build the URLs and know the service syntax. Apprise API is the network shaped version of that. It is described as a lightweight REST framework that wraps the Apprise notification library, and the README puts the benefit plainly: send notifications to more than 150 services, through a gateway, from anywhere that speaks HTTP. The audience is an operations team or a home lab operator with a dozen scripts and a handful of phones, who wants a single endpoint to point at rather than a library in every project.

The configuration manager is the same API, made visible

There is a small built-in Configuration Manager, reachable through a web browser, and the README walks through its three tabs. You create and save as many configurations as you like, and each one is identified by a Configuration ID that you choose yourself. The Review tab shows the Apprise URLs loaded from a configuration and the tags associated with them, and it lets you pick which tags to target for a test notification. The Notification tab sends a test message to one service or to several, and it accepts tag selection as well, so a test can be aimed at a subset. There is a special tag named all that notifies every configured service regardless of what tag it was otherwise given. The README is clear about the relationship between this interface and the API: the GUI is simply a user friendly interface to the same API that developers can call directly, which is the right design for a tool whose users split into operators and integrators.

Four mount points decide where your data lives

The container image is organised around four paths, and the README comments in the run command explain each one. The /config path is where configuration files are written through the API, with the internal persistent store under /config/store so a single /config volume is enough. The /plugin path is where you can drop your own custom Apprise plugins, and it is optional. The /attach path holds file attachments. The /tmp path is for temporary files and is described as suitable for tmpfs in hardened deployments. The image also sets three environment variables for these locations, APPRISE_CONFIG_DIR, APPRISE_ATTACH_DIR and APPRISE_PLUGIN_PATHS, while the compose example adds APPRISE_STATEFUL_MODE. The run command comments explain that setting the stateful mode to simple maps a defined key straight to a file found in the /config path, which the README suggests is sometimes the ideal expectation in simple home configurations. The compose file mounts /config, /plugin and /attach from the host.

Starting it and reaching the API

The documented install path is the published container image, and the API is then available at the local port 8000.

# Retrieve container
docker pull caronc/apprise:latest

# Start it up:
docker run --name apprise \
   -p 8000:8000 \
   --user "$(id -u):$(id -g)"

The user flag is worth a second look, because the README comments explain that it overrides the default user id of 1000 so the container runs as the user who started it, and that files written into the mounted volumes then belong to that user rather than to root. The compose file shows the same service with its environment set.

services:
  apprise:
    image: caronc/apprise:latest
    container_name: apprise
    ports:
      - "8000:8000"
    environment:
      APPRISE_STATEFUL_MODE: simple
      APPRISE_WORKER_COUNT: "1"
      APPRISE_DEFAULT_FORMAT: "text"
      TZ: America/Toronto

    volumes:
      - ./config:/config
      - ./plugin:/plugin
      - ./attach:/attach

The worker count is set to one in that example, and the README describes the run command as overriding a full production environment setting, which tells you the image ships a multi-worker default that the compose example deliberately lowers.

Django, gevent and gunicorn under the hood

The packaging metadata gives the server stack away. The project is a Django application, with the requirement django < 7 carrying a comment that language selection relies on a Django internal and that the bound should be raised only after testing a new major. gevent and gunicorn[gevent] handle concurrency, with a comment in requirements.txt noting that newer gunicorn releases no longer pull gunicorn in as a base dependency. django-prometheus is included for metrics. The repository matches that stack: there is a manage.py, a tox.ini, dev-requirements.txt, a swagger.yaml describing the API surface, and separate compose files for a Swagger UI and an override. The Dockerfile adds more. It starts from python:3.14-slim, installs nginx, tzdata, curl, sed and git, installs the Python requirements along with gunicorn and supervisor, and copies the static content into the nginx document root at /usr/share/nginx/html/s, so the container is an nginx plus a Python application rather than a single process. It also compiles the translations for both the API and Apprise itself during the build, with a comment noting that without that step every language quietly falls back to English.

Notification channels that go beyond HTTP webhooks

The requirements file is where the Apprise URL space becomes visible, because each optional dependency buys a family of URLs. requests provides webhook support, which is the common case. paho-mqtt covers MQTT, gntp covers the Apple Growl notification protocol, and cryptography and PGPy together provide the Pretty Good Privacy support behind mailto:// and deltachat:// addresses, as the comments say. smpplib provides smpp://, and slixmpp provides xmpp://. That list is the reason the API is worth running as a shared service rather than embedding. A single application that only needs email can import Apprise and stop there, but an infrastructure team that wants to notify over MQTT to a broker, over SMPP to a carrier gateway and over XMPP to a chat server has a long dependency list, and this service holds it in one place. The trade is that the message now travels over the network to a service that holds credentials for every destination, which is a different security posture from a library call inside the process that sends the message.

Reaching the API from a phone, and what it means for exposure

Apprise Mobile is the Android companion application, and the README is precise about its role. It sends a message, photo or file to one destination, a group or every destination, and it requires access to your running Apprise API server, so it is not a standalone notification service. Connecting is done through the Configuration Manager, where a configuration exposes an Apprise Mobile Quick Setup QR code that the app scans, which adds the server and loads that configuration in one step. The Android app is a Play Store listing under its own package, separate from this repository. The same feature is the strongest argument for putting the API on a network the phone can reach, and it is also the sharpest operational risk in the project. The README's own examples publish port 8000 on all interfaces, and the documentation in the repository does not describe an authentication layer, so a deployment that exposes the service beyond a trusted network has to answer that question itself, with a reverse proxy or a private network. The delivery report and URL builder screens in the app also mean the server holds and returns the configuration, including service URLs that often embed credentials.

Editorial conclusion

Apprise API fits an infrastructure team that wants one notification endpoint for many services, several applications pointing at it, and a browser based place to create and test configurations and tags, and it fits a home lab operator who would rather run a container than add a library to every script. It does not fit a single application that can import Apprise directly, because a network hop and a shared service are extra moving parts, and it does not fit a deployment where the notification endpoint may be reachable by untrusted callers, since the README's examples publish port 8000 without describing an authentication layer. Verify three things first: that the volume layout you mount matches the /config, /plugin and /attach paths the image expects, whether you need stateful mode at all or the stateless mode is enough, and what protects the API in your network before you publish the port.

Frequently asked questions

Official sources

1. caronc/apprise-api on GitHub
2. License: MIT
3. Project website
4. README
5. Releases