API Details

Health Checks

# Request a general text response
# Output will read `OK` if everything is fine, otherwise it will return
# one or more of the following separated by a comma:
#  - ATTACH_PERMISSION_ISSUE: Can not write attachments (likely a permission issue)
#  - CONFIG_PERMISSION_ISSUE: Can not write configuration (likely a permission issue)
#  - STORE_PERMISSION_ISSUE: Can not write to persistent storage (likely a permission issue)
curl -X GET http://localhost:8000/status

curl -X GET -H "Accept: application/json" http://localhost:8000/status

{
  "attach_lock": false,
  "config_lock": false,
  "stateful_enabled": true,
  "stateless_enabled": true,
  "degraded": false,
  "max_attachments": 6,
  "attach_size": 209715200,
  "status": {
    "persistent_storage": true,
    "can_write_config": true,
    "can_write_attach": true,
    "details": ["OK"]
  }
}

• The attach_lock always cross references if the APPRISE_ATTACH_SIZE on whether or not it is 0 (zero) or less.
• config_lock reports whether this caller may view configuration content. It

• stateful_enabled and stateless_enabled report the server-wide mode

• degraded is true when both notification modes are disabled.
• max_attachments is the active APPRISE_MAX_ATTACHMENTS value.
• attach_size is the active APPRISE_ATTACH_SIZE value.
• The status.persistent_storage defines if the persistent storage is enabled or not. If the environment variable APPRISE_STORAGE_PATH is empty, this value will always read false and it will not impact the status.details
• The status.can_write_config defines if the configuration directory is writable or not. If the environment variable APPRISE_STATEFUL_MODE is set to disabled, this value will always read false and it will not impact the status.details
• The status.can_write_attach defines if the attachment directory is writable or not. If the environment variable APPRISE_ATTACH_SIZE. This value will always read false and it will not impact the status.details.
• The status.details identifies the overall status. If there is more then 1 issue to report here, they will all show in this list. In a working orderly environment, this will always be set to OK and the http response type will be 200.

Stateless Solution

# Send your notifications directly
curl -X POST -d 'urls=mailto://user:pass@gmail.com&body=test message' \
    http://localhost:8000/notify

# Send a notification with an attachment:
curl -X POST \
    -F 'urls=mailto://user:pass@gmail.com' \
    -F 'body=test message' \
    -F attach=@Screenshot-1.png \
    http://localhost:8000/notify

# Send multiple attachments; just make sure the attach keyword is unique:
curl -X POST \
    -F 'urls=mailto://user:pass@gmail.com' \
    -F 'body=test message' \
    -F attach1=@Screenshot-1.png \
    -F attach2=@/my/path/to/Apprise.doc \
    http://localhost:8000/notify

# This example shows how you can place the body among other parameters
# in the GET parameter and not the payload as another option.
curl -X POST -d 'urls=mailto://user:pass@gmail.com&body=test message' \
    -F @/path/to/your/attachment \
    http://localhost:8000/notify

# The body is not required if an attachment is provided:
curl -X POST -d 'urls=mailto://user:pass@gmail.com' \
    -F @/path/to/your/attachment \
    http://localhost:8000/notify

# Send your notifications directly using JSON
curl -X POST -d '{"urls": "mailto://user:pass@gmail.com", "body":"test message"}' \
    -H "Content-Type: application/json" \
    http://localhost:8000/notify

# attach= is an alias of attachment=
# Send a notification with a URL based attachment
curl -X POST \
    -F 'urls=mailto://user:pass@gmail.com' \
    -F attach=https://raw.githubusercontent.com/caronc/apprise/master/apprise/assets/themes/default/apprise-logo.png \
    http://localhost:8000/notify

# Use the 'attachment' parameter and send along a web request
curl -X POST \
    -F 'urls=mailto://user:pass@gmail.com' \
    -F attachment=https://i.redd.it/my2t4d2fx0u31.jpg \
    http://localhost:8000/notify

# To send more then one URL, the following would work:
curl -X POST \
    -F 'urls=mailto://user:pass@gmail.com' \
    -F attachment=https://i.redd.it/my2t4d2fx0u31.jpg \
    -F attachment=https://path/to/another/remote/file.pdf \
    http://localhost:8000/notify

# Finally feel free to mix and match local files with external ones:
curl -X POST \
    -F 'urls=mailto://user:pass@gmail.com' \
    -F attachment=https://i.redd.it/my2t4d2fx0u31.jpg \
    -F attachment=https://path/to/another/remote/file.pdf \
    -F @/path/to/your/local/file/attachment \
    http://localhost:8000/notify

