Skip to content
Approvalens

Developers · API v1

REST API

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.

Create a keyOpenAPI 3.1

Quickstart

Base URL

https://approvalens.com/api/v1

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.

  1. Sign in. Any paid plan includes the API: a site plan or a server plan.

  2. Open Account → API keys and create a key. Choose "Read and write" if your script should change things. Copy it: it is shown once.

  3. 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
export APPROVALENS_KEY=al_live_…

curl https://approvalens.com/api/v1/account \
  -H "Authorization: Bearer $APPROVALENS_KEY"
2. Add up to 300 sites at once, with a tag (send dry_run first to preview)
curl -X POST https://approvalens.com/api/v1/sites \
  -H "Authorization: Bearer $APPROVALENS_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["example.com", "news.example.net"], "tags": ["client:acme"], "dry_run": true}'
3. Find sites with a problem, e.g. a missing ads.txt
curl "https://approvalens.com/api/v1/sites?signal=ads_txt_problem" \
  -H "Authorization: Bearer $APPROVALENS_KEY"
4. Start a scan and poll it until status is done
id=$(curl -s -X POST https://approvalens.com/api/v1/scans -H "Authorization: Bearer $APPROVALENS_KEY" \
  -H "Content-Type: application/json" -d '{"url": "example.com"}' | jq -r .scan.id)

while [ "$(curl -s https://approvalens.com/api/v1/scans/$id -H "Authorization: Bearer $APPROVALENS_KEY" | jq -r .scan.status)" != "done" ]; do sleep 15; done

Authentication and access

Included with every paid plan

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:

Authorization: Bearer al_live_••••••••••••••••••••••••••••••••

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.

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.

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."
}

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.

cursor=""
while :; do
  page=$(curl -s "https://approvalens.com/api/v1/sites?limit=300${cursor:+&cursor=$cursor}" -H "Authorization: Bearer $APPROVALENS_KEY")
  echo "$page" | jq -r '.sites[].host'
  cursor=$(echo "$page" | jq -r '.next_cursor // empty')
  [ -z "$cursor" ] && break
done

Idempotency keys

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.

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.

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
    }
  }
}
CodeStatusMeaning
bad_request400A parameter or the JSON body is not valid; message names the field.
bad_url400Not a public website address we can scan or monitor.
invalid_key401The key is malformed, unknown or revoked.
missing_key401No Authorization: Bearer header.
no_credits402Unlocking needs a site credit and the account has none. Nothing was charged.
insufficient_scope403The key is read-only and the endpoint changes something. details.required names the scope.
subscription_required403The account has no active paid plan. The same keys work again once it has one.
not_found404No such endpoint, or nothing with that id or host on your account.
idempotency_in_progress409A request with this Idempotency-Key is still running.
limit_reached409Too many active enrollment keys.
no_plan409Adding a site needs a live site plan.
not_ready409The scan has not finished yet.
plan_full409Every slot of the site plan is taken; details.plan has the numbers.
tag_exists409A tag with this name already exists.
tag_limit409The account would have more than 100 tags.
idempotency_key_reused422The Idempotency-Key was used for a different request.
unreachable422The site's name does not resolve or the site did not answer.
rate_limited429Too many requests: wait Retry-After seconds.
unavailable503Our side failed. Try again shortly.

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.

Example request
curl https://approvalens.com/api/v1/account \
  -H "Authorization: Bearer $APPROVALENS_KEY"
Example response · 200
{
  "account": {
    "email": "you@example.com",
    "key": {
      "id": 9,
      "prefix": "al_live_7Gk2",
      "scopes": [
        "read",
        "write"
      ]
    },
    "plans": {
      "site": {
        "status": "active",
        "limit": 25,
        "used": 2,
        "free": 23,
        "renews_at": "2026-10-25T08:00:00Z",
        "ends_at": null
      },
      "server": {
        "status": "active",
        "limit": 5,
        "used": 2,
        "free": 3,
        "renews_at": "2026-10-25T08:00:00Z",
        "ends_at": null
      }
    },
    "sites": {
      "limit": 25,
      "used": 2,
      "free": 23,
      "over_plan": 0,
      "included": 0
    },
    "servers": {
      "quota": 6,
      "used": 2
    },
    "credits": {
      "balance": 3,
      "billing": "live"
    }
  }
}

Errors: invalid_key, missing_key, subscription_required, rate_limited, unavailable

Sites

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
q
part of the host name
limit
page size, 1–300 (default 100)
cursor
next_cursor of the previous page
lang
en (default) or tr: language of the text fields
Example request
curl "https://approvalens.com/api/v1/sites?tag=wordpress&signal=ads_txt_problem&limit=50" \
  -H "Authorization: Bearer $APPROVALENS_KEY"
Example response · 200
{
  "sites": [
    {
      "id": 1,
      "host": "example.com",
      "url": "https://example.com/",
      "status": "up",
      "monitoring": true,
      "in_plan": true,
      "plan": {
        "status": "active",
        "source": "plan",
        "state": "active",
        "renews_at": "2026-10-25T08:00:00Z",
        "ends_at": null,
        "included_until": null,
        "test": false
      },
      "tags": [
        "client:acme",
        "wordpress"
      ],
      "uptime_30d": 99.94,
      "response_ms": null,
      "tls_valid": true,
      "tls_days_left": 41,
      "tls_expires_at": "2026-11-16T12:00:00Z",
      "ads_txt": "found",
      "signals": {
        "ads_txt": "ok",
        "pubs_missing": [],
        "mediapartners": "ok",
        "googlebot": "ok",
        "noindex": false,
        "ai_blocked_new": [
          "GPTBot"
        ],
        "ai_blocked_at": "2026-10-04T08:00:00Z"
      },
      "ai_allowed": 11,
      "ai_total": 14,
      "last_check": "2026-10-06T03:00:00Z",
      "next_check": "2026-10-07T03:00:00Z",
      "last_uptime_probe": "2026-10-06T07:58:00Z",
      "open_incident": null,
      "alerts_enabled": true
    },
    {
      "id": 2,
      "host": "recipes.example.org",
      "url": "https://recipes.example.org/",
      "status": "up",
      "monitoring": true,
      "in_plan": true,
      "plan": {
        "status": "active",
        "source": "plan",
        "state": "active",
        "renews_at": "2026-10-25T08:00:00Z",
        "ends_at": null,
        "included_until": null,
        "test": false
      },
      "tags": [
        "wordpress"
      ],
      "uptime_30d": 100,
      "response_ms": null,
      "tls_valid": true,
      "tls_days_left": 41,
      "tls_expires_at": "2026-11-16T12:00:00Z",
      "ads_txt": "missing",
      "signals": {
        "ads_txt": "missing",
        "pubs_missing": [],
        "mediapartners": "ok",
        "googlebot": "ok",
        "noindex": false,
        "ai_blocked_new": [],
        "ai_blocked_at": null
      },
      "ai_allowed": 14,
      "ai_total": 14,
      "last_check": "2026-10-06T03:00:00Z",
      "next_check": "2026-10-07T03:00:00Z",
      "last_uptime_probe": "2026-10-06T07:58:30Z",
      "open_incident": null,
      "alerts_enabled": true
    }
  ],
  "total": 2,
  "next_cursor": null
}

