openapi: 3.0.1
info:
  version: 1.0.0
  title: Authorization Tokens Accounts Analyst Highlights API
  description: 'Use the `oauth` endpoint to generate the secure, time-limited JSON Web Tokens (JWTs) used to authorize access to APIs and components.</br></br>

    To request a token, click Authorize and enter the following credentials:


    * Username - Your Client ID.

    * Password - Your Client Secret.'
servers:
- url: https://www.us-api.morningstar.com/token
  description: PROD US
- url: https://www.emea-api.morningstar.com/token
  description: PROD EMEA
- url: https://www.apac-api.morningstar.com/token
  description: PROD APAC
security:
- BasicAuth: []
tags:
- name: Analyst Highlights
paths:
  /direct-web-services/v1/ai-insights/analyst-highlights:
    post:
      tags:
      - Analyst Highlights
      operationId: postMorningstarHighlights
      summary: Request analyst highlights for a list of investments.
      description: "\n#### Request Input\nRequest analyst highlights for the investments specified in the request body. The API accepts:\n\n  * `performanceId` - Morningstar performance ID.\n  * `securityId` - Morningstar security ID. \n  * `isin`\n  * `cusip`\n  * `tradingSymbol`\n  * `fundCode`\n  * `msid` \n  \n  When querying identifiers that may not be globally unique (such as `tradingSymbol`), you can apply additional filters (`baseCurrency`, `domicile`, and `exchangeCountry`) to narrow the results and improve specificity.\n  \n  #### Response\n  \n  A `202 Accepted` response is returned to indicate the server has accepted the request for asynchronous processing.\n  The response includes a `jobId` and a `_links` array with a URL to the `/jobs/{jobId}` endpoint. You use this URL to check the status of the job until it completes.\n  \n  #### Retrieving Output\n  \n  When you poll the `/jobs` endpoint, a `200: OK` response indicates the status of the job.\n  \n  When processing completes, a `302: Found` response is returned. A URL to retrieve the output can be found in the `Location` header.\n  \n"
      parameters:
      - name: Prefer
        in: header
        required: true
        schema:
          type: string
          enum:
          - respond-async
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AiInsightsRequestInput'
            examples:
              exampleInputListOfIdentifersAndFilters:
                summary: List of Identifiers and Filters
                value:
                  investments:
                  - id: DODGX
                    idType: tradingSymbol
                  - id: 0P000000ppY
                    idType: securityId
                  - id: US4138386085
                    idType: isin
                    exchangeCountry: USA
                  - id: '780910105'
                    idType: cusip
                    exchangeCountry: USA
                    domicile: USA
                    baseCurrency: USD
                  - id: AAPL
                    idType: tradingSymbol
                    exchangeCountry: UKR
                  sortBy:
                  - updatedAt
                  orderBy: asc
                  limit: 10
              exampleInputListOfPerformanceIds:
                summary: List of Performance IDs
                value:
                  investments:
                  - id: 0P00000056
                    idType: performanceId
                  - id: 0P00008ICX
                    idType: performanceId
                  - id: 0P0001U4P6
                    idType: performanceId
                  - id: 0P0001UUHN
                    idType: performanceId
                  sortBy:
                  - updatedAt
                  orderBy: asc
                  limit: 10
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncResponse'
              examples:
                '202 Accepted: Get link to check job status.':
                  value:
                    jobId: 16bf1a7a-c883-4424-8810-2f4e9d244d40
                    _links:
                    - href: https://www.us-api.morningstar.com/dynamic-services-apis/jobs/16bf1a7a-c883-4424-8810-2f4e9d244d40
                      rel: self
                      method: GET
                    metadata:
                      requestId: 41ec7d45-4d13-46fc-acf8-292500708eb1
                      time: '2025-06-11T14:23:28.891651Z'
          links:
            GetJobStatus:
              description: Retrieve the status of the async job.
              parameters:
                href: $response.body#/_links/0/href
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
              example:
                statusCode: 400
                errorCode: 400.aiInsights.007
                message: The prefer header is required.
                requestId: 41ec7d45-4d13-46fc-acf8-292500708eb1
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
              example:
                statusCode: 500
                errorCode: 500.aiInsights.002
                message: Async job data not found in S3.
                requestId: 41ec7d45-4d13-46fc-acf8-292500708eb1
  /direct-web-services/v1/ai-insights/results/{resultId}:
    get:
      operationId: getAsyncResults
      tags:
      - Analyst Highlights
      summary: Retrieve analyst highlights.
      description: "When the asynchronous processing job is completed, this endpoint is returned in the `Location` header of the `302 Found` response returned by the `/jobs/{jobId}` endpoint.\n\n  When this endpoint is called, it returns:\n\n  * The AI insights for the investments it successfully identifies and where data is available.\n  * A metadata object listing any input identifiers that could not be matched or for which no data is available.\n"
      parameters:
      - name: resultId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiInsightsResponse'
              examples:
                default:
                  $ref: '#/components/examples/AiInsightsResponseExample'
        '404':
          description: Result not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetails'
