{"openapi":"3.1.0","info":{"title":"Homi Agent API","version":"1.0.0","description":"Transport and discovery contract for Homi's OAuth-protected Model Context Protocol server. After authorization, call the MCP tools/list method for the current function-calling schemas.","contact":{"name":"Homi support","email":"hello@homi.so","url":"https://www.homi.so/contact"}},"externalDocs":{"description":"Homi developer portal and MCP quickstart","url":"https://www.homi.so/developers"},"servers":[{"url":"https://www.homi.so","description":"Production"}],"tags":[{"name":"Discovery","description":"Unauthenticated machine-readable API and OAuth metadata."},{"name":"MCP","description":"The canonical Homi Model Context Protocol transport. Requires a homi:all OAuth token."}],"paths":{"/api":{"get":{"tags":["Discovery"],"operationId":"getHomiApiIndex","summary":"Get the Homi API index","description":"Returns canonical links for developer documentation, OpenAPI, MCP, and OAuth discovery.","responses":{"200":{"description":"Homi API discovery links.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiIndex"}}}}}}},"/.well-known/oauth-protected-resource":{"get":{"tags":["Discovery"],"operationId":"getHomiProtectedResourceMetadata","summary":"Get OAuth protected-resource metadata","description":"Returns RFC 9728 metadata for the Homi MCP resource, including its authorization server and supported scopes.","responses":{"200":{"description":"RFC 9728 protected-resource metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProtectedResourceMetadata"}}}}}}},"/.well-known/oauth-authorization-server/api/auth":{"get":{"tags":["Discovery"],"operationId":"getHomiAuthorizationServerMetadata","summary":"Get OAuth authorization-server metadata","description":"Returns RFC 8414 metadata, including authorization, token, registration, revocation, introspection, and JWKS endpoints.","responses":{"200":{"description":"RFC 8414 authorization-server metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthorizationServerMetadata"}}}}}}},"/api/mcp":{"get":{"tags":["MCP"],"operationId":"openHomiMcpStream","summary":"Open the Homi MCP stream","description":"Opens the authenticated Streamable HTTP response channel used by compatible MCP clients.","security":[{"homiOAuth":["homi:all"]}],"parameters":[{"$ref":"#/components/parameters/McpProtocolVersion"}],"responses":{"200":{"description":"MCP event stream.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"description":"The OAuth bearer token is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}}}},"post":{"tags":["MCP"],"operationId":"sendHomiMcpMessage","summary":"Send a Homi MCP message","description":"Sends an authenticated MCP JSON-RPC request. Initialize the client, call tools/list to obtain typed function schemas, then call tools/call with a selected Homi tool.","security":[{"homiOAuth":["homi:all"]}],"parameters":[{"$ref":"#/components/parameters/McpProtocolVersion"},{"$ref":"#/components/parameters/McpMethod"}],"requestBody":{"required":true,"description":"A valid MCP JSON-RPC request or notification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}}},"responses":{"200":{"description":"MCP JSON-RPC response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}},"text/event-stream":{"schema":{"type":"string"}}}},"202":{"description":"The MCP notification was accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}},"400":{"description":"The MCP or JSON-RPC request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}},"401":{"description":"The OAuth bearer token is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}}}},"delete":{"tags":["MCP"],"operationId":"closeHomiMcpSession","summary":"Close a legacy Homi MCP session","description":"Closes a negotiated legacy transport session. Modern Homi MCP clients use stateless requests.","security":[{"homiOAuth":["homi:all"]}],"parameters":[{"$ref":"#/components/parameters/McpProtocolVersion"}],"responses":{"200":{"description":"Session close response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}},"401":{"description":"The OAuth bearer token is missing or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthError"}}}}}}}},"components":{"securitySchemes":{"homiOAuth":{"type":"oauth2","description":"OAuth 2.1 authorization code flow with PKCE. Agents can use Dynamic Client Registration from the advertised registration endpoint.","flows":{"authorizationCode":{"authorizationUrl":"https://www.homi.so/api/auth/oauth2/authorize","tokenUrl":"https://www.homi.so/api/auth/oauth2/token","refreshUrl":"https://www.homi.so/api/auth/oauth2/token","scopes":{"homi:all":"Read and update Homi data the user explicitly authorizes.","offline_access":"Request a refresh token for continued access."}}}}},"parameters":{"McpProtocolVersion":{"name":"MCP-Protocol-Version","in":"header","required":false,"description":"The MCP protocol version negotiated by the client.","schema":{"type":"string","example":"2026-07-28"}},"McpMethod":{"name":"Mcp-Method","in":"header","required":false,"description":"The modern MCP method hint. The request body remains authoritative.","schema":{"type":"string","example":"tools/list"}}},"schemas":{"ApiIndex":{"type":"object","additionalProperties":false,"required":["name","description","documentation","openapi","mcp","authorizationServer","protectedResource"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"documentation":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"mcp":{"type":"string","format":"uri"},"authorizationServer":{"type":"string","format":"uri"},"protectedResource":{"type":"string","format":"uri"}}},"ProtectedResourceMetadata":{"type":"object","additionalProperties":true,"required":["resource","authorization_servers","scopes_supported"],"properties":{"resource":{"type":"string","format":"uri"},"authorization_servers":{"type":"array","items":{"type":"string","format":"uri"}},"scopes_supported":{"type":"array","items":{"type":"string"}},"bearer_methods_supported":{"type":"array","items":{"type":"string"}}}},"AuthorizationServerMetadata":{"type":"object","additionalProperties":true,"required":["issuer","authorization_endpoint","token_endpoint","registration_endpoint","scopes_supported"],"properties":{"issuer":{"type":"string","format":"uri"},"authorization_endpoint":{"type":"string","format":"uri"},"token_endpoint":{"type":"string","format":"uri"},"registration_endpoint":{"type":"string","format":"uri"},"jwks_uri":{"type":"string","format":"uri"},"scopes_supported":{"type":"array","items":{"type":"string"}}}},"JsonRpcRequest":{"type":"object","additionalProperties":false,"required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"number"}]},"method":{"type":"string","examples":["initialize","tools/list","tools/call"]},"params":{"type":"object","additionalProperties":true}}},"JsonRpcResponse":{"type":"object","additionalProperties":true,"required":["jsonrpc"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"result":{"type":"object","additionalProperties":true},"error":{"type":"object","additionalProperties":true,"required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{}}}}},"OAuthError":{"type":"object","additionalProperties":true,"required":["error","error_description"],"properties":{"error":{"type":"string","examples":["unauthorized","invalid_token"]},"error_description":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"resolution":{"type":"string"},"docs":{"type":"string","format":"uri"}}}}}}