Ask business-intelligence questions

POST /api/v1/ask takes a question and returns a grounded, structured answer — not just prose, but a verdict, KPI cards, an optional chart or table, and concrete recommendations. It is not credit-billed: it’s free within your plan’s monthly and per-minute quota, with no wallet debit either way, regardless of mode or options.

1. 1

   Decide account mode vs. generic mode

   Check which mode your API key is in before you write any context — it determines whether /api/v1/ask has anything to ground the answer in besides the question text. An account-mode key is tied to a real AskBiz business: the endpoint automatically pulls that business’s profile (currency, biz_type, region) and the columns from its latest uploaded dataset, and any context you send is ignored. A generic-mode key has no connected account, so context is the only source of grounding data — without it, the model has nothing but the question text to work with.

2. 2

   Craft a specific question and call the endpoint

   Send the question in the required question field (max 2000 characters) with your x-api-key. Ask about a specific metric, product, or time window — a vague "How’s my business doing?" gets a vague answer back. Account mode needs nothing else in the body:

   cURLJavaScriptPython

   curl -X POST https://askbiz.co/api/v1/ask \
     -H "x-api-key: abz_live_your_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "question": "Which of my top products should I reorder before the weekend rush?"
     }'

3. 3

   Optional — request CFO-style framing with options.cfo_mode

   Add options: { cfo_mode: true } to the same request body when you want the answer framed the way a financial controller would think about it, rather than a plain operational answer. It doesn’t change which fields come back — you still get the same answer, kpi_cards, chart, table, and recommendations shape, just different framing in the text fields. options also accepts a separate simulate_mode boolean; see the ask reference for the full options object.

   cURLJavaScriptPython

   curl -X POST https://askbiz.co/api/v1/ask \
     -H "x-api-key: abz_live_your_key_here" \
     -H "Content-Type: application/json" \
     -d '{
       "question": "If margins hold steady, what is my cash runway over the next 3 months?",
       "options": { "cfo_mode": true }
     }'

4. 4

   Read the structured response, not just answer

   Every successful call returns the same shape regardless of mode or options. kpi_cards are ready to render as stat tiles, chart and table are pre-shaped for a charting library or a data grid (each is null when the model didn’t judge the answer suited to that format), and recommendations gives concrete next actions without parsing prose. answer is still there for a plain-text fallback, but treat it as the least structured field, not the primary one:

   200 — success

   {
     "answer": "Rice 5kg and Cooking oil 2L are both below 2 days of cover at your current sales pace — reorder those two before the weekend. Your other top sellers have more than a week of stock left.",
     "insight_header": "Two top sellers are close to running out",
     "verdict": "act",
     "verdict_sentence": "Rice 5kg and Cooking oil 2L will likely stock out before your next scheduled delivery.",
     "confidence": "high",
     "kpi_cards": [
       { "label": "Products below 2 days cover", "value": "2" },
       { "label": "Fastest stockout", "value": "Rice 5kg — 1.2 days" }
     ],
     "chart": null,
     "table": {
       "headers": ["Product", "Stock qty", "Days of cover"],
       "rows": [
         ["Rice 5kg", 9, "1.2"],
         ["Cooking oil 2L", 14, "1.8"],
         ["Maize flour 2kg", 62, "9.4"]
       ]
     },
     "recommendations": [
       "Reorder Rice 5kg and Cooking oil 2L today — both are projected to stock out before your next delivery window.",
       "Maize flour 2kg has enough cover to wait until your next scheduled order."
     ],
     "follow_up_questions": [
       "How much should I reorder of Rice 5kg to cover the next two weeks?",
       "Which supplier gives me the best price on Cooking oil 2L?"
     ],
     "meta": {
       "model": "askbiz-v1",
       "latency_ms": 1610,
       "requests_remaining": 412
     }
   }

   JavaScriptPython

   if (result.kpi_cards?.length) renderStatTiles(result.kpi_cards)
   if (result.chart) renderChart(result.chart)       // null when the answer doesn't suit a chart
   if (result.table) renderTable(result.table)       // null when the answer doesn't suit a table
   if (result.recommendations?.length) renderActionList(result.recommendations)
   
   // result.answer is still there for a plain-text fallback or a chat transcript
   console.log(result.answer)

Generic mode — passing your own context

If your key is in generic mode, there’s no connected AskBiz account for the endpoint to read from, so add a context object with whatever fields are relevant to the question — currency, symbol, biz_type, region, revenue, margin, top_products, sector, or any other free-form key/value pairs. The same question from step 2, grounded with explicit context instead of a connected account:

curl -X POST https://askbiz.co/api/v1/ask \
  -H "x-api-key: abz_generic_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Which of my top products should I reorder before the weekend rush?",
    "context": {
      "currency": "KES",
      "symbol": "KSh",
      "biz_type": "retail",
      "region": "Nairobi, Kenya",
      "top_products": ["Rice 5kg", "Cooking oil 2L", "Maize flour 2kg"]
    }
  }'

What’s next

For the full parameter table, response field reference, and error codes, see POST /api/v1/ask. Note that unlike /scan and /whatsapp/send, /ask doesn’t accept an Idempotency-Key header — a 500 is still safe to retry since nothing is ever billed, but each retry is a brand-new call. See Errors and retries for the full contract across endpoints that do support idempotency.