Examples - Esheria

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

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

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

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())

esheria packs list --jurisdiction SG --readiness verified_published --format json

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

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.

curl

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

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:

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

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

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())

esheria obligations list \
  "$PACK_ID" \
  --duty-holder data_controller \
  --limit 5 \
  --format json

{
  "tool": "esheria_list_obligations",
  "arguments": {
    "pack_id": "UK-DATA-PROTECTION-PRIVACY",
    "duty_holder": "data_controller",
    "limit": 5
  }
}

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

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

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())

esheria applicability check \
  "$PACK_ID" \
  --role data_controller \
  --activity personal_data_processing \
  --sector financial_services \
  --limit 5 \
  --format json

{
  "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
  }
}

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

curl --compressed -sS \
  "$ESHERIA_API_BASE_URL/api/v1/domain-packs/$PACK_ID/evidence-register" \
  -H "x-api-key: $ESHERIA_API_KEY" | jq

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())

esheria evidence list "$PACK_ID" --format json

{
  "tool": "esheria_get_evidence_register",
  "arguments": {
    "pack_id": "UK-DATA-PROTECTION-PRIVACY"
  }
}

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

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

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())

esheria calendar list "$PACK_ID" --limit 10 --format json

{
  "tool": "esheria_get_filing_calendar",
  "arguments": {
    "pack_id": "UK-DATA-PROTECTION-PRIVACY",
    "limit": 10
  }
}

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

curl

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

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

curl

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

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

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

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())

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: 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

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

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())

esheria graph query --pack UK-DATA-PROTECTION-PRIVACY --pack EU-GDPR-DATA-PROTECTION --limit 10 --format json

{
  "tool": "esheria_query_regulatory_graph",
  "arguments": {
    "pack_ids": ["UK-DATA-PROTECTION-PRIVACY", "EU-GDPR-DATA-PROTECTION"],
    "limit": 10
  }
}

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.

​Pack Discovery

​Change Monitoring

​Obligation Listing

​Applicability Check

​Evidence Register

​Filing Calendar

​Penalty Facts

​Legal Review Audit

​Claim Verification

​Relationship Graph

Pack Discovery

Change Monitoring

Obligation Listing

Applicability Check

Evidence Register

Filing Calendar

Penalty Facts

Legal Review Audit

Claim Verification

Relationship Graph