Microsoft Azure :Analyze Conversations API

openapi: 3.2.0
info:
  title: Microsoft Azure Microsoft Cognitive Language Service…
  description: 'The language service conversations API is a suite of natural language processing (NLP) skills that can be used to analyze structured conversations (textual or spoken). The synchronous API in this suite accepts a request and mediates among multiple language projects, such as LUIS Generally Available, Question Answering, Conversational Language Understanding, and then calls the best candidate service to handle the request. At last, it returns a response with the candidate service''s response as a payload.


    In some cases, this API needs to forward requests and responses between the caller and an upstream service. The asynchronous APIs in this suite enable tasks like Conversation Summarization and Conversational PII detection.'
  version: 2023-04-15-preview
security:
- AADToken:
  - https://cognitiveservices.azure.com/.default
- apim_key: []
tags:
- name: Analyze Conversations
paths:
  /:analyze-conversations:
    post:
      operationId: microsoftAzureConversationanalysisAnalyzeconversation
      description: Analyzes the input conversation utterance.
      parameters:
      - $ref: common.json#/parameters/ApiVersionParameter
      responses:
        '200':
          description: The conversation analysis response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeConversationTaskResult'
        default:
          description: Error response.
          headers:
            x-ms-error-code:
              description: The error code for specific error that occurred.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: common.json#/definitions/ErrorResponse
      x-ms-examples:
        Conversation project result:
          $ref: ./examples/conversations/SuccessfulAnalyzeConversations.json
        Arbitration result:
          $ref: ./examples/conversations/SuccessfulAnalyzeConversationsArbitration.json
        Orchestrator direct target result:
          $ref: ./examples/conversations/SuccessfulAnalyzeConversationsArbitrationDirectTarget.json
      summary: Microsoft Azure Post :analyze Conversations
      tags:
      - Analyze Conversations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeConversationTask'
        description: A single conversational task to execute.
        required: true
  /analyze-conversations/jobs:
    post:
      description: Submit a collection of conversations for analysis. Specify one or more unique tasks to be executed.
      operationId: microsoftAzureAnalyzeconversationSubmitjob
      summary: Microsoft Azure Submit Analysis Job For Conversations
      parameters:
      - $ref: common.json#/parameters/ApiVersionParameter
      responses:
        '202':
          description: A successful call results with an Operation-Location header used to check the status of the analysis job.
          headers:
            Operation-Location:
              schema:
                type: string
        default:
          description: Error response.
          content:
            application/json:
              schema:
                $ref: common.json#/definitions/ErrorResponse
      x-ms-examples:
        Successful Conversational PII Analysis Job Request:
          $ref: ./examples/conversations/SuccessfulConversationPIISubmit.json
        Successful Conversational PII Analysis Exclusion Job Request:
          $ref: ./examples/conversations/SuccessfulConversationPIIExclusionSubmit.json
        Successful Conversational PII Analysis Redaction Job Request:
          $ref: ./examples/conversations/SuccessfulConversationPIIRedactionCharSubmit.json
        Successful Conversation Summarization Analysis Job Request:
          $ref: ./examples/conversations/SuccessfulConversationSummarySubmit.json
        Successful Conversation Summarization Task Submit:
          $ref: ./examples/conversations/SuccessfulConversationSummarizationTaskSubmit.json
        Successful Custom Conversation Summarization Task Submit:
          $ref: ./examples/conversations/SuccessfulCustomConversationSummarizationTaskSubmit.json
        Successful Conversation Sentiment Analysis Job Request:
          $ref: ./examples/conversations/SuccessfulConversationSentimentSubmit.json
      x-ms-long-running-operation: true
      tags:
      - Analyze Conversations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeConversationJobsInput'
        description: The collection of conversations to analyze and one or more tasks to execute.
        required: true
  /analyze-conversations/jobs/{jobId}:
    get:
      description: Get the status of an analysis job. A job may consist of one or more tasks. Once all tasks are succeeded, the job will transition to the succeeded state and results will be available for each task.
      operationId: microsoftAzureAnalyzeconversationJobstatus
      summary: Microsoft Azure Get Analysis Status And Results
      parameters:
      - $ref: common.json#/parameters/ApiVersionParameter
      - $ref: common.json#/parameters/JobId
      - $ref: common.json#/parameters/ShowStats
      responses:
        '200':
          description: Analysis job status and metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyzeConversationJobState'
        default:
          description: Error encountered.
          content:
            application/json:
              schema:
                $ref: common.json#/definitions/ErrorResponse
      x-ms-examples:
        Successful Get Conversation PII Analysis Job Status Request:
          $ref: ./examples/conversations/SuccessfulConversationPIITaskStatusRequest.json
        Successful Get Text Conversation Analysis Exclusion Job Status Request:
          $ref: ./examples/conversations/SuccessfulConversationPIIExclusionTaskStatusRequest.json
        Successful Get Text Conversation Analysis Redaction Job Status Request:
          $ref: ./examples/conversations/SuccessfulConversationPIIRedactionCharTaskStatusRequest.json
        Successful Get Text Conversation Analysis Job Status Request:
          $ref: ./examples/conversations/SuccessfulConversationSummarizationTaskStatusRequest.json
        Successful Get Conversation Sentiment Analysis Job Status Request:
          $ref: ./examples/conversations/SuccessfulConversationSentimentTaskStatusRequest.json
        Successful Get Conversation Summarization Result:
          $ref: ./examples/conversations/SuccessfulConversationSummarizationTaskResult.json
        Successful Get Custom Conversation Summarization Result:
          $ref: ./examples/conversations/SuccessfulCustomConversationSummarizationTaskResult.json
      tags:
      - Analyze Conversations
  /analyze-conversations/jobs/{jobId}:cancel:
    post:
      description: Cancel a long-running Text Analysis conversations job.
      operationId: microsoftAzureAnalyzeconversationCanceljob
      summary: Microsoft Azure Cancel A Long Running Text Analysis Conversations Job
      parameters:
      - $ref: common.json#/parameters/ApiVersionParameter
      - $ref: common.json#/parameters/JobId
      responses:
        '202':
          description: Cancel Job request has been received.
          headers:
            Operation-Location:
              schema:
                type: string
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: common.json#/definitions/ErrorResponse
      x-ms-examples:
        Successful Job Delete Request:
          $ref: ./examples/conversations/SuccessfulAnalyzeConversationsJobsCancelRequest.json
      x-ms-long-running-operation: true
      tags:
      - Analyze Conversations
