API overview and conventions

#Base URL

http://127.0.0.1:8787/v1

The API listens on loopback only. Through the console's dev server the same routes are under /api/v1/… (Vite strips the /api prefix). In the hosted review workspace, only /v1/radar/* routes are served.

#Route groups

#Requests

• POST and DELETE bodies are JSON and need Content-Type: application/json (otherwise 415).
• JSON bodies are capped at 100 KB (413 above that). The watchlist import route accepts up to 1 MB.
• Path segments such as case numbers are URL-encoded: DMA.100075 is sent as is, AT.40437 too.
• Dates are ISO YYYY-MM-DD.

#Responses

All responses are JSON, except the HTML case snapshot. Every response carries:

Radar responses also carry sample: true or a mode field when they come from the sample inventory.

#Errors

Errors are a JSON object with a human-readable error sentence and, where useful, a stable machine code:

{ "error": "The quote does not appear word for word in that recital.", "code": "quote_not_in_recital" }

Match on code, never on the sentence. See Errors and status codes for the full list.

#Authentication

Reads need nothing locally. Writes need an operator token once CLEARY_OPERATOR_TOKENS is set:

Authorization: Bearer <token>

See Authenticate writes.

#Attribution fields

Writes that record a human act name the person: by, reviewedBy, requestedBy, importedBy, proposedBy or estimatedBy, 1–120 characters. With operator tokens on, BINA fills them from the token and refuses a mismatch with 403.

#Pagination

List routes accept limit and offset and return total, offset and limit. The default limit is 200, the maximum 1,000.

#Browser access

A disallowed Origin is 403; a Host outside the allowlist is 421. Allowed origins default to the console's Vite origins. Extend with CLEARY_ALLOWED_ORIGINS and CLEARY_ALLOWED_HOSTS only behind a reverse proxy.