Quickstart - Esheria

This path gets a new developer from dashboard signup to current pack discovery, change visibility, and citation-backed claim verification.

Prerequisites

a dashboard account at https://dashboard.esheria.ai/ or an existing Esheria API key
curl and jq
Python 3.11+ for the optional Python and CLI examples
Node.js 20.17+ only if you want to preview these Mintlify docs locally

0. Create A Token

Open https://dashboard.esheria.ai/, sign up with verified Google/GitHub OAuth or sign in, choose your Sandbox packs under Settings, then create a data token from API Tokens. Store the token secret immediately; it is shown only once.

The dashboard also shows your current credit balance, usage, billing state, and a playground for testing API calls before you wire them into an app.

Set your environment:

export ESHERIA_API_BASE_URL="https://api.esheria.ai"
export ESHERIA_MCP_URL="https://mcp.esheria.ai/mcp"
export ESHERIA_API_KEY="YOUR_DASHBOARD_CREATED_DATA_TOKEN"
export ESHERIA_PACK_ID="UK-DATA-PROTECTION-PRIVACY"

The selected UK pack is only a starting example. Esheria is catalog-first: list packs first, then explicitly use a verified_published pack ID your workspace should query.

If you already received a workspace token from an Esheria operator or workspace owner, you can use it here instead of creating a new dashboard token.

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?readiness_label=verified_published&limit=100" \
  -H "x-api-key: $ESHERIA_API_KEY" | jq

import os
import httpx

base_url = os.environ["ESHERIA_API_BASE_URL"].rstrip("/")
api_key = os.environ["ESHERIA_API_KEY"]

response = httpx.get(
    f"{base_url}/api/v1/domain-packs",
    params={"jurisdiction": "EU", "readiness_label": "verified_published", "limit": 100},
    headers={"x-api-key": api_key},
    timeout=30,
)
response.raise_for_status()
print(response.json())

pip install esheria
esheria packs list --jurisdiction UK --readiness verified_published --format json

{
  "tool": "esheria_list_packs",
  "arguments": {
    "jurisdiction": "SG",
    "readiness_label": "verified_published",
    "limit": 100
  }
}

Pack discovery returns only the packs actually loaded and published in the environment your key can access; treat the API response, not documentation, as the source of truth for what is available. To try another jurisdiction, change the filter (for example jurisdiction=UK) or omit jurisdiction to discover every current pack your key can access. The repository-side stage-of-record for every pack (published_serving vs earlier pipeline stages) is docs/pack_status_matrix.md in the esheria-regulations repository. Expected response shape:

