On this page

API Reference

Run the same AI legal research pipeline that powers the web app, straight from your own code or from Claude. Every request authenticates with a Personal Access Token.

Get API keys Quickstart

There are two ways to use the API, and both authenticate the same way, with a Personal Access Token (an API key):

Direct REST — submit a research query over HTTP and poll for the finished memo. Documented below.
Claude (MCP) — connect the research pipeline as tools inside Claude Code, Claude Desktop, or claude.ai. See Connect Claude.

The base URL for all REST endpoints is:

Base URL

https://api.casescout.ai

Authentication

Every request must include an API key. Create one in Settings, API Keys (this is the same key you use to connect Claude). The full token is shown once, on creation, so copy it immediately, it cannot be retrieved again.

Send it as a bearer token in the Authorization header:

Authorization header

Authorization: Bearer pat_xxxxxxxxxxxxxxxxxxxxxxxx

A key acts as your full account, treat it like a password and never commit it or expose it in client-side code.
Each research run is billed to your account, exactly as if you had run it in the web app.
Revoke a key at any time from Settings, API Keys. Revoked or expired keys return 401.

Quickstart

Research is asynchronous: you start a query, get a session_id back immediately, then poll until the memo is ready. Here is the full round trip with curl.

bash

# 1. Start a research query
curl -X POST https://api.casescout.ai/api/research/query \
  -H "Authorization: Bearer $CASESCOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Test for severance of counts in a criminal trial",
    "case_type": "criminal",
    "research_type": "deep",
    "filters": { "court": "Court of Appeal for Ontario", "dateRange": "from-2018" }
  }'
# → { "message": "Research started", "session_id": "3f2a..." }

# 2. Poll until it returns 200 (202 means still running)
curl https://api.casescout.ai/api/research/results/3f2a... \
  -H "Authorization: Bearer $CASESCOUT_API_KEY"

Research options

GET/api/research/options

Returns the valid values for case_type, research_type, and each filter, the canonical source the web app itself renders. Public, no key required. Fetch this first so you never hard-code option values that can drift.

200 OK

{
  "case_types": [
    { "value": "criminal", "label": "Criminal Law" },
    { "value": "civil",    "label": "Civil Law" },
    { "value": "family",   "label": "Family Law" }
  ],
  "research_types": [
    { "value": "deep",     "label": "Standard Research" },
    { "value": "verified", "label": "Advanced Research" },
    { "value": "beta",     "label": "Pro Research" }
  ],
  "research_type_notes": { "non_criminal_forces_verified": true },
  "filters": {
    "dateRange":    [ { "value": "all", "label": "All Time" }, { "value": "from-2025", "label": "From 2025" } ],
    "jurisdiction": [ { "value": "all", "label": "All Jurisdictions" }, { "value": "Ontario", "label": "Ontario" } ],
    "court":        [ { "value": "all", "label": "All Courts" }, { "value": "Court of Appeal for Ontario", "label": "Court of Appeal for Ontario" } ]
  }
}

Start research

POST/api/research/query

Body (JSON):

Field	Type	Description
`query`required	string	The legal question to research.
`case_type`	string	Corpus: `criminal` (default), `civil`, or `family`.
`research_type`	string	`fast` (default; legacy, no longer shown in-app), `deep` (Standard), `verified` (Advanced), or `beta` (Pro — criminal-only, Pro/Team plans). Civil and family corpora only support Advanced, so `fast`/`deep`/`beta` are coerced to `verified` for them.
`filters`	object	Optional. Any of `dateRange`, `jurisdiction`, `court`, using values from `/api/research/options`.
`conversation_id`	string	Set to ask a follow-up in an existing conversation. See Follow-up questions.

Returns immediately with a session_id, the run continues in the background:

200 OK

{ "message": "Research started", "session_id": "3f2a1c8e-..." }

Poll for results

GET/api/research/results/{session_id}

Returns 202 while the research is still running, then 200 with the full result once complete. Poll every 1 to 2 seconds. Standard runs finish in seconds; Advanced and Pro runs can take a few minutes.

