The CARL API exposes the hosted assessor's functionality over HTTP for authenticated integrations. Today, POST /api/assess exists as a synchronous, IP-rate-limited endpoint that runs the deterministic engine and returns the persisted report in the same request. Intended surface:

• POST /api/assess — enqueue an assessment job. Returns a jobId.
• GET /api/assess/[jobId]/stream — server-sent events for progress phases.
• GET /api/report/[id] — fetch a completed report (JSON, per the report schema).
• GET /api/report/[id]/pdf — render the Executive view as a PDF.
• GET /api/badge/[owner]/[repo].svg — the live-updating level badge.

Authentication

API access uses the same session as the web app — BetterAuth with GitHub or Google OAuth. For machine-to-machine use, long-lived personal access tokens will be scoped to the minimum capability needed (read-only report access vs enqueueing an assessment).

Rate limits

To be finalized in M5. Target limits: 60 enqueues/hour/user for free accounts, higher for Pro, no limit for self-hosted.

When to prefer the API vs other tools

• Dashboards and custom integrations. API.
• CI gating. CLI — deterministic, no external dependency.
• One-off human-readable reports. Web app.

Reference

Full endpoint documentation will be published at /reference/api/ once the API ships.