Developer documentation

AskBiz API

Embed business intelligence into your own products with a single API call. Send a question and business context — get back a structured answer with verdict, KPI cards, charts, and recommendations.

Get your API key →See examples

Overview

One endpoint: POST /api/v1/ask. Send a natural language question and business context. Get back structured JSON.

⚡

Single endpoint

One POST request for all intelligence

🧠

Claude-powered

Business intelligence grounded in your data

📊

Structured output

JSON with charts, KPIs, verdicts

🔒

Secure by default

API key auth, HTTPS only, CORS enabled

Authentication

All requests require an x-api-key header. Get your key from Settings → API Keys.

HTTP header

x-api-key: abz_live_your_key_here

Keep your key secret. Never expose it in client-side code or public repos. Revoke compromised keys from Settings immediately.

Endpoint

POSThttps://askbiz.co/api/v1/ask

Accepts JSON. Returns JSON. CORS is enabled — callable from browser or server.

Request format

questionstringrequired

Plain English business question. Max 2,000 characters.

contextobject

Business data to ground the answer. All fields optional.

context.currencystring

ISO currency code. Default: 'GBP'

context.symbolstring

Currency symbol. Default: '£'

context.biz_typestring

'retail' | 'ecommerce' | 'distributor' | 'exporter'

context.regionstring

Country code e.g. 'GB', 'US', 'NG'

context.revenuenumber

Monthly revenue in your currency

context.marginnumber

Average gross margin as a percentage

context.top_productsstring[]

Array of your top product names

context.*any

Any additional fields — Claude will use them

options.cfo_modeboolean

Board-ready financial language. Default: false

options.simulate_modeboolean

Model before/after impact of a what-if scenario. Default: false

Response format

answerstring

Plain-English answer. 2–5 sentences.

insight_headerstring

One-sentence summary. Good for card headers.

verdictact|watch|problem

act = do something now · watch = monitor · problem = urgent

verdict_sentencestring

One sentence. One action. Max 20 words.

confidencehigh|medium|low

AI confidence based on context provided.

kpi_cardsarray

Array of {label, value, trend, status} objects.

chartobject|null

{type, labels, values, label} or null.

recommendationsstring[]

3–5 specific actions with numbers.

follow_up_questionsstring[]

Code examples

cURL

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": "What is my best selling product?",
    "context": {
      "currency": "GBP",
      "symbol": "£",
      "biz_type": "ecommerce",
      "revenue": 18400,
      "margin": 34,
      "top_products": ["Trainers", "Hoodies", "Caps"]
    }
  }'

JavaScript / TypeScript

const res = await fetch('https://askbiz.co/api/v1/ask', {
  method: 'POST',
  headers: {
    'x-api-key': 'abz_live_your_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    question: 'What is my best selling product?',
    context: {
      currency: 'GBP', symbol: '£',
      biz_type: 'ecommerce',
      revenue: 18400, margin: 34,
      top_products: ['Trainers', 'Hoodies', 'Caps'],
    },
  }),
})
const data = await res.json()
console.log(data.answer)
console.log(data.verdict)          // 'act' | 'watch' | 'problem'
console.log(data.kpi_cards)        // array of metric cards
console.log(data.recommendations)  // array of action strings

Python

import requests

res = requests.post(
    'https://askbiz.co/api/v1/ask',
    headers={
        'x-api-key': 'abz_live_your_key_here',
        'Content-Type': 'application/json',
    },
    json={
        'question': 'What is my best selling product?',
        'context': {
            'currency': 'GBP', 'symbol': '£',
            'biz_type': 'ecommerce',
            'revenue': 18400, 'margin': 34,
            'top_products': ['Trainers', 'Hoodies', 'Caps'],
        },
    }
)
data = res.json()
print(data['answer'])
print(data['verdict'])

Example response

{
  "answer": "Your best seller is Trainers at an estimated £8,200 this month. With a 34% margin that is roughly £2,788 in gross profit.",
  "insight_header": "Trainers driving 45% of revenue — margin healthy",
  "verdict": "act",
  "verdict_sentence": "Prioritise Trainers restocking — highest margin, highest volume.",
  "confidence": "high",
  "kpi_cards": [
    { "label": "Est. Trainers revenue", "value": "£8,200", "trend": "up", "status": "good" },
    { "label": "Gross margin", "value": "34%", "trend": "neutral", "status": "good" }
  ],
  "chart": {
    "type": "bar",
    "labels": ["Trainers", "Hoodies", "Caps"],
    "values": [8200, 6100, 4100],
    "label": "Estimated revenue by product"
  },
  "recommendations": [
    "Prioritise Trainers in your next restock order",
    "Consider a bundle with Hoodies — frequently bought together",
    "Review Caps cost vs selling price"
  ],
  "follow_up_questions": [
    "What is my margin on Trainers specifically?",
    "Should I expand the Trainers range?"
  ],
  "meta": {
    "model": "askbiz-v1",
    "latency_ms": 1240,
    "requests_remaining": 97
  }
}

Errors

400

Bad Request

Missing or invalid "question" field, or malformed JSON

401

Unauthorized

Missing or invalid x-api-key header

403

Forbidden

API key is disabled — re-enable in Settings

429

Rate Limit Exceeded

Monthly or per-minute limit reached

500

Internal Server Error

AI request failed — retry with exponential backoff

Pricing

API plans are separate from your AskBiz subscription. All keys start on Free automatically.

Free

£0/mo

100 requests / month

5 requests / minute

Starter

£29/mo

2,000 requests / month

20 requests / minute

Growth

£99/mo

10,000 requests / month

60 requests / minute

Enterprise

Custom

Unlimited requests / month

120 requests / minute

Upgrade your API plan →