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

# Epistemic analysis

> Chat with Wu-Weism's epistemic analysis engine, retrieve scientific evidence records, and access epistemic session data.

The epistemic analysis endpoints surface the knowledge layer beneath Wu-Weism's causal reasoning: confidence assessment, assumption identification, knowledge-gap detection, and provenance tracking for scientific evidence. Use these endpoints to build epistemic audit trails, expose uncertainty to end users, or retrieve the evidence records underpinning a session's claims.

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

***

## Epistemic analysis chat

```
POST /api/epistemic/chat
```

Opens an epistemic analysis dialogue. Given a scientific question, the engine assesses the epistemic state of the available evidence: what is known, what is assumed, where the evidence is weak or missing, and how confident Wu-Weism is in its causal inferences.

Responses are streamed as Server-Sent Events (SSE).

### Request body

<ParamField body="question" type="string" required>
  The scientific question or claim you want epistemic analysis on. Can be a hypothesis, a causal claim, or a general research question.

  Example: `"Is there sufficient evidence that chronic cortisol elevation causally reduces hippocampal volume in adult humans?"`
</ParamField>

<ParamField body="sessionId" type="string">
  UUID of an existing session to continue. If omitted, a new session is created.
</ParamField>

<ParamField body="providerId" type="string">
  AI provider to use for the analysis: `"anthropic"`, `"openai"`, or `"gemini"`. Defaults to the platform provider if not specified. See [Authentication](/api/authentication) for BYOK key details.
</ParamField>

### SSE events

The stream emits text chunks and structured events as the analysis progresses.

| Event         | Payload                          | Description                                                          |
| ------------- | -------------------------------- | -------------------------------------------------------------------- |
| `delta`       | `{text: string}`                 | Incremental text of the epistemic analysis narrative.                |
| `confidence`  | `{score: number, label: string}` | Overall confidence score (0.0–1.0) and label for the analysed claim. |
| `assumptions` | `{assumptions: string[]}`        | List of causal and epistemic assumptions the analysis rests on.      |
| `gaps`        | `{gaps: string[]}`               | Knowledge gaps identified — areas where evidence is insufficient.    |
| `done`        | `{sessionId: string}`            | Emitted when the analysis is complete.                               |
| `error`       | `{message: string}`              | Emitted on fatal error.                                              |

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://wuweism.com/api/epistemic/chat \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "question": "Is there sufficient evidence that chronic cortisol elevation causally reduces hippocampal volume in adult humans?",
      "providerId": "anthropic"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://wuweism.com/api/epistemic/chat', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer <token>',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      question: 'Is there sufficient evidence that chronic cortisol elevation causally reduces hippocampal volume in adult humans?',
      providerId: 'anthropic',
    }),
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    for (const line of chunk.split('\n')) {
      if (line.startsWith('data: ')) {
        const event = JSON.parse(line.slice(6));
        if (event.text) process.stdout.write(event.text);
      }
    }
  }
  ```

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

  response = requests.post(
      'https://wuweism.com/api/epistemic/chat',
      headers={'Authorization': 'Bearer <token>'},
      json={
          'question': 'Is there sufficient evidence that chronic cortisol elevation causally reduces hippocampal volume?',
          'providerId': 'anthropic',
      },
      stream=True,
  )

  for line in response.iter_lines():
      if line.startswith(b'data: '):
          event = json.loads(line[6:])
          if 'text' in event:
              print(event['text'], end='', flush=True)
  ```
</CodeGroup>

***

## Retrieve scientific evidence records

```
GET /api/epistemic/scientific-evidence
```

Returns scientific evidence records associated with your account. These records are created when PDFs are processed through the hybrid synthesize pipeline or uploaded for epistemic analysis. Each record captures the file's provenance, a structured summary, and the key scientific findings extracted during analysis.

### Response fields

<ResponseField name="evidence" type="object[]" required>
  Array of evidence records.

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

    <ResponseField name="fileName" type="string">
      Original filename of the processed PDF.
    </ResponseField>

    <ResponseField name="summary" type="string">
      Structured summary of the document's scientific content generated during analysis.
    </ResponseField>

    <ResponseField name="provenance" type="object">
      Origin and processing metadata.

      <Expandable title="provenance properties">
        <ResponseField name="runId" type="string">
          ID of the synthesis or analysis run that produced this record.
        </ResponseField>

        <ResponseField name="sessionId" type="string">
          Session in which the PDF was processed.
        </ResponseField>

        <ResponseField name="processedAt" type="string">
          ISO 8601 timestamp of when the PDF was analysed.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="keyFindings" type="string[]">
      List of key scientific findings extracted from the document.
    </ResponseField>

    <ResponseField name="causalEntities" type="string[]">
      Variable names and causal entities identified in the document, suitable for use as node names in SCM queries.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://wuweism.com/api/epistemic/scientific-evidence \
    --header 'Authorization: Bearer <token>'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://wuweism.com/api/epistemic/scientific-evidence', {
    headers: { 'Authorization': 'Bearer <token>' },
  });

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

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

  response = requests.get(
      'https://wuweism.com/api/epistemic/scientific-evidence',
      headers={'Authorization': 'Bearer <token>'},
  )

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

