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'