---
title: "The flagship: a computed, cited answer from verified data. Requires a free API key."
method: POST
path: "/v1/answer"
---

# The flagship: a computed, cited answer from verified data. Requires a free API key.

`POST /v1/answer`

## Request

- Base URL: `https://starwell.dev/api/starwell`
- URL: `https://starwell.dev/api/starwell/v1/answer`
- Auth: HTTP bearer

Real Python runs in a sandbox over the verified store — nothing is model-estimated. Returns the answer, the chart, the code, and per-series verification + citations. Refuses honestly (422) when no served series can answer. 10-40s on a cache miss; cached answers serve instantly and invalidate when the official data moves. mode:'deep' plans 3-4 orthogonal analyses (trend, statistics, outliers, cross-series relationships), runs each in the sandbox, and synthesizes one decision-ready report with per-section stdout, code, and charts (60-180s; cached separately from default answers). Requires an API key — free at /account; keyless calls return 401 code key_required. A keyless sample lives at GET /v1/answer/demo.

## Request body

- object
  - `question` string, required
  - `series` object[]: Optional: pin exact series and skip AI resolution.
    - `source` string
    - `seriesId` string
  - `start` string, date
  - `end` string, date
  - `source` string: Optional: restrict resolution to one source.
  - `mode` 'default' | 'deep': 'deep': planned multi-section report — every section is real sandbox-computed Python, synthesized into one cited answer.

## Response `200`

Computed answer with python, chart, citations, verification badges, and honest coverage meta. meta also carries the scope-honesty fields, each present only when it applies: truncatedSeries (daily series capped at the latest 6,000 points), uncoveredSubjects (subjects the question asked about that no served series answers), emptySeries (resolved series with no observations in the window), failingSeriesUsed (series failing verification at compute time), and degraded (true when the sandbox run reported an internal issue and its fallback was served — never dressed as full confidence). In mode:'deep', data.sections[] carries each analysis (title, stdout, python, charts, ok, degraded).

## Other responses

- `400`: Invalid parameters.
- `401`: Missing or invalid API key (code key_required). Keys are free at /account.
- `422`: No served series answers this question (never an invented number).
- `429`: Per-IP preview limit or key quota exceeded.

---

[API](https://skmtc.dev/starwell/apis/starwell-api.md) · [All operations](https://skmtc.dev/starwell/apis/starwell-api/llms.txt) · [OpenAPI document](https://skmtc.dev/starwell/apis/starwell-api/revisions/faaa9f35d4e6?raw)