openapi: 3.2.0
info:
  title: pyannoteAI Jobs API
  description: ''
  version: local
  contact: {}
  termsOfService: https://pyannote.ai/terms-of-use
servers:
- url: https://api.pyannote.ai
tags:
- name: Jobs
paths:
  /v1/jobs/{jobId}:
    get:
      operationId: getJobById
      parameters:
      - name: jobId
        required: true
        in: path
        description: Job ID to track the progress
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/DiarizationJob'
                  title: Diarization
                - $ref: '#/components/schemas/VoiceprintJob'
                  title: Voiceprint
                - $ref: '#/components/schemas/IdentifyJob'
                  title: Identification
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '402':
          description: Subscription is required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
      - api-key: []
      summary: Get job by ID
      tags:
      - Jobs
      x-api-key-permissions:
      - jobs:read
  /v2/jobs:
    get:
      operationId: getJobsByTeamV2
      parameters:
      - name: limit
        required: false
        in: query
        description: Number of jobs to return
        schema:
          minimum: 1
          maximum: 100
          default: 10
          example: 10
          type: number
      - name: cursor
        required: false
        in: query
        description: Cursor for pagination. Pass the `nextCursor` value from the previous response.
        schema:
          format: uuid
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
          type: string
      - name: status
        required: false
        in: query
        description: Status of the jobs to return
        schema:
          example: succeeded
          type: string
          enum:
          - pending
          - created
          - succeeded
          - canceled
          - failed
          - running
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetJobsResponseV2'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '402':
          description: Subscription is required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
      - api-key: []
      summary: Get all jobs
      tags:
      - Jobs
      x-api-key-permissions:
      - jobs:read
