Microsoft Azure Microsoft Cognitive Language Service

swagger: '2.0'
info:
  title: Microsoft Azure Microsoft Cognitive Language Service
  description: >-
    The language service API is a suite of natural language processing (NLP)
    skills built with best-in-class Microsoft machine learning algorithms.  The
    API can be used to analyze unstructured text for tasks such as sentiment
    analysis, key phrase extraction, language detection and question answering.
    Further documentation can be found in <a
    href="https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/overview">https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/overview</a>.
  version: 2023-04-15-preview
paths: {}
definitions:
  ErrorResponse:
    type: object
    description: Error response.
    additionalProperties: false
    properties:
      error:
        description: The error object.
        $ref: '#/definitions/Error'
    required:
      - error
  Error:
    type: object
    description: The error object.
    additionalProperties: true
    required:
      - code
      - message
    properties:
      code:
        description: One of a server-defined set of error codes.
        $ref: '#/definitions/ErrorCode'
      message:
        type: string
        description: A human-readable representation of the error.
      target:
        type: string
        description: The target of the error.
      details:
        type: array
        description: >-
          An array of details about specific errors that led to this reported
          error.
        items:
          $ref: '#/definitions/Error'
      innererror:
        description: >-
          An object containing more specific information than the current object
          about the error.
        $ref: '#/definitions/InnerErrorModel'
  InnerErrorModel:
    type: object
    description: >-
      An object containing more specific information about the error. As per
      Microsoft One API guidelines -
      https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.
    additionalProperties: false
    required:
      - code
      - message
    properties:
      code:
        description: One of a server-defined set of error codes.
        $ref: '#/definitions/InnerErrorCode'
      message:
        type: string
        description: Error message.
      details:
        type: object
        additionalProperties:
          type: string
        description: Error details.
      target:
        type: string
        description: Error target.
      innererror:
        description: >-
          An object containing more specific information than the current object
          about the error.
        $ref: '#/definitions/InnerErrorModel'
  ErrorCode:
    type: string
    description: Human-readable error code.
    x-ms-enum:
      name: ErrorCode
      modelAsString: true
    enum:
      - InvalidRequest
      - InvalidArgument
      - Unauthorized
      - Forbidden
      - NotFound
      - ProjectNotFound
      - OperationNotFound
      - AzureCognitiveSearchNotFound
      - AzureCognitiveSearchIndexNotFound
      - TooManyRequests
      - AzureCognitiveSearchThrottling
      - AzureCognitiveSearchIndexLimitReached
      - InternalServerError
      - ServiceUnavailable
      - Timeout
      - QuotaExceeded
      - Conflict
      - Warning
  InnerErrorCode:
    type: string
    description: Human-readable error code.
    x-ms-enum:
      name: InnerErrorCode
      modelAsString: true
    enum:
      - InvalidRequest
      - InvalidParameterValue
      - KnowledgeBaseNotFound
      - AzureCognitiveSearchNotFound
      - AzureCognitiveSearchThrottling
      - ExtractionFailure
      - InvalidRequestBodyFormat
      - EmptyRequest
      - MissingInputDocuments
      - InvalidDocument
      - ModelVersionIncorrect
      - InvalidDocumentBatch
      - UnsupportedLanguageCode
      - InvalidCountryHint
  Language:
    type: string
    description: >-
      Language of the text records. This is BCP-47 representation of a language.
      For example, use "en" for English; "es" for Spanish etc. If not set, use
      "en" for English as default.
  RedactionCharacter:
    type: string
    description: >-
      Optional parameter to use a Custom Character to be used for redaction in
      PII responses. Default character will be * as before. We allow specific
      ascii characters for redaction.
    default: '*'
    x-ms-enum:
      name: redactionCharacter
      modelAsString: true
    enum:
      - '!'
      - '#'
      - $
      - '%'
      - '&'
      - '*'
      - +
      - '-'
      - '='
      - '?'
      - '@'
      - ^
      - _
      - '~'
  StringIndexType:
    type: string
    description: >-
      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.
  TaskState:
    description: Returns the current state of the task.
    properties:
      lastUpdateDateTime:
        description: The last updated time in UTC for the task.
        format: date-time
        type: string
      status:
        description: The status of the task at the mentioned last update time.
        enum:
          - notStarted
          - running
          - succeeded
          - failed
          - cancelled
          - cancelling
        x-ms-enum:
          modelAsString: true
          name: State
    required:
      - status
      - lastUpdateDateTime
    type: object
  TaskIdentifier:
    type: object
    description: Base task object.
    properties:
      taskName:
        type: string
  TaskParameters:
    type: object
    description: Base parameters object for a text analysis task.
    properties:
      loggingOptOut:
        type: boolean
        default: false
  PreBuiltTaskParameters:
    type: object
    description: Parameters object for a text analysis task using pre-built models.
    properties:
      modelVersion:
        type: string
        default: latest
    allOf:
      - $ref: '#/definitions/TaskParameters'
  JobState:
    properties:
      displayName:
        type: string
      createdDateTime:
        format: date-time
        type: string
      expirationDateTime:
        format: date-time
        type: string
      jobId:
        type: string
      lastUpdatedDateTime:
        format: date-time
        type: string
      status:
        enum:
          - notStarted
          - running
          - succeeded
          - partiallyCompleted
          - failed
          - cancelled
          - cancelling
        type: string
        x-ms-enum:
          modelAsString: true
          name: State
      errors:
        items:
          $ref: '#/definitions/Error'
        type: array
      nextLink:
        type: string
    required:
      - jobId
      - lastUpdatedDateTime
      - createdDateTime
      - status
  JobErrors:
    properties:
      errors:
        items:
          $ref: '#/definitions/Error'
        type: array
    type: object
  InputError:
    type: object
    description: Contains details of errors encountered during a job execution.
    required:
      - id
      - error
    properties:
      id:
        type: string
        description: The ID of the input.
      error:
        type: object
        description: Error encountered.
        $ref: '#/definitions/Error'
  InputWarning:
    type: object
    description: Contains details of warnings encountered during a job execution.
    required:
      - code
      - message
    properties:
      code:
        type: string
        description: Warning code.
      message:
        type: string
        description: Warning message.
      targetRef:
        type: string
        description: A JSON pointer reference indicating the target object.
  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.
    additionalProperties: true
    description: >-
      if showStats=true was specified in the request this field will contain
      information about the request payload.
  PreBuiltResult:
    type: object
    properties:
      errors:
        type: array
        description: Errors by document id.
        items:
          $ref: '#/definitions/InputError'
      statistics:
        $ref: '#/definitions/RequestStatistics'
      modelVersion:
        type: string
        description: This field indicates which model is used for scoring.
    required:
      - errors
      - modelVersion
  AnswersResult:
    type: object
    description: Represents List of Question Answers.
    additionalProperties: false
    properties:
      answers:
        type: array
        description: Represents Answer Result list.
        items:
          $ref: '#/definitions/KnowledgeBaseAnswer'
  KnowledgeBaseAnswer:
    type: object
    description: Represents knowledge base answer.
    additionalProperties: false
    properties:
      questions:
        type: array
        description: List of questions associated with the answer.
        items:
          type: string
      answer:
        type: string
        description: Answer text.
      confidenceScore:
        type: number
        format: double
        x-ms-client-name: confidence
        description: Answer confidence score, value ranges from 0 to 1.
        maximum: 1
        minimum: 0
      id:
        type: integer
        x-ms-client-name: qnaId
        description: ID of the QnA result.
        format: int32
      source:
        type: string
        description: Source of QnA result.
      metadata:
        type: object
        description: >-
          Metadata associated with the answer, useful to categorize or filter
          question answers.
        additionalProperties:
          type: string
      dialog:
        type: object
        $ref: '#/definitions/KnowledgeBaseAnswerDialog'
      answerSpan:
        type: object
        x-ms-client-name: shortAnswer
        description: Answer span object of QnA with respect to user's question.
        $ref: '#/definitions/AnswerSpan'
  KnowledgeBaseAnswerDialog:
    type: object
    description: Dialog associated with Answer.
    properties:
      isContextOnly:
        type: boolean
        description: >-
          To mark if a prompt is relevant only with a previous question or not.
          If true, do not include this QnA as search result for queries without
          context; otherwise, if false, ignores context and includes this QnA in
          search result.
      prompts:
        type: array
        description: List of prompts associated with the answer.
        maxItems: 20
        items:
          $ref: '#/definitions/KnowledgeBaseAnswerPrompt'
  KnowledgeBaseAnswerPrompt:
    type: object
    description: Prompt for an answer.
    properties:
      displayOrder:
        type: integer
        description: Index of the prompt - used in ordering of the prompts.
        format: int32
      qnaId:
        type: integer
        description: QnA ID corresponding to the prompt.
        format: int32
      displayText:
        type: string
        description: Text displayed to represent a follow up question prompt.
        maxLength: 200
  AnswerSpan:
    type: object
    description: Answer span object of QnA.
    additionalProperties: false
    properties:
      text:
        type: string
        description: Predicted text of answer span.
      confidenceScore:
        type: number
        x-ms-client-name: confidence
        description: Predicted score of answer span, value ranges from 0 to 1.
        format: double
        maximum: 1
        minimum: 0
      offset:
        type: integer
        description: The answer span offset from the start of answer.
        format: int32
      length:
        type: integer
        description: The length of the answer span.
        format: int32
  AnswersOptions:
    type: object
    description: Parameters to query a knowledge base.
    additionalProperties: false
    properties:
      qnaId:
        type: integer
        description: >-
          Exact QnA ID to fetch from the knowledge base, this field takes
          priority over question.
        format: int32
      question:
        type: string
        description: User question to query against the knowledge base.
      top:
        type: integer
        description: Max number of answers to be returned for the question.
        format: int32
      userId:
        type: string
        description: Unique identifier for the user.
      confidenceScoreThreshold:
        type: number
        format: double
        x-ms-client-name: confidenceThreshold
        description: Minimum threshold score for answers, value ranges from 0 to 1.
        maximum: 1
        minimum: 0
      context:
        x-ms-client-name: answerContext
        description: Context object with previous QnA's information.
        $ref: '#/definitions/KnowledgeBaseAnswerContext'
      rankerType:
        type: string
        x-ms-client-name: rankerKind
        description: Type of ranker to be used.
        x-ms-enum:
          name: RankerKind
          modelAsString: true
          values:
            - value: QuestionOnly
              description: Question only ranker.
            - value: Default
              description: Default ranker.
        enum:
          - Default
          - QuestionOnly
      filters:
        description: Filter QnAs based on given metadata list and knowledge base sources.
        $ref: '#/definitions/QueryFilters'
      answerSpanRequest:
        x-ms-client-name: shortAnswerOptions
        description: To configure Answer span prediction feature.
        $ref: '#/definitions/ShortAnswerOptions'
      includeUnstructuredSources:
        type: boolean
        description: (Optional) Flag to enable Query over Unstructured Sources.
  KnowledgeBaseAnswerContext:
    type: object
    description: Context object with previous QnA's information.
    additionalProperties: false
    required:
      - previousQnaId
    properties:
      previousQnaId:
        type: integer
        description: Previous turn top answer result QnA ID.
        format: int32
      previousUserQuery:
        type: string
        x-ms-client-name: previousQuestion
        description: Previous user query.
  QueryFilters:
    type: object
    description: filters over knowledge base.
    additionalProperties: false
    properties:
      metadataFilter:
        type: object
        $ref: '#/definitions/MetadataFilter'
      sourceFilter:
        type: object
        $ref: '#/definitions/SourceFilter'
      logicalOperation:
        type: string
        description: Logical operation used to join metadata filter with source filter.
        $ref: '#/definitions/LogicalOperationKind'
        default: AND
  MetadataFilter:
    type: object
    description: Find QnAs that are associated with the given list of metadata.
    additionalProperties: false
    properties:
      metadata:
        type: array
        items:
          $ref: '#/definitions/MetadataRecord'
      logicalOperation:
        type: string
        description: Operation used to join metadata filters.
        $ref: '#/definitions/LogicalOperationKind'
        default: AND
  MetadataRecord:
    type: object
    description: Object to provide the key value pair for each metadata.
    additionalProperties: false
    required:
      - key
      - value
    properties:
      key:
        type: string
        description: Metadata Key from Metadata dictionary used in the QnA.
      value:
        type: string
        description: Metadata Value from Metadata dictionary used in the QnA.
  SourceFilter:
    type: array
    description: >-
      Find QnAs that are associated with any of the given list of sources in
      knowledge base.
    items:
      type: string
  LogicalOperationKind:
    type: string
    description: Set to 'OR' or 'AND' for using corresponding logical operation.
    x-ms-enum:
      name: LogicalOperationKind
      modelAsString: true
    enum:
      - AND
      - OR
  ShortAnswerOptions:
    type: object
    description: To configure Answer span prediction feature.
    additionalProperties: false
    required:
      - enable
    properties:
      enable:
        type: boolean
        description: Enable or disable Answer Span prediction.
        enum:
          - true
        x-ms-enum:
          name: enable
          modelAsString: false
      confidenceScoreThreshold:
        type: number
        format: double
        x-ms-client-name: confidenceThreshold
        description: >-
          Minimum threshold score required to include an answer span, value
          ranges from 0 to 1.
        maximum: 1
        minimum: 0
      topAnswersWithSpan:
        type: integer
        x-ms-client-name: top
        description: >-
          Number of Top answers to be considered for span prediction from 1 to
          10.
        format: int32
        maximum: 10
        minimum: 1
  Sentiment:
    type: string
    description: Predicted sentiment.
    enum:
      - positive
      - neutral
      - negative
      - mixed
    x-ms-enum:
      name: TextSentiment
      modelAsString: true
      values:
        - value: positive
          description: Positive sentiment.
        - value: neutral
          description: Neutral sentiment.
        - value: negative
          description: Negative sentiment.
        - value: mixed
          description: Mixed sentiment.
  SentimentConfidenceScores:
    type: object
    required:
      - positive
      - neutral
      - negative
    properties:
      positive:
        type: number
        format: double
        description: Confidence score for positive sentiment
      neutral:
        type: number
        format: double
        description: Confidence score for neutral sentiment
      negative:
        type: number
        format: double
        description: Confidence score for negative sentiment
    description: >-
      Represents the confidence scores between 0 and 1 across all sentiment
      classes: positive, neutral, negative.
  AbstractiveSummarizationTaskParametersBase:
    type: object
    description: Supported parameters for an Abstractive Summarization task.
    properties:
      sentenceCount:
        type: integer
        format: int32
        description: >-
          It controls the approximate number of sentences in the output
          summaries.
      stringIndexType:
        $ref: '#/definitions/StringIndexType'
  SummaryContext:
    type: object
    description: The context of the summary.
    required:
      - offset
      - length
    properties:
      offset:
        type: integer
        format: int32
        description: >-
          Start position for the context. Use of different 'stringIndexType'
          values can affect the offset returned.
      length:
        type: integer
        format: int32
        description: >-
          The length of the context. Use of different 'stringIndexType' values
          can affect the length returned.
  CustomTaskParameters:
    type: object
    description: Parameters object for a text analysis task using custom models.
    properties:
      projectName:
        type: string
        description: This field indicates the project name for the model.
      deploymentName:
        type: string
        description: This field indicates the deployment name for the model.
    allOf:
      - $ref: '#/definitions/TaskParameters'
    required:
      - projectName
      - deploymentName
  CustomResult:
    type: object
    properties:
      errors:
        type: array
        description: Errors by document id.
        items:
          $ref: '#/definitions/DocumentError'
      statistics:
        $ref: '#/definitions/RequestStatistics'
      projectName:
        type: string
        description: This field indicates the project name for the model.
      deploymentName:
        type: string
        description: This field indicates the deployment name for the model.
    required:
      - errors
      - projectName
      - deploymentName
  DocumentError:
    type: object
    required:
      - id
      - error
    properties:
      id:
        type: string
        description: Document Id.
      error:
        type: object
        description: Document Error.
        $ref: '#/definitions/Error'
