Endpoint Reference

Complete reference for all CLE Engine API endpoints.

Base URL

Production: https://api.cle-engine.com
Local Development: http://localhost:8000

GET /health

Check the health status of the API service.

Request

GET /health HTTP/1.1
Host: api.cle-engine.com

Authentication: Not required

Response

{
  "status": "ok"
}

Response Fields

Field	Type	Description
`status`	string	Service status. `"ok"` indicates the service is healthy.

Example

curl -X GET https://api.cle-engine.com/health

POST /v1/compute

Calculate CLE reporting deadlines and compliance information for a specific jurisdiction.

Request

POST /v1/compute HTTP/1.1
Host: api.cle-engine.com
Content-Type: application/json
X-API-Key: cle_your_api_key_here

{
  "jurisdiction": "CA",
  "profession": "lawyer",
  "last_name": "Smith"
}

Authentication: Required (X-API-Key header)

Request Body

Field	Type	Required	Default	Description
`jurisdiction`	string	Yes	-	US state or territory code (e.g., `"CA"`, `"NY"`, `"TX"`)
`profession`	string	No	`"lawyer"`	Licensed profession
`last_name`	string	Conditional	`null`	Attorney's last name. Required for CA, IL.
`birth_date`	string (ISO date)	Conditional	`null`	Date of birth (YYYY-MM-DD). Required for NJ, TX, PR.
`admission_date`	string (ISO date)	Conditional	`null`	Date of bar admission (YYYY-MM-DD). Required for CO, DE, FL, ID, IN, ND, SC, WA, WI.
`reporting_category`	string	Conditional	`null`	State-specific reporting category or compliance group. Required for MN, PA.
`reporting_period_end`	string (ISO date)	Conditional	`null`	Reporting period end date (YYYY-MM-DD). Required for NY, OR.
`renewal_year`	integer	Conditional	`null`	License renewal year. Required for VT.

Response

{
  "due_date": "2026-03-30",
  "cycle_start": null,
  "cycle_end": "2026-03-29",
  "credits_required": null,
  "reporting_group": "Group 3",
  "cle_required": true,
  "required_fields": ["last_name"],
  "missing_fields": [],
  "citations": [
    {
      "source_id": "ca_mcle_requirements",
      "excerpt_id": null,
      "url": "https://www.calbar.ca.gov/legal-professionals/maintaining-compliance/mcle/mcle-requirements"
    }
  ],
  "notes": "Compliance group assigned by last name."
}

Response Fields

Field	Type	Description
`due_date`	string (ISO date) or `null`	The date by which CLE credits must be reported
`cycle_start`	string (ISO date) or `null`	Start of the current compliance period
`cycle_end`	string (ISO date) or `null`	End of the current compliance period
`credits_required`	integer or `null`	Total credits required for the period
`reporting_group`	string or `null`	The attorney's assigned compliance group
`cle_required`	boolean or `null`	Whether mandatory CLE applies
`required_fields`	array of strings	Fields needed for accurate calculation
`missing_fields`	array of strings	Required fields that were not provided
`citations`	array of objects	Official sources supporting the calculation
`notes`	string or `null`	Human-readable explanation of the result

Citation Object

Field	Type	Description
`source_id`	string	Internal identifier for the source
`excerpt_id`	string or `null`	Specific excerpt reference
`url`	string or `null`	URL to the official source

HTTP Status Codes

Code	Description
`200`	Success
`401`	Invalid or missing API key
`429`	Quota exceeded
`500`	Server error

Examples

Basic Request (California)

curl -X POST https://api.cle-engine.com/v1/compute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cle_your_api_key_here" \
  -d '{
    "jurisdiction": "CA",
    "last_name": "Smith"
  }'

Request with Birth Date (New Jersey)

curl -X POST https://api.cle-engine.com/v1/compute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cle_your_api_key_here" \
  -d '{
    "jurisdiction": "NJ",
    "birth_date": "1985-06-15"
  }'

Request with Admission Date (Colorado)

curl -X POST https://api.cle-engine.com/v1/compute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cle_your_api_key_here" \
  -d '{
    "jurisdiction": "CO",
    "admission_date": "2020-09-15"
  }'

Request with Reporting Category (Pennsylvania)

curl -X POST https://api.cle-engine.com/v1/compute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cle_your_api_key_here" \
  -d '{
    "jurisdiction": "PA",
    "reporting_category": "1"
  }'

Request for Non-Mandatory CLE State (Maryland)

curl -X POST https://api.cle-engine.com/v1/compute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cle_your_api_key_here" \
  -d '{
    "jurisdiction": "MD"
  }'

Response:

{
  "due_date": null,
  "cycle_start": null,
  "cycle_end": null,
  "credits_required": null,
  "reporting_group": null,
  "cle_required": false,
  "required_fields": [],
  "missing_fields": [],
  "citations": [
    {
      "source_id": "md_cle_report",
      "url": "https://www.mdcourts.gov/lawyers/cle"
    }
  ],
  "notes": "Mandatory CLE has not been adopted; consideration postponed."
}

POST /v1/stats

Note: This endpoint is currently a placeholder and returns empty data. Full implementation is planned for a future release.

Retrieve aggregated statistics about attorney populations and upcoming renewals.

Request

POST /v1/stats HTTP/1.1
Host: api.cle-engine.com
Content-Type: application/json
X-API-Key: cle_your_api_key_here

{
  "jurisdiction": "CA",
  "as_of": "2026-01-15",
  "window_days": 60
}

Authentication: Required (X-API-Key header)

Request Body

Field	Type	Required	Default	Description
`jurisdiction`	string	No	`null`	US state/territory code; omit for national statistics
`as_of`	string (ISO date)	No	`null`	Date to compute upcoming renewals from
`window_days`	integer	No	`60`	Number of days to look ahead for renewals

Response

{
  "as_of": "2026-01-15",
  "window_days": 60,
  "totals": {
    "jurisdiction": "CA",
    "total_attorneys": null,
    "upcoming_renewals": null,
    "upcoming_percent": null
  },
  "jurisdictions": [],
  "citations": [],
  "notes": "Population stats not loaded yet"
}

POST /webhooks/stripe

Internal endpoint for processing Stripe payment webhooks. Not intended for direct API consumption.

Authentication: Stripe webhook signature verification

Request Headers

Required Headers

Header	Description	Example
`X-API-Key`	Your API key for authentication	`cle_a1b2c3d4...`
`Content-Type`	Content type for POST requests	`application/json`

Optional Headers

Header	Description	Example
`Accept`	Response format (always JSON)	`application/json`

Rate Limiting Headers

Response headers include rate limiting information:

Header	Description
`X-RateLimit-Limit`	Maximum requests per month for your tier
`X-RateLimit-Remaining`	Remaining requests this month
`X-RateLimit-Reset`	Unix timestamp when the limit resets

Pagination

Currently, all endpoints return complete results without pagination. Future endpoints may include pagination support with the following parameters:

Parameter	Description
`page`	Page number (1-indexed)
`per_page`	Results per page (max 100)