{"openapi":"3.1.0","info":{"title":"Gravity AI UI API","version":"1.0.0","description":"API, MCP, and discovery surfaces for Gravity AI UI, an agent-ready generator for validated A2UI and Gravity UI product interfaces.","contact":{"name":"Gravity AI UI","url":"https://gravity-ai.ydb-qdrant.tech/docs"},"license":{"name":"Apache-2.0"}},"servers":[{"url":"https://gravity-ai.ydb-qdrant.tech"}],"tags":[{"name":"Agent","description":"Interface generation and refinement."},{"name":"Feedback","description":"Publish liked generated interfaces."},{"name":"MCP","description":"Streamable HTTP MCP transport."},{"name":"Discovery","description":"Agent-readable discovery metadata."}],"paths":{"/api/agent":{"post":{"operationId":"streamGravityInterface","tags":["Agent"],"summary":"Stream generated Gravity UI interface events","description":"Accepts a prompt or action request and returns Server-Sent Events with status, A2UI messages, composed payload snapshots, errors, and a final done event.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRequest"},"examples":{"prompt":{"value":{"kind":"prompt","conversationId":"demo-conversation","prompt":"Build a deployment review dashboard"}}}}}},"responses":{"200":{"description":"SSE stream of agent events. Generator configuration errors are emitted as SSE error events.","content":{"text/event-stream":{"schema":{"type":"string"}}},"headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Documented request budget for agent clients."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining requests in the current window when enforced."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the current window resets when enforced."}}},"400":{"description":"Invalid agent request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}}}}},"/api/design-feedback":{"post":{"operationId":"publishDesignFeedback","tags":["Feedback"],"summary":"Publish liked interface feedback to the public gallery","description":"Stores a liked composed interface payload and schedules gallery thumbnail generation. Current public demo accepts only positive published feedback from the app flow.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Optional caller-provided retry key. The current demo documents the header for agent retry planning; durable idempotency is not enforced."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DesignFeedbackRequest"}}}},"responses":{"200":{"description":"Feedback was stored and a gallery id was created.","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Documented request budget for agent clients."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining requests in the current window when enforced."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the current window resets when enforced."}},"content":{"application/json":{"schema":{"type":"object","required":["feedbackId","galleryId","rating","createdAtMs"],"properties":{"feedbackId":{"type":"string"},"galleryId":{"type":"string"},"rating":{"type":"integer","const":1},"createdAtMs":{"type":"integer"}}}}}},"400":{"description":"Invalid design feedback.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}},"503":{"description":"Feedback storage unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimpleErrorResponse"}}}}}}},"/mcp":{"get":{"operationId":"rejectMcpGet","tags":["MCP"],"summary":"Reject unsupported MCP method","responses":{"405":{"description":"Method not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}}}},"post":{"operationId":"callMcpServer","tags":["MCP"],"summary":"Call the Gravity AI UI MCP server","description":"Streamable HTTP MCP endpoint. Send JSON-RPC requests with Accept: application/json, text/event-stream.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}}},"responses":{"200":{"description":"JSON-RPC response.","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Documented request budget for agent clients."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining requests in the current window when enforced."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the current window resets when enforced."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}},"403":{"description":"Forbidden origin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}},"500":{"description":"Internal MCP server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}}}},"delete":{"operationId":"rejectMcpDelete","tags":["MCP"],"summary":"Reject unsupported MCP method","responses":{"405":{"description":"Method not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}}}}},"/.well-known/mcp":{"post":{"operationId":"callWellKnownMcpServer","tags":["MCP"],"summary":"Call the Gravity AI UI MCP server","description":"Streamable HTTP MCP endpoint. Send JSON-RPC requests with Accept: application/json, text/event-stream.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}}},"responses":{"200":{"description":"JSON-RPC response.","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Documented request budget for agent clients."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining requests in the current window when enforced."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the current window resets when enforced."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}},"403":{"description":"Forbidden origin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}},"500":{"description":"Internal MCP server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}}}}}},"get":{"operationId":"getWellKnownMcpServerCard","tags":["Discovery","MCP"],"summary":"Fetch the Gravity AI UI MCP server card","responses":{"200":{"description":"JSON response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpServerCard"}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenApiSpec","tags":["Discovery"],"summary":"Fetch the OpenAPI 3.1 document","responses":{"200":{"description":"JSON response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiDocument"}}}}}}},"/.well-known/oauth-authorization-server":{"get":{"operationId":"getOAuthAuthorizationServerMetadata","tags":["Discovery"],"summary":"Fetch OAuth authorization server metadata","responses":{"200":{"description":"JSON response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthAuthorizationServerMetadata"}}}}}}},"/.well-known/oauth-protected-resource":{"get":{"operationId":"getOAuthProtectedResourceMetadata","tags":["Discovery"],"summary":"Fetch OAuth protected-resource metadata","responses":{"200":{"description":"JSON response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthProtectedResourceMetadata"}}}}}}},"/.well-known/oauth-protected-resource/mcp":{"get":{"operationId":"getMcpOAuthProtectedResourceMetadata","tags":["Discovery"],"summary":"Fetch MCP protected-resource metadata","responses":{"200":{"description":"JSON response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthProtectedResourceMetadata"}}}}}}},"/.well-known/openid-configuration":{"get":{"operationId":"getOpenIdConfiguration","tags":["Discovery"],"summary":"Fetch OpenID Provider configuration","responses":{"200":{"description":"JSON response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenIdConfiguration"}}}}}}},"/oauth/authorize":{"get":{"operationId":"authorizeOAuthClient","tags":["Discovery"],"summary":"OAuth authorization endpoint placeholder","description":"Returns structured oauth_not_enabled JSON while token issuance is disabled in the public demo.","responses":{"501":{"description":"OAuth authorization is not enabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/oauth/token":{"post":{"operationId":"issueOAuthToken","tags":["Discovery"],"summary":"OAuth token endpoint placeholder","description":"Returns structured oauth_not_enabled JSON while token issuance is disabled in the public demo.","responses":{"501":{"description":"OAuth token issuance is not enabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}},"get":{"operationId":"rejectOAuthTokenGet","tags":["Discovery"],"summary":"Reject unsupported OAuth token GET requests","responses":{"405":{"description":"OAuth token endpoint requires POST.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}},"/oauth/userinfo":{"get":{"operationId":"getOAuthUserInfo","tags":["Discovery"],"summary":"OpenID UserInfo endpoint placeholder","description":"Returns structured oauth_not_enabled JSON while bearer-token enforcement is disabled in the public demo.","responses":{"501":{"description":"OpenID UserInfo is not enabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}},"post":{"operationId":"postOAuthUserInfo","tags":["Discovery"],"summary":"OpenID UserInfo endpoint placeholder","description":"Returns structured oauth_not_enabled JSON while bearer-token enforcement is disabled in the public demo.","responses":{"501":{"description":"OpenID UserInfo is not enabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"securitySchemes":{"OAuth2Metadata":{"type":"oauth2","description":"Discovery metadata is published for agent compatibility. Token issuance is disabled in the current public demo.","flows":{"authorizationCode":{"authorizationUrl":"https://gravity-ai.ydb-qdrant.tech/oauth/authorize","tokenUrl":"https://gravity-ai.ydb-qdrant.tech/oauth/token","scopes":{"interface:generate":"Generate and refine interfaces.","interface:read":"Read public gallery interfaces."}}}}},"schemas":{"AgentRequest":{"oneOf":[{"$ref":"#/components/schemas/PromptAgentRequest"},{"$ref":"#/components/schemas/ActionAgentRequest"}]},"PromptAgentRequest":{"type":"object","additionalProperties":false,"required":["kind","conversationId","prompt"],"properties":{"kind":{"type":"string","const":"prompt"},"conversationId":{"type":"string","minLength":1,"maxLength":120},"prompt":{"type":"string","minLength":1,"maxLength":6000},"conversationContext":{"$ref":"#/components/schemas/ConversationContext"}}},"ActionAgentRequest":{"type":"object","additionalProperties":false,"required":["kind","conversationId","surfaceId","action"],"properties":{"kind":{"type":"string","const":"action"},"conversationId":{"type":"string","minLength":1,"maxLength":120},"surfaceId":{"type":"string","minLength":1,"maxLength":80},"action":{},"context":{},"dataModel":{},"conversationContext":{"$ref":"#/components/schemas/ConversationContext"}}},"ConversationContext":{"type":"object","additionalProperties":false,"properties":{"history":{"type":"array","maxItems":12,"items":{"$ref":"#/components/schemas/ConversationHistoryItem"}},"latestSurfaceId":{"type":"string","minLength":1,"maxLength":80},"latestPayload":{"$ref":"#/components/schemas/ComposedInterfacePayload"},"latestDataModel":{}}},"ConversationHistoryItem":{"type":"object","additionalProperties":false,"required":["role","text"],"properties":{"role":{"type":"string","enum":["user","assistant"]},"text":{"type":"string","minLength":1,"maxLength":2000},"surfaceId":{"type":"string","minLength":1,"maxLength":80}}},"ComposedInterfacePayload":{"type":"object","additionalProperties":false,"required":["sequence","surfaceId","root","nodes"],"properties":{"sequence":{"type":"integer","minimum":0,"maximum":10000},"surfaceId":{"type":"string","minLength":1,"maxLength":80},"dataModel":{},"root":{"type":"object","required":["component"],"properties":{"component":{"type":"string","enum":["Column","Row"]},"props":{"type":"object"}}},"nodes":{"type":"array","maxItems":120,"items":{"type":"object","required":["id","component"],"properties":{"id":{"type":"string"},"parentId":{"type":["string","null"]},"order":{"type":"integer","minimum":0},"component":{"type":"string"},"props":{"type":"object"}}}}}},"DesignFeedbackRequest":{"type":"object","additionalProperties":false,"required":["conversationId","turnId","rating","publish","payload"],"properties":{"conversationId":{"type":"string","minLength":1,"maxLength":120},"turnId":{"type":"string","minLength":1,"maxLength":160},"rating":{"type":"integer","const":1},"publish":{"type":"boolean","const":true},"prompt":{"type":"string","maxLength":6000},"payload":{"$ref":"#/components/schemas/ComposedInterfacePayload"},"messages":{"type":"array","maxItems":12,"items":{}},"dataModel":{},"conversationContext":{"type":"object"}}},"JsonRpcRequest":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":["string","number","null"]},"method":{"type":"string"},"params":{"type":"object"}}},"JsonRpcResponse":{"type":"object","required":["jsonrpc"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"type":["string","number","null"]},"result":{},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}},"ValidationErrorResponse":{"type":"object","required":["error","issues"],"properties":{"error":{"type":"string"},"issues":{"type":"object","additionalProperties":true,"description":"Validation details from Zod flatten(), including formErrors and fieldErrors."}}},"SimpleErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"McpServerCard":{"type":"object","additionalProperties":false,"required":["name","title","description","version","websiteUrl","serverUrl","transport","tools"],"properties":{"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"version":{"type":"string"},"websiteUrl":{"type":"string","format":"uri"},"serverUrl":{"type":"string","format":"uri"},"transport":{"type":"string","const":"streamable-http"},"tools":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["name","title","description","readOnly"],"properties":{"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"readOnly":{"type":"boolean"}}}}}},"ProblemDetails":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"docs":{"type":"string","format":"uri"},"issues":{}}}}},"OAuthAuthorizationServerMetadata":{"type":"object","required":["issuer","authorization_endpoint","token_endpoint","jwks_uri","response_types_supported","grant_types_supported","token_endpoint_auth_methods_supported","code_challenge_methods_supported","scopes_supported","service_documentation"],"properties":{"issuer":{"type":"string","format":"uri"},"authorization_endpoint":{"type":"string","format":"uri"},"token_endpoint":{"type":"string","format":"uri"},"jwks_uri":{"type":"string","format":"uri"},"response_types_supported":{"type":"array","items":{"type":"string"}},"grant_types_supported":{"type":"array","items":{"type":"string"}},"token_endpoint_auth_methods_supported":{"type":"array","items":{"type":"string"}},"code_challenge_methods_supported":{"type":"array","items":{"type":"string"}},"scopes_supported":{"type":"array","items":{"type":"string"}},"service_documentation":{"type":"string","format":"uri"}}},"OpenIdConfiguration":{"allOf":[{"$ref":"#/components/schemas/OAuthAuthorizationServerMetadata"},{"type":"object","required":["userinfo_endpoint","subject_types_supported","id_token_signing_alg_values_supported","claims_supported"],"properties":{"userinfo_endpoint":{"type":"string","format":"uri"},"subject_types_supported":{"type":"array","items":{"type":"string"}},"id_token_signing_alg_values_supported":{"type":"array","items":{"type":"string"}},"claims_supported":{"type":"array","items":{"type":"string"}}}}]},"OAuthProtectedResourceMetadata":{"type":"object","required":["resource"],"properties":{"resource":{"type":"string","format":"uri"},"authorization_servers":{"type":"array","items":{"type":"string"}},"scopes_supported":{"type":"array","items":{"type":"string"}},"bearer_methods_supported":{"type":"array","items":{"type":"string"}},"resource_name":{"type":"string"},"resource_documentation":{"type":"string","format":"uri"}}},"OpenApiDocument":{"type":"object","description":"OpenAPI 3.1 document."}}}}