swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Sentiment API
schemes:
- https
tags:
- name: Sentiment
paths:
  /sentiment:
    post:
      summary: Microsoft Azure Sentiment
      description: The API returns a detailed sentiment analysis for the input text. The analysis is done in multiple levels of granularity, start from the a document level, down to sentence and key terms (targets and assessments).
      operationId: microsoftAzureSentiment
      consumes:
      - application/json
      - text/json
      produces:
      - application/json
      - text/json
      parameters:
      - $ref: '#/parameters/ModelVersion'
      - $ref: '#/parameters/ShowStats'
      - name: opinionMining
        in: query
        description: (Optional) if set to true, response will contain not only sentiment prediction but also opinion mining (aspect-based sentiment analysis) results.
        type: boolean
      - $ref: '#/parameters/StringIndexType'
      - $ref: '#/parameters/MultiLanguageInput'
      responses:
        '200':
          description: A successful call results in a document sentiment prediction, as well as sentiment scores for each sentiment class (Positive, Negative, and Neutral)
          schema:
            $ref: '#/definitions/SentimentResponse'
        '400':
          description: Bad Request.
          schema:
            $ref: '#/definitions/ErrorResponse'
          x-ms-error-response: true
        '500':
          description: Internal error response
          schema:
            $ref: '#/definitions/ErrorResponse'
          x-ms-error-response: true
      x-ms-examples:
        Successful Sentiment request:
          $ref: .//examples//SuccessfulSentimentRequest.json
      deprecated: false
      tags:
      - Sentiment
