The Apprise API

Apprise allows you to send a notification to almost all of the most popular notification services available to us today such as: Telegram, Discord, Slack, Amazon SNS, Gotify, etc. This API provides a simple gateway to directly access it via an HTTP interface.

  • chevron_rightThis project was designed to be incredibly light weight.
  • chevron_rightConfiguration can be persistently stored for retrieval.

Stateless Endpoints

Those who wish to treat this API as nothing but a sidecar and/or microservice to their project only need to use the following URL.

URL Description
/notify/ Used to notify one one or more specified Apprise URLs. See the Apprise URL Builder if you need help constructing your URL(s).
Parameter Description
urls Used to define one or more Apprise URL(s). Use a comma and/or space to separate one URL from the next.
body Defines the message body. This field is required!
title The title to include in the notification. This is an optional field.
type This optional field defines the notification type. The possible options are:
  1. infoinfo - this is the default option if a type isn't specified.
  2. check_circlesuccess
  3. report_problemwarning
  4. cancelfailure
  • codeCurl Example 
    # Notifies an email address
    
                        curl -X POST -d '{"urls":"mailto://user:pass@gmail.com","body":"test body","title":"test title"}' \
    
                            -H "Content-Type: application/json" \
    
                            "https://hermod.royflix.net/notify/"
    
                        
    
                        # Notifies an email address with attachments
    
                        curl -X POST -F 'urls=mailto://user:pass@gmail.com' \
    
                            -F 'title=test title' \
    
                            -F 'body=test body' \
    
                            -F attach1=@/path/to/attachment.doc \
    
                            -F attach2=@Screenshot-2.png \
    
                            "https://hermod.royflix.net/notify/"
    # Send an web based file attachment to a Discord server:
    
                        curl -X POST -F 'urls=discord://credentials' \
    
                            -F "attach=https://raw.githubusercontent.com/caronc/apprise/master/apprise/assets/themes/default/apprise-logo.png" \
    
                            "https://hermod.royflix.net/notify/"
  • codePython Example 
    import json
    
                        from urllib.request import Request
    
                        
    
                        payload = {
    
                            'urls': 'mailto://user:pass@gmail.com',
    
                            'title': 'test title',
    
                            'body': 'test body',
    
                        }
    
                        
    # The Request
    
                        response = Request(
    
                            "https://hermod.royflix.net/notify/",
    
                            json.dumps(payload).encode('utf-8'),
    
                            {"Content-Type": "application/json"},
    
                            method='POST',
    
                        )
    # Notifies an email address with attachments
    
                        import requests

    
                        payload = {
    
                            'urls': 'mailto://user:pass@gmail.com',
    
                            'title': 'test title',
    
                            'body': 'test body',
    
                        }

    
                        with open("my/path/to/attachment.png", 'rb') as fp:
    
                            response = request.post("https://hermod.royflix.net/notify/",
    
                                data=payload,
    
                                files={'attach1':('attachment.png', fp)},
    
                            )
  • codePHP Example 
    <?php
    
                        
    
                        // The URL
    
                        $url = 'https://hermod.royflix.net/notify/';
    
                        
    
                        // Initiate cURL.
    
                        $ch = curl_init($url);
    
                        
    
                        // The JSON data.
    
                        $jsonData = array(
    
                            'urls' => 'mailto://user:pass@hotmail.com',
    
                            'title' => 'test title',
    
                            'body' => 'test body'
    
                        );
    
                        
    
                        //Encode the array into JSON.
    
                        $jsonDataEncoded = json_encode($jsonData);
    
                        
    
                        //Tell cURL that we want to send a POST request.
    
                        curl_setopt($ch, CURLOPT_POST, 1);
    
                        
    
                        //Attach our encoded JSON string to the POST fields.
    
                        curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonDataEncoded);
    
                        
    
                        //Set the content type to application/json
    
                        curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
    
                        
    
                        //Execute the request
    
                        $result = curl_exec($ch);
    
                        
    
                        // Close our handler
    
                        curl_close($ch);
    
                        ?>
    <?php
    
                        // Sending an Attachment using PHP

    
                        // The URL
    
                        $url = 'https://hermod.royflix.net/notify/';
    
                        
    
                        //Initiate cURL.
    
                        $ch = curl_init($url);
    
                        
    
                        // Prepare our File attachment
    
                        $path = '/path/to/photo.jpg';
    
                        
    
                        // Acquire our Filename
    
                        $fname = basename($path);
    
                        
    
                        // Get our attachment mime-type (in this case it's 'image/jpg')
    
                        $mimeType = mime_content_type($path);
    
                        
    
                        //The multipart data.
    
                        $data = array(
    
                            'urls' => 'mailto://user:pass@hotmail.com',
    
                            'title' => 'test title',
    
                            'body' => 'test body',
    
                            'attach1' => new CURLFile($path, $mimeType, $fname)
    
                        );
    
                        
    
                        //Tell cURL that we want to send a POST request.
    
                        curl_setopt($ch, CURLOPT_POST, 1);
    
                        
    
                        //Attach our data to the POST fields.
    
                        curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    
                        
    
                        //Execute the request
    
                        $result = curl_exec($ch);
    
                        
    
                        // Close our handler
    
                        curl_close($ch);
    
                        ?>

