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

# Claims

> List and retrieve causal claims produced during your Wu-Weism research sessions.

Every causal assertion generated by Wu-Weism — whether from the causal chat, hybrid synthesize pipeline, or legal reasoning feature — is recorded as a **claim** in your account's claim ledger. Claims carry a confidence score, uncertainty label, and provenance links back to the trace and session that produced them.

<Note>
  All claims endpoints require authentication. Include your session token in the `Authorization` header.
</Note>

***

## List claims

```
GET /api/claims
```

Returns a paginated list of claims for your account. Filter by session, trace, or source feature to narrow results.

### Query parameters

<ParamField query="limit" type="number" default="20">
  Maximum number of claims to return. Accepted range: 1–100. Defaults to 20.
</ParamField>

<ParamField query="sourceFeature" type="string">
  Filter claims by the feature that produced them. One of:

  * `chat` — claims from the causal chat interface
  * `hybrid` — claims from the hybrid synthesize pipeline
  * `legal` — claims from the legal reasoning feature
</ParamField>

<ParamField query="sessionId" type="string">
  Filter claims to a specific session UUID. Returns only claims produced in that session.
</ParamField>

<ParamField query="traceId" type="string">
  Filter claims linked to a specific counterfactual trace UUID.
</ParamField>

### Response fields

<ResponseField name="success" type="boolean" required>
  `true` when the request succeeds.
</ResponseField>