{
  "status": "ok",
  "data": {
    "packs": [
      {
        "domain_pack_id": "UK-DATA-PROTECTION-PRIVACY",
        "domain_pack_version": "2026-06-01-uk-data-protection-privacy-v0-source-intake",
        "readiness_label": "verified_published",
        "limitations": []
      },
      {
        "domain_pack_id": "EU-NIS2-CYBERSECURITY",
        "domain_pack_version": "recovery-20260709T1640Z",
        "readiness_label": "verified_published",
        "limitations": []
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0
    }
  },
  "errors": [],
  "trace_id": "..."
}

See the complete production catalog. The live esheria_list_packs / GET /api/v1/domain-packs response remains authoritative. Common failure modes:

Symptom	Likely cause	Fix
`401 unauthorized`	Missing or invalid `x-api-key`	Check `ESHERIA_API_KEY` and rotate exposed keys
Request hangs	Wrong base URL or local alias shadowing `esheria`	Run `type -a esheria` and test `/healthz` with `curl`
Empty `packs`	Filter is too narrow	Remove filters and retry with `limit=10`

3. Connect MCP

The live MCP endpoint is already hosted:

https://mcp.esheria.ai/mcp

You do not need local Python, uvx, pipx, or a virtual environment to use the hosted MCP endpoint when your host supports remote MCP. Authentication depends on the host:

Claude.ai, Claude Desktop Directory, and Codex use OAuth through the Esheria dashboard consent page. Do not paste an Esheria data token into the Claude Directory connector.
Cursor, Claude Code, internal agent hosts, and Codex as an alternative may use a dashboard-created data token as a bearer token.

Hosted OAuth exposes 20 curated read-only tools. A normal API data token exposes 29 safe read/read-like tools. Operator data tokens add only the mutations authorized by their write scopes, up to the complete 37-tool catalog. Invalid and management-only credentials cannot list tools. For the Codex desktop app, open Settings -> MCP servers -> Add server, choose Streamable HTTP, enter https://mcp.esheria.ai/mcp, save and restart, then select Authenticate. Approve access in the Esheria dashboard and use /mcp to verify the connection. For Codex CLI OAuth:

codex mcp remove esheria 2>/dev/null || true
codex mcp add esheria --url https://mcp.esheria.ai/mcp
codex mcp login esheria

Approve access in the Esheria dashboard, then restart Codex and call esheria_health, esheria_ready, and esheria_list_packs. The desktop app and CLI can share this MCP configuration when they use the same Codex profile. For the bearer-token alternative, set ESHERIA_API_KEY and use:

[mcp_servers.esheria]
url = "https://mcp.esheria.ai/mcp"
bearer_token_env_var = "ESHERIA_API_KEY"

Do not keep bearer_token_env_var on the same entry when testing OAuth. Other agent hosts should use their Remote MCP or Streamable HTTP MCP configuration screen with:

URL: https://mcp.esheria.ai/mcp
Authorization: OAuth when the host offers Esheria connector authorization, or Bearer YOUR_DASHBOARD_CREATED_DATA_TOKEN for API-key hosts

The MCP examples in the next sections assume the host is connected to the live endpoint.

4. Check Pack Version History

curl --compressed -sS \
  "$ESHERIA_API_BASE_URL/api/v1/domain-packs/$ESHERIA_PACK_ID/versions?limit=10" \
  -H "x-api-key: $ESHERIA_API_KEY" | jq

Use the returned domain_pack_version values to pin reads with version=... or to compare two versions with /diff and /change-events.

5. Verify A Claim When The Pack Enables It

Use claim verification as a guardrail for generated or user-supplied legal text. Claim verification is evaluator-gated, so first inspect the selected pack. The example below uses a pack with an enabled evaluator; generic fact workflows do not depend on claim verification being enabled.

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 '{
    "pack_id": "KE-CORPORATE-REGISTRY-BRS",
    "claim": "A company shall keep a register of beneficial owners.",
    "limit": 3
  }' | jq

import os
import time
import httpx

base_url = os.environ["ESHERIA_API_BASE_URL"].rstrip("/")
api_key = os.environ["ESHERIA_API_KEY"]

payload = {
    "pack_id": "KE-CORPORATE-REGISTRY-BRS",
    "claim": "A company shall keep a register of beneficial owners.",
    "limit": 3,
}

response = httpx.post(
    f"{base_url}/api/v1/legal-status/verify-claim",
    json=payload,
    headers={
        "x-api-key": api_key,
        "idempotency-key": f"claim-verify-{int(time.time())}",
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())

esheria claims verify \
  --pack KE-CORPORATE-REGISTRY-BRS \
  --limit 3 \
  "A company shall keep a register of beneficial owners." \
  --format json

{
  "tool": "esheria_verify_claim",
  "arguments": {
    "pack_id": "KE-CORPORATE-REGISTRY-BRS",
    "claim": "A company shall keep a register of beneficial owners.",
    "limit": 3
  }
}

Expected response shape:

{
  "status": "ok",
  "data": {
    "domain_pack_id": "KE-CORPORATE-REGISTRY-BRS",
    "publication_mode": "published",
    "status": "likely_supported",
    "citation_ids": ["..."],
    "quote_spans": [
      {
        "citation_id": "...",
        "verification_status": "compiler_exact_span_candidate"
      }
    ]
  },
  "errors": [],
  "trace_id": "..."
}

Common failure modes:

Symptom	Likely cause	Fix
`400 idempotency_key_required`	Missing `idempotency-key` on a POST	Send a unique idempotency key
`unsupported_capability`	Pack has no claim evaluator profile	Use obligations/applicability or choose a pack with a verifier
`not_found`	Claim is outside the published facts	Show a conservative answer and inspect citations manually

Next Steps

Self-Serve Dashboard

Create tokens, manage credits, review usage, update billing, and use the playground.

Authentication

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

CLI

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

MCP

Connect an agent host to the live MCP endpoint and run the first five tool calls.

Recipes

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

​Prerequisites

​0. Create A Token

​1. Check Liveness

​2. List Packs

​3. Connect MCP

​4. Check Pack Version History

​5. Verify A Claim When The Pack Enables It

​Next Steps

Self-Serve Dashboard

Authentication

CLI

MCP

Recipes

Prerequisites

0. Create A Token

1. Check Liveness

2. List Packs

3. Connect MCP

4. Check Pack Version History

5. Verify A Claim When The Pack Enables It

Next Steps