components:
  schemas:
    AnalyzeConversationResultsKind:
      type: string
      description: Enumeration of supported Conversation Analysis task results.
      enum:
      - ConversationalPIIResults
      - ConversationalSummarizationResults
      - CustomConversationalSummarizationResults
      - ConversationalSentimentResults
      x-ms-enum:
        name: AnalyzeConversationResultsKind
        modelAsString: true
    Modality:
      type: string
      description: Enumeration of supported conversational modalities.
      enum:
      - transcript
      - text
      x-ms-enum:
        name: InputModality
        modelAsString: true
    Conversation:
      type: object
      description: A complete ordered set of utterances (spoken or written), by one or more speakers to be used for analysis.
      discriminator:
        propertyName: modality
      required:
      - id
      - language
      - modality
      properties:
        id:
          description: Unique identifier for the conversation.
          type: string
        language:
          description: The language of the conversation item in BCP-47 format.
          type: string
        modality:
          $ref: '#/components/schemas/Modality'
        domain:
          $ref: '#/components/schemas/ConversationDomain'
    AnalyzeConversationLROTask:
      type: object
      description: The base class for an long running conversation input task.
      discriminator:
        propertyName: kind
      required:
      - kind
      properties:
        kind:
          $ref: '#/components/schemas/AnalyzeConversationLROTaskKind'
      allOf:
      - $ref: common.json#/definitions/TaskIdentifier
    AnalyzeConversationTask:
      type: object
      description: The base class of a conversation input task.
      discriminator:
        propertyName: kind
      required:
      - kind
      properties:
        kind:
          $ref: '#/components/schemas/AnalyzeConversationTaskKind'
    MultiLanguageConversationAnalysisInput:
      type: object
      required:
      - conversations
      properties:
        conversations:
          type: array
          items:
            $ref: '#/components/schemas/Conversation'
    ConversationRequestStatistics:
      type: object
      description: if showStats=true was specified in the request this field will contain information about the request payload.
      required:
      - conversationsCount
      - validConversationsCount
      - erroneousConversationsCount
      properties:
        conversationsCount:
          type: integer
          format: int32
          description: Number of conversations submitted in the request.
        validConversationsCount:
          type: integer
          format: int32
          description: Number of conversations documents. This excludes empty, over-size limit or non-supported languages documents.
        erroneousConversationsCount:
          type: integer
          format: int32
          description: Number of invalid documents. This includes empty, over-size limit or non-supported languages documents.
      allOf:
      - $ref: common.json#/definitions/RequestStatistics
    AnalyzeConversationLROTaskKind:
      type: string
      description: Enumeration of supported analysis tasks on a collection of conversation.
      enum:
      - ConversationalPIITask
      - ConversationalSummarizationTask
      - CustomConversationalSummarizationTask
      - ConversationalSentimentTask
      x-ms-enum:
        name: AnalyzeConversationLROTaskKind
        modelAsString: true
    AnalyzeConversationTaskResultsKind:
      type: string
      description: Enumeration of supported conversational task results
      enum:
      - ConversationResult
      x-ms-enum:
        name: AnalyzeConversationTaskResultsKind
        modelAsString: true
    ConversationDomain:
      type: string
      description: Enumeration of supported conversational domains.
      enum:
      - finance
      - healthcare
      - generic
      x-ms-enum:
        name: ConversationDomain
        modelAsString: true
    AnalyzeConversationJobState:
      description: Contains the status of the analyze conversations job submitted along with related statistics.
      allOf:
      - $ref: common.json#/definitions/JobState
      - $ref: '#/components/schemas/ConversationTasksState'
      - $ref: '#/components/schemas/AnalyzeConversationJobStatistics'
    AnalyzeConversationJobResult:
      type: object
      description: Container for results for all tasks in the conversation job.
      discriminator:
        propertyName: kind
      properties:
        kind:
          $ref: '#/components/schemas/AnalyzeConversationResultsKind'
      allOf:
      - $ref: common.json#/definitions/TaskState
      - $ref: common.json#/definitions/TaskIdentifier
      required:
      - kind
    AnalyzeConversationTaskResult:
      type: object
      description: The base class of a conversation task result.
      discriminator:
        propertyName: kind
      required:
      - kind
      properties:
        kind:
          $ref: '#/components/schemas/AnalyzeConversationTaskResultsKind'
    AnalyzeConversationJobStatistics:
      description: Contains the statistics for the job submitted.
      properties:
        statistics:
          $ref: '#/components/schemas/ConversationRequestStatistics'
      type: object
    AnalyzeConversationTaskKind:
      type: string
      description: Enumeration of supported Conversation tasks.
      enum:
      - Conversation
      x-ms-enum:
        name: AnalyzeConversationTaskKind
        modelAsString: true
    ConversationTasksState:
      description: Contains the state for the tasks being executed as part of the analyze conversation job submitted.
      properties:
        tasks:
          properties:
            completed:
              description: Count of tasks completed successfully.
              type: integer
              format: int32
            failed:
              description: Count of tasks that failed.
              type: integer
              format: int32
            inProgress:
              description: Count of tasks in progress currently.
              type: integer
              format: int32
            total:
              description: Total count of tasks submitted as part of the job.
              type: integer
              format: int32
            items:
              description: List of results from tasks (if available).
              type: array
              items:
                $ref: '#/components/schemas/AnalyzeConversationJobResult'
          required:
          - total
          - completed
          - failed
          - inProgress
          type: object
      required:
      - tasks
      type: object
    AnalyzeConversationJobsInput:
      type: object
      properties:
        displayName:
          description: Optional display name for the analysis job.
          type: string
        analysisInput:
          $ref: '#/components/schemas/MultiLanguageConversationAnalysisInput'
        tasks:
          description: The set of tasks to execute on the input conversation.
          type: array
          items:
            $ref: '#/components/schemas/AnalyzeConversationLROTask'
      required:
      - analysisInput
      - tasks
  securitySchemes:
    AADToken:
      type: oauth2
      flows:
        implicit:
          scopes:
            https://cognitiveservices.azure.com/.default: https://cognitiveservices.azure.com/.default
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
      description: "These are the [Azure Active Directory OAuth2](https://docs.microsoft.com/azure/active-directory/develop/v1-overview) Flows. When paired with [Azure role-based access](https://docs.microsoft.com/azure/role-based-access-control/overview) control it can be used to control access to Azure Maps REST APIs. Azure role-based access controls are used to designate access to one or more Azure Maps resource account or sub-resources. Any user, group, or service principal can be granted access via a  built-in role or a custom role composed of one or more permissions to Azure Maps REST APIs.\n\nTo implement scenarios, we recommend viewing [authentication concepts](https://aka.ms/amauth). In summary, this security definition provides a solution for modeling application(s) via objects capable of access control on specific APIs and scopes.\n\n#### Notes\n* This security definition **requires** the use of the `x-ms-client-id` header to indicate which Azure Maps resource the application is requesting access to. This can be acquired from the [Maps management API](https://aka.ms/amauthdetails).\n* \nThe `Authorization URL` is specific to the Azure public cloud instance. Sovereign clouds have unique Authorization URLs and Azure Active directory configurations. \n* \nThe Azure role-based access control is configured from the [Azure management plane](https://aka.ms/amrbac) via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.\n* \nUsage of the [Azure Maps Web SDK](https://aka.ms/amaadmc) allows for configuration based setup of an application for multiple use cases.\n* Currently, Azure Active Directory [v1.0 or v2.0](https://docs.microsoft.com/azure/active-directory/develop/azure-ad-endpoint-comparison) supports Work, School, and Guests but does not support Personal accounts."
    apim_key:
      type: apiKey
      description: A subscription key for a Language service resource.
      name: Ocp-Apim-Subscription-Key
      in: header
x-ms-parameterized-host:
  hostTemplate: '{Endpoint}/language'
  useSchemePrefix: false
  parameters:
  - $ref: common.json#/parameters/Endpoint