<ResponseExample>
  ```json 200 theme={null}
  {
    "evidence": [
      {
        "evidenceId": "ev-7c3d1e2f-aa4b-4c9a-b011-d2e3f4a5b678",
        "fileName": "mcewen_2012_stress_hippocampus.pdf",
        "summary": "Comprehensive review of glucocorticoid-mediated structural plasticity in the hippocampus. Covers dendritic remodelling in CA3, BDNF suppression under chronic stress, and reversibility of volume reduction following stress cessation.",
        "provenance": {
          "runId": "run-4e2f9c10-bb3a-4d8e-a917-c1d0f2b3e456",
          "sessionId": "s9f8e7d6-cc4d-4f1a-b802-d6e7f3a0c291",
          "processedAt": "2026-04-05T12:01:08Z"
        },
        "keyFindings": [
          "Chronic stress reduces CA3 dendritic arborisation in rodent models.",
          "Elevated cortisol suppresses BDNF mRNA expression.",
          "Hippocampal volume reduction is partially reversible after stress removal."
        ],
        "causalEntities": [
          "cortisol_level",
          "stress_exposure",
          "BDNF_expression",
          "hippocampal_volume",
          "CA3_dendritic_arborisation"
        ]
      }
    ]
  }
  ```
</ResponseExample>

***

## Get epistemic session data

```
GET /api/epistemic/session
```

Returns epistemic session data for your most recent (or active) session. Use this to retrieve the accumulated epistemic state — questions asked, assumptions surfaced, confidence trajectory, and knowledge gaps identified — across a session's lifetime.

### Response fields

<ResponseField name="sessionId" type="string" required>
  UUID of the session.
</ResponseField>

<ResponseField name="createdAt" type="string" required>
  ISO 8601 timestamp when the session was created.
</ResponseField>

<ResponseField name="questions" type="object[]" required>
  List of questions asked in this session, in chronological order.

  <Expandable title="question properties">
    <ResponseField name="questionId" type="string">
      UUID of the question.
    </ResponseField>

    <ResponseField name="text" type="string">
      The question text.
    </ResponseField>

    <ResponseField name="confidence" type="number">
      Confidence score returned for this question (0.0–1.0).
    </ResponseField>

    <ResponseField name="uncertaintyLabel" type="string">
      Human-readable uncertainty bucket.
    </ResponseField>

    <ResponseField name="timestamp" type="string">
      ISO 8601 timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="aggregateAssumptions" type="string[]" required>
  Deduplicated list of all causal and epistemic assumptions surfaced across the session.
</ResponseField>

<ResponseField name="aggregateGaps" type="string[]" required>
  Deduplicated list of all knowledge gaps identified across the session.
</ResponseField>

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://wuweism.com/api/epistemic/session \
    --header 'Authorization: Bearer <token>'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://wuweism.com/api/epistemic/session', {
    headers: { 'Authorization': 'Bearer <token>' },
  });

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

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

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

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

<ResponseExample>
  ```json 200 theme={null}
  {
    "sessionId": "s9f8e7d6-cc4d-4f1a-b802-d6e7f3a0c291",
    "createdAt": "2026-04-05T11:55:00Z",
    "questions": [
      {
        "questionId": "q-001",
        "text": "Is there sufficient evidence that chronic cortisol elevation causally reduces hippocampal volume in adult humans?",
        "confidence": 0.74,
        "uncertaintyLabel": "medium",
        "timestamp": "2026-04-05T11:56:12Z"
      }
    ],
    "aggregateAssumptions": [
      "Rodent models generalise to adult human hippocampal plasticity.",
      "Cortisol as measured in serum is a reliable proxy for tissue-level glucocorticoid exposure.",
      "SUTVA holds: one subject's cortisol exposure does not affect another's hippocampal volume."
    ],
    "aggregateGaps": [
      "Limited longitudinal human data with causal (interventional) designs.",
      "Dose-response relationship between cortisol and hippocampal volume not well characterised in humans.",
      "Mechanistic pathway from cortisol to volume reduction (BDNF vs. neurogenesis vs. dendritic atrophy) not yet resolved."
    ]
  }
  ```
</ResponseExample>