REST API overview¶

Everything the dashboard does is available under /api/v1, and the Agent, the plugins and the reporting scripts use the same API. This page covers the conventions that apply to every call; the interactive reference lists each route.

Where the API lives¶

The ingest host is never filtered by the workspace IP allowlist; the workspace address is, unless Settings → Security allows ingest from any IP. Use the exact base URL shown on the Install Tokens, API Keys or Delegated DNS-01 page rather than deriving one.

Interactive reference¶

Sign in to your workspace and open API docs from the account menu, or go to /api/v1/docs (Swagger UI) or /api/v1/redoc; the schema is at /api/v1/openapi.json. The reference is generated from the running platform, so it always matches the deployed version. Demo accounts are redirected away from it. GET /api/v1/meta (no authentication) returns the product version, build, deployment mode and capability flags; GET /api/v1/version adds the database schema status.

Authentication¶

• API keys are presented as <prefix>.<secret> in either the X-Api-Key header or Authorization: Bearer <prefix>.<secret>. What a key may do is decided by its scope and organization binding; see API keys & authentication. A wrong, revoked or expired key always gets the same 401.
• Browser sessions from the dashboard can call the API too (the API docs page relies on this). POST /api/v1/auth/login starts a session for a local account and is throttled like the sign-in page (10 attempts per minute per address and email, 30 per address, and a 15-minute lockout after eight consecutive failures); single sign-on users sign in through the dashboard. For an account with two-factor sign-in, the answer has mfa_required: true and the session can only call POST /api/v1/auth/mfa/verify (with code or recovery_code), GET /api/v1/auth/me and POST /api/v1/auth/logout until the code is verified; every other call answers 403 with mfa-required.
• GET /api/v1/auth/me describes the current principal: the tenant, the organizations it can act in, its permissions, and for a reporting key the reporting_organization_id its submissions land in. It is the quickest way to check a new key.

curl https://<slug>.app.certin.tel/api/v1/auth/me \
  -H "X-Api-Key: cik_<prefix>.<secret>"

Pagination¶

List routes use keyset pagination:

Responses carry the rows in items and a meta object with limit, next_cursor and has_more; stop when has_more is false.

Errors¶

Every error is an RFC 9457 problem document with Content-Type: application/problem+json:

{
  "type": "https://certin.tel/problems/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "…",
  "request_id": "…",
  "errors": [{"field": "…", "message": "…"}]
}

errors appears only on validation failures (422). Quote the request_id when you report a problem. A resource that exists in another tenant or organization answers 404, never 403, so an id cannot reveal what exists elsewhere; see troubleshooting. A 429 (…/problems/rate-limited) carries a Retry-After header; wait that long before retrying.

Resource families¶

Routes used only by the platform console are not part of the published schema.