Response format

Success

{
  "success": true,
  "version": "v1",
  "request": { "tool": "calculate_bmi", "calculator_id": "bmi", "inputs": { "weight_kg": 70, "height_cm": 175 }, "request_id": "req_…", "received_at": "2026-09-23T07:20:14Z" },
  "result": {
    "entity_type": "calculation", "id": "calc_bmi", "calculator_id": "bmi", "calculator_name": "BMI Calculator", "category": "health",
    "status": "completed",
    "values": { "bmi": 22.86, "category": "Normal weight", "healthy_weight_min_kg": 56.7, "healthy_weight_max_kg": 76.3, "prime": 0.914 },
    "units": { "bmi": "kg/m²", "healthy_weight_min_kg": "kg", "healthy_weight_max_kg": "kg" },
    "formula": "BMI = weight_kg / (height_cm / 100)²",
    "notes": [],
    "summary": "BMI: 22.86 kg/m²; Category: Normal weight; …"
  },
  "warnings": [],
  "sources": [ { "name": "WHO – …", "url": "https://…", "type": "standard", "retrieved_at": "2026-09-23" } ],
  "freshness": { "type": "static", "max_age_seconds": null, "note": "…" },
  "cache": { "hit": false, "cacheable": true, "deterministic": true },
  "timestamp": "2026-09-23T07:20:14Z",
  "duration_ms": 1,
  "next_actions": [ { "tool": "calculate_bmr", "calculator_id": "bmr", "reason": "…", "url": "https://…", "docs": "https://…" } ],
  "links": { "self": "…", "html": "…", "markdown": "…", "schema": "…", "openapi": "…", "mcp": "…", "task": "…" }
}

• values are rounded to the precision declared per output; units maps output names to units.
• status is always completed for calculations (all tools are synchronous). Task states used elsewhere: pending, processing, completed, failed, cancelled.
• timestamp, received_at, retrieved_at are ISO 8601 UTC.
• freshness.type ∈ static, daily (date-dependent defaults). cache.deterministic=false means re-run when the date changes.
• next_actions lists related tools an agent can call next with the reason.
• links.task is a content-addressed task URL: GET /api/v1/tasks/{task_id} returns the same calculation again (no storage; the id encodes calculator and inputs).

Failure

{
  "success": false,
  "version": "v1",
  "error": { "code": "OUT_OF_RANGE", "message": "height_cm must be <= 300, got 1750.", "field": "height_cm", "hint": "Allowed range: min 50, max 300 cm.", "retryable": false },
  "request": { "tool": "calculate_bmi", "calculator_id": "bmi", "inputs": { "weight_kg": "70", "height_cm": "1750" }, "request_id": "req_…" },
  "timestamp": "2026-09-23T07:20:14Z",
  "links": { "docs": "https://…/docs/errors.md", "schema": "https://…/api/v1/calculators/bmi" }
}

HTTP status codes match the error (400, 404, 405, 422, 429, 500). See errors.

Markdown source: /docs/response-format.md