mirror of
https://github.com/caronc/apprise-api.git
synced 2024-12-15 03:11:14 +01:00
498 lines
24 KiB
HTML
498 lines
24 KiB
HTML
{% extends 'base.html' %}
|
|
{% load i18n %}
|
|
{% block body %}
|
|
<h4>{% trans "The Apprise API" %}</h4>
|
|
<p>
|
|
{% blocktrans %}
|
|
<a target="_blank" href="https://github.com/caronc/apprise">Apprise</a> allows you to send a notification to almost
|
|
all of the most popular notification services available to us today such as: <em>Telegram</em>, <em>Discord</em>,
|
|
<em>Slack</em>, <em>Amazon SNS</em>, <em>Gotify</em>, etc.
|
|
This API provides a simple gateway to directly access it via an HTTP interface.{% endblocktrans %}
|
|
<ul>
|
|
<li><i class="tiny material-icons">chevron_right</i>{% blocktrans %}This project was designed to be incredibly light
|
|
weight.{% endblocktrans %}</li>
|
|
<li><i class="tiny material-icons">chevron_right</i>{% blocktrans %}Configuration can be persistently stored for
|
|
retrieval.{% endblocktrans %}</li>
|
|
</ul>
|
|
</p>
|
|
|
|
<div class="section">
|
|
<h4>{% trans "Stateless Endpoints" %}</h4>
|
|
<p>{% blocktrans %}Those who wish to treat this API as nothing but a <a
|
|
href="https://docs.microsoft.com/en-us/azure/architecture/patterns/sidecar" target="_blank">sidecar</a> and/or
|
|
microservice to their project only need to use the following URL.{% endblocktrans %}</p>
|
|
<table class="highlighted">
|
|
<thead>
|
|
<tr>
|
|
<th>{% trans "URL" %}</th>
|
|
<th>{% trans "Description" %}</th>
|
|
</tr>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<tr>
|
|
<td><code>/notify/</code></td>
|
|
<td>
|
|
{% blocktrans %}Used to notify one one or more specified Apprise URLs. See the <a target="_blank"
|
|
href="https://github.com/caronc/apprise/wiki#notification-services">Apprise Wiki</a> if you need help
|
|
constructing your URL(s).{% endblocktrans %}
|
|
<div class="section">
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>{% trans "Parameter" %}</th>
|
|
<th>{% trans "Description" %}</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>urls</td>
|
|
<td>{% blocktrans %}Used to define one or more Apprise URL(s). Use a comma and/or space to separate
|
|
one URL from the next.{% endblocktrans %}</td>
|
|
</tr>
|
|
<tr>
|
|
<td>body</td>
|
|
<td>{% blocktrans %}Defines the message body. This field is required!{% endblocktrans %}</td>
|
|
</tr>
|
|
<tr>
|
|
<td>title</td>
|
|
<td>{% blocktrans %}The title to include in the notification. This is an optional
|
|
field.{% endblocktrans %}
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>type</td>
|
|
<td>{% blocktrans %}This optional field defines the notification type. The possible options
|
|
are:{% endblocktrans %}
|
|
<ol>
|
|
<li><i class="tiny material-icons" style="color: blue">info</i><code>{% trans "info" %}</code> -
|
|
<i>{% blocktrans %}this is the default option if a type
|
|
isn't
|
|
specified.{% endblocktrans %}</i></li>
|
|
<li><i class="tiny material-icons"
|
|
style="color: green">check_circle</i><code>{% trans "success" %}</code></li>
|
|
<li><i class="tiny material-icons"
|
|
style="color: orange">report_problem</i><code>{% trans "warning" %}</code></li>
|
|
<li><i class="tiny material-icons" style="color: red">cancel</i><code>{% trans "failure" %}</code>
|
|
</li>
|
|
</ol>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<ul class="collapsible">
|
|
<li>
|
|
<div class="collapsible-header"><i class="material-icons">code</i>curl example</div>
|
|
<div class="collapsible-body">
|
|
<pre><code class="bash">
|
|
# {% blocktrans %}Notifies an email address{% endblocktrans %}<br/>
|
|
curl -X POST -d '{"urls":"mailto://user:pass@gmail.com","body":"test body","title":"test title"}' \<br/>
|
|
-H "Content-Type: application/json" \<br/>
|
|
http://localhost:8000/notify/</code></pre>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<div class="collapsible-header"><i class="material-icons">code</i>python example</div>
|
|
<div class="collapsible-body">
|
|
<pre><code class="python">
|
|
import json<br/>
|
|
from urllib.request import Request<br/>
|
|
<br/>
|
|
payload = {<br/>
|
|
'urls': 'mailto://user:pass@gmail.com',<br/>
|
|
'title': 'test title',<br/>
|
|
'body': 'test body',<br/>
|
|
}<br/>
|
|
<br/># The URL<br/>
|
|
req = Request(<br/>
|
|
"http://localhost:8000/notify/",<br/>
|
|
json.dumps(payload).encode('utf-8'),<br/>
|
|
{"Content-Type": "application/json"},<br/>
|
|
method='POST',<br/>
|
|
)
|
|
</code></pre>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<div class="collapsible-header"><i class="material-icons">code</i>php example</div>
|
|
<div class="collapsible-body">
|
|
<pre><code class="php"><?php<br/>
|
|
<br/>
|
|
// The URL<br/>
|
|
$url = 'http://localhost:8000/notify/';<br/>
|
|
<br/>
|
|
//Initiate cURL.<br/>
|
|
$ch = curl_init($url);<br/>
|
|
<br/>
|
|
//The JSON data.<br/>
|
|
$jsonData = array(<br/>
|
|
'urls' => 'mailto://user:pass@hotmail.com',<br/>
|
|
'title' => 'test title',<br/>
|
|
'body' => 'test body'<br/>
|
|
);<br/>
|
|
<br/>
|
|
//Encode the array into JSON.<br/>
|
|
$jsonDataEncoded = json_encode($jsonData);<br/>
|
|
<br/>
|
|
//Tell cURL that we want to send a POST request.<br/>
|
|
curl_setopt($ch, CURLOPT_POST, 1);<br/>
|
|
<br/>
|
|
//Attach our encoded JSON string to the POST fields.<br/>
|
|
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonDataEncoded);<br/>
|
|
<br/>
|
|
//Set the content type to application/json<br/>
|
|
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));<br/>
|
|
<br/>
|
|
//Execute the request<br/>
|
|
$result = curl_exec($ch);
|
|
</code></pre>
|
|
</div>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<div class="section">
|
|
<h4>{% trans "Persistent Store Endpoints" %}</h4>
|
|
<p>{% 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 %}</p>
|
|
<p>{% blocktrans %}All endpoints that expect posted data can be received in either JSON or in it's standard
|
|
encoding.
|
|
You must pass along the <code>Content-Type</code> as <code>application/json</code> in order for it to be
|
|
interpreted
|
|
properly.{% endblocktrans %}</p>
|
|
|
|
<table class="highlighted">
|
|
<thead>
|
|
<tr>
|
|
<th>{% trans "URL" %}</th>
|
|
<th>{% trans "Description" %}</th>
|
|
</tr>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<tr>
|
|
<td><code>/add/<em>{% trans "KEY" %}</em></code></td>
|
|
<td>
|
|
{% blocktrans %}Used to add a new Apprise configuration or a set of URLs and associates them with the
|
|
specified <em>KEY</em>. See the <a target="_blank"
|
|
href="https://github.com/caronc/apprise/wiki#notification-services">Apprise Wiki</a> if you need help
|
|
constructing your URLs.{% endblocktrans %}
|
|
<div class="section">
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>{% trans "Parameter" %}</th>
|
|
<th>{% trans "Description" %}</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>urls</td>
|
|
<td>{% blocktrans %}Used to define one or more Apprise URL(s). Use a comma and/or space to separate
|
|
one URL from the next.{% endblocktrans %}</td>
|
|
</tr>
|
|
<tr>
|
|
<td>config</td>
|
|
<td>{% blocktrans %}Provide the contents of either a YAML or TEXT based Apprise
|
|
configuration.{% endblocktrans %}</td>
|
|
</tr>
|
|
<tr>
|
|
<td>format</td>
|
|
<td>{% 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 %}
|
|
<ol>
|
|
<li><code>{% trans "yaml" %}</code></li>
|
|
<li><code>{% trans "text" %}</code></li>
|
|
</ol>
|
|
<ul>
|
|
<li>{% blocktrans %}You must specify either the <code>urls</code> parameter or the
|
|
<code>config</code>.{% endblocktrans %}</li>
|
|
<li>{% blocktrans %}The <code>urls</code> takes priority over the <code>config</code> if both
|
|
were
|
|
specified.{% endblocktrans %}</li>
|
|
<li>{% blocktrans %}The <code>format</code> parameter is only required if the
|
|
<code>config</code>
|
|
parameter was also specified.{% endblocktrans %}</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<ul class="collapsible">
|
|
<li>
|
|
<div class="collapsible-header"><i class="material-icons">code</i>curl example</div>
|
|
<div class="collapsible-body">
|
|
<pre><code class="bash">
|
|
# {% blocktrans %}Load a single URL and assign it to the <em>KEY</em> of abc123{% endblocktrans %}<br/>
|
|
curl -X POST -d '{"urls":"mailto://user:pass@gmail.com"}' \<br/>
|
|
-H "Content-Type: application/json" \<br/>
|
|
http://localhost:8000/add/<em>abc123</em></code></pre>
|
|
<pre><code class="bash">
|
|
# {% blocktrans %}Load a simple TEXT config entry <em>KEY</em> abc123{% endblocktrans %}<br/>
|
|
curl -X POST -d '{"format":"text","config":"devops=mailto://user:pass@gmail.com"}' \<br/>
|
|
-H "Content-Type: application/json" \<br/>
|
|
http://localhost:8000/add/abc123/
|
|
</code></pre>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<div class="collapsible-header"><i class="material-icons">code</i>python example</div>
|
|
<div class="collapsible-body">
|
|
<pre><code class="python">
|
|
import json<br/>
|
|
from urllib.request import Request<br/>
|
|
<br/>
|
|
payload = {<br/>
|
|
'urls': 'mailto://user:pass@gmail.com',<br/>
|
|
}<br/>
|
|
<br/># The URL if the key was <em>abc123</em><br/>
|
|
req = Request(<br/>
|
|
"http://localhost:8000/add/<em>abc123</em>",<br/>
|
|
json.dumps(payload).encode('utf-8'),<br/>
|
|
{"Content-Type": "application/json"},<br/>
|
|
method='POST',<br/>
|
|
)
|
|
</code></pre>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<div class="collapsible-header"><i class="material-icons">code</i>php example</div>
|
|
<div class="collapsible-body">
|
|
<pre><code class="php"><?php<br/>
|
|
<br/>
|
|
// The URL if the key was <em>abc123</em><br/>
|
|
$url = 'http://localhost:8000/add/<em>abc123</em>';<br/>
|
|
<br/>
|
|
//Initiate cURL.<br/>
|
|
$ch = curl_init($url);<br/>
|
|
<br/>
|
|
//The JSON data.<br/>
|
|
$jsonData = array(<br/>
|
|
'urls' => 'mailto://user:pass@hotmail.com'<br/>
|
|
);<br/>
|
|
<br/>
|
|
//Encode the array into JSON.<br/>
|
|
$jsonDataEncoded = json_encode($jsonData);<br/>
|
|
<br/>
|
|
//Tell cURL that we want to send a POST request.<br/>
|
|
curl_setopt($ch, CURLOPT_POST, 1);<br/>
|
|
<br/>
|
|
//Attach our encoded JSON string to the POST fields.<br/>
|
|
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonDataEncoded);<br/>
|
|
<br/>
|
|
//Set the content type to application/json<br/>
|
|
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));<br/>
|
|
<br/>
|
|
//Execute the request<br/>
|
|
$result = curl_exec($ch);
|
|
</code></pre>
|
|
</div>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>/del/<em>{% trans "KEY" %}</em></code></td>
|
|
<td>{% blocktrans %}There are no arguments required. If the <em>KEY</em> exists and has data associated with
|
|
it,
|
|
it will be removed.{% endblocktrans %}
|
|
<ul class="collapsible">
|
|
<li>
|
|
<div class="collapsible-header"><i class="material-icons">code</i>curl example</div>
|
|
<div class="collapsible-body">
|
|
<pre><code class="bash">
|
|
# {% blocktrans %}Remove previously loaded configuration associated with the <em>KEY</em> of abc123{% endblocktrans %}<br/>
|
|
curl -X POST http://localhost:8000/del/<em>abc123</em></code></pre>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<div class="collapsible-header"><i class="material-icons">code</i>python example</div>
|
|
<div class="collapsible-body">
|
|
<pre><code class="python">
|
|
import json<br/>
|
|
from urllib.request import Request<br/>
|
|
<br/># The request if the key was <em>abc123</em><br/>
|
|
req = Request(<br/>
|
|
"http://localhost:8000/del/<em>abc123</em>",<br/>
|
|
json.dumps(payload).encode('utf-8'),<br/>
|
|
{"Content-Type": "application/json"},<br/>
|
|
method='POST',<br/>
|
|
)
|
|
</code></pre>
|
|
</div>
|
|
<li>
|
|
<li>
|
|
<div class="collapsible-header"><i class="material-icons">code</i>php example</div>
|
|
<div class="collapsible-body">
|
|
<pre><code class="php"><?php<br/>
|
|
<br/>
|
|
// The URL if the key was <em>abc123</em><br/>
|
|
$url = 'http://localhost:8000/del/<em>abc123</em>';<br/>
|
|
<br/>
|
|
//Initiate cURL.<br/>
|
|
$ch = curl_init($url);<br/>
|
|
<br/>
|
|
//Tell cURL that we want to send a POST request.<br/>
|
|
curl_setopt($ch, CURLOPT_POST, 1);<br/>
|
|
<br/>
|
|
//Execute the request<br/>
|
|
$result = curl_exec($ch);
|
|
</code></pre>
|
|
</div>
|
|
</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>/get/<em>{% trans "KEY" %}</em></code></td>
|
|
<td>{% blocktrans %}This feature can be used by Apprise itself. It provides a means of remotely fetching it's
|
|
configuration.{% endblocktrans %}<br />
|
|
<pre><code lang="bash"># Use Apprise to retrieve your configuration:<br/>
|
|
apprise --body="test message" --config={{ request.scheme }}://{{request.META.HTTP_HOST}}{{ request.path }}<em>{% trans "KEY" %}</em></code></pre>
|
|
</p>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code>/notify/<em>{% trans "KEY" %}</em></code></td>
|
|
<td>{% blocktrans %}Notifies the URLs associated with the specified <em>KEY</em>.{% endblocktrans %}
|
|
<div class="section">
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>{% trans "Parameter" %}</th>
|
|
<th>{% trans "Description" %}</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>body</td>
|
|
<td>{% blocktrans %}Defines the message body. This field is required!{% endblocktrans %}</td>
|
|
</tr>
|
|
<tr>
|
|
<td>title</td>
|
|
<td>{% blocktrans %}The title to include in the notification. This is an optional
|
|
field.{% endblocktrans %}
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>type</td>
|
|
<td>{% blocktrans %}This optional field defines the notification type. The possible options
|
|
are:{% endblocktrans %}
|
|
<ol>
|
|
<li><i class="tiny material-icons" style="color: blue">info</i><code>{% trans "info" %}</code> -
|
|
<i>{% blocktrans %}this is the default option if a type
|
|
isn't
|
|
specified.{% endblocktrans %}</i></li>
|
|
<li><i class="tiny material-icons"
|
|
style="color: green">check_circle</i><code>{% trans "success" %}</code></li>
|
|
<li><i class="tiny material-icons"
|
|
style="color: orange">report_problem</i><code>{% trans "warning" %}</code></li>
|
|
<li><i class="tiny material-icons"
|
|
style="color: red">cancel</i><code>{% trans "failure" %}</code></li>
|
|
</ol>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td>tags</td>
|
|
<td>{% blocktrans %}Apply tagging logic to the further filter your URLs. This is an optional
|
|
field.{% endblocktrans %}</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<ul class="collapsible">
|
|
<li>
|
|
<div class="collapsible-header"><i class="material-icons">code</i>curl example</div>
|
|
<div class="collapsible-body">
|
|
<pre><code class="bash">
|
|
# {% blocktrans %}Notifies all URLs assigned the <em>devops</em> tag{% endblocktrans %}<br/>
|
|
curl -X POST -d '{"tags":"devops","body":"test body","title":"test title"}' \<br/>
|
|
-H "Content-Type: application/json" \<br/>
|
|
http://localhost:8000/notify/<em>KEY</em></code></pre>
|
|
</div>
|
|
</li>
|
|
<li>
|
|
<div class="collapsible-header"><i class="material-icons">code</i>python example</div>
|
|
<div class="collapsible-body">
|
|
<pre><code class="python">
|
|
import json<br/>
|
|
from urllib.request import Request<br/>
|
|
<br/>
|
|
payload = {<br/>
|
|
'tags': 'devops',<br/>
|
|
'title': 'test title',<br/>
|
|
'body': 'test body',<br/>
|
|
}<br/>
|
|
<br/># The URL if the key was <em>abc123</em><br/>
|
|
req = Request(<br/>
|
|
"http://localhost:8000/notify/<em>abc123</em>",<br/>
|
|
json.dumps(payload).encode('utf-8'),<br/>
|
|
{"Content-Type": "application/json"},<br/>
|
|
method='POST',<br/>
|
|
)
|
|
</code></pre>
|
|
</div>
|
|
<li>
|
|
<li>
|
|
<div class="collapsible-header"><i class="material-icons">code</i>php example</div>
|
|
<div class="collapsible-body">
|
|
<pre><code class="php"><?php<br/>
|
|
<br/>
|
|
// The URL if the key was <em>abc123</em><br/>
|
|
$url = 'http://localhost:8000/notify/<em>abc123</em>';<br/>
|
|
<br/>
|
|
//Initiate cURL.<br/>
|
|
$ch = curl_init($url);<br/>
|
|
<br/>
|
|
//The JSON data.<br/>
|
|
$jsonData = array(<br/>
|
|
'tags' => 'devops',<br/>
|
|
'title' => 'test title',<br/>
|
|
'body' => 'test body'<br/>
|
|
);<br/>
|
|
<br/>
|
|
//Encode the array into JSON.<br/>
|
|
$jsonDataEncoded = json_encode($jsonData);<br/>
|
|
<br/>
|
|
//Tell cURL that we want to send a POST request.<br/>
|
|
curl_setopt($ch, CURLOPT_POST, 1);<br/>
|
|
<br/>
|
|
//Attach our encoded JSON string to the POST fields.<br/>
|
|
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonDataEncoded);<br/>
|
|
<br/>
|
|
//Set the content type to application/json<br/>
|
|
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));<br/>
|
|
<br/>
|
|
//Execute the request<br/>
|
|
$result = curl_exec($ch);
|
|
</code></pre>
|
|
</div>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<div class="section">
|
|
<h4>{% trans "Endpoint Notes" %}</h4>
|
|
<p>
|
|
The <em>KEY</em> you plan to associate your configuration with:
|
|
<ol>
|
|
<li>Can not have spaces and/or special characters in it. Both a dash (<code>-</code>) and underscore
|
|
(<code>_</code>) are the only exceptions to this rule.</li>
|
|
<li>Must start with at least 2 alpha/numeric characters.</li>
|
|
<li>Can not exceed 64 characters in total length.</li>
|
|
</ol>
|
|
</p>
|
|
</div>
|
|
</div>
|
|
{% endblock %} |