Public API — Reference (generated)

For the versioning policy (what v1 guarantees, what forces a v2, the v1 deprecation window, auth, error shapes, pagination — all independently verified prose), see public-api-versioning.md. For an interactive, always-current copy of this same information, see the live docs portal: /api/v1/reference / /api/v2/reference (ReDoc), /api/v1/docs / /api/v2/docs (Swagger UI), /api/v1/docs-json / /api/v2/docs-json (raw OpenAPI 3.0). All paths below are relative to the API base URL (e.g. https://app.cmdash.net/api). For the exact shape of a failed request and every fixed error value the API can return, see error-catalogue.md. For safe request retries — including a curl example against this API — see the public-API section of idempotency.md.

v1 Endpoints

16 endpoints across 5 resource groups. v1 is deprecated but unchanged — every response below still carries the exact shape it always has, including the two known 200 { error: ... } cases (see public-api-versioning.md's "Error shapes" section).

v2 Endpoints

45 endpoints across 15 resource groups. Every v1 route has a v2 counterpart at the same sub-path; v2 additionally fixes the two 200 { error: ... } cases to a real 404, and adds new resources (webhooks, reports, audit-logs) that have no v1 equivalent.

Permission scopes

Every scope in ApiKeyService's VALID_PERMISSIONS whitelist — which is NOT versioned, a key's scopes work against whichever version's routes it calls — and whether a v1 route and/or a v2 route actually checks it today. A key may be issued with a scope neither version enforces yet; see public-api-versioning.md for what that means and for the one scope (compliance:write) that was removed from this whitelist entirely rather than carried into v2 unenforced.

API key lifetime

Default expiry: 90 days. Maximum expiry: 365 days (enforced at creation and rotation).

Re-authentication for key management

An API key is a bearer credential that outlives the session that minted it, so the routes that mint, rotate or revoke one are gated on a FRESH credential — a stolen access token is not enough on its own.

Call POST /auth/reauth with { "password": "…" } (or { "mfaCode": "123456" } on an account with MFA) on the authenticated session. It returns a short-lived proof; replay it in the X-Fresh-Auth header on the gated call. The proof is valid for 10 minutes by default (FRESH_AUTH_TTL_MINUTES), is bound to the user who obtained it, and grants nothing on its own.

Without a valid proof the call returns 403 with error: "FRESH_AUTH_REQUIRED" (repeated in details.code). The session is still valid — refresh nothing and sign nobody out; obtain a proof and retry once. See error-catalogue.md.

Listing keys and reading a key's rate-limit usage are NOT gated: a read changes no credential.

Rate limits

Per-API-key, Redis-backed, fixed 60-minute window, resolved from the calling tenant's org tier. Applies identically to v1 and v2 (the limiter keys on the API key, not the path version).

Plans without Public API access are not listed: no API key can be minted on them.