API — Recipes

These assume you’ve set BQP_BASE and BQP_KEY from the Quickstart. Every call sends Authorization: Bearer $BQP_KEY.

Ingest a document and chat over it

# 1. create a datasource → returns its id
curl -s "$BQP_BASE/v1/datasources" \
  -H "Authorization: Bearer $BQP_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Policies"}'
# → { "id": "DS_ID", ... }

# 2. upload a PDF (multipart) → 202 Accepted with a document + job id
curl -s "$BQP_BASE/v1/datasources/DS_ID/documents" \
  -H "Authorization: Bearer $BQP_KEY" \
  -F "file=@handbook.pdf"
# → { "document_id": "DOC_ID", "job_id": "JOB_ID" }

# 3. poll until processing finishes (status goes parsing → embedding → tagging → "ready")
curl -s "$BQP_BASE/v1/documents/DOC_ID" -H "Authorization: Bearer $BQP_KEY"
# → { ..., "status": "ready" }      # "failed" means processing errored (see the "error" field)

# 4. ask a grounded question scoped to the datasource
curl -s "$BQP_BASE/v1/chat" \
  -H "Authorization: Bearer $BQP_KEY" -H "Content-Type: application/json" \
  -d '{"message":"What is our refund policy?","datasource_ids":["DS_ID"]}'
# → { "session_id": "...", "answer": "...", "trace": [ ...evidence... ], "model": "..." }

trace holds the tool calls and passages behind the answer — the evidence. Pass the returned session_id on the next call to continue the same conversation.

Run a governed proposal

# pick an advisor that has datasources attached
curl -s "$BQP_BASE/v1/personas" -H "Authorization: Bearer $BQP_KEY"

# 1. request a recommendation (the advisor drafts it)
curl -s "$BQP_BASE/v1/proposals" \
  -H "Authorization: Bearer $BQP_KEY" -H "Content-Type: application/json" \
  -d '{"persona_id":"PERSONA_ID","situation":"Should we raise prices 10% next quarter?"}'
# → { "id": "PROP_ID", "status": "proposed", "recommendation": "...", "evidence": [...] }

# 2a. a checker approves it …
curl -s "$BQP_BASE/v1/proposals/PROP_ID/verdict" \
  -H "Authorization: Bearer $BQP_KEY" -H "Content-Type: application/json" \
  -d '{"verdict":"approved","reason":"Aligned with strategy"}'

# 2b. … or asks the advisor to refine it (regenerates, stays "proposed")
curl -s "$BQP_BASE/v1/proposals/PROP_ID/regenerate" \
  -H "Authorization: Bearer $BQP_KEY" -H "Content-Type: application/json" \
  -d '{"suggestions":"Be more cautious about churn; lead with a clear go/no-go."}'

verdict is approved, rejected, and a decision is final. Deciding requires a checker or admin; requesting does not. Proposals are an organization feature.

Connect an external AI client (MCP)

To let Claude Desktop, Cursor, or another MCP client search your knowledge directly, use the ready‑made client config under Studio → MCP in the app — see Integrations & MCP. It authenticates with the same API key.