API quickstart

The REST API serves the same data as the browser and MCP interfaces. Its base URL is https://api.caseharvester.org/api/v1.

Authenticate

Send your token, which starts with chv_, as a bearer credential on every data request:

Authorization: Bearer chv_your_token

Tokens identify one person and must not be shared. The interactive reference can reuse a token already saved in your browser by the app.

Allowance and request limits

REST queries, counts, aggregates, CSV exports, and MCP tools all count against one rolling 30-day row allowance. Each person on an account has their own, and they all reset on the same date. The allowance is a guardrail against bulk extraction, and ordinary research work rarely reaches it. If your project does, contact [email protected] to have it raised. The license terms describe how it works.

A query page may request at most 1,000 rows. For a larger result set, keep the same sort on every page and move through it with successive startRow/endRow windows on POST /query/{table}. That is the only endpoint that pages: counts, aggregates, and exports each answer one whole thing, so a body carrying startRow or endRow is refused there. Send every request body as application/json.

One CSV export may return at most 100,000 rows. An export that needs more rows than you have left in your allowance is refused before any rows count, rather than cut short.

Aggregate without retrieving every row

POST /aggregate/{table} applies the same filters as a row query, then groups the matching slice and counts rows or sums a published measure.

Results contain at most 50,000 groups. A true truncated value means additional groups were omitted, and totalGroups says how many the filter produced. Send maxGroups to ask for fewer. A larger figure is refused rather than trimmed. Read each table's groupableColumns, bucketableColumns, and summableColumns from GET /metadata. Selectable fields do not automatically support aggregation.

Minimum pattern lengths

Substring filters need a minimum number of consecutive letters or digits:

• contains requires at least three consecutive alphanumeric characters.
• startsWith requires at least one alphanumeric character.
• endsWith requires at least two consecutive alphanumeric characters.

Shorter patterns would force a slow scan of the whole table, so they are rejected.

Capabilities come from the catalog

A column may be selectable without being sortable or filterable. Each table's sortableColumns, native-column filterOperators, and qualified parent-case caseFilterOperators are the authoritative, index-backed lists. Keys in caseFilterOperators use the case.* namespace. Read GET /metadata before constructing a query rather than assuming every served field supports every operation.

The public data codebook presents query and aggregation capabilities alongside the served field definitions.

Complete reference

The public interactive API reference documents ordinary access. After authentication, GET /metadata returns the exact tables and fields available to your account.

Last updated: September 3, 2026