API Overview

The Sitepulse API is a versioned JSON HTTP API. All v1 routes live under /api/v1. Responses use stable resource shapes designed for integrations and automation.

What you can do with the API

Teams

List teams, plan limits, and monitoring defaults

Sites

Create and manage monitored sites

Checks

Create on-demand checks and read results

Reports

Pull uptime and performance reports

Issues

Read monitoring incidents and lifecycle history

Base URL

All API endpoints use this base URL:

https://app.sitepulse.dev/api/v1

All paths in this documentation are relative to the base URL unless noted otherwise.

Quick start

Create an API token

In the Sitepulse dashboard, open Settings → API tokens. Create a personal access token and select the scopes your integration needs (for example sites:read, sites:write, checks:run).

Copy the token when it is shown. Sitepulse does not display it again.

Call the API

Use the token in the Authorization header:

curl -sS \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  "https://app.sitepulse.dev/api/v1/me"

const response = await fetch('https://app.sitepulse.dev/api/v1/me', {
  headers: {
    Authorization: 'Bearer YOUR_TOKEN',
    Accept: 'application/json',
  },
});
const data = await response.json();

import requests

response = requests.get(
    'https://app.sitepulse.dev/api/v1/me',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Accept': 'application/json',
    },
)
data = response.json()

req, _ := http.NewRequest(http.MethodGet, "https://app.sitepulse.dev/api/v1/me", nil)
req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
req.Header.Set("Accept", "application/json")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    panic(err)
}
defer resp.Body.Close()

body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))

require 'net/http'
require 'json'

uri = URI('https://app.sitepulse.dev/api/v1/me')
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_TOKEN'
request['Accept'] = 'application/json'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)

$ch = curl_init('https://app.sitepulse.dev/api/v1/me');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_TOKEN',
        'Accept: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

Work inside a team

Most write operations require an active team context. Team-scoped routes resolve the team from the URL (/teams/{team}/sites) or from the site or check in the path.

curl -sS \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  "https://app.sitepulse.dev/api/v1/teams"

const response = await fetch('https://app.sitepulse.dev/api/v1/teams', {
  headers: {
    Authorization: 'Bearer YOUR_TOKEN',
    Accept: 'application/json',
  },
});
const data = await response.json();

import requests

response = requests.get(
    'https://app.sitepulse.dev/api/v1/teams',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Accept': 'application/json',
    },
)
data = response.json()

req, _ := http.NewRequest(http.MethodGet, "https://app.sitepulse.dev/api/v1/teams", nil)
req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
req.Header.Set("Accept", "application/json")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    panic(err)
}
defer resp.Body.Close()

body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))

require 'net/http'
require 'json'

uri = URI('https://app.sitepulse.dev/api/v1/teams')
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_TOKEN'
request['Accept'] = 'application/json'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)

$ch = curl_init('https://app.sitepulse.dev/api/v1/teams');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_TOKEN',
        'Accept: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

Create a site and run a check

Only url is required. New sites inherit the team’s monitoring defaults; to enable specific tools or set cadences at creation, send a monitoring_settings object.

TEAM_ID=01JZ7VQ3J7Y5S8N9P0Q1R2S3T4

# Create a site
curl -sS -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","name":"Example"}' \
  "https://app.sitepulse.dev/api/v1/teams/${TEAM_ID}/sites"

# Run a status check (returns 202 with pending check records)
curl -sS -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"tools":["status"]}' \
  "https://app.sitepulse.dev/api/v1/sites/{site-uuid}/checks"

# Poll until completed
curl -sS \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  "https://app.sitepulse.dev/api/v1/checks/{check-uuid}"

const headers = {
  Authorization: 'Bearer YOUR_TOKEN',
  Accept: 'application/json',
  'Content-Type': 'application/json',
};

const teamId = '01JZ7VQ3J7Y5S8N9P0Q1R2S3T4';

// Create a site
const siteResponse = await fetch(
  `https://app.sitepulse.dev/api/v1/teams/${teamId}/sites`,
  {
    method: 'POST',
    headers,
    body: JSON.stringify({
      url: 'https://example.com',
      name: 'Example',
    }),
  }
);
const site = await siteResponse.json();

// Run a status check (returns 202 with pending check records)
const checkResponse = await fetch(
  `https://app.sitepulse.dev/api/v1/sites/${site.data.uuid}/checks`,
  {
    method: 'POST',
    headers,
    body: JSON.stringify({ tools: ['status'] }),
  }
);
const check = await checkResponse.json();

// Poll until completed
const resultResponse = await fetch(
  `https://app.sitepulse.dev/api/v1/checks/${check.data[0].uuid}`,
  { headers: { Authorization: headers.Authorization, Accept: headers.Accept } }
);
const result = await resultResponse.json();

import requests

headers = {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}

team_uuid = '01JZ7VQ3J7Y5S8N9P0Q1R2S3T4'

# Create a site
site = requests.post(
    f'https://app.sitepulse.dev/api/v1/teams/{team_uuid}/sites',
    headers=headers,
    json={
        'url': 'https://example.com',
        'name': 'Example',
    },
).json()

# Run a status check (returns 202 with pending check records)
check = requests.post(
    f"https://app.sitepulse.dev/api/v1/sites/{site['data']['uuid']}/checks",
    headers=headers,
    json={'tools': ['status']},
).json()

# Poll until completed
result = requests.get(
    f"https://app.sitepulse.dev/api/v1/checks/{check['data'][0]['uuid']}",
    headers={'Authorization': headers['Authorization'], 'Accept': headers['Accept']},
).json()

headers := map[string]string{
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept":        "application/json",
    "Content-Type":  "application/json",
}

