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

# Examples

> Copy-paste API, Python, CLI, and MCP examples for the core regulatory workflows.

Create a data token in `https://dashboard.esheria.ai/`, then set shared
environment variables.

```bash theme={null}
export ESHERIA_API_BASE_URL="https://api.esheria.ai"
export ESHERIA_API_KEY="YOUR_DASHBOARD_CREATED_DATA_TOKEN"
export PACK_ID="UK-DATA-PROTECTION-PRIVACY"
```

## Pack Discovery

<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

  response = httpx.get(
      f"{os.environ['ESHERIA_API_BASE_URL'].rstrip('/')}/api/v1/domain-packs",
      params={"jurisdiction": "EU", "readiness_label": "verified_published", "limit": 100},
      headers={"x-api-key": os.environ["ESHERIA_API_KEY"]},
      timeout=30,
  )
  response.raise_for_status()
  print(response.json())
  ```

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

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

Expected: `data.packs[]` with `domain_pack_id`, readiness metadata, limitations, and pagination.

Production discovery in catalog `2026-07-15-v1+sha256:c5732893a6156d077166b60ea5016166ac5b178bb024162320d3a54e0ce745eb` includes 69 pack records across 27 jurisdiction labels, with 60 marked `verified_published` and 9 marked `not_ready`. Use any jurisdiction returned by the API, or omit `jurisdiction` to list all packs available to your key.

Common failures: `unauthorized` for invalid keys, empty result for overly narrow filters.

## Change Monitoring

Use version history, diffs, and change events before updating downstream
operating obligations.

```bash curl theme={null}
curl --compressed -sS \
  "$ESHERIA_API_BASE_URL/api/v1/domain-packs/$PACK_ID/versions?limit=10" \
  -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("/")
pack_id = os.environ["PACK_ID"]

