# MapleJuris API — full reference

> Verify Canadian legal citations against a structured graph of federal legislation. REST + MCP. This file is the complete reference, written for language models and agents.

Base URL: `https://api.maplejuris.com`
MCP endpoint: `https://api.maplejuris.com/mcp`
Sign-up: https://maplejuris.com/signup · API keys: https://maplejuris.com/dashboard/api-keys

## Authentication

Every request needs an API key created at https://maplejuris.com/dashboard/api-keys. The secret is shown once, at creation. Send it as either:

```
Authorization: Bearer ak_your_key_here
X-API-Key: ak_your_key_here
```

A missing, revoked, or expired key returns `401`. Keys are scoped to one account and count against that account's monthly allowance. Never embed a key in client-side code.

### Token exchange (optional, recommended for high-volume callers)

`POST /v1/token` trades your API key for a self-signed bearer token valid for 24 hours. Requests made with the token verify locally on our servers (no auth-provider round trip), which shaves latency and means key revocation propagates at the next mint. Tokens draw down the same monthly allowance as the key that minted them. Minting is free (unmetered).

```bash
curl -X POST https://api.maplejuris.com/v1/token -H "X-API-Key: $MAPLEJURIS_KEY"
# {"access_token": "eyJ...", "token_type": "Bearer", "expires_in": 86400, "plan": "non_commercial_free"}
```

Use the returned `access_token` exactly like a key: `Authorization: Bearer <token>` or `X-API-Key: <token>`. When it expires (`401`), mint a new one.

### Usage introspection

`GET /v1/usage` (any key or token) returns the account's month-to-date consumption — checking usage never burns quota:

```json
{"scope": "key", "subject": "user_...", "plan": "non_commercial_free", "quota": 1000, "month": "202607", "used": 42, "remaining": 958}
```

The dashboard at https://maplejuris.com/dashboard/api-keys shows the same numbers.

## POST /v1/validate-citation

Validate a single citation. Returns `200` whenever the key is valid — a citation that does not resolve is a result, not an error.

Body (send exactly one of `query` or `structured`):

| Field | Type | Notes |
|---|---|---|
| `query` | string | The citation as free text, 1–500 characters. |
| `structured` | object | Pre-parsed citation (`short_title`, `chapter`, `statute_id`, `section_label`, `subsection_label`, `paragraph_label`, `subparagraph_label`, `schedule_label`, `defined_term`, `target_node_type`). Skips the language-model parse for a fully deterministic lookup. Requires one of `short_title` / `chapter` / `statute_id`. |

Example:

```bash
curl -X POST https://api.maplejuris.com/v1/validate-citation \
  -H "Authorization: Bearer $MAPLEJURIS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Criminal Code s. 718"}'
```

Response:

```json
{
  "query": "Criminal Code s. 718",
  "valid": true,
  "validity_score": 0.94,
  "status": "resolved",
  "confidence": 0.94,
  "statute": { "short_title": "Criminal Code", "chapter": "C-46" },
  "target": {
    "node_type": "Section",
    "label": "718",
    "display_label": "Criminal Code, R.S.C. 1985, c. C-46, s. 718",
    "text": "...provision text...",
    "tree": []
  },
  "alternatives": [],
  "notes": [],
  "data_license": "...",
  "disclaimer": "..."
}
```

### Field reference

| Field | Meaning |
|---|---|
| `valid` | Boolean. True only when the citation resolved AND was verified against the graph. |
| `validity_score` | Float 0–1. `>= 0.75` resolved and verified · `0.4–0.75` understood but unmatched, or ambiguous · `0.1–0.4` statute identified, pinpoint missing · `< 0.1` nothing found. |
| `status` | `resolved` \| `ambiguous` \| `not_found` \| `unsupported`. |
| `score_breakdown` | `graph_match`, `statute_title_verified`, `unique_match`, `target_type_matches`, `has_current_text`, `statute_in_corpus`. |
| `confidence` | Model's interpretation confidence, or null when there is no candidate. |
| `statute` | Identified statute (short title, chapter), populated even on partial resolves. |
| `target` | Matched provision including `display_label`, provision `text`, and a `tree` breadcrumb from the statute root. Present only when `valid` is true. |
| `alternatives` | Up to five other candidates. Populated when `status` is `ambiguous`. |
| `notes` | Human-readable diagnostics explaining why a citation failed. |

### Status values

- `resolved` — single confident match, verified in the graph; `target` populated.
- `ambiguous` — two or more plausible candidates; `alternatives` populated, `target` null.
- `not_found` — citation understood but no matching provision exists (typo, repealed, wrong statute).
- `unsupported` — out of scope (provincial, foreign, or case law); `target` null.

## POST /v1/validate-citation/batch

