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).
  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:
    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
    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
    AnalyzeConversationTask:
      type: object
      description: The base class of a conversation input task.
      discriminator:
        propertyName: kind
      required:
      - kind
      properties:
        kind:
          $ref: '#/components/schemas/AnalyzeConversationTaskKind'
    AnalyzeConversationJobStatistics:
      description: Contains the statistics for the job submitted.
      properties:
        statistics:
          $ref: '#/components/schemas/ConversationRequestStatistics'
      type: object
    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'
    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
    Modality:
      type: string
      description: Enumeration of supported conversational modalities.
      enum:
      - transcript
      - text
      x-ms-enum:
        name: InputModality
        modelAsString: true
    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
    AnalyzeConversationTaskResult:
      type: object
      description: The base class of a conversation task result.
      discriminator:
        propertyName: kind
      required:
      - kind
      properties:
        kind:
          $ref: '#/components/schemas/AnalyzeConversationTaskResultsKind'
    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
    MultiLanguageConversationAnalysisInput:
      type: object
      required:
      - conversations
      properties:
        conversations:
          type: array
          items:
            $ref: '#/components/schemas/Conversation'
    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'
    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
    AnalyzeConversationResultsKind:
      type: string
      description: Enumeration of supported Conversation Analysis task results.
      enum:
      - ConversationalPIIResults
      - ConversationalSummarizationResults
      - CustomConversationalSummarizationResults
      - ConversationalSentimentResults
      x-ms-enum:
        name: AnalyzeConversationResultsKind
        modelAsString: true
    AnalyzeConversationTaskResultsKind:
      type: string
      description: Enumeration of supported conversational task results
      enum:
      - ConversationResult
      x-ms-enum:
        name: AnalyzeConversationTaskResultsKind
        modelAsString: true
  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