API reference

The Renew Radar API lets you manage tracked certificates, alert channels, and thresholds from your own tooling. It's a JSON REST API secured with personal access tokens.

Authentication

Create a token from Settings → API tokens, then send it as a bearer token on every request:

curl https://renewradar.com/api/v1/certificates \
  -H "Authorization: Bearer <your-token>" \
  -H "Accept: application/json"

Each token is scoped to read or read & write when you create it. Tokens can be revoked at any time from the same page — revoking one takes effect immediately.

Your account's email address must be verified. If it isn't — for example, right after you change it in your profile settings — every request returns 403 Forbidden with the message Your email address is not verified. until you click the link in the verification email.

Base URL & rate limits

All endpoints are under https://renewradar.com/api/v1 and return JSON. Requests are limited to 60 per minute per token, and 120 per minute across all of an account's tokens. The X-RateLimit-* headers report the per-token budget.

Certificate inspections — adding a certificate, changing a live certificate's domain, and single or bulk rescans — also share a separate budget of 20 per minute per account, across every token and the web app. Once it's used up, those requests return 429 Too Many Requests with a Retry-After header giving the seconds until the budget frees up.

Responses

Every successful response with a body wraps its payload in a data key — a single object for one resource, an array for a list:

{
  "data": { "id": 1, "domain": "shop.acme.com", ... }
}

Lists return every item at once, except /certificate-events, which is paginated. Successful DELETE requests return 204 No Content with an empty body. Validation failures return 422 with a message and an errors object keyed by field.

Certificates

To track a live domain, send a domain with source set to live. To track an offline certificate, set source to offline and include a PEM-encoded certificate_pem instead:

curl https://renewradar.com/api/v1/certificates \
  -X POST \
  -H "Authorization: Bearer <your-token>" \
  -H "Accept: application/json" \
  -d "domain=shop.acme.com" \
  -d "source=live" \
  -d "auto_renew=0"

Bulk rescans

POST /certificates/rescan re-checks certificates one at a time, charging each against the inspection budget. If the budget runs out partway through, it stops and returns 200 with only the certificates it re-checked. Certificates are re-checked least-recently-checked first, so check meta.skipped: if it's above zero, wait a minute and call the endpoint again to reach the ones that were skipped. If the budget was already used up before any certificate could be re-checked, it returns 429.

{
  "data": [ /* re-checked certificate objects */ ],
  "meta": { "total": 20, "rescanned": 12, "skipped": 8 }
}

Certificate object

{
  "data": {
    "id": 1,
    "domain": "shop.acme.com",
    "source": "live",
    "status": "valid",
    "issuer": "R3",
    "organization": null,
    "key_algorithm": "RSA",
    "key_size": 2048,
    "serial_number": "...",
    "signature_algorithm": "sha256WithRSAEncryption",
    "fingerprint_sha256": "...",
    "self_signed": false,
    "valid_from": "2026-05-01T00:00:00.000000Z",
    "valid_to": "2026-07-30T00:00:00.000000Z",
    "days_remaining": 16,
    "auto_renew": false,
    "error": null,
    "last_checked_at": "2026-07-14T09:00:00.000000Z",
    "chain": [ /* as served by the host (leaf and intermediates) */ ],
    "created_at": "2026-04-01T00:00:00.000000Z",
    "updated_at": "2026-07-14T09:00:00.000000Z"
  }
}

Single-certificate endpoints return this object inside data, as shown; the list endpoint returns an array of them under data.

Alert channels

Alert thresholds

Certificate events

Events are paginated. Pass per_page (1–100, default 25) and page, and filter by type: one of added, removed, valid, expiring, expired, error, or alert.

curl "https://renewradar.com/api/v1/certificate-events?type=alert&per_page=50" \
  -H "Authorization: Bearer <your-token>" \
  -H "Accept: application/json"

Unlike the other lists, the response also includes links and meta. Keep requesting links.next until it's null to get every event — the next-page link keeps your type and per_page filters:

{
  "data": [
    {
      "id": 42,
      "certificate_id": 1,
      "domain": "shop.acme.com",
      "type": "alert",
      "message": "...",
      "created_at": "2026-07-14T09:00:00.000000Z"
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "...?page=2" },
  "meta": { "current_page": 1, "last_page": 3, "per_page": 50, "total": 120, ... }
}

Current user