District court records, with the coverage caveats printed on the tin

The honest shape of subordinate court data

Three levels, two routes, different reach

The index models a court in three levels. Which of them you can filter on depends on which search route you are using, and the difference is larger here than anywhere else in the hierarchy, because a district establishment can contain a family court, a commercial court, a small causes court and a dozen magistrates.

Order history, and the thing it is not

const BASE = "https://research.courtmesh.ai/api/v1/prod";
const headers = {
  "X-API-Key": process.env.COURTMESH_API_KEY,
  "Content-Type": "application/json",
};

// Order history is a job, not a synchronous read. Start it, then poll.
async function orderHistory(caseId) {
  const started = await fetch(`${BASE}/request-timeline`, {
    method: "POST",
    headers,
    body: JSON.stringify({ case_id: caseId }),
  }).then((r) => r.json());

  // A cached case answers immediately with orders already attached.
  if (started.data.cached) return started.data.orders;

  const requestId = started.data.requestId;

  for (let attempt = 0; attempt < 20; attempt += 1) {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    const poll = await fetch(`${BASE}/get-timeline/${requestId}`, { headers })
      .then((r) => r.json());

    if (poll.data.status === "completed") {
      console.log(poll.data.orderCount, "of", poll.data.totalOrderCount);
      return poll.data.orders;
    }
    if (poll.data.status === "failed") throw new Error(poll.data.error);
  }
  throw new Error("timeline job still running");
}

District Court API questions

Is there a cnr parameter for CNR lookups?

No, and nothing in the request body maps onto one. Pass the CNR as the query string instead. The query parser recognises an alphanumeric prefix followed by a four digit year and normalises separators before searching, which is why a CNR pasted straight from an eCourts page usually works. Treat it as a text match rather than a key lookup, and confirm the record you get back before you build on it.

What do the sixteen characters of a CNR mean?

A CNR is a fixed width identifier issued by the eCourts system: two characters for the state, two for the district, two for the court establishment inside that district, six for the sequential filing number at that establishment, and four for the year of filing. Because the number is allotted at the establishment, it survives renumbering, transfer between courts within the establishment and changes of case type. That is what makes it the most stable identifier a subordinate court matter has.

How do I scope a search to one district or one court establishment?

Through the court parameter, using the verbatim establishment string. There are 740 of them in the district layer and they are inconsistent by nature, because they are what each state registry published: District Court of Agra sits alongside Civil Judge Sr. Divn, Hooghly and District Court of Mumbai Motor Accident Claims T. Pass an array when a district has several establishment strings, and expect to build a small lookup for the districts you care about rather than guessing the format.

Can I filter by case type codes such as O.S. or Sessions Case?

Not reliably. The case type catalogue holds 669 codes drawn from the Supreme Court and the 25 High Courts, and it contains no district entries, so a district case type will not expand and a primary type such as Writ or Appeal will expand into High Court codes rather than subordinate ones. Put the case type in the query text for this layer and rely on court, date and free text instead.

Does the API return cause lists or the next hearing date?

No. There is no cause list route and no next hearing field on any response. What exists is order history: POST /request-timeline starts a job for a case and returns a requestId, and GET /get-timeline/:requestId returns status along with orders, orderCount and totalOrderCount once it finishes. That tells you what has already happened on a matter. It does not tell you when the matter is next listed, and we would rather say so than let a listing product be inferred from a timeline endpoint.

Are district judges searchable through the judge lookup?

No. GET /judges/search reads two lists, 1,069 Supreme Court names and 3,590 High Court names, merged into 4,561 unique entries. The subordinate judiciary is not in that index, so passing a district judge name to judgeName will usually return nothing. Search the officer's name as free text in query, and accept that coverage of presiding officer names in the underlying records is uneven.

How does district coverage compare with High Court and Supreme Court data?

It is broader and thinner at the same time. The corpus runs past 310 million records overall and the district layer supplies much of that volume, but subordinate court records skew towards registry metadata and orders rather than long reasoned judgments, and reporting conventions mean far less of it has ever been written up. The AI analysed and vector indexed subset, roughly two million judgments, is drawn mostly from higher court material. So keyword search reaches district matters well while semantic search reaches them sparsely.

How can I tell how good a particular record is before relying on it?

Read the flags the response already gives you. Every search result carries hasDocuments and hasAnalysis, and the case record adds documentCount. Those three tell you whether a stored document exists, whether structured analysis has been derived, and how many files sit behind the record. Profiling a sample of an establishment on those flags takes one request and is far more useful than any coverage percentage we could quote you.

Can I follow a matter from the district court up through appeal?

Partly, and it takes work. Case numbers change at every tier, so GET /cases/:id/related will not bridge them: it groups documents that share one case number and returns a timeline of that single matter. To follow a dispute upward, carry the party names and the impugned order details into a fresh search scoped to the relevant High Court, then to the Supreme Court. The link is evidentiary rather than structural, which means a human should confirm it.

What are the operational limits on this layer?

The same as everywhere else on the surface: 10 requests per minute for an API key, a maximum of 100 results per page, and 429 responses carrying retryAfter when you exceed the cap. Because district volume is large, use the searchAfter cursor returned by the keyword route for deep pagination instead of walking page numbers, and remember that only GET /health is reachable without a key.