Fodda API & MCP — Expert Intelligence for AI Systems

Core API Surface & Machine Contract

This reference documents Fodda's Core API Families. For the exhaustive, machine-readable specification of all 150+ platform operations, parameter constraints, and schemas, inspect the Fodda OpenAPI 3.1 Specification.

Connection Methods

• Sign-in (OAuth) [Recommended Default]: https://mcp.fodda.ai/mcp — For modern clients supporting OAuth (Claude Desktop, ChatGPT, Copilot Studio, Perplexity). Sign in with your Fodda account when prompted.
• Connection Token [Tokenized URL]: https://mcp.fodda.ai/c/<token> — For clients without OAuth or custom header support (Notion, legacy tools, headless IDEs).
• API Key [Developers & Headers]: https://api.fodda.ai/v1 — Direct deterministic HTTP integration for web apps, Cursor, Claude Code, and backend services via X-API-Key or Authorization: Bearer sk_live_....
• Autonomous Agent Wallet [Base L2 / Zero-Account]: https://api.fodda.ai/v1 — Autonomous multi-agent swarms with zero account signup. Sends unauthenticated request → receives HTTP 402 challenge → settles USDC on Base network → redeems via Authorization: Bearer <tx_hash>.

Authentication

• Account API Key: X-API-Key: sk_live_... or Authorization: Bearer sk_live_...
• Autonomous Agent Settlement: Authorization: Bearer <tx_hash_or_token> — Autonomous Agent Settlement via Base L2 (USDC) or Payment Token upon HTTP 402 challenge.
• Enterprise OIDC: Authorization: Bearer <OIDC_JWT>
• Private Connection Token: https://mcp.fodda.ai/c/<token> for header-incapable clients (treat the complete URL as a private secret).

Quickstart: Search a Knowledge Graph

Example request querying the Retail knowledge graph for AI shopping agent trends:

cURL

curl -X POST "https://api.fodda.ai/v1/graphs/retail/search" \
  -H "Authorization: Bearer $FODDA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How are AI shopping agents changing retail checkout?",
    "limit": 5
  }'

Python

import os, requests

res = requests.post(
    "https://api.fodda.ai/v1/graphs/retail/search",
    headers={"Authorization": f"Bearer {os.environ['FODDA_TOKEN']}", "Content-Type": "application/json"},
    json={"query": "How are AI shopping agents changing retail checkout?", "limit": 5},
    timeout=30
)
res.raise_for_status()
print(res.json())

JavaScript

const res = await fetch("https://api.fodda.ai/v1/graphs/retail/search", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.FODDA_TOKEN,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ query: "How are AI shopping agents changing retail checkout?", limit: 5 })
});
const data = await res.json();
console.log(data);

Representative Response JSON

{
  "dataStatus": "TREND_MATCH",
  "meta": {
    "query": "How are AI shopping agents changing retail checkout?",
    "graph_id": "retail",
    "decision": "ANSWER",
    "execution_time_ms": 142
  },
  "rows": [
    {
      "trend_id": "trend-agentic-checkout-602",
      "name": "Autonomous Agentic Commerce",
      "summary": "AI agents increasingly execute end-to-end shopping transactions, bypassing traditional web front-ends.",
      "evidence": [
        {
          "article_id": "art-9481",
          "title": "Retail AI Protocol Benchmarks",
          "source_url": "https://psfk.com/2026/08/retail-ai-benchmarks.html",
          "published_at": "2026-08-14"
        }
      ]
    }
  ]
}

Core Endpoints Summary

Operational Error Contracts

All API errors return a standard JSON envelope with a machine-readable code, clear message, and correlation request ID:

{
  "error": {
    "code": "invalid_parameter",
    "message": "The specified graph_id 'unknown_graph' was not found in the active catalog.",
    "request_id": "req_8f1a92bc4e02",
    "retryable": false
  }
}

• 400 Bad Request: Invalid parameter, malformed JSON, or missing required field (e.g. INVALID_ARGUMENT).
• 401 Unauthorized: Missing or invalid API key or connection token.
• 402 Payment Required: Autonomous Agent Settlement challenge for unauthenticated requests; returns dynamic rate and Base L2 settlement requirements.
• 404 Not Found: Graph ID, node ID, or analyst name not found in the active catalog.
• 429 Rate Limit Exceeded: Request ceiling reached. Emits Retry-After header with backoff seconds.
• 500 Server Error: Transient upstream or database error. Client should retry with exponential jitter.

Data Handling, Privacy & Retention

In accordance with Fodda's Compliance Dossier: query text is retained for 12 months solely for billing reconciliation and telemetry, after which it is purged. Result text is never retained. Client prompts and responses are never used for model training. Contractual zero-retention query logging is available for enterprise tiers.

Dynamic Pricing Discovery

Airtable is the single source of truth for pricing. Query rates, subscription tiers, and monthly allowances are served dynamically via public discovery endpoints: GET /v1/pricing/plans and GET /v1/pricing/query-types. Autonomous agent requests receive dynamic per-call pricing and Base L2 settlement requirements in the HTTP 402 Payment Required challenge envelope.

Machine-Readable Discovery

• OpenAPI 3.1 Specification
• A2A Agent Card
• MCP Manifest
• llms.txt
• llms-full.txt
• catalog.okf