response = httpx.get(
    f"{base_url}/api/v1/domain-packs/{pack_id}/versions",
    params={"limit": 10},
    headers={"x-api-key": os.environ["ESHERIA_API_KEY"]},
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

After choosing two versions:

```bash theme={null}
curl --compressed -sS \
  "$ESHERIA_API_BASE_URL/api/v1/domain-packs/$PACK_ID/diff?from_version=$FROM_VERSION&to_version=$TO_VERSION" \
  -H "x-api-key: $ESHERIA_API_KEY" | jq

curl --compressed -sS \
  "$ESHERIA_API_BASE_URL/api/v1/domain-packs/$PACK_ID/change-events?from_version=$FROM_VERSION&to_version=$TO_VERSION&limit=25" \
  -H "x-api-key: $ESHERIA_API_KEY" | jq
```

Expected: version rows, diff summary, and change events with `change_type`,
`fact_type`, `impacted_fact_ids`, `materiality`, `confidence`, and citation
basis.

Common failures: comparing unavailable versions, or treating canonical change
events as tenant tasks without applicability review.

## Obligation Listing

<CodeGroup>
  ```bash curl theme={null}
  curl --compressed -sS \
    "$ESHERIA_API_BASE_URL/api/v1/domain-packs/$PACK_ID/obligations?duty_holder=data_controller&limit=5" \
    -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("/")
  pack_id = os.environ["PACK_ID"]

  response = httpx.get(
      f"{base_url}/api/v1/domain-packs/{pack_id}/obligations",
      params={"duty_holder": "data_controller", "limit": 5},
      headers={"x-api-key": os.environ["ESHERIA_API_KEY"]},
      timeout=30,
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```bash CLI theme={null}
  esheria obligations list \
    "$PACK_ID" \
    --duty-holder data_controller \
    --limit 5 \
    --format json
  ```

  ```json MCP theme={null}
  {
    "tool": "esheria_list_obligations",
    "arguments": {
      "pack_id": "UK-DATA-PROTECTION-PRIVACY",
      "duty_holder": "data_controller",
      "limit": 5
    }
  }
  ```
</CodeGroup>

Expected: `data.obligations[]` with duty holders, action text, citation IDs, quote spans, and pagination.

Common failures: wrong `pack_id`, unsupported filter value, or a broad query returning more rows than the client expects.

## Applicability Check

<CodeGroup>
  ```bash curl theme={null}
  curl --compressed -sS -X POST \
    "$ESHERIA_API_BASE_URL/api/v1/domain-packs/$PACK_ID/applicability-check" \
    -H "content-type: application/json" \
    -H "x-api-key: $ESHERIA_API_KEY" \
    -H "idempotency-key: applicability-$(date +%s)" \
    -d '{
      "entity_profile": {
        "jurisdictions": ["UK"],
        "entity_types": ["data_controller"],
        "regulated_activities": ["personal_data_processing"],
        "data_categories": ["customer_personal_data"],
        "risk_flags": [],
        "existing_controls": []
      },
      "profile_facts": [],
      "limit": 5
    }' | jq
  ```

  ```python Python theme={null}
  import os
  import time
  import httpx

  base_url = os.environ["ESHERIA_API_BASE_URL"].rstrip("/")
  pack_id = os.environ["PACK_ID"]

  response = httpx.post(
      f"{base_url}/api/v1/domain-packs/{pack_id}/applicability-check",
      json={
          "entity_profile": {
              "jurisdictions": ["UK"],
              "entity_types": ["data_controller"],
              "regulated_activities": ["personal_data_processing"],
              "data_categories": ["customer_personal_data"],
              "risk_flags": [],
              "existing_controls": [],
          },
          "profile_facts": [],
          "limit": 5,
      },
      headers={
          "x-api-key": os.environ["ESHERIA_API_KEY"],
          "idempotency-key": f"applicability-{int(time.time())}",
      },
      timeout=30,
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```bash CLI theme={null}
  esheria applicability check \
    "$PACK_ID" \
    --role data_controller \
    --activity personal_data_processing \
    --sector financial_services \
    --limit 5 \
    --format json
  ```

  ```json MCP theme={null}
  {
    "tool": "esheria_check_applicability",
    "arguments": {
      "pack_id": "UK-DATA-PROTECTION-PRIVACY",
      "entity_roles": ["data_controller"],
      "activities": ["personal_data_processing"],
      "sector_tags": ["financial_services"],
      "limit": 5
    }
  }
  ```
</CodeGroup>

Expected: `data.applicable_obligations[]` with applicability status, score, reasons, and citation IDs.

Common failures: missing idempotency key, missing profile facts, or
over-interpreting `potentially_applies` as a final legal decision.

## Evidence Register

<CodeGroup>
  ```bash curl theme={null}
  curl --compressed -sS \
    "$ESHERIA_API_BASE_URL/api/v1/domain-packs/$PACK_ID/evidence-register" \
    -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("/")
  pack_id = os.environ["PACK_ID"]

  response = httpx.get(
      f"{base_url}/api/v1/domain-packs/{pack_id}/evidence-register",
      headers={"x-api-key": os.environ["ESHERIA_API_KEY"]},
      timeout=30,
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```bash CLI theme={null}
  esheria evidence list "$PACK_ID" --format json
  ```

  ```json MCP theme={null}
  {
    "tool": "esheria_get_evidence_register",
    "arguments": {
      "pack_id": "UK-DATA-PROTECTION-PRIVACY"
    }
  }
  ```
</CodeGroup>

Expected: `data.evidence_register[]` with first-class evidence requirement IDs,
evidence type, requirement level, linked obligations, linked filing rules, and
citations.

Common failures: assuming every obligation has a structured evidence type, or dropping citation IDs when transforming evidence into a checklist.

## Filing Calendar

<CodeGroup>
  ```bash curl theme={null}
  curl --compressed -sS \
    "$ESHERIA_API_BASE_URL/api/v1/domain-packs/$PACK_ID/filing-calendar?limit=10" \
    -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("/")
  pack_id = os.environ["PACK_ID"]

  response = httpx.get(
      f"{base_url}/api/v1/domain-packs/{pack_id}/filing-calendar",
      params={"limit": 10},
      headers={"x-api-key": os.environ["ESHERIA_API_KEY"]},
      timeout=30,
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```bash CLI theme={null}
  esheria calendar list "$PACK_ID" --limit 10 --format json
  ```

  ```json MCP theme={null}
  {
    "tool": "esheria_get_filing_calendar",
    "arguments": {
      "pack_id": "UK-DATA-PROTECTION-PRIVACY",
      "limit": 10
    }
  }
  ```
</CodeGroup>

Expected: `data.calendar_items[]` with filing rule ID, trigger, deadline rule,
recurrence, regulator, linked obligations, forms where available, and citation
metadata.

Common failures: treating relative deadlines as calendar dates without the triggering event.

## Penalty Facts

```bash curl theme={null}
curl --compressed -sS \
  "$ESHERIA_API_BASE_URL/api/v1/domain-packs/$PACK_ID/penalty-facts?limit=25" \
  -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("/")
pack_id = os.environ["PACK_ID"]

response = httpx.get(
    f"{base_url}/api/v1/domain-packs/{pack_id}/penalty-facts",
    params={"limit": 25},
    headers={"x-api-key": os.environ["ESHERIA_API_KEY"]},
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

Expected: `data.penalty_facts[]` with trigger or violation, consequence type,
amount or range, regulator or enforcer, linked facts, and citations.

Common failures: treating penalty facts as customer risk scores. They are
canonical legal consequences.

## Legal Review Audit

```bash curl theme={null}
curl --compressed -sS \
  "$ESHERIA_API_BASE_URL/api/v1/domain-packs/$PACK_ID/legal-review-audit?limit=25" \
  -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("/")
pack_id = os.environ["PACK_ID"]

response = httpx.get(
    f"{base_url}/api/v1/domain-packs/{pack_id}/legal-review-audit",
    params={"limit": 25},
    headers={"x-api-key": os.environ["ESHERIA_API_KEY"]},
    timeout=30,
)
response.raise_for_status()
print(response.json())
```

Expected: `data.legal_review_items[]` with fact classification, promotion
state, review decision, blocking metadata, citations, and source basis.

Common failures: treating legal review audit rows as tenant workbench records.

## Claim Verification

<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

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

  response = httpx.post(
      f"{os.environ['ESHERIA_API_BASE_URL'].rstrip('/')}/api/v1/legal-status/verify-claim",
      json=payload,
      headers={
          "x-api-key": os.environ["ESHERIA_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: `data.status`, `publication_mode`, `citation_ids`, `quote_spans`, and correction labels where applicable.

Common failures: missing idempotency key, claim outside pack scope, or unsupported claim verifier for a pack.

## Relationship Graph

<CodeGroup>
  ```bash curl theme={null}
  curl --compressed -sS -X POST \
    "$ESHERIA_API_BASE_URL/api/v1/regulatory-graph/query" \
    -H "content-type: application/json" \
    -H "x-api-key: $ESHERIA_API_KEY" \
    -H "idempotency-key: graph-query-$(date +%s)" \
    -d '{
      "pack_ids": ["UK-DATA-PROTECTION-PRIVACY", "EU-GDPR-DATA-PROTECTION"],
      "limit": 10
    }' | jq
  ```

  ```python Python theme={null}
  import os
  import time
  import httpx

  response = httpx.post(
      f"{os.environ['ESHERIA_API_BASE_URL'].rstrip('/')}/api/v1/regulatory-graph/query",
      json={"pack_ids": ["UK-DATA-PROTECTION-PRIVACY", "EU-GDPR-DATA-PROTECTION"], "limit": 10},
      headers={
          "x-api-key": os.environ["ESHERIA_API_KEY"],
          "idempotency-key": f"graph-query-{int(time.time())}",
      },
      timeout=30,
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```bash CLI theme={null}
  esheria graph query --pack UK-DATA-PROTECTION-PRIVACY --pack EU-GDPR-DATA-PROTECTION --limit 10 --format json
  ```

  ```json MCP theme={null}
  {
    "tool": "esheria_query_regulatory_graph",
    "arguments": {
      "pack_ids": ["UK-DATA-PROTECTION-PRIVACY", "EU-GDPR-DATA-PROTECTION"],
      "limit": 10
    }
  }
  ```
</CodeGroup>

Expected: relationship facts with source pack, target pack, relationship type, evidence basis, and trace ID.

Common failures: relationship filters that exclude all facts, or treating graph context as a substitute for pack-specific obligations.