# MCP
Source: https://docs.esheria.ai/agent-tools/mcp
Connect Esheria's regulatory tools to Claude, Codex, Cursor, or an internal agent host.
Use Esheria MCP when an agent host needs citation-backed regulatory facts
without direct database, S3, or pipeline access.
Production MCP URL: `https://mcp.esheria.ai/mcp`
## Choose Your Auth Path
Claude or Codex opens Esheria consent. Click **Approve access**. No pasted API key.
Use a dashboard data token as the bearer token.
Fallback for hosts without remote MCP. Runs locally.
| Path | Flow |
| ---------------- | ----------------------------------------------------------------- |
| Claude Directory | Claude -> Esheria consent -> remote MCP |
| Codex OAuth | Codex -> Esheria consent -> local loopback callback -> remote MCP |
| API-key hosts | Host secret -> bearer token -> remote MCP |
| Stdio fallback | Local MCP process -> `https://api.esheria.ai` |
Esheria is catalog-first. Start with `esheria_list_packs`, then pass the
selected `pack_id` to pack-specific tools. MCP does not silently select Kenya
or any other jurisdiction, and multi-pack graph or preview tools require an
explicit `pack_ids` list.
## Host Setup
| Host | Connection | Auth |
| ------------------------------------ | ------------------------------------------------------ | --------------------------------------------- |
| Claude.ai / Claude Desktop Directory | Add `https://mcp.esheria.ai/mcp` in the connector flow | OAuth dashboard consent |
| Codex desktop app | Settings -> MCP servers -> Streamable HTTP | OAuth dashboard consent |
| Codex CLI | Remote MCP URL in `~/.codex/config.toml` | OAuth (recommended) or `bearer_token_env_var` |
| Cursor | Remote MCP or local stdio MCP | Bearer data token |
| Claude Code | Remote MCP if available; stdio fallback otherwise | Bearer data token |
| Internal host | HTTP / Streamable HTTP MCP | Bearer data token |
### Claude.ai / Claude Desktop Directory
Use `https://mcp.esheria.ai/mcp`.
Sign in to the Esheria dashboard and click **Approve access**.
Ask Claude to list Esheria packs, then inspect a pack such as
`UK-DATA-PROTECTION-PRIVACY` or `EU-NIS2-CYBERSECURITY`.
Do not paste an `esh_live_` or `esh_test_` token into a Claude Directory
connector. Directory connections use OAuth.
### Codex Desktop App
Open **Settings**, select **MCP servers**, then choose **Add server**.
Set the name to `Esheria`, choose **Streamable HTTP**, and use
`https://mcp.esheria.ai/mcp` as the server URL.
Save the server, then select **Restart** so the app reloads its MCP
configuration.
Select **Authenticate**, sign in to the Esheria dashboard, and click
**Approve access**. No Esheria API key is required for this OAuth path.
Type `/mcp` in the composer and confirm Esheria is connected, then ask
Codex to call `esheria_list_packs`.
The Codex desktop app, CLI, and IDE extension can share MCP configuration when
they use the same Codex profile. If you already completed
`codex mcp login esheria` in that profile, Esheria may already appear as
authenticated in the app.
### Codex CLI
Configure and authenticate with 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. Codex returns to a strict loopback
callback on `127.0.0.1` with an ephemeral port. Then call `esheria_health`,
`esheria_ready`, and `esheria_list_packs`.
Bearer-token alternative:
```bash theme={null}
export ESHERIA_API_KEY="YOUR_DASHBOARD_CREATED_DATA_TOKEN"
```
```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.
### Generic Remote MCP
Use this shape for Cursor, Claude Code remote MCP, or an internal agent host
that accepts an HTTP MCP URL and bearer token:
```json theme={null}
{
"name": "esheria",
"transport": "http",
"url": "https://mcp.esheria.ai/mcp",
"authorization": "Bearer YOUR_DASHBOARD_CREATED_DATA_TOKEN"
}
```
### Local Stdio Fallback
Use this when a host does not support remote MCP URLs:
```bash theme={null}
uvx --from esheria esheria-mcp serve --stdio
```
Pass these environment variables to the host:
```bash theme={null}
ESHERIA_API_BASE_URL=https://api.esheria.ai
ESHERIA_API_TOKEN=YOUR_DASHBOARD_CREATED_DATA_TOKEN
```
Stdio validates the token before exposing a catalog. Invalid and
management-only tokens cause startup to fail closed.
## Verify The Connection
Use the same first calls in every host:
| Tool | Expected result |
| -------------------------- | --------------------------------------------------------------------- |
| `esheria_health` | MCP process is reachable |
| `esheria_ready` | Runtime dependencies are ready |
| `esheria_list_packs` | Current pack catalog |
| `esheria_get_pack` | Metadata for one `pack_id` |
| `esheria_list_obligations` | Bounded `structuredContent` with published obligations and `trace_id` |
Example obligation lookup:
```json theme={null}
{
"tool": "esheria_list_obligations",
"arguments": {
"pack_id": "UK-DATA-PROTECTION-PRIVACY",
"query": "data subject",
"limit": 3
}
}
```
Choose any `verified_published` pack returned by `esheria_list_packs`; the UK
pack above is an example, not a default.
## Tool Access
The 37 tools are the complete catalog—not 37 obsolete or additional tools. Authentication determines the safe subset shown to each connection.
| Credential | Visible tools | Access |
| ------------------- | ------------: | --------------------------------------------------- |
| Hosted MCP OAuth | 20 | Curated read-only tools. |
| API data token | 29 | All safe read/read-like tools. |
| Operator data token | 29-37 | Adds only mutations authorized by its write scopes. |
Invalid and management-only credentials are rejected before initialization or
tool listing.
### Hosted OAuth: 20 read-only tools
| Area | Tools |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Runtime | `esheria_health`, `esheria_ready` |
| Packs and versions | `esheria_list_packs`, `esheria_get_pack`, `esheria_list_pack_versions`, `esheria_get_pack_diff`, `esheria_list_change_events` |
| Published facts | `esheria_list_obligations`, `esheria_get_filing_calendar`, `esheria_get_evidence_register`, `esheria_get_penalty_facts`, `esheria_get_legal_review_audit` |
| Applicability and claims | `esheria_check_applicability`, `esheria_check_graph_applicability`, `esheria_verify_claim` |
| Graph and export | `esheria_list_relationships`, `esheria_query_regulatory_graph`, `esheria_get_entity_profile`, `esheria_export_pack`, `esheria_get_citation_context` |
### API data tokens: nine additional safe tools
* `esheria_list_source_watches`
* `esheria_get_source_currentness`
* `esheria_list_source_change_events`
* `esheria_list_recompile_candidates`
* `esheria_get_graph_coverage`
* `esheria_list_customer_profiles`
* `esheria_preview_customer_lifecycle`
* `esheria_list_customer_obligation_instances`
* `esheria_list_customer_change_impacts`
Use `esheria_list_customer_profiles` with `customer_profile_id` to inspect one
profile. Add `include_applicability_runs: true` to retrieve its prior run
history through the same safe tool.
### Operator mutations
Every mutation requires both its scope and `"confirm": true`.
| Scope | Tools |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `monitoring:write` | `esheria_create_source_watch`, `esheria_check_source_watches` |
| `graph:write` | `esheria_rebuild_graph_projection` |
| `customer:write` | `esheria_create_customer_profile`, `esheria_run_customer_applicability`, `esheria_update_customer_obligation_instance`, `esheria_recompute_customer_change_impacts`, `esheria_update_customer_change_impact` |
MCP does not expose token, billing, subscription, or workspace administration.
## Results And Large Responses
Successful calls return the same bounded JSON in text content and
`structuredContent`, so hosts that consume either representation receive the
result. Results include `trace_id` and an `mcp` object with:
* `truncated`
* `output_bytes`
* `max_output_bytes`
Structured payloads are bounded to 24 KiB by default. Use pagination or the equivalent
API/CLI command when `truncated` is true. MCP pack export is a bounded
manifest/count/sample view; use `esheria packs export` or the REST export route
for the complete artifact.
## Protocol Compatibility
The hosted service uses the official MCP SDK and negotiates MCP `2025-11-25`.
It supports `ping`, input-schema validation, lifecycle enforcement, MCP tool
errors, bounded active-session counts, idle expiry, and Streamable HTTP
sessions.
Clients must initialize, retain `Mcp-Session-Id`, send
`MCP-Protocol-Version` after initialization, and send
`notifications/initialized`. Invalid JSON-RPC, batches, unsupported versions,
missing sessions, unsafe Origin/Host headers, and malformed tool arguments fail
closed. Streamable HTTP requests use `Content-Type: application/json` and
advertise both `application/json` and `text/event-stream` in `Accept`.
API-token profiles expose three pack resource templates through
`resources/templates/list` and five prompts. `resources/list` is empty because
pack resources require a selected `pack_id`. Hosted OAuth remains tool-only.
## Source-Monitor Guardrails
Hosted source monitoring rejects local files, private/link-local/metadata
destinations, DNS rebinding, HTTPS-to-HTTP downgrade redirects,
caller-selected S3 endpoints, unapproved S3 buckets, non-standard ports,
oversized content, unbounded waits, and oversized check batches.
Offline local-file monitoring is a separate pipeline-only mode.
## Troubleshooting
| Symptom | Meaning |
| ----------------------------------- | --------------------------------------------------------- |
| `401` plus `WWW-Authenticate` | Missing, invalid, expired, or management-only credential. |
| `403 Invalid Origin header` | The browser/host Origin is not allow-listed. |
| `400 Unsupported protocol version` | Upgrade the MCP host or negotiate a supported version. |
| `400 Missing session ID` | Initialize and reuse the returned `Mcp-Session-Id`. |
| Tool result has `isError: true` | Check its validation/API message and `trace_id`. |
| `mcp.truncated: true` | Paginate or use CLI/API for the complete result. |
| Mutation is absent | Mint a data token with the required write scope. |
| Mutation says `confirm` is required | Retry only after review with `"confirm": true`. |
## Agent Guardrails
Ask agents to:
* call Esheria before making regulatory assertions
* preserve citation IDs, readiness labels, limitations, and `trace_id`
* avoid legal-advice framing
* route uncertain or unsupported answers to human review
# Create a data API token
Source: https://docs.esheria.ai/api-reference/api-tokens/create-a-data-api-token
/openapi.json post /api/v1/tokens
# List workspace API tokens
Source: https://docs.esheria.ai/api-reference/api-tokens/list-workspace-api-tokens
/openapi.json get /api/v1/tokens
# Revoke an API token
Source: https://docs.esheria.ai/api-reference/api-tokens/revoke-an-api-token
/openapi.json post /api/v1/tokens/{token_id}/revoke
# Approve Oauth Authorization Request
Source: https://docs.esheria.ai/api-reference/approve-oauth-authorization-request
/openapi.json post /api/v1/admin/oauth/claude/requests/{authorization_request_id}/approve
# Cancel the current workspace subscription
Source: https://docs.esheria.ai/api-reference/billing/cancel-the-current-workspace-subscription
/openapi.json post /api/v1/billing/subscription/cancel
# Create a Stripe Checkout session for credits or subscription
Source: https://docs.esheria.ai/api-reference/billing/create-a-stripe-checkout-session-for-credits-or-subscription
/openapi.json post /api/v1/billing/topups/checkout-session
# Get the current workspace subscription
Source: https://docs.esheria.ai/api-reference/billing/get-the-current-workspace-subscription
/openapi.json get /api/v1/billing/subscription
# Get workspace credit balance
Source: https://docs.esheria.ai/api-reference/billing/get-workspace-credit-balance
/openapi.json get /api/v1/billing/balance
# List available billing plans
Source: https://docs.esheria.ai/api-reference/billing/list-available-billing-plans
/openapi.json get /api/v1/billing/plans
# List metered API usage
Source: https://docs.esheria.ai/api-reference/billing/list-metered-api-usage
/openapi.json get /api/v1/billing/usage
# Create a workspace-scoped customer regulatory profile
Source: https://docs.esheria.ai/api-reference/customer-applicability-api/create-a-workspace-scoped-customer-regulatory-profile
/openapi.json post /api/v1/customer-profiles
# Inspect a workspace-scoped customer regulatory profile
Source: https://docs.esheria.ai/api-reference/customer-applicability-api/inspect-a-workspace-scoped-customer-regulatory-profile
/openapi.json get /api/v1/customer-profiles/{customer_profile_id}
# List persisted customer-specific applicability runs
Source: https://docs.esheria.ai/api-reference/customer-applicability-api/list-persisted-customer-specific-applicability-runs
/openapi.json get /api/v1/customer-profiles/{customer_profile_id}/applicability-runs
# List workspace customer change impacts
Source: https://docs.esheria.ai/api-reference/customer-applicability-api/list-workspace-customer-change-impacts
/openapi.json get /api/v1/customer-change-impacts
# List workspace customer obligation instances that reference published facts
Source: https://docs.esheria.ai/api-reference/customer-applicability-api/list-workspace-customer-obligation-instances-that-reference-published-facts
/openapi.json get /api/v1/customer-obligation-instances
# List workspace-scoped customer regulatory profiles
Source: https://docs.esheria.ai/api-reference/customer-applicability-api/list-workspace-scoped-customer-regulatory-profiles
/openapi.json get /api/v1/customer-profiles
# Preview customer applicability and change impacts without storing customer state
Source: https://docs.esheria.ai/api-reference/customer-applicability-api/preview-customer-applicability-and-change-impacts-without-storing-customer-state
/openapi.json post /api/v1/customer-lifecycle/preview
# Recompute customer impacts from pack change events
Source: https://docs.esheria.ai/api-reference/customer-applicability-api/recompute-customer-impacts-from-pack-change-events
/openapi.json post /api/v1/customer-change-impacts/recompute
# Run and persist customer-specific applicability against locked pack versions
Source: https://docs.esheria.ai/api-reference/customer-applicability-api/run-and-persist-customer-specific-applicability-against-locked-pack-versions
/openapi.json post /api/v1/customer-profiles/{customer_profile_id}/applicability-runs
# Update tenant-owned lifecycle state for a customer change impact
Source: https://docs.esheria.ai/api-reference/customer-applicability-api/update-tenant-owned-lifecycle-state-for-a-customer-change-impact
/openapi.json patch /api/v1/customer-change-impacts/{customer_change_impact_id}
# Update tenant-owned lifecycle state for a customer obligation instance
Source: https://docs.esheria.ai/api-reference/customer-applicability-api/update-tenant-owned-lifecycle-state-for-a-customer-obligation-instance
/openapi.json patch /api/v1/customer-obligation-instances/{customer_obligation_instance_id}
# Deny Oauth Authorization Request
Source: https://docs.esheria.ai/api-reference/deny-oauth-authorization-request
/openapi.json post /api/v1/admin/oauth/claude/requests/{authorization_request_id}/deny
# Get Oauth Authorization Request
Source: https://docs.esheria.ai/api-reference/get-oauth-authorization-request
/openapi.json get /api/v1/admin/oauth/claude/requests/{authorization_request_id}
# Oauth Authorization Server Metadata
Source: https://docs.esheria.ai/api-reference/oauth-authorization-server-metadata
/openapi.json get /.well-known/oauth-authorization-server
# Oauth Authorize
Source: https://docs.esheria.ai/api-reference/oauth-authorize
/openapi.json get /authorize
# Oauth Introspect
Source: https://docs.esheria.ai/api-reference/oauth-introspect
/openapi.json get /api/v1/oauth/introspect
# Oauth Protected Resource Metadata
Source: https://docs.esheria.ai/api-reference/oauth-protected-resource-metadata
/openapi.json get /.well-known/oauth-protected-resource
# Oauth Register
Source: https://docs.esheria.ai/api-reference/oauth-register
/openapi.json post /register
# Oauth Revoke
Source: https://docs.esheria.ai/api-reference/oauth-revoke
/openapi.json post /revoke
# Oauth Token
Source: https://docs.esheria.ai/api-reference/oauth-token
/openapi.json post /token
# Healthz
Source: https://docs.esheria.ai/api-reference/operations/healthz
/openapi.json get /healthz
# Metrics
Source: https://docs.esheria.ai/api-reference/operations/metrics
/openapi.json get /metrics
# Readyz
Source: https://docs.esheria.ai/api-reference/operations/readyz
/openapi.json get /readyz
# Query published regulatory relationship facts across packs
Source: https://docs.esheria.ai/api-reference/regulatory-graph-api/query-published-regulatory-relationship-facts-across-packs
/openapi.json post /api/v1/regulatory-graph/query
# Rebuild published regulatory graph projections from serving facts
Source: https://docs.esheria.ai/api-reference/regulatory-graph-api/rebuild-published-regulatory-graph-projections-from-serving-facts
/openapi.json post /api/v1/regulatory-graph/projections/rebuild
# Return graph node coverage for published regulatory facts
Source: https://docs.esheria.ai/api-reference/regulatory-graph-api/return-graph-node-coverage-for-published-regulatory-facts
/openapi.json get /api/v1/regulatory-graph/coverage
# Return pack applicability results with published relationship context
Source: https://docs.esheria.ai/api-reference/regulatory-graph-api/return-pack-applicability-results-with-published-relationship-context
/openapi.json post /api/v1/regulatory-graph/applicability-check
# Summarize entity profile context from published pack and relationship facts
Source: https://docs.esheria.ai/api-reference/regulatory-graph-api/summarize-entity-profile-context-from-published-pack-and-relationship-facts
/openapi.json get /api/v1/regulatory-graph/entity-profile
# Create or update a regulatory source watch
Source: https://docs.esheria.ai/api-reference/regulatory-monitoring-api/create-or-update-a-regulatory-source-watch
/openapi.json post /api/v1/regulatory-monitoring/source-watches
# List configured regulatory source watches
Source: https://docs.esheria.ai/api-reference/regulatory-monitoring-api/list-configured-regulatory-source-watches
/openapi.json get /api/v1/regulatory-monitoring/source-watches
# List recorded regulatory source-change events
Source: https://docs.esheria.ai/api-reference/regulatory-monitoring-api/list-recorded-regulatory-source-change-events
/openapi.json get /api/v1/regulatory-monitoring/source-change-events
# List source currentness from the latest monitoring snapshots
Source: https://docs.esheria.ai/api-reference/regulatory-monitoring-api/list-source-currentness-from-the-latest-monitoring-snapshots
/openapi.json get /api/v1/regulatory-monitoring/source-currentness
# List source or fact changes queued for regulatory pack recompile
Source: https://docs.esheria.ai/api-reference/regulatory-monitoring-api/list-source-or-fact-changes-queued-for-regulatory-pack-recompile
/openapi.json get /api/v1/regulatory-monitoring/recompile-candidates
# Run source snapshot and change detection for configured watches
Source: https://docs.esheria.ai/api-reference/regulatory-monitoring-api/run-source-snapshot-and-change-detection-for-configured-watches
/openapi.json post /api/v1/regulatory-monitoring/source-watches/check
# Check which obligations potentially apply to an entity profile
Source: https://docs.esheria.ai/api-reference/regulatory-pack-api/check-which-obligations-potentially-apply-to-an-entity-profile
/openapi.json post /api/v1/domain-packs/{pack_id}/applicability-check
# Diff canonical facts between two regulatory domain pack versions
Source: https://docs.esheria.ai/api-reference/regulatory-pack-api/diff-canonical-facts-between-two-regulatory-domain-pack-versions
/openapi.json get /api/v1/domain-packs/{pack_id}/diff
# Export the published regulatory pack
Source: https://docs.esheria.ai/api-reference/regulatory-pack-api/export-the-published-regulatory-pack
/openapi.json get /api/v1/domain-packs/{pack_id}/export
# Inspect a regulatory domain pack summary
Source: https://docs.esheria.ai/api-reference/regulatory-pack-api/inspect-a-regulatory-domain-pack-summary
/openapi.json get /api/v1/domain-packs/{pack_id}
# List current regulatory domain packs
Source: https://docs.esheria.ai/api-reference/regulatory-pack-api/list-current-regulatory-domain-packs
/openapi.json get /api/v1/domain-packs
# List historical versions for a regulatory domain pack
Source: https://docs.esheria.ai/api-reference/regulatory-pack-api/list-historical-versions-for-a-regulatory-domain-pack
/openapi.json get /api/v1/domain-packs/{pack_id}/versions
# List published obligations for a regulatory domain pack
Source: https://docs.esheria.ai/api-reference/regulatory-pack-api/list-published-obligations-for-a-regulatory-domain-pack
/openapi.json get /api/v1/domain-packs/{pack_id}/obligations
# List stored or generated legal change events for a regulatory domain pack
Source: https://docs.esheria.ai/api-reference/regulatory-pack-api/list-stored-or-generated-legal-change-events-for-a-regulatory-domain-pack
/openapi.json get /api/v1/domain-packs/{pack_id}/change-events
# Return canonical legal review and publication audit metadata
Source: https://docs.esheria.ai/api-reference/regulatory-pack-api/return-canonical-legal-review-and-publication-audit-metadata
/openapi.json get /api/v1/domain-packs/{pack_id}/legal-review-audit
# Return evidence requirements grouped by evidence type
Source: https://docs.esheria.ai/api-reference/regulatory-pack-api/return-evidence-requirements-grouped-by-evidence-type
/openapi.json get /api/v1/domain-packs/{pack_id}/evidence-register
# Return published relationship facts involving a regulatory domain pack
Source: https://docs.esheria.ai/api-reference/regulatory-pack-api/return-published-relationship-facts-involving-a-regulatory-domain-pack
/openapi.json get /api/v1/domain-packs/{pack_id}/relationships
# Return regulatory filing and deadline calendar items
Source: https://docs.esheria.ai/api-reference/regulatory-pack-api/return-regulatory-filing-and-deadline-calendar-items
/openapi.json get /api/v1/domain-packs/{pack_id}/filing-calendar
# Return source-traced penalty and consequence facts
Source: https://docs.esheria.ai/api-reference/regulatory-pack-api/return-source-traced-penalty-and-consequence-facts
/openapi.json get /api/v1/domain-packs/{pack_id}/penalty-facts
# Verify a legal claim against a selected regulatory pack
Source: https://docs.esheria.ai/api-reference/regulatory-pack-api/verify-a-legal-claim-against-a-selected-regulatory-pack
/openapi.json post /api/v1/legal-status/verify-claim
# Get the current workspace
Source: https://docs.esheria.ai/api-reference/workspace/get-the-current-workspace
/openapi.json get /api/v1/workspace
# Update the current workspace settings
Source: https://docs.esheria.ai/api-reference/workspace/update-the-current-workspace-settings
/openapi.json patch /api/v1/workspace
# Changelog
Source: https://docs.esheria.ai/changelog/index
Release notes for Esheria developer surfaces.
## 2026-07-14
### Codex OAuth Login
* Added strict RFC 8252-style loopback callback support for
`codex mcp login esheria`, including dynamic local ports and exact
`/callback/` validation.
* Kept hosted HTTPS callbacks on the explicit allow-list and rejected lookalike
hosts, missing ports, wrong paths, fragments, userinfo, and non-loopback HTTP
redirects.
* Generalized dashboard consent and connector-token naming for Claude, Codex,
and future hosted MCP OAuth clients while retaining legacy connector tokens.
* Added Codex desktop-app setup through **Settings -> MCP servers**, including
Streamable HTTP configuration, OAuth authentication, shared-profile behavior,
and `/mcp` verification.
### Billing And Credits Production Hardening / CLI 1.2.0
* Replaced caller-selected Checkout credits and quantity with server-owned
plan/top-up SKUs, persisted orders, exact public prices, and Stripe line-item
verification.
* Added Sandbox, Developer, Team, Business, and Enterprise plan policy with
pack limits, feature gates, authenticated requests/minute, expiring Sandbox
grants, and 12-month paid top-ups.
* Scoped idempotency to the authenticated workspace/token, authorized every
pack in multi-pack payloads, and made unknown protected route pricing fail
closed.
* Moved runtime charging to immutable `2026-07-14-v2` database rules and exposed
the current catalog through billing plans.
* Added retryable Stripe events, recurring invoice grants, asynchronous payment
outcomes, refunds/disputes, credit-debt restoration, and stale-reservation
reconciliation.
* Disabled unverified public email/password provisioning; verified Google and
GitHub OAuth remain the production self-service identity paths.
* Updated the Dashboard and CLI to choose workspace packs and Checkout SKUs;
`esheria billing checkout --sku-id ...` replaces caller-defined top-ups.
## 2026-07-13
### MCP 1.1.0 Production Hardening
* Replaced the handwritten transport with the official MCP SDK and current
Streamable HTTP lifecycle, protocol negotiation, `ping`, schema validation,
resource templates, and MCP-native tool errors.
* Added exact 20/29/37 scope-aware catalogs. Invalid and management-only
credentials are rejected before catalog disclosure; mutations require their
write scope and explicit confirmation.
* Blocked path traversal, DNS-rebinding/private source-monitor destinations,
downgrade redirects, local files, caller-controlled S3 settings, oversized
content, unbounded waits, and oversized check batches.
* Added backward-compatible bounded JSON text plus structured outputs, pooled
API clients, pre-auth/per-token rate and concurrency controls, session caps,
structured logs, bounded-cardinality Prometheus metrics, HSTS, and versioned
systemd/nginx hardening.
* Completed customer-profile detail/run-history reads without deleting or
increasing the 37-tool catalog.
### Multi-Jurisdiction Hardening
* Removed Kenya and `data_protection` request fallbacks from API, CLI, Python
client, and MCP claim verification. `pack_id` is now explicit and pack
jurisdiction/domain metadata is inferred from the selected pack.
* Required explicit pack selection for graph queries, graph applicability,
entity-profile summaries, and stateless customer lifecycle previews.
* Refreshed the production catalog to 69 current pack records across 27
jurisdiction labels: 60 `verified_published` and 9 metadata-only `not_ready`.
* Diversified API, CLI, MCP, recipe, monitoring, billing, and applicability
examples across UK, EU, US, Singapore, Australia, and global packs.
* Added UK-pack API, CLI, and MCP release validation.
### CLI 1.0.0 Production Release
* Promoted the package to `Development Status :: 5 - Production/Stable` and
declared Apache-2.0 for the distributed CLI, Python client, and MCP code.
* Added dedicated `monitoring:write`, `graph:write`, and `customer:write`
scopes. Read-only tokens can no longer authorize hosted-state mutations.
* Restricted data-token creation to the documented read/operator scopes while
keeping dashboard and OAuth connector tokens read-only by default.
* Added `esheria --version`, global output flags, richer command help, strict
configuration/input validation, and broader NDJSON row streaming.
* Added explicit `--yes` confirmation for graph projection rebuilds, source
checks, and subscription cancellation.
* Added workspace and subscription commands, source-watch list/create
commands, customer-profile inspection, and applicability-run history.
* Fixed graph applicability payload compatibility and removed silently ignored
calendar, evidence, monitoring, and relationship filters.
* Prevented API-key forwarding through HTTP redirects and added wheel install
smoke tests for Python 3.11, 3.12, and 3.13.
* Added CI wheel/entry-point smoke coverage on Linux, Windows, and macOS.
* Hardened PyPI publication with tag/version matching, focused release tests,
`twine check`, installed-wheel entry-point smoke, and `pip check`.
## 2026-06-28
### Regulatory Intelligence Workflows
* Added source monitoring endpoints, CLI commands, and MCP tools for source
watches, source currentness, source-change events, and binding recompile
candidates.
* Added published-only graph projection rebuild and graph coverage workflows.
* Added workspace-scoped customer profiles, applicability runs, customer
obligation instances, and customer change-impact workflows.
* Updated OpenAPI-backed docs to include monitoring, graph, customer
applicability, obligation instance, and impact surfaces.
## 2026-06-25
### Hosted MCP Transport
* Deployed the hosted MCP HTTP endpoint at `https://mcp.esheria.ai/mcp`.
* Published DNS, nginx TLS, and a managed `esheria-mcp.service` process for the hosted endpoint.
* Updated Codex setup to use a remote MCP URL with bearer-token auth instead of a local `uvx` stdio command.
* Updated the public MCP guide and quickstart so users connect by URL first; local `esheria-mcp serve --stdio` is now documented only as a fallback for hosts that do not support remote MCP URLs.
## 2026-06-03
### Production Multipack Catalog
* Updated public pack documentation to show the current production Postgres
serving catalog: five Kenya packs and six UK packs.
* Added current versions and published API counts for obligations, filing
calendar items, evidence rows, and applicability rows.
* Clarified that generic pack workflows are available across the loaded packs,
while claim verification remains limited to packs with enabled evaluator
profiles.
* Disclosed that UK pack versions still carry source-intake names until the
later publication-normalization phase, even though the production API is
serving their published workflow surfaces.
### Full Regulatory Fact Surfaces
* Added API Reference coverage for pack versions, pack diffs, change events,
penalty facts, and legal review audit metadata.
* Added guides for change monitoring and first-class filing/evidence/penalty
surfaces.
* Updated examples to use the current Kenya Data Protection pack version and a
customer-operating claim instead of older institutional-duty examples.
* Clarified that the API provides read-only canonical legal intelligence;
downstream products own applicability review, task ownership, uploaded
evidence, remediation, comments, and reports.
## 2026-06-01
### CLI And MCP Package
* Published the `esheria` Python package with `esheria` and `esheria-mcp` console commands.
* Added repo-local wrappers at `bin/esheria` and `bin/esheria-mcp`.
* Added host examples for Claude Desktop, Cursor, Codex MCP, and internal agent hosts.
* Added first five MCP tool calls for liveness, readiness, pack discovery, pack inspection, and obligation retrieval.
### Developer Docs
* Added Mintlify documentation structure under `mintlify/`.
* Added `docs.json` navigation for Quickstart, API Reference, CLI, MCP, Recipes, Errors, and Changelog.
* Copied and enriched `api/openapi.v1.json` as `mintlify/openapi.json` with server URLs and `x-api-key` security metadata.
* Added GitHub Actions docs validation with OpenAPI freshness checks.
## Contract Notes
* Public responses keep the deterministic envelope: `status`, `data`, `errors`, and `trace_id`.
* Production workflows serve published regulatory facts.
* Claim verification requires a pack-level claim evaluation profile.
# CLI
Source: https://docs.esheria.ai/cli/index
Install and use the esheria command-line interface for API smoke checks and regulatory pack workflows.
The `esheria` CLI is a thin client over the public Regulatory Pack API. It does not read Postgres, S3, pipeline artifacts, or internal evidence folders directly.
The CLI is catalog-first and multi-jurisdictional. It never selects Kenya or
any other jurisdiction implicitly: discover packs, inspect readiness, and pass
the chosen pack ID to pack-specific commands.
Version `1.2.2` is production/stable. The distributed CLI, Python client, and
MCP software are Apache-2.0 licensed. Hosted services, regulatory data,
outputs, and Esheria trademarks remain subject to the Esheria Terms of Service,
Privacy Policy, and customer agreements.
Preserve readiness labels, limitations, citations, and trace IDs in
downstream workflows. Esheria output is regulatory intelligence, not legal
advice or a substitute for qualified counsel.
## Install
```bash pip theme={null}
pip install esheria
```
```bash pipx theme={null}
pipx install esheria
```
```bash uvx theme={null}
uvx --from esheria esheria health --format json
```
## Configure
Create a self-serve data token in the dashboard first:
1. Open `https://dashboard.esheria.ai/`.
2. Sign up or sign in.
3. Create a token from **API Tokens**.
4. Store the one-time token secret as `ESHERIA_API_KEY`.
```bash macOS/Linux theme={null}
export ESHERIA_API_BASE_URL="https://api.esheria.ai"
export ESHERIA_API_KEY="YOUR_DASHBOARD_CREATED_DATA_TOKEN"
export ESHERIA_TIMEOUT_SECONDS="30"
export ESHERIA_RETRY_COUNT="2"
```
```powershell Windows PowerShell theme={null}
$env:ESHERIA_API_BASE_URL = "https://api.esheria.ai"
$env:ESHERIA_API_KEY = "YOUR_DASHBOARD_CREATED_DATA_TOKEN"
$env:ESHERIA_TIMEOUT_SECONDS = "30"
$env:ESHERIA_RETRY_COUNT = "2"
```
## Smoke Test
```bash theme={null}
esheria --version
esheria health --format json
esheria ready --format json
esheria packs list --format json
export ESHERIA_PACK_ID="UK-DATA-PROTECTION-PRIVACY"
esheria packs inspect "$ESHERIA_PACK_ID" --format json
esheria obligations list "$ESHERIA_PACK_ID" --limit 3 --format json
```
Use `esheria packs list --jurisdiction EU`, `--jurisdiction SG`, or another
catalog value to select a different jurisdiction. See the
[complete production catalog](/guides/pack-catalog).
## Core Commands
| Workflow | Command |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| Health | `esheria health` |
| Readiness | `esheria ready` |
| Diagnostics | `esheria doctor --pack "$ESHERIA_PACK_ID"` |
| Pack discovery | `esheria packs list` |
| Pack inspection | `esheria packs inspect "$ESHERIA_PACK_ID"` |
| Pack export | `esheria packs export "$ESHERIA_PACK_ID" --out pack.json` |
| Obligations | `esheria obligations list "$ESHERIA_PACK_ID" --limit 25` |
| Applicability | `esheria applicability check "$ESHERIA_PACK_ID" --role data_controller --activity personal_data_processing` |
| Claim verification | `esheria claims verify --pack "$ESHERIA_PACK_ID" "..."` |
| Filing calendar | `esheria calendar list "$ESHERIA_PACK_ID"` |
| Evidence register | `esheria evidence list "$ESHERIA_PACK_ID"` |
| Citation context | `esheria citations get "$ESHERIA_PACK_ID" --citation-id CITATION_ID` |
| Relationships | `esheria relationships list "$ESHERIA_PACK_ID"` |
| Graph query | `esheria graph query --pack "$ESHERIA_PACK_ID"` |
| Graph projection | `esheria graph rebuild-projection --reason scheduled_rebuild --yes` |
| Graph coverage | `esheria graph coverage --domain-pack-id "$ESHERIA_PACK_ID"` |
| Source watches | `esheria monitoring watches --domain-pack-id "$ESHERIA_PACK_ID"` |
| Source currentness | `esheria monitoring currentness --domain-pack-id "$ESHERIA_PACK_ID"` |
| Source check | `esheria monitoring check --domain-pack-id "$ESHERIA_PACK_ID" --yes` |
| Recompile candidates | `esheria monitoring recompile-candidates --domain-pack-id "$ESHERIA_PACK_ID"` |
| Customer lifecycle preview | `esheria customers preview --pack "$ESHERIA_PACK_ID" --role data_controller` |
| Customer profiles | `esheria customers profiles` |
| Customer profile inspection | `esheria customers inspect-profile CUSTOMER_PROFILE_ID` |
| Customer applicability | `esheria customers run-applicability CUSTOMER_PROFILE_ID --pack "$ESHERIA_PACK_ID"` |
| Customer applicability history | `esheria customers applicability-runs CUSTOMER_PROFILE_ID` |
| Customer obligations | `esheria customers obligations --customer-profile-id CUSTOMER_PROFILE_ID` |
| Customer impacts | `esheria customers impacts --customer-profile-id CUSTOMER_PROFILE_ID` |
| Token list | `esheria tokens list` |
| Token creation | `esheria tokens create --name "Production data token" --pack "$ESHERIA_PACK_ID"` |
| Token revocation | `esheria tokens revoke TOKEN_ID` |
| Credit balance | `esheria billing balance` |
| Usage ledger | `esheria billing usage --limit 25` |
| Billing catalog | `esheria billing plans` |
| Checkout | `esheria billing checkout --sku-id developer-topup-1000` |
| Subscription state | `esheria billing subscription` |
| Workspace settings | `esheria workspace show` |
The dashboard remains the recommended UI for signup, one-time token reveal,
usage review, billing checkout, subscription state, and workspace settings.
Dashboard-created data tokens and OAuth connector tokens are read-only.
Workspace, token, billing, and subscription CLI commands require a management
token. Do not put management tokens in browser code, shared shell profiles,
CI logs, or agent-host configuration.
Commands that create/check source watches, rebuild graph projections, or update
persisted customer lifecycle state change hosted data. They require
`monitoring:write`, `graph:write`, or `customer:write` respectively;
`regulatory:read` alone is rejected. Create a least-privilege operator token
with a management token:
```bash theme={null}
esheria tokens create --name "Monitoring operator" \
--scope regulatory:read --scope monitoring:write \
--pack UK-DATA-PROTECTION-PRIVACY
```
## Additional Fact Surfaces
The CLI also wraps canonical fact surfaces for versions, diffs, change events,
penalties, and legal review audit. The equivalent API calls are:
```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
curl --compressed -sS \
"$ESHERIA_API_BASE_URL/api/v1/domain-packs/$ESHERIA_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/$ESHERIA_PACK_ID/change-events?from_version=$FROM_VERSION&to_version=$TO_VERSION&limit=25" \
-H "x-api-key: $ESHERIA_API_KEY" | jq
curl --compressed -sS \
"$ESHERIA_API_BASE_URL/api/v1/domain-packs/$ESHERIA_PACK_ID/penalty-facts?limit=25" \
-H "x-api-key: $ESHERIA_API_KEY" | jq
curl --compressed -sS \
"$ESHERIA_API_BASE_URL/api/v1/domain-packs/$ESHERIA_PACK_ID/legal-review-audit?limit=25" \
-H "x-api-key: $ESHERIA_API_KEY" | jq
```
## Output Formats
Output flags can appear before the command or on the leaf command:
```bash theme={null}
esheria --format json packs list
esheria packs list --format json
```
Supported output controls are:
```text theme={null}
--format table
--format json
--format yaml
--format ndjson
--raw
--envelope
```
Use `--envelope` when you need the full API envelope. Use `--raw` when you want the returned payload without table formatting.
## Examples
### List Packs
```bash theme={null}
esheria packs list --jurisdiction EU --readiness verified_published --format json
```
### Check Applicability
```bash theme={null}
esheria applicability check \
UK-DATA-PROTECTION-PRIVACY \
--role data_controller \
--activity personal_data_processing \
--limit 5 \
--format json
```
### Verify A Claim
```bash theme={null}
esheria claims verify \
--pack UK-DATA-PROTECTION-PRIVACY \
"A controller must respond to data subject rights requests." \
--format json
```
The last command may return `unsupported_capability` when the selected pack has
no enabled claim evaluator. That does not affect obligations, applicability,
calendar, evidence, penalties, relationships, or export for the pack.
## Troubleshooting
| Symptom | Likely cause | Fix |
| -------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------ |
| `esheria` opens SSH or another program | Shell alias shadows the installed command | Run `type -a esheria`, then remove or rename the alias |
| `Invalid API key` | Missing or wrong `ESHERIA_API_KEY` | Re-export the key and retry `esheria packs list` |
| `credits_exhausted` | Workspace credit balance is empty | Run `esheria billing balance` and create a top-up checkout session |
| `billing_unavailable` | Billing ledger is not reachable | Retry after the API operator restores ledger availability |
| Request hangs | Wrong base URL or network issue | Test `curl "$ESHERIA_API_BASE_URL/healthz"` |
| `unsupported_capability` | The pack does not support that workflow | Use generic pack endpoints or choose another pack |
Repository-local wrappers remain available as `bin/esheria` and `bin/esheria-mcp` for contributors working from a checkout.
# API Keys
Source: https://docs.esheria.ai/guides/api-keys
Store, rotate, and test Esheria API keys without leaking credentials.
API keys identify the client calling the Regulatory Pack API. Treat keys as production credentials.
Create API tokens from the Esheria API Dashboard at
`https://dashboard.esheria.ai/`. The dashboard creates workspace-scoped data
tokens for production services, local development, CLI use, and MCP hosts.
Store tokens in your shell for local testing or in your service secret manager
for production use.
Dashboard-created and OAuth connector tokens are read-only
(`regulatory:read`). A workspace owner can use a management token to create a
least-privilege operator data token with `monitoring:write`, `graph:write`, or
`customer:write` when an integration must change hosted state.
Existing customers may also receive a workspace token from an Esheria
operator or workspace owner. Dashboard-created data tokens are the recommended
self-serve path for new integrations.
## Create A Token In The Dashboard
1. Open `https://dashboard.esheria.ai/`.
2. Sign up or sign in.
3. Open **API Tokens**.
4. Create a data token with a clear name such as `Production backend` or `Local development`.
5. Store the returned token secret immediately. It is shown once and cannot be recovered later.
Use separate data tokens for each service, environment, and major integration.
That makes revocation and usage debugging easier.
For an operator token, repeat the CLI `--scope` option. Unknown scopes and
management scopes are rejected for data tokens:
```bash theme={null}
esheria tokens create --name "Monitoring operator" \
--scope regulatory:read --scope monitoring:write \
--pack UK-DATA-USE-AND-ACCESS
```
## Local Setup
```bash theme={null}
export ESHERIA_API_BASE_URL="https://api.esheria.ai"
export ESHERIA_API_KEY="YOUR_DASHBOARD_CREATED_DATA_TOKEN"
export ESHERIA_DEFAULT_PACK_ID="EU-NIS2-CYBERSECURITY"
```
`ESHERIA_DEFAULT_PACK_ID` is an optional client preference chosen by you; it is
not a server-side jurisdiction default. Pack-specific commands still accept an
explicit pack ID.
For long-running services, store keys in the host secret manager and inject them as environment variables at runtime.
## Test A Key
```bash theme={null}
curl --compressed -sS \
"$ESHERIA_API_BASE_URL/api/v1/domain-packs?limit=1" \
-H "x-api-key: $ESHERIA_API_KEY" | jq
```
A valid key returns `status: ok`. An invalid key returns the normal error envelope with `unauthorized`.
## CLI Configuration
The CLI reads the same environment variables.
```bash theme={null}
esheria doctor --pack "$ESHERIA_DEFAULT_PACK_ID" --format json
```
The CLI redacts credential status in diagnostics. It should report whether a key is `set` or `missing`, never the key value.
## Rotation Checklist
1. Create a new data token in the dashboard.
2. Deploy the new key to services and MCP hosts.
3. Run `esheria packs list --format json`.
4. Revoke the old key from **API Tokens**.
5. Remove exposed key material from shell history, logs, and screenshots.
## Common Failure Modes
| Symptom | Cause | Resolution |
| ------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------- |
| Works in one terminal but not another | Environment variable was exported only in one shell | Re-export the key or use your shell profile carefully |
| CLI calls SSH or another command | A local alias shadows `esheria` | Run `type -a esheria` and remove the alias |
| Browser playground fails on pilot URL | HTTPS docs page calling an HTTP pilot server can be blocked | Use the production HTTPS base URL for browser-based playgrounds |
# Authentication
Source: https://docs.esheria.ai/guides/authentication
Use API keys, idempotency keys, and trace IDs safely across Esheria API workflows.
Protected endpoints require an API key in the `x-api-key` header.
```http theme={null}
x-api-key: YOUR_ESHERIA_API_KEY
```
Create self-serve API tokens from `https://dashboard.esheria.ai/`. Dashboard
signup requires a verified Google or GitHub email, resolves your workspace,
and lets you choose plan-allowed packs before creating/revoking data tokens.
Public email/password signup is not enabled in production.
`GET /healthz` and `GET /readyz` are operational endpoints. Regulatory pack endpoints under `/api/v1` require authentication.
In billing-enabled workspaces, API keys are workspace tokens. Management tokens
can create and revoke data tokens and read billing state. Dashboard-created and
OAuth connector data tokens use `regulatory:read` by default. Hosted-state
mutations require an explicitly created operator data token with
`monitoring:write`, `graph:write`, or `customer:write`; read scope alone is
rejected. Data-token requests are charged against workspace credits.
The dashboard uses server-side management credentials for token, billing,
workspace, checkout, and playground operations. Do not put management tokens or
dashboard server credentials in browser applications.
## Mutating Requests
All mutating requests require an idempotency key. This applies to `POST` workflows such as claim verification, applicability checks, and graph applicability checks.
```http theme={null}
idempotency-key: unique-request-intent
```
Use a stable key for a single request intent. Reusing the same key with the same
payload allows replay protection; reusing it with a different payload returns a
conflict. Authentication and current scope/pack/feature authorization run
before replay, and stored responses are isolated by workspace and token.
## Trace IDs
Every response includes a `trace_id`.
```json theme={null}
{
"status": "ok",
"data": {},
"errors": [],
"trace_id": "bdf7825f-..."
}
```
Store `trace_id` with user-visible decisions, support tickets, and agent outputs. It is the fastest way to connect a downstream answer to the API request that produced it.
## Example
```bash theme={null}
curl --compressed -sS -X POST \
"$ESHERIA_API_BASE_URL/api/v1/domain-packs/UK-DATA-PROTECTION-PRIVACY/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"]
},
"profile_facts": [],
"limit": 5
}' | jq
```
## Failure Modes
| Code | Meaning | Action |
| -------------------------- | ----------------------------------------------------------------- | ------------------------------------------------- |
| `unauthorized` | The API key is missing or invalid | Check the header and rotate any exposed key |
| `forbidden` | The token lacks the required read/write scope or pack entitlement | Use a correctly scoped least-privilege token |
| `credits_exhausted` | The workspace has no available credits | Add credits or create a Stripe Checkout top-up |
| `billing_unavailable` | The billing ledger could not be checked | Retry after operators restore ledger availability |
| `idempotency_key_required` | A mutating request was sent without `idempotency-key` | Generate a unique key for the request intent |
| `idempotency_key_conflict` | The same key was reused with a different payload | Use a new key or replay the original payload |
| `validation_error` | Request fields did not match the API schema | Compare the payload with the API Reference |
Do not put API keys in docs, repositories, browser screenshots, support
tickets, agent transcripts, or browser bundles. Use the dashboard token list
and `trace_id` values for debugging instead of raw token secrets.
# Billing and Credits
Source: https://docs.esheria.ai/guides/billing-and-credits
Production plans, workspace credits, server-owned Checkout SKUs, metering, and payment safety.
Esheria uses workspace credits across API, CLI, and MCP traffic. Credits are a
workload/value unit—not LLM tokens—and the same plan, pack, feature, rate, and
balance controls apply on every surface.
## Production Plans
| Plan | Price | Included credits | Pack access | Requests/minute |
| --------------------- | ------------: | ----------------------: | -------------------------------------------------------------- | --------------: |
| Sandbox | \$0 | 500 once, valid 14 days | Choose 2 published packs | 30 |
| Developer | \$99/month | 10,000/month | Choose 5 published packs | 60 |
| Team | \$449/month | 50,000/month | Choose 20 published packs; monitoring reads and graph coverage | 180 |
| Business | \$1,499/month | 250,000/month | All published standard packs | 600 |
| Enterprise / Embedded | \$3,500/month | 500,000/month | Standard plus contracted custom/premium packs | 1,200 |
Enterprise plans include contracted support, throughput, SLA, and data-rights terms. Taxes, premium/custom content, and negotiated services may be additional.
Existing balances are grandfathered. Esheria does not remove or
retroactively debit credits when publishing a new catalog or pricing rule.
## Top-up SKUs
| SKU | Available to | Price | Credits | Expiry |
| ---------------------- | ---------------------------------------------- | ----: | ------: | -------- |
| `business-topup-50000` | Business, Enterprise / Embedded, Grandfathered | \$500 | 50,000 | 365 days |
| `developer-topup-1000` | Developer | \$15 | 1,000 | 365 days |
| `team-topup-10000` | Team | \$120 | 10,000 | 365 days |
Use `esheria billing plans` or `GET /api/v1/billing/plans` as the source of
truth. The response includes exact prices, available SKUs, workspace plan and
pack policy, and the active pricing-rule catalog.
## Checkout
Checkout accepts one server-owned SKU. You cannot submit the price, credits,
quantity, grant expiry, plan, or entitlement.
```bash theme={null}
esheria billing plans
esheria billing checkout --sku-id developer-topup-1000
```
```bash theme={null}
curl --compressed -sS -X POST \
"https://api.esheria.ai/api/v1/billing/topups/checkout-session" \
-H "content-type: application/json" \
-H "x-api-key: $ESHERIA_API_KEY" \
-H "idempotency-key: $(uuidgen)" \
-d '{"sku_id":"developer-topup-1000"}' | jq
```
The API creates an internal order before redirecting to Stripe. Payment
webhooks validate the Stripe Price and line item against that order. Credit
grants never come from browser, CLI, or Checkout metadata values.
## Metering
Production pricing version: `2026-07-14-v2`.
| Operation | Credits | Availability |
| ----------------------------- | --------------------: | -------------------------------- |
| Claim verification | 15 | Entitled plans |
| Customer impact read | 2 + 1/100 impacts | Business+ |
| Customer impact recompute | 50 + 1/100 impacts | Business+ and `customer:write` |
| Customer profile read | 2 + 1/100 results | Business+ |
| Customer profile write | 10 | Business+ and `customer:write` |
| Customer state patch | 5 | Business+ and `customer:write` |
| Execute source check | 50 + 5/source | Business+ and `monitoring:write` |
| Fact listings | 2 + 1/100 results | Entitled plans |
| Full pack export | 250 + 10/MiB | Business+ |
| Graph coverage | 2 | Team+ |
| Graph projection rebuild | 100 + 1/1,000 facts | Business+ and `graph:write` |
| Graph query/entity profile | 8 + 1/100 results | Entitled plans |
| Monitoring read/currentness | 2 + 1/100 results | Team+ |
| Pack discovery/detail | 1 | Entitled plans |
| Persisted applicability | 25 + 1/50 obligations | Business+ and `customer:write` |
| Source-watch write | 10 | Business+ and `monitoring:write` |
| Stateless applicability | 10 + 1/50 results | Entitled plans |
| Versions, diff, change events | 2 + 1/100 results | Entitled plans |
The API reserves credits before work starts, charges successful work once, and
releases failed requests. Usage rows retain every referenced pack, the pricing
rule/version, request and response units, final charge, and `trace_id`.
An in-process reconciler releases stale reservations and safely reclaims due
or interrupted Stripe events.
```bash theme={null}
esheria billing balance
esheria billing usage --limit 25 --format json
```
## Entitlements And Replays
* Workspace settings choose the packs available under the plan.
* A token inherits those packs by default or narrows to a subset.
* Every pack in a multi-pack graph/customer request is checked.
* Full export and hosted operator workflows also require plan features.
* Authentication and current authorization run before an idempotent response
can be replayed. Replay records are isolated by workspace and token.
## Renewals, Refunds, And Disputes
Recurring invoice credits are derived from Stripe Price-to-plan mappings and
granted once per paid invoice, including concurrent duplicate deliveries.
Failed and stale-processing Stripe events remain retryable. Self-service
Checkout refuses a second current subscription for the same workspace.
Refunds reverse the proportional credits tied to the refunded payment.
Disputes temporarily reverse the affected value. If those credits were already
used, Esheria records credit debt instead of directly consuming an unrelated
grant. A won dispute clears that debt first and restores any remaining credits.
## Errors
| HTTP | Code | Meaning |
| ---: | ----------------------------------------------------- | ------------------------------------------------------------------- |
| 401 | `unauthorized` | Token is missing, invalid, revoked, or expired |
| 402 | `credits_exhausted` | No usable credits remain |
| 403 | `forbidden` / `feature_not_entitled` | Scope, pack, or plan feature is missing |
| 409 | `idempotency_key_conflict` | Key was reused with a different payload in the same principal scope |
| 429 | `rate_limited` | Pre-auth abuse limit or plan request limit was exceeded |
| 503 | `billing_unavailable` / `billing_pricing_unavailable` | Ledger or pricing catalog failed closed |
MCP intentionally does not expose billing mutation, Checkout, or token
management tools. Configure billing and tokens in the Dashboard or CLI first.
# Change Monitoring
Source: https://docs.esheria.ai/guides/change-monitoring
Use pack versions, diffs, and change events to answer what changed since the last sync.
Compliance teams need to know what changed before anything becomes tenant work.
The Regulatory Pack API exposes source-traced change intelligence at the
canonical pack layer:
* pack version history
* deterministic fact diffs between versions
* change events with impacted fact IDs, materiality, confidence, and citation basis
* source-watch currentness, source-change events, and binding recompile candidates
Pack diff endpoints do not create tenant tasks. Customer applicability endpoints
can persist workspace-scoped obligation instances and change impacts after a
profile-specific review.
## List Versions
Select a pack explicitly. This example uses the UK Data Use and Access pack:
```bash theme={null}
export ESHERIA_PACK_ID="UK-DATA-USE-AND-ACCESS"
```
```bash curl 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
```
Expected response shape:
```json theme={null}
{
"status": "ok",
"data": {
"versions": [
{
"domain_pack_version": "recovery-20260709T1640Z",
"is_current": true
}
],
"pagination": {
"total": 1,
"limit": 10,
"offset": 0
}
},
"trace_id": "..."
}
```
## Diff Versions
Set two versions from the version list:
```bash theme={null}
export FROM_VERSION="VERSION_FROM_THE_API"
export TO_VERSION="NEWER_VERSION_FROM_THE_API"
```
Then call the diff endpoint:
```bash curl theme={null}
curl --compressed -sS \
"$ESHERIA_API_BASE_URL/api/v1/domain-packs/$ESHERIA_PACK_ID/diff?from_version=$FROM_VERSION&to_version=$TO_VERSION" \
-H "x-api-key: $ESHERIA_API_KEY" | jq
```
Diff rows can include:
* `change_type`
* `fact_type`
* `fact_id`
* `impacted_fact_ids`
* `source_citation_basis`
* `materiality`
* `confidence`
* before/after hashes
## List Change Events
```bash curl theme={null}
curl --compressed -sS \
"$ESHERIA_API_BASE_URL/api/v1/domain-packs/$ESHERIA_PACK_ID/change-events?from_version=$FROM_VERSION&to_version=$TO_VERSION&limit=25" \
-H "x-api-key: $ESHERIA_API_KEY" | jq
```
Use change events to power a downstream change monitor:
| Change signal | Downstream action |
| -------------------------- | ---------------------------------------------------- |
| New obligation | Review applicability, then instantiate if accepted |
| Changed obligation | Update the existing operating obligation if impacted |
| Removed or superseded fact | Mark the old operating record for review |
| Filing changed | Update due-date logic or filing workflow |
| Evidence changed | Request new evidence or update control mapping |
| Citation changed | Re-verify source trace and legal review posture |
CLI and MCP wrappers are available for monitoring currentness, source checks,
change events, graph coverage, customer applicability runs, obligation
instances, and customer change impacts.
## Monitor Source Currentness
Create source watches for validated public HTTP(S) or deployment-approved S3
sources, then run a bounded source check. These state-changing calls require `monitoring:write`; pack
version, diff, event, and currentness reads use `regulatory:read`:
```bash curl theme={null}
curl --compressed -sS -X POST \
"$ESHERIA_API_BASE_URL/api/v1/regulatory-monitoring/source-watches" \
-H "content-type: application/json" \
-H "x-api-key: $ESHERIA_API_KEY" \
-H "idempotency-key: $(uuidgen)" \
-d '{
"domain_pack_id": "UK-DATA-USE-AND-ACCESS",
"source_asset_id": "uk_duaa_2025",
"source_uri": "https://www.legislation.gov.uk/ukpga/2025/18/contents",
"source_kind": "binding",
"authority_type": "binding"
}' | jq
curl --compressed -sS -X POST \
"$ESHERIA_API_BASE_URL/api/v1/regulatory-monitoring/source-watches/check" \
-H "content-type: application/json" \
-H "x-api-key: $ESHERIA_API_KEY" \
-H "idempotency-key: $(uuidgen)" \
-d '{"domain_pack_id":"UK-DATA-USE-AND-ACCESS"}' | jq
```
Only binding source changes create recompile candidates. Guidance and watchlist
changes are currentness signals and do not become binding obligations without
binding source support.
```bash CLI theme={null}
esheria monitoring currentness --domain-pack-id UK-DATA-USE-AND-ACCESS --format json
esheria monitoring check --domain-pack-id UK-DATA-USE-AND-ACCESS --format json
esheria monitoring changes --domain-pack-id UK-DATA-USE-AND-ACCESS --format json
esheria monitoring recompile-candidates --domain-pack-id UK-DATA-USE-AND-ACCESS --format json
```
# Citations And Evidence
Source: https://docs.esheria.ai/guides/citations-and-evidence
Keep source IDs, quote spans, evidence requirements, and trace IDs attached to every regulatory answer.
Esheria is citation-first. Applications should preserve citation IDs and quote spans from API responses instead of paraphrasing regulatory facts without source context.
## Citation Fields
Common citation-bearing fields include:
* `citation_ids`
* `quote_spans`
* `authority_ids`
* `provision_ids`
* `obligation_ids`
* `source_asset_id`
* `trace_id`
## Evidence Register
The evidence register exposes first-class `evidence_requirement` facts when
available. These are source-backed legal requirements or recommended proof
artifacts, not tenant file uploads.
```bash curl theme={null}
curl --compressed -sS \
"$ESHERIA_API_BASE_URL/api/v1/domain-packs/UK-DATA-PROTECTION-PRIVACY/evidence-register" \
-H "x-api-key: $ESHERIA_API_KEY" | jq
```
```bash CLI theme={null}
esheria evidence list UK-DATA-PROTECTION-PRIVACY --format json
```
```json MCP theme={null}
{
"tool": "esheria_get_evidence_register",
"arguments": {
"pack_id": "UK-DATA-PROTECTION-PRIVACY"
}
}
```
Expected shape:
```json theme={null}
{
"status": "ok",
"data": {
"evidence_register": [
{
"evidence_requirement_id": "...",
"evidence_type": "policy_document",
"requirement_level": "required",
"linked_obligation_ids": ["..."],
"linked_filing_rule_ids": [],
"obligations": [
{
"semantic_obligation_id": "...",
"citation_ids": ["..."]
}
]
}
]
},
"trace_id": "..."
}
```
## Filing Calendar
Filing calendar returns first-class filing rules when the pack has them, with
trigger, deadline rule, recurrence, regulator, forms, evidence/proof expected,
linked obligations, and citations.
```bash theme={null}
esheria calendar list UK-DATA-PROTECTION-PRIVACY --limit 10 --format json
```
## Penalties And Consequences
Penalty facts are exposed separately from operating obligations so clients can
triage consequence and risk without confusing penalties with tasks.
```bash theme={null}
curl --compressed -sS \
"$ESHERIA_API_BASE_URL/api/v1/domain-packs/UK-DATA-PROTECTION-PRIVACY/penalty-facts?limit=25" \
-H "x-api-key: $ESHERIA_API_KEY" | jq
```
Penalty rows include trigger or violation, consequence type, amount or range
when source-stated, regulator or enforcer, linked obligations/provisions, and
citations.
## Legal Review Audit
Use legal review audit to inspect canonical publication and classification
metadata:
```bash theme={null}
curl --compressed -sS \
"$ESHERIA_API_BASE_URL/api/v1/domain-packs/UK-DATA-PROTECTION-PRIVACY/legal-review-audit?limit=25" \
-H "x-api-key: $ESHERIA_API_KEY" | jq
```
This endpoint returns fact classification, actionability, promotion state,
review decision, blocking reasons, primitive summary, and citations. It is not
a tenant workbench endpoint.
## Citation Context
The CLI and MCP expose citation context by fetching the published pack export and filtering the pack citations client-side.
```bash theme={null}
esheria citations get UK-DATA-PROTECTION-PRIVACY --citation-id CITATION_ID --format json
```
```json theme={null}
{
"tool": "esheria_get_citation_context",
"arguments": {
"pack_id": "UK-DATA-PROTECTION-PRIVACY",
"citation_id": "CITATION_ID"
}
}
```
A direct citation lookup endpoint is a future API improvement. Today the CLI and MCP preserve the same published citation data returned by the pack export.
# Claim Verification
Source: https://docs.esheria.ai/guides/claim-verification
Verify generated or user-supplied regulatory claims against published facts and citation spans.
Claim verification is a guardrail workflow. Use it when an application, assistant, or review process has drafted a legal/regulatory claim and needs to check whether the published pack supports it.
It is not the first step for most business workflows. Start with packs, obligations, applicability, evidence, and calendars; use claim verification to keep generated text grounded.
`pack_id` is required. Jurisdiction and legal domain are inferred from the
selected pack when omitted; the API never falls back to Kenya or another
jurisdiction. Claim verification remains evaluator-gated.
## Request
```bash 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
```
## Response
Successful responses include status, publication mode, authority IDs, provision IDs, obligation IDs, citation IDs, quote spans, and any correction labels.
```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": "...",
"line_start": 1,
"line_end": 1,
"verification_status": "compiler_exact_span_candidate"
}
],
"issue_labels": ["generic_claim_profile_retrieval"]
},
"errors": [],
"trace_id": "..."
}
```
## Correction Example
If a generated answer changes a deadline or statutory detail, the verifier can return `supported_with_corrections` with issue labels such as `deadline_mismatch`.
```bash theme={null}
esheria claims verify \
--pack KE-CORPORATE-REGISTRY-BRS \
"A company may omit its register of beneficial owners." \
--format json
```
## When Verification Is Unsupported
Some packs may not have a promoted `claim_evaluation_profile`. In that case, claim verification returns `unsupported_capability`. The pack can still support obligation, applicability, evidence, filing-calendar, export, and graph workflows.
## Failure Modes
| Result | Meaning | Product behavior |
| ---------------------------- | ------------------------------------------------------ | -------------------------------------------------------- |
| `likely_supported` | Published facts support the claim | Show the answer with citations and trace ID |
| `supported_with_corrections` | Nearby source-backed fact supports a corrected version | Show correction context, not the original claim as final |
| `unsupported_scope` | Claim is outside supported scope | Ask for a narrower claim or route to review |
| `not_found` | No supporting published fact found | Do not present the claim as source-backed |
| `unsupported_capability` | Pack lacks a claim verifier | Use generic pack workflows instead |
# Self-Serve Dashboard
Source: https://docs.esheria.ai/guides/dashboard-self-serve
Sign up, create API tokens, monitor usage, manage credits, and test Esheria API calls from dashboard.esheria.ai.
Use the Esheria API Dashboard when you want to start without operator help.
The dashboard is available at `https://dashboard.esheria.ai/` and is the
recommended path for account setup, token management, usage review, billing,
and first-request testing.
The dashboard manages access to the Regulatory Pack API. API responses remain
source-backed regulatory workflow data, not legal advice.
## What You Can Do
Sign up with a verified Google or GitHub identity. Public email/password
signup is disabled until production email verification and recovery exist.
Create data tokens for services, integrations, local development, CLI, and
MCP hosts.
List active tokens, copy token prefixes for debugging, and revoke tokens
that should no longer work.
Review remaining credits, recent usage, endpoint families, status codes,
charged credits, and trace IDs.
Start Stripe Checkout for top-ups or subscriptions and review the current
subscription state.
Test pack discovery, claim verification, obligations, applicability,
evidence, filings, penalties, graph queries, and exports from the browser.
## First Dashboard Flow
Go to `https://dashboard.esheria.ai/` and choose **Sign up** with Google or
GitHub. Esheria provisions free Sandbox credits only for verified provider
email addresses.
After sign-in, the dashboard resolves your workspace and shows your current
credit balance, token state, usage, and available API workflows.
Open **Settings**, choose up to two Sandbox packs, then open **API Tokens**,
create a data token, and store the returned token
immediately. The token secret is shown once and cannot be retrieved later.
Store the token in your shell, CI secret store, or server secret manager as
`ESHERIA_API_KEY`.
Use the dashboard playground, `curl`, or the `esheria` CLI to list packs and
confirm the token works.
```bash theme={null}
export ESHERIA_API_BASE_URL="https://api.esheria.ai"
export ESHERIA_API_KEY="YOUR_DASHBOARD_CREATED_DATA_TOKEN"
curl --compressed -sS \
"$ESHERIA_API_BASE_URL/api/v1/domain-packs?limit=10" \
-H "x-api-key: $ESHERIA_API_KEY" | jq
```
## Token Types
Dashboard users normally create **data tokens**. Data tokens call entitled
Regulatory Pack API routes and spend workspace credits when billing is enabled.
Management tokens are used by the dashboard server and trusted automation for
workspace, token, billing, and checkout administration. Do not put management
tokens in browser code, public repositories, notebooks, support tickets, or
client-side applications.
| Token task | Where to do it |
| ------------------------------ | ----------------------------------------------------------------- |
| Create a data token | Dashboard **API Tokens** page |
| List active and revoked tokens | Dashboard **API Tokens** page or `esheria tokens list` |
| Revoke a token | Dashboard **API Tokens** page or `esheria tokens revoke TOKEN_ID` |
| Copy a new token secret | Only on the one-time creation screen |
| Recover an old token secret | Not supported; create a replacement token |
## Billing And Credits
Credits belong to the workspace, not to individual tokens. Creating more tokens
does not create more free credits.
The dashboard billing pages show:
* current credit balance
* free-credit and paid-credit grants
* recent usage and charged credits
* available top-up or subscription plans
* checkout success and cancel states
* current subscription state and cancellation controls when available
Protected API requests are metered by endpoint family. Health checks, readiness
checks, token management, billing reads, and checkout-session creation are not
billable.
New verified workspaces receive 500 credits valid for 14 days and may select
two published packs. Paid plans expand included credits, pack limits, features,
and authenticated requests per minute. Billing cards and Checkout use exact
server-returned SKUs; hidden browser fields never determine a price or grant.
If credits are exhausted, billable API calls return HTTP `402` with
`credits_exhausted`. Add credits or update the workspace plan before retrying
production traffic.
## Usage And Activity
Use **Usage** and **Activity Logs** to debug integration behavior without
exposing secrets. Rows include fields such as endpoint family, method, path,
pack ID, token label or prefix, status code, charged credits, pricing rule
version, and `trace_id`.
Keep the `trace_id` with support tickets, application logs, and user-visible
decisions. It is the fastest way to connect a downstream answer to the API
request that produced it.
## Workspace Settings
Use **Workspace Settings** for customer-visible account details such as display
name, billing contact email, and plan-allowed pack selection. Subscription
management lives under **Billing**.
Team invitations and enterprise SSO are deployment-specific. If your team needs
an organization rollout, contact Esheria from the dashboard sign-in page.
## CLI Equivalents
The dashboard is the easiest self-serve entry point, but the CLI exposes the
same token and billing primitives for automation:
```bash theme={null}
pip install esheria
esheria tokens list --format json
esheria tokens create --name "Production data token"
esheria tokens revoke "$TOKEN_ID"
esheria billing balance
esheria billing usage --limit 25 --format json
esheria billing plans
esheria billing checkout --sku-id developer-topup-1000
```
MCP does not expose token or billing mutation tools. Use the dashboard or CLI
for token and billing management before configuring `esheria-mcp`.
## Safety Checklist
* Create separate data tokens for development, staging, production, and each
major integration.
* Store token secrets in a server secret manager or local environment variable.
* Revoke tokens immediately when they are exposed or no longer needed.
* Do not place API tokens in browser bundles, screenshots, documentation,
issue trackers, logs, or agent transcripts.
* Use dashboard usage rows and `trace_id` values for debugging instead of raw
token secrets.
# Filing, Evidence, And Penalties
Source: https://docs.esheria.ai/guides/filing-evidence-and-penalties
Use first-class filing rules, evidence requirements, penalty facts, and review audit metadata.
The current Regulatory Pack API separates source material from tenant-owned
work. Filing rules, evidence requirements, and penalties are canonical
source-traced facts. They help downstream products decide what to do, what to
prove, and how to triage consequences, but they are not customer task records by
themselves.
## Filing Rules
```bash curl theme={null}
curl --compressed -sS \
"$ESHERIA_API_BASE_URL/api/v1/domain-packs/UK-DATA-PROTECTION-PRIVACY/filing-calendar?limit=25" \
-H "x-api-key: $ESHERIA_API_KEY" | jq
```
The response prefers first-class `filing_rule` facts when available and falls
back to legacy obligation deadline fields for older packs. Filing rule rows can
include:
* `filing_rule_id`
* `filing_name`
* `trigger`
* `deadline_rule`
* `recurrence`
* `regulator`
* `duty_holders`
* `submission_channel`
* `evidence_or_proof_expected`
* `linked_obligation_ids`
* `forms`
* `citation_ids`
Use `version=` to read historical canonical filing rules
when that version is loaded.
## Evidence Requirements
```bash curl theme={null}
curl --compressed -sS \
"$ESHERIA_API_BASE_URL/api/v1/domain-packs/UK-DATA-PROTECTION-PRIVACY/evidence-register" \
-H "x-api-key: $ESHERIA_API_KEY" | jq
```
The response prefers first-class `evidence_requirement` facts when available.
Evidence rows can include:
* `evidence_requirement_id`
* `evidence_type`
* `description`
* `requirement_level`
* `required`
* `retention_period`
* `linked_obligation_ids`
* `linked_filing_rule_ids`
* `forms`
* `citation_ids`
* `verification_metadata`
This is the legal basis for evidence. Uploaded files, attestations, approvals,
and evidence review status belong in the downstream operating workbench.
## Penalty Facts
```bash curl theme={null}
curl --compressed -sS \
"$ESHERIA_API_BASE_URL/api/v1/domain-packs/UK-DATA-PROTECTION-PRIVACY/penalty-facts?limit=25" \
-H "x-api-key: $ESHERIA_API_KEY" | jq
```
Penalty rows are source-backed consequence facts, not customer risk scores. They
can include:
* `penalty_fact_id`
* `trigger_or_violation`
* `consequence_type`
* `amount_or_range`
* `regulator_or_enforcer`
* `linked_obligation_ids`
* `linked_provision_ids`
* `citation_ids`
* `materiality`
* `confidence`
Supported filters include `version`, `regulator_or_enforcer`,
`consequence_type`, `linked_obligation_id`, `linked_provision_id`, `q`, `limit`,
and `offset`.
## Legal Review Audit
```bash curl theme={null}
curl --compressed -sS \
"$ESHERIA_API_BASE_URL/api/v1/domain-packs/UK-DATA-PROTECTION-PRIVACY/legal-review-audit?limit=25" \
-H "x-api-key: $ESHERIA_API_KEY" | jq
```
Legal review audit rows explain canonical classification and publication
decisions. They can include:
* `fact_class`
* `duty_holder_type`
* `audience_type`
* `operability_class`
* `customer_actionability`
* `legal_effect`
* `recommended_use`
* `promotion_state`
* `promotion_tier`
* `review.review_decision`
* blocking reasons
* primitive summary
* citations and quote spans
This endpoint is an audit surface for canonical legal intelligence. It does
not expose tenant owners, operating statuses, uploaded evidence, comments, or
remediation records.
# Obligations
Source: https://docs.esheria.ai/guides/obligations
List and filter published obligations for a regulatory pack.
Obligation workflows return published customer-operating duties with citation
metadata and classification fields. Use them to build applicability review
queues, compliance registers, workflow task lists, review checklists, and agent
context.
The endpoint does not turn every canonical legal fact into a customer task.
Regulator powers, regulator duties, definitions, procedural provisions,
penalties, filing rules, and evidence requirements are available through the
appropriate canonical surfaces.
## List Obligations
```bash curl theme={null}
curl --compressed -sS \
"$ESHERIA_API_BASE_URL/api/v1/domain-packs/UK-DATA-PROTECTION-PRIVACY/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("/")
response = httpx.get(
f"{base_url}/api/v1/domain-packs/UK-DATA-PROTECTION-PRIVACY/obligations",
params={"duty_holder": "data_controller", "limit": 5},
headers={"x-api-key": os.environ["ESHERIA_API_KEY"]},
)
response.raise_for_status()
print(response.json())
```
```bash CLI theme={null}
esheria obligations list \
UK-DATA-PROTECTION-PRIVACY \
--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
}
}
```
## Filters
Common filters:
* `version`
* `duty_holder`
* `workflow_target`
* `instrument_id`
* `evidence_type`
* `fact_class`
* `customer_actionability`
* `q`
* `limit`
* `offset`
## Expected Shape
```json theme={null}
{
"status": "ok",
"data": {
"domain_pack": {
"domain_pack_id": "UK-DATA-PROTECTION-PRIVACY",
"publication_mode": "published",
"index_row_count": 11
},
"obligations": [
{
"semantic_obligation_id": "...",
"duty_holders": ["data_controller"],
"legal_action": "...",
"fact_class": "customer_operating_obligation",
"customer_actionability": "actionable_if_applicable",
"citation_ids": ["..."],
"quote_spans": []
}
],
"pagination": {
"total": 42,
"limit": 5,
"offset": 0
}
},
"trace_id": "..."
}
```
## Applicability Check
Use applicability when you need to match obligations against an entity profile.
The API returns a legal-intelligence recommendation; the downstream product
decides whether to accept, exclude, request more facts, or instantiate an
operating obligation.
Structured profile-fact payload:
```bash theme={null}
curl --compressed -sS -X POST \
"$ESHERIA_API_BASE_URL/api/v1/domain-packs/UK-DATA-PROTECTION-PRIVACY/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
```
Compatibility CLI payload:
```bash theme={null}
esheria applicability check \
UK-DATA-PROTECTION-PRIVACY \
--role data_controller \
--activity personal_data_processing \
--sector financial_services \
--limit 5 \
--format json
```
The response preserves `applicability.status=potentially_applies` for
compatibility and adds `result_status`, `reason`, `confidence`,
`matched_profile_facts`, `missing_profile_facts`, `source_rule_ids`, and
`recommended_next_step`.
# Production Pack Catalog
Source: https://docs.esheria.ai/guides/pack-catalog
Complete current API catalog across jurisdictions, legal domains, readiness states, and published fact counts.
This sanitized release was generated from the production catalog on July 15, 2026.
Catalog version: `2026-07-15-v1+sha256:c5732893a6156d077166b60ea5016166ac5b178bb024162320d3a54e0ce745eb`.
The production serving catalog contains **69 packs across 27 jurisdiction labels**. Of these, **60 are `verified_published`** and expose published facts; **9 are `not_ready`** metadata records with no published legal-status facts.
Always call `esheria packs list --format json` or `GET /api/v1/domain-packs` before pinning a pack. The authenticated API response is authoritative for current entitlements and runtime availability.
## Jurisdiction Summary
| Jurisdiction | Total | Published | Metadata only |
| ------------- | ----: | --------: | ------------: |
| `AR` | 1 | 0 | 1 |
| `AU` | 2 | 2 | 0 |
| `BH` | 1 | 1 | 0 |
| `BR` | 2 | 0 | 2 |
| `CA` | 1 | 1 | 0 |
| `CA-QC` | 2 | 2 | 0 |
| `CH` | 1 | 1 | 0 |
| `CL` | 1 | 0 | 1 |
| `CO` | 1 | 1 | 0 |
| `EU` | 14 | 13 | 1 |
| `Global` | 2 | 2 | 0 |
| `HK` | 2 | 2 | 0 |
| `ID` | 1 | 0 | 1 |
| `IN` | 1 | 1 | 0 |
| `KE` | 5 | 5 | 0 |
| `MX` | 2 | 1 | 1 |
| `QA` | 1 | 1 | 0 |
| `SG` | 3 | 3 | 0 |
| `TH` | 1 | 0 | 1 |
| `TR` | 1 | 1 | 0 |
| `UAE/Dubai` | 1 | 1 | 0 |
| `UK` | 12 | 11 | 1 |
| `UN / Global` | 1 | 1 | 0 |
| `US` | 7 | 7 | 0 |
| `US-CA` | 1 | 1 | 0 |
| `US-CO` | 1 | 1 | 0 |
| `ZA` | 1 | 1 | 0 |
## Complete Catalog
`verified_published` means the pack currently exposes published facts. `not_ready` rows remain discoverable as metadata but must not be used as production legal-intelligence sources.
| Jurisdiction | Pack ID | Legal domain | Readiness | Published facts |
| ------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------- | -------------------- | --------------: |
| `AR` | `AR-DATA-PROTECTION-REFORM` | data\_protection\_privacy | `not_ready` | 0 |
| `AU` | `AU-AML-CTF-REFORMS` | financial\_crime\_aml\_cft\_sanctions | `verified_published` | 145 |
| `AU` | `AU-PRIVACY-APRA-CPS-230` | data\_protection\_privacy / operational\_resilience / regulated\_financial\_services | `verified_published` | 1 |
| `BH` | `BH-PDPL` | data\_protection\_privacy | `verified_published` | 46 |
| `BR` | `BR-LGPD-DATA-PROTECTION` | data\_protection\_privacy | `not_ready` | 0 |
| `BR` | `BR-NFE-TAX-REFORM` | tax\_finance | `not_ready` | 0 |
| `CA` | `CA-PRIVACY-PIPEDA-REFORM-WATCH` | data\_protection\_privacy | `verified_published` | 2 |
| `CA-QC` | `CA-QC-PRIVACY-LAW-25` | data\_protection\_privacy | `verified_published` | 5 |
| `CH` | `CH-FADP` | data\_protection\_privacy | `verified_published` | 69 |
| `CL` | `CL-PERSONAL-DATA-PROTECTION` | data\_protection\_privacy | `not_ready` | 0 |
| `CO` | `CO-HABEAS-DATA` | data\_protection\_privacy | `verified_published` | 13 |
| `EU` | `EU-ACCESSIBILITY-ACT` | consumer\_protection | `verified_published` | 13 |
| `EU` | `EU-AML-SINGLE-RULEBOOK-AMLA` | financial\_crime\_aml\_cft\_sanctions | `verified_published` | 68 |
| `EU` | `EU-CBAM` | tax\_finance | `verified_published` | 53 |
| `EU` | `EU-CSRD-ESRS` | sustainability\_reporting | `verified_published` | 52 |
| `EU` | `EU-CYBER-RESILIENCE-ACT` | technology\_governance | `verified_published` | 17 |
| `EU` | `EU-DATA-ACT` | technology\_governance | `verified_published` | 28 |
| `EU` | `EU-DIGITAL-OPERATIONAL-RESILIENCE-ACT` | operational\_resilience / regulated\_financial\_services / technology\_governance | `not_ready` | 0 |
| `EU` | `EU-DMA-GATEKEEPERS` | digital\_platforms | `verified_published` | 8 |
| `EU` | `EU-EHDS` | health\_data | `verified_published` | 25 |
| `EU` | `EU-EUDR` | supply\_chain\_due\_diligence | `verified_published` | 19 |
| `EU` | `EU-GDPR-DATA-PROTECTION` | data\_protection\_privacy | `verified_published` | 6 |
| `EU` | `EU-NIS2-CYBERSECURITY` | cybersecurity\_governance | `verified_published` | 8 |
| `EU` | `EU-SANCTIONS-DUE-DILIGENCE` | financial\_crime\_aml\_cft\_sanctions | `verified_published` | 218 |
| `EU` | `EU-VIDA-EINVOICING` | tax\_finance | `verified_published` | 214 |
| `Global` | `FATF-TRAVEL-RULE-R16` | financial\_crime\_aml\_cft\_sanctions | `verified_published` | 20 |
| `HK` | `HK-SFC-HKMA-VIRTUAL-ASSETS` | virtual\_assets / regulated\_financial\_services / financial\_crime\_aml\_cft\_sanctions | `verified_published` | 13 |
| `HK` | `HK-STABLECOINS-ORDINANCE` | virtual\_assets | `verified_published` | 195 |
| `ID` | `ID-PDP-LAW` | data\_protection\_privacy | `not_ready` | 0 |
| `IN` | `IN-DIGITAL-PERSONAL-DATA-PROTECTION` | data\_protection\_privacy | `verified_published` | 9 |
| `KE` | `KE-CORPORATE-REGISTRY-BRS` | corporate\_registry | `verified_published` | 52 |
| `KE` | `KE-DATA-PROTECTION` | data\_protection | `verified_published` | 66 |
| `KE` | `KE-EMPLOYMENT-LABOUR-WORKPLACE` | employment\_labour\_workplace | `verified_published` | 176 |
| `KE` | `KE-FINANCIAL-CRIME-AML-CFT-CPF` | financial\_crime\_compliance | `verified_published` | 171 |
| `KE` | `KE-TAX-FINANCE-COMPLIANCE` | tax\_finance\_compliance | `verified_published` | 146 |
| `MX` | `MX-CFDI-EINVOICING` | tax\_finance | `verified_published` | 12 |
| `MX` | `MX-LFPDPPP` | data\_protection\_privacy | `not_ready` | 0 |
| `Global` | `OECD-PILLAR-TWO-GLOBE` | tax\_finance | `verified_published` | 9 |
| `QA` | `QA-PDPL` | data\_protection\_privacy | `verified_published` | 10 |
| `CA-QC` | `QUEBEC-LAW-25` | data\_protection\_privacy | `verified_published` | 3 |
| `SG` | `SG-AI-GOVERNANCE-AI-VERIFY` | regulated\_ai / technology\_governance / data\_protection\_privacy | `verified_published` | 18 |
| `SG` | `SG-DPT-STABLECOINS` | virtual\_assets | `verified_published` | 85 |
| `SG` | `SG-MAS-TRM-OUTSOURCING` | regulated\_financial\_services | `verified_published` | 1,050 |
| `TH` | `TH-PDPA` | data\_protection\_privacy | `not_ready` | 0 |
| `TR` | `TR-KVKK` | data\_protection\_privacy | `verified_published` | 43 |
| `UAE/Dubai` | `UAE-DUBAI-VARA-VIRTUAL-ASSETS` | virtual\_assets / regulated\_financial\_services / financial\_crime\_aml\_cft\_sanctions | `verified_published` | 2 |
| `UK` | `UK-CORPORATE-REGISTRY-COMPANIES-HOUSE-ECCTA` | corporate\_registry\_company\_law | `verified_published` | 64 |
| `UK` | `UK-CRYPTOASSETS-FSMA` | virtual\_assets | `verified_published` | 106 |
| `UK` | `UK-DATA-PROTECTION-ICO-AI-GUIDANCE` | data\_protection\_privacy / regulated\_ai / technology\_governance | `not_ready` | 0 |
| `UK` | `UK-DATA-PROTECTION-PRIVACY` | data\_protection\_privacy | `verified_published` | 63 |
| `UK` | `UK-DATA-USE-AND-ACCESS` | data\_protection\_privacy | `verified_published` | 39 |
| `UK` | `UK-ECCTA-COMPANIES-HOUSE` | corporate\_registry\_company\_law | `verified_published` | 139 |
| `UK` | `UK-EMPLOYMENT-PAYROLL-WORKPLACE` | employment\_payroll\_workplace | `verified_published` | 63 |
| `UK` | `UK-FCA-REGULATED-FINANCIAL-SERVICES` | fca\_regulated\_financial\_services | `verified_published` | 48 |
| `UK` | `UK-FINANCIAL-CRIME-AML-CTF-SANCTIONS` | financial\_crime\_aml\_ctf\_sanctions | `verified_published` | 75 |
| `UK` | `UK-OFSI-SANCTIONS` | financial\_crime\_aml\_cft\_sanctions | `verified_published` | 1,097 |
| `UK` | `UK-PSTI-IOT-SECURITY` | cybersecurity\_governance | `verified_published` | 16 |
| `UK` | `UK-TAX-VAT-PAYROLL-FINANCE` | tax\_vat\_payroll\_finance | `verified_published` | 72 |
| `UN / Global` | `UN-SANCTIONS-IMPLEMENTATION` | financial\_crime\_aml\_cft\_sanctions | `verified_published` | 33 |
| `US-CA` | `US-CA-CCPA-CPRA` | data\_protection\_privacy | `verified_published` | 35 |
| `US-CO` | `US-CO-ADMT` | regulated\_ai | `verified_published` | 7 |
| `US` | `US-COPPA-CHILDREN-PRIVACY` | children\_privacy | `verified_published` | 3 |
| `US` | `US-CYBER-TRUST-MARK` | cybersecurity\_governance | `verified_published` | 8 |
| `US` | `US-DATA-BROKER-DELETE-ACTS` | data\_protection\_privacy | `verified_published` | 6 |
| `US` | `US-FDA-AI-ML-MEDICAL-DEVICES` | medical\_devices | `verified_published` | 54 |
| `US` | `US-HIPAA-SECURITY-PRIVACY` | data\_protection\_privacy | `verified_published` | 20 |
| `US` | `US-OFAC-SANCTIONS` | financial\_crime\_aml\_cft\_sanctions | `verified_published` | 236 |
| `US` | `US-SEC-CYBERSECURITY-DISCLOSURE` | securities\_disclosure / cybersecurity\_governance / corporate\_governance | `verified_published` | 6 |
| `ZA` | `ZA-POPIA-DATA-PROTECTION` | data\_protection\_privacy | `verified_published` | 4 |
## Discover And Filter
```bash CLI theme={null}
esheria packs list --format json
esheria packs list --jurisdiction UK --format json
esheria packs list --jurisdiction EU --readiness verified_published --format json
```
```bash API theme={null}
curl --compressed -sS \
"$ESHERIA_API_BASE_URL/api/v1/domain-packs?jurisdiction=SG&readiness_label=verified_published&limit=100" \
-H "x-api-key: $ESHERIA_API_KEY" | jq
```
Select packs by returned `domain_pack_id`, inspect readiness and limitations, and pass those IDs explicitly to API, CLI, and MCP workflows.
# Regulatory Packs
Source: https://docs.esheria.ai/guides/packs
Discover available packs, inspect readiness labels, and choose the right pack for a workflow.
Regulatory packs are source-backed fact bundles for a jurisdiction and legal
domain. Esheria is catalog-first: select a `pack_id` explicitly, then use that
same ID across API, CLI, and MCP workflows.
The sanitized discovery release contains 69 pack records across 27 jurisdiction labels. 60 are `verified_published`; 9 remain discoverable as `not_ready` metadata records without published legal-status facts. Catalog version: `2026-07-15-v1+sha256:c5732893a6156d077166b60ea5016166ac5b178bb024162320d3a54e0ce745eb`.
Browse every current pack, jurisdiction, legal domain, readiness state, and
published-fact count from the July 13, 2026 production snapshot.
## Discover Packs
Omit the jurisdiction filter to discover everything entitled to the token, or
filter by any jurisdiction returned by the catalog.
```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": "UK", "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 EU --readiness verified_published --format json
```
```json MCP theme={null}
{
"tool": "esheria_list_packs",
"arguments": {
"jurisdiction": "SG",
"readiness_label": "verified_published",
"limit": 100
}
}
```
Treat the API response as the source of truth. Catalog entries can change when
a pack is promoted, superseded, or temporarily marked not ready.
## Select A Pack Explicitly
```bash theme={null}
export ESHERIA_PACK_ID="UK-DATA-PROTECTION-PRIVACY"
esheria packs inspect "$ESHERIA_PACK_ID" --format json
esheria obligations list "$ESHERIA_PACK_ID" --limit 25 --format json
```
Inspect these fields before using a pack:
* `jurisdiction`
* `legal_domain`
* `readiness_label`
* `limitations`
* `published_legal_status_count`
* current version and version history
`not_ready` packs are catalog metadata, not production legal-intelligence
sources. Use packs marked `verified_published` for published-fact workflows.
## Version History And Diffs
Use the selected pack ID rather than relying on a product-wide default.
```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
curl --compressed -sS \
"$ESHERIA_API_BASE_URL/api/v1/domain-packs/$ESHERIA_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/$ESHERIA_PACK_ID/change-events?from_version=$FROM_VERSION&to_version=$TO_VERSION&limit=25" \
-H "x-api-key: $ESHERIA_API_KEY" | jq
```
Diff and change-event rows include change type, fact type, impacted fact IDs,
source/citation basis, materiality, confidence, and limitations.
## Multi-Jurisdiction Examples
| Jurisdiction/domain | Example pack |
| ---------------------------- | -------------------------------- |
| UK data protection | `UK-DATA-PROTECTION-PRIVACY` |
| EU cybersecurity | `EU-NIS2-CYBERSECURITY` |
| Singapore financial services | `SG-MAS-TRM-OUTSOURCING` |
| US sanctions | `US-OFAC-SANCTIONS` |
| Australia AML/CTF | `AU-AML-CTF-REFORMS` |
| Global tax | `OECD-PILLAR-TWO-GLOBE` |
| Kenya employment | `KE-EMPLOYMENT-LABOUR-WORKPLACE` |
These are examples, not defaults. Any entitled `verified_published` pack can
use the generic pack workflows for obligations, applicability, filing calendar,
evidence, penalties, `legal-review-audit`, versions, diffs, change events,
relationships, and export.
Claim verification is evaluator-gated. A pack may return
`unsupported_capability` for claim verification while its generic fact
workflows remain available.
## Readiness Labels
| Label | Meaning |
| ------------------------ | ------------------------------------------------------------------------- |
| `verified_published` | The current pack exposes published facts through production workflows |
| `not_ready` | Metadata is discoverable, but the pack has no approved published fact set |
| `unsupported_capability` | The pack exists, but a specific optional workflow is not enabled |
Production API mode serves published rows only. Internal draft and
citation-verification tiers are not customer API tiers.
# Rate Limits And Timeouts
Source: https://docs.esheria.ai/guides/rate-limits-and-timeouts
Design clients that handle local rate limits, timeouts, retries, and idempotent replay safely.
The API is designed for deterministic, source-backed workflows. Client code should use bounded timeouts, conservative retries, and idempotency keys on mutating requests.
## Recommended Client Defaults
| Setting | Recommended value |
| --------------- | ------------------------------------------------------------------------------- |
| Request timeout | `30` seconds |
| Retry count | `2` for transient network failures |
| Retry methods | Safe `GET` requests and idempotent `POST` retries with the same idempotency key |
| Page size | Start with `limit=25`; increase only when needed |
## Production Rate Limits
Esheria applies two independent controls:
1. An IP-level pre-authentication abuse limit (3,000 requests/minute by default).
2. An authenticated workspace limit from the active plan, shared by all API
and OAuth tokens in that workspace.
| Plan | Authenticated requests/minute |
| --------------------- | ----------------------------: |
| Sandbox | 30 |
| Developer | 60 |
| Team | 180 |
| Business | 600 |
| Enterprise / Embedded | 1,200+ contracted |
Production readiness requires the shared Redis limiter through
`API_REDIS_URL`. Customers behind the same NAT share only the high pre-auth IP
guard; after authentication, their paid limit is isolated by workspace.
Responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and
`Retry-After` when blocked.
The CLI uses:
```bash theme={null}
export ESHERIA_TIMEOUT_SECONDS="30"
export ESHERIA_RETRY_COUNT="2"
```
You can override per command:
```bash theme={null}
esheria --timeout 8 --retry-count 0 packs list --format json
```
## Pagination
List endpoints use `limit` and `offset`.
```bash theme={null}
curl --compressed -sS \
"$ESHERIA_API_BASE_URL/api/v1/domain-packs/SG-MAS-TRM-OUTSOURCING/obligations?limit=25&offset=0" \
-H "x-api-key: $ESHERIA_API_KEY" | jq
```
## Failure Modes
| Symptom | Meaning | Action |
| ------------------------------ | ------------------------------------------------------------- | ---------------------------------------------------------------------- |
| HTTP timeout | Runtime, network, or reverse-proxy issue | Retry with bounded attempts and store the failed `trace_id` if present |
| `429` or rate-limit response | Pre-auth abuse limit or authenticated plan limit was exceeded | Honor `Retry-After`, back off, and reduce concurrency |
| `409 idempotency_key_conflict` | Same key reused with different payload | Generate a new idempotency key |
| Large responses are slow | Full export or broad query | Use filters and pagination before exporting a whole pack |
## Production Notes
If Redis is unavailable, readiness fails and production billing rate checks
fail closed. Restore Redis before accepting customer traffic; development may
still use the bounded in-process limiter.
# Regulatory Intelligence
Source: https://docs.esheria.ai/guides/regulatory-intelligence
Monitor sources, rebuild graph coverage, preview customer lifecycle applicability, and optionally track hosted customer change impacts.
Regulatory intelligence workflows sit above published regulatory packs. They
keep legal truth in `regulatory_serving`, then add operational state for source
monitoring and graph projections. Customer lifecycle work is stateless by
default: clients send profile facts in a request and receive obligation and
impact previews without storing customer state in Esheria. Hosted customer
profiles, applicability runs, obligation instances, and customer change impacts
remain available as opt-in operational state.
Read and preview operations use `regulatory:read`. Source-watch mutations use
`monitoring:write`, graph projection rebuild uses `graph:write`, and persisted
customer lifecycle mutations use `customer:write`.
## Source Monitoring
Source monitoring stores source watches, source snapshots, source-change
events, and recompile candidates. Hosted watch URIs may be validated public
HTTP(S) URLs or deployment-allow-listed `s3://bucket/key` objects. The public
API rejects local files, private/link-local/metadata destinations, unsafe
redirects, caller-selected S3 endpoints, unapproved buckets, oversized
content, and oversized check batches.
Local paths remain available only to the offline pipeline monitor. They are not
reachable through the API or MCP.
```bash CLI theme={null}
esheria monitoring currentness --domain-pack-id UK-DATA-USE-AND-ACCESS --format json
esheria monitoring check --domain-pack-id UK-DATA-USE-AND-ACCESS --yes --format json
esheria monitoring recompile-candidates --domain-pack-id UK-DATA-USE-AND-ACCESS --format json
```
Binding source changes create recompile candidates. Guidance, watchlist, and
context source changes are recorded as non-binding currentness signals.
## Graph Projection
Graph projection rebuilds materialized graph tables from current published
serving facts only. Draft, blocked, and citation-verified rows are excluded
from authoritative graph truth and counted in coverage metadata.
```bash CLI theme={null}
esheria graph rebuild-projection --reason scheduled_rebuild --yes --format json
esheria graph coverage --domain-pack-id EU-NIS2-CYBERSECURITY --format json
```
Graph query uses the latest completed published projection when available, and
falls back to stored relationship facts only when no projection has been built.
Use graph query `explain=true` when a caller needs authority-source,
publication-mode, projection-run, and draft/blocked exclusion details.
## Customer Applicability
Use stateless lifecycle preview for the main data-infrastructure flow. It
returns citation-backed obligation previews and change-impact previews, and the
response marks `persistence.writes_performed` as `false`.
```bash CLI theme={null}
esheria customers preview \
--pack UK-DATA-PROTECTION-PRIVACY \
--role data_controller \
--activity personal_data_processing \
--sector financial_services \
--format json
```
Hosted lifecycle state is opt-in. Customer profiles are workspace scoped.
Applicability runs lock pack versions, return citation-backed results, and
create customer obligation instances that reference published fact IDs instead
of duplicating legal truth.
```bash CLI theme={null}
esheria customers create-profile \
--name "Acme UK fintech" \
--pack UK-DATA-PROTECTION-PRIVACY \
--profile-file customer-profile.json \
--format json
esheria customers run-applicability CUSTOMER_PROFILE_ID \
--pack UK-DATA-PROTECTION-PRIVACY \
--format json
esheria customers obligations \
--customer-profile-id CUSTOMER_PROFILE_ID \
--format json
esheria customers update-obligation CUSTOMER_OBLIGATION_INSTANCE_ID \
--status monitoring \
--priority high \
--owner-label "Compliance lead" \
--due-date 2026-07-31 \
--format json
```
`customer-profile.json` can include `entity_profile` and `profile_facts`.
```json theme={null}
{
"entity_profile": {
"entity_roles": ["data_controller"],
"regulated_activities": ["personal_data_processing"],
"sector_tags": ["financial_services"]
},
"profile_facts": [
{
"fact_type": "entity_role",
"value": "data_controller",
"source": "customer_attestation",
"confidence": 1.0
}
]
}
```
## Customer Change Impacts
Stateless previews can include change-impact previews. Hosted change impacts
connect pack change events to stored customer obligation instances only when a
customer opts into persisted lifecycle state.
```bash CLI theme={null}
esheria customers recompute-impacts \
--customer-profile-id CUSTOMER_PROFILE_ID \
--domain-pack-id UK-DATA-PROTECTION-PRIVACY \
--format json
esheria customers impacts \
--customer-profile-id CUSTOMER_PROFILE_ID \
--format json
esheria customers update-impact CUSTOMER_CHANGE_IMPACT_ID \
--status resolved \
--format json
```
## MCP Tools
The MCP server exposes the same workflows through:
* `esheria_get_source_currentness`
* `esheria_check_source_watches`
* `esheria_list_recompile_candidates`
* `esheria_rebuild_graph_projection`
* `esheria_get_graph_coverage`
* `esheria_preview_customer_lifecycle`
* `esheria_create_customer_profile`
* `esheria_run_customer_applicability`
* `esheria_list_customer_obligation_instances`
* `esheria_update_customer_obligation_instance`
* `esheria_recompute_customer_change_impacts`
* `esheria_list_customer_change_impacts`
* `esheria_update_customer_change_impact`
# Esheria
Source: https://docs.esheria.ai/index
Contextualised, computable legal knowledge for product, compliance, and agent workflows.
Esheria gives applications contextualised, computable legal knowledge: discover current packs, compare versions, monitor legal changes, retrieve obligations, test applicability, build filing calendars and evidence registers, inspect penalties and review audit metadata, query relationships, and verify claims with citation spans.
Every response preserves the audit trail that regulatory products need: `trace_id`, readiness labels, limitation disclosures, citation IDs, quote spans, and publication mode.
Esheria returns source-backed regulatory workflow data, not legal advice. Keep legal review in the loop for client-facing advice.
## Legal Operating Layer
Work with structured statutes, regulations, obligations, filing rules, evidence requirements, penalties, review metadata, and citation-backed source context.
Turn legal data into applicability reviews, registers, calendars, evidence checklists, change monitors, and product surfaces without losing the source trail.
Give assistants MCP tools that return citations, limitations, and `trace_id` with every legal workflow.
## Start Building
Sign up at `dashboard.esheria.ai`, create a data token, manage credits, and test calls in the playground.
Set a dashboard-created token, run the first `curl`, install `esheria`, configure MCP, and verify a claim with citations.
Use generated OpenAPI pages and the playground for every public endpoint.
Compare pack versions, inspect diffs, and route change events into downstream review.
Monitor sources, rebuild graph coverage, run customer applicability, and track customer impacts.
Use first-class filing rules, evidence requirements, penalty facts, and legal review audit metadata.
Run smoke checks, list packs, export evidence, and inspect claim-verification output.
Expose regulatory tools to Claude Desktop, Cursor, Codex MCP, or an internal host.
Map Esheria workflows to law firm, fintech, corporate registry, GRC, HR, tax, and AI product scenarios.
## First Request
```bash theme={null}
export ESHERIA_API_BASE_URL="https://api.esheria.ai"
export ESHERIA_API_KEY="YOUR_DASHBOARD_CREATED_DATA_TOKEN"
curl --compressed -sS \
"$ESHERIA_API_BASE_URL/api/v1/domain-packs?readiness_label=verified_published&limit=10" \
-H "x-api-key: $ESHERIA_API_KEY" | jq
```
The response shape is stable across endpoints:
```json theme={null}
{
"status": "ok",
"data": {
"packs": []
},
"errors": [],
"trace_id": "request-trace-id"
}
```
Errors use the same envelope:
```json theme={null}
{
"status": "error",
"data": null,
"errors": [
{
"code": "unauthorized",
"message": "Invalid API key"
}
],
"trace_id": "request-trace-id"
}
```
## Operational Model
Customer-facing endpoints serve the published regulatory pack tier and disclose readiness limitations.
Obligations, evidence, calendars, relationships, and claims carry citation IDs and quote-span context.
API and CLI preserve the API envelope. MCP returns bounded structured content with `trace_id` and truncation metadata.
## Core Workflows
API, CLI, and MCP entry points for current regulatory packs.
Published duties with classification, actionability, actors, workflow targets, citations, and quote spans.
Match obligations to structured entity profile facts, activities, sectors, and processing context.
Use versions, diffs, and change events before updating tenant operating records.
Filing rules, evidence requirements, penalties, and review audit metadata with source trace.
Test model or user claims against published facts before display.
MCP tools for Claude Desktop, Cursor, Codex MCP, and internal hosts.
## First User Journey
Open `https://dashboard.esheria.ai/`, sign up or sign in, and resolve your workspace.
Open **API Tokens**, create a data token, store the one-time secret, then set it as `ESHERIA_API_KEY`.
Call `/healthz`, then list packs with `/api/v1/domain-packs`.
Run `pip install esheria`, then `esheria packs list --format json`.
Add the live `https://mcp.esheria.ai/mcp` URL, then use OAuth where supported or a dashboard data token as the bearer-token alternative.
Use `verify-claim` to test a generated answer against published facts, citations, and quote spans.
## Current Pack Posture
The sanitized discovery release contains 69 pack records across 27 jurisdiction labels. 60 are `verified_published`; 9 remain metadata-only `not_ready` records. Catalog version: `2026-07-15-v1+sha256:c5732893a6156d077166b60ea5016166ac5b178bb024162320d3a54e0ce745eb`. Coverage includes Africa, Europe, North and South America, Asia-Pacific, Middle East, and global regulatory sources across privacy, financial crime, cybersecurity, tax, sustainability, virtual assets, AI, health, and other domains.
See every current pack ID, jurisdiction, legal domain, readiness state, and
published-fact count.
All listed packs expose the generic pack workflows for obligations,
applicability, filing calendars, evidence registers, penalty facts, legal
review audit, versions, diffs, change events, relationships, and export.
Claim verification is available only for packs with an enabled claim evaluation
profile; other packs return `unsupported_capability` for that workflow while
the generic pack endpoints continue to work.
# Quickstart
Source: https://docs.esheria.ai/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.
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:
```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.
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
```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
```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
}
}
```
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.
```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
}
}
```
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
Create tokens, manage credits, review usage, update billing, and use the playground.
Learn headers, idempotency, trace IDs, and error envelopes.
Install `esheria`, run smoke checks, and export pack data.
Connect an agent host to the live MCP endpoint and run the first five tool calls.
Copy complete examples for pack discovery, change monitoring, obligations, evidence, penalties, and claim checks.
# Examples
Source: https://docs.esheria.ai/recipes/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
```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
}
}
```
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
```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
}
}
```
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
```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
}
}
```
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
```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"
}
}
```
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
```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
}
}
```
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
```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
}
}
```
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
```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
}
}
```
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.
# Errors
Source: https://docs.esheria.ai/reference/errors
Interpret API error envelopes and recover from common authentication, idempotency, validation, and capability failures.
All errors use the normal API envelope.
```json theme={null}
{
"status": "error",
"data": null,
"errors": [
{
"code": "unauthorized",
"message": "Invalid API key"
}
],
"trace_id": "..."
}
```
## Common Codes
| Code | HTTP status | Meaning | Recovery |
| -------------------------- | -------------: | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `unauthorized` | `401` | Missing or invalid API key | Check `x-api-key`, create or rotate a token in the dashboard |
| `workspace_not_active` | `403` | Workspace token is valid but the workspace is suspended or closed | Contact the workspace owner or Esheria support |
| `api_token_required` | `403` | A token/billing management endpoint was called without an API-token principal | Use a management token when billing is enabled |
| `credits_exhausted` | `402` | Workspace has no available credits for a billable request | Add credits or create a subscription/top-up checkout session from the dashboard |
| `billing_unavailable` | `503` | Billing ledger could not be checked or settled | Retry after operators resolve ledger availability |
| `validation_error` | `422` | Request payload or parameters do not match the schema | Compare with the API Reference and examples |
| `idempotency_key_required` | `400` | Mutating request omitted `idempotency-key` | Send a unique key for the request intent |
| `idempotency_key_conflict` | `409` | Same idempotency key reused with a different payload | Use a new key or replay the original request |
| `unsupported_capability` | `400` or `422` | Pack exists but does not support the requested workflow | Use another workflow or pack |
| `deprecated_api_route` | `410` | Caller used a non-regulatory route outside the public contract | Move to the Regulatory Pack API surface |
| `not_ready` | `503` | Runtime dependencies are missing or unhealthy | Check `/readyz` and retry after operators resolve readiness |
## Client Pattern
```python theme={null}
import httpx
try:
response = httpx.get(
f"{base_url}/api/v1/domain-packs",
headers={"x-api-key": api_key},
timeout=30,
)
response.raise_for_status()
except httpx.HTTPStatusError as exc:
payload = exc.response.json()
trace_id = payload.get("trace_id")
errors = payload.get("errors", [])
raise RuntimeError(f"Esheria API error trace_id={trace_id} errors={errors}") from exc
```
## Support Checklist
When escalating an issue, include:
* endpoint and method
* timestamp
* `trace_id`
* HTTP status
* first error code and message
* sanitized request shape
Use `https://dashboard.esheria.ai/` for token rotation, credit top-ups, usage
inspection, and billing state before escalating a support issue.
Do not include API keys or personal data unless your support channel explicitly requires and protects it.
# Solutions And Use Cases
Source: https://docs.esheria.ai/solutions/use-cases
API, CLI, and MCP workflows for legal teams, compliance builders, and agentic products.
Esheria is useful when a product needs regulatory data that can become a
workflow: pack versions, change events, obligations, applicability results,
filing rules, evidence requirements, penalty facts, legal review audit metadata,
forms, citations, relationship context, and claim verification.
Use this page to choose the right API, CLI, or MCP path for a legal, compliance, or technical workflow.
Esheria returns source-backed regulatory workflow data, not legal advice. Keep legal review in the loop for client-facing advice.
## What Works Today
| Job to be done | API endpoint | CLI | MCP |
| --------------------------------- | --------------------------------------------------------- | ----------------------------- | -------------------------------- |
| Discover published packs | `GET /api/v1/domain-packs` | `esheria packs list` | `esheria_list_packs` |
| Inspect readiness and limits | `GET /api/v1/domain-packs/{pack_id}` | `esheria packs inspect` | `esheria_get_pack` |
| Monitor pack versions | `GET /api/v1/domain-packs/{pack_id}/versions` | `esheria packs versions` | `esheria_list_pack_versions` |
| Compare legal changes | `GET /api/v1/domain-packs/{pack_id}/diff` | `esheria packs diff` | `esheria_get_pack_diff` |
| Read change events | `GET /api/v1/domain-packs/{pack_id}/change-events` | `esheria packs change-events` | `esheria_list_change_events` |
| Build an obligation register | `GET /api/v1/domain-packs/{pack_id}/obligations` | `esheria obligations list` | `esheria_list_obligations` |
| Match duties to an entity profile | `POST /api/v1/domain-packs/{pack_id}/applicability-check` | `esheria applicability check` | `esheria_check_applicability` |
| Build a filing calendar | `GET /api/v1/domain-packs/{pack_id}/filing-calendar` | `esheria calendar list` | `esheria_get_filing_calendar` |
| Build an evidence register | `GET /api/v1/domain-packs/{pack_id}/evidence-register` | `esheria evidence list` | `esheria_get_evidence_register` |
| Triage penalties | `GET /api/v1/domain-packs/{pack_id}/penalty-facts` | `esheria penalties list` | `esheria_get_penalty_facts` |
| Audit publication decisions | `GET /api/v1/domain-packs/{pack_id}/legal-review-audit` | `esheria legal-review audit` | `esheria_get_legal_review_audit` |
| Verify a generated answer | `POST /api/v1/legal-status/verify-claim` | `esheria claims verify` | `esheria_verify_claim` |
| Query relationship context | `POST /api/v1/regulatory-graph/query` | `esheria graph query` | `esheria_query_regulatory_graph` |
| Export a pack | `GET /api/v1/domain-packs/{pack_id}/export` | `esheria packs export` | `esheria_export_pack` |
## Current Production Pack Coverage
The sanitized discovery release contains 69 pack records across 27 jurisdiction labels: 60 `verified_published` packs and 9 metadata-only `not_ready` records. Catalog version: `2026-07-15-v1+sha256:c5732893a6156d077166b60ea5016166ac5b178bb024162320d3a54e0ce745eb`. Use `GET /api/v1/domain-packs` for live discovery and inspect a pack before pinning its ID or version.
| Coverage area | Representative packs | Useful workflows |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| United Kingdom and European Union | `UK-OFSI-SANCTIONS`, `UK-DATA-USE-AND-ACCESS`, `EU-NIS2-CYBERSECURITY`, `EU-CSRD-ESRS` | Sanctions, privacy, cybersecurity, sustainability, and change monitoring |
| North and South America | `US-OFAC-SANCTIONS`, `US-HIPAA-SECURITY-PRIVACY`, `CA-QC-PRIVACY-LAW-25`, `CO-HABEAS-DATA` | Sanctions, health privacy, regional privacy, and evidence workflows |
| Asia-Pacific | `SG-MAS-TRM-OUTSOURCING`, `AU-AML-CTF-REFORMS`, `HK-STABLECOINS-ORDINANCE`, `IN-DIGITAL-PERSONAL-DATA-PROTECTION` | Financial services, AML/CTF, virtual assets, and privacy |
| Africa and Middle East | `KE-EMPLOYMENT-LABOUR-WORKPLACE`, `ZA-POPIA-DATA-PROTECTION`, `BH-PDPL`, `UAE-DUBAI-VARA-VIRTUAL-ASSETS` | Employment, privacy, and virtual-asset compliance |
| Global sources | `FATF-TRAVEL-RULE-R16`, `OECD-PILLAR-TWO-GLOBE`, `UN-SANCTIONS-IMPLEMENTATION` | Financial crime, tax, and sanctions implementation |
View the complete production catalog and readiness state for every pack.
Generic pack workflows are available across the loaded packs. Claim
verification remains evaluator-gated; choose a pack with an enabled evaluator
when using `POST /api/v1/legal-status/verify-claim`.
## Fastest Useful Flow
1. List packs.
2. Inspect the pack readiness label and limitations.
3. Check the current version and latest change events.
4. Run applicability for the user's entity profile.
5. Pull obligations, filing rules, evidence requirements, and penalties.
6. Verify any generated answer before displaying it.
7. Store citation IDs, quote spans, source basis, and `trace_id` with the downstream workflow.
```bash curl theme={null}
curl --compressed -sS -X POST \
"$ESHERIA_API_BASE_URL/api/v1/domain-packs/UK-DATA-PROTECTION-PRIVACY/applicability-check" \
-H "content-type: application/json" \
-H "x-api-key: $ESHERIA_API_KEY" \
-H "idempotency-key: $(python3 -c 'import uuid; print(uuid.uuid4())')" \
-d '{
"entity_profile": {
"jurisdictions": ["UK"],
"entity_types": ["data_controller"],
"regulated_activities": ["personal_data_processing"],
"data_categories": ["customer_personal_data"]
},
"profile_facts": [],
"limit": 5
}' | jq
```
```bash CLI theme={null}
esheria applicability check UK-DATA-PROTECTION-PRIVACY \
--role data_controller \
--activity personal_data_processing \
--sector financial_services \
--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
}
}
```
Expected output includes applicable obligations, match reasons, applicability
status, confidence, citations, quote spans, readiness labels, limitations, and
`trace_id`.
## Vertical Plays
Use obligations, provisions through pack export, citations, and claim verification to prepare research-backed client notes and review generated legal answers before associates rely on them.
Build data protection obligation registers, regulator-facing task lists, evidence checklists, and answer verification for product and compliance teams.
Use corporate registry packs, filing-calendar items, forms, provisions, and relationship context to build entity-maintenance checklists.
Convert obligations into controls, evidence requirements, audit tasks, and traceable source-backed registers.
Use employment and payroll packs as they are published to build workplace obligations, filing dates, and evidence checklists.
Use tax and VAT packs as they are published to create filing calendars, recordkeeping checklists, and entity-profile workflows.
Use AML/CFT packs as they are published to map obligations to controls, evidence, customer-risk workflows, and reporting calendars.
Use claim verification, citation context, and MCP tools to keep generated answers grounded in published regulatory facts.
## Example Plays
### UK Fintech Privacy Register
Business question:
> We are a UK fintech acting as a data controller and processing customer personal data. What obligations should product, legal, and compliance review first?
Call applicability, then turn returned obligations into tasks.
```bash CLI theme={null}
esheria applicability check UK-DATA-PROTECTION-PRIVACY \
--role data_controller \
--activity personal_data_processing \
--sector financial_services \
--format json
```
Then fetch the evidence register:
```bash CLI theme={null}
esheria evidence list UK-DATA-PROTECTION-PRIVACY --format json
```
Then inspect penalty facts and review audit metadata through the API:
```bash curl theme={null}
curl --compressed -sS \
"$ESHERIA_API_BASE_URL/api/v1/domain-packs/UK-DATA-PROTECTION-PRIVACY/penalty-facts?limit=25" \
-H "x-api-key: $ESHERIA_API_KEY" | jq
curl --compressed -sS \
"$ESHERIA_API_BASE_URL/api/v1/domain-packs/UK-DATA-PROTECTION-PRIVACY/legal-review-audit?limit=25" \
-H "x-api-key: $ESHERIA_API_KEY" | jq
```
### Corporate Registry Checklist
Business question:
> Which corporate registry duties, forms, and filings should a company secretary monitor?
Start with a UK Companies House pack and calendar-facing workflow:
```bash CLI theme={null}
esheria packs inspect UK-CORPORATE-REGISTRY-COMPANIES-HOUSE-ECCTA
esheria calendar list UK-CORPORATE-REGISTRY-COMPANIES-HOUSE-ECCTA --format json
esheria packs export UK-CORPORATE-REGISTRY-COMPANIES-HOUSE-ECCTA --include-all-forms --out companies-house-pack.json
```
### AI Answer Guardrail
Business question:
> Can we show this generated regulatory answer to a user?
Verify the claim before display:
```bash CLI theme={null}
esheria claims verify \
--pack UK-DATA-PROTECTION-PRIVACY \
"A controller must respond to a valid data subject access request within the applicable statutory period." \
--format json
```
This claim example uses one currently evaluator-enabled pack; it is not a
jurisdiction default. If the selected pack returns `unsupported_capability`,
use its generic obligation, applicability, evidence, penalty, relationship,
and change workflows instead. For any `not_found` or
`supported_with_corrections` result, show the limitations and corrections
rather than presenting the answer as settled.