Ask

GET /v1/ask takes a plain-language question and returns a grounded answer built exclusively from Foresight data. It is the same data the deterministic endpoints serve — observations, computed insights, active signals — selected and narrated for your question.

curl "https://api.creativeforesight.io/v1/ask?q=How+has+unemployment+in+Williamson+County,+Texas+trended+over+the+past+two+years" \
  -H "Authorization: Bearer cf_live_REPLACE_ME"

The grounding contract

The answer engine is an orchestrator, not an oracle. It selects from the same typed tools the MCP server exposes, and it may only phrase facts those tools returned:

• Every number, direction, and date in the prose appears verbatim in a cited tool payload. The engine verifies this mechanically on every response; the grounded flag tells you whether verification passed.
• The citations array is assembled from the tool calls the engine actually executed — it is not self-reported by the model.
• If the tools return nothing relevant, the answer says so. The engine never improvises and never answers from general model knowledge.
• One statistic, one source. When several datasets could answer the same question — population, say — the answer uses the editorially chosen series for that kind of place and cites it, rather than juxtaposing competing figures.
• Statistics — trends, CAGR, deltas, watermarks — come from the deterministic facts layer. The model narrates them; it does not compute them.

You don’t pay when we don’t have the data

Before any payment is requested, a deterministic coverage check screens the question against the indicator catalog. No coverage means a free no_coverage response, and on the x402 path no 402 challenge is ever issued. Covered questions are $0.25 per paid x402 ask, or any Foresight API key.

Briefing depth

Add depth=briefing for a full briefing instead of a focused answer: the engine runs a deeper orchestration pass (more tool calls, a longer answer) on a premium model, priced at $1.50 per paid x402 request. Everything else is unchanged — the grounding contract, the citation trace, and the rule that uncovered questions are free at any depth.

Curated briefings

Foresight also publishes curated briefings on a schedule. The catalog at GET /v1/briefings/public is free; the latest run of any briefing — full grounded prose plus its citation trace — is $0.10 per paid x402 read (or included with a premium API key) at GET /v1/briefings/public/{slug}. Saved private briefings on your own schedule are available to premium API keys at /v1/briefings.

Request

Response

{
  "answer": "Over the past two years, Williamson County's unemployment rate has held a narrow 3.2%–3.9% band ...",
  "citations": [
    {
      "tool": "search_indicators",
      "args": { "query": "unemployment" },
      "summary": "{\"data\":[{\"code\":\"LAUS_unemploymentRate\" ..."
    },
    {
      "tool": "get_insights",
      "args": { "indicator": "LAUS_unemploymentRate", "region": "48491" },
      "summary": "{\"facts\":[..."
    }
  ],
  "resolved": {
    "indicators": ["LAUS_unemploymentRate"],
    "regions": ["48491"],
    "window": "all"
  },
  "grounded": true,
  "truncated": false,
  "status": "ok",
  "meta": { "model": "...", "rounds": 4, "toolCalls": 5 }
}

Other outcomes:

• no_coverage — the catalog has nothing matching the question. Free.
• no_data — the catalog matched, but the tools returned nothing for your specific scope (for example, a region we don’t hold that series for).
• 503 — the ask engine is unavailable; the deterministic endpoints are unaffected.

truncated: true means a per-request ceiling ended the work early — the answer is grounded but partial, and usually means the question’s scope was too broad for one ask. Narrow the region, window, or subject and ask again.

Verifying an answer

Every citation’s args are replayable against the deterministic endpoints: call /v1/observations, /v1/insights, or /v1/signals with the same arguments and check the numbers yourself. That is the point of the trace — an ask answer is an index into data you can independently fetch.

MCP

The same capability is exposed as the ask tool on the hosted MCP server (POST /api/mcp). Agents that don’t know the indicator vocabulary should prefer ask; agents that do should use the typed tools directly.