<ResponseField name="claims" type="object[]" required>
  Array of claim objects.

  <Expandable title="claim properties" defaultOpen={true}>
    <ResponseField name="id" type="string">
      UUID of the claim.
    </ResponseField>

    <ResponseField name="source_feature" type="string">
      The feature that produced this claim: `"chat"`, `"hybrid"`, or `"legal"`.
    </ResponseField>

    <ResponseField name="claim_kind" type="string">
      The epistemic type of the claim. Common values: `"hypothesis"`, `"finding"`, `"counterfactual"`, `"mechanism"`.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status of the claim: `"active"`, `"retracted"`, or `"superseded"`.
    </ResponseField>

    <ResponseField name="confidence_score" type="number">
      Numerical confidence in the claim, from `0.0` (no confidence) to `1.0` (certain). Derived from the underlying causal analysis.
    </ResponseField>

    <ResponseField name="uncertainty_label" type="string">
      Human-readable uncertainty bucket corresponding to `confidence_score`: `"low"`, `"medium"`, or `"high"`.
    </ResponseField>

    <ResponseField name="trace_id" type="string">
      UUID of the counterfactual trace that produced this claim. Use this to retrieve the full trace via [GET /api/scm/counterfactual-traces/{traceId}](/api/scm/counterfactual-traces).
    </ResponseField>

    <ResponseField name="session_id" type="string">
      UUID of the session in which this claim was generated.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the claim was created.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://wuweism.com/api/claims?limit=10&sourceFeature=chat' \
    --header 'Authorization: Bearer <token>'
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    limit: '10',
    sourceFeature: 'chat',
  });

  const response = await fetch(`https://wuweism.com/api/claims?${params}`, {
    headers: { 'Authorization': 'Bearer <token>' },
  });

  const { claims } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://wuweism.com/api/claims',
      headers={'Authorization': 'Bearer <token>'},
      params={'limit': 10, 'sourceFeature': 'chat'},
  )

  claims = response.json()['claims']
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "claims": [
      {
        "id": "c1a2b3d4-0001-4abc-9def-000000000001",
        "source_feature": "chat",
        "claim_kind": "hypothesis",
        "status": "active",
        "confidence_score": 0.82,
        "uncertainty_label": "high",
        "trace_id": "b3f1c2d4-88ae-4e1a-9c3b-7f2a0d5e6b19",
        "session_id": "s9f8e7d6-cc4d-4f1a-b802-d6e7f3a0c291",
        "created_at": "2026-01-15T10:30:00Z"
      },
      {
        "id": "c1a2b3d4-0001-4abc-9def-000000000002",
        "source_feature": "chat",
        "claim_kind": "counterfactual",
        "status": "active",
        "confidence_score": 0.61,
        "uncertainty_label": "medium",
        "trace_id": "a1b2c3d4-11aa-4e1a-9c3b-aabbccddeeff",
        "session_id": "s9f8e7d6-cc4d-4f1a-b802-d6e7f3a0c291",
        "created_at": "2026-01-15T10:35:22Z"
      }
    ]
  }
  ```
</ResponseExample>

***

## Get a specific claim

```
GET /api/claims/{claimId}
```

Returns the full record for a single claim, including evidence links and gate decisions from the causal reasoning pipeline.

### Path parameters

<ParamField path="claimId" type="string" required>
  UUID of the claim to retrieve.
</ParamField>

### Response fields

All fields from the list response apply. The full record also includes:

<ResponseField name="evidence_links" type="object[]" required>
  Documents, PDF analyses, or external sources that support this claim.

  <Expandable title="evidence_link properties">
    <ResponseField name="linkId" type="string">
      UUID of the evidence link.
    </ResponseField>

    <ResponseField name="sourceType" type="string">
      Type of evidence: `"pdf"`, `"company_profile"`, `"trace"`, or `"external"`.
    </ResponseField>

    <ResponseField name="label" type="string">
      Human-readable description of the evidence source.
    </ResponseField>

    <ResponseField name="url" type="string">
      URL or reference path for the source, if available.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="gate_decisions" type="object[]" required>
  Records of each gate the claim passed through in the reasoning pipeline (e.g., novelty gate, integrity gate). Empty array if no gates were applied.

  <Expandable title="gate_decision properties">
    <ResponseField name="gate" type="string">
      Name of the gate: `"novelty"`, `"integrity"`, `"identifiability"`.
    </ResponseField>

    <ResponseField name="passed" type="boolean">
      Whether the claim passed this gate.
    </ResponseField>

    <ResponseField name="rationale" type="string">
      Explanation of the gate decision.
    </ResponseField>

    <ResponseField name="timestamp" type="string">
      ISO 8601 timestamp of the gate evaluation.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://wuweism.com/api/claims/c1a2b3d4-0001-4abc-9def-000000000001 \
    --header 'Authorization: Bearer <token>'
  ```

  ```javascript JavaScript theme={null}
  const claimId = 'c1a2b3d4-0001-4abc-9def-000000000001';

  const response = await fetch(`https://wuweism.com/api/claims/${claimId}`, {
    headers: { 'Authorization': 'Bearer <token>' },
  });

  const claim = await response.json();
  ```

  ```python Python theme={null}
  import requests

  claim_id = 'c1a2b3d4-0001-4abc-9def-000000000001'

  response = requests.get(
      f'https://wuweism.com/api/claims/{claim_id}',
      headers={'Authorization': 'Bearer <token>'},
  )

  claim = response.json()
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "id": "c1a2b3d4-0001-4abc-9def-000000000001",
    "source_feature": "chat",
    "claim_kind": "hypothesis",
    "status": "active",
    "confidence_score": 0.82,
    "uncertainty_label": "high",
    "trace_id": "b3f1c2d4-88ae-4e1a-9c3b-7f2a0d5e6b19",
    "session_id": "s9f8e7d6-cc4d-4f1a-b802-d6e7f3a0c291",
    "created_at": "2026-01-15T10:30:00Z",
    "evidence_links": [
      {
        "linkId": "el-001",
        "sourceType": "pdf",
        "label": "McEwen et al. (2012) — Stress and hippocampal plasticity",
        "url": null
      },
      {
        "linkId": "el-002",
        "sourceType": "trace",
        "label": "Counterfactual trace: cortisol_level → hippocampal_volume",
        "url": "/api/scm/counterfactual-traces/b3f1c2d4-88ae-4e1a-9c3b-7f2a0d5e6b19"
      }
    ],
    "gate_decisions": [
      {
        "gate": "identifiability",
        "passed": true,
        "rationale": "Back-door criterion satisfied with adjustment set ['stress_exposure'].",
        "timestamp": "2026-01-15T10:29:55Z"
      },
      {
        "gate": "novelty",
        "passed": true,
        "rationale": "Claim is sufficiently distinct from prior claims in this session.",
        "timestamp": "2026-01-15T10:29:58Z"
      }
    ]
  }
  ```

  ```json 404 theme={null}
  {
    "success": false,
    "error": "Claim not found"
  }
  ```
</ResponseExample>