API Documentation
Complete reference for the YouMonit REST API v2, with copy-paste examples in seven languages.
Base URL & conventions
All endpoints are served over HTTPS under the version prefix below. Requests and responses are JSON encoded as UTF-8; timestamps are ISO-8601.
https://www.youmonit.com/api/v2
Authentication
Create an API key in your workspace under Integrations & API, then pass it as a Bearer token on every request. Keys start with ymk_live_ and are shown only once — store them safely.
Authorization: Bearer ymk_live_xxxxxxxxxxxxxxxx
Create a key in Integrations & API
Scopes
Each key carries one or more scopes. A write scope implies the matching read scope. A request missing a required scope is rejected with HTTP 403.
| Scope | Grants |
|---|---|
read:monitors |
Read monitors, their check history and uptime. |
write:monitors |
Create, update, pause and delete monitors. |
read:incidents |
List and read incidents. |
write:incidents |
Acknowledge incidents. |
read:status-pages |
Read public status pages. |
read:channels |
List notification channels. |
read:billing |
Read the subscription, plan limits and invoices. |
read:members |
Read the account profile and its members. |
Quick start — list your monitors
Pick your language above. This example fetches every monitor in the workspace the key belongs to.
curl https://www.youmonit.com/api/v2/monitors \
-H "Authorization: Bearer ymk_live_xxxxxxxxxxxxxxxx"<?php
$ch = curl_init('https://www.youmonit.com/api/v2/monitors');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ymk_live_xxxxxxxxxxxxxxxx'],
]);
$body = curl_exec($ch);
curl_close($ch);
$data = json_decode($body, true);
foreach ($data['monitors'] as $m) {
printf("%s — %s\n", $m['name'], $m['last_status']);
}const res = await fetch('https://www.youmonit.com/api/v2/monitors', {
headers: { Authorization: 'Bearer ymk_live_xxxxxxxxxxxxxxxx' },
});
const { monitors } = await res.json();
monitors.forEach(m => console.log(`${m.name} — ${m.last_status}`));import requests
res = requests.get(
"https://www.youmonit.com/api/v2/monitors",
headers={"Authorization": "Bearer ymk_live_xxxxxxxxxxxxxxxx"},
)
for m in res.json()["monitors"]:
print(m["name"], "—", m["last_status"])use strict;
use warnings;
use LWP::UserAgent;
use JSON::PP qw(decode_json);
my $ua = LWP::UserAgent->new;
my $res = $ua->get(
'https://www.youmonit.com/api/v2/monitors',
'Authorization' => 'Bearer ymk_live_xxxxxxxxxxxxxxxx',
);
die $res->status_line unless $res->is_success;
my $data = decode_json($res->decoded_content);
for my $m (@{ $data->{monitors} }) {
printf "%s — %s\n", $m->{name}, $m->{last_status};
}require "net/http"
require "json"
uri = URI("https://www.youmonit.com/api/v2/monitors")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer ymk_live_xxxxxxxxxxxxxxxx"
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
JSON.parse(res.body)["monitors"].each do |m|
puts "#{m['name']} — #{m['last_status']}"
endpackage main
import (
"encoding/json"
"fmt"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://www.youmonit.com/api/v2/monitors", nil)
req.Header.Set("Authorization", "Bearer ymk_live_xxxxxxxxxxxxxxxx")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
var data struct {
Monitors []struct {
Name string `json:"name"`
LastStatus string `json:"last_status"`
} `json:"monitors"`
}
json.NewDecoder(res.Body).Decode(&data)
for _, m := range data.Monitors {
fmt.Printf("%s — %s\n", m.Name, m.LastStatus)
}
}Create a monitor
POST a JSON body. The fields type, name and target are required; everything else falls back to sensible defaults.
curl -X POST https://www.youmonit.com/api/v2/monitors \
-H "Authorization: Bearer ymk_live_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"type": "http",
"name": "Marketing site",
"target": "https://example.com",
"interval_seconds": 300
}'<?php
$payload = json_encode([
'type' => 'http',
'name' => 'Marketing site',
'target' => 'https://example.com',
'interval_seconds' => 300,
]);
$ch = curl_init('https://www.youmonit.com/api/v2/monitors');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ymk_live_xxxxxxxxxxxxxxxx',
'Content-Type: application/json',
],
]);
$monitor = json_decode(curl_exec($ch), true)['monitor'];
curl_close($ch);
echo "Created monitor #{$monitor['id']}\n";const res = await fetch('https://www.youmonit.com/api/v2/monitors', {
method: 'POST',
headers: {
Authorization: 'Bearer ymk_live_xxxxxxxxxxxxxxxx',
'Content-Type': 'application/json',
},
body: JSON.stringify({
type: 'http',
name: 'Marketing site',
target: 'https://example.com',
interval_seconds: 300,
}),
});
const { monitor } = await res.json();
console.log('Created monitor #' + monitor.id);import requests
res = requests.post(
"https://www.youmonit.com/api/v2/monitors",
headers={"Authorization": "Bearer ymk_live_xxxxxxxxxxxxxxxx"},
json={
"type": "http",
"name": "Marketing site",
"target": "https://example.com",
"interval_seconds": 300,
},
)
print("Created monitor #", res.json()["monitor"]["id"])use strict;
use warnings;
use LWP::UserAgent;
use JSON::PP qw(encode_json decode_json);
my $ua = LWP::UserAgent->new;
my $res = $ua->post(
'https://www.youmonit.com/api/v2/monitors',
'Authorization' => 'Bearer ymk_live_xxxxxxxxxxxxxxxx',
'Content-Type' => 'application/json',
Content => encode_json({
type => 'http',
name => 'Marketing site',
target => 'https://example.com',
interval_seconds => 300,
}),
);
my $monitor = decode_json($res->decoded_content)->{monitor};
print "Created monitor #", $monitor->{id}, "\n";require "net/http"
require "json"
uri = URI("https://www.youmonit.com/api/v2/monitors")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer ymk_live_xxxxxxxxxxxxxxxx"
req["Content-Type"] = "application/json"
req.body = {
type: "http",
name: "Marketing site",
target: "https://example.com",
interval_seconds: 300,
}.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
puts "Created monitor ##{JSON.parse(res.body)['monitor']['id']}"package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func main() {
payload, _ := json.Marshal(map[string]any{
"type": "http",
"name": "Marketing site",
"target": "https://example.com",
"interval_seconds": 300,
})
req, _ := http.NewRequest("POST",
"https://www.youmonit.com/api/v2/monitors", bytes.NewReader(payload))
req.Header.Set("Authorization", "Bearer ymk_live_xxxxxxxxxxxxxxxx")
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
var data struct {
Monitor struct {
ID int `json:"id"`
} `json:"monitor"`
}
json.NewDecoder(res.Body).Decode(&data)
fmt.Printf("Created monitor #%d\n", data.Monitor.ID)
}Endpoint reference
Monitors
| Method | Endpoint | Scope | Description |
|---|---|---|---|
| GET | /api/v2/monitors |
read:monitors |
List all monitors; filter by type or status. |
| POST | /api/v2/monitors |
write:monitors |
Create a new monitor. |
| GET | /api/v2/monitors/{id} |
read:monitors |
Fetch a single monitor by ID. |
| PATCH | /api/v2/monitors/{id} |
write:monitors |
Update fields on an existing monitor. |
| DELETE | /api/v2/monitors/{id} |
write:monitors |
Delete a monitor permanently. |
| GET | /api/v2/monitors/{id}/checks |
read:monitors |
Recent check results for a monitor. |
| GET | /api/v2/monitors/{id}/uptime |
read:monitors |
Uptime aggregate for 24h / 7d / 30d / 90d. |
Incidents
| Method | Endpoint | Scope | Description |
|---|---|---|---|
| GET | /api/v2/incidents |
read:incidents |
List incidents; filter by status. |
| GET | /api/v2/incidents/{id} |
read:incidents |
Fetch a single incident by ID. |
| POST | /api/v2/incidents/{id}/acknowledge |
write:incidents |
Acknowledge an open incident. |
Status pages & channels
| Method | Endpoint | Scope | Description |
|---|---|---|---|
| GET | /api/v2/status-pages |
read:status-pages |
List the workspace status pages. |
| GET | /api/v2/channels |
read:channels |
List notification channels. |
Account & members
| Method | Endpoint | Scope | Description |
|---|---|---|---|
| GET | /api/v2/me |
read:members |
The account the API key belongs to. |
| GET | /api/v2/accounts/{id} |
read:members |
Fetch account details by ID. |
| GET | /api/v2/accounts/{id}/members |
read:members |
List members of the account. |
Billing
| Method | Endpoint | Scope | Description |
|---|---|---|---|
| GET | /api/v2/billing/plans |
— | Public catalogue of plans — no auth required. |
| GET | /api/v2/billing/subscription |
read:billing |
Current subscription and plan limits. |
| GET | /api/v2/billing/invoices |
read:billing |
Invoice history. |
Errors & status codes
Errors return the appropriate HTTP status with a JSON body containing an error field describing what went wrong.
200 / 201 | Success — the response body carries the resource. |
401 | Missing, malformed or revoked Bearer token. |
403 | The token is valid but lacks the required scope. |
404 | The resource does not exist or is not in your account. |
422 | Validation failed — check the error message for the offending field. |
429 | Rate limit exceeded — slow down and retry. |
{ "error": "token lacks required scope: write:monitors" }
Rate limits
API keys are held to a fair-use budget of 120 requests per minute. Batch where you can; exceeding the budget returns HTTP 429.
Outgoing webhooks
Instead of polling, register a webhook in Integrations & API to receive monitor.up and monitor.down events. Each delivery is signed with HMAC-SHA-256 so you can verify it came from YouMonit.