components:
  schemas:
    AsyncResponse:
      description: Response returned immediately after submitting an async request.
      type: object
      properties:
        jobId:
          type:
          - string
          - 'null'
          format: uuid
          description: Unique identifier for the async job.
        _links:
          type:
          - array
          - 'null'
          description: Links for interacting with the submitted job. Includes a URL to poll for job status.
          items:
            $ref: '#/components/schemas/ResponseLink'
        metadata:
          $ref: '#/components/schemas/ResponseMetadata'
      additionalProperties: false
    AiInsightsResponse:
      description: Response body returned by the Analyst Highlights results endpoint.
      type: object
      properties:
        investments:
          type:
          - array
          - 'null'
          description: List of investments with AI-generated highlights.
          items:
            $ref: '#/components/schemas/AnalystHighlightsInvestment'
        metadata:
          $ref: '#/components/schemas/ResponseMetadataWithMessages'
      additionalProperties: false
    InvestmentInput:
      description: A single investment identifier submitted in a request.
      required:
      - id
      type: object
      properties:
        id:
          type: string
          minLength: 1
          description: The identifier value for the investment.
        idType:
          type:
          - string
          - 'null'
          description: The type of the identifier supplied in `id`.
          enum:
          - isin
          - cusip
          - performanceId
          - securityId
          - tradingSymbol
          - fundCode
          - msid
          default: performanceId
        baseCurrency:
          type:
          - string
          - 'null'
          description: ISO 4217 three-letter currency code. Used to disambiguate non-unique identifiers such as `tradingSymbol`.
        domicile:
          type:
          - string
          - 'null'
          description: ISO 3166-1 alpha-3 country code for the investment's domicile. Used to disambiguate non-unique identifiers.
        exchangeCountry:
          type:
          - string
          - 'null'
          description: ISO 3166-1 alpha-3 country code for the exchange country. Used to disambiguate non-unique identifiers.
      additionalProperties: false
    ResponseMessage:
      description: A warning or informational message relating to one or more investments.
      type: object
      properties:
        investments:
          type:
          - array
          - 'null'
          description: The investments this message applies to.
          items:
            $ref: '#/components/schemas/InvestmentLookupInputDetails'
        type:
          $ref: '#/components/schemas/MessageType'
        message:
          type:
          - string
          - 'null'
          description: Human-readable description of the warning or issue.
        code:
          type:
          - string
          - 'null'
          description: Machine-readable error or warning code.
      additionalProperties: false
    AnalystHighlightsInvestment:
      description: A single investment with its AI-generated analyst highlight summary.
      type: object
      properties:
        identifiers:
          type:
          - object
          - 'null'
          description: Map of identifier types to their resolved values for this investment. May include `performanceId`, `securityId`, `isin`, `cusip`, `tradingSymbol`, `fundCode`, `msid`, `baseCurrency`, `domicile`, and `exchangeCountry`.
          additionalProperties:
            type:
            - string
            - 'null'
          example:
            performanceId: 0P00002Y8D
            isin: US4138386085
            exchangeCountry: USA
        summary:
          type:
          - string
          - 'null'
          description: AI-generated analyst highlight summary for the investment.
      additionalProperties: false
    InvestmentLookupInputDetails:
      description: Describes an investment referenced in a response message, including its resolved identifiers.
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: The identifier value as supplied in the original request.
        idType:
          type:
          - string
          - 'null'
          description: The identifier type as supplied in the original request.
        companyId:
          type:
          - string
          - 'null'
          description: Resolved Morningstar company ID, if available.
        performanceId:
          type:
          - string
          - 'null'
          description: Resolved Morningstar performance ID, if available.
        baseCurrency:
          type:
          - string
          - 'null'
          description: Base currency filter applied during lookup.
        domicile:
          type:
          - string
          - 'null'
          description: Domicile filter applied during lookup.
        exchangeCountry:
          type:
          - string
          - 'null'
          description: Exchange country filter applied during lookup.
      additionalProperties: false
    MessageType:
      type: string
      description: Indicates whether the message is an informational warning or a hard error.
      enum:
      - Warning
      - Error
    ResponseLink:
      description: A hypermedia link returned in a response.
      type: object
      properties:
        href:
          type:
          - string
          - 'null'
          format: uri
          description: The URL of the linked resource.
        rel:
          type:
          - string
          - 'null'
          description: The relationship of the linked resource to the current response.
        method:
          type:
          - string
          - 'null'
          description: The HTTP method to use when following the link.
          enum:
          - GET
          - POST
          - PUT
          - DELETE
          - PATCH
      additionalProperties: false
    ErrorDetails:
      description: Standard error response body.
      type: object
      properties:
        statusCode:
          type: integer
          format: int32
          description: HTTP status code.
        errorCode:
          type:
          - string
          - 'null'
          description: Morningstar-specific error code (e.g. `400.aiInsights.007`).
        message:
          type:
          - string
          - 'null'
          description: Human-readable description of the error.
        requestId:
          type:
          - string
          - 'null'
          format: uuid
          description: Request identifier to include when contacting support.
      additionalProperties: false
    ResponseMetadata:
      description: Standard metadata included in all responses.
      type: object
      properties:
        requestId:
          type:
          - string
          - 'null'
          format: uuid
          description: Unique identifier for the API request, useful for tracing and support.
        time:
          type: string
          format: date-time
          description: UTC datetime at which the response was generated.
          readOnly: true
      additionalProperties: false
    ResponseMetadataWithMessages:
      description: Standard response metadata, extended with an optional list of warnings or informational messages about the request.
      type: object
      properties:
        messages:
          type:
          - array
          - 'null'
          description: Warnings or informational messages relating to specific investments in the request — for example, unmatched identifiers, duplicate submissions, or missing data coverage.
          items:
            $ref: '#/components/schemas/ResponseMessage'
        requestId:
          type:
          - string
          - 'null'
          format: uuid
          description: Unique identifier for the API request, useful for tracing and support.
        time:
          type: string
          format: date-time
          description: UTC datetime at which the response was generated.
          readOnly: true
      additionalProperties: false
    AiInsightsRequestInput:
      description: Request body for the Analyst Highlights endpoint.
      required:
      - investments
      type: object
      properties:
        investments:
          type: array
          description: List of investments to query.
          items:
            $ref: '#/components/schemas/InvestmentInput'
        sortBy:
          type:
          - array
          - 'null'
          description: Specifies the field(s) to sort results by.
          items:
            type: string
            enum:
            - updatedAt
          default:
          - updatedAt
        orderBy:
          type:
          - string
          - 'null'
          description: Determines the sort direction.
          enum:
          - asc
          - desc
          default: desc
        limit:
          type:
          - integer
          - 'null'
          description: Limits the number of results returned. Must be between 1 and 20.
          format: int32
          minimum: 1
          maximum: 20
          default: 20
          example: 20
      additionalProperties: false
  examples:
    AiInsightsResponseExample:
      summary: Analyst Highlights Response
      value:
        investments:
        - identifiers:
            isin: US4138386085
            performanceId: 0P00002Y8D
            exchangeCountry: USA
          summary: The Oakmark Select strategy, managed by Bill Nygren since 1996, focuses on undervalued stocks with growth potential, typically maintaining 20-25 positions. The strategy has a High rating for People and Above Average for Process, with a Silver Morningstar Medalist Rating. As of March 2025, the top holding is Iqvia at 6.7%. The fund has achieved an 11.5% annualized gain over Nygren's tenure, outperforming the S&P 500's 9.5%, although recent performance has been inconsistent due to market fluctuations and specific holdings like Alphabet and Lithia Motors. The fund's net expense ratio is 0.99%, and it has a total return of 19.08%. While riskier than the broader Oakmark fund, patient investors may benefit from its bold approach. The ticker for the fund is OAKLX, traded on Nasdaq.
        - identifiers:
            tradingSymbol: DODGX
            performanceId: 0P00002PB8
          summary: 'Dodge & Cox Stock (Ticker: DODGX) is managed by a six-member investment committee led by CIO David Hoeft, focusing on fundamental research and contrarian stock selection within a 60- to 90-stock portfolio, maintaining a modest turnover of approximately 30% annually. As of March 2025, sector allocations include 17% in financials and 26% in healthcare. The fund has achieved a 9.2% annualized return since January 2002, outperforming 98% of its peers, with a total return of 12.95%. It holds a Gold Morningstar Medalist Rating and a 4-star Morningstar Star Rating, reflecting its strong performance and reasonable net expense ratio of 0.51%. The firm emphasizes risk management and has enhanced its risk assessment tools, contributing to its High Parent rating due to effective succession planning. While the strategy may experience some volatility, its long-term performance is robust, indicating potential for positive alpha.'
        metadata:
          requestId: 36f8e3e6-56bd-4628-9bbb-791724c995cd
          time: '2025-06-12T12:49:14.1695143Z'
          messages:
          - type: Warning
            code: 404.investmentInsights.101
            message: 'Investment Insights : No data coverage for the investments.'
            investments:
            - id: '780910105'
              idType: cusip
              performanceId: 0P00002COT
              baseCurrency: USD
              domicile: USA
              exchangeCountry: USA
            - id: AAPL
              idType: tradingSymbol
              performanceId: 0P0001ISID
              exchangeCountry: UKR
          - type: Warning
            code: 404.common.125
            message: 'Lookup : Invalid investments.'
            investments:
            - id: 0P000000ppY
              idType: securityId
          - type: Warning
            code: 200.common.126
            message: 'Lookup : Multiple identifier match found for the investments.'
            investments:
            - id: AAPL
              idType: tradingSymbol
              performanceId: 0P0001ISID
              exchangeCountry: UKR
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic