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

• REST API: https://api.fodda.ai/v1 — Direct deterministic HTTP integration.
• MCP Server (HTTP): https://mcp.fodda.ai/mcp — Streamable HTTP for Claude, Cursor, and IDEs.
• Tokenized MCP: https://mcp.fodda.ai/c/<token> — Streamable transport with pre-authenticated connection token.
• ChatGPT MCP: https://mcp.fodda.ai/chatgpt — OAuth 2.1 authentication for custom ChatGPT Connectors.
• Copilot Studio MCP: https://mcp.fodda.ai/copilot — Curated 17-tool MCP profile for Microsoft Copilot Studio.
• A2A & Machine Settlement: Autonomous delegation via /.well-known/agent-card.json with HTTP 402 MPP challenge.

Authentication

• Account API Key: X-API-Key: sk_live_... or Authorization: Bearer sk_live_...
• Autonomous MPP / SPT: Unauthenticated requests return HTTP 402 with price challenge; settle via Authorization: Bearer spt_... (Direct REST only).
• 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

{
  "ok": true,
  "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: MPP Challenge for unauthenticated autonomous requests; returns price challenge and settlement address.
• 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.

Pricing & Quotas

Published USD rate: 50¢ per API call. Fodda Base plan includes 100 free calls every month. Daily burst ceiling without card on file: 50 calls/day. Commercial deliverables (Brand Intelligence $30.00, Deep Research $100.00) are billed at flat published rates.

Machine-Readable Discovery

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