{% extends 'base.html' %} {% load i18n %} {% block body %}

{% trans "The Apprise API" %}

{% blocktrans %} 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.{% endblocktrans %}

{% trans "Stateless Endpoints" %}

{% blocktrans %}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.{% endblocktrans %}

{% trans "URL" %} {% trans "Description" %}
/notify/ {% blocktrans %}Used to notify one one or more specified Apprise URLs. See the Apprise Wiki if you need help constructing your URL(s).{% endblocktrans %}
{% trans "Parameter" %} {% trans "Description" %}
urls {% blocktrans %}Used to define one or more Apprise URL(s). Use a comma and/or space to separate one URL from the next.{% endblocktrans %}
body {% blocktrans %}Defines the message body. This field is required!{% endblocktrans %}
title {% blocktrans %}The title to include in the notification. This is an optional field.{% endblocktrans %}
type {% blocktrans %}This optional field defines the notification type. The possible options are:{% endblocktrans %}
  1. info{% trans "info" %} - {% blocktrans %}this is the default option if a type isn't specified.{% endblocktrans %}
  2. check_circle{% trans "success" %}
  3. report_problem{% trans "warning" %}
  4. cancel{% trans "failure" %}
  • codecurl example
    
								    # {% blocktrans %}Notifies an email address{% endblocktrans %}
    
								    curl -X POST -d '{"urls":"mailto://user:pass@gmail.com","body":"test body","title":"test title"}' \
    
										    -H "Content-Type: application/json" \
    
										    http://localhost:8000/notify/
  • codepython example
    
                    import json
    
                    from urllib.request import Request
    
                    
    
                    payload = {
    
                        'urls': 'mailto://user:pass@gmail.com',
    
                        'title': 'test title',
    
                        'body': 'test body',
    
                    }
    
                    
    # The URL
    
                    req = Request(
    
                        "http://localhost:8000/notify/",
    
                        json.dumps(payload).encode('utf-8'),
    
                        {"Content-Type": "application/json"},
    
                        method='POST',
    
                   )
  • codephp example
    <?php
    
                  
    
                  // The URL
    
                  $url = 'http://localhost:8000/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);

{% trans "Persistent Store Endpoints" %}

{% blocktrans %}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.{% endblocktrans %}

{% blocktrans %}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.{% endblocktrans %}

{% trans "URL" %} {% trans "Description" %}
/add/{% trans "KEY" %} {% blocktrans %}Used to add a new Apprise configuration or a set of URLs and associates them with the specified KEY. See the Apprise Wiki if you need help constructing your URLs.{% endblocktrans %}
{% trans "Parameter" %} {% trans "Description" %}
urls {% blocktrans %}Used to define one or more Apprise URL(s). Use a comma and/or space to separate one URL from the next.{% endblocktrans %}
config {% blocktrans %}Provide the contents of either a YAML or TEXT based Apprise configuration.{% endblocktrans %}
format {% blocktrans %}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:{% endblocktrans %}
  1. {% trans "yaml" %}
  2. {% trans "text" %}
  • {% blocktrans %}You must specify either the urls parameter or the config.{% endblocktrans %}
  • {% blocktrans %}The urls takes priority over the config if both were specified.{% endblocktrans %}
  • {% blocktrans %}The format parameter is only required if the config parameter was also specified.{% endblocktrans %}
  • codecurl example
    
								    # {% blocktrans %}Load a single URL and assign it to the KEY of abc123{% endblocktrans %}
    
								    curl -X POST -d '{"urls":"mailto://user:pass@gmail.com"}' \
    
										    -H "Content-Type: application/json" \
    
										    http://localhost:8000/add/abc123
    
						        # {% blocktrans %}Load a simple TEXT config entry KEY abc123{% endblocktrans %}
    
										curl -X POST -d '{"format":"text","config":"devops=mailto://user:pass@gmail.com"}' \
    
										    -H "Content-Type: application/json" \
    
										    http://localhost:8000/add/abc123/
  • codepython example
    
                        import json
    
                        from urllib.request import Request
    
                        
    
                        payload = {
    
                            'urls': 'mailto://user:pass@gmail.com',
    
                        }
    
                        
    # The URL if the key was abc123
    
                        req = Request(
    
                            "http://localhost:8000/add/abc123",
    
                            json.dumps(payload).encode('utf-8'),
    
                            {"Content-Type": "application/json"},
    
                            method='POST',
    
                       )
  • codephp example
    <?php
    
                        
    
                        // The URL if the key was abc123
    
                        $url = 'http://localhost:8000/add/abc123';
    
                        
    
                        //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);
