Add clients.md file

content/docs/alerting/alertmanager.md

@@ -54,7 +54,7 @@ Inhibitions are configured through the Alertmanager's configuration file.
 ## Silences
 
 Silences are a straightforward way to simply mute alerts for a given time.
-A silence is configured based on matchers, just as the routing tree. Incoming
+A silence is configured based on matchers, just like the routing tree. Incoming
 alerts are checked whether they match all the equality or regular expression
 matchers of an active silence.
 If they do, no notifications will be send out for that alert.

content/docs/alerting/clients.md

+---
+title: Clients
+sort_rank: 5
+nav_icon: sliders
+---
+
+# Sending alerts
+
+__**Disclaimer**: Prometheus automatically takes care of sending alerts
+generated by its configured [alerting rules](../rules). It is highly
+recommended to configure alerting rules in Prometheus based on time series
+data rather than implementing a direct client.__
+
+The Alertmanager listens for alerts on an API endpoint at `/api/v1/alerts`.
+Clients are expected to continously re-send alerts as long as they are still
+active (usually on the order of 30 seconds to 3 minutes).
+Clients can push a list of alerts to that endpoint via a POST request of
+the following format:
+
+```
+[
+  {
+    "labels": {
+      "<labelname>": "<labelvalue>",
+      ...
+    },
+    "annotations": {
+      "<labelname>": "<labelvalue>",
+    },
+    "startsAt": "<rfc3339>",
+    "endAt": "<rfc3339>"
+    "generatorURL": "<generator_url>"
+  },
+  ...
+]
+```
+
+The labels are used to identify identical instances of an alert and to perform
+deduplication. The annotations are always set to those received most recently
+and are not identifying an alert.
+
+Both timestamps are optional. If `startsAt` is omitted, the current time
+is assigned by the Alertmanager. `endsAt` is only set if the end time of an
+alert is known. Otherwise it will be set to a configurable timeout period from
+the time since the alert was last received.
+
+The `generatorURL` field is a unique back-link which identifies the causing
+entity of this alert in the client. 
+
+Alertmanager also supports a legacy endpoint on `/api/alerts` which is
+compatible with Prometheus versions 0.16.2 and lower.
\ No newline at end of file