> ## Documentation Index
> Fetch the complete documentation index at: https://docs.esheria.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CodeGroup>
  ```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
    }
  }
  ```
</CodeGroup>

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