{"openapi":"3.1.0","info":{"title":"AlpineDataWorks.AI Intelligence Object API","version":"0.3.0","description":"155 intelligence objects · built from over 2,700 data feeds. REST + MCP API serving the full AlpineDataWorks.AI product registry. Agent-callable intelligence objects spanning crypto, macro, DeFi, real estate, energy, news, supply chain, AI ecosystem, geographic health, source quality, and actuarial/risk domains.","contact":{"name":"AlpineDataWorks.AI","url":"https://www.alpinedataworks.com"}},"servers":[{"url":"https://api.alpinedataworks.com","description":"Production"},{"url":"http://localhost:8787","description":"Local dev (wrangler dev)"}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"Public demo key: adw_free_demo (Free tier). Gold/Platinum require an issued API key. Production: SHA-256 hashed keys stored in Cloudflare KV."}},"schemas":{"Driver":{"type":"object","required":["factor","contribution"],"properties":{"factor":{"type":"string","description":"Named driver of the score"},"contribution":{"oneOf":[{"type":"number"},{"type":"string"}],"description":"Numeric weight or label contribution"}}},"IntelligenceObject":{"type":"object","description":"Alpine Intelligence Object Manifest (IOM) v0.1. Field depth depends on caller tier: Free (score/trend/freshness only), Gold (+drivers/confidence/history endpoint), Platinum (all fields).","required":["product_id","entity","score","confidence","top_drivers","methodology_version","freshness"],"properties":{"product_id":{"type":"string","example":"ADW-001"},"entity":{"type":"string","example":"BTC"},"score":{"oneOf":[{"type":"number"},{"type":"string"}],"description":"Headline metric"},"trend":{"type":"string","example":"bullish","description":"Direction vs prior period"},"confidence":{"type":"number","minimum":0,"maximum":1,"example":0.85},"top_drivers":{"type":"array","items":{"$ref":"#/components/schemas/Driver"},"description":"Ranked factors explaining the score (Gold+ only)"},"prediction_horizon":{"type":"string","example":"7d"},"recommended_use":{"type":"string","example":"Short-term trading signal"},"methodology_version":{"type":"string","example":"v2.1"},"freshness":{"type":"string","format":"date-time","example":"2026-06-19T14:00:00Z"},"coverage":{"type":"string","example":"Global Spot & Derivatives"},"source_lineage":{"type":"array","items":{"type":"string"},"example":["Alternative.me","CoinGecko"]},"allowed_use":{"type":"string","example":"evaluation, commercial"}},"additionalProperties":true},"ProductSummary":{"type":"object","properties":{"product_id":{"type":"string","example":"ADW-001"},"name":{"type":"string","example":"Crypto Market Sentiment & Volatility Index"},"domain":{"type":"string","example":"Market/Crypto"},"type":{"type":"string","enum":["index","score","driver","summary","forecast"]},"tier":{"type":"string","enum":["Free","Gold","Platinum"],"description":"Minimum subscription tier required"},"agent_question":{"type":"string"},"refresh":{"type":"string","example":"hourly"},"access":{"type":"object","properties":{"rest":{"type":"string"},"mcp_tool":{"type":"string"}}}}},"HistoryPoint":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"2026-05-21"},"score":{"type":"number","example":0.71}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["UNAUTHORIZED","TIER_FORBIDDEN","NOT_FOUND","BAD_REQUEST","RATE_LIMITED","INTERNAL_ERROR"]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true},"request_id":{"type":"string","example":"req_a1b2c3d4"}}}}}}},"security":[],"paths":{"/v1/catalog":{"get":{"summary":"Discover the full catalog (paginated, metered)","operationId":"getCatalog","tags":["Catalog"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"offset","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"category","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Catalog entries + categories","content":{"application/json":{}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/geohealth/{zip}":{"get":{"summary":"GeoHealth risk index for a US ZIP / ZCTA","operationId":"getGeoHealth","tags":["Products"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"zip","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"GeoHealth IOM object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelligenceObject"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"ZIP/ZCTA not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/intelligence/bundle":{"post":{"summary":"Fetch multiple IOM objects in one call (metered by sum of per-product cost)","operationId":"getIntelligenceBundle","tags":["Products"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"}}},"required":["ids"]}}}},"responses":{"200":{"description":"Array of tier-projected IOM objects","content":{"application/json":{}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/validation":{"get":{"summary":"Validation-gate ledger — which metrics beat a naive baseline","operationId":"getValidation","tags":["Catalog"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Validation records","content":{"application/json":{}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/health":{"get":{"summary":"API health check","operationId":"getHealth","tags":["Public"],"responses":{"200":{"description":"Service is up","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"time":{"type":"string","format":"date-time"},"version":{"type":"string"},"products":{"type":"integer","example":138}}}}}}}}},"/v1/sources/health":{"get":{"summary":"Upstream source health map","operationId":"getSourcesHealth","tags":["Public"],"responses":{"200":{"description":"Source API health statuses","content":{"application/json":{"schema":{"type":"object","properties":{"sources":{"type":"array","items":{"type":"object"}},"checked_at":{"type":"string","format":"date-time"}}}}}}}}},"/v1/schemas":{"get":{"summary":"IOM JSON Schema","operationId":"getSchemas","tags":["Public"],"responses":{"200":{"description":"The IOM contract schema","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/validate":{"post":{"summary":"Validate an IOM object","operationId":"validateIOM","tags":["Public"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Validation result","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"errors":{"type":"array","items":{"type":"string"}}}}}}}}}},"/openapi.json":{"get":{"summary":"This OpenAPI specification","operationId":"getOpenAPI","tags":["Public"],"responses":{"200":{"description":"OpenAPI 3.1 spec document"}}}},"/v1/products":{"get":{"summary":"List all intelligence products","operationId":"listProducts","tags":["Products"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"domain","in":"query","schema":{"type":"string"},"description":"Filter by domain (partial match)"},{"name":"tier","in":"query","schema":{"type":"string","enum":["Free","Gold","Platinum"]}},{"name":"type","in":"query","schema":{"type":"string","enum":["index","score","driver","summary","forecast"]}}],"responses":{"200":{"description":"Product list","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/ProductSummary"}},"total":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/products/{id}":{"get":{"summary":"Get a single IOM object (tier-projected)","operationId":"getProduct","tags":["Products"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"IOM object (fields gated by tier)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelligenceObject"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/intelligence/{id}":{"get":{"summary":"Alias for GET /v1/products/{id} (canonical registry path)","operationId":"getIntelligence","tags":["Products"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"IOM object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntelligenceObject"}}}}}}},"/v1/products/batch":{"post":{"summary":"Fetch multiple IOMs in one call","operationId":"batchProducts","tags":["Products"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"},"maxItems":100,"description":"Max 20 for Free/Gold; max 100 for Platinum"}}}}}},"responses":{"200":{"description":"Array of IOM objects","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/IntelligenceObject"}}}}}}}}}},"/v1/products/{id}/drivers":{"get":{"summary":"Get top drivers for a product (Gold+ only)","operationId":"getDrivers","tags":["Products"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Driver decomposition","content":{"application/json":{"schema":{"type":"object","properties":{"product_id":{"type":"string"},"top_drivers":{"type":"array","items":{"$ref":"#/components/schemas/Driver"}}}}}}},"403":{"description":"Paid tier (Gold or Platinum) required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/products/{id}/history":{"get":{"summary":"30-day score history (Gold+ only)","operationId":"getHistory","tags":["Products"],"security":[{"BearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deterministic demo history series","content":{"application/json":{"schema":{"type":"object","properties":{"product_id":{"type":"string"},"points":{"type":"array","items":{"$ref":"#/components/schemas/HistoryPoint"}},"note":{"type":"string"}}}}}},"403":{"description":"Gold tier required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/account/me":{"get":{"summary":"Authenticated account snapshot (session OR bearer key)","operationId":"getAccountMe","tags":["Account"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Account snapshot","content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"tier":{"type":"string","enum":["Free","Gold","Platinum"]},"plan":{"type":"string"},"verified":{"type":"boolean"},"status":{"type":"string","example":"active"},"credits":{"type":["number","null"]}}}}}},"401":{"description":"Session or valid API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/account/usage":{"get":{"summary":"Credit-spend dashboard: balance, burn rate, daily burn, top products, forecast","operationId":"getAccountUsage","tags":["Account"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Usage summary (excluded from token meter)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Session or valid API key required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Account not active or email unverified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/account/credits":{"get":{"summary":"Current credit balance + recent transactions (session required)","operationId":"getAccountCredits","tags":["Account"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Balance + recent transactions","content":{"application/json":{"schema":{"type":"object","properties":{"balance":{"type":"number"},"recent_transactions":{"type":"array","items":{"type":"object","additionalProperties":true}},"request_id":{"type":"string"}}}}}},"401":{"description":"Session required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/billing/status":{"get":{"summary":"Current plan + subscription status (session required)","operationId":"getBillingStatus","tags":["Billing"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Plan + subscription status","content":{"application/json":{"schema":{"type":"object","properties":{"tier":{"type":"string","enum":["Free","Gold","Platinum"]},"subscription_status":{"type":"string","example":"active"}}}}}},"401":{"description":"Session required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/billing/checkout":{"post":{"summary":"Create a Stripe Checkout Session for a paid tier (session required)","operationId":"createBillingCheckout","tags":["Billing"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tier"],"properties":{"tier":{"type":"string","enum":["Gold","Platinum"]}}}}}},"responses":{"200":{"description":"Checkout URL","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"stub":{"type":"boolean"}}}}}},"400":{"description":"Invalid or missing tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Session required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Account not active or email unverified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/billing/credits/checkout":{"post":{"summary":"Buy a credit pack (session required); JSON returns URL, form-post redirects","operationId":"createCreditCheckout","tags":["Billing"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pack"],"properties":{"pack":{"type":"string","enum":["starter","builder","pro","scale"]}}}}}},"responses":{"200":{"description":"Checkout URL (JSON request)","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"stub":{"type":"boolean"}}}}}},"302":{"description":"Redirect to Stripe Checkout (form-post request)"},"400":{"description":"Invalid pack","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Account not active or email unverified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/billing/portal":{"get":{"summary":"Create a Stripe Billing Portal session (session required)","operationId":"getBillingPortal","tags":["Billing"],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Billing portal URL","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"stub":{"type":"boolean"}}}}}},"401":{"description":"Session required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Account not active or email unverified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No Stripe customer found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/mcp":{"post":{"summary":"MCP JSON-RPC 2.0 endpoint","operationId":"mcpRpc","tags":["MCP"],"description":"Model Context Protocol server. Supports: initialize, tools/list, tools/call. Each live product is exposed as an MCP tool (e.g. adw.adw_001 … adw.adw_382; 145 tools advertised).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method","id"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"method":{"type":"string"},"id":{"oneOf":[{"type":"string"},{"type":"integer"}]},"params":{"type":"object"}}}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"tags":[{"name":"Public","description":"No authentication required"},{"name":"Products","description":"Intelligence object endpoints (Bearer auth required)"},{"name":"Account","description":"Account snapshot, usage, and credit balance (session or bearer key)"},{"name":"Billing","description":"Stripe checkout, credit packs, billing portal, and status (session required)"},{"name":"MCP","description":"Model Context Protocol server for agent access"}]}