Errors: bad_request, invalid_key, missing_key, subscription_required, rate_limited, unavailable

POST/api/v1/sitesScope: write

Add sites

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.

Parameters

lang
en (default) or tr: language of the text fields
Example request
curl -X POST https://approvalens.com/api/v1/sites \
  -H "Authorization: Bearer $APPROVALENS_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"urls":["example.com","news.example.net","https://shop.example.net/products","not a site"],"tags":["client:acme"]}'
Example response · 200
{
  "dry_run": false,
  "results": [
    {
      "input": "example.com",
      "host": "example.com",
      "status": "already",
      "id": 1
    },
    {
      "input": "news.example.net",
      "host": "news.example.net",
      "status": "added",
      "id": 31
    },
    {
      "input": "https://shop.example.net/products",
      "host": "shop.example.net",
      "status": "added",
      "id": 32
    },
    {
      "input": "not a site",
      "host": null,
      "status": "invalid",
      "reason": "bad_url"
    }
  ],
  "summary": {
    "already": 1,
    "added": 2,
    "invalid": 1
  },
  "plan": {
    "limit": 25,
    "used": 4,
    "free": 21
  }
}
Also answers · 201
{
  "dry_run": false,
  "results": [
    {
      "input": "news.example.net",
      "host": "news.example.net",
      "status": "added",
      "id": 31
    }
  ],
  "summary": {
    "added": 1
  },
  "plan": {
    "limit": 25,
    "used": 3,
    "free": 22
  }
}

Errors: bad_request, bad_url, invalid_key, missing_key, insufficient_scope, subscription_required, idempotency_in_progress, no_plan, plan_full, tag_limit, idempotency_key_reused, unreachable, rate_limited, unavailable

POST/api/v1/sites/removeScope: write

Remove sites

Takes up to 300 sites out of your plan in one call (as DELETE does for one). Hosts that are not on your account come back in not_found.

Example request
curl -X POST https://approvalens.com/api/v1/sites/remove \
  -H "Authorization: Bearer $APPROVALENS_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"hosts":["recipes.example.org","news.example.net","old.example.com"]}'
Example response · 200
{
  "removed": [
    "recipes.example.org",
    "news.example.net"
  ],
  "deleted": [
    "recipes.example.org",
    "news.example.net"
  ],
  "not_found": [
    "old.example.com"
  ]
}

Errors: bad_request, invalid_key, missing_key, insufficient_scope, subscription_required, idempotency_in_progress, idempotency_key_reused, rate_limited, unavailable

GET/api/v1/sites/{host}Scope: read

One site

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.

Parameters

host
the site's host, with or without www
lang
en (default) or tr: language of the text fields
Example request
curl https://approvalens.com/api/v1/sites/example.com \
  -H "Authorization: Bearer $APPROVALENS_KEY"
Example response · 200
{
  "site": {
    "id": 1,
    "host": "example.com",
    "url": "https://example.com/",
    "status": "up",
    "monitoring": true,
    "in_plan": true,
    "plan": {
      "status": "active",
      "source": "plan",
      "state": "active",
      "renews_at": "2026-10-25T08:00:00Z",
      "ends_at": null,
      "included_until": null,
      "test": false
    },
    "tags": [
      "client:acme",
      "wordpress"
    ],
    "uptime_30d": 99.94,
    "response_ms": null,
    "tls_valid": true,
    "tls_days_left": 41,
    "tls_expires_at": "2026-11-16T12:00:00Z",
    "ads_txt": "found",
    "signals": {
      "ads_txt": "ok",
      "pubs_missing": [],
      "mediapartners": "ok",
      "googlebot": "ok",
      "noindex": false,
      "ai_blocked_new": [
        "GPTBot"
      ],
      "ai_blocked_at": "2026-10-04T08:00:00Z"
    },
    "ai_allowed": 11,
    "ai_total": 14,
    "last_check": "2026-10-06T03:00:00Z",
    "next_check": "2026-10-07T03:00:00Z",
    "last_uptime_probe": "2026-10-06T07:58:00Z",
    "open_incident": null,
    "alerts_enabled": true,
    "ai_crawlers": {
      "allowed": 11,
      "blocked_by_robots": 2,
      "blocked_by_server": 1,
      "unknown": 0,
      "total": 14
    },
    "security": {
      "https_redirect": true,
      "hsts": true,
      "headers": [
        "nosniff",
        "frame"
      ],
      "files_checked": [
        "env",
        "git_head"
      ],
      "exposed": []
    },
    "pending_confirmation": [],
    "latest_check_url": "https://approvalens.com/ai/Xk2v9QmL0pRa",
    "incidents": [
      {
        "id": 12,
        "started_at": "2026-10-03T08:00:00Z",
        "ended_at": "2026-10-03T08:25:00Z",
        "ongoing": false,
        "duration_seconds": 1500,
        "reason": "http_502",
        "http_status": 502,
        "description": "HTTP 502"
      }
    ],
    "alerts": [
      {
        "id": 87,
        "at": "2026-10-03T08:25:00Z",
        "kind": "up",
        "emailed": true,
        "lines": [
          "Your homepage answers again. It was down for 25 minutes (Oct 3, 2026 08:00 UTC – Oct 3, 2026 08:25 UTC). Reason seen: HTTP 502."
        ],
        "check_id": null
      },
      {
        "id": 86,
        "at": "2026-10-03T08:10:00Z",
        "kind": "down",
        "emailed": true,
        "lines": [
          "example.com is down · HTTP 502"
        ],
        "check_id": null
      }
    ]
  }
}

Errors: bad_request, invalid_key, missing_key, subscription_required, not_found, rate_limited, unavailable

PATCH/api/v1/sites/{host}Scope: write

Tag a site, switch its alerts

Adds and removes tags (names are created when missing) and switches the site's e‑mail alerts on or off. Answers the site as GET does.

Parameters

host
the site's host, with or without www
lang
en (default) or tr: language of the text fields
Example request
curl -X PATCH https://approvalens.com/api/v1/sites/example.com \
  -H "Authorization: Bearer $APPROVALENS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"add_tags":["client:acme"],"remove_tags":["old-theme"],"alerts_enabled":true}'
