openapi: 3.0.1 info: title: PortfolioPilot Plugin description: A plugin that acts as your AI investing coach, producing personalized portfolio assessment, recommendations, and answers to all investment-related questions version: 'v1' servers: - url: https://portfoliopilot.com/api/gpt paths: /security_details: get: operationId: getSecurityDetails summary: Get security details for a specific ticker with up to date information from the last 24 hours parameters: - name: ticker in: query description: The ticker symbol of the security required: true schema: type: string - name: include_news_and_ai_sentiment in: query description: Whether to include AI sentiment analysis in the response required: false schema: type: boolean responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/SecurityDetailsResponse' "400": $ref: '#/components/responses/BadRequest' "405": $ref: '#/components/responses/MethodNotAllowed' /top_etfs: get: operationId: getTopETFs summary: Get the top 20 best ETFs based on the provided filters with a lot of additional ETF information. Mention available filters in response parameters: - name: philosophy in: query description: The fund philosophy required: false schema: type: string enum: - "Actively Managed" - "Passively Managed" - "Strategic Beta" - name: is_diversified in: query description: Whether the ETFs should be sufficiently diversified as True or False required: false schema: type: boolean - name: max_expense_ratio in: query description: The maximum expense ratio for the ETFs required: false schema: type: number - name: asset_class in: query description: The asset class to filter by required: false schema: type: string enum: - "US Large Cap Equities" - "US Mid Cap Equities" - "US Small Cap Equities" - "Developed Total Market Equities (Ex-US)" - "Emerging Total Market Equities" - "Private Equity" - "US Government Bonds" - "US Municipal Bonds" - "US Corporate Bonds" - "Developed Total Market Bonds" - "Emerging Total Market Bonds" - "Global Inflation-linked Bonds" - "Gold" - "Other Commodities" - "Real Estate" - "Cryptocurrencies" - "Cash & Equivalents" - "Other Currencies" - "Unknown" - name: listed_country in: query description: The country in which the ETF is listed required: false schema: type: string enum: - "US" - "CA" responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/TopETFsResponse' "400": $ref: '#/components/responses/BadRequest' "405": $ref: '#/components/responses/MethodNotAllowed' /top_stocks: get: operationId: getTopStocks summary: Get the top 20 stocks with the highest expected Sharpe based on the provided filters. parameters: - name: sector in: query description: The sector to filter by required: false schema: type: string enum: - "Healthcare" - "Energy" - "Technology" - "Financial Services" - "Basic Materials" - "Industrials" - "Real Estate" - "Consumer Defensive" - "Manufacturing" - "Consumer Cyclical" - "Communication Services" - "Information" - "Retail Trade" - "Professional, Scientific, and Technical Services" - "Transportation and Warehousing" - "Finance and Insurance" - "Health Care and Social Assistance" - "Utilities" - "Educational Services" - "Mining, Quarrying, and Oil and Gas Extraction" - "Administrative and Support and Waste Management and Remediation Services" - "Agriculture, Forestry, Fishing and Hunting" - "Construction" - "Wholesale Trade" - "Arts, Entertainment, and Recreation" - "Real Estate and Rental and Leasing" - "Accommodation and Food Services" - "Management of Companies and Enterprises" - name: min_marketcap in: query description: The minimum market capitalization for the stocks required: false schema: type: number - name: country in: query description: The country to filter by required: false schema: type: string enum: - "US" - "CA" - name: sort_by in: query description: The parameter to sort by required: false schema: type: string enum: - "expected_sharpe" - "ai_sentiment_score" - "expected_return" - "market_cap" - name: sort_order in: query description: The order to sort by (descending meaning highest to lowest, ascending meaning lowest value first) required: false schema: type: string enum: - "descending" - "ascending" responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/TopStocksResponse' "400": $ref: '#/components/responses/BadRequest' "405": $ref: '#/components/responses/MethodNotAllowed' /portfolio_details: post: operationId: getPortfolioDetails summary: Get all performance details for the given portfolio, best presented in table format requestBody: content: application/json: schema: type: object properties: portfolio: $ref: '#/components/schemas/Portfolio' example: - portfolio: - T: AAPL A: 5000 - T: VTI A: 4000 - T: CUR:USD A: 2000 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/getPortfolioDetailsResponse' "400": $ref: '#/components/responses/BadRequest' "405": $ref: '#/components/responses/MethodNotAllowed' /portfolio_exposures: post: operationId: getPortfolioExposures summary: Get sector, country, and holding exposures for the given portfolio and the markdown of respective charts requestBody: content: application/json: schema: type: object properties: portfolio: type: array items: $ref: '#/components/schemas/Portfolio' example: portfolio: - T: AAPL A: 5000 - T: VWO A: 3000 - T: CUR:USD A: 2000 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/getPortfolioExposuresResponse' "400": $ref: '#/components/responses/BadRequest' "405": $ref: '#/components/responses/MethodNotAllowed' /portfolio_assessment: post: operationId: getAiAssessment summary: Portfolio assessment with summary, downside protection. Each section helps understanding portfolio insights. requestBody: content: application/json: schema: type: object properties: portfolio: $ref: '#/components/schemas/Portfolio' example: - portfolio: - T: AAPL A: 5000 - T: VTI A: 4000 - T: CUR:USD A: 2000 responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/PortfolioAssessmentResponse' "400": $ref: '#/components/responses/BadRequest' "405": $ref: '#/components/responses/MethodNotAllowed' /macro_insights: get: operationId: getMacroInsights summary: Get macro insights of the global economy or a specific region based on the provided filters. Describes what's happening in the economy and how it affects the markets. parameters: - name: region in: query description: The region of the economy to get macro insights for. If not provided, global macro insights will be returned. required: false schema: type: string enum: - "US" - "Canada" - "World" responses: "200": description: OK content: application/json: schema: $ref: '#/components/schemas/MacroInsightsResponse' "400": $ref: '#/components/responses/BadRequest' "405": $ref: '#/components/responses/MethodNotAllowed' components: responses: BadRequest: description: Bad Request content: application/json: schema: type: object properties: status_code: type: integer description: The HTTP status code for the response. example: 400 error: type: string description: A short description of the error. example: Bad Request message: type: string description: A detailed error message explaining the reason for the bad request. example: The request is invalid due to missing or incorrect parameters. MethodNotAllowed: description: Method not allowed (e.g. GET request type is not supported, use POST method instead) content: application/json: schema: type: object properties: message: type: string schemas: SecurityDetailsResponse: type: object description: Response object containing security details for a specific ticker properties: security_details: $ref: '#/components/schemas/SecurityDetails' SecurityDetails: type: object properties: ticker: type: string series_type: type: string volatility: type: number sharpe_ratio: type: number beta: type: number description: The beta of the security (relative co-movement to the market as a whole) listed_exchange: type: string issue_type: type: string price: type: number revenue_per_share: type: number earnings_per_share: type: number dividend_per_share: type: number trading_volume_10_day: type: number trading_volume_30_day: type: number put_call_ratio: type: number enterprise_value: type: number revenue: type: number revenue_per_employee: type: number profit_margin: type: number debt_to_equity: type: number growth_factor: type: number description: The relative exposure of the security to changing macro growth conditions inflation_factor: type: number description: The relative exposure of the security to changing macro inflation conditions liquidity_factor: type: number description: The relative exposure of the security to changing macro liquidity conditions commodities_factor: type: number description: The relative exposure of the security to changing macro commodities factor credit_factor: type: number description: The relative exposure of the security to changing macro credit conditions interest_rates_factor: type: number description: The relative exposure of the security to changing macro interest rate conditions next_earnings_date_factor: type: string next_dividend_date: type: string ex_dividend_date: type: string related_securities: type: array items: type: string description: A list of related securities news: type: array items: $ref: '#/components/schemas/NewsArticle' description: A list of news articles related to the security ai_sentiment: type: number description: The AI-calculated news sentiment weighted by relevance description: type: string description: A description of the security sector: type: string industry: type: string website: type: string employees: type: integer market_cap: type: number investing_method: type: string diversified: type: string expense_ratio: type: number asset_class: type: string sector_exposures: type: array items: $ref: '#/components/schemas/SectorExposure' description: A list of sector exposures for the security country_exposures: type: array items: $ref: '#/components/schemas/CountryExposure' description: A list of country exposures for the security holding_exposures: type: array items: $ref: '#/components/schemas/HoldingExposure' description: A list of holding exposures for the security more_info: type: string description: url to the PortfolioPilot Security Explorer page providing more information (create link) NewsArticle: type: object properties: date: type: string headline: type: string source: type: string url: type: string summary: type: string image_url: type: string api_source: type: string language: type: string author: type: string has_paywall: type: boolean category: type: string relevance: type: string sentiment: type: string SectorExposure: type: object properties: series_name: type: string weight: type: number description: The weight of the sector series in the fund CountryExposure: type: object properties: series_name: type: string description: The name of the country series weight: type: number description: The weight of the country series in the fund HoldingExposure: type: object properties: series_name: type: string weight: type: number description: The weight of the holding series in the fund TopETFsResponse: type: object description: Response object containing the top 10 ETFs based on the provided filters. A lot of ETF-specific information is also provided properties: top_etfs: type: array items: $ref: '#/components/schemas/ETFDetails' ETFDetails: type: object properties: Ticker: type: string beta: type: number description: The beta value of the ETF, indicating its sensitivity to market movements. security_type: type: string sub_asset_class: type: string philosophy: type: string description: The investment philosophy of the ETF (e.g. "Actively Managed"). expense_ratio: type: number concentration_score: type: number description: A score representing the concentration of the ETF's holdings. is_diversified: type: boolean description: Indicates whether the ETF is sufficiently diversified. Company_Growth: type: number description: The company growth factor of the ETF. Company_Quality: type: number description: The company quality factor of the ETF. Company_Size: type: number description: The company size factor of the ETF. Company_Value: type: number description: The company value factor of the ETF. Credit_Conditions: type: number description: The credit conditions factor of the ETF. Economic_Growth: type: number description: The economic growth factor of the ETF. High_Dividend: type: number description: The high dividend factor of the ETF. Inflation_Surprises: type: number description: The inflation surprises factor of the ETF. Low_Volatility: type: number description: The low volatility factor of the ETF. Oil_Price: type: number description: The oil price factor of the ETF. Price_Momentum: type: number description: The price momentum factor of the ETF. Real_Yield: type: number description: The real yield factor of the ETF. VIX_Index: type: number description: The VIX index factor of the ETF. fundName: type: string more_info: type: string description: url to the PortfolioPilot Security Explorer page providing more information (create link) TopStocksResponse: type: object description: Response object containing the top 10 stocks based on the provided filters. A lot of stock-specific information is also provided. properties: top_stocks: type: array items: $ref: '#/components/schemas/StockDetails' StockDetails: type: object properties: Ticker: type: string beta: type: number description: The beta value of the stock, indicating its sensitivity to market movements. security_type: type: string description: The type of security (e.g. "Companies"). sub_asset_class: type: string name: type: string description: The name of the company. country: type: string description: The country where the company is headquartered. exchange: type: string detailed_info: type: string description: Additional detailed information about the stock (if available). sector: type: string industry: type: string marketcap: type: number employees: type: number ceo: type: string similar: type: string description: Similar stocks or companies (if available). logo: type: string description: The logo of the company as a url to a hosted image. url: type: string tags: type: string Company_Growth: type: number description: The company growth factor of the stock. Company_Quality: type: number description: The company quality factor of the stock. Company_Size: type: number description: The company size factor of the stock. Company_Value: type: number description: The company value factor of the stock. Credit_Conditions: type: number description: The credit conditions factor of the stock. Economic_Growth: type: number description: The economic growth factor of the stock. High_Dividend: type: number description: The high dividend factor of the stock. Inflation_Surprises: type: number description: The inflation surprises factor of the stock. Low_Volatility: type: number description: The low volatility factor of the stock. Oil_Price: type: number description: The oil price factor of the stock. Price_Momentum: type: number description: The price momentum factor of the stock. Real_Yield: type: number description: The real yield factor of the stock. VIX_Index: type: number description: The VIX index factor of the stock. seriesName: type: string more_info: type: string description: url to the PortfolioPilot Security Explorer page providing more information (create link) PortfolioAssessmentResponse: type: object properties: expected_performance: $ref: '#/components/schemas/PortfolioExpectedPerformance' downside_protection: $ref: '#/components/schemas/PortfolioDownsideProtection' invest_next_1000: type: array description: Suggestion for which 3 securities to buy if you were to invest more money (e.g. investing the next $1000) items: type: string description: Ticker symbol summary: type: string description: AI assessment of the given portfolio getPortfolioDetailsResponse: type: object properties: portfolio_details: type: array description: Performance details and assumptions for each security in the given portfolio items: $ref: '#/components/schemas/PortfolioDetails' total_amount: type: number description: The total amount invested in the portfolio dividend_return_in_dollars: type: number details_url: type: string description: url to the PortfolioPilot Portfolio Details page providing more information (create link) PortfolioDetails: type: object properties: ticker: type: string weight: type: number description: The proportion of the security within the investment portfolio market_beta: type: number description: The systemic risk of the security compared to the market as a whole getPortfolioExposuresResponse: type: object properties: exposure_dicts: type: object properties: country: type: object additionalProperties: type: number sector: type: object additionalProperties: type: number holding: type: object additionalProperties: type: number country_exposure_chart_markdown: type: string description: Markdown for displaying the country exposure pie chart sector_exposure_chart_markdown: type: string description: Markdown for displaying the sector exposure pie chart holding_exposure_chart_markdown: type: string description: Markdown for displaying the holding exposure pie chart Portfolio: type: array description: Provided portfolio for the user. Use ticker CUR:USD for cash, ticker Reserved.RealEstate for real estate, ticker Reserved.Crypto for cryptocurrencies, ticker Private.MoneyMarket for money market funds items: $ref: '#/components/schemas/Investment' Investment: type: object description: Individual investment within the portfolio. Each cash investment must have its ticker converted to CUR:USD. A (amount) represents the investment's current market value, not the quantity required: - T - A properties: T: type: string description: ticker symbol A: type: number description: amount representing current market value PortfolioExpectedPerformance: type: object description: Expected performance of the given portfolio including Sharpe ratio, volatility properties: volatility: type: number sharpe_ratio: type: number PortfolioDownsideStatusFlag: type: string enum: - good - warning - critical description: An indicator of the status of a specific downside protection component in your investment portfolio. "Good" means the component is in a favorable state, "Warning" indicates caution, and "Critical" suggests a significant concern. PortfolioDownsideComponentStatus: type: object properties: name: type: string description: The name of the downside protection component being assessed (e.g. "Sector Diversification, "Inflation Risk"). score: type: number description: A numerical score representing the performance of the downside protection component. Higher scores are generally better. status: $ref: '#/components/schemas/PortfolioDownsideStatusFlag' is_significant: type: boolean description: Indicates whether the downside protection component has a significant impact on your investment portfolio's risk profile. PortfolioDownsideProtection: type: array items: $ref: '#/components/schemas/PortfolioDownsideComponentStatus' description: A list of downside protection components in your investment portfolio, each with its own assessment and status. MacroInsight: type: object properties: title: type: string description: The title is like a headline that gives a quick idea of what the economic insight is all about. It summarizes the main topic, so you know what to expect when you read further. sub_title: type: string description: The subtitle is like a supporting headline that gives a bit more information about the economic insight chart_markdown: type: string description: Markdown for displaying an economic macro insight providing a visual representation of the insight's data or analysis tags: type: array items: type: string description: The "tags" of an economic macro insight are keywords that describe the insight's topic. They are used to help investors find the insight they are looking for. MacroInsightsResponse: type: object properties: top_macro_insights: type: array description: A list of macro insights for the given region or the entire world items: $ref: '#/components/schemas/MacroInsight'