/del/{% trans "KEY" %} {% blocktrans %}There are no arguments required. If the KEY exists and has data associated with it, it will be removed.{% endblocktrans %}
  • codecurl example
    
								    # {% blocktrans %}Remove previously loaded configuration associated with the KEY of abc123{% endblocktrans %}
    
								    curl -X POST http://localhost:8000/del/abc123
  • codepython example
    
                      import json
    
                      from urllib.request import Request
    
                      
    # The request if the key was abc123
    
                      req = Request(
    
                          "http://localhost:8000/del/abc123",
    
                          json.dumps(payload).encode('utf-8'),
    
                          {"Content-Type": "application/json"},
    
                          method='POST',
    
                     )
  • codephp example
    <?php
    
                      
    
                      // The URL if the key was abc123
    
                      $url = 'http://localhost:8000/del/abc123';
    
                      
    
                      //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);
/get/{% trans "KEY" %} {% blocktrans %}This feature can be used by Apprise itself. It provides a means of remotely fetching it's configuration.{% endblocktrans %}
# Use Apprise to retrieve your configuration:

                apprise --body="test message" --config={{ request.scheme }}://{{request.META.HTTP_HOST}}{{ request.path }}{% trans "KEY" %}
/notify/{% trans "KEY" %} {% blocktrans %}Notifies the URLs associated with the specified KEY.{% endblocktrans %}
{% trans "Parameter" %} {% trans "Description" %}
body {% blocktrans %}Defines the message body. This field is required!{% endblocktrans %}
title {% blocktrans %}The title to include in the notification. This is an optional field.{% endblocktrans %}
type {% blocktrans %}This optional field defines the notification type. The possible options are:{% endblocktrans %}
  1. info{% trans "info" %} - {% blocktrans %}this is the default option if a type isn't specified.{% endblocktrans %}
  2. check_circle{% trans "success" %}
  3. report_problem{% trans "warning" %}
  4. cancel{% trans "failure" %}
tags {% blocktrans %}Apply tagging logic to the further filter your URLs. This is an optional field.{% endblocktrans %}
  • codecurl example
    
								    # {% blocktrans %}Notifies all URLs assigned the devops tag{% endblocktrans %}
    
								    curl -X POST -d '{"tags":"devops","body":"test body","title":"test title"}' \
    
										    -H "Content-Type: application/json" \
    
										    http://localhost:8000/notify/KEY
  • codepython example
    
                        import json
    
                        from urllib.request import Request
    
                        
    
                        payload = {
    
                            'tags': 'devops',
    
                            'title': 'test title',
    
                            'body': 'test body',
    
                        }
    
                        
    # The URL if the key was abc123
    
                        req = Request(
    
                            "http://localhost:8000/notify/abc123",
    
                            json.dumps(payload).encode('utf-8'),
    
                            {"Content-Type": "application/json"},
    
                            method='POST',
    
                       )
  • codephp example
    <?php
    
                      
    
                      // The URL if the key was abc123
    
                      $url = 'http://localhost:8000/notify/abc123';
    
                      
    
                      //Initiate cURL.
    
                      $ch = curl_init($url);
    
                       
    
                      //The JSON data.
    
                      $jsonData = array(
    
                          'tags' => '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);

{% trans "Endpoint Notes" %}

The KEY 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.

{% endblock %}