> ## Documentation Index
> Fetch the complete documentation index at: https://docs.courtrules.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> API Reference for Court Rules and Enforcement Data

Base URL: `https://api.courtrules.app`

The REST API covers court rules (compliance checks, judge rules, document classification). Enforcement data is available through the [MCP server](/guides/mcp-enforcement) at `mcp.courtrules.app`, which also exposes [court rules tools](/guides/mcp-court-rules).

## Endpoints

| Method | Path | Description |
| - | - | - |
| `GET` | [`/api/v1/courts`](/api-reference/courts) | List all courts |
| `GET` | [`/api/v1/courts/:id`](/api-reference/get-court) | Get a single court's details |
| `GET` | [`/api/v1/judges`](/api-reference/judges) | List judges for a district |
| `GET` | [`/api/v1/rules`](/api-reference/rules) | Get applicable rules for a judge |
| `GET` | `/api/v1/profile` | Get a judge's full compliance profile |
| `GET` | `/api/v1/documents` | List source documents for a judge |
| `GET` | `/api/v1/documents/{id}/pdf` | Download a source document PDF |
| `POST` | [`/api/v1/check`](/api-reference/check) | Check document compliance |
| `POST` | [`/api/v1/classify`](/api-reference/classify) | Classify a PDF and extract metadata |
| `GET` | `/openapi.json` | Download the OpenAPI specification |

## Authentication

All endpoints require a Bearer token in the `Authorization` header:

```
Authorization: Bearer YOUR_API_KEY
```

See [Authentication](/authentication) for details on obtaining and using API keys.

## Interactive playground

Each endpoint page in this section includes a live request builder. Select an endpoint from the sidebar, fill in parameters, and send real requests against `https://api.courtrules.app`. You'll need your API key from [console.courtrules.app](https://console.courtrules.app).

## OpenAPI specification

The complete OpenAPI 3.1 spec is available as a public endpoint (no authentication required):

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl 'https://api.courtrules.app/openapi.json' -o openapi.json
```

Use this with Postman, code generators, or AI agents. See [Building with AI Agents](/guides/building-with-ai-agents) for integration examples.

## Content type

All `POST` requests must use `Content-Type: application/json`.

Most responses are `application/json`. Document PDF endpoints (`/documents/{id}/pdf`) return `application/pdf`.

## Error responses

Error responses follow a consistent format with actionable guidance:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": "Judge \"john-doe\" not found in edny.",
  "suggestion": "Use GET /api/v1/judges?district_id=edny to list valid judge slugs.",
  "docs_url": "https://docs.courtrules.app/api-reference/judges/list-judges"
}
```

Validation errors include field-level details:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": "Invalid request",
  "details": [{ "path": "document.page_count", "message": "Required" }],
  "docs_url": "https://docs.courtrules.app/api-reference/check/check-document"
}
```

Compliance checks need a compliance profile, which exists for `edny` today. `/check` and `/classify` on any other court return `422` and point to that court's rules:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": "Compliance checks are not available for Superior Court of California, County of Los Angeles yet.",
  "suggestion": "Compliance checks run for the Eastern District of New York (edny) today. For this court, read the judge's rules with GET /api/v1/rules?district_id=ca-los-angeles-superior&judge_slug=<slug> or search them with GET /api/v1/extracted-rules?district_id=ca-los-angeles-superior.",
  "docs_url": "https://docs.courtrules.app/api-reference/extracted-rules",
  "district_id": "ca-los-angeles-superior"
}
```

## Rate limits

All endpoints are rate-limited per API key using a sliding window:

| Endpoint | Limit |
| - | - |
| `POST /classify` | 5 RPM |
| `POST /check` | 60 RPM |
| `GET /courts`, `/judges`, `/rules` | 300 RPM |

Every response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. When exceeded, the API returns `429` with a `Retry-After` header.

See [Rate Limits](/api-reference/rate-limits) for retry guidance and common mistakes.

## HTTP status codes

| Code | Meaning |
| - | - |
| `200` | Success |
| `400` | Invalid request (missing params, validation failure) |
| `401` | Missing or invalid Authorization header |
| `403` | Invalid API key |
| `404` | Resource not found (judge not in court, unknown court ID) |
| `415` | Requested a PDF for a document stored in another format |
| `422` | Compliance check requested for a court without a compliance profile, or a search too broad to run |
| `429` | Rate limit exceeded |
| `502` | Classification failed (timeout or upstream error on `/classify`) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.