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

# KB Analytics & Learning

> Retrieve knowledge-base analytics, outcome attribution, and learning-loop readiness; control the learned ranking prior.

All routes require a `Bearer` token and are scoped to the caller's organization.

## Get KB analytics

<ParamField method="GET" path="/api/knowledge/kb/{id}/analytics" />

Returns the analytics dashboard for a knowledge base. Pass a `section` to fetch a specific view; omit it for the default dashboard (usage stats + top chunks).

### Query parameters

<ParamField query="section" type="string">
  Which view to return. One of:

  * `trends` — query volume + average relevance over time (`&days=N`)
  * `agents` — per-agent usage breakdown
  * `gaps` — low-relevance / never-used queries
  * `content` — per-document utilization
  * `costs` — embedding + vector-store cost attribution (`&days=N`)
  * `resource-performance` — per-document impressions, thumbs up/down, helpfulness tier (outcome attribution)
  * `feedback-gaps` — queries that retrieved from the KB but earned a thumbs down, ranked by failure count
  * `funnel` — impression → click → conversion funnel with CTR / conversion rate
  * `learning` — learning-loop readiness: weighted signal score, per-source breakdown, stage unlocks, prior state

  Omit to return the default dashboard.
</ParamField>

<ParamField query="days" type="integer" default="30">
  Look-back window for time-scoped sections (`trends`, `costs`, `resource-performance`, `feedback-gaps`, `funnel`).
</ParamField>

<ParamField query="limit" type="integer" default="10">
  Number of top chunks in the default dashboard.
</ParamField>

### Response (200) — `section=learning`

<ResponseField name="learningReadiness" type="object">
  <Expandable title="learningReadiness">
    <ResponseField name="score" type="number">Total weighted training-signal score.</ResponseField>
    <ResponseField name="breakdown" type="array">Per-source counts and weighted contribution (includes reserved coming-soon sources).</ResponseField>
    <ResponseField name="stages" type="array">The three learning stages (`smart_ranking`, `learned_weights`, `custom_reranker`) with `threshold`, `unlocked`, and `progress` (0–1).</ResponseField>
    <ResponseField name="priorEnabled" type="boolean">Whether the learned ranking prior is switched on for this KB.</ResponseField>
    <ResponseField name="priorActive" type="boolean">Whether any resource has crossed its exposure floor and is actually boosted.</ResponseField>
  </Expandable>
</ResponseField>

Other sections return a single key named after the view — e.g. `resourcePerformance`, `feedbackGaps`, `conversionFunnel`, `queryTrends`, `agentUsageBreakdown`, `knowledgeGaps`, `contentUtilization`, `costAttribution`.

<CodeGroup>
  ```bash curl theme={null}
  curl "https://your-domain.com/api/knowledge/kb/$KB_ID/analytics?section=resource-performance&days=30" \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch(
    `/api/knowledge/kb/${kbId}/analytics?section=learning`,
    { headers: { Authorization: `Bearer ${token}` } },
  );
  const { learningReadiness } = await res.json();
  ```
</CodeGroup>

## Toggle the learned ranking prior

<ParamField method="PATCH" path="/api/knowledge/kb/{id}/learning-prior" />

Turn the engagement-based ranking boost on or off for a knowledge base. On by default. Requires `edit` access to the knowledge base.

<ParamField body="enabled" type="boolean" required>
  `true` to apply learning to ranking; `false` to keep manual control (semantic + keyword relevance + content weights only).
</ParamField>

### Response (200)

<ResponseField name="enabled" type="boolean">The new state.</ResponseField>

<CodeGroup>
  ```bash curl theme={null}
  curl -X PATCH "https://your-domain.com/api/knowledge/kb/$KB_ID/learning-prior" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"enabled": false}'
  ```
</CodeGroup>

## Recompute the engagement prior

<ParamField method="POST" path="/api/knowledge/kb/{id}/learning-prior/refresh" />

Recompute the engagement prior for this knowledge base's organization on demand (it otherwise refreshes on a schedule). Requires `edit` access.

### Response (200)

<ResponseField name="documents" type="integer">Number of documents whose prior was recomputed.</ResponseField>

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://your-domain.com/api/knowledge/kb/$KB_ID/learning-prior/refresh" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" -d '{}'
  ```
</CodeGroup>