Example response · 200
{
  "site": {
    "id": 1,
    "host": "example.com",
    "url": "https://example.com/",
    "status": "up",
    "monitoring": true,
    "in_plan": true,
    "plan": {
      "status": "active",
      "source": "plan",
      "state": "active",
      "renews_at": "2026-10-25T08:00:00Z",
      "ends_at": null,
      "included_until": null,
      "test": false
    },
    "tags": [
      "client:acme",
      "wordpress"
    ],
    "uptime_30d": 99.94,
    "response_ms": null,
    "tls_valid": true,
    "tls_days_left": 41,
    "tls_expires_at": "2026-11-16T12:00:00Z",
    "ads_txt": "found",
    "signals": {
      "ads_txt": "ok",
      "pubs_missing": [],
      "mediapartners": "ok",
      "googlebot": "ok",
      "noindex": false,
      "ai_blocked_new": [
        "GPTBot"
      ],
      "ai_blocked_at": "2026-10-04T08:00:00Z"
    },
    "ai_allowed": 11,
    "ai_total": 14,
    "last_check": "2026-10-06T03:00:00Z",
    "next_check": "2026-10-07T03:00:00Z",
    "last_uptime_probe": "2026-10-06T07:58:00Z",
    "open_incident": null,
    "alerts_enabled": true,
    "ai_crawlers": {
      "allowed": 11,
      "blocked_by_robots": 2,
      "blocked_by_server": 1,
      "unknown": 0,
      "total": 14
    },
    "security": {
      "https_redirect": true,
      "hsts": true,
      "headers": [
        "nosniff",
        "frame"
      ],
      "files_checked": [
        "env",
        "git_head"
      ],
      "exposed": []
    },
    "pending_confirmation": [],
    "latest_check_url": "https://approvalens.com/ai/Xk2v9QmL0pRa",
    "incidents": [
      {
        "id": 12,
        "started_at": "2026-10-03T08:00:00Z",
        "ended_at": "2026-10-03T08:25:00Z",
        "ongoing": false,
        "duration_seconds": 1500,
        "reason": "http_502",
        "http_status": 502,
        "description": "HTTP 502"
      }
    ],
    "alerts": [
      {
        "id": 87,
        "at": "2026-10-03T08:25:00Z",
        "kind": "up",
        "emailed": true,
        "lines": [
          "Your homepage answers again. It was down for 25 minutes (Oct 3, 2026 08:00 UTC – Oct 3, 2026 08:25 UTC). Reason seen: HTTP 502."
        ],
        "check_id": null
      },
      {
        "id": 86,
        "at": "2026-10-03T08:10:00Z",
        "kind": "down",
        "emailed": true,
        "lines": [
          "example.com is down · HTTP 502"
        ],
        "check_id": null
      }
    ]
  }
}

Errors: bad_request, invalid_key, missing_key, insufficient_scope, subscription_required, not_found, tag_limit, rate_limited, unavailable

DELETE/api/v1/sites/{host}Scope: write

Remove a site

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).

Parameters

host
the site's host, with or without www
Example request
curl -X DELETE https://approvalens.com/api/v1/sites/recipes.example.org \
  -H "Authorization: Bearer $APPROVALENS_KEY"
Example response · 200
{
  "id": 2,
  "host": "recipes.example.org",
  "deleted": true,
  "monitoring": false
}

Errors: bad_request, invalid_key, missing_key, insufficient_scope, subscription_required, not_found, rate_limited, unavailable

GET/api/v1/sites/{host}/uptimeScope: read

Uptime of a site

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.

Parameters

host
the site's host, with or without www
Example request
curl https://approvalens.com/api/v1/sites/example.com/uptime \
  -H "Authorization: Bearer $APPROVALENS_KEY"
Example response · 200
{
  "host": "example.com",
  "status": "up",
  "monitoring": true,
  "uptime_30d": 99.94,
  "response_ms": null,
  "last_probe": "2026-10-06T07:58:00Z",
  "monitored_since": "2026-08-26T08:00:00Z",
  "days": [
    {
      "date": "2026-09-07",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-09-08",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-09-09",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-09-10",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-09-11",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-09-12",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-09-13",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-09-14",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-09-15",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-09-16",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-09-17",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-09-18",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-09-19",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-09-20",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-09-21",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-09-22",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-09-23",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-09-24",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-09-25",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-09-26",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-09-27",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-09-28",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-09-29",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-09-30",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-10-01",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-10-02",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-10-03",
      "uptime_pct": 98.26,
      "downtime_seconds": 1500
    },
    {
      "date": "2026-10-04",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-10-05",
      "uptime_pct": 100,
      "downtime_seconds": 0
    },
    {
      "date": "2026-10-06",
      "uptime_pct": 100,
      "downtime_seconds": 0
    }
  ]
}

Errors: bad_request, invalid_key, missing_key, subscription_required, not_found, rate_limited, unavailable

GET/api/v1/sites/{host}/incidentsScope: read

Outages of a site

Outages that ended after since or are still going on, newest first. An outage opens after two failed checks in a row.

Parameters

host
the site's host, with or without www
since
ISO-8601 date or time; default 30 days ago
limit
1–500, default 100
lang
en (default) or tr: language of the text fields
Example request
curl "https://approvalens.com/api/v1/sites/example.com/incidents?since=2026-09-06" \
  -H "Authorization: Bearer $APPROVALENS_KEY"
Example response · 200
{
  "host": "example.com",
  "since": "2026-09-06T08:00:00Z",
  "incidents": [
    {
      "id": 12,
      "started_at": "2026-10-03T08:00:00Z",
      "ended_at": "2026-10-03T08:25:00Z",
      "ongoing": false,
      "duration_seconds": 1500,
      "reason": "http_502",
      "http_status": 502,
      "description": "HTTP 502"
    }
  ]
}

Errors: bad_request, invalid_key, missing_key, subscription_required, not_found, rate_limited, unavailable

Tags

Your own labels on sites and servers: create, rename, delete, and put on many items at once.

GET/api/v1/tagsScope: read

List tags

Your tags with the ids of the sites and servers that carry them.

Example request
curl https://approvalens.com/api/v1/tags \
  -H "Authorization: Bearer $APPROVALENS_KEY"
Example response · 200
{
  "tags": [
    {
      "id": 3,
      "name": "client:acme",
      "color": "blue",
      "created_at": "2026-09-06T08:00:00Z",
      "site_ids": [
        1
      ],
      "server_ids": []
    },
    {
      "id": 4,
      "name": "wordpress",
      "color": "green",
      "created_at": "2026-09-06T08:00:00Z",
      "site_ids": [
        1,
        2
      ],
      "server_ids": [
        21
      ]
    }
  ]
}

Errors: invalid_key, missing_key, subscription_required, rate_limited, unavailable

