> ## 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.

# Quickstart

> Make the first API request, install the CLI, configure MCP, and verify a citation-backed claim.

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.

<Tip>
  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.
</Tip>

Set your environment:

```bash theme={null}
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.

<Note>
  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.
</Note>

## 1. Check Liveness

```bash theme={null}
curl --compressed -sS "$ESHERIA_API_BASE_URL/healthz" | jq
```

Expected envelope:

```json theme={null}
{
  "status": "ok",
  "data": {
    "status": "ok"
  },
  "errors": [],
  "trace_id": "..."
}
```

## 2. List Packs

<CodeGroup>
  ```bash curl theme={null}
  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
  ```

  ```python Python theme={null}
  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())
  ```

  ```bash CLI theme={null}
  pip install esheria
  esheria packs list --jurisdiction UK --readiness verified_published --format json
  ```

  ```json MCP theme={null}
  {
    "tool": "esheria_list_packs",
    "arguments": {
      "jurisdiction": "SG",
      "readiness_label": "verified_published",
      "limit": 100
    }
  }
  ```
</CodeGroup>

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:

```json theme={null}
{
  "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](/guides/pack-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:

```text theme={null}
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:

```bash theme={null}
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:

```toml theme={null}
[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

```bash theme={null}
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.

<CodeGroup>
  ```bash curl theme={null}
  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
  ```

  ```python Python theme={null}
  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())
  ```

  ```bash CLI theme={null}
  esheria claims verify \
    --pack KE-CORPORATE-REGISTRY-BRS \
    --limit 3 \
    "A company shall keep a register of beneficial owners." \
    --format json
  ```

  ```json MCP theme={null}
  {
    "tool": "esheria_verify_claim",
    "arguments": {
      "pack_id": "KE-CORPORATE-REGISTRY-BRS",
      "claim": "A company shall keep a register of beneficial owners.",
      "limit": 3
    }
  }
  ```
</CodeGroup>

Expected response shape:

```json theme={null}
{
  "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

<Columns cols={2}>
  <Card title="Self-Serve Dashboard" icon="user-plus" href="/guides/dashboard-self-serve">
    Create tokens, manage credits, review usage, update billing, and use the playground.
  </Card>

  <Card title="Authentication" icon="key-round" href="/guides/authentication">
    Learn headers, idempotency, trace IDs, and error envelopes.
  </Card>

  <Card title="CLI" icon="terminal" href="/cli">
    Install `esheria`, run smoke checks, and export pack data.
  </Card>

  <Card title="MCP" icon="bot" href="/agent-tools/mcp">
    Connect an agent host to the live MCP endpoint and run the first five tool calls.
  </Card>

  <Card title="Recipes" icon="blocks" href="/recipes/examples">
    Copy complete examples for pack discovery, change monitoring, obligations, evidence, penalties, and claim checks.
  </Card>
</Columns>