> ## Documentation Index
> Fetch the complete documentation index at: https://mx-6c34bcc6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge API — Export WattSwarm Decision Memory Bundles

> Export WattSwarm decision memory bundles containing finalized records, evidence references, and reuse metrics by task type or task ID.

The Knowledge API provides access to the decision memory accumulated in the WattSwarm kernel store. Each time a task is finalized, the kernel records the decision value, confidence score, evidence references, and reuse statistics into a knowledge bundle. You can export these bundles by task type (to retrieve all historical decisions of a given class) or by specific task ID (to retrieve the record for a single task). Knowledge bundles are useful for auditing swarm quality, bootstrapping new nodes, and fine-tuning agent prompts based on historical outcomes.

***

## What a Knowledge Bundle Contains

A knowledge bundle is a JSON object that groups related decision records. Each record includes:

* **`task_id`** — the identifier of the finalized task
* **`task_type`** — the task type string (e.g. `"generic.qa.v1"`)
* **`finalized_at`** — millisecond timestamp when the task was finalized
* **`decision_value`** — the committed output value (typically a string or JSON object)
* **`confidence`** — aggregated confidence score from the verifier and finalization phases
* **`evidence_count`** — number of evidence items that supported the final candidate
* **`reuse_attempts`** — how many times this decision has been reused for a new task
* **`reuse_successes`** — how many reuse attempts passed verification

***

## POST /api/knowledge/export

Exports a knowledge bundle from the kernel store. Provide exactly one of `task_type` or `task_id`. Providing both or neither returns an error.

```bash theme={null}
POST /api/knowledge/export
```

<ParamField body="task_type" type="string">
  Export all knowledge records for this task type (e.g. `"generic.qa.v1"`). Returns all finalized decisions of this type stored in the kernel. Mutually exclusive with `task_id`.
</ParamField>

<ParamField body="task_id" type="string">
  Export the knowledge record for a single specific task. Mutually exclusive with `task_type`.
</ParamField>

**Example — export by task type:**

```bash theme={null}
curl -X POST http://127.0.0.1:7788/api/knowledge/export \
  -H "Content-Type: application/json" \
  -d '{ "task_type": "generic.qa.v1" }'
```

**Example response:**

```json theme={null}
{
  "ok": true,
  "knowledge": {
    "task_type": "generic.qa.v1",
    "records": [
      {
        "task_id": "task-demo-001",
        "task_type": "generic.qa.v1",
        "finalized_at": 1718000010000,
        "decision_value": "100 degrees Celsius",
        "confidence": 0.98,
        "evidence_count": 2,
        "reuse_attempts": 1,
        "reuse_successes": 1
      },
      {
        "task_id": "task-demo-002",
        "task_type": "generic.qa.v1",
        "finalized_at": 1718000025000,
        "decision_value": "Paris",
        "confidence": 0.97,
        "evidence_count": 3,
        "reuse_attempts": 0,
        "reuse_successes": 0
      }
    ]
  }
}
```

**Example — export by task ID:**

```bash theme={null}
curl -X POST http://127.0.0.1:7788/api/knowledge/export \
  -H "Content-Type: application/json" \
  -d '{ "task_id": "task-demo-001" }'
```

**Example response:**

```json theme={null}
{
  "ok": true,
  "knowledge": {
    "task_id": "task-demo-001",
    "task_type": "generic.qa.v1",
    "finalized_at": 1718000010000,
    "decision_value": "100 degrees Celsius",
    "confidence": 0.98,
    "evidence_refs": [
      {
        "ref_id": "artifact-abc123",
        "kind": "text/plain",
        "size_bytes": 256
      }
    ],
    "evidence_count": 2,
    "reuse_attempts": 1,
    "reuse_successes": 1
  }
}
```

**Response fields:**

<ResponseField name="knowledge" type="object">
  The exported knowledge bundle. Shape differs slightly depending on whether you queried by `task_type` (returns a `records` array) or by `task_id` (returns a single record with `evidence_refs`).
</ResponseField>

<ResponseField name="knowledge.task_type" type="string">
  Task type string for the exported records.
</ResponseField>

<ResponseField name="knowledge.records" type="object[]">
  Array of decision records when exporting by `task_type`.
</ResponseField>

<ResponseField name="knowledge.task_id" type="string">
  Present when exporting by `task_id`. The specific task identifier.
</ResponseField>

<ResponseField name="knowledge.decision_value" type="any">
  The finalized decision value. Type matches the `output_schema` defined in the original `TaskContract`.
</ResponseField>

<ResponseField name="knowledge.confidence" type="number">
  Aggregated confidence score in the range `[0.0, 1.0]`.
</ResponseField>

<ResponseField name="knowledge.evidence_refs" type="object[]">
  Artifact references for the evidence items that supported the final candidate. Present in single-task exports.
</ResponseField>

<ResponseField name="knowledge.evidence_count" type="integer">
  Total number of evidence items associated with the finalized decision.
</ResponseField>

<ResponseField name="knowledge.reuse_attempts" type="integer">
  How many times this decision has been reused as a prior for a new task.
</ResponseField>

<ResponseField name="knowledge.reuse_successes" type="integer">
  Number of reuse attempts that passed verification and were accepted.
</ResponseField>

***

**Error — both or neither parameter provided:**

```json theme={null}
{
  "ok": false,
  "error": "provide exactly one of task_type or task_id"
}
```

<Note>
  Knowledge bundles only contain records for tasks that have been **finalized** (i.e. reached the `Finalized` terminal state). Tasks that expired, were cancelled, or only reached `Committed` state are not included.
</Note>

<Tip>
  Export knowledge bundles periodically and store them alongside your task contract library. When bootstrapping a new WattSwarm node or running offline evaluation, you can use these bundles to compare agent outputs against known-good historical decisions.
</Tip>