API Documentation

The technical reference for the LegalCals v1 API. For an overview and SDKs, see /developers.

Overview

The v1 API exposes LegalCals' regulatory intelligence — risk scoring, comparisons, scenario evaluation, alerts, reports, and national observatory snapshots — over a stable, versioned REST interface. All endpoints live under /api/v1/* and share one authentication and rate-limiting layer.

Authentication

Send your API key in the x-legalcals-key header on every request. Generate a key from /settings/api (requires a LegalCals account) — a key generated this way is linked to your account, which is required for /api/v1/alerts and /api/v1/reports/weekly.

curl https://legalcals.com/api/v1/jurisdictions \
  -H "x-legalcals-key: lc_your_key_here"

Endpoints

Resource-oriented endpoints added for integrations and partners:

Method	Path	Description
GET	/api/v1/jurisdictions	All supported jurisdictions and metadata
GET	/api/v1/rules?jurisdiction=XX	Rules across every topic for a jurisdiction
POST	/api/v1/comparison	Risk/trend matrix across jurisdictions × topics
POST	/api/v1/scenario	Evaluate a scenario against one jurisdiction
GET	/api/v1/alerts	Active alerts for the key's linked account
GET	/api/v1/reports/weekly	Signed URL to the account's weekly digest PDF
POST	/api/v1/observatory	National risk/similarity/trend snapshot

Plus the original analysis-oriented endpoints:

GET /api/v1/topicsGET /api/v1/topics/{topic}/coveragePOST /api/v1/intelligencePOST /api/v1/reasoningPOST /api/v1/checklistPOST /api/v1/riskPOST /api/v1/heatmapPOST /api/v1/similarity/matrixPOST /api/v1/similarity/clustersPOST /api/v1/trends/jurisdictionPOST /api/v1/trends/nationalPOST /api/v1/forecast/jurisdictionPOST /api/v1/forecast/nationalPOST /api/v1/reports/quarterlyPOST /api/v1/reports/annual

Request & response example

curl -X POST https://legalcals.com/api/v1/scenario \
  -H "x-legalcals-key: lc_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "jurisdiction": "bc",
    "inputs": { "topic": "rent-increase", "narrative": "Landlord wants to raise rent by 8%", "severity": 60 }
  }'

{
  "success": true,
  "data": { "jurisdiction": "bc", "topic": "rent-increase", "scenarioText": "...", "risk": { "overallRisk": "high", ... } },
  "lastUpdated": "2026-07-06T12:00:00.000Z",
  "source": "LegalCals Authority Bundle",
  "version": "v1"
}

Rate limits

Each key has its own per-minute and per-day limit (self-service keys from /settings/api: 30/minute, 1,000/day). Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. Exceeding a limit returns 429.

Error format

Every error response has the same shape:

{ "success": false, "error": "Human-readable message" }

Status	Meaning
400	Missing or invalid request parameters
401	Missing or invalid API key
403	Valid key, but not permitted for this endpoint (e.g. not linked to an account)
404	Jurisdiction, topic, or resource not found
429	Rate limit exceeded
500	Unexpected server error

Versioning

The current version is v1, reflected in the URL path and in every response's version field. Additive changes (new endpoints, new optional fields) ship within v1 without notice. Breaking changes (removed fields, changed semantics) will ship as a new /api/v2/* namespace, with v1 kept running in parallel.