Bitvore Sentiment Scores API

openapi: 3.2.0
info:
  description: '## Precision News API


    The Precision News APIs provide access to curated news annotated with metadata tags.'
  version: '1.0'
  title: Bitvore Legacy Sentiment Scores API
  license:
    name: Copyright Bitvore Corp. 2026
servers:
- url: https://api.bitvore.com/
tags:
- name: Sentiment Scores
  description: Company Sentiment Score API
paths:
  /sentimentscores:
    get:
      tags:
      - Sentiment Scores
      summary: Sentiment Score Query
      description: '### Sentiment Scores


        Returns the daily sentiment scores of a given type for the specified companies over a period of time. The scores of up to 10 companies identified by their Bitvore ID (BvId) can be returned in a single call. The time period requested can be up to one year. The call options are:

        * BvId - Up to 10 Bitvore ID''s of companies to return scores for.

        * Score - Type of score to return. Options are growth, risk, and sentiment (overall sentiment for a company).

        * Start - First day of the time series to return. In the format of yyyy-MM-dd, 2019-10-01 for example.

        * End - Last day of the time series to return. In the format of yyyy-MM-dd, 2019-10-09 for example.


        The following is an example of using the API to return the growth scores for IBM, BvId b00001ab7, between October 1st and October 7th.


        ```js

        GET /sentimentscores?bvId=b00001ab7&score=growth&start=2019-10-01&end=2019-10-07&key=xyz123 HTTP 1.1

        Accept: application/json

        ```


        The API response will list the timeline of the returned data series as a range. It will then list the scores per day in that range separately for each company requested. The list of scores for a company will be identified by the company''s BvId. An example of a response is as follows:


        ```js

        {

        "success": true,

        "response": {

        {

        "timeline": {

        "start": "2019-10-01",

        "end": "2019-10-07"

        },

        "series": [

        {

        "bvId": "b00001ab7",

        "scores": [

        0.4936433,

        0.4936433,

        0.4936433,

        0.15462846,

        0.15462846,

        0.11870702,

        0.11870702

        ]

        }

        ]

        }

        }

        }

        ```'
      operationId: handleSentimentScoreQueryUsingGET
      parameters:
      - name: bvId
        in: query
        description: Bitvore IDs (up to 10) of organizations to get sentiment scores for.
        required: false
        allowEmptyValue: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: score
        in: query
        description: Type of score to return. Acceptalbe values are sentiment, growth, risk.
        required: false
        allowEmptyValue: false
        schema:
          type: string
      - name: start
        in: query
        description: Day of the first score to return. Format is yyyy-mm-dd.
        required: false
        allowEmptyValue: false
        schema:
          type: string
      - name: end
        in: query
        description: Day of the last score to return. Format is yyyy-mm-dd.
        required: false
        allowEmptyValue: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationSentimentScoreResponseLegacy'
                originalRef: OrganizationSentimentScoreResponseLegacy
        '401':
          description: Unauthorized to view intelligence
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReasonResponse'
                originalRef: ReasonResponse
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReasonResponse'
                originalRef: ReasonResponse
      security:
      - API key:
        - Global
      - BasicAuth:
        - Global
      - OAuth:
        - Global
      deprecated: false
components:
  schemas:
    OrganizationSentimentScoreResponseLegacy:
      type: object
      properties:
        reason:
          type: string
          example: Could not locate subject.
          description: Text reason for the failure (if not successful)
        reasonSupport:
          type: string
          example: Longer description of the missing subject.
          description: Additional information about the failure (if not successful)
        response:
          description: Response payload
          $ref: '#/components/schemas/OrganizationSentimentScoreTimeSeriesLegacy'
          originalRef: OrganizationSentimentScoreTimeSeriesLegacy
        success:
          type: boolean
          example: true
          description: Indicates whether the call was successful or not
      title: OrganizationSentimentScoreResponseLegacy
      description: Response to organization sentiment score queries.
    OrganizationSentimentScoreSeriesLegacy:
      type: object
      properties:
        bvId:
          type: string
          example: b00001ab7
          description: Bitvore Id of the organization with the scores.
        scores:
          type: array
          description: List of floating point numbers representing sentiment scores ranging from -1.0 (negative) to 1.0 (positive).
          items:
            type: number
            format: float
      title: OrganizationSentimentScoreSeriesLegacy
      description: Series of organization sentiment scores.
    TimeSeriesTimeline:
      type: object
      properties:
        end:
          type: string
          example: '2017-07-28'
          description: Last day of the timeline
        start:
          type: string
          example: '2017-06-29'
          description: First day of the timeline
      title: TimeSeriesTimeline
      description: Lists the first and last days of the time series.
    OrganizationSentimentScoreTimeSeriesLegacy:
      type: object
      properties:
        bvId:
          type: string
          example: b00001ab7
          description: Bitvore Id of the organization with the scores.
        series:
          type: array
          description: List of organization scores over the timeline
          items:
            $ref: '#/components/schemas/OrganizationSentimentScoreSeriesLegacy'
            originalRef: OrganizationSentimentScoreSeriesLegacy
        timeline:
          description: Timeline of the time series
          $ref: '#/components/schemas/TimeSeriesTimeline'
          originalRef: TimeSeriesTimeline
      title: OrganizationSentimentScoreTimeSeriesLegacy
      description: Time series of organization sentiment scores.
    ReasonResponse:
      type: object
      properties:
        reason:
          type: string
          example: Could not locate subject.
          description: Text reason for the failure (if not successful)
        reasonSupport:
          type: object
          example: Longer description of the missing subject.
          description: Additional information about the failure (if not successful)
        response:
          type: object
          description: Response payload
        success:
          type: boolean
          example: true
          description: Indicates whether the call was successful or not
      title: ReasonResponse
      description: A response used to explain a failure or issue with the request.
  securitySchemes:
    API_key:
      type: apiKey
      name: X-BV-APIKEY
      in: header
    BasicAuth:
      type: http
      scheme: basic
    OAuth:
      type: oauth2
      flows:
        clientCredentials:
          scopes:
            Global: Includes all Bitvore APIs
          tokenUrl: https://api.bitvore.com/oauth/accesstoken