Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.esheria.ai/llms.txt

Use this file to discover all available pages before exploring further.

This path gets a new developer from credentials to a citation-backed claim verification.

​
Prerequisites

  • an Esheria API key
  • curl and jq
  • Python 3.11+ for the optional Python example
  • Node.js 20.17+ only if you want to preview these Mintlify docs locally
Set your environment: 
export ESHERIA_API_BASE_URL="https://reg-api.esheria.co.ke"
export ESHERIA_API_KEY="YOUR_ESHERIA_API_KEY"
export ESHERIA_DEFAULT_PACK_ID="KE-DATA-PROTECTION"
If you are testing the current pilot runtime before DNS/TLS cutover, use the base URL your Esheria contact gave you.

​
1. Check Liveness

curl --compressed -sS "$ESHERIA_API_BASE_URL/healthz" | jq
Expected envelope: 
{
  "status": "ok",
  "data": {
    "status": "ok"
  },
  "errors": [],
  "trace_id": "..."
}

​
2. List Packs

curl --compressed -sS \
  "$ESHERIA_API_BASE_URL/api/v1/domain-packs?jurisdiction=KE&limit=10" \
  -H "x-api-key: $ESHERIA_API_KEY" | jq
Expected response shape: 
{
  "status": "ok",
  "data": {
    "packs": [
      {
        "domain_pack_id": "KE-DATA-PROTECTION",
        "readiness_label": "pilot_ready_with_limitations",
        "limitations": []
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0
    }
  },
  "errors": [],
  "trace_id": "..."
}
Common failure modes:
SymptomLikely causeFix
401 unauthorizedMissing or invalid x-api-keyCheck ESHERIA_API_KEY and rotate exposed keys
Request hangsWrong base URL or local alias shadowing esheriaRun type -a esheria and test /healthz with curl
Empty packsFilter is too narrowRemove filters and retry with limit=10

​
3. Verify A Claim

Use claim verification as a guardrail for generated or user-supplied legal text. 
curl --compressed -sS -X POST \
  "$ESHERIA_API_BASE_URL/api/v1/legal-status/verify-claim" \
  -H "content-type: application/json" \
  -H "x-api-key: $ESHERIA_API_KEY" \
  -H "idempotency-key: claim-verify-$(date +%s)" \
  -d '{
    "claim": "The Public Service Commission shall invite applications for the position of Data Commissioner within seven days of being notified of a vacancy.",
    "jurisdiction": "KE",
    "domain": "data_protection",
    "pack_id": "KE-DATA-PROTECTION",
    "limit": 3
  }' | jq
Expected response shape: 
{
  "status": "ok",
  "data": {
    "domain_pack_id": "KE-DATA-PROTECTION",
    "publication_mode": "published",
    "status": "likely_supported",
    "citation_ids": ["..."],
    "quote_spans": [
      {
        "citation_id": "...",
        "verification_status": "compiler_exact_span_candidate"
      }
    ]
  },
  "errors": [],
  "trace_id": "..."
}
Common failure modes:
SymptomLikely causeFix
400 idempotency_key_requiredMissing idempotency-key on a POSTSend a unique idempotency key
unsupported_capabilityPack has no claim evaluator profileUse obligations/applicability or choose a pack with a verifier
not_foundClaim is outside the published factsShow a conservative answer and inspect citations manually

​
Next Steps

Authentication

Learn headers, idempotency, trace IDs, and error envelopes.

CLI

Install esheria, run smoke checks, and export pack data.

MCP

Add Esheria tools to an agent host and run the first five tool calls.

Recipes

Copy complete examples for pack discovery, obligations, evidence, and claim checks.