{ "openapi": "3.1.0", "info": { "title": "Fodda Public API", "description": "The curated public surface of the Fodda API. This spec includes only the documented, stable endpoints available to external developers. Internal, admin, and pricing-configuration endpoints are excluded.", "version": "1.7.0", "x-generated-at": "2026-11-11T21:38:02.801Z" }, "servers": [ { "url": "https://api.fodda.ai" } ], "paths": { "/v1/health": { "get": { "summary": "V1 API health check", "description": "Check service availability.", "operationId": "v1_api_health_check", "x-fodda-price-usd": 0, "x-fodda-billing-type": "free", "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "security": [] } }, "/v1/graph-slice": { "get": { "summary": "Graph slice JSON-LD", "description": "Get semantic Schema.org slice of a graph.", "operationId": "graph_slice_json_ld", "x-fodda-price-usd": 0, "x-fodda-billing-type": "free", "parameters": [ { "name": "graph_id", "in": "query", "schema": { "type": "string" } }, { "name": "source_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "security": [] } }, "/v1/graphs/catalog": { "get": { "summary": "Graph registry catalog", "description": "Get all registry graphs.", "operationId": "graph_registry_catalog", "x-fodda-price-usd": 0, "x-fodda-billing-type": "free", "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "security": [] } }, "/v1/graphs/{graph_id}/search": { "post": { "summary": "Search knowledge graph", "description": "Search trends and signals semantically.", "operationId": "search_knowledge_graph", "x-fodda-price-usd": 7.5, "x-fodda-billing-type": "topic_research", "parameters": [ { "name": "graph_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "security": [ { "apiKey": [] }, { "stripeSPT": [] } ] } }, "/v1/graphs/{graph_id}/evidence": { "post": { "summary": "Get evidence", "description": "Get source articles and signals for a trend.", "operationId": "get_evidence", "x-fodda-price-usd": 2.5, "x-fodda-billing-type": "standalone_evidence", "parameters": [ { "name": "graph_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "security": [ { "apiKey": [] }, { "stripeSPT": [] } ] } }, "/v1/graphs/{graph_id}/statistics": { "get": { "summary": "Search statistics", "description": "Get metrics and expert quotes.", "operationId": "search_statistics", "x-fodda-price-usd": 2.5, "x-fodda-billing-type": "standalone_statistics", "parameters": [ { "name": "graph_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "security": [ { "apiKey": [] }, { "stripeSPT": [] } ] } }, "/v1/search/domain": { "post": { "summary": "Domain Intelligence parallel search", "description": "Search across all PSFK domain graphs.", "operationId": "domain_intelligence_parallel_search", "x-fodda-price-usd": 2.5, "x-fodda-billing-type": "domain_intelligence", "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "security": [ { "apiKey": [] }, { "stripeSPT": [] } ] } }, "/v1/search/report": { "post": { "summary": "Report Intelligence parallel search", "description": "Search across industry research report graphs.", "operationId": "report_intelligence_parallel_search", "x-fodda-price-usd": 2.5, "x-fodda-billing-type": "report_intelligence", "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "security": [ { "apiKey": [] }, { "stripeSPT": [] } ] } }, "/v1/analysts": { "get": { "summary": "List synthetic expert analysts", "description": "Retrieve registered expert analyst personas.", "operationId": "list_synthetic_expert_analysts", "x-fodda-price-usd": 0, "x-fodda-billing-type": "free", "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "security": [] } }, "/v1/analysts/consult": { "post": { "summary": "Consult analyst turn", "description": "Ask a synthetic expert analyst a question.", "operationId": "consult_analyst_turn", "x-fodda-price-usd": 2.5, "x-fodda-billing-type": "expert_agent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "analyst_id", "query" ], "properties": { "analyst_id": { "type": "string" }, "query": { "type": "string" } } } } } }, "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "security": [ { "apiKey": [] }, { "stripeSPT": [] } ] } }, "/v1/supplemental/context": { "post": { "summary": "Unified Supplemental Context", "description": "Unified access to FRED, Census, PubMed, Google Trends, etc. in parallel.", "operationId": "unified_supplemental_context", "x-fodda-price-usd": 2.5, "x-fodda-billing-type": "standalone_supplemental", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "Search query or research topic" }, "domain": { "type": "string", "description": "Optional domain hint (retail, beauty, fashion, etc.)" }, "brands": { "type": "array", "items": { "type": "string" }, "description": "Brand names for product lookups" }, "graph_ids": { "type": "array", "items": { "type": "string" }, "description": "Graph IDs from prior search for domain inference" }, "sources": { "type": "array", "items": { "type": "string" }, "description": "Explicit source IDs to execute" }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Category filters" }, "geo": { "type": "string", "description": "Country code hint (e.g. BR, TH, GB)" }, "geography": { "type": "string", "description": "Country code or country name (e.g. BR, Brazil, United Kingdom)" }, "location": { "type": "string", "description": "Location hint" } } } } } }, "responses": { "200": { "description": "Unified supplemental data payload with source coverage telemetry", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "domain": { "type": "string" }, "sources_queried": { "type": "number" }, "sources_returned": { "type": "number" }, "sources_succeeded": { "type": "array", "items": { "type": "string" } }, "sources_failed": { "type": "array", "items": { "type": "object" } }, "sources_skipped": { "type": "array", "items": { "type": "object" } }, "source_coverage": { "type": "object", "properties": { "considered": { "type": "number" }, "selected": { "type": "number" }, "attempted": { "type": "number" }, "returned": { "type": "number" }, "dropped": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "stage": { "type": "string", "enum": [ "routing", "fetch", "consolidate", "coherence" ] }, "reason": { "type": "string" } } } }, "query_interpreted_as": { "type": "string" }, "domain_inference": { "type": "string" }, "classifier_path": { "type": "string", "enum": [ "regex", "gemini", "fallback" ] }, "need_adjacency_applied": { "type": "array", "items": { "type": "string" } } } }, "demand_signals": { "type": "object" }, "economic_context": { "type": "object" }, "market_data": { "type": "object" }, "financial_reporting": { "type": "object" }, "research_signals": { "type": "object" }, "demographic_context": { "type": "object" }, "_meta": { "type": "object" } } } } } } }, "security": [ { "apiKey": [] }, { "stripeSPT": [] } ] } }, "/v1/supplemental/suggest": { "get": { "summary": "Supplemental: suggest", "description": "Supplemental data snapshot endpoint for suggest.", "operationId": "supplemental__suggest", "x-fodda-price-usd": 2.5, "x-fodda-billing-type": "standalone_supplemental", "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "security": [ { "apiKey": [] }, { "stripeSPT": [] } ] } }, "/v1/catalog.okf": { "get": { "summary": "Download Open Knowledge Format bundle", "description": "Full machine-readable Open Knowledge Format bundle (.tar.gz or JSON format) mapping the 250+ knowledge graph catalog for autonomous agents.", "operationId": "get_catalog_okf", "x-fodda-price-usd": 0, "x-fodda-billing-type": "free", "parameters": [ { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "tar.gz", "json" ], "default": "tar.gz" }, "description": "Output format: tar.gz (default) or json" } ], "responses": { "200": { "description": "OKF bundle payload or archive", "content": { "application/gzip": {}, "application/json": { "schema": { "type": "object" } } } } }, "security": [] } }, "/v1/experts/search": { "get": { "summary": "Search expert and analyst roster", "description": "Search 4,150+ specialist roster by query, returning ranked candidate experts with match rationale.", "operationId": "search_experts_roster", "x-fodda-price-usd": 0, "x-fodda-billing-type": "free", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query or problem statement" }, { "name": "class", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "human", "classic", "synthetic" ] }, "description": "Filter by expert classification" } ], "responses": { "200": { "description": "Candidate expert matches", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "security": [] } }, "/v1/human-agents/consult": { "post": { "summary": "Consult Human Agent digital twin", "description": "Consult an authorized living industry figure's digital twin with grounded graph evidence.", "operationId": "consult_human_agent", "x-fodda-price-usd": 2.5, "x-fodda-billing-type": "human_agent_consult", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "analyst_id", "query" ], "properties": { "analyst_id": { "type": "string", "description": "Human agent ID (e.g. piers-fawkes, ben-dietz)" }, "query": { "type": "string", "description": "Question or research brief" }, "session_id": { "type": "string", "description": "Optional thread ID to continue multi-turn consultation" }, "deep": { "type": "boolean", "description": "Trigger deep background homework mode" } } } } } }, "responses": { "200": { "description": "Consultation answer with sources and next moves", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "security": [ { "apiKey": [] }, { "stripeSPT": [] } ] } }, "/v1/brand-intelligence/{brand}": { "post": { "summary": "Get Brand Intelligence profile", "description": "Consolidated brand signals dashboard and cross-graph footprint.", "operationId": "get_brand_intelligence_profile_by_brand", "x-fodda-price-usd": 10, "x-fodda-billing-type": "brand_intelligence", "parameters": [ { "name": "brand", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Brand name or ticker" } ], "responses": { "200": { "description": "Success response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "security": [ { "apiKey": [] }, { "stripeSPT": [] } ] } }, "/v1/verify/claim": { "post": { "summary": "Verify factual claim against graph evidence", "description": "5-gate anti-hallucination factual claim verification with graph corroboration and structured verdict.", "operationId": "verify_claim_evidence", "x-fodda-price-usd": 2.5, "x-fodda-billing-type": "human_agent_consult", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "claim" ], "properties": { "claim": { "type": "string", "description": "The assertion, claim, or hypothesis to verify" }, "analyst_id": { "type": "string", "description": "Optional specific expert to evaluate the claim" } } } } } }, "responses": { "200": { "description": "Verification result with verdict, confidence, and primary evidence citations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "security": [ { "apiKey": [] }, { "stripeSPT": [] } ] } }, "/v1/intelligence/dossier": { "post": { "summary": "Assemble certified multi-source evidence dossier", "description": "Assemble certified multi-source evidence dossier with optional editorial briefing.", "operationId": "assemble_intelligence_dossier", "x-fodda-price-usd": 10, "x-fodda-billing-type": "topic_research", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "topic" ], "properties": { "topic": { "type": "string", "description": "Topic or brand for dossier assembly" }, "graph_ids": { "type": "array", "items": { "type": "string" }, "description": "Target knowledge graphs" }, "include_briefing": { "type": "boolean", "description": "Whether to include an executive editorial narrative" } } } } } }, "responses": { "200": { "description": "Certified evidence dossier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "security": [ { "apiKey": [] }, { "stripeSPT": [] } ] } } }, "components": { "schemas": { "Graph": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "curator": { "type": "string" }, "domain": { "type": "string" } } }, "ApiResponse": { "type": "object", "properties": { "ok": { "type": "boolean" }, "requestId": { "type": "string" }, "schema_version": { "type": "string" }, "search_path": { "type": "string" }, "deterministic": { "type": "boolean" }, "dataStatus": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "rowId": { "type": "string" }, "rowName": { "type": "string" }, "rowSummary": { "type": "string" }, "_score": { "type": "number" } } } }, "meta": { "type": "object", "properties": { "decision": { "type": "string" }, "usage": { "type": "object", "properties": { "total_billable_units": { "type": "integer" } } } } } } } }, "securitySchemes": { "apiKey": { "type": "apiKey", "name": "X-API-Key", "in": "header", "description": "Required for all endpoints unless marked public." }, "stripeSPT": { "type": "http", "scheme": "bearer", "description": "Stripe Shared Payment Token (MPP). Pass an SPT obtained from Stripe Link via Authorization: Bearer spt_xxx." } } } }