Developer API

Quick start

Every endpoint lives under one base URL, requires a Bearer key, and returns JSON. Create a key on your Account page (Professional), then make your first request:

https://www.clearancesearchengine.com/api/v1

curl -H "Authorization: Bearer case_live_your_key_here" \
  "https://www.clearancesearchengine.com/api/v1/cases?guideline=F&outcome=granted&year_from=2020&per_page=5"

import requests

r = requests.get(
    "https://www.clearancesearchengine.com/api/v1/cases",
    headers={"Authorization": "Bearer case_live_your_key_here"},
    params={"guideline": "F", "outcome": "granted", "year_from": 2020, "per_page": 5},
)
for case in r.json()["data"]:
    print(case["case_number"], case["outcome"], case["decision_date"])

const res = await fetch(
  "https://www.clearancesearchengine.com/api/v1/cases?guideline=F&outcome=granted&year_from=2020&per_page=5",
  { headers: { Authorization: "Bearer case_live_your_key_here" } },
);
const { data } = await res.json();
for (const c of data) console.log(c.case_number, c.outcome, c.decision_date);

Authentication

Send your key as a Bearer token on the Authorization header. Keys look like case_live_ followed by 48 hex characters, and the full key is shown only once, at creation. You can hold up to two active keys per account, and revoke either at any time from your Account page.

Authorization: Bearer case_live_1a2b3c...

A missing, malformed, unknown, or revoked key returns 401 unauthorized. Keep keys secret; treat one like a password.

Rate limits

Each key is allowed 2,000 requests per day, counted per calendar day in UTC and reset at 00:00 UTC. Once the quota is exceeded, requests return 429 quota_exceeded until the reset. For steady jobs, spread requests across the day and cache what you have already pulled. For a higher ceiling or a bulk arrangement, contact us with a description of the project.

Pagination

List endpoints are paged. Pass page (1-based, default 1) and per_page (default 25, maximum 50). Every list response carries page, per_page, and total, the true count across all pages, so you can loop until page × per_page ≥ total.

{
  "data": [ /* … */ ],
  "page": 1,
  "per_page": 25,
  "total": 812
}

Response format

• Successful responses wrap results in a data field.
• Every response includes an attribution string. Display it on any published use of the data (see Terms).
• Dates are ISO 8601. Names, summaries, and rulings are the public-record values shown on the site.
• Guideline letters are A–M; outcomes are upper-case (GRANTED, DENIED, REVOKED); level is HEARING or APPEAL.

Errors

Errors use standard HTTP status codes and a consistent body.

{
  "error": {
    "code": "quota_exceeded",
    "message": "Daily quota of 2000 requests reached; resets at 00:00 UTC."
  }
}

Versioning and stability

• The API is versioned in the path; this documentation covers v1.
• Additive changes (new fields, new optional parameters) may appear without notice. Build clients that ignore fields they do not recognize.
• Breaking changes only ever arrive as a new version path. The prior version keeps running, with its retirement date posted on this page well in advance.
• The record itself grows as DOHA publishes new decisions (ingested nightly), and verified extraction corrections are applied corpus-wide, so responses can gain rows or improve over time.

AI connector (MCP)

CASE supports the Model Context Protocol, the standard AI assistants use to reach outside tools. Once connected, an assistant can search the decided record, open a case, find similar cases, compute statistics and timelines, and read the measured series on time since conduct and candor outcomes, citing CASE pages in its answers.

https://www.clearancesearchengine.com/api/mcp

• Claude (claude.ai or the desktop app): Settings → Connectors → Add custom connector, then paste the URL above.
• ChatGPT: Settings → Connectors (where custom MCP connectors are supported on your plan), then paste the URL.
• Cursor and other MCP clients: add a remote MCP server with the URL above (streamable HTTP transport).
• No key needed for a free allowance of 200 tool calls per day. Add your API key as an Authorization: Bearer case_live_… header for the full API quota; Professional entitlements are attached to the key.
• Tools exposed: search_cases, get_case, similar_cases, get_statistics, get_timelines, get_conduct_recency, get_candor_outcomes. Read-only, public record only.
• A plain-language walkthrough for non-developers is at the connector page.

Terms and fair use

• The data is the decided public record, descriptive only. Do not present it as a prediction, as legal advice, or as a rating or score of any judge, attorney, or applicant.
• Attribute published uses: “Data: CASE (clearancesearchengine.com)”. The attribution field in every response carries the full line.
• Build on the record; do not bulk-mirror or resell the corpus as a dataset, and do not re-host it as a competing copy.
• The API is read-only and returns only the public record. It never exposes user data, uploads, or accounts, yours or anyone else’s.
• Access is included with an active Professional plan and follows the same Terms of Service.