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']}"
end
package 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 / 201Success — the response body carries the resource.
401Missing, malformed or revoked Bearer token.
403The token is valid but lacks the required scope.
404The resource does not exist or is not in your account.
422Validation failed — check the error message for the offending field.
429Rate 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.