Persistent (Stateful) Storage Solution

{
   "tags": ["devops", "admin", "me"],
   "urls": [
      {
         "url": "slack://TokenA/TokenB/TokenC",
         "tags": ["devops", "admin"]
      },
      {
         "url": "discord://WebhookID/WebhookToken",
         "tags": ["devops"]
      },
      {
         "url": "mailto://user:pass@gmail.com",
         "tags": ["me"]
      }
   ]
}

# Send notification(s) to a {key} defined as 'abc123'
curl -X POST -d "body=test message" \
    http://localhost:8000/notify/abc123

# Here is the same request but using JSON instead:
curl -X POST -d '{"body":"test message"}' \
    -H "Content-Type: application/json" \
    http://localhost:8000/notify/abc123

# Send attachments:
curl -X POST \
    -F 'urls=mailto://user:pass@gmail.com' \
    -F 'body=test message' \
    -F attach1=@Screenshot-1.png \
    -F attach2=@/my/path/to/Apprise.doc \
    http://localhost:8000/notify/abc123

# attach= is an alias of attachment=
# Send a notification with a URL based attachment
curl -X POST \
    -F 'urls=mailto://user:pass@gmail.com' \
    -F attach=https://raw.githubusercontent.com/caronc/apprise/master/apprise/assets/themes/default/apprise-logo.png \
    http://localhost:8000/notify/abc123

# Send notification(s) to a {KEY} defined as 'abc123'
# but only notify the URLs associated with the 'devops' tag
curl -X POST -d 'tag=devops&body=test message' \
    http://localhost:8000/notify/abc123

# Here is the same request but using JSON instead:
curl -X POST -d '{"tag":"devops", "body":"test message"}' \
    -H "Content-Type: application/json" \
    http://localhost:8000/notify/abc123

Template Values

template:
  # A default is used unless the notification supplies a value
  smtp_host: smtp.example.com
  # No default: the notification or server environment must fill this name
  api_key:

urls:
  - sendgrid://${API_KEY}:noreply@example.com/you@example.com:
      - tag: alerts

curl -X POST -H "Content-Type: application/json" \
    -d '{"tag":"alerts", "body":"test message",
         "template": {"api_key": "your-secret-key"}}' \
    http://localhost:8000/notify/abc123

curl -X POST \
    -F "tag=alerts" \
    -F "body=test message" \
    -F "template[api_key]=your-secret-key" \
    http://localhost:8000/notify/abc123

Tagging

# 'AND' Example
# Send notification(s) to a {KEY} defined as 'abc123'
# Notify the URLs associated with the 'devops' and 'after-hours' tag
# The 'space' acts as an 'AND' You can also use '+' character (in spot of the
# space to achieve the same results)
curl -X POST -d '{"tag":"devops after-hours", "body":"repo outage"}' \
    -H "Content-Type: application/json" \
    http://localhost:8000/notify/abc123


# 'OR' Example
# Send notification(s) to a {KEY} defined as 'def456'
# Notify the URLs associated with the 'dev' OR 'qa' tag
# The 'comma' acts as an 'OR'.  The whitespace around the comma is ignored (if
# defined) You can also use '+' character (in spot of the space to achieve the
# same results)
curl -X POST -d '{"tag":"dev, qa", "body":"bug #000123 is back :("}' \
    -H "Content-Type: application/json" \
    http://localhost:8000/notify/def456


# 'AND' and 'OR' Example
# Send notification(s) to a {KEY} defined as 'projectX'
# Notify the URLs associated with the 'leaders AND teamA' AND additionally
# the 'leaders AND teamB'.
curl -X POST -d '{"tag":"leaders teamA, leaders teamB", "body":"meeting now"}' \
    -H "Content-Type: application/json" \
    http://localhost:8000/notify/projectX

Live Progress Streaming

Log Detail

curl -N -X POST -d '{"tag":"devops", "body":"repo outage"}' \
    -H "Content-Type: application/json" \
    "http://localhost:8000/notify/abc123?stream=yes"

event: log
data: {"level": "INFO", "asctime": "2025-01-01 12:00:00,000", "message": "Sent to Telegram", "service": "Telegram"}

event: result
data: {"status": "SUCCESS"}

API Response Codes

API Notes

• {KEY} must be 1-128 alphanumeric characters in length. In addition to this, the underscore (_) and dash (-) are also accepted.

• Specify the Content-Type of application/json to use the JSON support otherwise the default expected format is application/x-www-form-urlencoded (whether it is specified or not).
• Authentication is disabled by default. Set APPRISE_AUTH_REQUIRED=yes to enable it; see Authentication.
• There are no additional dependencies (such as database requirements, etc) should you choose to use the optional persistent store (mounted as /config).