Persistent Store Endpoints

Those wishing to use the persistent store may do so. This section is a set it and forget it type deal. Set your configuration once and just trigger notifications later on demand with light-weight API calls.

All endpoints that expect posted data can be received in either JSON or in it's standard encoding. You must pass along the Content-Type as application/json in order for it to be interpreted properly.

URL Description
/add/444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf Used to add a new Apprise configuration or a set of URLs and associates them with configuration identified with the id of 444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf. See the Apprise URL Builder if you need help constructing your URLs.
Parameter Description
urls Used to define one or more Apprise URL(s). Use a comma and/or space to separate one URL from the next.
config Provide the contents of either a YAML or TEXT based Apprise configuration.
format This field is only required if you've specified the config option. It's purpose is to tell the server which of the supported (Apprise) configuration types you are passing. Valid options are:
  1. yaml
  2. text
  • You must specify either the urls parameter or the config.
  • The urls takes priority over the config if both were specified.
  • The format parameter is only required if the config parameter was also specified.
  • codeCurl Example 
    # Load a single URL and assign it to: 444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf
    
                            curl -X POST -d '{"urls":"mailto://user:pass@gmail.com"}' \
    
                                -H "Content-Type: application/json" \
    
                                https://hermod.royflix.net/add/444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf
    # Load a simple TEXT config entry sent to: 444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf
    
                            curl -X POST -d '{"format":"text","config":"devops=mailto://user:pass@gmail.com"}' \
    
                                -H "Content-Type: application/json" \
    
                                https://hermod.royflix.net/add/444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf/
  • codePython Example 
    import json
    
                            from urllib.request import Request
    
                            
    
                            payload = {
    
                                'urls': 'mailto://user:pass@gmail.com',
    
                            }
    
                            
    # The URL if the key was 444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf
    
                            req = Request(
    
                                "https://hermod.royflix.net/add/444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf",
    
                                json.dumps(payload).encode('utf-8'),
    
                                {"Content-Type": "application/json"},
    
                                method='POST',
    
                            )
  • codePHP Example 
    <?php
    
                            
    
                            // The URL if the key was 444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf
    
                            $url = 'https://hermod.royflix.net/add/444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf';
    
                            
    
                            //Initiate cURL.
    
                            $ch = curl_init($url);
    
                            
    
                            //The JSON data.
    
                            $jsonData = array(
    
                                'urls' => 'mailto://user:pass@hotmail.com'
    
                            );
    
                            
    
                            //Encode the array into JSON.
    
                            $jsonDataEncoded = json_encode($jsonData);
    
                            
    
                            //Tell cURL that we want to send a POST request.
    
                            curl_setopt($ch, CURLOPT_POST, 1);
    
                            
    
                            //Attach our encoded JSON string to the POST fields.
    
                            curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonDataEncoded);
    
                            
    
                            //Set the content type to application/json
    
                            curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
    
                            
    
                            //Execute the request
    
                            $result = curl_exec($ch);
    
                            
    
                            // Close our handler
    
                            curl_close($ch);
    
                            ?>
/del/444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf There are no arguments required. If configuration id of 444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf exists and has data associated with it, it will be removed.
  • codeCurl Example 
    # Remove previously loaded configuration associated with the id of 444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf
    
                          curl -X POST https://hermod.royflix.net/del/444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf
  • codePython Example 
    import json
    
                          from urllib.request import Request
    
                          
    # The request if the key was 444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf
    
                          req = Request(
    
                              "https://hermod.royflix.net/del/444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf",
    
                              json.dumps(payload).encode('utf-8'),
    
                              {"Content-Type": "application/json"},
    
                              method='POST',
    
                          )
  • codePHP Example 
    <?php
    
                          
    
                          // The URL if the key was 444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf
    
                          $url = 'https://hermod.royflix.net/del/444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf';
    
                          
    
                          //Initiate cURL.
    
                          $ch = curl_init($url);
    
                          
    
                          //Tell cURL that we want to send a POST request.
    
                          curl_setopt($ch, CURLOPT_POST, 1);
    
                          
    
                          //Execute the request
    
                          $result = curl_exec($ch);
    
                          
    
                          // Close our handler
    
                          curl_close($ch);
    
                          ?>
/get/444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf This feature can be used by Apprise itself. It provides a means of remotely fetching it's the configuration associated with the configuration identified through the id of 444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf. 
# Use Apprise to retrieve your configuration:

                    apprise --body="test message" --config=https://hermod.royflix.net/get/444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf
/cfg/444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf This is an alias of /get/444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf defined above. It provides a means of remotely fetching it's the configuration associated with the configuration identified through the id of 444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf. 
# Use Apprise to retrieve your configuration:

                    apprise --body="test message" --config=https://hermod.royflix.net/cfg/444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf
