KB Analytics & Learning

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

Get KB 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

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.

integer

default:"30"

Look-back window for time-scoped sections (trends, costs, resource-performance, feedback-gaps, funnel).

integer

default:"10"

Number of top chunks in the default dashboard.

Response (200) — `section=learning`

object

Show learningReadiness

number

Total weighted training-signal score.

array

Per-source counts and weighted contribution (includes reserved coming-soon sources).

array

The three learning stages (smart_ranking, learned_weights, custom_reranker) with threshold, unlocked, and progress (0–1).

boolean

Whether the learned ranking prior is switched on for this KB.

boolean

Whether any resource has crossed its exposure floor and is actually boosted.

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

curl "https://your-domain.com/api/knowledge/kb/$KB_ID/analytics?section=resource-performance&days=30" \
  -H "Authorization: Bearer $TOKEN"

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

Toggle the learned ranking prior

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

boolean

required

true to apply learning to ranking; false to keep manual control (semantic + keyword relevance + content weights only).

Response (200)

boolean

The new state.

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}'

Recompute the engagement prior

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

Response (200)

integer

Number of documents whose prior was recomputed.

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 '{}'

Getting Started

Agent Provisioning

Bot Service

Auth Service

Knowledge Service

Get KB analytics

Query parameters

Response (200) — `section=learning`

Toggle the learned ranking prior

Response (200)

Recompute the engagement prior

Response (200)

​Get KB analytics

​Query parameters

​Response (200) — section=learning

​Toggle the learned ranking prior

​Response (200)

​Recompute the engagement prior

​Response (200)

Get KB analytics

Query parameters

Response (200) — `section=learning`

Toggle the learned ranking prior

Response (200)

Recompute the engagement prior

Response (200)