Amazon Transcribe Transcribe Medical Scribe Job API

openapi: 3.1.0
info:
  title: Amazon Transcribe Service Medical Scribe Job API
  version: '2017-10-26'
  description: Generated from AWS's published Smithy model for Amazon Transcribe Service. 4 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://transcribe.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
paths:
  /#DeleteMedicalScribeJob:
    post:
      operationId: DeleteMedicalScribeJob
      summary: Delete Medical Scribe Job
      description: Deletes a Medical Scribe job. To use this operation, specify the name of the job you want to delete using
        MedicalScribeJobName. Job names are case sensitive.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                type: string
        '400':
          description: BadRequestException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/BadRequestException'
        '500':
          description: InternalFailureException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalFailureException'
        '429':
          description: LimitExceededException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/LimitExceededException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - Transcribe.DeleteMedicalScribeJob
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/DeleteMedicalScribeJobRequest'
      tags:
      - Medical Scribe Job
  /#GetMedicalScribeJob:
    post:
      operationId: GetMedicalScribeJob
      summary: Get Medical Scribe Job
      description: Provides information about the specified Medical Scribe job. To view the status of the specified medical
        transcription job, check the MedicalScribeJobStatus field. If the status is COMPLETED, the job is finished. You can
        find the results at the location specified in MedicalScribeOutput. If the status is FAILED, FailureReason provides
        details on why your Medical Scribe job failed. To get a list of your Medical Scribe jobs, use the operation.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/GetMedicalScribeJobResponse'
        '400':
          description: BadRequestException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/BadRequestException'
        '500':
          description: InternalFailureException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalFailureException'
        '429':
          description: LimitExceededException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/LimitExceededException'
        '404':
          description: NotFoundException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/NotFoundException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - Transcribe.GetMedicalScribeJob
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/GetMedicalScribeJobRequest'
      tags:
      - Medical Scribe Job
  /#ListMedicalScribeJobs:
    post:
      operationId: ListMedicalScribeJobs
      summary: List Medical Scribe Jobs
      description: Provides a list of Medical Scribe jobs that match the specified criteria. If no criteria are specified,
        all Medical Scribe jobs are returned. To get detailed information about a specific Medical Scribe job, use the operation.
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ListMedicalScribeJobsResponse'
        '400':
          description: BadRequestException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/BadRequestException'
        '500':
          description: InternalFailureException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalFailureException'
        '429':
          description: LimitExceededException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/LimitExceededException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - Transcribe.ListMedicalScribeJobs
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/ListMedicalScribeJobsRequest'
      tags:
      - Medical Scribe Job
  /#StartMedicalScribeJob:
    post:
      operationId: StartMedicalScribeJob
      summary: Start Medical Scribe Job
      description: 'Transcribes patient-clinician conversations and generates clinical notes. Amazon Web Services HealthScribe
        automatically provides rich conversation transcripts, identifies speaker roles, classifies dialogues, extracts medical
        terms, and generates preliminary clinical notes. To learn more about these features, refer to Amazon Web Services
        HealthScribe. To make a StartMedicalScribeJob request, you must first upload your media file into an Amazon S3 bucket;
        you can then specify the Amazon S3 location of the file using the Media parameter. You must include the following
        parameters in your StartMedicalTranscriptionJob request: DataAccessRoleArn: The ARN of an IAM role with the these
        minimum permissions: read permission on input file Amazon S3 bucket specified in Media, write permission on the Amazon
        S3 bucket specified in OutputBucketName, and full permissions on the KMS key specified in OutputEncryptionKMSKeyId
        (if set). The role should also allow transcribe.amazonaws.com to assume it. Media (MediaFileUri): The Amazon S3 location
        of your media file. MedicalScribeJobName: A custom name you create for your MedicalScribe job that is unique within
        your Amazon Web Services account. OutputBu'
      responses:
        '200':
          description: Success
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/StartMedicalScribeJobResponse'
        '400':
          description: BadRequestException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/BadRequestException'
        '409':
          description: ConflictException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/ConflictException'
        '500':
          description: InternalFailureException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/InternalFailureException'
        '429':
          description: LimitExceededException
          content:
            application/x-amz-json-1.1:
              schema:
                $ref: '#/components/schemas/LimitExceededException'
      parameters:
      - name: X-Amz-Target
        in: header
        required: true
        schema:
          type: string
          enum:
          - Transcribe.StartMedicalScribeJob
      requestBody:
        required: true
        content:
          application/x-amz-json-1.1:
            schema:
              $ref: '#/components/schemas/StartMedicalScribeJobRequest'
      tags:
      - Medical Scribe Job
