Everything your account page does for a portfolio, as JSON: add, tag and remove sites in bulk, read uptime, ads.txt, robots and noindex signals, servers and their security state, start scans and read reports.
Base URL
https://approvalens.com/api/v1
Included with every paid plan · included with every site and server plan.
Every endpoint answers with JSON and only ever touches the account that owns the key: its sites, servers, tags and the reports scanned or bought with its e‑mail address.
01
Sign in. Any paid plan includes the API: a site plan or a server plan.
02
Open Account → API keys and create a key. Choose "Read and write" if your script should change things. Copy it: it is shown once.
03
Put it in an environment variable and send it as a bearer token with every request.
1. Check the key: who it belongs to, its scopes and your free site slots
API access comes with any paid plan: a site plan (from $4.99 a month) or a server plan, while it is active or cancelled but not yet ended. The month of monitoring included with a full report does not include it. Without a plan your keys are kept, but every request answers 403 subscription_required; the same keys work again once a plan is active.
Keys look like al_live_ followed by 32 characters. Send one in the Authorization header:
An account can have up to 5 active keys. Revoke a key on the account page and it stops working at once. We store only a SHA-256 fingerprint of each key, so a lost key cannot be shown again: make a new one.
The API is for servers and scripts. It sends no CORS headers, so a web page on another site cannot call it from a visitor's browser. Never put a key in front-end code.
03
Scopes: read and write
Every key has a scope, chosen when you create it:
read: every GET endpoint, and the free AI crawler check (it changes nothing on your account).
read and write: everything read can do, plus adding, tagging and removing sites, tags, server enrollment keys, starting scans and spending a credit you already have.
Keys made before 7 October 2026 are read-only: write access did not exist then, and we did not want an old key in an old script to gain it silently. Make a new key with the write scope for scripts that change things. A read-only key that calls a write endpoint gets 403 insufficient_scope.
403
{
"error": "insufficient_scope",
"message": "This key is read-only. Make a key with the write scope on your account page to POST here.",
"details": {
"required": "write"
}
}
No endpoint ever charges you. POST /api/v1/scans/:id/unlock only spends a site credit your account already has; with none left it answers 402 no_credits.
04
Rate limits
60 requests a minute per key, counted over a sliding minute, and at most 10 in any one second. Every answer carries:
X-RateLimit-Limit the per-minute limit
X-RateLimit-Remaining requests left in the current minute
X-RateLimit-Reset when the oldest request leaves the window (Unix seconds)
X-RateLimit-Burst the per-second cap
X-Request-Id this request's id; quote it if you write to us
Over a limit you get 429 rate_limited with a Retry-After header in seconds. Some endpoints have their own limits on top, the same as on the site:
POST /ai-checks: 6 a minute per key; a site checked in the last 10 minutes gets that result back (cached: true).
POST /scans: 8 a minute per key, and per account the hourly and daily caps of the free scan. A site scanned in the last 20 minutes gives that scan back.
POST /sites: 30 calls per 10 minutes and 1,500 added sites an hour per account, shared with the account page's import.
POST /sites/remove: 20 calls per 10 minutes per account. POST /scans/:id/unlock: 12 per 10 minutes.
Requests with a wrong key: 20 a minute per IP address.
429
{
"error": "rate_limited",
"message": "Rate limit of 60 requests per minute per key reached. Retry in 12 s."
}
05
Pagination
Lists (sites, servers, scans, reports) come in pages, sorted so that a page never shifts while you read: sites and servers by id, scans newest first. limit sets the page size (default 100, at most 300; the default covers the largest site plan, so clients that never page still see every site).
Each answer has next_cursor. Pass it back unchanged as ?cursor= with the same filters to get the next page; it is null on the last one. Cursors are opaque: do not build them yourself. total (sites, servers) counts every item that matches the filters.
Send an Idempotency-Key header (a UUID is ideal) with any POST. If the connection drops, retry with the same key: the request runs once, and the retry gets the first answer back with Idempotent-Replayed: true. Answers are kept for 24 hours.
Reusing a key for a different request answers 422 idempotency_key_reused; retrying while the first is still running answers 409 idempotency_in_progress. A request that failed on our side (5xx) is not kept, so a retry runs it again. Adding a site that is already there and unlocking a site that is already open are safe to repeat anyway.
07
Conventions
Times are ISO-8601 in UTC, without fractions: 2026-10-06T09:14:03Z. A missing time is null.
Add ?lang=tr to get human-readable text (incident descriptions, alert lines, finding titles) in Turkish; the default is English.
Sites are addressed by host and matched with and without www; servers, tags and keys by their numeric id.
Fields may be added to v1 answers; existing fields keep their name and meaning. Breaking changes get a new version in the path.
08
Errors
Errors use the HTTP status and one JSON shape: a machine-readable code, a sentence for people and, where it helps, details (a limit, your plan's usage, the scope needed):
409
{
"error": "plan_full",
"message": "Your site plan is full. Remove a site or move to a larger plan.",
"details": {
"plan": {
"limit": 25,
"used": 25,
"free": 0
}
}
}
Code
Status
Meaning
bad_request
400
A parameter or the JSON body is not valid; message names the field.
bad_url
400
Not a public website address we can scan or monitor.
invalid_key
401
The key is malformed, unknown or revoked.
missing_key
401
No Authorization: Bearer header.
no_credits
402
Unlocking needs a site credit and the account has none. Nothing was charged.
insufficient_scope
403
The key is read-only and the endpoint changes something. details.required names the scope.
subscription_required
403
The account has no active paid plan. The same keys work again once it has one.
not_found
404
No such endpoint, or nothing with that id or host on your account.
idempotency_in_progress
409
A request with this Idempotency-Key is still running.
limit_reached
409
Too many active enrollment keys.
no_plan
409
Adding a site needs a live site plan.
not_ready
409
The scan has not finished yet.
plan_full
409
Every slot of the site plan is taken; details.plan has the numbers.
tag_exists
409
A tag with this name already exists.
tag_limit
409
The account would have more than 100 tags.
idempotency_key_reused
422
The Idempotency-Key was used for a different request.
unreachable
422
The site's name does not resolve or the site did not answer.
rate_limited
429
Too many requests: wait Retry-After seconds.
unavailable
503
Our side failed. Try again shortly.
09
Endpoints
Shapes are exact; the values are an example account. Every request needs the Authorization header.
Account
The key, its scopes, your plans and their free slots.
GET/api/v1/accountScope: read
Your account
The e‑mail the key belongs to, its scopes, your site and server plans with their used and free slots, and the credit balance. Check free slots here before a bulk add.
Monitored sites: list with filters, add and remove in bulk, tags, uptime, outages and the daily AdSense signals.
GET/api/v1/sitesScope: readpaged
List sites
Every site on your account with its state now: up or down, 30-day uptime, last response time, TLS, ads.txt, the AdSense signals of the daily check (ads.txt, Mediapartners and Googlebot access, noindex, newly blocked AI crawlers), tags, plan coverage and the outage going on, if any. Filter by tag, status, monitoring, signal or part of the host.
Parameters
tag
only items with this tag; repeat or comma-separate for any of several
status
up, down or unknown (not probed yet)
monitoring
true or false: monitored now
signal
only sites with this problem: down, ads_txt_problem, noindex, mediapartners_blocked, googlebot_blocked, ai_blocked_new, tls_expiring (14 days or less), over_plan, not_monitored
Adds one site (url) or up to 300 (urls) to your site plan, exactly like the account page's import: each entry is checked (format, DNS, public address), duplicates are folded, and only free slots of your plan are used; nothing is bought. Tags are put on every added or already-present site. With one url: 201 when added, 200 when it was already there, 409 no_plan or plan_full otherwise. With urls: 200 and one result per entry, in order (added, already, invalid, duplicate, no_slot, no_plan). dry_run: true previews without adding.
Everything in the list, plus the AI crawler breakdown, the daily security checks (HTTPS redirect, HSTS, headers, exposed .env or .git), the 5 most recent outages and the 10 most recent alerts.
Takes the site out of your plan; its slot is free at once. A paid report month keeps it monitored to its end (monitoring: true); a site nothing covers any more is deleted with its history (deleted: true).
The 5-minute uptime check: state now, 30-day uptime, the last response time (null until measured) and the last 30 UTC days one by one, oldest first. Days before the site was added are null.
Puts tags on (op add; names are created when missing) or takes them off (op remove) up to 300 sites, by host, and servers, by id, in one call. Unknown hosts and ids come back in not_found.
Servers running the agent: their numbers now, open alerts, the full detail, and enrollment keys to add machines.
GET/api/v1/serversScope: readpaged
List servers
Your servers with their numbers now (CPU, load, memory, the fullest disk and when it fills up), how many alerts, security signals and notices are open, tags, and the server quota of your plans.
Parameters
status
pending, up, silent or paused
tag
only items with this tag; repeat or comma-separate for any of several
Everything the server page shows, in its own contract: overview (availability, outages, reboots), security (ports explained, SSH, logins, firewall, updates, recommendations, score), resources with chart series for the range, events and the agent. Times inside are Unix seconds.
A new enrollment key. Its secret and the install line are in this answer only; run the line on each machine (Ansible, cloud-init…). Machines beyond your server quota are paused.
Start free scans, follow them, read reports and open one with a credit you already have.
GET/api/v1/scansScope: readpaged
List scans
Scans you started through the API or while signed in, and reports bought with your e‑mail address, newest first: score and verdict (null until done, or when the site blocked us), what is unlocked until when, and the deep scan an unlock started.
Starts the free scan of a site, as the home page does. It takes a few minutes: poll GET /scans/:id. A site scanned in the last 20 minutes gives that scan back (cached: true).
Progress while the scan runs (stage, percent, place in the queue), then score, verdict and the report summary. The pages and parameters behind a finding are included only when your account has the site unlocked (or while every report is free).
Opens the full report of a finished scan with a site credit your account already has: 30 days, a deep re-crawl and unlimited rescans. It never charges you: a site already open costs nothing (already: true), and with no credits left it answers 402 no_credits.
Score, verdict, issue counts by severity, category scores and every failing finding with its title and severity; evidence only where your account has the site unlocked.
Runs the free “Can AI see your site?” check of one homepage (about 20 seconds) and returns the full result: each AI crawler's robots.txt rule and simulated request, meta directives, llms.txt and the sitemap. 201 for a new check, 200 for a cached one. Read-only keys may run it.
Where your alerts go: the account e‑mail, extra e‑mail addresses, Slack, Telegram, Discord and webhooks, with the alert families, minimum severity, tags, quiet hours and digest of each. Secrets are never sent: targets are masked. Change them on the account page.
Webhook destinations (set up on your account page, listed by GET /alert-channels) get each alert as a JSON POST, signed with the secret shown when you created or rotated the webhook. The X-Approvalens-Signature header looks like t=1791273600,v1=5f2c…: t is the Unix time it was sent, v1 the hex HMAC-SHA256 of the time, a dot and the raw body, with your secret as the key.
Compute the same HMAC over the raw body (before you parse it), compare in constant time, and refuse a t older than 5 minutes. X-Approvalens-Delivery stays the same on retries, so you can drop duplicates.
Node.js
import crypto from "node:crypto";
// header: the X-Approvalens-Signature value; raw: the request body as received (a Buffer)
export function verify(secret, header, raw) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
const t = Number(parts.t);
if (!t || Date.now() / 1000 - t > 300) return false; // older than 5 minutes
const want = crypto.createHmac("sha256", secret).update(`${t}.`).update(raw).digest("hex");
const got = String(parts.v1 || "");
return got.length === want.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(want));
}
Python
import hashlib, hmac, time
def verify(secret: str, header: str, raw: bytes) -> bool:
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t = int(parts.get("t", "0") or 0)
if not t or time.time() - t > 300: # older than 5 minutes
return False
want = hmac.new(secret.encode(), f"{t}.".encode() + raw, hashlib.sha256).hexdigest()
return hmac.compare_digest(parts.get("v1", ""), want)
The whole API as an OpenAPI 3.1 document: every endpoint, parameter, body and answer with its schema and example, generated from the same code as this page. Load it into Postman, Insomnia or a code generator.
v1.1 · 2026-10-07Write access and more: add, tag and remove sites in bulk, site filters and uptime, tags, servers and enrollment keys, scans and unlock with a credit, account, alert destinations. Key scopes (keys made before are read-only), a burst limit, idempotency keys, cursors and OpenAPI. The API now comes with every paid plan, server plans included.