definitions:
  SentenceSentiment:
    type: object
    required:
    - text
    - sentiment
    - confidenceScores
    - offset
    - length
    properties:
      text:
        type: string
        description: The sentence text.
      sentiment:
        type: string
        description: The predicted Sentiment for the sentence.
        enum:
        - positive
        - neutral
        - negative
        x-ms-enum:
          name: SentenceSentimentValue
          modelAsString: false
      confidenceScores:
        description: The sentiment confidence score between 0 and 1 for the sentence for all classes.
        $ref: '#/definitions/SentimentConfidenceScorePerLabel'
      offset:
        type: integer
        format: int32
        description: The sentence offset from the start of the document.
      length:
        type: integer
        format: int32
        description: The length of the sentence.
      targets:
        type: array
        description: The array of sentence targets for the sentence.
        items:
          $ref: '#/definitions/SentenceTarget'
      assessments:
        type: array
        description: The array of assessments for the sentence.
        items:
          $ref: '#/definitions/SentenceAssessment'
  MultiLanguageBatchInput:
    type: object
    required:
    - documents
    properties:
      documents:
        type: array
        description: The set of documents to process as part of this batch.
        items:
          $ref: '#/definitions/MultiLanguageInput'
    description: Contains a set of input documents to be analyzed by the service.
  RequestStatistics:
    type: object
    required:
    - documentsCount
    - validDocumentsCount
    - erroneousDocumentsCount
    - transactionsCount
    properties:
      documentsCount:
        type: integer
        format: int32
        description: Number of documents submitted in the request.
      validDocumentsCount:
        type: integer
        format: int32
        description: Number of valid documents. This excludes empty, over-size limit or non-supported languages documents.
      erroneousDocumentsCount:
        type: integer
        format: int32
        description: Number of invalid documents. This includes empty, over-size limit or non-supported languages documents.
      transactionsCount:
        type: integer
        format: int64
        description: Number of transactions for the request.
    description: if showStats=true was specified in the request this field will contain information about the request payload.
  DocumentError:
    type: object
    required:
    - id
    - error
    properties:
      id:
        type: string
        description: Document Id.
      error:
        type: object
        description: Document Error.
        $ref: '#/definitions/TextAnalyticsError'
  DocumentStatistics:
    type: object
    required:
    - charactersCount
    - transactionsCount
    properties:
      charactersCount:
        type: integer
        format: int32
        description: Number of text elements recognized in the document.
      transactionsCount:
        type: integer
        format: int32
        description: Number of transactions for the document.
    description: if showStats=true was specified in the request this field will contain information about the document payload.
  SentenceTarget:
    type: object
    required:
    - confidenceScores
    - length
    - offset
    - relations
    - sentiment
    - text
    properties:
      sentiment:
        type: string
        enum:
        - positive
        - mixed
        - negative
        x-ms-enum:
          name: TokenSentimentValue
          modelAsString: false
        description: Targeted sentiment in the sentence.
      confidenceScores:
        description: Target sentiment confidence scores for the target in the sentence.
        $ref: '#/definitions/TargetConfidenceScoreLabel'
      offset:
        type: integer
        format: int32
        description: The target offset from the start of the sentence.
      length:
        type: integer
        format: int32
        description: The length of the target.
      text:
        type: string
        description: The target text detected.
      relations:
        type: array
        description: The array of either assessment or target objects which is related to the target.
        items:
          $ref: '#/definitions/TargetRelation'
  TextAnalyticsWarning:
    type: object
    required:
    - code
    - message
    properties:
      code:
        type: string
        enum:
        - LongWordsInDocument
        - DocumentTruncated
        x-ms-enum:
          name: WarningCodeValue
          modelAsString: true
        description: Error code.
      message:
        type: string
        description: Warning message.
      targetRef:
        type: string
        description: A JSON pointer reference indicating the target object.
  SentimentResponse:
    type: object
    required:
    - documents
    - errors
    - modelVersion
    properties:
      documents:
        type: array
        description: Sentiment analysis per document.
        items:
          $ref: '#/definitions/DocumentSentiment'
      errors:
        type: array
        description: Errors by document id.
        items:
          $ref: '#/definitions/DocumentError'
      statistics:
        $ref: '#/definitions/RequestStatistics'
      modelVersion:
        type: string
        description: This field indicates which model is used for scoring.
  TargetConfidenceScoreLabel:
    type: object
    required:
    - negative
    - positive
    properties:
      positive:
        type: number
        format: double
      negative:
        type: number
        format: double
    description: 'Represents the confidence scores across all sentiment classes: positive, neutral, negative.'
  MultiLanguageInput:
    type: object
    required:
    - id
    - text
    properties:
      id:
        type: string
        description: A unique, non-empty document identifier.
      text:
        type: string
        description: The input text to process.
      language:
        type: string
        description: (Optional) This is the 2 letter ISO 639-1 representation of a language. For example, use "en" for English; "es" for Spanish etc. If not set, use "en" for English as default.
    description: Contains an input document to be analyzed by the service.
  DocumentSentiment:
    type: object
    required:
    - id
    - sentiment
    - confidenceScores
    - sentences
    - warnings
    properties:
      id:
        type: string
        description: Unique, non-empty document identifier.
      sentiment:
        type: string
        description: Predicted sentiment for document (Negative, Neutral, Positive, or Mixed).
        enum:
        - positive
        - neutral
        - negative
        - mixed
        x-ms-enum:
          name: DocumentSentimentValue
          modelAsString: false
      statistics:
        $ref: '#/definitions/DocumentStatistics'
      confidenceScores:
        description: Document level sentiment confidence scores between 0 and 1 for each sentiment class.
        $ref: '#/definitions/SentimentConfidenceScorePerLabel'
      sentences:
        type: array
        description: Sentence level sentiment analysis.
        items:
          $ref: '#/definitions/SentenceSentiment'
      warnings:
        type: array
        description: Warnings encountered while processing document.
        items:
          $ref: '#/definitions/TextAnalyticsWarning'
  SentimentConfidenceScorePerLabel:
    type: object
    required:
    - positive
    - neutral
    - negative
    properties:
      positive:
        type: number
        format: double
      neutral:
        type: number
        format: double
      negative:
        type: number
        format: double
    description: 'Represents the confidence scores between 0 and 1 across all sentiment classes: positive, neutral, negative.'
  ErrorResponse:
    type: object
    required:
    - error
    properties:
      error:
        type: object
        description: Document Error.
        $ref: '#/definitions/TextAnalyticsError'
  SentenceAssessment:
    type: object
    required:
    - confidenceScores
    - isNegated
    - length
    - offset
    - sentiment
    - text
    properties:
      sentiment:
        type: string
        enum:
        - positive
        - mixed
        - negative
        x-ms-enum:
          name: TokenSentimentValue
          modelAsString: false
        description: Assessment sentiment in the sentence.
      confidenceScores:
        description: Assessment sentiment confidence scores in the sentence.
        $ref: '#/definitions/TargetConfidenceScoreLabel'
      offset:
        type: integer
        format: int32
        description: The assessment offset from the start of the sentence.
      length:
        type: integer
        format: int32
        description: The length of the assessment.
      text:
        type: string
        description: The assessment text detected.
      isNegated:
        type: boolean
        description: The indicator representing if the assessment is negated.
  TargetRelation:
    type: object
    required:
    - ref
    - relationType
    properties:
      relationType:
        type: string
        enum:
        - assessment
        - target
        x-ms-enum:
          name: TargetRelationType
          modelAsString: false
        description: The type related to the target.
      ref:
        type: string
        description: The JSON pointer indicating the linked object.
  InnerError:
    type: object
    required:
    - code
    - message
    properties:
      code:
        type: string
        enum:
        - InvalidParameterValue
        - InvalidRequestBodyFormat
        - EmptyRequest
        - MissingInputRecords
        - InvalidDocument
        - ModelVersionIncorrect
        - InvalidDocumentBatch
        - UnsupportedLanguageCode
        - InvalidCountryHint
        x-ms-enum:
          name: InnerErrorCodeValue
          modelAsString: true
        description: Error code.
      message:
        type: string
        description: Error message.
      details:
        type: object
        additionalProperties:
          type: string
        description: Error details.
      target:
        type: string
        description: Error target.
      innererror:
        $ref: '#/definitions/InnerError'
        description: Inner error contains more specific information.
  TextAnalyticsError:
    type: object
    required:
    - code
    - message
    properties:
      code:
        type: string
        enum:
        - InvalidRequest
        - InvalidArgument
        - InternalServerError
        - ServiceUnavailable
        - NotFound
        x-ms-enum:
          name: ErrorCodeValue
          modelAsString: false
        description: Error code.
      message:
        type: string
        description: Error message.
      target:
        type: string
        description: Error target.
      innererror:
        $ref: '#/definitions/InnerError'
        description: Inner error contains more specific information.
      details:
        type: array
        description: Details about specific errors that led to this reported error.
        items:
          $ref: '#/definitions/TextAnalyticsError'
