{"openapi":"3.1.0","info":{"title":"OpticAlpha Terminal (Public API)","description":"Public, unauthenticated OpticAlpha endpoints only. This production schema omits every route that requires a user session, an internal key, or admin access — see https://opticalpha.net/auth.md for the agent authentication flow that unlocks the rest of the API.","version":"1.0.0"},"paths":{"/health":{"get":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"head":{"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/":{"get":{"tags":["Pages"],"summary":"Landing","operationId":"landing__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/terminal":{"get":{"tags":["Pages"],"summary":"Terminal","operationId":"terminal_terminal_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/pricing":{"get":{"tags":["Pages"],"summary":"Pricing","operationId":"pricing_pricing_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/login":{"get":{"tags":["Pages"],"summary":"Login","operationId":"login_login_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/signup":{"get":{"tags":["Pages"],"summary":"Signup","operationId":"signup_signup_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/billing":{"get":{"tags":["Pages"],"summary":"Billing","operationId":"billing_billing_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/callback":{"get":{"tags":["Pages"],"summary":"Callback","operationId":"callback_callback_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/terms":{"get":{"tags":["Pages"],"summary":"Terms","operationId":"terms_terms_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/privacy":{"get":{"tags":["Pages"],"summary":"Privacy","operationId":"privacy_privacy_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/llms.txt":{"get":{"tags":["Pages"],"summary":"Llms Txt","operationId":"llms_txt_llms_txt_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/admin":{"get":{"tags":["Pages"],"summary":"Admin","operationId":"admin_admin_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/ticker-search-data":{"get":{"tags":["Research"],"summary":"Ticker Search Data","description":"Returns the ultra-fast cached ticker list for frontend autocomplete.","operationId":"ticker_search_data_api_ticker_search_data_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/research/popular-narratives":{"get":{"tags":["Research"],"summary":"Popular Narratives","description":"Returns 100 most popular US stock narratives. Cached 24h.","operationId":"popular_narratives_api_research_popular_narratives_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/user/timezone":{"get":{"summary":"Get Timezone","operationId":"get_timezone_user_timezone_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/posts":{"get":{"tags":["Blog"],"summary":"Get Posts","description":"Optional ?category= filters to one topic (e.g. for the feature-page\n'Related reading' widget). Falls back to the unfiltered latest-100 feed\nwhen omitted or invalid, same as before.","operationId":"get_posts_api_posts_get","parameters":[{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/posts/{slug}":{"get":{"tags":["Blog"],"summary":"Get Single Post","operationId":"get_single_post_api_posts__slug__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/feed.xml":{"get":{"tags":["Blog"],"summary":"Get Rss Feed","operationId":"get_rss_feed_feed_xml_get","responses":{"200":{"description":"Successful Response"}}}},"/sitemap.xml":{"get":{"tags":["Blog"],"summary":"Get Sitemap","operationId":"get_sitemap_sitemap_xml_get","responses":{"200":{"description":"Successful Response"}}}},"/llms-full.txt":{"get":{"tags":["Blog"],"summary":"Get Llms Full","operationId":"get_llms_full_llms_full_txt_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/blog":{"get":{"tags":["Blog"],"summary":"Serve Blog Index","operationId":"serve_blog_index_blog_get","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"title":"Page"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/blog/topic/{category}":{"get":{"tags":["Blog"],"summary":"Serve Blog Topic","description":"Category pillar page — lists posts in one topic cluster.","operationId":"serve_blog_topic_blog_topic__category__get","parameters":[{"name":"category","in":"path","required":true,"schema":{"type":"string","title":"Category"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"title":"Page"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/blog/{category}/{slug}":{"get":{"tags":["Blog"],"summary":"Serve Blog Post","description":"Clustered post URL. Self-heals: if the URL category ≠ the post's canonical\ncategory, 301 to the correct path.","operationId":"serve_blog_post_blog__category___slug__get","parameters":[{"name":"category","in":"path","required":true,"schema":{"type":"string","title":"Category"}},{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/blog/{slug}":{"get":{"tags":["Blog"],"summary":"Serve Blog Frontend","operationId":"serve_blog_frontend_blog__slug__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"title":"Page"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/institutions/fund-search-data":{"get":{"tags":["Institutions"],"summary":"Institutions Fund Search Data","description":"Comprehensive list of 13F filers for the current quarter — used for autocomplete.\nFalls back to the hardcoded FUNDS constant if SEC EDGAR is unavailable or still loading.","operationId":"institutions_fund_search_data_api_institutions_fund_search_data_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/http-message-signatures-directory":{"get":{"tags":["Agent Discovery"],"summary":"Http Message Signatures Directory","operationId":"http_message_signatures_directory__well_known_http_message_signatures_directory_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/api-catalog":{"get":{"tags":["Agent Discovery"],"summary":"Api Catalog","operationId":"api_catalog__well_known_api_catalog_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/oauth-protected-resource":{"get":{"tags":["Agent Discovery"],"summary":"Oauth Protected Resource","operationId":"oauth_protected_resource__well_known_oauth_protected_resource_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/oauth-authorization-server":{"get":{"tags":["Agent Discovery"],"summary":"Oauth Authorization Server","operationId":"oauth_authorization_server__well_known_oauth_authorization_server_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/mcp/server-card.json":{"get":{"tags":["Agent Discovery"],"summary":"Mcp Server Card","operationId":"mcp_server_card__well_known_mcp_server_card_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/agent-card.json":{"get":{"tags":["Agent Discovery"],"summary":"A2A Agent Card","operationId":"a2a_agent_card__well_known_agent_card_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/agent-skills/index.json":{"get":{"tags":["Agent Discovery"],"summary":"Agent Skills Index","operationId":"agent_skills_index__well_known_agent_skills_index_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/auth.md":{"get":{"tags":["Agent Discovery"],"summary":"Auth Md","operationId":"auth_md_auth_md_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/58ekughzu7mcqq1avpfmx9n6bzjjfq4z.txt":{"get":{"tags":["Agent Discovery"],"summary":"Indexnow Key","operationId":"indexnow_key_58ekughzu7mcqq1avpfmx9n6bzjjfq4z_txt_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/demo/research":{"get":{"tags":["Public Demo"],"summary":"Demo Research","description":"Public landing-page demo of /api/research, whitelist-restricted.","operationId":"demo_research_api_demo_research_get","parameters":[{"name":"ticker","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":10,"title":"Ticker"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/demo/options-research":{"get":{"tags":["Public Demo"],"summary":"Demo Options Research","description":"Public landing-page demo of /api/options-research, whitelist-restricted.","operationId":"demo_options_research_api_demo_options_research_get","parameters":[{"name":"ticker","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":10,"title":"Ticker"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/demo/analyst-details/{security_id}":{"get":{"tags":["Public Demo"],"summary":"Demo Analyst Details","description":"Public demo of /api/analyst/security/{id}/details, locked to one security.","operationId":"demo_analyst_details_api_demo_analyst_details__security_id__get","parameters":[{"name":"security_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":20,"title":"Security Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/demo/fund-holdings":{"get":{"tags":["Public Demo"],"summary":"Demo Fund Holdings","description":"Public demo of /api/fund-holdings, locked to one fund.","operationId":"demo_fund_holdings_api_demo_fund_holdings_get","parameters":[{"name":"fund_id","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":100,"title":"Fund Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/demo/holding-history":{"get":{"tags":["Public Demo"],"summary":"Demo Holding History","description":"Public demo of /api/institutions/holding-history, locked to one CIK.","operationId":"demo_holding_history_api_demo_holding_history_get","parameters":[{"name":"cik","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":20,"title":"Cik"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/demo/ticker-strip":{"get":{"tags":["Public Demo"],"summary":"Demo Ticker Strip","description":"Public landing-page ticker marquee: fixed whitelist, no query params.","operationId":"demo_ticker_strip_api_demo_ticker_strip_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/data/{slug}":{"get":{"tags":["Public Data"],"summary":"Get Data Page","operationId":"get_data_page_data__slug__get","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","title":"Slug"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/data":{"get":{"tags":["Public Data"],"summary":"Get Data Hub","operationId":"get_data_hub_data_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/agent/identity":{"post":{"tags":["Agent Auth"],"summary":"Agent Identity","operationId":"agent_identity_agent_identity_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/agent/claim/complete":{"post":{"tags":["Agent Auth"],"summary":"Agent Claim Complete","description":"Called by callback.html after Auth0 login to mark a pending claim as completed.","operationId":"agent_claim_complete_agent_claim_complete_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/agent/identity/claim":{"post":{"tags":["Agent Auth"],"summary":"Agent Identity Claim","operationId":"agent_identity_claim_agent_identity_claim_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/oauth2/token":{"post":{"tags":["Agent Auth"],"summary":"Oauth2 Token","operationId":"oauth2_token_oauth2_token_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/share-card":{"post":{"tags":["Share Card"],"summary":"Create Share Card","operationId":"create_share_card_api_share_card_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareCardRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/s/{sid}.png":{"get":{"tags":["Share Card"],"summary":"Serve Share Png","operationId":"serve_share_png_s__sid__png_get","parameters":[{"name":"sid","in":"path","required":true,"schema":{"type":"string","title":"Sid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/s/{sid}":{"get":{"tags":["Share Card"],"summary":"Serve Share Page","operationId":"serve_share_page_s__sid__get","parameters":[{"name":"sid","in":"path","required":true,"schema":{"type":"string","title":"Sid"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/shared":{"get":{"tags":["Share Card"],"summary":"Shared Gallery","operationId":"shared_gallery_shared_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/img-proxy":{"get":{"tags":["Image Proxy"],"summary":"Img Proxy","operationId":"img_proxy_api_img_proxy_get","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","maxLength":1024,"title":"Url"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/status":{"get":{"tags":["Status"],"summary":"Get Status","operationId":"get_status_api_status_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ShareCardRequest":{"properties":{"png":{"type":"string","title":"Png"},"channel":{"type":"string","title":"Channel","default":"chart"},"title":{"type":"string","title":"Title","default":""},"turnstile":{"type":"string","title":"Turnstile","default":""}},"type":"object","required":["png"],"title":"ShareCardRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}