> ## 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"
}
```

District access errors include structured context and a contact email:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": "District 'sdny' is not yet accessible in your plan.",
  "suggestion": "Contact api@courtrules.app to upgrade your plan for Southern District of New York access.",
  "docs_url": "https://docs.courtrules.app/api-reference/courts",
  "district": {
    "district_id": "sdny",
    "name": "Southern District of New York",
    "status": "preview"
  },
  "accessible_districts": ["edny"],
  "contact": "api@courtrules.app"
}
```

## 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, or district not yet accessible                  |
| `404` | Resource not found (judge not in district, unknown district ID)  |
| `429` | Rate limit exceeded                                              |
| `502` | Classification failed (timeout or upstream error on `/classify`) |