The result is a rich object, the most useful fields are shown trimmed below:

200 OK (trimmed)

{
  "success": true,
  "query": "Test for severance of counts in a criminal trial",
  "response": "## Executive summary\n\n...full memo in Markdown...",
  "executiveSummary": "...",
  "keyFindings": ["...", "..."],
  "citedDocuments": [
    {
      "id": "...",
      "title": "R. v. Last",
      "citation": "2009 SCC 45",
      "court": "Supreme Court of Canada",
      "date": "2009",
      "relevanceScore": 0.94,
      "keyPassages": ["..."],
      "url": "https://..."
    }
  ],
  "legalPrinciples": ["..."],
  "recommendations": ["..."],
  "processingTime": 42.7,
  "costBreakdown": { "totalCost": 0.083, "totalTokens": 51234 },
  "conversation_id": "c1a2...",
  "timestamp": "2026-07-16T08:12:00Z"
}

A 404 means the session id is unknown or has expired. Fetch results reasonably soon after the run completes.

Follow-up questions

To continue a conversation, pass the conversation_id from a completed result back into POST /api/research/query. The pipeline answers from the existing research context, and only runs a fresh search if the follow-up needs one.

bash

curl -X POST https://api.casescout.ai/api/research/query \
  -H "Authorization: Bearer $CASESCOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How does that apply to a multi-complainant sexual assault case?",
    "conversation_id": "c1a2..."
  }'

Manage API keys

Keys are normally created in the UI, but the same operations are available over the API (authenticated with an existing key). The plaintext token is returned only on POST.

GET/api/api-keys

List your keys (metadata only, never the token).

POST/api/api-keys

Field	Type	Description
`name`required	string	A label for the key (1 to 100 characters).
`expires_in_days`	integer	Optional. Days until the key expires (1 to 3650). Omit for a non-expiring key.

201 Created

{
  "id": 12,
  "name": "My integration",
  "token_prefix": "pat_ab12",
  "token": "pat_ab12...full-token-shown-once...",
  "created_at": "2026-07-16T08:00:00Z",
  "expires_at": null
}

DELETE/api/api-keys/{key_id}

Revoke (soft-delete) a key. Returns 204. The key stops working immediately.

Connect Claude (MCP)

The same pipeline is available as a Model Context Protocol connector, so you can run research from inside Claude. The MCP endpoint is:

MCP endpoint

https://mcp.casescout.ai/mcp

It exposes three tools:

Tool	Purpose
`list_research_options`	List valid corpora, modes, and filter values.
`start_legal_research`	Submit a query, returns a `session_id`.
`get_research_result`	Poll a `session_id`, returns running or the memo.

Claude Code (recommended)

bash

claude mcp add --transport http legal-ai https://mcp.casescout.ai/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Claude Desktop

Add this to claude_desktop_config.json (via the mcp-remote bridge), then restart Claude:

claude_desktop_config.json

{
  "mcpServers": {
    "legal-ai": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.casescout.ai/mcp",
        "--header",
        "Authorization: Bearer YOUR_API_KEY"
      ]
    }
  }
}

The claude.ai web connector authenticates via OAuth (there is no field for a static API key). Claude Code and Claude Desktop use the API key header shown above.

Errors

Status	Meaning
`202`	Research not finished yet, keep polling the results endpoint.
`401`	Missing, invalid, revoked, or expired API key.
`402`	Out of credits, or trial expired. The body carries an `error` code and remaining balance.
`403`	Your plan does not include the requested mode or corpus (`plan_upgrade_required`).
`404`	Session id unknown or expired.
`500`	Unexpected server error.

Limits & notes

Full-account scope. A key can do anything your account can. There are no granular scopes yet.
Async, poll to completion. Results live in memory on the backend, fetch them soon after the run finishes rather than much later.
Advanced/Pro runs take longer. Standard returns in seconds; Advanced and Pro (and civil/family, which coerce to Advanced) can take a few minutes.
Not legal advice. Results are a research aid, verify everything before relying on it. See our Terms.

Questions or need higher limits? Contact us.