teamID := "01JZ7VQ3J7Y5S8N9P0Q1R2S3T4"

// Create a site
siteBody := strings.NewReader(`{"url":"https://example.com","name":"Example"}`)
siteReq, _ := http.NewRequest(http.MethodPost, fmt.Sprintf("https://app.sitepulse.dev/api/v1/teams/%s/sites", teamID), siteBody)
for key, value := range headers {
    siteReq.Header.Set(key, value)
}
siteResp, _ := http.DefaultClient.Do(siteReq)
defer siteResp.Body.Close()
siteData, _ := io.ReadAll(siteResp.Body)

// Run a status check (returns 202 with pending check records)
checkBody := strings.NewReader(`{"tools":["status"]}`)
checkReq, _ := http.NewRequest(http.MethodPost, "https://app.sitepulse.dev/api/v1/sites/{site-uuid}/checks", checkBody)
for key, value := range headers {
    checkReq.Header.Set(key, value)
}
checkResp, _ := http.DefaultClient.Do(checkReq)
defer checkResp.Body.Close()
checkData, _ := io.ReadAll(checkResp.Body)

// Poll until completed
resultReq, _ := http.NewRequest(http.MethodGet, "https://app.sitepulse.dev/api/v1/checks/{check-uuid}", nil)
resultReq.Header.Set("Authorization", headers["Authorization"])
resultReq.Header.Set("Accept", headers["Accept"])
resultResp, _ := http.DefaultClient.Do(resultReq)
defer resultResp.Body.Close()
resultData, _ := io.ReadAll(resultResp.Body)
fmt.Println(string(siteData), string(checkData), string(resultData))

require 'net/http'
require 'json'

headers = {
  'Authorization' => 'Bearer YOUR_TOKEN',
  'Accept' => 'application/json',
  'Content-Type' => 'application/json',
}

team_uuid = '01JZ7VQ3J7Y5S8N9P0Q1R2S3T4'

# Create a site
site_uri = URI("https://app.sitepulse.dev/api/v1/teams/#{team_uuid}/sites")
site_request = Net::HTTP::Post.new(site_uri)
headers.each { |key, value| site_request[key] = value }
site_request.body = {
  url: 'https://example.com',
  name: 'Example',
}.to_json

site_response = Net::HTTP.start(site_uri.hostname, site_uri.port, use_ssl: true) do |http|
  http.request(site_request)
end
site = JSON.parse(site_response.body)

# Run a status check (returns 202 with pending check records)
check_uri = URI("https://app.sitepulse.dev/api/v1/sites/#{site['data']['uuid']}/checks")
check_request = Net::HTTP::Post.new(check_uri)
headers.each { |key, value| check_request[key] = value }
check_request.body = { tools: ['status'] }.to_json

check_response = Net::HTTP.start(check_uri.hostname, check_uri.port, use_ssl: true) do |http|
  http.request(check_request)
end
check = JSON.parse(check_response.body)

# Poll until completed
result_uri = URI("https://app.sitepulse.dev/api/v1/checks/#{check['data'][0]['uuid']}")
result_request = Net::HTTP::Get.new(result_uri)
result_request['Authorization'] = headers['Authorization']
result_request['Accept'] = headers['Accept']

result_response = Net::HTTP.start(result_uri.hostname, result_uri.port, use_ssl: true) do |http|
  http.request(result_request)
end
result = JSON.parse(result_response.body)

$headers = [
    'Authorization: Bearer YOUR_TOKEN',
    'Accept: application/json',
    'Content-Type: application/json',
];

$teamId = 1;

// Create a site
$ch = curl_init("https://app.sitepulse.dev/api/v1/teams/{$teamId}/sites");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => json_encode([
        'url' => 'https://example.com',
        'name' => 'Example',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$site = json_decode(curl_exec($ch), true);
curl_close($ch);

// Run a status check (returns 202 with pending check records)
$ch = curl_init("https://app.sitepulse.dev/api/v1/sites/{$site['data']['uuid']}/checks");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => json_encode(['tools' => ['status']]),
    CURLOPT_RETURNTRANSFER => true,
]);
$check = json_decode(curl_exec($ch), true);
curl_close($ch);

// Poll until completed
$ch = curl_init("https://app.sitepulse.dev/api/v1/checks/{$check['data'][0]['uuid']}");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer YOUR_TOKEN',
        'Accept: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

Versioning

Only /api/v1 is documented here. Breaking changes will ship under a new version prefix.

Build integrations only against the documented /api/v1 endpoints so a future version prefix doesn’t break your code.

Requirements

Before using the API, ensure you have:

A verified Sitepulse user account (email verified)
An active subscription on the team you are accessing (inactive billing returns 402)
API token scopes that cover the operation (missing scope returns 403)
Team membership and role permissions for the underlying action (returns 403 or 404 as appropriate)

API documentation

Authentication

Personal access tokens, OAuth scopes, and required headers

Requests & Responses

JSON conventions, pagination, team context, errors, and rate limits

Resources

Field-by-field schemas for users, teams, sites, checks, issues, and reports

Endpoints

Complete HTTP method and path reference

Check Results

Result object shapes per check tool

Getting Started

User Guide

API Reference

What you can do with the API

Teams

Sites

Checks

Reports

Issues

Base URL

Quick start

Versioning

Requirements

API documentation

Authentication

Requests & Responses

Resources

Endpoints

Check Results

​What you can do with the API

Teams

Sites

Checks

Reports

Issues

​Base URL

​Quick start

​Versioning

​Requirements

​API documentation

Authentication

Requests & Responses

Resources

Endpoints

Check Results

​Related guides

What you can do with the API

Base URL

Quick start

Versioning

Requirements

API documentation

Related guides