Quickstart

Use the human path when you want a reusable API key. Use the agent path when a model or tool runtime should discover the catalog, call MCP tools, or pay per request with x402.

Humans: get a key

Create a free-tier key, store it, then make the first call:


curl -X POST "https://api.creativeforesight.io/v1/signup" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

The response returns the raw cf_live_ key exactly once. Store it as CF_API_KEY, then call the observations endpoint:


curl "https://api.creativeforesight.io/v1/observations?indicator=UNRATE&limit=2" \
  -H "Authorization: Bearer $CF_API_KEY"

The response uses a stable { data, meta } envelope:


{
  "data": [
    {
      "date": "2026-05-01",
      "value": 4.2,
      "indicator": "UNRATE",
      "region": "US",
      "unit": "percent",
      "source": "fred",
      "source_updated_at": "2026-06-06T12:00:00.000Z",
      "is_preliminary": false,
      "revision": 0
    }
  ],
  "meta": {
    "indicator": "UNRATE",
    "region": "US",
    "unit": "percent",
    "total": 1,
    "limit": 2,
    "offset": 0
  }
}

JavaScript


const response = await fetch(
  'https://api.creativeforesight.io/v1/observations?indicator=UNRATE&limit=2',
  {
    headers: {
      Authorization: `Bearer ${process.env.CF_API_KEY}`,
    },
  },
)
 
if (!response.ok) {
  throw new Error(await response.text())
}
 
const body = await response.json()
for (const row of body.data) {
  console.log(row.date, row.value, row.revision, row.is_preliminary)
}

Python


import os
import requests
 
response = requests.get(
    "https://api.creativeforesight.io/v1/observations",
    params={"indicator": "UNRATE", "limit": 2},
    headers={"Authorization": f"Bearer {os.environ['CF_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
 
body = response.json()
for row in body["data"]:
    print(row["date"], row["value"], row["revision"], row["is_preliminary"])

Agents: MCP

The streamable HTTP MCP server is at https://api.creativeforesight.io/api/mcp. It exposes catalog tools, observation tools, and a question-answering tool:

Tool	Purpose
`search_indicators`	Find indicators by text, source, category, or frequency.
`list_sources`	List data providers and source metadata.
`list_regions`	Discover regions and filter by type or parent region.
`get_observations`	Fetch observation rows for an indicator.
`get_latest`	Fetch the latest observation for an indicator.
`get_insights`	Compute deterministic facts plus active signals for an indicator.
`get_active_signals`	List currently open Creative Foresight signal intervals.
`ask`	Answer a plain-language question with a citation trace.

Catalog tools work without a key. For ready-made Claude Code, Claude Desktop, and Cursor configs, see Connect over MCP. A client that accepts a URL and headers takes:


{
  "mcpServers": {
    "foresight": {
      "url": "https://api.creativeforesight.io/api/mcp",
      "headers": {
        "Authorization": "Bearer cf_live_..."
      }
    }
  }
}

Manual discovery call:


curl -X POST "https://api.creativeforesight.io/api/mcp" \
  -H "Authorization: Bearer $CF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Agents: pay per request

Observation, insight, and signal endpoints also support anonymous per-request payment — USDC via x402, or Lightning via L402.

Call /v1/observations, /v1/observations/latest, /v1/insights, /v1/signals, or /v1/signals/active without an API key.
Read the HTTP 402 payment requirements in the response (x402 in the body, a Lightning invoice in the WWW-Authenticate header).
Pay on either rail.
Retry with X-PAYMENT (x402) or Authorization: L402 … (Lightning).


curl -i "https://api.creativeforesight.io/v1/observations/latest?indicator=UNRATE"
 
curl "https://api.creativeforesight.io/v1/observations/latest?indicator=UNRATE" \
  -H "X-PAYMENT: BASE64_PAYMENT_PAYLOAD"

Paid retries that settle successfully include X-Payment-Settled: true.

See Pay per request for both rails in full — the runnable x402 client, the Lightning flow, the payable endpoints and prices, and discovery.