Validate up to 100 citations in one call. The body is an array of the same objects; the response is an array of the same result objects in the same order. The whole call costs one unit of quota regardless of how many citations it carries, so batching is the cheapest way to validate in bulk.

```bash
curl -X POST https://api.maplejuris.com/v1/validate-citation/batch \
  -H "Authorization: Bearer $MAPLEJURIS_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"query": "Criminal Code s. 718"}, {"query": "PIPEDA s. 5"}]'
```

## Accepted citation styles

The resolver reads free-form text, so citations can be passed as a lawyer would write them:

- Short title + section — `Criminal Code s. 718`
- Subsection — `Access to Information Act, s. 2(1)`
- Paragraph / subparagraph — `s. 718.2(a)(i) of the Criminal Code`
- Chapter form — `R.S.C. 1985, c. C-46, s. 2`
- Common abbreviation — `PIPEDA s. 5`, `CDSA s. 4`, `ITA s. 18`
- Defined term — `definition of "officer" in s. 2 of the Customs Act`
- Full statute title — `Income Tax Act s. 18`

Scope is Canadian federal legislation. Out-of-scope citations return `unsupported` rather than a false negative.

Two known gaps, both reported honestly rather than guessed at (`statute_in_corpus: false` plus an explanatory note): constitutional instruments such as the *Canadian Charter of Rights and Freedoms* are not in the corpus yet, and pinpoints into a *schedule* do not resolve.

## MCP server

Human-readable setup guide (public, no account needed to read): https://maplejuris.com/mcp

Endpoint: `https://api.maplejuris.com/mcp`
Transport: streamable HTTP (JSON-RPC 2.0 over POST, SSE responses). Auth: the same bearer token as REST.

### Tools

**`validate_citation`**
- `query` (string, optional) — citation as written, natural language.
- `structured` (object, optional) — pre-parsed citation; skips the model parse.
- Exactly one of `query` or `structured` must be supplied.
- Returns the same object as `POST /v1/validate-citation`.

**`validate_citations_batch`**
- `queries` (array of strings, 1–100, required).
- Returns `{results: [{index, query, response, error}], summary: {total, succeeded, failed, valid, avg_validity_score}}`.

### Client configuration

Claude Code:

```bash
claude mcp add maplejuris \
  --transport http https://api.maplejuris.com/mcp \
  --header "Authorization: Bearer $MAPLEJURIS_KEY"
```

Codex — `~/.codex/config.toml`:

```toml
experimental_use_rmcp_client = true

[mcp_servers.maplejuris]
url = "https://api.maplejuris.com/mcp"
bearer_token_env_var = "MAPLEJURIS_KEY"
startup_timeout_sec = 20
```

Then `export MAPLEJURIS_KEY=ak_your_key_here` and verify with `codex mcp list`. Codex rejects an inline `bearer_token` for streamable HTTP — it must be an environment variable reference.

Cursor and other clients accepting an HTTP MCP entry:

```json
{
  "mcpServers": {
    "maplejuris": {
      "type": "http",
      "url": "https://api.maplejuris.com/mcp",
      "headers": { "Authorization": "Bearer ak_your_key_here" }
    }
  }
}
```

Claude Desktop and any client that only launches local processes, via the `mcp-remote` bridge:

```json
{
  "mcpServers": {
    "maplejuris": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "https://api.maplejuris.com/mcp",
        "--header",
        "Authorization: Bearer ${MAPLEJURIS_KEY}"
      ],
      "env": { "MAPLEJURIS_KEY": "ak_your_key_here" }
    }
  }
}
```

## Plans, quotas, and errors

| Plan | Licence | Monthly citation validations |
|---|---|---|
| Free | Non-commercial | 1,000 |
| Research ($100/month) | Non-commercial | 10,000 |
| Commercial ($1,000/month) | Commercial | 100,000 |
| Enterprise ($5,000/month) | Commercial | 1,000,000 |

Usage is counted per account (summed across all the account's keys and tokens), per calendar month, and resets on the first of the month. One unit is charged per API request, not per citation: a 100-citation batch costs one unit. Over MCP only `tools/call` is metered — `initialize`, `tools/list`, and reconnecting are free (they still require a valid key). Quota exhaustion returns 429 after the handshake succeeds, so an MCP client connects and reports the error rather than failing to start.

| Code | Meaning |
|---|---|
| `401` | Missing, revoked, or expired API key. |
| `422` | Malformed body; the response names the offending field. |
| `429` | Monthly allowance spent; the message states the plan and its limit. |

## Legal

MapleJuris is a citation-verification tool, not a law firm. It does not provide legal advice and does not create a solicitor-client relationship. All output must be independently verified by a qualified legal professional. Statutory text is public law (Crown copyright, reproduced under the applicable federal and provincial reproduction terms); MapleJuris's proprietary rights are in the graph structure, embeddings, scoring, and validation methodology.

Contact: info@maplejuris.com