# Legalize — Full API Reference for LLMs

> Free REST API for consolidated legislation from every country Legalize covers. Search laws, track reforms, time-travel through legal history.

## Authentication

All /api/v1/* endpoints require a Bearer token:

```
Authorization: Bearer leg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Get a free API key at https://legalize.dev/dashboard (2,000 calls/month, no credit card).

Rate limit headers on every response:
- X-RateLimit-Limit: monthly limit
- X-RateLimit-Used: current usage
- X-RateLimit-Reset: ISO date of next reset

## Available Countries

Country codes are two-letter ISO codes, and every code works as
`/api/v1/{code}/laws`. `GET /api/v1/countries` returns the current list with
law counts — the list grows as countries ship, so it is not copied here.

## Endpoints

### GET /api/v1/countries

List all countries with law counts.

```bash
curl -H "Authorization: Bearer $KEY" https://legalize.dev/api/v1/countries
```

Response:
```json
[
  {"country": "es", "count": 8677},
  {"country": "se", "count": 9732},
  ...
]
```

### GET /api/v1/{country}/laws

Search and list laws. Supports pagination and filtering.

Parameters:
- q (string): Full-text search query
- page (int, default 1): Page number
- per_page (int, default 50, max 100): Results per page
- law_type (string): Filter by type (comma-separated for multiple: "ley,constitucion")
- year (int): Filter by publication year
- status (string): Filter by status ("vigente", "derogada")
- jurisdiction (string): Filter by jurisdiction code
- sort (string): "date_desc" (default), "date_asc", "title"
- from_date (string): Filter from date (YYYY-MM-DD)
- to_date (string): Filter to date (YYYY-MM-DD)

```bash
# Search for laws about "código penal" in Spain
curl -H "Authorization: Bearer $KEY" \
     "https://legalize.dev/api/v1/es/laws?q=código+penal"

# List Spanish laws from 2024, sorted by title
curl -H "Authorization: Bearer $KEY" \
     "https://legalize.dev/api/v1/es/laws?year=2024&sort=title"

# Filter by date range and law type
curl -H "Authorization: Bearer $KEY" \
     "https://legalize.dev/api/v1/es/laws?from_date=2024-01-01&to_date=2024-12-31&law_type=ley_organica"
```

Response:
```json
{
  "country": "es",
  "total": 16,
  "page": 1,
  "per_page": 50,
  "query": "código penal",
  "results": [
    {
      "id": "BOE-A-1995-25444",
      "title": "Ley Orgánica 10/1995, del Código Penal",
      "short_title": "Código Penal",
      "country": "es",
      "law_type": "ley_organica",
      "publication_date": "1995-11-24",
      "status": "vigente",
      "article_count": 639
    }
  ]
}
```

### GET /api/v1/{country}/laws/{law_id}

Get a complete law with full Markdown content.

```bash
curl -H "Authorization: Bearer $KEY" \
     "https://legalize.dev/api/v1/es/laws/BOE-A-1978-31229"
```

Response:
```json
{
  "id": "BOE-A-1978-31229",
  "title": "Constitución Española",
  "article_count": 169,
  "publication_date": "1978-12-29",
  "status": "vigente",
  "content_md": "# Constitución Española\n\n## Título Preliminar\n\nArtículo 1\n..."
}
```

### GET /api/v1/{country}/laws/{law_id}/meta

Metadata only (no content). Fast — no GitHub fetch.

```bash
curl -H "Authorization: Bearer $KEY" \
     "https://legalize.dev/api/v1/es/laws/BOE-A-1978-31229/meta"
```

### GET /api/v1/{country}/laws/{law_id}/reforms

Reform history for a law. Each reform is a legislative change.

Parameters:
- limit (int, default 100, max 1000): Results per page
- offset (int, default 0): Pagination offset

```bash
curl -H "Authorization: Bearer $KEY" \
     "https://legalize.dev/api/v1/es/laws/BOE-A-1978-31229/reforms"
```

Response:
```json
{
  "law_id": "BOE-A-1978-31229",
  "total": 4,
  "reforms": [
    {
      "date": "2024-02-17",
      "source_id": "BOE-A-2024-3099",
      "articles_affected": "Artículo 49"
    }
  ]
}
```

### GET /api/v1/{country}/laws/{law_id}/commits

Git commit history. Each commit represents a version of the law.

```bash
curl -H "Authorization: Bearer $KEY" \
     "https://legalize.dev/api/v1/es/laws/BOE-A-1978-31229/commits"
```

Response:
```json
{
  "law_id": "BOE-A-1978-31229",
  "commits": [
    {"sha": "80667b15f311", "date": "2024-02-16", "message": "[reforma] Constitución — art. 49"},
    {"sha": "a1b2c3d4e5f6", "date": "1978-12-29", "message": "[original] Constitución Española"}
  ]
}
```

### GET /api/v1/{country}/laws/{law_id}/at/{sha}

Time-travel: get the law text at a specific historical version.

```bash
curl -H "Authorization: Bearer $KEY" \
     "https://legalize.dev/api/v1/es/laws/BOE-A-1978-31229/at/a1b2c3d"
```

Response:
```json
{
  "law_id": "BOE-A-1978-31229",
  "sha": "a1b2c3d",
  "content_md": "# Constitución Española\n\n..."
}
```

### GET /api/v1/{country}/law-types

List law types available in a country.

```bash
curl -H "Authorization: Bearer $KEY" \
     "https://legalize.dev/api/v1/es/law-types"
```

Response: `["constitucion", "ley", "ley_organica", "real_decreto", ...]`

### GET /api/v1/{country}/stats

Aggregate statistics.

```bash
curl -H "Authorization: Bearer $KEY" \
     "https://legalize.dev/api/v1/es/stats"
```

Response:
```json
{
  "country": "es",
  "reform_activity_by_year": [{"year": "2024", "count": 1203}],
  "most_reformed_laws": [...],
  "law_types": ["constitucion", "ley", ...]
}
```

## Error Handling

All errors return JSON with `error`, `message`, and `detail` fields:

```json
{"error": "invalid_api_key", "message": "API key is invalid or unconfirmed.", "detail": {...}}
```

Status codes:
- 400: Invalid input (bad date format, empty query, invalid country)
- 401: Missing or invalid API key
- 404: Law or country not found
- 402: Paid quota renewal awaits payment; account and billing remain accessible
- 429: Monthly quota exceeded (includes Retry-After header)
- 503: Service unavailable (maintenance)

## Code Examples

### Python
```python
import requests

KEY = "leg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
HEADERS = {"Authorization": f"Bearer {KEY}"}

# Search laws
resp = requests.get("https://legalize.dev/api/v1/es/laws", params={"q": "protección de datos"}, headers=HEADERS)
laws = resp.json()["results"]

# Get reform history
reforms = requests.get(f"https://legalize.dev/api/v1/es/laws/{laws[0]['id']}/reforms", headers=HEADERS).json()
```

### JavaScript
```javascript
const KEY = "leg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
const headers = { "Authorization": `Bearer ${KEY}` };

const resp = await fetch("https://legalize.dev/api/v1/es/laws?q=protección+de+datos", { headers });
const { results } = await resp.json();

const reforms = await fetch(`https://legalize.dev/api/v1/es/laws/${results[0].id}/reforms`, { headers }).then(r => r.json());
```

## Pricing

| Tier | Price | Requests/month | Features |
|------|-------|----------------|----------|
| Free | €0 | 2,000 | All endpoints, basic metadata |
| Pro | €29 | 50,000 | + extended metadata, department, source, extra fields |
| Enterprise | €149+ | 2,000,000+ | + custom volume, direct support |

## Links

- Website: https://legalize.dev
- API Docs: https://legalize.dev/api/docs
- Dashboard: https://legalize.dev/dashboard
- GitHub: https://github.com/legalize-dev
- Pricing: https://legalize.dev/pricing

Quota periods: Free resets on the 1st at 00:00 UTC. Pro includes 50,000 requests per monthly period from the subscription start date. Annual billing includes twelve monthly quotas, not a single annual allowance. The original day returns after shorter months; dates use UTC. Unused requests do not roll over. API and MCP share quota. New paid periods require confirmed payment.