/ Developer + agent API

Instant Quote API

Karven prices Australian trade jobs with a deterministic engine, one calculator per trade. This API exposes that engine over HTTP so an AI booking agent, or a tradie’s own website, can get a structured, GST-inclusive instant quote in a single call. The price comes from the engine. No language model sets it.

View the live schema Try a calculator

Endpoints

POST /api/quote/instant: Send a trade slug and job inputs, receive a price band, point estimate and line breakdown. CORS-enabled and rate-limited per IP (60 requests per minute).
GET /api/quote/schema: The self-serve discovery document. Lists every trade slug and its required inputs (id, type, options, price band). Read this first to learn what to send.

Request

POST a JSON body with a trade slug and an inputs object. Any input id the trade does not accept is rejected with a clear 400 so you can self-correct. Omit inputs and the engine uses realistic defaults.

curl -X POST https://www.karven.com.au/api/quote/instant \
  -H 'content-type: application/json' \
  -d '{
    "trade": "deck-cost",
    "inputs": { "deck_length_m": 6, "deck_width_m": 4 }
  }'

Response

A stable, versioned quote. estimate, priceBand and every lines[].amount are AUD, GST inclusive. The shape is pinned by apiVersion.

{
  "ok": true,
  "quote": {
    "apiVersion": "1.0",
    "trade": "deck-cost",
    "tradeName": "Deck",
    "currency": "AUD",
    "gstInclusive": true,
    "priceBand": { "low": 6500, "typical": 10500, "high": 17500, "unit": "..." },
    "estimate": 11240,
    "lines": [ { "label": "Decking boards", "amount": 3180 } ],
    "assumptions": [ "Priced at typical 2026 Australian metro rates." ],
    "disclaimer": "Instant estimate ... not a fixed quote.",
    "url": "https://www.karven.com.au/calculators/deck-cost",
    "computedAt": "2026-06-07T00:00:00.000Z"
  }
}

Errors

Bad input returns HTTP 400 with a machine-readable code: invalid_request, unknown_trade (lists the available trades) or unknown_input (lists the accepted inputs). Over the rate limit returns HTTP 429 with a Retry-After header.

{
  "ok": false,
  "apiVersion": "1.0",
  "error": {
    "code": "unknown_input",
    "message": "Unknown input(s) for trade \"deck-cost\": made_up_field.",
    "unknownInputs": ["made_up_field"],
    "acceptedInputs": ["deck_length_m", "deck_width_m", "deck_board_type"]
  }
}

/ For tradies

Want every quote to come from your own prices?

Inside Karven the same engine runs on your real rates and supplier prices, then sends a branded quote to your customer. Start a free week and put the calculator on your own site.

Start a free week Embed the estimator