POST/api/v1/tagsScope: write

Create a tag

A new tag. Names are stored lower-case: 1–32 letters, digits, space or - _ : . / &.

Example request
curl -X POST https://approvalens.com/api/v1/tags \
  -H "Authorization: Bearer $APPROVALENS_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"client:acme","color":"blue"}'
Example response · 201
{
  "tag": {
    "id": 3,
    "name": "client:acme",
    "color": "blue",
    "created_at": "2026-09-06T08:00:00Z",
    "site_ids": [
      1
    ],
    "server_ids": []
  }
}

Errors: bad_request, invalid_key, missing_key, insufficient_scope, subscription_required, idempotency_in_progress, tag_exists, tag_limit, idempotency_key_reused, rate_limited, unavailable

PATCH/api/v1/tags/{id}Scope: write

Rename or recolour a tag

Changes the name, the colour or both.

Parameters

id
the tag id
Example request
curl -X PATCH https://approvalens.com/api/v1/tags/3 \
  -H "Authorization: Bearer $APPROVALENS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"color":"blue"}'
Example response · 200
{
  "tag": {
    "id": 3,
    "name": "client:acme",
    "color": "blue",
    "created_at": "2026-09-06T08:00:00Z",
    "site_ids": [
      1
    ],
    "server_ids": []
  }
}

Errors: bad_request, invalid_key, missing_key, insufficient_scope, subscription_required, not_found, tag_exists, rate_limited, unavailable

POST/api/v1/tags/assignScope: write

Tag many sites and servers

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.

Example request
curl -X POST https://approvalens.com/api/v1/tags/assign \
  -H "Authorization: Bearer $APPROVALENS_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"op":"add","tags":["wordpress"],"sites":["example.com","recipes.example.org","old.example.com"],"servers":[21]}'
Example response · 200
{
  "op": "add",
  "tag_ids": [
    4
  ],
  "sites": {
    "updated": [
      "example.com",
      "recipes.example.org"
    ],
    "not_found": [
      "old.example.com"
    ]
  },
  "servers": {
    "updated": [
      21
    ],
    "not_found": []
  }
}

Errors: bad_request, invalid_key, missing_key, insufficient_scope, subscription_required, not_found, idempotency_in_progress, tag_limit, idempotency_key_reused, rate_limited, unavailable

Servers

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
limit
page size, 1–300 (default 100)
cursor
next_cursor of the previous page
Example request
curl https://approvalens.com/api/v1/servers \
  -H "Authorization: Bearer $APPROVALENS_KEY"
Example response · 200
{
  "servers": [
    {
      "id": 21,
      "name": "web-1",
      "status": "up",
      "paused_reason": null,
      "hostname": "web-1.example.net",
      "os": "Ubuntu 24.04.1 LTS",
      "arch": "x86_64",
      "agent_version": "0.3.0",
      "created_at": "2026-09-16T08:00:00Z",
      "first_seen_at": "2026-09-16T08:05:00Z",
      "last_seen_at": "2026-10-06T07:59:20Z",
      "learning_until": null,
      "tags": [
        "wordpress"
      ],
      "current": {
        "at": "2026-10-06T07:59:20Z",
        "cpu_pct": 23.4,
        "load": [
          0.82,
          0.71,
          0.64
        ],
        "cores": 4,
        "mem_pct": 61.2,
        "swap_pct": 3.1,
        "disk_max_pct": 74,
        "disk_full_in_hours": 4600,
        "uptime_seconds": 1814400,
        "processes": 214
      },
      "open": {
        "alerts": 0,
        "security_signals": 1,
        "notices": 1
      }
    },
    {
      "id": 22,
      "name": "db-1",
      "status": "silent",
      "paused_reason": null,
      "hostname": "db-1.example.net",
      "os": "Ubuntu 24.04.1 LTS",
      "arch": "x86_64",
      "agent_version": "0.3.0",
      "created_at": "2026-09-16T08:00:00Z",
      "first_seen_at": "2026-09-16T08:05:00Z",
      "last_seen_at": "2026-10-06T06:00:00Z",
      "learning_until": null,
      "tags": [],
      "current": {
        "at": "2026-10-06T07:59:20Z",
        "cpu_pct": 23.4,
        "load": [
          0.82,
          0.71,
          0.64
        ],
        "cores": 4,
        "mem_pct": 61.2,
        "swap_pct": 3.1,
        "disk_max_pct": 74,
        "disk_full_in_hours": 4600,
        "uptime_seconds": 1814400,
        "processes": 214
      },
      "open": {
        "alerts": 0,
        "security_signals": 0,
        "notices": 0
      }
    }
  ],
  "quota": 6,
  "used": 2,
  "total": 2,
  "next_cursor": null
}

Errors: bad_request, invalid_key, missing_key, subscription_required, rate_limited, unavailable

GET/api/v1/servers/{id}Scope: read

One server

The list entry plus every disk, the open alerts, security signals and notices with their text, recent events and the security settings check.

Parameters

id
the server id
Example request
curl https://approvalens.com/api/v1/servers/21 \
  -H "Authorization: Bearer $APPROVALENS_KEY"
Example response · 200
{
  "server": {
    "id": 21,
    "name": "web-1",
    "status": "up",
    "paused_reason": null,
    "hostname": "web-1.example.net",
    "os": "Ubuntu 24.04.1 LTS",
    "arch": "x86_64",
    "agent_version": "0.3.0",
    "created_at": "2026-09-16T08:00:00Z",
    "first_seen_at": "2026-09-16T08:05:00Z",
    "last_seen_at": "2026-10-06T07:59:20Z",
    "learning_until": null,
    "tags": [
      "wordpress"
    ],
    "current": {
      "at": "2026-10-06T07:59:20Z",
      "cpu_pct": 23.4,
      "load": [
        0.82,
        0.71,
        0.64
      ],
      "cores": 4,
      "mem_pct": 61.2,
      "swap_pct": 3.1,
      "disk_max_pct": 74,
      "disk_full_in_hours": 4600,
      "uptime_seconds": 1814400,
      "processes": 214
    },
    "open": {
      "alerts": 0,
      "security_signals": 1,
      "notices": 1
    },
    "disks": [
      {
        "mount": "/",
        "fs": "ext4",
        "total_bytes": 160000000000,
        "used_bytes": 118400000000,
        "pct": 74,
        "full_in_hours": 4600
      }
    ],
    "alerts": [],
    "security_signals": [
      {
        "id": 501,
        "kind": "new_port",
        "at": "2026-10-06T03:00:00Z",
        "ended_at": null,
        "acknowledged_at": null,
        "emailed": true,
        "security": true,
        "lines": [
          "A new public port is open: 8080/tcp (node)."
        ]
      }
    ],
    "notices": [
      {
        "id": 495,
        "kind": "updates",
        "at": "2026-10-05T08:00:00Z",
        "ended_at": null,
        "acknowledged_at": null,
        "emailed": false,
        "security": false,
        "lines": [
          "12 package updates are waiting, 3 of them security updates."
        ]
      }
    ],
    "recent_events": [
      {
        "id": 480,
        "kind": "silent",
        "at": "2026-10-02T08:00:00Z",
        "ended_at": "2026-10-02T08:20:00Z",
        "acknowledged_at": null,
        "emailed": true,
        "security": false,
        "lines": [
          "web-1 sent nothing for 20 minutes."
        ]
      }
    ],
    "posture": [
      {
        "key": "ssh_password",
        "status": "warn",
        "label": "SSH accepts passwords",
        "detail": "PasswordAuthentication is yes in sshd_config.",
        "acknowledged": false
      }
    ],
    "posture_at": "2026-10-06T07:00:00Z"
  }
}

