openapi: 3.0.1
info:
  title: Analyst Insights API
  version: '1.0'
servers:
  - url: https://api.benzinga.com/api/v1
paths:
  /analyst/insights:
    get:
      summary: Get analyst insights for a given ticker symbol.
      operationId: getAnalystInsights
      parameters:
        - name: page
          in: query
          required: false
          description: Page number for pagination.
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          required: false
          description: Number of items per page.
          schema:
            type: integer
            default: 10
        - name: symbols
          in: query
          required: false
          description: Stock ticker symbols separated by commas to query for analyst insights.
          schema:
            type: string
            format: csv
        - name: analyst
          in: query
          required: false
          description: One or more analyst ids separated by a comma.
          schema:
            type: string
            format: csv
        - name: rating_id
          in: query
          required: false
          description: One or more rating ids separated by a comma.
          schema:
            type: string
            format: csv
        - name: search_keys_type
          in: query
          required: false
          description: If you wanna query by firm Id or firm name, use this parameter and pass the key. Currently supported are [firm_id, firm]
          schema:
            type: string
            enum:
              - firm_id
              - firm
        - name: search_keys
          in: query
          required: false
          description: If you have selected search_keys_type, pass the appropriate identifier here.
          schema:
            type: string
      responses:
        '200':
          description: An array of analyst insights for the requested ticker symbol.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AnalystInsight'
        '401':
          description: Authentication information is missing or invalid.
        '404':
          description: Analyst insights for the provided ticker symbol were not found.
components:
  schemas:
    AnalystInsight:
      type: object
      properties:
        action:
          type: string
          description: Analyst's action on the stock (e.g., Maintains, Upgrades).
        analyst_insights:
          type: string
          description: Detailed insights from the analyst.
        date:
          type: string
          format: date
          description: Date of the analyst insight.
        firm:
          type: string
          description: Name of the firm providing the insight.
        firm_id:
          type: string
          description: Unique identifier for the firm.
        id:
          type: string
          format: uuid
          description: Unique identifier for the analyst insight.
        pt:
          type: string
          description: Price target given by the analyst.
        rating:
          type: string
          description: Rating provided by the analyst.
        rating_id:
          type: string
          description: Unique identifier for the rating.
        security:
          type: object
          properties:
            cik:
              type: string
            exchange:
              type: string
            isin:
              type: string
            name:
              type: string
            symbol:
              type: string
          description: Security details for which the insight is provided.
        updated:
          type: integer
          format: int64
          description: Timestamp of when the insight was last updated.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: token
security:
  - ApiKeyAuth: []