{"openapi":"3.1.0","info":{"title":"Kensho Grounding, AI S&P Data Retrieval","version":"0.1.0"},"paths":{"/login":{"get":{"tags":["auth"],"summary":"Login Kensho","description":"Initiate Kensho Auth Code flow.","operationId":"login_kensho_login_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/login-spgi":{"get":{"tags":["auth"],"summary":"Login Spgi Auth Code","description":"Initiate SPGI Auth Code flow.","operationId":"login_spgi_auth_code_login_spgi_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/login/redirect":{"get":{"tags":["auth"],"summary":"Login Callback","description":"OAuth callback with CSRF protection via state validation.\n\nThis callback validates the OAuth state parameter for CSRF protection,\nthen uses the flow type stored in the session to differentiate flows:\n- flow_type=\"api\" or \"spgi-api\": Return HTML with tokens (API flow)\n- flow_type=\"admin\" or \"spgi-admin\": Store tokens in session and redirect to admin panel\nSPGI-based flow types use the SPGI auth manager (connected to SPGI Okta), while non-SPGI flow\ntypes use the Kensho auth manager (connected to Kensho Okta)\n\nArgs:\n    request: FastAPI request object\n    state: OAuth state parameter for CSRF protection\n\nReturns:\n    HTML response with tokens (API flow) or redirect to admin (admin flow)","operationId":"login_callback_login_redirect_get","parameters":[{"name":"state","in":"query","required":false,"schema":{"type":"string","title":"State"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/oauth2/refresh":{"post":{"tags":["auth"],"summary":"Refresh Token Endpoint","description":"Refresh OAuth access token using refresh token.","operationId":"refresh_token_endpoint_oauth2_refresh_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshTokenRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"string","title":"Response Refresh Token Endpoint Oauth2 Refresh Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/spgi-login":{"post":{"tags":["auth"],"summary":"Spgi Login Ropc","description":"Perform SPGI ROPC flow.","operationId":"spgi_login_ropc_spgi_login_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpgiTokenRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpgiTokenResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/admin-login":{"get":{"tags":["admin-oauth"],"summary":"Admin Login Redirect","description":"Initiate Kensho OAuth flow for admin access.","operationId":"admin_login_redirect_admin_login_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/admin-login-spgi":{"get":{"tags":["admin-oauth"],"summary":"Admin Login Spgi Redirect","description":"Initiate SPGI OAuth flow for admin access.","operationId":"admin_login_spgi_redirect_admin_login_spgi_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/ready":{"get":{"tags":["health"],"summary":"Get Ready","description":"Readiness endpoint to ensure server is stood up.","operationId":"ready","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"string","title":"Response Ready"}}}}}}},"/api/v1/agents":{"get":{"tags":["agents"],"summary":"Get Agents","description":"Returns a list of agents accessible to the user.","operationId":"agents","security":[{"HTTPBearer":[]}],"parameters":[{"name":"min_release_stage","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ReleaseStage","default":"generally-available"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataAgentListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/admin/agents":{"get":{"tags":["admin"],"summary":"Get Agents","description":"Returns a list of configured agents with their health status.\n\nRequires admin role (enforced at router level).","operationId":"all_agents","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DataAgentAdminListResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v2/search":{"post":{"tags":["search"],"summary":"Search For Data","description":"POST Endpoint that performs the search and returns structured data.\n\nReturns data in the grounding output protocol format with\nstructured data, source tracking, and metadata handling.","operationId":"search","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchApiRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroundingAgentOutputV2"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}}},"components":{"schemas":{"AdminDataAgentResponse":{"properties":{"agent":{"$ref":"#/components/schemas/DataAgent"},"health":{"$ref":"#/components/schemas/AgentHealth"}},"type":"object","required":["agent","health"],"title":"AdminDataAgentResponse","description":"Agent with its health status."},"AgentHealth":{"properties":{"status":{"$ref":"#/components/schemas/HealthStatus","default":"unknown"},"last_checked":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Checked"},"response_time_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Response Time Ms"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"}},"type":"object","title":"AgentHealth","description":"Agent health data."},"CellSource":{"properties":{"type":{"type":"string","const":"cell","title":"Type","description":"Source type","default":"cell"},"row":{"type":"integer","minimum":0.0,"title":"Row","description":"Zero-based row index"},"column":{"type":"string","title":"Column","description":"Column name"},"source":{"$ref":"#/components/schemas/SourceInfo","description":"Source information"}},"type":"object","required":["row","column","source"],"title":"CellSource","description":"Cell-level source."},"ColumnSource":{"properties":{"type":{"type":"string","const":"column","title":"Type","description":"Source type","default":"column"},"name":{"type":"string","title":"Name","description":"Column name"},"source":{"$ref":"#/components/schemas/SourceInfo","description":"Source information"}},"type":"object","required":["name","source"],"title":"ColumnSource","description":"Column-level source."},"DataAgent":{"properties":{"name":{"type":"string","title":"Name"},"display_name":{"type":"string","title":"Display Name"},"short_description":{"type":"string","title":"Short Description"},"description":{"type":"string","title":"Description"},"example_queries":{"items":{"type":"string"},"type":"array","title":"Example Queries"},"underlying_datasets":{"items":{"$ref":"#/components/schemas/UnderlyingDataset"},"type":"array","title":"Underlying Datasets"},"connection_params":{"additionalProperties":true,"type":"object","title":"Connection Params"},"enabled":{"type":"boolean","title":"Enabled"},"owner":{"type":"string","title":"Owner","default":"kensho"},"type":{"type":"string","title":"Type","default":""},"data_owner_division":{"type":"string","title":"Data Owner Division","default":""},"data_owner_team":{"type":"string","title":"Data Owner Team","default":""},"release_stage":{"$ref":"#/components/schemas/ReleaseStage","default":"beta"},"auth_scope":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Auth Scope"},"requires_spgi_token":{"type":"boolean","title":"Requires Spgi Token","default":false},"priority_group":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Priority Group"},"priority":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Priority"}},"type":"object","required":["name","display_name","short_description","description","example_queries","underlying_datasets","connection_params","enabled"],"title":"DataAgent","description":"Configuration for a Data Agent"},"DataAgentAdminListResponse":{"properties":{"agents":{"items":{"$ref":"#/components/schemas/AdminDataAgentResponse"},"type":"array","title":"Agents"}},"type":"object","required":["agents"],"title":"DataAgentAdminListResponse"},"DataAgentListResponse":{"properties":{"agents":{"items":{"$ref":"#/components/schemas/DataAgentResponse"},"type":"array","title":"Agents"}},"type":"object","required":["agents"],"title":"DataAgentListResponse"},"DataAgentResponse":{"properties":{"name":{"type":"string","title":"Name"},"display_name":{"type":"string","title":"Display Name"},"short_description":{"type":"string","title":"Short Description"},"description":{"type":"string","title":"Description"},"example_queries":{"items":{"type":"string"},"type":"array","title":"Example Queries"},"underlying_datasets":{"items":{"$ref":"#/components/schemas/UnderlyingDataset"},"type":"array","title":"Underlying Datasets"},"enabled":{"type":"boolean","title":"Enabled"},"type":{"type":"string","title":"Type"},"release_stage":{"$ref":"#/components/schemas/ReleaseStage"},"requires_spgi_token":{"type":"boolean","title":"Requires Spgi Token"}},"type":"object","required":["name","display_name","short_description","description","example_queries","underlying_datasets","enabled","type","release_stage","requires_spgi_token"],"title":"DataAgentResponse","description":"API response representation of a DataAgent, excluding internal properties."},"GroundingAgentOutputV2":{"properties":{"response":{"items":{"$ref":"#/components/schemas/ResponseItem"},"type":"array","title":"Response","description":"Response items"},"schema_version":{"type":"string","const":"2.0","title":"Schema Version","description":"Schema version","default":"2.0"}},"type":"object","required":["response"],"title":"GroundingAgentOutputV2","description":"Top-level v2 output format."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthStatus":{"type":"string","enum":["healthy","unhealthy","unknown"],"title":"HealthStatus","description":"Agent health status."},"Problem":{"properties":{},"additionalProperties":true,"type":"object","title":"Problem","description":"Simplified problem format supporting any additional fields."},"RefreshTokenRequest":{"properties":{"refresh_token":{"type":"string","title":"Refresh Token"}},"type":"object","required":["refresh_token"],"title":"RefreshTokenRequest"},"ReleaseStage":{"type":"string","enum":["beta","generally-available"],"title":"ReleaseStage","description":"Agent release stage levels.\n\nThis class is copied into system_tests.common.utils\nso that the system tests's uv environment does not have\na dependency on app"},"ResponseItem":{"properties":{"schema":{"$ref":"#/components/schemas/Schema","description":"Schema containing field definitions"},"data":{"items":{"additionalProperties":{"anyOf":[{"type":"boolean"},{"type":"integer"},{"type":"number"},{"type":"string"},{"type":"null"}]},"type":"object"},"type":"array","title":"Data","description":"Data rows as objects"},"sources":{"items":{"oneOf":[{"$ref":"#/components/schemas/TableSource"},{"$ref":"#/components/schemas/RowSource"},{"$ref":"#/components/schemas/ColumnSource"},{"$ref":"#/components/schemas/CellSource"}],"discriminator":{"propertyName":"type","mapping":{"cell":"#/components/schemas/CellSource","column":"#/components/schemas/ColumnSource","row":"#/components/schemas/RowSource","table":"#/components/schemas/TableSource"}}},"type":"array","title":"Sources","description":"Source information at various levels"},"problems":{"items":{"$ref":"#/components/schemas/Problem"},"type":"array","title":"Problems","description":"Issues encountered"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Additional metadata"},"representation_type":{"type":"string","const":"tabular","title":"Representation Type","description":"Data representation type","default":"tabular"}},"type":"object","required":["schema","data","sources"],"title":"ResponseItem","description":"Single response item containing data, sources, and metadata."},"RowSource":{"properties":{"type":{"type":"string","const":"row","title":"Type","description":"Source type","default":"row"},"index":{"type":"integer","minimum":0.0,"title":"Index","description":"Zero-based row index"},"source":{"$ref":"#/components/schemas/SourceInfo","description":"Source information"}},"type":"object","required":["index","source"],"title":"RowSource","description":"Row-level source."},"Schema":{"properties":{"fields":{"items":{"$ref":"#/components/schemas/SchemaField"},"type":"array","title":"Fields","description":"Column definitions"}},"type":"object","required":["fields"],"title":"Schema","description":"Schema definition matching pandas DataFrame table format."},"SchemaField":{"properties":{"name":{"type":"string","title":"Name","description":"Column name"},"type":{"anyOf":[{"type":"string","enum":["null","boolean","integer","number","string"]},{"items":{"type":"string","enum":["null","boolean","integer","number","string"]},"type":"array"}],"title":"Type","description":"JSON Schema primitive type(s) - single string or list of strings"}},"type":"object","required":["name","type"],"title":"SchemaField","description":"Schema definition for a column in the data."},"SearchApiRequest":{"properties":{"query":{"type":"string","title":"Query","description":"The search query to execute. Use natural language to describe what information you're looking for. Be specific about timeframes, data types, and any filtering criteria for optimal results.","examples":["Show me AAPL's Q3 2024 revenue AND compare it with company profile information","What did accenture say their goals are in their last earnings call?","AAPL's last income statement","2023 Salary and bonus for Walmart executives"]},"allowed_datasets":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Allowed Datasets","description":"Optional list of specific datasets to search within. If not provided, searches across all accessible datasets.","examples":[["xpf_financials_companyintel_structured"],["ciq_financials_structured","xpf_keydevelopments_structured"]]},"min_release_stage":{"$ref":"#/components/schemas/ReleaseStage","description":"Minimum release stage for data agents to include in search. Controls access to experimental or beta features.","default":"generally-available","examples":["generally-available","beta"]}},"type":"object","required":["query"],"title":"SearchApiRequest","description":"API Request Model for searching data within Grounding Agents.\n\nThis model defines the structure for search requests from external clients"},"SourceInfo":{"properties":{"uri":{"type":"string","title":"Uri","description":"Link to the source"},"name":{"type":"string","title":"Name","description":"Name of the source"},"provider":{"type":"string","title":"Provider","description":"Provider of the source"}},"type":"object","required":["uri","name","provider"],"title":"SourceInfo","description":"Basic source information."},"SpgiTokenRequest":{"properties":{"username":{"type":"string","title":"Username","description":"Username to authenticate to SPGI Okta."},"password":{"type":"string","title":"Password","description":"Password to authenticate to SPGI Okta."}},"type":"object","required":["username","password"],"title":"SpgiTokenRequest","description":"API Request Model for SPGI tokens (Password Grant)."},"SpgiTokenResponse":{"properties":{"access_token":{"type":"string","title":"Access Token"},"refresh_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Refresh Token"}},"type":"object","required":["access_token"],"title":"SpgiTokenResponse","description":"API response model for SPGI tokens."},"TableSource":{"properties":{"type":{"type":"string","const":"table","title":"Type","description":"Source type","default":"table"},"source":{"$ref":"#/components/schemas/SourceInfo","description":"Source information"}},"type":"object","required":["source"],"title":"TableSource","description":"Global table-level source."},"UnderlyingDataset":{"type":"string","enum":["financials","market_data","multiples","market_cap","transactions","professionals","drive_transcripts","drive_filings","energy_aird","company_intelligence","competitors","company_products","news","lng","segments","credit_ratings","macroeconomics","ratings_research","estimates","guidance","rounds_of_funding","business_relationships","transcripts","private_company_financials","keydevs","executive_departures"],"title":"UnderlyingDataset","description":"Underlying Datasets accessed by the agent. Used for evaluations."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"HTTPBearer":{"type":"http","description":"Grab your access token from <a href='/login'>/login</a> (Kensho) or <a href='/login-spgi'>/login-spgi</a> (SPGI)","scheme":"bearer"}}}}