Errors: invalid_key, missing_key, subscription_required, not_found, rate_limited, unavailable

GET/api/v1/servers/{id}/detailScope: read

Server detail

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.

Parameters

id
the server id
range
chart range: 1h, 24h (default), 7d or 30d
lang
en (default) or tr: language of the text fields
Example request
curl "https://approvalens.com/api/v1/servers/21/detail?range=7d" \
  -H "Authorization: Bearer $APPROVALENS_KEY"
Example response · 200
{
  "detail": {
    "id": 21,
    "name": "web-1",
    "range": "24h",
    "overview": {
      "hostname": "web-1.example.net",
      "os": "Ubuntu 24.04.1 LTS",
      "kernel": "6.8.0-45-generic",
      "arch": "x86_64",
      "virt": "kvm",
      "cores": 4,
      "mem_total": 8000000000,
      "uptime_s": 1814400,
      "first_seen": 1789545900,
      "last_seen": 1791273560,
      "status": "up",
      "availability": {
        "d1": 100,
        "d7": 99.9,
        "d30": 99.8
      },
      "outages": [],
      "reboots": []
    },
    "security": {
      "summary": {
        "level": "warn",
        "bad": 0,
        "warn": 2,
        "ok": 14
      },
      "score": {
        "value": 82,
        "grade": "B"
      },
      "ports": [
        {
          "proto": "tcp",
          "port": 22,
          "addr": "0.0.0.0",
          "public": true,
          "process": "sshd",
          "service": "SSH",
          "purpose": "Remote login.",
          "advice": "Keep it; allow keys only.",
          "level": "ok",
          "reachable": true
        }
      ]
    },
    "resources": {
      "current": {
        "cpu": 23.4,
        "load": [
          0.82,
          0.71,
          0.64
        ],
        "mem_pct": 61.2,
        "swap_pct": 3.1,
        "procs": 214
      },
      "series": {
        "cpu": [
          [
            1791273000,
            21.2
          ],
          [
            1791273300,
            23.4
          ]
        ]
      }
    },
    "events": [
      {
        "id": 501,
        "at": 1791255600,
        "kind": "new_port",
        "level": "warn",
        "title": "New public port 8080/tcp",
        "acked": false,
        "emailed": true
      }
    ],
    "agent": {
      "version": "0.3.0",
      "latest": "0.3.0",
      "mode": "detailed",
      "cpu_pct": 0.05,
      "rss": 17000000,
      "sent_kb_day": 240
    }
  }
}

Errors: bad_request, invalid_key, missing_key, subscription_required, not_found, rate_limited, unavailable

GET/api/v1/servers/enroll-keysScope: read

List enrollment keys

Your enrollment keys: one key installs the agent on many machines, each becoming a server. The secret is never listed.

Example request
curl https://approvalens.com/api/v1/servers/enroll-keys \
  -H "Authorization: Bearer $APPROVALENS_KEY"
Example response · 200
{
  "keys": [
    {
      "id": 7,
      "name": "ansible",
      "prefix": "alek_Qm81xZ",
      "created_at": "2026-09-26T08:00:00Z",
      "last_used_at": "2026-10-04T08:00:00Z",
      "uses": 14,
      "revoked_at": null,
      "active": true
    }
  ]
}

Errors: invalid_key, missing_key, subscription_required, rate_limited, unavailable

POST/api/v1/servers/enroll-keysScope: write

Create an enrollment key

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.

Example request
curl -X POST https://approvalens.com/api/v1/servers/enroll-keys \
  -H "Authorization: Bearer $APPROVALENS_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"ansible"}'
Example response · 201
{
  "key": {
    "id": 7,
    "name": "ansible",
    "prefix": "alek_Qm81xZ",
    "created_at": "2026-09-26T08:00:00Z",
    "last_used_at": "2026-10-04T08:00:00Z",
    "uses": 14,
    "revoked_at": null,
    "active": true
  },
  "secret": "alek_Qm81xZ••••••••••••••••••••••••••••••••",
  "install_command": "curl -fsSL https://approvalens.com/agent/install.sh | sudo bash -s -- --enroll alek_Qm81xZ••••••••••••••••••••••••••••••••"
}

Errors: bad_request, invalid_key, missing_key, insufficient_scope, subscription_required, idempotency_in_progress, limit_reached, idempotency_key_reused, rate_limited, unavailable

DELETE/api/v1/servers/enroll-keys/{id}Scope: write

Revoke an enrollment key

No new machines can enroll with it; servers it already created keep reporting.

Parameters

id
the enrollment key id
Example request
curl -X DELETE https://approvalens.com/api/v1/servers/enroll-keys/7 \
  -H "Authorization: Bearer $APPROVALENS_KEY"
Example response · 200
{
  "key": {
    "id": 7,
    "name": "ansible",
    "prefix": "alek_Qm81xZ",
    "created_at": "2026-09-26T08:00:00Z",
    "last_used_at": "2026-10-04T08:00:00Z",
    "uses": 14,
    "revoked_at": "2026-10-06T08:00:00Z",
    "active": false
  }
}

Errors: bad_request, invalid_key, missing_key, insufficient_scope, subscription_required, not_found, rate_limited, unavailable

Scans and reports

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.

Parameters

status
queued, running, done, error or blocked
host
only scans of this host
limit
page size, 1–300 (default 100)
cursor
next_cursor of the previous page
Example request
curl https://approvalens.com/api/v1/scans \
  -H "Authorization: Bearer $APPROVALENS_KEY"