Environment Variables

Nginx Overrides

1. /etc/nginx/location-override.conf which is included within all of the Apprise API NginX location references.
2. /etc/nginx/server-override.conf which is included within Apprise API server reference.

Authentication

Built-in Basic Auth

docker run --name apprise \
   -p 8000:8000 \
   -v /path/to/local/config:/config \
   -e APPRISE_AUTH_REQUIRED=yes \
   -e APPRISE_USER=foobar \
   -e APPRISE_PASSWORD=your-password-here \
   caronc/apprise:latest

Per-Configuration Access

# Set (or replace) a password just for this one configuration ID.
# The very first time requires the global credentials:
curl -X POST -H "Content-Type: application/json" \
   -u foobar:your-password-here \
   -d '{"access": "locked", "username": "alice", "password": "s3cret"}' \
   http://localhost:8000/auth/my-config-id

# Make tagged notifications public. Credentials are optional in this mode.
curl -X POST -H "Content-Type: application/json" \
   -u foobar:your-password-here \
   -d '{"access": "public"}' \
   http://localhost:8000/auth/my-public-config

# Public callers need the Config ID and a specific tag.
curl -X POST -d 'body=test message' -d 'tag=customers' \
   http://localhost:8000/notify/my-public-config

# Freeze this account while preserving its configuration and credentials.
curl -X POST -H "Content-Type: application/json" \
   -u foobar:your-password-here \
   -d '{"access": "disabled"}' \
   http://localhost:8000/auth/my-config-id

# Replace it with the key's current credentials:
curl -X POST -H "Content-Type: application/json" \
   -u alice:s3cret \
   -d '{"username": "alice", "password": "new-password"}' \
   http://localhost:8000/auth/my-config-id

# Remove it as the global administrator (the configuration is untouched):
curl -X DELETE -u foobar:your-password-here http://localhost:8000/auth/my-config-id

Moving a Configuration

# Move 'my-config-id' to 'my-new-config-id' using that key's own credentials:
curl -X POST -H "Content-Type: application/json" \
   -u alice:s3cret \
   -d '{"to": "my-new-config-id"}' \
   http://localhost:8000/move/my-config-id

# The same, performed by a global administrator:
curl -X POST -H "Content-Type: application/json" \
   -u foobar:your-password-here \
   -d '{"to": "my-new-config-id"}' \
   http://localhost:8000/move/my-config-id

Reverse-proxy (NginX) Basic Auth

# Our override.conf file:
auth_basic            "Apprise API Restricted Area";
auth_basic_user_file  /etc/nginx/.htpasswd;

# Create ourselves a for our user 'foobar'; the below will prompt you for the pass
# you want to provide:
htpasswd -c apprise_api.htpasswd foobar

# Note: the -c above is only needed to create the database for the first time

# Pre-create the paths you will mount to
mkdir -p /path/to/local/{attach,config,plugin}

# Create our container containing Basic Auth:
docker run --name apprise \
   -p 8000:8000 \
   --user "$(id -u):$(id -g)" \
   -v /path/to/local/config:/config \
   -v /path/to/local/attach:/attach \
   -v /path/to/local/plugin:/plugin \
   -v ./override.conf:/etc/nginx/location-override.conf:ro \
   -v ./apprise_api.htpasswd:/etc/nginx/.htpasswd:ro \
   -e APPRISE_STATEFUL_MODE=simple \
   -e APPRISE_WORKER_COUNT=1 \
   -e APPRISE_DEFAULT_FORMAT=text \
   -e TZ=America/Toronto \
   -d caronc/apprise:latest

# Add another account
htpasswd apprise_api.htpasswd user2

Pruning

# From inside the running container:
docker exec -it apprise python manage.py prune
docker exec -it apprise python manage.py storeprune --days 30
docker exec -it apprise python manage.py authprune --seconds 2592000

Kubernetes

Example Kubernetes Deployment

apiVersion: v1
kind: Namespace
metadata:
  labels:
    name: apprise
  name: apprise
---
apiVersion: v1
kind: ConfigMap
metadata:
  labels:
    name: apprise
  name: apprise-api-override-conf-config
  namespace: apprise
data:
  location-override.conf: |
    auth_basic            "Apprise API Restricted Area";
    auth_basic_user_file  /etc/nginx/.htpasswd;
---
apiVersion: v1
kind: Secret
metadata:
  labels:
    name: apprise
  name: apprise-api-htpasswd-secret
  namespace: apprise