parameters:
  Endpoint:
    name: endpoint
    description: >-
      Supported Cognitive Services endpoint (e.g.,
      https://<resource-name>.api.cognitiveservices.azure.com).
    x-ms-parameter-location: client
    required: true
    type: string
    format: url
    in: path
    x-ms-skip-url-encoding: true
  ProjectNameQueryParameter:
    name: projectName
    in: query
    required: true
    type: string
    description: The name of the project to use.
    x-ms-parameter-location: method
  ProjectNamePathParameter:
    name: projectName
    in: path
    required: true
    type: string
    maxLength: 100
    description: The name of the project to use.
    x-ms-parameter-location: method
  DeploymentNameQueryParameter:
    name: deploymentName
    in: query
    required: true
    type: string
    description: The name of the specific deployment of the project to use.
    x-ms-parameter-location: method
  DeploymentNamePathParameter:
    name: deploymentName
    in: path
    required: true
    type: string
    description: The name of the specific deployment of the project to use.
    x-ms-parameter-location: method
  ApiVersionParameter:
    name: api-version
    in: query
    required: true
    type: string
    description: Client API version.
  TopParameter:
    name: top
    in: query
    description: The maximum number of resources to return from the collection.
    type: integer
    format: int32
    x-ms-parameter-location: method
  SkipParameter:
    name: skip
    in: query
    description: An offset into the collection of the first resource to be returned.
    type: integer
    format: int32
    x-ms-parameter-location: method
  MaxPageSizeParameter:
    name: maxpagesize
    in: query
    description: The maximum number of resources to include in a single response.
    type: integer
    format: int32
    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
  JobId:
    description: Job ID
    format: uuid
    in: path
    name: jobId
    required: true
    type: string
    x-ms-parameter-location: method