/notify/444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf Notifies the URLs associated with configuration identified by the id of 444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf.
Parameter Description
body Defines the message body. This field is required!
title The title to include in the notification. This is an optional field.
type This optional field defines the notification type. The possible options are:
  1. infoinfo - this is the default option if a type isn't specified.
  2. check_circlesuccess
  3. report_problemwarning
  4. cancelfailure
tag Apply tagging logic to the further filter your URLs. This is an optional field.
  • codeCurl Example 
    # Notifies all URLs assigned to the configuration
    
                            curl -X POST \
    
                                -F "tag=all" \
    
                                -F "body=test body" \
    
                                -F "title=test title" \
    
                                "https://hermod.royflix.net/notify/444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf"
    # Sends a notification to our endpoints with an attachment
    
                            curl -X POST \
    
                                -F "tag=all" \
    
                                -F "attach=https://raw.githubusercontent.com/caronc/apprise/master/apprise/assets/themes/default/apprise-logo.png" \
    
                                "https://hermod.royflix.net/notify/444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf"
    # Notifies all URLs assigned the devops tag
    
                            curl -X POST -d '{"tag":"devops","body":"test body","title":"test title"}' \
    
                                -H "Content-Type: application/json" \
    
                                "https://hermod.royflix.net/notify/444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf"
  • codePython Example
    Ideally you should leverage the Apprise Library, it will make your life much easier: 
    import apprise
    
                            
    
                            # Create an Apprise Instance
    
                            aobj = apprise.Apprise()
    
                            
    
                            # Add our URL
    
                            aobj.add("apprises://hermod.royflix.net/444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf")
    
                            
    
                            # Send our notification:
    
                            aobj.notify("test body", "test title")
    
                            
    
                            # Sending an attachment is just as easy:
    
                            aobj.notify("test body", "test title", attach="/path/to/file")
    The legacy (but more compatible and light weight) way of doing things: 
    import json
    
                            from urllib.request import Request
    
                            
    
                            payload = {
    
                                'tag': 'devops',
    
                                'title': 'test title',
    
                                'body': 'test body',
    
                            }
    
                            
    # The URL if the key was 444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf
    
                            req = Request(
    
                                "https://hermod.royflix.net/notify/444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf",
    
                                json.dumps(payload).encode('utf-8'),
    
                                {"Content-Type": "application/json"},
    
                                method='POST',
    
                            )
  • codePHP Example 
    <?php
    
                            
    
                            // The URL if the key was 444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf
    
                            $url = 'https://hermod.royflix.net/notify/444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf';
    
                            
    
                            //Initiate cURL.
    
                            $ch = curl_init($url);
    
                            
    
                            //The JSON data.
    
                            $jsonData = array(
    
                                'tag' => 'devops',
    
                                'title' => 'test title',
    
                                'body' => 'test body'
    
                            );
    
                            
    
                            //Encode the array into JSON.
    
                            $jsonDataEncoded = json_encode($jsonData);
    
                            
    
                            //Tell cURL that we want to send a POST request.
    
                            curl_setopt($ch, CURLOPT_POST, 1);
    
                            
    
                            //Attach our encoded JSON string to the POST fields.
    
                            curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonDataEncoded);
    
                            
    
                            //Set the content type to application/json
    
                            curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
    
                            
    
                            //Execute the request
    
                            $result = curl_exec($ch);
    
                            
    
                            // Close our handler
    
                            curl_close($ch);
    
                            ?>
    <?php
    
                            // Sending an Attachment using PHP

    
                            // The URL
    
                            $url = 'https://hermod.royflix.net/notify/444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf';
    
                            
    
                            //Initiate cURL.
    
                            $ch = curl_init($url);
    
                            
    
                            // Prepare our File attachment
    
                            $path = '/path/to/photo.jpg';
    
                            
    
                            // Acquire our Filename
    
                            $fname = basename($path);
    
                            
    
                            // Get our attachment mime-type (in this case it's 'image/jpg')
    
                            $mimeType = mime_content_type($path);
    
                            
    
                            //The multipart data.
    
                            $data = array(
    
                                'urls' => 'mailto://user:pass@hotmail.com',
    
                                'title' => 'test title',
    
                                'body' => 'test body',
    
                                'attach1' => new CURLFile($path, $mimeType, $fname)
    
                            );
    
                            
    
                            //Tell cURL that we want to send a POST request.
    
                            curl_setopt($ch, CURLOPT_POST, 1);
    
                            
    
                            //Attach our data to the POST fields.
    
                            curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
    
                            
    
                            //Execute the request
    
                            $result = curl_exec($ch);
    
                            
    
                            // Close our handler
    
                            curl_close($ch);
    
                            ?>

Endpoint Notes

The Configuration ID (444ddabce1871ae892cbc546c72390fb8fa9559ce1c8f02bb4db8cdcda1341bf) you plan to associate your configuration with:

  1. Can not have spaces and/or special characters in it. Both a dash (-) and underscore (_) are the only exceptions to this rule.
  2. Must start with at least 2 alpha/numeric characters.
  3. Can not exceed 64 characters in total length.