Use the API safely

Start with the running API reference

On your application host, GET /api/openapi.json serves the route-derived OpenAPI 3.1 inventory. Use that instance's reference for available methods and paths. Authenticated organization endpoints require a valid session and an organization role; the public website does not expose private organization routes.

The current API uses session cookies. Obtain the session's CSRF token from /api/auth/session for mutation requests and send X-CSRF-Token with an Origin matching the application origin. Login may require Turnstile and MFA; do not bypass those checks or put session credentials in shared examples.

Example: read a domain's history

In an authenticated same-origin browser session, replace the placeholders with IDs from your own organization. Read-only requests still enforce organization access. Never paste session cookies or CSRF tokens into support messages.

1. For another page of history, pass the returned next_cursor as the cursor parameter.
2. Use only IDs belonging to the selected organization. Access to another organization is not implied by knowing its ID.

const response = await fetch(
  '/api/organizations/ORG_ID/history?domain_id=DOMAIN_ID',
  { credentials: 'same-origin' },
);
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const history = await response.json();

Error handling and permissions

Check the HTTP status and JSON response rather than assuming every response is successful. A sign-in or proxy HTML page is not an API result. A 401 requires sign-in; 403 can indicate missing permissions or failed request verification; 404 can mean the resource is unavailable to this account; 429 means requests are being limited.

Viewers read data; members manage domains and monitors; admins manage integrations, notifications and memberships; owners can export or delete their organization. Role checks and tenant boundaries apply independently of CSRF and authentication. The API is not an anonymous monitoring service.