{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Bogi Agent API","version":"1.0.0","description":"Public contract for the hosted Bogi MCP server. MCP exposes tool schemas after initialization; this OpenAPI document describes transport, discovery, and scoped OAuth access.","contact":{"name":"Bogi developer support","email":"hello@usebogi.com","url":"https://usebogi.com/developers"}},"externalDocs":{"description":"Bogi developer resources","url":"https://usebogi.com/developers"},"servers":[{"url":"https://usebogi.com","description":"Bogi production"}],"tags":[{"name":"MCP","description":"Bogi remote MCP transport using Streamable HTTP."}],"paths":{"/api/v1/mcp":{"post":{"operationId":"sendMcpMessage","summary":"Send an MCP JSON-RPC message","description":"Initialize a session, discover tools, or invoke a tool. Each tool enforces its own OAuth scope in addition to transport authentication.","tags":["MCP"],"parameters":[{"name":"MCP-Protocol-Version","in":"header","required":false,"description":"MCP protocol version negotiated during initialization.","schema":{"type":"string"}}],"security":[{"mcpOAuth":["workspace:read"]},{"mcpOAuth":["workspace:write"]},{"mcpOAuth":["workspace:execute"]},{"mcpOAuth":["apps:preview"]},{"mcpOAuth":["threads:read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}}},"responses":{"200":{"description":"MCP JSON-RPC response or server-sent event stream.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}},"text/event-stream":{"schema":{"type":"string"}}}},"202":{"description":"MCP notification accepted."},"400":{"description":"Invalid MCP or JSON-RPC request."},"401":{"description":"Missing or invalid OAuth bearer token. Inspect the WWW-Authenticate header for protected resource metadata."},"403":{"description":"The token lacks the scope required by the requested tool."}}},"get":{"operationId":"openMcpStream","summary":"Open an MCP server event stream","tags":["MCP"],"parameters":[{"name":"MCP-Protocol-Version","in":"header","required":false,"description":"MCP protocol version negotiated during initialization.","schema":{"type":"string"}}],"security":[{"mcpOAuth":["workspace:read"]},{"mcpOAuth":["workspace:write"]},{"mcpOAuth":["workspace:execute"]},{"mcpOAuth":["apps:preview"]},{"mcpOAuth":["threads:read"]}],"responses":{"200":{"description":"MCP server-sent event stream.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"description":"Missing or invalid OAuth bearer token."}}},"delete":{"operationId":"closeMcpSession","summary":"Close an MCP session","tags":["MCP"],"parameters":[{"name":"MCP-Protocol-Version","in":"header","required":false,"description":"MCP protocol version negotiated during initialization.","schema":{"type":"string"}}],"security":[{"mcpOAuth":["workspace:read"]},{"mcpOAuth":["workspace:write"]},{"mcpOAuth":["workspace:execute"]},{"mcpOAuth":["apps:preview"]},{"mcpOAuth":["threads:read"]}],"responses":{"200":{"description":"MCP session closed."},"401":{"description":"Missing or invalid OAuth bearer token."}}}}},"components":{"securitySchemes":{"mcpOAuth":{"type":"oauth2","description":"OAuth 2.0 authorization code flow with S256 PKCE and dynamic client registration. Request only the scopes needed for the intended tools.","flows":{"authorizationCode":{"authorizationUrl":"https://usebogi.com/api/v1/oauth/mcp/authorize","tokenUrl":"https://usebogi.com/api/v1/oauth/mcp/token","refreshUrl":"https://usebogi.com/api/v1/oauth/mcp/token","scopes":{"workspace:read":"Read files and context","workspace:write":"Write files, create assets, and persist changes","workspace:execute":"Run shell commands and code","apps:preview":"Start and inspect app previews","threads:read":"Read chat threads and transcripts"}}}}},"schemas":{"JsonRpcRequest":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"anyOf":[{"type":"string"},{"type":"integer"}]},"method":{"type":"string"},"params":{"type":"object","additionalProperties":true}},"additionalProperties":true},"JsonRpcResponse":{"type":"object","required":["jsonrpc"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"null"}]},"result":true,"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":true},"additionalProperties":true}},"additionalProperties":true}}},"x-bogi-oauth-discovery":{"authorizationServer":"https://usebogi.com/.well-known/oauth-authorization-server","protectedResource":"https://usebogi.com/.well-known/oauth-protected-resource","dynamicClientRegistration":"https://usebogi.com/api/v1/oauth/mcp/register"},"x-bogi-capability-scopes":{"workspaceInspection":["workspace:read"],"workspaceFilesAndAssets":["workspace:write"],"commandExecution":["workspace:execute"],"appPreviews":["apps:preview"],"threadInspection":["threads:read"]}}