API Reference
The v1 API exposes anonymous catalog routes, self-serve free-tier signup, and API-key or x402-paid observation, insight, and signal routes.
Contract
Use the OpenAPI document for generated clients, schema validation, and endpoint discovery:
OpenAPI JSON
OpenAPI 3.1 contract for the public Foresight API read surface.
LLM Reference
Concatenated docs for agents that prefer a plain-text reference.
Authentication
Catalog endpoints are anonymous. POST /v1/signup issues a free-tier API key. Observation, insight, and signal endpoints accept either an API key or an x402 payment.
curl "https://api.creativeforesight.io/v1/observations?indicator=UNRATE" \
-H "Authorization: Bearer $CF_API_KEY"API keys can be sent as Authorization: Bearer cf_live_... or X-API-Key: cf_live_....
Endpoints
| Endpoint | Auth | Description |
|---|---|---|
POST /v1/signup | Anonymous | Create a free-tier API key. |
GET /v1/sources | Anonymous | List data sources. |
GET /v1/indicators | Anonymous | Search and page through indicators. |
GET /v1/indicators/{code} | Anonymous | Fetch indicator detail by code. |
GET /v1/regions | Anonymous | List regions and filter by type or parent. |
GET /v1/observations | API key or x402 | List observations for an indicator. |
GET /v1/observations/latest | API key or x402 | Fetch the latest observation for an indicator. |
GET /v1/insights | API key or x402 | Compute deterministic facts and active signals for an indicator. |
GET /v1/signals | API key or x402 | List signal interval history. |
GET /v1/signals/active | API key or x402 | List currently open signal intervals. |
GET /v1/ping | API key | Validate bearer API key connectivity. |
Response conventions
Successful list and detail responses use { "data": ..., "meta": ... } when pagination or query metadata is available. Errors use { "error": { "code": "...", "message": "...", "details": ... } }.