Foresight API for agents

Agents can discover catalog data without credentials, use authenticated MCP tools for observations, or pay per observation request with x402.

MCP endpoint

The streamable HTTP MCP server is available at POST /api/mcp. It exposes search_indicators, list_sources, list_regions, get_observations, and get_latest.

{
  "mcpServers": {
    "creative-foresight": {
      "url": "https://api.creativeforesight.io/api/mcp",
      "headers": {
        "Authorization": "Bearer cf_live_..."
      }
    }
  }
}
curl -X POST "https://api.creativeforesight.io/api/mcp" \
  -H "Authorization: Bearer $CF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

x402 flow

  1. Call /v1/observations?indicator=UNRATE without an API key.
  2. The API returns HTTP 402 with accepted payment requirements.
  3. Submit the paid retry with an X-PAYMENT header.
  4. A settled paid response includes X-Payment-Settled: true.

Passthrough indicators are priced at $0.01. Creative Foresight cf:* derived indicators are priced at $0.05.

{
  "x402Version": 1,
  "error": "X-PAYMENT header is required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base-sepolia",
      "maxAmountRequired": "$0.01",
      "description": "Foresight API observations for UNRATE",
      "mimeType": "application/json",
      "payTo": "0x...",
      "outputSchema": {
        "input": {
          "type": "http",
          "method": "GET",
          "discoverable": true
        }
      }
    }
  ]
}

Settlement failures

If a paid retry reaches the facilitator but settlement fails, the API returns HTTP 502 with the standard error envelope and INTERNAL_ERROR.