{"openapi":"3.1.0","info":{"title":"Agent FAI Workload API","version":"1.0.0","description":"Embed the grounded FAI Engine in applications, automations, and Studio workloads.","contact":{"name":"FrootAI","url":"https://frootai.dev"}},"servers":[{"url":"https://frootai.dev/v1/agent","description":"FrootAI production gateway"}],"paths":{"/chat":{"post":{"operationId":"runAgentFai","summary":"Run Agent FAI","description":"Send Accept: text/event-stream to receive the grounded answer progressively. Valid personal API keys have no cumulative Agent FAI question or conversation cap; short-window abuse protection still applies.","security":[{"FaiApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","maxLength":8000},"threadId":{"type":"string","format":"uuid","nullable":true,"description":"Optional durable conversation identifier shared across Agent FAI surfaces."},"mode":{"type":"string","enum":["auto","answer","architecture","plan","review"],"default":"auto"},"capabilities":{"type":"object","properties":{"diagrams":{"type":"boolean","default":true},"citations":{"type":"boolean","default":true}}},"history":{"type":"array","maxItems":10,"items":{"type":"object","required":["role","content"],"properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string","maxLength":3000}}}}}}}}},"responses":{"200":{"description":"Grounded Agent FAI response with request correlation, usage, MCP activity, citations, and product-registry freshness metadata","headers":{"X-Agent-FAI-Allowance-Kind":{"schema":{"type":"string","enum":["unlimited"]},"description":"Confirms that this valid key has no cumulative Agent FAI chat cap."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentFaiResponse"}},"text/event-stream":{"schema":{"type":"string","description":"Sanitized SSE meta and content events, followed by done and [DONE] only after durable persistence; safe error events may use stream_upstream_error, stream_too_large, stream_incomplete, conversation_persistence_failed, or usage_event_persistence_failed."}}}},"400":{"description":"Invalid JSON request fields, history, capabilities, mode, or thread ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing, invalid, or revoked fai_live_ API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Browser origin is not approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Durable thread not found or not owned by this key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Message exceeds 8,000 characters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"415":{"description":"Content-Type is not application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"The short-window abuse-protection limit was reached; there is no cumulative question or conversation cap.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the short request window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"FAI Engine unavailable or invalid upstream response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Gateway or conversation persistence is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"ErrorResponse":{"type":"object","required":["error","requestId"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["gateway_not_configured","invalid_token","origin_denied","unsupported_media_type","invalid_json","request_too_large","invalid_message","message_too_long","invalid_mode","invalid_thread_id","invalid_history","invalid_capabilities","thread_not_found","conversation_store_unavailable","conversation_persistence_failed","usage_event_persistence_failed","rate_limited","agent_unavailable","agent_upstream_error","invalid_agent_response","stream_upstream_error","stream_too_large","stream_incomplete"]},"message":{"type":"string"}}},"requestId":{"type":"string"}}},"ProductRegistryMetadata":{"type":"object","required":["schemaVersion","updatedAt","digest","products"],"properties":{"schemaVersion":{"type":"string","example":"1.0.0"},"updatedAt":{"type":"string","format":"date","example":"2026-07-29"},"digest":{"type":"string","pattern":"^[a-f0-9]{64}$"},"products":{"type":"integer","minimum":1,"example":12}}},"AgentFaiResponse":{"type":"object","required":["reply","agent"],"properties":{"reply":{"type":"string"},"usage":{"type":"object","additionalProperties":true},"agent":{"type":"object","required":["requestId","version","grounding"],"properties":{"requestId":{"type":"string"},"version":{"type":"string"},"threadId":{"type":["string","null"],"format":"uuid"},"grounding":{"type":"object","properties":{"corpusSize":{"type":"integer","example":1017},"productRegistry":{"$ref":"#/components/schemas/ProductRegistryMetadata"},"sources":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}}}},"securitySchemes":{"FaiApiKey":{"type":"http","scheme":"bearer","bearerFormat":"fai_live_...","description":"Revocable personal API key created from your signed-in FrootAI account."}}}}