Example response · 200
{
  "scans": [
    {
      "id": "q7RkT2mYw9Lb3xNc",
      "host": "example.com",
      "url": "https://example.com/",
      "status": "done",
      "score": 78,
      "verdict": "almost",
      "created_at": "2026-10-04T08:00:00Z",
      "finished_at": "2026-10-04T08:06:50Z",
      "unlocked": true,
      "unlocked_until": "2026-11-03T08:00:00Z",
      "ai_unlocked_until": null,
      "deep_scan": {
        "id": "Hn4sP0dVe8KqZ1aY",
        "status": "done",
        "progress": 100
      },
      "report_url": "https://approvalens.com/scan/q7RkT2mYw9Lb3xNc"
    }
  ],
  "next_cursor": null
}

Errors: bad_request, invalid_key, missing_key, subscription_required, rate_limited, unavailable

POST/api/v1/scansScope: write

Start a scan

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).

Example request
curl -X POST https://approvalens.com/api/v1/scans \
  -H "Authorization: Bearer $APPROVALENS_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://recipes.example.org"}'
Example response · 202
{
  "scan": {
    "id": "Zt8mQ2xLp4Vn6RcA",
    "host": "recipes.example.org",
    "url": "https://recipes.example.org/",
    "status": "queued",
    "score": null,
    "verdict": null,
    "created_at": "2026-10-06T07:58:30Z",
    "finished_at": null,
    "progress": {
      "stage": "",
      "percent": 0,
      "queue_position": 1
    },
    "unlocked": false,
    "unlocked_until": null,
    "ai_unlocked": false,
    "ai_unlocked_until": null,
    "deep_scan": null,
    "report_url": "https://approvalens.com/scan/Zt8mQ2xLp4Vn6RcA",
    "summary": null
  },
  "cached": false
}

Errors: bad_request, bad_url, invalid_key, missing_key, insufficient_scope, subscription_required, idempotency_in_progress, idempotency_key_reused, unreachable, rate_limited, unavailable

GET/api/v1/scans/{id}Scope: read

One scan

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).

Parameters

id
the scan or report id
lang
en (default) or tr: language of the text fields
Example request
curl https://approvalens.com/api/v1/scans/q7RkT2mYw9Lb3xNc \
  -H "Authorization: Bearer $APPROVALENS_KEY"
Example response · 200
{
  "scan": {
    "id": "q7RkT2mYw9Lb3xNc",
    "host": "example.com",
    "url": "https://example.com/",
    "status": "done",
    "score": 78,
    "verdict": "almost",
    "created_at": "2026-10-04T08:00:00Z",
    "finished_at": "2026-10-04T08:06:50Z",
    "progress": null,
    "unlocked": true,
    "unlocked_until": "2026-11-03T08:00:00Z",
    "ai_unlocked": true,
    "ai_unlocked_until": null,
    "deep_scan": {
      "id": "Hn4sP0dVe8KqZ1aY",
      "status": "done",
      "progress": 100
    },
    "report_url": "https://approvalens.com/scan/q7RkT2mYw9Lb3xNc",
    "summary": {
      "counts": {
        "blocker": 0,
        "critical": 1,
        "warning": 3,
        "notice": 2,
        "pass": 74
      },
      "categories": [
        {
          "id": "content",
          "score": 71
        },
        {
          "id": "trust",
          "score": 90
        }
      ],
      "pages_scanned": 50,
      "findings": [
        {
          "id": "content.thin_pages",
          "title": "Thin articles",
          "category": "content",
          "severity": "critical",
          "level": "official",
          "evidence_total": 26,
          "unlocked": true,
          "params": {
            "thin": 26,
            "very_thin": 9,
            "of": 42,
            "pct": 62,
            "median": 131,
            "tools": 0
          },
          "evidence": [
            {
              "url": "https://example.com/recipes/quick-salsa/",
              "detail": "96 words"
            },
            {
              "url": "https://example.com/recipes/lemonade/",
              "detail": "118 words (+240 words of menus/footer)"
            }
          ]
        },
        {
          "id": "trust.contact_missing",
          "title": "Contact information",
          "category": "trust",
          "severity": "warning",
          "level": "official",
          "evidence_total": 0,
          "unlocked": true,
          "params": {},
          "evidence": []
        }
      ]
    }
  }
}
Also answers · 200
{
  "scan": {
    "id": "Zt8mQ2xLp4Vn6RcA",
    "host": "recipes.example.org",
    "url": "https://recipes.example.org/",
    "status": "running",
    "score": null,
    "verdict": null,
    "created_at": "2026-10-06T07:58:30Z",
    "finished_at": null,
    "progress": {
      "stage": "pages",
      "percent": 46,
      "queue_position": null
    },
    "unlocked": false,
    "unlocked_until": null,
    "ai_unlocked": false,
    "ai_unlocked_until": null,
    "deep_scan": null,
    "report_url": "https://approvalens.com/scan/Zt8mQ2xLp4Vn6RcA",
    "summary": null
  }
}

Errors: invalid_key, missing_key, subscription_required, not_found, rate_limited, unavailable

POST/api/v1/scans/{id}/unlockScope: write

Unlock a report with a credit

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.

Parameters

id
the scan or report id
Example request
curl -X POST https://approvalens.com/api/v1/scans/q7RkT2mYw9Lb3xNc/unlock \
  -H "Authorization: Bearer $APPROVALENS_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
Example response · 200
{
  "unlock": {
    "host": "example.com",
    "already": false,
    "free": false,
    "unlocked_until": "2026-11-05T08:00:00Z",
    "credits_left": 2,
    "deep_scan_id": "Hn4sP0dVe8KqZ1aY"
  }
}

Errors: bad_request, invalid_key, missing_key, no_credits, insufficient_scope, subscription_required, not_found, idempotency_in_progress, not_ready, idempotency_key_reused, rate_limited, unavailable

GET/api/v1/creditsScope: read

Your credits

The site credit balance and the sites the credits opened. While every report is free, billing is free and balance is null.

Example request
curl https://approvalens.com/api/v1/credits \
  -H "Authorization: Bearer $APPROVALENS_KEY"
Example response · 200
{
  "credits": {
    "billing": "live",
    "balance": 2,
    "unlocks": [
      {
        "host": "example.com",
        "scan_id": "q7RkT2mYw9Lb3xNc",
        "until": "2026-11-05T08:00:00Z",
        "active": true
      }
    ]
  }
}

Errors: invalid_key, missing_key, subscription_required, rate_limited, unavailable

GET/api/v1/reportsScope: readpaged

List reports

The same list as GET /scans, kept for clients written before it.

Parameters

limit
page size, 1–300 (default 100)
cursor
next_cursor of the previous page
Example request
curl https://approvalens.com/api/v1/reports \
  -H "Authorization: Bearer $APPROVALENS_KEY"
