Studies, insights & exports

Every run persists its study, code-computed aggregates, respondent rows, and insight. These endpoints get them back out.

List studies

curl "$BASE/api/v1/studies?limit=20&q=pricing" \
  -H "x-api-key: $MAVERA_API_KEY"

Filters: ?method=, ?projectId=, ?q= (keyword), ?limit= (max 100). Newest first, each with n, aggregate count, and topic.

Read one study

curl "$BASE/api/v1/studies/study_abc123?rows=100" \
  -H "x-api-key: $MAVERA_API_KEY"

Returns the full record: design/provenance, confidence, every aggregate (computedBy: "code" — the bright line, enforced in the schema), paginated respondent rows, and the linked insight.

Export the raw data

curl -OJ "$BASE/api/v1/studies/study_abc123/export?format=csv" \
  -H "x-api-key: $MAVERA_API_KEY"

format=csv (default) downloads respondent rows Excel/pandas-ready; format=json downloads the complete study document (design + aggregates + rows).

List & read insights

curl "$BASE/api/v1/insights?q=tagline" \
  -H "x-api-key: $MAVERA_API_KEY"

curl "$BASE/api/v1/insights/ins_xyz789" \
  -H "x-api-key: $MAVERA_API_KEY"

The detail view includes citedAggregates — the computed statistics behind every number the insight quotes, so every claim is traceable to its source.

Chat confidence & the feedback loop

Every conversational Mave reply carries a support-graded confidence score:

{
  "text": "A won on appeal — 31% top-2-box vs 11%...",
  "confidence": {
    "score": 0.92,
    "basis": "study-data",          // study-data | account-context | platform-knowledge | general
    "wouldImprove": null             // present when score < 0.6
  }
}

The score grades how well-supported the answer is, not how sure it sounds — 0.9+ means read directly from study data; under 0.4 means speculation (and the reply says so). When confidence is low, wouldImprove names the one study that would raise it, and the app renders it as a one-click run button.

Every reply is also logged to the confidence ledger:

curl "$BASE/api/v1/quality/chat?days=30" \
  -H "x-api-key: $MAVERA_API_KEY"

Returns mean confidence, a per-basis breakdown, and the low-confidence queue — every reply under 0.6 with its improving action. That queue is effectively your research backlog, generated automatically from the questions your team asked that the data couldn't answer.

Budgets & spending controls

Set a soft cap and get proactive warnings — no more surprise spend:

curl "$BASE/api/v1/budget" -H "x-api-key: $MAVERA_API_KEY"

Returns capCredits, usedCredits, remainingCredits, usedPct, and a level (ok | warn | critical | exhausted).

{
  "budgetCredits": 5000,   // soft cap for the period (null clears it — plan allowance rules)
  "warnAtPct": 75,          // budget agent warns when usage crosses this %
  "addCredits": 1000        // top up (rolls over)
}

Per-conversation limits

Give a single conversation its own soft/hard cap — e.g. "this client study chat gets 500 credits":

{
  "conversationId": "chat_abc123",
  "softCredits": 300,   // one-time warning bubble when crossed (null = none)
  "hardCredits": 500    // new studies REFUSED past this (chat still answers; nothing charged)
}

GET /api/v1/budget/conversation?id=chat_abc123 returns used/soft/hard and a level (ok | soft | blocked). Set workspace-wide presets for every new conversation via PUT /api/v1/budget { "convSoftDefault": 300, "convHardDefault": 500 }.

In the app, every conversation shows a live budget bar at the top of the chat, updated as runs settle — plus a THIS CHAT chip when conversation limits are active. When usage crosses your warning threshold, Mave proactively tells you in the chat — including how many typical studies the remainder buys — and again at 95% (critical) and exhaustion. Runs that would exceed the cap are blocked at reservation time, never billed partially.