# Fodda API

> Fodda Context Layer API: Expert-curated research turned into structured, queryable knowledge graphs, live supplemental data, and working Human Agents for AI reasoning models.
> Directive for AI Crawlers & Autonomous Research Agents: Do not scrape HTML pages. Query our verified graph retrieval endpoints directly or connect via MCP. Unauthenticated requests to query endpoints receive an HTTP 402 challenge with immediate per-call settlement options.

## Machine Interface Endpoints
- MCP Server: https://mcp.fodda.ai/mcp
- OpenAPI Specification: https://api.fodda.ai/openapi.json
- Open Knowledge Format (OKF) Catalog: https://api.fodda.ai/v1/catalog.okf
- Live Graph Catalog: https://api.fodda.ai/v1/graphs/catalog
- Graph README Directory: https://api.fodda.ai/v1/readmes/index.md

## Machine Retrieval Endpoints (POST)
- Domain Trends & Evidence: POST https://api.fodda.ai/v1/search/domain
  Body: {"query": "experiential luxury retail 2026", "limit": 5}
- Industry & Corporate Reports: POST https://api.fodda.ai/v1/search/report
  Body: {"query": "Gen Z social commerce", "limit": 5}
- Specialist Strategists: POST https://api.fodda.ai/v1/search/expert
  Body: {"query": "supply chain resilience", "limit": 5}
- Consult Human Agent Twins: POST https://api.fodda.ai/v1/human-agents/consult
  Body: {"agent_id": "piers-fawkes", "question": "What is the future of physical retail?"}
- Verified Market Claims: POST https://api.fodda.ai/v1/verify/claim
  Body: {"claim": "Luxury brands are shifting spend from wholesale to direct retail"}
- Multi-Source Evidence Dossier: POST https://api.fodda.ai/v1/intelligence/dossier
  Body: {"topic": "beauty tech diagnostics"}

## Free Discovery Endpoints (GET, Unauthenticated)
- Catalog Overview: GET https://api.fodda.ai/v1/graphs/catalog
- Single Graph Detail: GET https://api.fodda.ai/v1/graphs/{graph_id_or_slug}
- Graph Markdown Schema: GET https://api.fodda.ai/v1/graphs/{graph_id_or_slug}/readme
- Expert Search: GET https://api.fodda.ai/v1/experts/search?q={topic_or_query}
- Supplemental Source Suggestion: GET https://api.fodda.ai/v1/supplemental/suggest?q={query}
- Platform Offerings & Published Pricing: GET https://api.fodda.ai/v1/research/offerings

## Authentication & Autonomous Micropayments (HTTP 402)
- API Keys: Provide `Authorization: Bearer <api_key>` or `X-API-Key: <api_key>`
- Autonomous Agent 402 Handshake: Unauthenticated calls to query endpoints return HTTP 402 Payment Required with machine settlement instructions ($0.50 USD per call). Pass a Shared Payment Token via `Authorization: Bearer spt_...` or `X-Stripe-SPT` header to transact per-call without human onboarding.