Example response · 200
{
  "reports": [
    {
      "id": "q7RkT2mYw9Lb3xNc",
      "host": "example.com",
      "url": "https://example.com/",
      "status": "done",
      "score": 78,
      "verdict": "almost",
      "created_at": "2026-10-04T08:00:00Z",
      "finished_at": "2026-10-04T08:06:50Z",
      "unlocked": true,
      "unlocked_until": "2026-11-03T08:00:00Z",
      "ai_unlocked_until": null,
      "deep_scan": {
        "id": "Hn4sP0dVe8KqZ1aY",
        "status": "done",
        "progress": 100
      },
      "report_url": "https://approvalens.com/scan/q7RkT2mYw9Lb3xNc"
    }
  ],
  "next_cursor": null
}

Errors: bad_request, invalid_key, missing_key, subscription_required, rate_limited, unavailable

GET/api/v1/reports/{id}Scope: read

One report

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.

Parameters

id
the scan or report id
lang
en (default) or tr: language of the text fields
Example request
curl https://approvalens.com/api/v1/reports/q7RkT2mYw9Lb3xNc \
  -H "Authorization: Bearer $APPROVALENS_KEY"
Example response · 200
{
  "report": {
    "id": "q7RkT2mYw9Lb3xNc",
    "host": "example.com",
    "url": "https://example.com/",
    "status": "done",
    "score": 78,
    "verdict": "almost",
    "created_at": "2026-10-04T08:00:00Z",
    "finished_at": "2026-10-04T08:06:50Z",
    "unlocked": true,
    "unlocked_until": "2026-11-03T08:00:00Z",
    "ai_unlocked": true,
    "ai_unlocked_until": null,
    "report_url": "https://approvalens.com/scan/q7RkT2mYw9Lb3xNc",
    "counts": {
      "blocker": 0,
      "critical": 1,
      "warning": 3,
      "notice": 2,
      "pass": 74
    },
    "categories": [
      {
        "id": "content",
        "score": 71
      },
      {
        "id": "trust",
        "score": 90
      }
    ],
    "pages_scanned": 50,
    "findings": [
      {
        "id": "content.thin_pages",
        "title": "Thin articles",
        "category": "content",
        "severity": "critical",
        "level": "official",
        "evidence_total": 26,
        "unlocked": true,
        "params": {
          "thin": 26,
          "very_thin": 9,
          "of": 42,
          "pct": 62,
          "median": 131,
          "tools": 0
        },
        "evidence": [
          {
            "url": "https://example.com/recipes/quick-salsa/",
            "detail": "96 words"
          },
          {
            "url": "https://example.com/recipes/lemonade/",
            "detail": "118 words (+240 words of menus/footer)"
          }
        ]
      },
      {
        "id": "trust.contact_missing",
        "title": "Contact information",
        "category": "trust",
        "severity": "warning",
        "level": "official",
        "evidence_total": 0,
        "unlocked": true,
        "params": {},
        "evidence": []
      }
    ]
  }
}

Errors: invalid_key, missing_key, subscription_required, not_found, rate_limited, unavailable

AI check

The free “Can AI see your site?” check.

POST/api/v1/ai-checksScope: read

Run an AI crawler check

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.

Example request
curl -X POST https://approvalens.com/api/v1/ai-checks \
  -H "Authorization: Bearer $APPROVALENS_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'
