Quickstart

1. Sign up programmatically (AI-agent flow)

curl -X POST https://api.buildcalcapi.dev/v1/account/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "payment_method_id": "pm_card_visa"
  }'

In production replace pm_card_visa (Stripe's universal test card) with a real PaymentMethod ID created via Stripe Elements or the Stripe API.

The response contains your API key (shown only once):

{
  "api_key": "bcapi_...",
  "key_prefix": "bcapi_xx",
  "tier": "free",
  "monthly_quota": 1000,
  "rpm_limit": 10,
  "stripe_customer_id": "cus_..."
}

Save the api_key immediately. Lost keys cannot be recovered — create a new one via POST /v1/account/api-keys.

Browser flow (Turnstile)

For human-facing signup forms, pass turnstile_token (from a Cloudflare Turnstile widget) and setup_intent_id (from a Stripe SetupIntent) instead of payment_method_id. See Authentication for the full anti-abuse design.

2. Call your first calculator

curl -X POST https://api.buildcalcapi.dev/v1/calc/concrete/yards \
  -H "Authorization: Bearer bcapi_..." \
  -H "Content-Type: application/json" \
  -d '{"length_ft": 10, "width_ft": 10, "depth_in": 4}'

Returns:

{
  "cubic_yards": 1.358,
  "cubic_feet": 33.333,
  "bags_60lb": 62,
  "bags_80lb": 49,
  "waste_included_cuyd": 0.123
}

The math: 10ft × 10ft × (4in / 12) = 33.33 cuft. Divided by 27 = 1.235 cuyd base. With default 10% waste factor = 1.358 cuyd. ACI 332 / IRC R506 compliant.

3. Discover the catalog

# 81 calculators grouped by category
curl https://api.buildcalcapi.dev/v1/calc/list \
  -H "Authorization: Bearer bcapi_..."

# 5 code families (IRC, IBC, NEC, IECC, IPC) — see Codes vertical docs
curl https://api.buildcalcapi.dev/v1/codes/list \
  -H "Authorization: Bearer bcapi_..."

# OpenAPI 3.x schema for the whole API (SDK generators, Postman, Insomnia)
curl https://api.buildcalcapi.dev/v1/openapi.json \
  -H "Authorization: Bearer bcapi_..."

/v1/calc/list returns a list grouped by category with each entry having kind, path, and a one-line summary. /v1/codes/list returns the 5 code families with their default + available editions. See Codes vertical for the section + adoption endpoints.

/v1/openapi.json returns the full OpenAPI 3.x schema for every endpoint — input/output Pydantic models, parameter types, response shapes, the works. Feed it to openapi-generator-cli or Postman/Insomnia to scaffold a typed client in any language. The schema is auth-gated (a valid API key is required); the interactive Swagger UI and ReDoc viewers are intentionally disabled in production to keep schema enumeration behind authentication.

4. Hook up an MCP client

Point Claude Desktop, Cursor, or any MCP-compatible AI agent at https://api.buildcalcapi.dev/mcp with Authorization: Bearer <key> to get all ~105 tools (calculators + codes + costs + benchmarks + products endpoints + discovery helpers) auto-discovered. See MCP integration for the full config.