Reference
HTTP API.
Every route the server has. The law engine, the health self-test, the facts file and the MCP endpoint are public on the hosted site. The three model routes work only on a self-hosted deployment that sets a server key. Examples on this page were produced by the real handlers when the page was built.
Routes at a glance
| Route | What it does | Hosted site | Limits |
|---|---|---|---|
| POST /api/rules | The Section 479 engine on typed-in facts. No model, no network. | Yes | zod-validated input; up to 40 sections |
| GET /api/health | Liveness plus a self-test of the engine and the verifier. | Yes | never cached |
| GET /api/facts | The numbers the site shows, with sources, and the evaluation report. | Yes | cached 5 minutes |
| POST /api/extract | Reads one document with Claude, verifies the quotes, applies the law. | Self-host only (503 without a key) | text ≤ 60,000 chars · 12/min per IP · daily spend cap |
| POST /api/baseline | The plain-chatbot answer, for comparison. | Self-host only | text ≤ 60,000 chars · 6/min per IP · daily spend cap |
| POST /api/ocr | Transcribes one scanned page. | Self-host only | image ≤ 7,000,000 base64 chars · 30/min per IP · daily spend cap |
| POST /mcp | The MCP server over stateless Streamable HTTP (JSON-RPC 2.0). | Yes | body ≤ 2 MB · 120/min per IP |
Hosted site and server keys
The hosted site holds no Anthropic key, so/api/extract, /api/baseline and /api/ocr answer 503 there. The site reads new papers in the visitor's browser with the visitor's own key instead (see Security). To use these routes, deploy your own copy with ANTHROPIC_API_KEY set (see Self-hosting).Errors and status codes
The /api routes answer errors as JSON with one field, {"error": "..."}. The message is safe to show to a person; it never contains document text. /mcp answers JSON-RPC errors ({"jsonrpc":"2.0","error":{"code":…,"message":…},"id":…}).
| Status | When |
|---|---|
| 200 | Success. On /mcp also a tool call whose input failed validation: the result has isError: true and the reason as text. |
| 400 | Body is not JSON, or fails the schema (the first validation message is returned). On /mcp: a JSON-RPC parse error. |
| 406 | /mcp only: the Accept header must include both application/json and text/event-stream. |
| 413 | /mcp only: body over 2 MB, by the Content-Length header or by actual length. |
| 429 | Per-IP limit for this minute reached. Try again in a minute. |
| 503 | Model routes: no server key is configured, or today's spend cap is used up. /api/health: the self-test failed. |
| 500 | Anything else. The message is generic: “Something went wrong reading this document.” |
Validation runs before the rate limit and before any model call, so a malformed request costs nothing. Rate limits and the spend cap are counted in Cloudflare KV; the model routes skip both when no KV namespace is bound (local runs), while /mcp falls back to an in-memory count per isolate.
POST /api/rules
Applies Section 479 to facts you already know. Pure code: the same request always gives the same answer.
| Field | Type | Notes |
|---|---|---|
| today | string | YYYY-MM-DD. Required: the date to evaluate as of. |
| input.sections[] | array, ≤ 40 | Each { act, section, quantity?, spanId? }. |
| input.sections[].act | enum | IPC, BNS, NDPS, ARMS, POCSO, SCST, DOWRY, GAMBLING, IT, EXCISE, GANGSTERS, OTHER |
| input.sections[].section | string, ≤ 40 | As written: 379, 304-B, 25(1-b)(a), 3/25 (compound references are split). |
| input.sections[].quantity | enum? | NDPS only: small, intermediate, commercial, unknown. |
| input.custodyStart | string | null | YYYY-MM-DD. null means the papers don't say. |
| input.firstTimeOffender | enum | true, false, unknown (strings). |
| input.otherPendingCases | enum | true, false, unknown (strings). |
| input.accusedDelayDays | number? | 0–10,000. Days of delay caused by the accused. |
| input.registeredOn | string | null? | YYYY-MM-DD. Decides the pre-July-2024 note. |
| input.maxTermOverrideMonths | number | null? | 1–1,200. A maximum a lawyer entered when the tables can't decide. |
curl -s https://halftime.prashantthakur.dev/api/rules \
-H 'content-type: application/json' \
-d '{
"today": "2026-11-15",
"input": {
"sections": [
{
"act": "IPC",
"section": "379"
}
],
"custodyStart": "2024-05-20",
"firstTimeOffender": "true",
"otherPendingCases": "false",
"registeredOn": null
}
}'{
"provision": "BNSS_479_PRE_JULY_2024",
"sections": [
{
"act": "IPC",
"section": "379",
"canonical": "379",
"found": true,
"title": "Punishment for theft",
"punishment": {
"kind": "term",
"months": 36
},
"source": "IPC 1860 s.379"
}
],
"trace": [
{
"step": "section",
"text": "IPC 1860 s.379 (Punishment for theft) → max 3 years",
"source": "IPC 1860 s.379"
},
{
"step": "provision",
"text": "Case from before 1 Jul 2024: Sec 479 BNSS still applies, per the Supreme Court order of 23 Aug 2024. Old Sec 436A CrPC (half line, no first-time benefit) shown for comparison.",
"source": "SC order, W.P.(C) 406/2013, 23 Aug 2024"
},
{
"step": "max_term",
"text": "Maximum term: 3 years (IPC 1860 s.379).",
"source": "IPC 1860 s.379"
},
{
"step": "fraction",
"text": "First-time offender (per the papers): one-third of 3 years.",
"source": "BNSS 2023 s.479(1) and first proviso"
},
{
"step": "custody",
"text": "Custody began 20 May 2024."
},
{
"step": "line",
"text": "Line: 20 May 2025."
},
{
"step": "today",
"text": "Today: 15 Nov 2026; 909 days detained."
},
{
"step": "result",
"text": "PAST THE LINE by 544 days: the jail superintendent must apply under Sec 479(3). A lawyer reviews and signs."
}
],
"flags": [],
"missing": [],
"daysDetained": 909,
"firstTimeLineDate": "2025-05-20",
"oldLawLineDate": "2025-11-20",
"daysPast": 544,
"daysToGo": null,
"beyondMaximum": false,
"pastIfFirstTime": false,
"verdict": "PAST_THE_LINE",
"maxTermMonths": 36,
"fraction": "1/3",
"lineDate": "2025-05-20"
}With registeredOn null and an IPC section charged, the engine treats the case as registered before July 2024, which is why provision is BNSS_479_PRE_JULY_2024 and oldLawLineDate is filled.
The response is the engine's Evaluation: verdict, provision, maxTermMonths, fraction, lineDate, firstTimeLineDate, oldLawLineDate, daysDetained, daysPast, daysToGo, beyondMaximum, pastIfFirstTime, flags[], missing[], sections[] (how each section was resolved) and trace[] (each step with its statute source). The rules are on How Section 479 is computed.
{
"error": "Use YYYY-MM-DD."
}GET /api/health
Applies the engine to a known theft case and runs the verifier on a Hindi sentence (one real quote must pass, one with a changed year must fail). status is ok with HTTP 200, or degraded with 503. build is the build date; ms the time the self-test took. The scheduled production check and the status page call it.
curl -s https://halftime.prashantthakur.dev/api/health
{
"status": "ok",
"engine": "PAST_THE_LINE",
"verifier": true,
"build": "2026-11-14",
"ms": 0
}GET /api/facts
The file every number on the site comes from (apps/web/src/data/facts.json, built by scripts/build-facts.ts). Top-level keys: sources, undertrials_2024, undertrial_share_2024, prison_occupancy_2024, identified_479_2024, applications_479_2024, released_479_2024, held_over_2y_2024, held_over_5y_2024, sc_order_date, eval. Each statistic is { value, source, unit? }; sources maps a key to { label, url }; eval is the evaluation report (eval/report.json).
curl -s https://halftime.prashantthakur.dev/api/facts
POST /api/extract
Self-host only. Runs extraction and the missing-section self-check with Claude, merges any sections the self-check found, then verifies every quote and applies the law. today defaults to the server's date.
| Field | Type | Notes |
|---|---|---|
| text | string | 40–60,000 characters: the order's text. |
| today | string? | YYYY-MM-DD. |
curl -s https://your-deployment.example/api/extract -H 'content-type: application/json' \
-d '{"text": "<the order text>", "today": "2026-11-15"}'The response has these fields:
extraction: what the model returned, each fact with its quote.facts:input(the facts the engine used),spans[](each accepted fact with its start and end offsets intext) andrejected[](field, claim, quote, reason).evaluation: the same shape as/api/rules.text: the normalised document the offsets point into;selfCheckAdded: how many sections the self-check added; andmeta[]: model, cached, ms, tokens and cost for each call.
Errors: 400 for text that is too short or too long; 429 over 12 requests per minute per IP; 503 without a key or over the spend cap.
POST /api/baseline
Self-host only. Asks the same model the question a person would type (“Is the accused eligible for release under Section 479 of the BNSS? If yes, from what date?”), then a small model reads the answer into yes, no or unclear. Used for the comparison on /vs-chatbot; it is not part of HalfTime's decision.
{ "text": "<the order text, 40–60,000 characters>" }{
"answer": { "text": "<the chatbot's paragraph>", "saysEligible": true | false | null, "date": "YYYY-MM-DD" | null },
"meta": [ { "model", "cached", "ms", "inputTokens", "outputTokens", "costUsd" }, ... ]
}Errors: 400 “Send the document text.”; 429 over 6 per minute per IP; 503 without a key or over the spend cap.
POST /api/ocr
Self-host only. Transcribes one scanned page with Claude Opus 5.5, keeping Devanagari as Devanagari.
| Field | Type | Notes |
|---|---|---|
| image | string | Base64 of one page, 100 to 7,000,000 characters. |
| mediaType | enum | image/png or image/jpeg. |
{ "text": "<the transcription>", "meta": { "model", "cached", "ms", "inputTokens", "outputTokens", "costUsd" } }Errors: 400 “Send one PNG or JPEG page as base64.”; 429 over 30 pages per minute per IP; 503 without a key or over the spend cap.
POST /mcp (JSON-RPC)
The remote MCP server: stateless Streamable HTTP, JSON responses, no session. Send Content-Type: application/json and Accept: application/json, text/event-stream. The connected client's model does the reading; these tools only verify quotes and apply the law, so no key is involved. Tools and their inputs are on MCP server.
initialize
curl -s https://halftime.prashantthakur.dev/mcp -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'{
"result": {
"protocolVersion": "2025-06-18",
"capabilities": {
"tools": {
"listChanged": true
},
"prompts": {
"listChanged": true
}
},
"serverInfo": {
"name": "halftime",
"version": "1.0.0"
},
"instructions": "HalfTime applies Section 479 of the Bharatiya Nagarik Suraksha Sanhita (BNSS) to Indian court papers: an under… (1,324 characters)"
},
"jsonrpc": "2.0",
"id": 1
}tools/list
curl -s https://halftime.prashantthakur.dev/mcp -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'Returns 7 tools, each with its full JSON input schema and annotations (all read-only): check_order, sweep_jail, apply_section_479, lookup_section, draft_application, list_sample_orders, get_sample_order. The local file tools are never exposed here.
tools/call
curl -s https://halftime.prashantthakur.dev/mcp -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"lookup_section","arguments":{"act":"IPC","section":"379"}}}'{
"result": {
"content": [
{
"type": "text",
"text": "IPC 1860 s.379 · Punishment for theft\nAct: Indian Penal Code, 1860\nMaximum: up to 3 years\nSource: IPC 1860 s.379\nBNS equivalent: 303(2) (one-to-one)"
}
]
},
"jsonrpc": "2.0",
"id": 3
}{
"result": {
"content": [
{
"type": "text",
"text": "MCP error -32602: Input validation error: Invalid arguments for tool lookup_section: Invalid option: expected one of \"IPC\"|\"BNS\"|\"NDPS\"|\"ARMS\"|\"POCSO\"|\"SCST\"|\"DOWRY\"|\"GAMBLING\"|\"IT\"|\"EXCISE\"|\"GANGSTERS\"|\"OTHER\" at act"
}
],
"isError": true
},
"jsonrpc": "2.0",
"id": 4
}Limits: 2 MB per request (413), 120 requests per IP per minute (429), and bounded tool inputs: documents ≤ 120,000 characters, quotes ≤ 4,000, sweeps ≤ 50 orders.