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://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://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://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://emerald.ynai.co.ke/v1/updates?since=2026-08-18T00:00:00Z" \
  -H "X-API-Key: em_live_..."

Connect Emerald through MCP

Use https://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://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.

readRead the selected Emerald document in bounded chunks. For legislation, pass a reference such as section 41 or article 47 to retrieve that provision directly.

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; read is chunked for the same reason.