data:
  .htpasswd: <base64_encoded> # add output of: htpasswd -c apprise_api.htpasswd <USERNAME> && cat apprise_api.htpasswd | base64
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  labels:
    name: apprise
  name: apprise-data
  namespace: apprise
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
---
apiVersion: v1
kind: Service
metadata:
  labels:
    name: apprise
  name: apprise
  namespace: apprise
spec:
  ports:
  - name: http
    port: 80
    protocol: TCP
    targetPort: 8000
  selector:
    name: apprise
  type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    name: apprise
  name: apprise
  namespace: apprise
spec:
  replicas: 1
  selector:
    matchLabels:
      name: apprise
  strategy:
    type: Recreate
  template:
    metadata:
      labels:
        name: apprise
    spec:
      containers:
        - env:
            - name: APPRISE_STATEFUL_MODE
              value: simple
            - name: PGID
              value: "1000"
            - name: PUID
              value: "1000"
            - name: TZ
              value: America/Toronto
          image: caronc/apprise:1.1
          name: apprise
          ports:
            - containerPort: 8000
              protocol: TCP
          resources:
            limits:
              cpu: "500m"
              memory: "512Mi"
            requests:
              cpu: "250m"
              memory: "128Mi"
          volumeMounts:
            - mountPath: /config
              name: apprise-data
            - mountPath: /plugin
              name: apprise-data
            - mountPath: /attach
              name: apprise-data
            # the following mountPath can be removed if not wanted/used
            - mountPath: /etc/nginx/.htpasswd
              name: apprise-api-htpasswd-secret-volume
              readOnly: true
              subPath: .htpasswd
            # the following mountPath can be removed if not wanted/used
            - mountPath: /etc/nginx/location-override.conf
              name: apprise-api-override-conf-config-volume
              readOnly: true
              subPath: location-override.conf
      restartPolicy: Always
      volumes:
        - name: apprise-data
          persistentVolumeClaim:
            claimName: apprise-data
        # the following volume can be removed if not wanted/used
        - name: apprise-api-htpasswd-secret-volume
          secret:
            secretName: apprise-api-htpasswd-secret
        # the following volume can be removed if not wanted/used
        - name: apprise-api-override-conf-config-volume
          configMap:
            name: apprise-api-override-conf-config

Hardened Kubernetes deployment (rootless and read only)

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: apprise
  name: apprise
  namespace: apprise
spec:
  replicas: 1
  selector:
    matchLabels:
      app: apprise
  template:
    metadata:
      labels:
        app: apprise
    spec:
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000
        fsGroup: 1000
        readOnlyRootFilesystem: true
      containers:
        - name: apprise
          image: caronc/apprise:latest
          imagePullPolicy: IfNotPresent
          securityContext:
            allowPrivilegeEscalation: false
            capabilities:
              drop: ["ALL"]
          env:
            - name: APPRISE_STATEFUL_MODE
              value: simple
            - name: APPRISE_WORKER_COUNT
              value: "1"
            - name: TZ
              value: America/Toronto
          ports:
            - containerPort: 8000
              name: http
          volumeMounts:
            # Persistent data
            - name: config
              mountPath: /config
            - name: plugin
              mountPath: /plugin
            - name: attach
              mountPath: /attach

            # Ephemeral runtime and temp files
            - name: tmp
              mountPath: /tmp

      volumes:
        - name: config
          persistentVolumeClaim:
            claimName: apprise-config
        - name: plugin
          persistentVolumeClaim:
            claimName: apprise-plugin
        - name: attach
          persistentVolumeClaim:
            claimName: apprise-attach

        # The deployment mounts /tmp as an in-memory emptyDir, which is where nginx,
        # gunicorn, and supervisord store pids, sockets, and temporary files.
        # This is configured as an ephemeral volume, stored in memory.
        - name: tmp
          emptyDir:
            medium: Memory

Development Environment

Bare Metal

# Start the development server in debug mode:
tox -e runserver
# Then visit: http://localhost:8000/

# If you want to run on a different port:
tox -e runserver -- "localhost:8080"
# Then visit: http://localhost:8000/

# You can also bind it to all of your interfaces like so:
tox -e runserver -- "0.0.0.0:8080"

tox -e runserver -- --branch=1341-retries-and-priorities

Docker Compose for Development

# Pre-create the paths you will mount to
mkdir -p attach config plugin

PUID=$(id -u) PGID=$(id -g) docker compose up

Quality Assurance and Testing (via Tox)

# Run unit tests
tox -e test

# Test structure; calls ruff under the hood
tox -e lint

tox -e test,lint

tox -e format

Manual Tools (optional)

