CaseDiver API v1

# No key required — lists endpoints and current prices
curl https://casediver.com/api/v1

Authorization: Bearer lt_live_xxxxxxxxxxxxxxxxxxxx
# or
X-API-Key: lt_live_xxxxxxxxxxxxxxxxxxxx

{
  "results": [ ... ],
  "usage": {
    "operation": "case_search",
    "quantity": 7,
    "costMillicents": 210,
    "costCents": 21,
    "breakdown": { "cases": 7 }
  },
  "requestId": "req_Ab3xK9pQ"
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid search request.",
    "details": [
      { "field": "jurisdiction.state", "message": "jurisdiction.state is required when type is 'one_state'" }
    ]
  },
  "usage": null,
  "requestId": "req_Ab3xK9pQ"
}

curl -X POST https://casediver.com/api/v1/search \
  -H "Authorization: Bearer $LAWTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-request-2026-08-13-001" \
  -d '{"query":"adverse possession","jurisdiction":{"type":"one_state","state":"FL"},"limit":5}'

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
Retry-After: 12          # only on 429

const BASE = 'https://casediver.com/api/v1';
const KEY = process.env.LAWTOOLS_API_KEY!; // server-side only

async function call<T>(path: string, body?: unknown, idempotencyKey?: string): Promise<T> {
  const res = await fetch(BASE + path, {
    method: body ? 'POST' : 'GET',
    headers: {
      Authorization: `Bearer ${KEY}`,
      ...(body ? { 'Content-Type': 'application/json' } : {}),
      ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });

  const json = await res.json();
  if (!res.ok) {
    // Quote requestId in support tickets; it keys our log line and ledger row.
    throw new Error(`${json.error?.code}: ${json.error?.message} (${json.requestId})`);
  }
  return json as T;
}

const found = await call<{ results: Array<{ caseName: string; citation: string }> }>('/search', {
  query: 'promissory estoppel reliance damages',
  jurisdiction: { type: 'one_state_plus_federal', state: 'NY' },
  limit: 5,
});

for (const r of found.results) console.log(r.caseName, '—', r.citation);

curl -X POST https://casediver.com/api/v1/search \
  -H "Authorization: Bearer $LAWTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "qualified immunity excessive force",
    "jurisdiction": { "type": "federal_circuit", "circuit": "11" },
    "limit": 5,
    "filters": { "dateFrom": "2015-01-01" }
  }'

{
  "results": [
    {
      "caseId": "4218873",
      "caseName": "Smith v. City of Miami",
      "citation": "812 F.3d 1234",
      "court": "United States Court of Appeals for the Eleventh Circuit",
      "courtAbbreviation": "11th Cir.",
      "jurisdiction": "Eleventh Circuit",
      "dateFiled": "2016-02-11",
      "year": 2016,
      "published": true,
      "citedByCount": 74,
      "snippet": "...the officers' use of force was not objectively reasonable...",
      "snippetSource": "citing_opinion",
      "goodLaw": {
        "status": "good_law",
        "negative": false,
        "unknown": false,
        "negativeTreatmentCount": 0,
        "basis": "No negative treatment among 74 citing opinions."
      },
      "matchExplanation": "Matched on keyword and semantic recall.",
      "retrievalUrl": "https://casediver.com/api/v1/cases/4218873/pdf"
    }
  ],
  "total": 1,
  "totalAvailable": 46,
  "searchInfo": {
    "enginesUsed": ["keyword", "semantic"],
    "jurisdictionLabel": "the 11th Circuit and the U.S. Supreme Court",
    "citationsDetected": [],
    "liftedPhrases": [],
    "bodyTextSearchUnavailable": false,
    "latencyMs": 412
  },
  "suggestion": null,
  "usage": { "operation": "case_search", "quantity": 1, "costCents": 3, "breakdown": { "cases": 1 } },
  "requestId": "req_Ab3xK9pQ"
}

curl -X POST https://casediver.com/api/v1/citecheck/cite \
  -H "Authorization: Bearer $LAWTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"citations":["570 U.S. 744","999 F.3d 1"]}'

