# Certack REST API — plain-text reference (docs/api.txt)

> Complete reference for the Certack proactive monitoring API: SSL/TLS, DNS and domain checks, sites, alerts, incidents, API keys, billing and webhooks. Human version: https://certack.com/docs/api. Machine spec: https://certack.com/openapi.yaml. Index: https://certack.com/llms.txt.

## Base URL and auth
- Production API: https://api.certack.com/v1 (the app also serves the same handlers under https://certack.com/api).
- Auth: Bearer API key in the Authorization header. Keys look like `ct_…` and are created in the dashboard (Account → API keys) or via POST /api-keys.
- Cookie sessions work in browsers; Bearer keys are the only credential on API hosts and for MCP/CLI use.
- No-auth surface (rate limited, 10 req/min/IP): GET /public/check-ssl?domain=example.com and POST /public/mcp (check_ssl, check_dns, check_domain tools only).

## Sites
- POST /sites — add a site. Body: { domain, check_types?: ["ssl","dns","domain","ct"] }. Domains must resolve to a public IP (private/NXDOMAIN → 400).
- GET /sites — list your sites with latest check summaries.
- PATCH /sites?id=SITE_ID — update check_types, alert_days, origin_ip, custom port.
- DELETE /sites?id=SITE_ID — remove a site and its history.
- Free plan: 2 sites. Starter: 10. Pro: 20.

## On-demand checks
- POST /check-ssl — { domain, port?, origin_ip?, site_id? }. Returns validity, issuer, expiry, days_remaining, SANs, full chain, protocol/cipher. Uses the external TLS prober when configured (result.source "probe"), else CT-log fallback ("ct_fallback").
- POST /check-dns — { domain }. A/AAAA/MX/NS/TXT records + DNSSEC status.
- POST /check-domain — { domain }. Registrar, expiry, days_remaining, nameservers (RDAP).
- GET /checks?site_id=… — latest results per type; add check_type/from/to/limit/offset for history.
- POST /checks — record an external check result { site_id, check_type, result }.
- GET /cert-history?site_id=… — certificate change history (renewals, issuer changes).

## Alerts and incidents
- GET /alerts — unresolved alerts (type, severity, message, suggestion).
- PATCH /alerts?id=ALERT_ID — resolve an alert.
- GET /incidents — list; POST /incidents { title, severity, affected_sites } — open one (also fires webhooks per settings).
- GET/PATCH /incidents/[id] — detail / update status. GET/POST /incidents/[id]/updates — timeline entries.
- GET /maintenance-windows — list; POST { site_id?, starts_at, ends_at, description? } — create (suppresses alerts inside the window); DELETE /maintenance-windows?id=…

## API keys
- GET /api-keys — list (id, prefix, name, last used; never the secret).
- POST /api-keys { name } — create; the full key is returned ONCE.
- DELETE /api-keys?id=KEY_ID — revoke.
- Limits: Free 1 key, Starter 3, Pro 5.

## Account, billing, settings
- GET /account — profile + effective plan.
- GET /billing/status — plan + Creem customer id (polled by the checkout success page).
- POST /billing/portal — customer portal session URL. POST /billing/cancel — cancel subscription (immediate; plan falls back to free).
- POST /checkout { planId: "starter"|"pro", billing: "monthly"|"yearly" } — Creem checkout session (test mode in staging).
- GET /settings/notifications — channels, alert events, thresholds. PATCH — update. POST { event?|events? } — send a test notification to your own channels.
- GET /notifications/history — delivery log; DELETE clears it.

## Private-cert agent (Pro)
- POST /agent/register — register a monitoring agent (returns agent key ct_agent_…).
- GET /agent/key — list keys. POST /agent/report — submit internal scan results. GET /agent/certs — discovered certs.

## MCP (AI assistants)
- POST /mcp (Bearer key): list_sites, add_site, update_site, remove_site, get_site_status, check_ssl, check_dns, check_domain, list_alerts, resolve_alert, get_cert_history, list_private_certs.
- POST /public/mcp (no auth, rate limited): check_ssl, check_dns, check_domain.

## Ops endpoints (CRON_SECRET bearer, not user keys)
- GET/POST /cron — scheduled check runner. GET/POST /reconcile — billing safety net (upgrades only).
- POST /webhooks/creem — Creem webhook receiver (signature verified).
- GET /renewal — renewal status; POST { site_id } — trigger ACME renewal (Pro).

## Rate limits
- Per-plan QPS sliding window (Free 1, Starter 5, Pro 10) + monthly call quota (Free 100, Starter 2,000, Pro 10,000). Only Bearer-key traffic counts toward the monthly quota; dashboard session traffic is exempt.
- 429 responses carry Retry-After; quota headers: X-RateLimit-*, X-MonthlyLimit-*.
- Public endpoints: 10 req/min per IP. Same domain re-probed at most every 5 minutes (shared cache).

## Errors
- JSON { error } with HTTP status: 400 validation, 401 missing/invalid credential, 403 plan gate or ownership, 404 unknown id, 429 rate limited, 5xx with a logged error id.
- Unauthenticated /api/* GETs return 401 JSON (never a login page).

## Examples
```bash
KEY=ct_YOUR_KEY
# add a site
curl -X POST https://api.certack.com/v1/sites -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{"domain":"example.com"}'
# check its certificate
curl -X POST https://api.certack.com/v1/check-ssl -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" -d '{"domain":"example.com"}'
# poll alerts
curl https://api.certack.com/v1/alerts -H "Authorization: Bearer $KEY"
```

## Outbound webhooks (Certack → you)
- Configure HTTPS URLs in notification settings; events (ssl.expiring, site.down, incident.created/resolved, …) POST as JSON signed with HMAC-SHA256 (X-Certack-Signature) using your WEBHOOK_SIGNING_SECRET.
- Full event catalog and verification snippets (Node/Python/Go/PHP): https://certack.com/docs/api#webhooks.

## Support
- Support (all inquiries): support@certack.com
- Terms: https://certack.com/terms — Privacy: https://certack.com/privacy