components:
  schemas:
    ValidationError:
      type: object
      properties:
        field:
          type: string
          description: Field name
          example: url
        message:
          type: string
          description: Error message
          example: Invalid URL
      required:
      - field
      - message
    JobListItem:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
        createdAt:
          format: date-time
          type: string
      required:
      - id
      - status
      - createdAt
    TranscriptionSegment:
      type: object
      properties:
        start:
          type: number
          description: Start time of the segment in seconds
        end:
          type: number
          description: End time of the segment in seconds
        text:
          type: string
          description: The transcribed speech content for this segment
        speaker:
          type: string
          description: Speaker label
      required:
      - start
      - end
      - text
      - speaker
    DiarizationSegment:
      type: object
      properties:
        speaker:
          type: string
          description: Speaker label
          example: SPEAKER_00
        start:
          type: number
          description: Start time of the segment in seconds
          example: 15
        end:
          type: number
          description: End time of the segment in seconds
          example: 30.5
        confidence:
          type: object
          description: Confidence scores that this speech turn matches each diarization speaker. Only available if `turnLevelConfidence` is set to true when job is created.
          example:
            SPEAKER_00: 16
            SPEAKER_01: 93
      required:
      - speaker
      - start
      - end
    IdentificationSegment:
      type: object
      properties:
        speaker:
          type: string
          description: Speaker label
          example: SPEAKER_00
        start:
          type: number
          description: Start time of the segment in seconds
          example: 15
        end:
          type: number
          description: End time of the segment in seconds
          example: 30.5
        confidence:
          type: object
          description: Confidence scores that this speech turn matches each diarization speaker. Only available if `turnLevelConfidence` is set to true when job is created.
          example:
            SPEAKER_00: 16
            SPEAKER_01: 93
        diarizationSpeaker:
          type: string
          description: Speaker label
          example: SPEAKER_00
        match:
          type:
          - string
          - 'null'
          description: Label of the voiceprint that was identified following the matching settings
          example: Sam
      required:
      - diarizationSpeaker
      - match
    ValidationErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message
          example: Invalid request
        errors:
          description: List of errors
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
      required:
      - message
      - errors
    Confidence:
      type: object
      properties:
        score:
          description: List of confidence scores for each sample. Values are between 0 and 100
          example:
          - 95
          - 89
          - 78
          - 67
          - 56
          - 45
          - 34
          - 23
          - 12
          - 1
          type: array
          items:
            type: number
        resolution:
          type: number
          description: Resolution of the confidence scores. Value is number of seconds per sample
          example: 0.02
      required:
      - score
      - resolution
    GetJobsResponseV2:
      type: object
      properties:
        items:
          description: List of jobs. Sorted by creation date, descending. Does not include output data.
          type: array
          items:
            $ref: '#/components/schemas/JobListItem'
        nextCursor:
          type:
          - string
          - 'null'
          description: Cursor to pass as `cursor` query param to get the next page. Null if there are no more results.
          example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
      required:
      - items
      - nextCursor
    IdentifyJob:
      type: object
      properties:
        jobId:
          type: string
          description: Job ID to track the progress or get the results
          example: fb16c565-f3f0-4402-a08c-9d44df0ccc7b
        status:
          description: Status of the job
          allOf:
          - $ref: '#/components/schemas/JobStatus'
        createdAt:
          format: date-time
          type: string
          description: Date and time the job was created
          example: '2024-02-20T12:00:00Z'
        updatedAt:
          format: date-time
          type: string
          description: Date and time the job was last updated
          example: '2024-02-20T12:00:00Z'
        output:
          description: Output segments of an identification job, available for 24 hours after job completion
          allOf:
          - $ref: '#/components/schemas/IdentificationJobOutput'
    ApiError:
      type: object
      properties:
        requestId:
          type: string
          description: Request ID
          example: 37a4c3a0-b034-4e8c-9ed9-76da6645544a
        message:
          type: string
          description: Error message
          example: Error message
      required:
      - requestId
      - message
    VoiceprintJob:
      type: object
      properties:
        jobId:
          type: string
          description: Job ID to track the progress or get the results
          example: fb16c565-f3f0-4402-a08c-9d44df0ccc7b
        status:
          description: Status of the job
          allOf:
          - $ref: '#/components/schemas/JobStatus'
        createdAt:
          format: date-time
          type: string
          description: Date and time the job was created
          example: '2024-02-20T12:00:00Z'
        updatedAt:
          format: date-time
          type: string
          description: Date and time the job was last updated
          example: '2024-02-20T12:00:00Z'
        output:
          description: Output of a voiceprint job, available for 24 hours after job completion
          allOf:
          - $ref: '#/components/schemas/VoiceprintJobResults'
    IdentificationVoiceprint:
      type: object
      properties:
        speaker:
          type: string
          description: Diarization speaker
          example: SPEAKER_00
        match:
          type: string
          description: Label of the voiceprint that was identified following the matching settings
          example: Sam
        confidence:
          type: object
          description: Confidence for each speaker label, as a dictionary of speaker label to confidence score
          example:
            Sam: 16
            Rick: 24
      required:
      - speaker
      - match
      - confidence
    VoiceprintJobResults:
      type: object
      properties:
        voiceprint:
          type: string
          description: Voiceprint of the audio. To be used for identification
          example: aGVsbG8gd29ybGQ
        warning:
          type: string
          description: Warning message if any
        error:
          type: string
          description: Error message if any
      required:
      - voiceprint
    JobStatus:
      type: string
      enum:
      - pending
      - created
      - succeeded
      - canceled
      - failed
      - running
      description: Status of the job
    DiarizationJob:
      type: object
      properties:
        jobId:
          type: string
          description: Job ID to track the progress or get the results
          example: fb16c565-f3f0-4402-a08c-9d44df0ccc7b
        status:
          description: Status of the job
          allOf:
          - $ref: '#/components/schemas/JobStatus'
        createdAt:
          format: date-time
          type: string
          description: Date and time the job was created
          example: '2024-02-20T12:00:00Z'
        updatedAt:
          format: date-time
          type: string
          description: Date and time the job was last updated
          example: '2024-02-20T12:00:00Z'
        output:
          description: Output segments of a diarization, available for 24 hours after job completion
          allOf:
          - $ref: '#/components/schemas/DiarizationJobOutput'
    IdentificationJobOutput:
      type: object
      properties:
        diarization:
          description: List of diarization segments
          type: array
          items:
            $ref: '#/components/schemas/DiarizationSegment'
        confidence:
          description: Confidence scores details. Only returned if `confidence` is set to true when job is created
          allOf:
          - $ref: '#/components/schemas/Confidence'
        exclusiveDiarization:
          description: Exclusive diarization segments where only one speaker is active at a time. Only returned if `exclusive` is set to true when job is created.
          type: array
          items:
            $ref: '#/components/schemas/DiarizationSegment'
        error:
          type: string
          description: Error message if any
        warning:
          type: string
          description: Warning message if any
        identification:
          description: List of identification segments
          type: array
          items:
            $ref: '#/components/schemas/IdentificationSegment'
        voiceprints:
          type: array
          items:
            $ref: '#/components/schemas/IdentificationVoiceprint'
    DiarizationJobOutput:
      type: object
      properties:
        diarization:
          description: List of diarization segments
          type: array
          items:
            $ref: '#/components/schemas/DiarizationSegment'
        confidence:
          description: Confidence scores details. Only returned if `confidence` is set to true when job is created
          allOf:
          - $ref: '#/components/schemas/Confidence'
        exclusiveDiarization:
          description: Exclusive diarization segments where only one speaker is active at a time. Only returned if `exclusive` is set to true when job is created.
          type: array
          items:
            $ref: '#/components/schemas/DiarizationSegment'
        wordLevelTranscription:
          description: Word-level transcription segments with text. Only returned if `transcription` is set to true when job is created.
          example:
          - start: 0.5
            end: 0.8
            text: Hello
            speaker: SPEAKER_00
          type: array
          items:
            $ref: '#/components/schemas/TranscriptionSegment'
        turnLevelTranscription:
          description: Turn-level (speaker turn) transcription segments with text. Only returned if `transcription` is set to true when job is created.
          example:
          - start: 0.5
            end: 2.3
            text: Hello, how are you?
            speaker: SPEAKER_00
          type: array
          items:
            $ref: '#/components/schemas/TranscriptionSegment'
        error:
          type: string
          description: Error message if any
        warning:
          type: string
          description: Warning message if any
      required:
      - diarization
  securitySchemes:
    api-key:
      scheme: bearer
      bearerFormat: JWT
      type: http
externalDocs:
  description: pyannoteAI Docs
  url: https://docs.pyannote.ai/