{
  "results": [
    {
      "citationAsWritten": "570 U.S. 744",
      "verdict": "valid",
      "correctedCitation": "United States v. Windsor, 570 U.S. 744 (2013)",
      "explanation": "This citation resolves to a case in the corpus.",
      "corpusCaveat": null,
      "reporterKeys": ["us/570/744"],
      "candidates": [
        {
          "caseId": "2812209",
          "caseName": "United States v. Windsor",
          "bluebookCitation": "United States v. Windsor, 570 U.S. 744 (2013)",
          "citation": "570 U.S. 744",
          "parallelCitations": ["133 S. Ct. 2675", "186 L. Ed. 2d 808"],
          "court": "Supreme Court of the United States",
          "year": 2013,
          "published": true,
          "citedByCount": 1204,
          "goodLaw": { "status": "good_law", "negative": false, "unknown": false },
          "matchedBy": "reporter_key",
          "confidence": 1,
          "retrievalUrl": "https://casediver.com/api/v1/cases/2812209/pdf"
        }
      ]
    }
  ],
  "usage": { "operation": "citecheck_cite", "quantity": 2, "costCents": 6 },
  "requestId": "req_Ab3xK9pQ"
}

curl -X POST https://casediver.com/api/v1/citecheck/document \
  -H "Authorization: Bearer $LAWTOOLS_API_KEY" \
  -F "[email protected]"

{
  "jobId": "9f2c1a44-8e7b-4d2a-9c15-6b0e3f7a1d88",
  "status": "queued",
  "fileName": "brief.pdf",
  "fileSize": 1841204,
  "statusUrl": "https://casediver.com/api/v1/citecheck/jobs/9f2c1a44-.../",
  "reportUrl": "https://casediver.com/api/v1/citecheck/jobs/9f2c1a44-.../report",
  "pollAfterSeconds": 5,
  "requestId": "req_Ab3xK9pQ"
}

{
  "jobId": "9f2c1a44-8e7b-4d2a-9c15-6b0e3f7a1d88",
  "status": "completed",
  "fileName": "brief.pdf",
  "pageCount": 34,
  "citationCount": 41,
  "counts": { "valid": 36, "likelyValid": 3, "notFound": 2 },
  "otherAuthoritiesFound": 7,
  "citations": [ /* one entry per citation, same shape as the cite endpoint */ ],
  "reportUrl": "https://casediver.com/api/v1/citecheck/jobs/9f2c1a44-.../report",
  "error": null,
  "createdAt": "2026-08-13T14:02:11.000Z",
  "completedAt": "2026-08-13T14:03:04.000Z"
}

curl -X POST https://casediver.com/api/v1/cases/retrieve \
  -H "Authorization: Bearer $LAWTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Smith v. Jones"}'

{
  "status": "did_you_mean",
  "message": "More than one case could match... Choose one and call this endpoint again with its `caseId` (no charge for this response).",
  "candidates": [
    {
      "caseId": "1183422",
      "caseName": "Smith v. Jones",
      "bluebookCitation": "Smith v. Jones, 421 So. 2d 1024 (Fla. 1982)",
      "year": 1982,
      "confidence": 0.82,
      "matchedBy": "case_name",
      "pdfUrl": "https://casediver.com/api/v1/cases/1183422/pdf"
    }
  ],
  "charged": false,
  "usage": { "operation": "case_retrieval", "quantity": 0, "costCents": 0 },
  "requestId": "req_Ab3xK9pQ"
}

curl -X POST https://casediver.com/api/v1/cases/retrieve \
  -H "Authorization: Bearer $LAWTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Smith v. Jones","caseId":"1183422"}'

curl -L https://casediver.com/api/v1/cases/2812209/pdf \
  -H "Authorization: Bearer $LAWTOOLS_API_KEY" \
  -o windsor.pdf

Content-Type: application/pdf
Content-Disposition: inline; filename="United States v. Windsor.pdf"
X-Request-Id: req_Ab3xK9pQ
X-CaseDiver-Operation: case_retrieval
X-CaseDiver-Charge-Units: 1
X-CaseDiver-Charge-Cents: 5

