RegSentry API v1

A JSON API for the sites you monitor, their scans and findings, deploy-time policy checks and signed webhooks. The MCP account tools use the same service layer.

Machine-readable: /api/v1/openapi.json (OpenAPI 3.1). This page is generated from that document. Quickstarts for agents and CI are on /agents.

Authentication

Send an API key on every request:

Authorization: Bearer rs_live_...

Create keys in the owner dashboard under API & agents. A token is shown once; RegSentry stores only its hash. The same key authenticates the MCP server at /mcp. GET /openapi.json and GET /plans need no key.

Write operations also need a plan with API access (Team or Protect); webhook creation needs a plan with webhooks. On Monitor, keys are read-only.

Errors

Every error has the same shape, sometimes with extra fields such as limit, used or resetsAt:

{ "error": { "code": "plan_required", "message": "Your plan (Monitor) does not include apiAccess. ..." } }

Rate limits and API runs

Each key may make 300 requests per minute. Past that the API returns 429 rate_limited; retry after a minute. Separately, scans and deploy checks started through the API, MCP or CI count toward the plan's monthly API runs (UTC month). Scheduled monitoring scans do not count.

The public MCP endpoint is limited per client IP to 120 requests per minute, and public runtime inspections to 6 per hour.

Endpoints

Paths are relative to https://regsentry.com. In body lists, * marks a required field. Full schemas are in the OpenAPI document.

Account

Who the key belongs to, its plan, features and usage, plus the public plan ladder.

Sites

Sites on your account. Each has its own policy, monitoring state and optional alert email.

Scans

Full scans of your own sites: homepage plus up to four high-signal pages, diffed against the last run. Starting a scan returns 202 with the running scan; pass wait: true to block up to 120 seconds, or poll GET /scans/{id}.

Findings

Recorded findings with observation dates, and the evidence export as JSON, CSV or PDF.

Checks

Deploy-time policy checks of any public host you are authorized to inspect. Synchronous, up to about 45 seconds. The response carries exitCode 0 pass, 1 fail or 2 inconclusive.

Webhooks

Signed delivery endpoints for scan, finding, consent and check events. See Webhooks.

Policies

A policy turns an observation into pass, fail or inconclusive. Set one per site (PATCH /sites/{id}) or per call (policy on scans and checks). "Flagged" means the tracker is in RegSentry's alert set.

Webhooks

Create an endpoint with POST /webhooks (https only, public hosts only). Subscribe to specific events or ["*"]. The response includes a whsec_... secret once; store it. Each delivery is a JSON POST of { id, event, createdAt, data }. Failed deliveries are retried up to 5 times with backoff over roughly 14 hours. POST /webhooks/{id}/test sends a signed test delivery.

Check-event change: inconclusive results now use check.inconclusive instead of check.passed. Existing endpoints subscribed to selected events must be recreated with check.inconclusive to receive those results; wildcard subscriptions receive it automatically. Inspect the result in data.policy.

Headers

Verify a delivery (Node)

Compute the HMAC over the timestamp, a period and the raw request body, compare in constant time, and reject stale timestamps. Each retry is signed with a fresh timestamp.

import express from "express";
import crypto from "node:crypto";

const app = express();
const SECRET = process.env.REGSENTRY_WEBHOOK_SECRET; // whsec_..., returned once when the endpoint is created

// Verify against the raw body, before any JSON parsing.
app.post("/hooks/regsentry", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.get("X-RegSentry-Timestamp") || "";
  const signature = req.get("X-RegSentry-Signature") || "";
  const expected = "v1=" + crypto.createHmac("sha256", SECRET).update(`${timestamp}.${req.body}`).digest("hex");
  const valid = signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
  if (!valid || !fresh) return res.sendStatus(401);

  const delivery = JSON.parse(req.body.toString("utf8")); // { id, event, createdAt, data }
  // delivery.event === "consent.regression", delivery.data.domain, ...
  res.sendStatus(204);
});

Exit codes

The exitCode field of POST /checks reports the result: