Use the application API

Current access model

The current API is the session-authenticated application API used by the Uptime dashboard. Requests are authorized against the signed-in user and selected organization.

Personal API tokens, service accounts, and a general public developer API are not available yet. Use the examples in this guide for first-party development and local integration work. Do not build unattended production automation around copied browser cookies.

The web application and API run on separate local origins by default:

Web: http://localhost:3000
API: http://localhost:3001

Browser requests must include credentials so the API receives the authenticated session.

Common request pattern

Use a small wrapper that preserves response context and treats non-success responses as data:

const apiBase = "http://localhost:3001";

async function apiRequest<T>(path: string, init: RequestInit = {}) {
  const response = await fetch(`${apiBase}${path}`, {
    ...init,
    credentials: "include",
    headers: {
      "content-type": "application/json",
      ...init.headers,
    },
  });

  const payload = await response.json().catch(() => null);

  if (!response.ok) {
    throw new Error(payload?.error ?? `Request failed (${response.status})`);
  }

  return payload as T;
}

Do not log cookie headers or complete integration credentials. When surfacing failures, include the method, route, status, and safe validation message.

Organization authorization

Most collection endpoints require organizationId in the query or request body. The server validates that the signed-in user can access the organization; the identifier alone does not grant access.

Expected error categories include:

• 400 for missing context or invalid input;
• 401 when no valid session is present;
• 403 when the session cannot perform the organization action;
• 404 when the resource does not exist in the authorized scope;
• 409 for a conflicting state where applicable;
• 500 for an unexpected server failure.

Schema validation responses may include structured issues. Map those issues to fields when possible instead of showing only a generic toast.

Create an HTTP monitor

The create endpoint validates protocol, timing, assertions, regions, incident thresholds, and organization access. Confirmation cannot require more regions than the monitor uses.

type CreateMonitorResponse = {
  monitor: { id: string; name: string; type: string };
};

const result = await apiRequest<CreateMonitorResponse>("/api/monitors", {
  method: "POST",
  body: JSON.stringify({
    organizationId,
    name: "Public API",
    type: "http",
    url: "https://api.example.com/health",
    intervalSeconds: 60,
    timeoutMs: 10000,
    failureThreshold: 2,
    recoveryThreshold: 2,
    confirmationRegions: 2,
    regions: ["us-east", "us-west", "eu-west"],
    httpMethod: "GET",
    expectedStatus: "2xx_3xx",
    followRedirects: true,
    sslCheckEnabled: true,
  }),
});

console.log(result.monitor.id);

Use HTTPS targets when possible. For websites that block ICMP, create an HTTP or TCP monitor instead of treating a ping failure as service downtime.

Read monitor inventory

Fetch the monitor list for an authorized organization:

const { monitors } = await apiRequest<{
  monitors: Array<{
    id: string;
    name: string;
    enabled: boolean;
    health: string;
  }>;
}>(`/api/monitors?organizationId=${encodeURIComponent(organizationId)}`);

Inventory responses are intended for dashboard views. Treat the API response as the source of truth for current health rather than recalculating state from a single latest check.

Read check evidence

The check-log endpoint is paginated and filterable so clients do not need to download an unlimited observation history. Use it for investigation, not chart aggregation.

GET /api/monitors/{monitorId}/checks

Depending on the active explorer filters, request parameters can narrow status, region, time range, or pagination. Preserve the server-provided ordering and pagination boundary when loading the next page.

A check represents one observation from one region. It is not equivalent to an incident. Use incident endpoints for lifecycle state and the check log for underlying evidence.

Read telemetry efficiently

Use the telemetry endpoint for charts:

GET /api/monitors/{monitorId}/telemetry

Supported chart ranges include short operational windows and longer historical periods. The server chooses time buckets appropriate to the selected range and calculates average, median, and p95 values by bucket and region. It also returns incident and maintenance ranges needed for overlays.

Do not fetch raw 90-day observations and aggregate them in the browser. The aggregated endpoint keeps response size and rendering time bounded while aligning failure markers, incident intervals, maintenance windows, availability, and optional previous-period comparison.

Read incidents and status pages

Common collection routes include:

GET /api/incidents?organizationId={organizationId}
GET /api/status-pages?organizationId={organizationId}
GET /api/maintenance?organizationId={organizationId}

Incident data contains operational state and timeline events. Public status-page responses are a separate boundary and must omit private monitor targets and organization data. Do not expose an authenticated response directly from a public route.

Update safely

For mutable resources, send only supported fields and keep the current organization scope explicit. Avoid retrying non-idempotent requests blindly after a network timeout because the server may have completed the operation before the connection failed.

When an update changes incident policy:

1. read the current monitor;
2. show the operator the resulting timing and quorum;
3. validate confirmation against selected regions;
4. apply the update;
5. refetch the monitor and verify persisted state;
6. rely on audit history for administrative changes where available.

Production integration boundary

The session API is not a substitute for a documented public API. A future public surface should include scoped tokens or service accounts, stable versioning, rate-limit semantics, idempotency guidance, audit attribution, and a published compatibility policy.

Until that boundary exists:

• do not distribute internal session credentials;
• do not promise third parties a stable undocumented endpoint contract;
• keep first-party callers typed and colocated with the application;
• validate every organization-scoped response on the server;
• update this guide when contracts change.

For notification automation that is supported today, use Slack webhooks and verify delivery in the incident timeline.