curl "https://casediver.com/api/v1/usage?days=30" \
  -H "Authorization: Bearer $LAWTOOLS_API_KEY"

{
  "consumer": { "name": "Acme Legal", "email": "[email protected]", "status": "active" },
  "periodDays": 30,
  "since": "2026-07-14T00:00:00.000Z",
  "byOperation": [
    { "operation": "case_search", "calls": 412, "units": 3180, "costCents": 954 },
    { "operation": "case_retrieval", "calls": 96, "units": 88, "costCents": 440 }
  ],
  "totalCostCents": 1394,
  "yourPricing": {
    "caseSearchPerCase": 3,
    "citeCheckPerCitation": 2,
    "citeCheckPerPage": 1,
    "caseRetrievalPerCase": 5,
    "rateLimitPerMinute": 60,
    "maxCasesPerSearch": 100
  },
  "requestId": "req_Ab3xK9pQ"
}

import { readFile } from 'node:fs/promises';

// 1. Upload
const form = new FormData();
form.append('file', new Blob([await readFile('brief.pdf')], { type: 'application/pdf' }), 'brief.pdf');

const started = await fetch(BASE + '/citecheck/document', {
  method: 'POST',
  headers: { Authorization: `Bearer ${KEY}` }, // no Content-Type: fetch sets the boundary
  body: form,
}).then((r) => r.json());

// 2. Poll. 5s matches pollAfterSeconds; the cap turns a stuck job into an error.
let job = started;
for (let i = 0; i < 120 && (job.status === 'queued' || job.status === 'processing'); i++) {
  await new Promise((r) => setTimeout(r, 5000));
  job = await call(`/citecheck/jobs/${started.jobId}`);
}
if (job.status !== 'completed') throw new Error(`Cite check ${job.status}: ${job.error ?? 'timed out'}`);

console.log(`${job.citationCount} citations over ${job.pageCount} pages`, job.counts);

// 3. Download the report (free — the charge landed when it was produced)
const pdf = await fetch(`${BASE}/citecheck/jobs/${started.jobId}/report`, {
  headers: { Authorization: `Bearer ${KEY}` },
}).then((r) => r.arrayBuffer());

let hit = await call<any>('/cases/retrieve', { query: 'Smith v. Jones' });

if (hit.status === 'did_you_mean') {
  // Present hit.candidates to a human. Auto-picking the top candidate is a
  // product decision — it can silently return a case nobody asked for.
  const chosen = hit.candidates[0];
  hit = await call<any>('/cases/retrieve', { query: 'Smith v. Jones', caseId: chosen.caseId });
}

if (hit.status === 'not_found') {
  console.log('No match.', hit.corpusCaveat ?? '');
} else {
  const pdf = await fetch(hit.case.pdfUrl, {
    headers: { Authorization: `Bearer ${KEY}` },
  }).then((r) => r.arrayBuffer());
}

const key = `search-${crypto.randomUUID()}`; // one key per distinct request

async function withRetry<T>(path: string, body: unknown): Promise<T> {
  for (let attempt = 0; attempt < 3; attempt++) {
    try {
      return await call<T>(path, body, key); // same key: at most one charge
    } catch (err) {
      if (attempt === 2) throw err;
      await new Promise((r) => setTimeout(r, 1000 * 2 ** attempt));
    }
  }
  throw new Error('unreachable');
}

import os, requests

BASE = "https://casediver.com/api/v1"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['LAWTOOLS_API_KEY']}"

res = session.post(f"{BASE}/citecheck/cite", json={"citations": ["570 U.S. 744", "999 F.3d 1"]})
res.raise_for_status()
payload = res.json()

for item in payload["results"]:
    print(item["citationAsWritten"], "->", item["verdict"])
    if item["verdict"] == "likely_valid":
        for cand in item["candidates"]:
            print("   did you mean:", cand["bluebookCitation"])

print("charged (cents):", payload["usage"]["costCents"])

cd tools/api-tester
npm install
npm run dev            # http://localhost:5199

# Point it at a different server (defaults to http://localhost:4000)
$env:LAWTOOLS_API_URL = "https://casediver.com"; npm run dev