{"openapi":"3.1.0","info":{"title":"Fortune OS API","version":"v1","description":"The public API surfaces of Fortune OS: the Model Context Protocol server for AI agents and the versioned REST endpoints. Every operation is generated from the Zod schema that validates it."},"servers":[{"url":"https://app.fortuneos.ai"}],"components":{"securitySchemes":{"session":{"type":"apiKey","in":"cookie","name":"better-auth.session_token"},"secureSession":{"type":"apiKey","in":"cookie","name":"__Secure-better-auth.session_token"},"sessionCookie":{"type":"apiKey","in":"cookie","name":"__Secure-better-auth.session_token","description":"The signed-in session BetterAuth issues on sign-in."},"apiKey":{"type":"http","scheme":"bearer","description":"A merchant-minted key from Settings → Profile → MCP tokens, prefixed fos_. Read-only unless the key carries a catalog availability write grant."},"mcpOAuth":{"type":"oauth2","description":"The MCP connector sign-in flow; discovery lives at /.well-known/oauth-authorization-server.","flows":{"authorizationCode":{"authorizationUrl":"https://app.fortuneos.ai/api/auth/oauth2/authorize","tokenUrl":"https://app.fortuneos.ai/api/auth/oauth2/token","scopes":{}}}}}},"paths":{"/api/mcp/v1":{"post":{"operationId":"callMcp","summary":"Send one Model Context Protocol request","description":"JSON-RPC 2.0 over streamable HTTP, stateless per request: tools/list publishes the typed tool contract and tools/call invokes business_context, describe_business_data, query_sales, read_business_records, read_merchant_data, read_catalog or set_catalog_availability. Every call authorizes the credential, the live memberships and the named business scope again.","security":[{"apiKey":[]},{"mcpOAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"anyOf":[{"type":"string"},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"method":{"type":"string"},"params":{"type":"object","properties":{"_meta":{"type":"object","properties":{"progressToken":{"anyOf":[{"type":"string"},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"io.modelcontextprotocol/related-task":{"type":"object","properties":{"taskId":{"type":"string"}},"required":["taskId"]}},"additionalProperties":{}}},"additionalProperties":{}}},"required":["jsonrpc","id","method"],"additionalProperties":false}}}},"responses":{"200":{"description":"The JSON-RPC result or error for the request id.","content":{"application/json":{"schema":{"oneOf":[{"anyOf":[{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"anyOf":[{"type":"string"},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"result":{"type":"object","properties":{"_meta":{"type":"object","properties":{"progressToken":{"anyOf":[{"type":"string"},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"io.modelcontextprotocol/related-task":{"type":"object","properties":{"taskId":{"type":"string"}},"required":["taskId"]}},"additionalProperties":{}}},"additionalProperties":{}}},"required":["jsonrpc","id","result"],"additionalProperties":false},{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"anyOf":[{"type":"string"},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"error":{"type":"object","properties":{"code":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"message":{"type":"string"},"data":{}},"required":["code","message"]}},"required":["jsonrpc","error"],"additionalProperties":false}]},{"type":"object","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"anyOf":[{"type":"string"},{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}]},"error":{"type":"object","properties":{"code":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"message":{"type":"string"},"data":{}},"required":["code","message"]}},"required":["jsonrpc","error"],"additionalProperties":false}]}}}},"401":{"description":"Missing or invalid bearer; WWW-Authenticate names the protected-resource metadata.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"405":{"description":"Only POST is served; the server opens no SSE stream.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/exports/v1/{report}/{format}":{"get":{"operationId":"downloadReportExport","summary":"Download an authorized merchant report","description":"Requires report:read and live venue authority. Custom periods require ordered from/to dates within the configured maximum span. The format selects CSV or PDF; locale affects PDF labels only.","security":[{"session":[]},{"secureSession":[]}],"parameters":[{"name":"report","in":"path","required":true,"schema":{"type":"string","enum":["summary","items","locations","employees","paymentTypes","refunds","orderDetails"]}},{"name":"format","in":"path","required":true,"schema":{"type":"string","enum":["csv","pdf"]}},{"name":"locationId","in":"query","required":true,"style":"form","explode":true,"schema":{"type":"string","minLength":1}},{"name":"period","in":"query","required":false,"style":"form","explode":true,"schema":{"default":"thisMonth","type":"string","enum":["today","yesterday","last7","thisMonth","custom"]}},{"name":"from","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"to","in":"query","required":false,"style":"form","explode":true,"schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"locationMode","in":"query","required":false,"style":"form","explode":true,"schema":{"default":"single","type":"string","enum":["single","all"]}},{"name":"paymentTypes","in":"query","required":false,"style":"form","explode":true,"schema":{"minItems":1,"type":"array","items":{"type":"string","enum":["cash","card","wallet","mixed","other"]}}},{"name":"locale","in":"query","schema":{"type":"string"},"description":"PDF label locale; unsupported values use the application default."}],"responses":{"200":{"description":"Complete report with provenance and attachment filename.","headers":{"Content-Disposition":{"schema":{"type":"string"}}},"content":{"text/csv":{"schema":{"type":"string"}},"application/pdf":{"schema":{}}}},"400":{"description":"Invalid filter.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"A signed-in session is required.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"The session cannot read this report or venue scope.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"Unknown report, format or venue.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"413":{"description":"Export exceeds the CSV or PDF row limit; narrow its scope.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"Export processing failed.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"504":{"description":"Database deadline reached; narrow the requested scope.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}}},"/api/myfatoorah-documents/v1/upload":{"post":{"operationId":"uploadMyFatoorahDocument","summary":"Upload one MyFatoorah KYC document","description":"Forwards a base64-encoded KYC document to the organization's connected MyFatoorah account and records the upload marker. Requires a signed-in session with payment-provider rights for that organization.","security":[{"sessionCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"organizationId":{"type":"string","minLength":1},"fileType":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"fileName":{"type":"string","minLength":1,"maxLength":255},"contentType":{"type":"string","enum":["image/jpeg","image/png","image/bmp","image/gif","application/pdf","application/msword","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.ms-excel","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"]},"buffer":{"type":"string","minLength":1}},"required":["organizationId","fileType","fileName","contentType","buffer"],"additionalProperties":false}}}},"responses":{"200":{"description":"MyFatoorah accepted the document and the marker was recorded.","content":{"application/json":{"schema":{"type":"object","properties":{"fileType":{"type":"number"},"uploadedAt":{"type":"string"}},"required":["fileType","uploadedAt"]}}}},"400":{"description":"That upload request is not valid, or MyFatoorah rejected the file.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"Sign in to upload a document.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"You cannot upload MyFatoorah documents.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"409":{"description":"Connect MyFatoorah before uploading documents.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"412":{"description":"MyFatoorah is not configured.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"413":{"description":"That file exceeds MyFatoorah's 5 MB limit.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"MyFatoorah accepted the document, but saving it here failed.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"502":{"description":"MyFatoorah could not accept that document.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}}}}}