components:
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical
        request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: transcribe
  schemas:
    BadRequestException:
      type: object
      properties:
        Message:
          type: string
    ClinicalNoteGenerationSettings:
      type: object
      properties:
        NoteTemplate:
          type: string
          enum:
          - HISTORY_AND_PHYSICAL
          - GIRPP
          - BIRP
          - SIRP
          - DAP
          - BEHAVIORAL_SOAP
          - PHYSICAL_SOAP
          description: 'Specify one of the following templates to use for the clinical note summary. The default is HISTORY_AND_PHYSICAL.
            HISTORY_AND_PHYSICAL: Provides summaries for key sections of the clinical documentation. Examples of sections
            include Chief Complaint, History of Present Illness, Review of Systems, Past Medical History, Assessment, and
            Plan. GIRPP: Provides summaries based on the patients progress toward goals. Examples of sections include Goal,
            Intervention, Response, Progress, and Plan. BIRP: Focuses on the patient''s behavioral patterns and responses.
            Examples of sections include Behavior, Inter'
    ConflictException:
      type: object
      properties:
        Message:
          type: string
    DeleteMedicalScribeJobRequest:
      type: object
      properties:
        MedicalScribeJobName:
          type: string
          description: The name of the Medical Scribe job you want to delete. Job names are case sensitive.
      required:
      - MedicalScribeJobName
    GetMedicalScribeJobRequest:
      type: object
      properties:
        MedicalScribeJobName:
          type: string
          description: The name of the Medical Scribe job you want information about. Job names are case sensitive.
      required:
      - MedicalScribeJobName
    GetMedicalScribeJobResponse:
      type: object
      properties:
        MedicalScribeJob:
          $ref: '#/components/schemas/MedicalScribeJob'
    InternalFailureException:
      type: object
      properties:
        Message:
          type: string
    LimitExceededException:
      type: object
      properties:
        Message:
          type: string
    ListMedicalScribeJobsRequest:
      type: object
      properties:
        Status:
          type: string
          enum:
          - QUEUED
          - IN_PROGRESS
          - FAILED
          - COMPLETED
          description: Returns only Medical Scribe jobs with the specified status. Jobs are ordered by creation date, with
            the newest job first. If you do not include Status, all Medical Scribe jobs are returned.
        JobNameContains:
          type: string
          description: Returns only the Medical Scribe jobs that contain the specified string. The search is not case sensitive.
        NextToken:
          type: string
          description: If your ListMedicalScribeJobs request returns more results than can be displayed, NextToken is displayed
            in the response with an associated string. To get the next page of results, copy this string and repeat your request,
            including NextToken with the value of the copied string. Repeat as needed to view all your results.
        MaxResults:
          type: integer
          description: The maximum number of Medical Scribe jobs to return in each page of results. If there are fewer results
            than the value that you specify, only the actual results are returned. If you do not specify a value, a default
            of 5 is used.
    ListMedicalScribeJobsResponse:
      type: object
      properties:
        Status:
          type: string
          enum:
          - QUEUED
          - IN_PROGRESS
          - FAILED
          - COMPLETED
          description: Lists all Medical Scribe jobs that have the status specified in your request. Jobs are ordered by creation
            date, with the newest job first.
        NextToken:
          type: string
          description: If NextToken is present in your response, it indicates that not all results are displayed. To view
            the next set of results, copy the string associated with the NextToken parameter in your results output, then
            run your request again including NextToken with the value of the copied string. Repeat as needed to view all your
            results.
        MedicalScribeJobSummaries:
          type: array
          items:
            $ref: '#/components/schemas/MedicalScribeJobSummary'
          description: Provides a summary of information about each result.
    Media:
      type: object
      properties:
        MediaFileUri:
          type: string
          description: 'The Amazon S3 location of the media file you want to transcribe. For example: s3://DOC-EXAMPLE-BUCKET/my-media-file.flac
            s3://DOC-EXAMPLE-BUCKET/media-files/my-media-file.flac Note that the Amazon S3 bucket that contains your input
            media must be located in the same Amazon Web Services Region where you''re making your transcription request.'
        RedactedMediaFileUri:
          type: string
          description: 'The Amazon S3 location of the media file you want to redact. For example: s3://DOC-EXAMPLE-BUCKET/my-media-file.flac
            s3://DOC-EXAMPLE-BUCKET/media-files/my-media-file.flac Note that the Amazon S3 bucket that contains your input
            media must be located in the same Amazon Web Services Region where you''re making your transcription request.
            RedactedMediaFileUri produces a redacted audio file in addition to a redacted transcript. It is only supported
            for Call Analytics (StartCallAnalyticsJob) transcription requests.'
    MedicalScribeChannelDefinition:
      type: object
      properties:
        ChannelId:
          type: integer
          description: Specify the audio channel you want to define.
        ParticipantRole:
          type: string
          enum:
          - PATIENT
          - CLINICIAN
          description: Specify the participant that you want to flag. The options are CLINICIAN and PATIENT
      required:
      - ChannelId
      - ParticipantRole
    MedicalScribeContext:
      type: object
      properties:
        PatientContext:
          $ref: '#/components/schemas/MedicalScribePatientContext'
    MedicalScribeJob:
      type: object
      properties:
        MedicalScribeJobName:
          type: string
          description: The name of the Medical Scribe job. Job names are case sensitive and must be unique within an Amazon
            Web Services account.
        MedicalScribeJobStatus:
          type: string
          enum:
          - QUEUED
          - IN_PROGRESS
          - FAILED
          - COMPLETED
          description: Provides the status of the specified Medical Scribe job. If the status is COMPLETED, the job is finished
            and you can find the results at the location specified in MedicalScribeOutput If the status is FAILED, FailureReason
            provides details on why your Medical Scribe job failed.
        LanguageCode:
          type: string
          enum:
          - en-US
          description: The language code used to create your Medical Scribe job. US English (en-US) is the only supported
            language for Medical Scribe jobs.
        Media:
          $ref: '#/components/schemas/Media'
        MedicalScribeOutput:
          $ref: '#/components/schemas/MedicalScribeOutput'
        StartTime:
          type: string
          format: date-time
          description: The date and time your Medical Scribe job began processing. Timestamps are in the format YYYY-MM-DD'T'HH:MM:SS.SSSSSS-UTC.
            For example, 2022-05-04T12:32:58.789000-07:00 represents a Medical Scribe job that started processing at 12:32
            PM UTC-7 on May 4, 2022.
        CreationTime:
          type: string
          format: date-time
          description: The date and time the specified Medical Scribe job request was made. Timestamps are in the format YYYY-MM-DD'T'HH:MM:SS.SSSSSS-UTC.
            For example, 2022-05-04T12:32:58.761000-07:00 represents a Medical Scribe job that started processing at 12:32
            PM UTC-7 on May 4, 2022.
        CompletionTime:
          type: string
          format: date-time
          description: The date and time the specified Medical Scribe job finished processing. Timestamps are in the format
            YYYY-MM-DD'T'HH:MM:SS.SSSSSS-UTC. For example, 2022-05-04T12:32:58.761000-07:00 represents a Medical Scribe job
            that finished processing at 12:32 PM UTC-7 on May 4, 2022.
        FailureReason:
          type: string
          description: 'If MedicalScribeJobStatus is FAILED, FailureReason contains information about why the transcription
            job failed. See also: Common Errors.'
        Settings:
          $ref: '#/components/schemas/MedicalScribeSettings'
        DataAccessRoleArn:
          type: string
          description: 'The Amazon Resource Name (ARN) of an IAM role that has permissions to access the Amazon S3 bucket
            that contains your input files, write to the output bucket, and use your KMS key if supplied. If the role that
            you specify doesn’t have the appropriate permissions your request fails. IAM role ARNs have the format arn:partition:iam::account:role/role-name-with-path.
            For example: arn:aws:iam::111122223333:role/Admin. For more information, see IAM ARNs.'
        ChannelDefinitions:
          type: array
          items:
            $ref: '#/components/schemas/MedicalScribeChannelDefinition'
          description: Makes it possible to specify which speaker is on which channel. For example, if the clinician is the
            first participant to speak, you would set ChannelId of the first ChannelDefinition in the list to 0 (to indicate
            the first channel) and ParticipantRole to CLINICIAN (to indicate that it's the clinician speaking). Then you would
            set the ChannelId of the second ChannelDefinition in the list to 1 (to indicate the second channel) and ParticipantRole
            to PATIENT (to indicate that it's the patient speaking).
        MedicalScribeContextProvided:
          type: boolean
          description: Indicates whether the MedicalScribeContext object was provided when the Medical Scribe job was started.
        Tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
          description: Adds one or more custom tags, each in the form of a key:value pair, to the Medical Scribe job. To learn
            more about using tags with Amazon Transcribe, refer to Tagging resources.
    MedicalScribeJobSummary:
      type: object
      properties:
        MedicalScribeJobName:
          type: string
          description: The name of the Medical Scribe job. Job names are case sensitive and must be unique within an Amazon
            Web Services account.
        CreationTime:
          type: string
          format: date-time
          description: The date and time the specified Medical Scribe job request was made. Timestamps are in the format YYYY-MM-DD'T'HH:MM:SS.SSSSSS-UTC.
            For example, 2022-05-04T12:32:58.761000-07:00 represents a Medical Scribe job that started processing at 12:32
            PM UTC-7 on May 4, 2022.
        StartTime:
          type: string
          format: date-time
          description: The date and time your Medical Scribe job began processing. Timestamps are in the format YYYY-MM-DD'T'HH:MM:SS.SSSSSS-UTC.
            For example, 2022-05-04T12:32:58.789000-07:00 represents a Medical Scribe job that started processing at 12:32
            PM UTC-7 on May 4, 2022.
        CompletionTime:
          type: string
          format: date-time
          description: The date and time the specified Medical Scribe job finished processing. Timestamps are in the format
            YYYY-MM-DD'T'HH:MM:SS.SSSSSS-UTC. For example, 2022-05-04T12:32:58.761000-07:00 represents a Medical Scribe job
            that finished processing at 12:32 PM UTC-7 on May 4, 2022.
        LanguageCode:
          type: string
          enum:
          - en-US
          description: The language code used to create your Medical Scribe job. US English (en-US) is the only supported
            language for Medical Scribe jobs.
        MedicalScribeJobStatus:
          type: string
          enum:
          - QUEUED
          - IN_PROGRESS
          - FAILED
          - COMPLETED
          description: Provides the status of the specified Medical Scribe job. If the status is COMPLETED, the job is finished
            and you can find the results at the location specified in MedicalScribeOutput If the status is FAILED, FailureReason
            provides details on why your Medical Scribe job failed.
        FailureReason:
          type: string
          description: 'If MedicalScribeJobStatus is FAILED, FailureReason contains information about why the transcription
            job failed. See also: Common Errors.'
    MedicalScribeOutput:
      type: object
      properties:
        TranscriptFileUri:
          type: string
          description: Holds the Amazon S3 URI for the Transcript.
        ClinicalDocumentUri:
          type: string
          description: Holds the Amazon S3 URI for the Clinical Document.
      required:
      - TranscriptFileUri
      - ClinicalDocumentUri
    MedicalScribePatientContext:
      type: object
      properties:
        Pronouns:
          type: string
          enum:
          - HE_HIM
          - SHE_HER
          - THEY_THEM
          description: The patient's preferred pronouns that the user wants to provide as a context for clinical note generation.
    MedicalScribeSettings:
      type: object
      properties:
        ShowSpeakerLabels:
          type: boolean
          description: Enables speaker partitioning (diarization) in your Medical Scribe output. Speaker partitioning labels
            the speech from individual speakers in your media file. If you enable ShowSpeakerLabels in your request, you must
            also include MaxSpeakerLabels. For more information, see Partitioning speakers (diarization).
        MaxSpeakerLabels:
          type: integer
          description: Specify the maximum number of speakers you want to partition in your media. Note that if your media
            contains more speakers than the specified number, multiple speakers are treated as a single speaker. If you specify
            the MaxSpeakerLabels field, you must set the ShowSpeakerLabels field to true.
        ChannelIdentification:
          type: boolean
          description: Enables channel identification in multi-channel audio. Channel identification transcribes the audio
            on each channel independently, then appends the output for each channel into one transcript. For more information,
            see Transcribing multi-channel audio.
        VocabularyName:
          type: string
          description: The name of the custom vocabulary you want to include in your Medical Scribe request. Custom vocabulary
            names are case sensitive.
        VocabularyFilterName:
          type: string
          description: The name of the custom vocabulary filter you want to include in your Medical Scribe request. Custom
            vocabulary filter names are case sensitive. Note that if you include VocabularyFilterName in your request, you
            must also include VocabularyFilterMethod.
        VocabularyFilterMethod:
          type: string
          enum:
          - remove
          - mask
          - tag
          description: Specify how you want your custom vocabulary filter applied to your transcript. To replace words with
            ***, choose mask. To delete words, choose remove. To flag words without changing them, choose tag.
        ClinicalNoteGenerationSettings:
          $ref: '#/components/schemas/ClinicalNoteGenerationSettings'
    NotFoundException:
      type: object
      properties:
        Message:
          type: string
    StartMedicalScribeJobRequest:
      type: object
      properties:
        MedicalScribeJobName:
          type: string
          description: A unique name, chosen by you, for your Medical Scribe job. This name is case sensitive, cannot contain
            spaces, and must be unique within an Amazon Web Services account. If you try to create a new job with the same
            name as an existing job, you get a ConflictException error.
        Media:
          $ref: '#/components/schemas/Media'
        OutputBucketName:
          type: string
          description: The name of the Amazon S3 bucket where you want your Medical Scribe output stored. Do not include the
            S3:// prefix of the specified bucket. Note that the role specified in the DataAccessRoleArn request parameter
            must have permission to use the specified location. You can change Amazon S3 permissions using the Amazon Web
            Services Management Console. See also Permissions Required for IAM User Roles.
        OutputEncryptionKMSKeyId:
          type: string
          description: 'The Amazon Resource Name (ARN) of a KMS key that you want to use to encrypt your Medical Scribe output.
            KMS key ARNs have the format arn:partition:kms:region:account:key/key-id. For example: arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab.
            For more information, see KMS key ARNs. If you do not specify an encryption key, your output is encrypted with
            the default Amazon S3 key (SSE-S3). Note that the role making the request and the role specified in the DataAccessRoleArn
            request parameter (if present) must have permission to use the specified KMS key.'
        KMSEncryptionContext:
          type: object
          additionalProperties:
            type: string
          description: A map of plain text, non-secret key:value pairs, known as encryption context pairs, that provide an
            added layer of security for your data. For more information, see KMS encryption context and Asymmetric keys in
            KMS.
        DataAccessRoleArn:
          type: string
          description: 'The Amazon Resource Name (ARN) of an IAM role that has permissions to access the Amazon S3 bucket
            that contains your input files, write to the output bucket, and use your KMS key if supplied. If the role that
            you specify doesn’t have the appropriate permissions your request fails. IAM role ARNs have the format arn:partition:iam::account:role/role-name-with-path.
            For example: arn:aws:iam::111122223333:role/Admin. For more information, see IAM ARNs.'
        Settings:
          $ref: '#/components/schemas/MedicalScribeSettings'
        ChannelDefinitions:
          type: array
          items:
            $ref: '#/components/schemas/MedicalScribeChannelDefinition'
          description: Makes it possible to specify which speaker is on which channel. For example, if the clinician is the
            first participant to speak, you would set ChannelId of the first ChannelDefinition in the list to 0 (to indicate
            the first channel) and ParticipantRole to CLINICIAN (to indicate that it's the clinician speaking). Then you would
            set the ChannelId of the second ChannelDefinition in the list to 1 (to indicate the second channel) and ParticipantRole
            to PATIENT (to indicate that it's the patient speaking).
        Tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
          description: Adds one or more custom tags, each in the form of a key:value pair, to the Medical Scribe job. To learn
            more about using tags with Amazon Transcribe, refer to Tagging resources.
        MedicalScribeContext:
          $ref: '#/components/schemas/MedicalScribeContext'
      required:
      - MedicalScribeJobName
      - Media
      - OutputBucketName
      - DataAccessRoleArn
      - Settings
    StartMedicalScribeJobResponse:
      type: object
      properties:
        MedicalScribeJob:
          $ref: '#/components/schemas/MedicalScribeJob'
    Tag:
      type: object
      properties:
        Key:
          type: string
          description: The first part of a key:value pair that forms a tag associated with a given resource. For example,
            in the tag Department:Sales, the key is 'Department'.
        Value:
          type: string
          description: The second part of a key:value pair that forms a tag associated with a given resource. For example,
            in the tag Department:Sales, the value is 'Sales'. Note that you can set the value of a tag to an empty string,
            but you can't set the value of a tag to null. Omitting the tag value is the same as using an empty string.
      required:
      - Key
      - Value
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/transcribe/service/2017-10-26/transcribe-2017-10-26.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)