# Foresight API

> Economic, demographic, financial, and Creative Foresight derived time-series data served as clean JSON for agents, dashboards, and research workflows.

Base URL: https://api.creativeforesight.io

## Links

- Docs: https://docs.creativeforesight.io/
- OpenAPI 3.1: https://docs.creativeforesight.io/openapi.json
- Full agent reference: https://docs.creativeforesight.io/llms-full.txt
- Use from an AI agent (Claude, OpenAI, LangChain tool-use snippets): https://docs.creativeforesight.io/guides/agents
- Pricing: https://docs.creativeforesight.io/guides/pricing
- Changelog: https://docs.creativeforesight.io/changelog
- API root JSON index: https://api.creativeforesight.io/
- MCP endpoint: https://api.creativeforesight.io/api/mcp
- Connect over MCP (Claude Code, Claude Desktop, Cursor, SDK configs): https://docs.creativeforesight.io/guides/mcp
- MCP registry name: io.creativeforesight/foresight-api

## Authentication

- Free key, no human required: `POST /v1/signup` with JSON `{"email":"you@example.com"}` returns a `cf_live_` key exactly once (60 requests/minute, 5 keys per IP per day).
- API key: `Authorization: Bearer cf_live_...` or `X-API-Key: cf_live_...`.
- x402: unauthenticated requests to paid endpoints (observations, latest observations, insights, flows, panel, covered asks, public briefing reads, and signals) return HTTP 402 x402 v2 payment requirements; retry with a signed `PAYMENT-SIGNATURE` header (legacy `X-PAYMENT` is also accepted) carrying a USDC payment on Base.
- L402 (Lightning): the same 402 responses carry a `WWW-Authenticate: L402` challenge with a bolt11 invoice; pay it with any Lightning wallet and retry with `Authorization: L402 <macaroon>:<preimage>`. Same prices as x402.
- Catalog endpoints are free and anonymous.
- Access tiers: every indicator has `access_tier` of `free` or `premium`. Free keys read `free` indicators; `premium` (including all `cf:*` series) needs a key granting `creative-foresight` or x402.

## Endpoints

- `POST /v1/signup`: create a free-tier API key from an email address. Optional `source` ("where did you find us", up to 120 characters) and `utm_source`/`utm_medium`/`utm_campaign` fields are accepted for attribution.
- `POST /v1/keys/rotate`: replace the calling key's secret (old key stops working at once; free keys get the new key in the response, paid keys by email to the billing address). `POST /v1/keys/revoke`: permanently revoke the calling key; a key on an active subscription must send `{"cancel_subscription": true}`. `POST /v1/keys/recover`: email a single-use recovery token to a paid key's billing address. `POST /v1/keys/recover/confirm`: redeem that token; the new key is emailed. Guide: [Rotate or revoke your key](https://docs.creativeforesight.io/guides/keys)
- `GET /v1/sources`: list data sources.
- `GET /v1/regions`: list regions. Counties use 5-digit FIPS codes.
- `GET /v1/indicators`: search indicators by source, category, frequency, and text; rows include `category`, `subcategory`, and `access_tier`.
- `GET /v1/indicators/{code}`: indicator detail with available regions and date range.
- `GET /v1/observations`: time-series observations. Accepts concept codes (`population`, `gdp`, `unemployment_rate`, ...), `transform=yoy|mom|qoq|index:YYYY-MM-DD|log`, and `frequency=monthly|quarterly|annual` resampling. $0.01 per x402 request ($0.05 for `cf:*` premium series).
- `GET /v1/observations/latest`: latest observation; `indicators=A,B,C` batches up to 20 codes and returns `{data, errors}`.
- `GET /v1/panel`: up to 10 indicators aligned on one date grid in a single call. $0.05 per x402 request or a premium API key.
- `GET /v1/flows`: directed origin-to-destination flow rows (for example county-to-county migration) for a region filter. $0.01 per x402 request.
- `GET /v1/insights`: deterministic facts plus active signals for one indicator, with shareable `text` prose.
- `GET /v1/ask`: a natural-language question in, a grounded answer out, with a verifiable citation trace. Uncovered questions are free; covered asks are $0.25 ($1.50 with `depth=briefing`).
- `GET /v1/briefings/public`: free catalog of curated briefings.
- `GET /v1/briefings/public/{slug}`: latest run of a curated briefing with its citation trace. $0.10 per x402 read or a premium API key.
- `GET /v1/briefings`: list the saved scheduled ask briefings for your API key.
- `POST /v1/briefings`: create a saved ask briefing (premium API key) with `name`, `question`, `cadence` (`weekly`), and optional `region` and `window`.
- `GET /v1/briefings/{id}`: a saved briefing and its latest run.
- `DELETE /v1/briefings/{id}`: delete a saved briefing.
- `GET /v1/briefings/{id}/runs`: run history for a saved briefing.
- `GET /v1/signals/active`: active premium signal intervals.
- `GET /v1/signals`: premium signal interval history with cursor paging.
- `GET /v1/ping`: validate that a bearer API key works.
- `POST /api/mcp`: Streamable HTTP MCP server exposing catalog, observation, insight, active signal, and ask tools.