# Run unit tests manually (if needed)
pytest apprise_api

# Lint code with Ruff
ruff check .

# Format code with Ruff
ruff format .

Apprise Integration

# install apprise into your environment
pip install apprise

Apprise CLI Pull Example

# A simple example of the Apprise CLI
# pulling down previously stored configuration
apprise -vvv --body="test message" \
   --config=http://localhost:8000/get/{KEY}

# Linux users can place this in ~/.apprise
# Windows users can place this info in %APPDATA%/Apprise/apprise

# Swap {KEY} with your apprise key you configured on your API
import http://localhost:8000/get/{KEY}

# Configuration is automatically loaded from our server.
apprise -vvv --body="my notification"

# Configuration is automatically loaded from our server.
apprise -vvv --tag=devops \
   --body="Tell James GitLab is down again."

# Swap {KEY} with your apprise key you configured on your API
apprise -vvv --body="There are donut's in the front hall if anyone wants any" \
   apprise://localhost:8000/{KEY}

# Linux users can place this in ~/.apprise
# Windows users can place this info in %APPDATA%/Apprise/apprise

# Swap {KEY} with your apprise key you configured on your API
devteam=apprise://localhost:8000/{KEY}?tags=devteam

# the only catch is you need to map your tags on the local server to the tags
# you want to pass upstream to your Apprise server using this method.
# In the above we tied the local keyword `devteam` to the apprise server using the tag `devteam`

# Trigger our service:
apprise -vvv --tag=devteam \
    --body="Guys, don't forget about the audit tomorrow morning."

AppriseConfig() Pull Example

import apprise

# Point our configuration to this API server:
config = apprise.AppriseConfig()

# A locked server requires global administrator credentials for this request.
# Other callers can use an apprise:// URL to send through the saved configuration.
config.add('http://localhost:8000/get/{KEY}')

# Create our Apprise Instance
a = apprise.Apprise()

# Store our new configuration
a.add(config)

# Send a test message
a.notify('test message')

Third Party Webhook Support

{
    "body": "Message body"
}

{
   "subject": "My Title",
   "payload": "My Body"
}

# Note the keyword arguments prefixed with a `:` (colon).   These
# instruct the API to map the payload (which we may not have control over)
# to align with what the Apprise API expects.
#
# We also convert `subject` to `title` too:
curl -X POST \
    -F "subject=Mesage Title" \
    -F "payload=Message Body" \
    "http://localhost:8000/notify/{KEY}?:subject=title&:payload=body"

# We also convert `subject` to `title` too:
curl -X POST -d '{"href": "mailto://user:pass@gmail.com", "subject":"My Title", "payload":"Body"}' \
    -H "Content-Type: application/json" \
    "http://localhost:8000/notify/{KEY}?:subject=title&:payload=body&:href=urls"

1. :existing_key=expected_key: Rename an existing (expected) payload key to one Apprise expects
2. :existing_key=: By setting no value, the existing key is simply removed from the payload entirely
3. :expected_key=A value to give it: You can also fix an expected apprise key to a pre-generated string value.

Nested / Subfield Mapping

# Payload sent by the third-party tool:
# {
#   "event":     { "title": "CPU spike", "state": "critical" },
#   "component": { "name": "web-server-01" }
# }
#
# Map nested fields to the flat Apprise fields:
curl -X POST \
    -H "Content-Type: application/json" \
    -d '{"event":{"title":"CPU spike","state":"critical"},"component":{"name":"web-server-01"}}' \
    "http://localhost:8000/notify/{KEY}?:event.title=title&:event.state=type&:component.name=body"

# Payload from a forum / project-management webhook (e.g. Scoold / Para):
# {
#   "items": [ { "title": "New post", "objectURI": "https://example.com/q/1234" } ]
# }
curl -g -X POST \
    -H "Content-Type: application/json" \
    -d '{"items":[{"title":"New post","objectURI":"https://example.com/q/1234"}]}' \
    "http://localhost:8000/notify/{KEY}?:items[0].title=title&:items[0].objectURI=body"

Metrics Collection & Analysis

OpenAPI / Swagger Specification

docker compose -f docker-compose.swagger.yml up -d
# Then browse to:
#   http://localhost:8001

Want To Learn More?

• 🌎 Apprise API/Web Interface
• 🛠️ Development API
• ⚙️ Configuration File Help
• ⚡ Create Your Own Custom Notifications
• 📣 Using the CLI
• 📖 Apprise Documentation Source
• 🔧 Troubleshooting
• 🎉 Showcase

• 💡 Contribute to the Apprise Code Base
• ❤️ Sponsorship and Donations