Example response · 201
{
  "check": {
    "id": "aic_7Qm2xK9pLs",
    "url": "greenleaf-journal.example",
    "final_url": "https://www.greenleaf-journal.example/",
    "host": "www.greenleaf-journal.example",
    "checked_at": "2026-10-06T12:45:00Z",
    "duration_ms": 17420,
    "cached": false,
    "headline": {
      "key": "blocked_server",
      "bot": "ChatGPT-User",
      "product": "ChatGPT"
    },
    "summary": {
      "allowed": 6,
      "blocked_robots": 4,
      "blocked_server": 3,
      "unknown": 1,
      "total": 14
    },
    "bots": [
      {
        "id": "oai-searchbot",
        "token": "OAI-SearchBot",
        "name": "OAI-SearchBot",
        "vendor": "OpenAI",
        "product": "ChatGPT",
        "purpose": "search",
        "kind": "fetcher",
        "doc_url": "https://developers.openai.com/api/docs/bots",
        "robots_respected": true,
        "robots": {
          "allowed": true,
          "group": "*",
          "rule": null
        },
        "http": {
          "simulated": true,
          "status": 200,
          "verdict": "ok",
          "reason": "200 OK, same page as a browser",
          "similarity": 0.98,
          "headers": {
            "content-type": "text/html; charset=utf-8"
          }
        },
        "verdict": "allowed"
      }
    ],
    "robots": {
      "url": "https://www.greenleaf-journal.example/robots.txt",
      "status": 200,
      "found": true,
      "unavailable": false,
      "excerpt": "User-agent: *\nDisallow: /wp-admin/\nAllow: /wp-admin/admin-ajax.php\n\nUser-agent: GPTBot\nDisallow: /\n\nUser-agent: CCBot\nDisallow: /\n\nUser-agent: Bytespider\nDisallow: /\n\nUser-agent: Google-Extended\nDisallow: /\n\nSitemap: https://www.greenleaf-journal.example/sitemap_index.xml"
    },
    "directives": {
      "meta": [
        {
          "name": "robots",
          "content": "index, follow, noai, noimageai"
        }
      ],
      "x_robots_tag": [],
      "flags": {
        "noai": true,
        "noimageai": true,
        "noindex": false,
        "nosnippet": false
      }
    },
    "js": {
      "raw_words": 412,
      "rendered_words": 1860,
      "ratio": 0.22,
      "verdict": "js_dependent",
      "reason": ""
    },
    "llms": {
      "url": "https://www.greenleaf-journal.example/llms.txt",
      "status": 200,
      "found": true,
      "content_type": "text/html; charset=utf-8",
      "h1": "Greenleaf Journal",
      "summary": null,
      "sections": 3,
      "links": 18,
      "problems": [
        {
          "code": "no_summary",
          "detail": "No blockquote summary after the H1",
          "line": 2
        },
        {
          "code": "content_type",
          "detail": "Served as text/html; expected text/plain or text/markdown",
          "line": null
        },
        {
          "code": "bad_list_item",
          "detail": "Several links on one list line",
          "line": 14
        }
      ]
    },
    "sitemap": {
      "sitemaps": [
        {
          "url": "https://www.greenleaf-journal.example/sitemap_index.xml",
          "status": 200,
          "valid": true,
          "blocked_for": [
            "gptbot",
            "ccbot",
            "bytespider",
            "google-extended"
          ]
        },
        {
          "url": "https://www.greenleaf-journal.example/post-sitemap.xml",
          "status": 200,
          "valid": true,
          "blocked_for": [
            "gptbot",
            "ccbot",
            "bytespider",
            "google-extended"
          ]
        }
      ],
      "sampled": 20,
      "resolved": 19,
      "problems": [
        {
          "code": "blocked_for_ai",
          "detail": "robots.txt blocks 4 AI crawlers from the URLs this sitemap lists"
        }
      ]
    },
    "result_url": "https://approvalens.com/ai/aic_7Qm2xK9pLs"
  }
}
Also answers · 200
{
  "check": {
    "id": "aic_7Qm2xK9pLs",
    "url": "greenleaf-journal.example",
    "final_url": "https://www.greenleaf-journal.example/",
    "host": "www.greenleaf-journal.example",
    "checked_at": "2026-10-06T12:45:00Z",
    "duration_ms": 17420,
    "cached": false,
    "headline": {
      "key": "blocked_server",
      "bot": "ChatGPT-User",
      "product": "ChatGPT"
    },
    "summary": {
      "allowed": 6,
      "blocked_robots": 4,
      "blocked_server": 3,
      "unknown": 1,
      "total": 14
    },
    "bots": [
      {
        "id": "oai-searchbot",
        "token": "OAI-SearchBot",
        "name": "OAI-SearchBot",
        "vendor": "OpenAI",
        "product": "ChatGPT",
        "purpose": "search",
        "kind": "fetcher",
        "doc_url": "https://developers.openai.com/api/docs/bots",
        "robots_respected": true,
        "robots": {
          "allowed": true,
          "group": "*",
          "rule": null
        },
        "http": {
          "simulated": true,
          "status": 200,
          "verdict": "ok",
          "reason": "200 OK, same page as a browser",
          "similarity": 0.98,
          "headers": {
            "content-type": "text/html; charset=utf-8"
          }
        },
        "verdict": "allowed"
      }
    ],
    "robots": {
      "url": "https://www.greenleaf-journal.example/robots.txt",
      "status": 200,
      "found": true,
      "unavailable": false,
      "excerpt": "User-agent: *\nDisallow: /wp-admin/\nAllow: /wp-admin/admin-ajax.php\n\nUser-agent: GPTBot\nDisallow: /\n\nUser-agent: CCBot\nDisallow: /\n\nUser-agent: Bytespider\nDisallow: /\n\nUser-agent: Google-Extended\nDisallow: /\n\nSitemap: https://www.greenleaf-journal.example/sitemap_index.xml"
    },
    "directives": {
      "meta": [
        {
          "name": "robots",
          "content": "index, follow, noai, noimageai"
        }
      ],
      "x_robots_tag": [],
      "flags": {
        "noai": true,
        "noimageai": true,
        "noindex": false,
        "nosnippet": false
      }
    },
    "js": {
      "raw_words": 412,
      "rendered_words": 1860,
      "ratio": 0.22,
      "verdict": "js_dependent",
      "reason": ""
    },
    "llms": {
      "url": "https://www.greenleaf-journal.example/llms.txt",
      "status": 200,
      "found": true,
      "content_type": "text/html; charset=utf-8",
      "h1": "Greenleaf Journal",
      "summary": null,
      "sections": 3,
      "links": 18,
      "problems": [
        {
          "code": "no_summary",
          "detail": "No blockquote summary after the H1",
          "line": 2
        },
        {
          "code": "content_type",
          "detail": "Served as text/html; expected text/plain or text/markdown",
          "line": null
        },
        {
          "code": "bad_list_item",
          "detail": "Several links on one list line",
          "line": 14
        }
      ]
    },
    "sitemap": {
      "sitemaps": [
        {
          "url": "https://www.greenleaf-journal.example/sitemap_index.xml",
          "status": 200,
          "valid": true,
          "blocked_for": [
            "gptbot",
            "ccbot",
            "bytespider",
            "google-extended"
          ]
        },
        {
          "url": "https://www.greenleaf-journal.example/post-sitemap.xml",
          "status": 200,
          "valid": true,
          "blocked_for": [
            "gptbot",
            "ccbot",
            "bytespider",
            "google-extended"
          ]
        }
      ],
      "sampled": 20,
      "resolved": 19,
      "problems": [
        {
          "code": "blocked_for_ai",
          "detail": "robots.txt blocks 4 AI crawlers from the URLs this sitemap lists"
        }
      ]
    },
    "result_url": "https://approvalens.com/ai/aic_7Qm2xK9pLs"
  }
}

Errors: bad_request, bad_url, invalid_key, missing_key, subscription_required, idempotency_in_progress, idempotency_key_reused, unreachable, rate_limited, unavailable

Alerts

Where your alerts go (read-only).

GET/api/v1/alert-channelsScope: read

List alert destinations

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.

Parameters

lang
en (default) or tr: language of the text fields
Example request
curl https://approvalens.com/api/v1/alert-channels \
  -H "Authorization: Bearer $APPROVALENS_KEY"
Example response · 200
{
  "channels": [
    {
      "id": 1,
      "kind": "account",
      "name": "",
      "target": "you@example.com",
      "status": "active",
      "primary": true,
      "events": [
        "uptime",
        "ssl",
        "domain",
        "adstxt",
        "robots",
        "noindex",
        "aibots",
        "security",
        "reputation",
        "server",
        "server_security"
      ],
      "min_severity": "info",
      "tags": [],
      "quiet_hours": null,
      "digest": "weekly",
      "digest_hour": 8,
      "instant": true,
      "created_at": "2026-08-26T08:00:00Z",
      "last_ok_at": "2026-10-03T08:00:00Z",
      "last_error": null,
      "failures": 0
    },
    {
      "id": 5,
      "kind": "webhook",
      "name": "Ops webhook",
      "target": "hooks.example.net/…/x9Kq",
      "status": "active",
      "primary": false,
      "events": [
        "uptime",
        "server"
      ],
      "min_severity": "warning",
      "tags": [
        "client:acme"
      ],
      "quiet_hours": {
        "start": "23:00",
        "end": "07:00"
      },
      "digest": "off",
      "digest_hour": null,
      "instant": true,
      "created_at": "2026-09-27T08:00:00Z",
      "last_ok_at": "2026-10-03T08:00:00Z",
      "last_error": null,
      "failures": 0
    }
  ],
  "timezone": "Europe/Istanbul",
  "webhooks": {
    "signature_header": "X-Approvalens-Signature",
    "docs_url": "https://approvalens.com/api#webhooks"
  }
}

Errors: invalid_key, missing_key, subscription_required, rate_limited, unavailable

Webhook signatures

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)
Set up a webhook

OpenAPI

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.

Open /api/openapi.json

Changelog

  1. 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.
  2. v1 · 2026-10-06First version: sites, incidents, reports, report summary, AI checks.
  3. —Breaking changes will come as /api/v2 and be announced here first.