parameters:
  ModelVersion:
    name: model-version
    in: query
    description: '(Optional) This value indicates which model will be used for scoring. If a model-version is not specified, the API should default to the latest, non-preview version. '
    type: string
    required: false
    x-ms-parameter-location: method
  ShowStats:
    name: showStats
    in: query
    description: (Optional) if set to true, response will contain request and document level statistics.
    type: boolean
    required: false
    x-ms-parameter-location: method
  MultiLanguageInput:
    in: body
    name: input
    description: Collection of documents to analyze.
    required: true
    schema:
      $ref: '#/definitions/MultiLanguageBatchInput'
    x-ms-parameter-location: method
  StringIndexType:
    name: stringIndexType
    in: query
    type: string
    description: (Optional) Specifies the method used to interpret string offsets.  Defaults to Text Elements (Graphemes) according to Unicode v8.0.0. For additional information see https://aka.ms/text-analytics-offsets
    default: TextElements_v8
    enum:
    - TextElements_v8
    - UnicodeCodePoint
    - Utf16CodeUnit
    x-ms-enum:
      name: StringIndexType
      modelAsString: true
      values:
      - value: TextElements_v8
        description: Returned offset and length values will correspond to TextElements (Graphemes and Grapheme clusters) confirming to the Unicode 8.0.0 standard. Use this option if your application is written in .Net Framework or .Net Core and you will be using StringInfo.
      - value: UnicodeCodePoint
        description: Returned offset and length values will correspond to Unicode code points. Use this option if your application is written in a language that support Unicode, for example Python.
      - value: Utf16CodeUnit
        description: Returned offset and length values will correspond to UTF-16 code units. Use this option if your application is written in a language that support Unicode, for example Java, JavaScript.
    x-ms-parameter-location: method
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'