Emerald API + MCP

One corpus for judgments and statutes.

Search Kenyan legal data through REST, or connect the same corpus to an MCP-compatible assistant so it can find and read the law when it needs it.

REST API authentication

Send your Emerald key in the X-API-Key header.

X-API-Key: em_live_...

The base URL is https://www.emerald.ynai.co.ke.

Search legal data

GET /v1/search

Search judgment and statute text together, or filter to one document type.

Example

curl "https://www.emerald.ynai.co.ke/v1/search?q=adverse+possession&document_type=judgment&limit=10" \
  -H "X-API-Key: em_live_..."

Parameter	What it does
`q`	Words, a phrase, party name, statute name or citation to search for.
`document_type`	`judgment` for cases, `statute` for legislation. Omit it to search both.
`court`	Filter judgments by court code, for example `KECA`.
`date_from`	Only return judgments on or after this date.
`date_to`	Only return judgments on or before this date.
`limit`	Number of results to return. Maximum: 100.
`offset`	Skip results when paginating.

Read a document

Search results include an Emerald document ID. Use it to fetch metadata, stored legal text or a rendered copy.

GET /v1/documents/{id}Document type, title, citation, court or chapter, date, source URL and hashes.

GET /v1/documents/{id}/search-textPlain text used by Emerald for search and retrieval.

GET /v1/documents/{id}/contentThe stored legal-body HTML.

GET /v1/documents/{id}/content-urlA short-lived signed URL for the stored body artifact.

GET /v1/documents/{id}/readerSanitized body HTML for embedding in your own reading view.

GET /v1/documents/{id}/pdfA branded PDF built from Emerald's stored legal text when supported.

GET /v1/documents/{id}/source-urlA signed URL for the original source file when one is stored.

Resolve a citation

GET /v1/citations/resolve

Use citation resolution when you already know the neutral citation and want the corresponding Emerald record.

curl --get "https://www.emerald.ynai.co.ke/v1/citations/resolve" \
  --data-urlencode "citation=[2025] KEHC 19140 (KLR)" \
  -H "X-API-Key: em_live_..."

New and updated records

GET /v1/updates

Use an ISO timestamp in since when you maintain a local cache or index and want to pull records Emerald has added or refreshed.

curl "https://www.emerald.ynai.co.ke/v1/updates?since=2026-08-18T00:00:00Z" \
  -H "X-API-Key: em_live_..."

Connect Emerald through MCP

Use https://www.emerald.ynai.co.ke/mcp as the remote MCP server URL. Do not add a trailing slash. Emerald uses OAuth for MCP connections, so a compatible client opens the Emerald sign-in flow instead of asking you to paste an API key.

https://www.emerald.ynai.co.ke/mcp

Claude

Add a custom remote connector, paste the MCP URL, leave optional client credentials blank, then sign in to Emerald when Claude opens the authorization page. If Emerald's tool schema has changed since you first connected it, remove and re-add the connector to force fresh discovery.

ChatGPT

For ChatGPT plans or workspaces that support custom MCP apps, create an app using the same endpoint and complete the Emerald OAuth flow. If you previously created an Emerald app against older OAuth metadata, create a fresh draft so the current metadata and tool manifest are discovered.

Emerald intentionally exposes only two read-only MCP tools:

searchFind judgments or statutes from natural-language questions, party names, citations, legislation names, courts and date constraints. Results include stable Emerald document IDs for reading. Legislation lookups accept a title (a year and commas are ignored: Constitution of Kenya, 2010), a chapter (Cap. 160) and a provision (s.29 Law of Succession Act, Order 42 rule 6); a provision query returns the statute with the provision text in results[0].provision. Statutes are returned at their latest consolidation, with version_date. When an instrument or case is not held, quality.note says so: that is a coverage gap, not evidence a citation is wrong.

readRead the selected Emerald document. The full text is returned in one call by default (up to 400k characters, which covers nearly the whole corpus). For legislation, pass a reference such as section 41, s.41(2)(a), article 47, Order 10 rule 11 or First Schedule to retrieve that provision directly. Numbering that restarts in every Order (a bare rule 11) is returned as an ambiguous list of candidates instead of a guess, and outline: true lists a statute's provisions. REST equivalents: GET /v1/documents/{id}/provision?reference=… and /v1/documents/{id}/provisions.

The intended agent workflow is search → choose the authority → read. Citation resolution, case/statute selection and provision lookup are handled inside those two primitives instead of being exposed as separate tools.

Errors and limits

`401`	The credential is missing, expired or invalid.
`404`	The requested record or stored content is not available.
`429`	The account has reached its current usage or rate limit.

REST search returns at most 100 results per request. MCP search deliberately returns a smaller bounded result set so assistants retrieve only what they need. MCP read returns the full document text in one call by default; only unusually long documents (over 400k characters) are paginated, and the response then carries has_more and next_offset so the assistant can continue reading.