{
  "openapi": "3.0.3",
  "info": {
    "title": "DaDaScribe API",
    "description": "Advanced AI Audio & Video Transcription Service.\n\n- Transcribe from YouTube URLs, direct audio/video links, or uploaded files\n- Supports 100+ languages for source and destination\n- Speaker diarization (name speakers)\n- Translation to up to 5 languages\n- Returns .txt transcripts and .srt subtitles\n\n**Base URL**: `https://api.dadascribe.com/v1`\n",
    "contact": {
      "name": "DaDaScribe Support",
      "url": "https://www.dadascribe.com/contact/"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://www.dadascribe.com/"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.dadascribe.com/v1",
      "description": "Production server"
    }
  ],
  "tags": [
    {
      "name": "Transcription",
      "description": "Submit and monitor transcription jobs"
    },
    {
      "name": "Output",
      "description": "Download completed transcripts and subtitles"
    }
  ],
  "paths": {
    "/transcribe": {
      "post": {
        "tags": [
          "Transcription"
        ],
        "summary": "Submit audio for transcription",
        "description": "Submit one or more audio/video sources for transcription and optional translation/diarization.\n\n**Supported sources**:\n- YouTube URLs (including Shorts and youtu.be links)\n- Direct audio/video file URLs\n- Uploaded files (same formats; max 10 GB via /v1/upload/*)\n- s3_token from /v1/upload/complete\n\nMax 10 sources per request. Max 10 hours per source.\n\n**Rate limit**: 60 requests per minute per API key.\n",
        "operationId": "createTranscription",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TranscribeRequest"
              },
              "examples": {
                "youtube": {
                  "summary": "YouTube video",
                  "value": {
                    "source": "https://www.youtube.com/watch?v=dQw4w9wgccc",
                    "source-language": "en",
                    "destination-language": "es,it",
                    "diarization": "Host,Guest"
                  }
                },
                "multiple": {
                  "summary": "Multiple sources",
                  "value": {
                    "source": [
                      "https://example.com/audio1.mp3",
                      "https://example.com/audio2.wav"
                    ],
                    "source-language": "en"
                  }
                }
              }
            },
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/transcribe_body"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Transcription job created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TranscribeSuccessResponse"
                }
              }
            }
          },
          "4XX": {
            "$ref": "#/components/responses/ClientError"
          },
          "5XX": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/status": {
      "post": {
        "tags": [
          "Transcription"
        ],
        "summary": "Check status of a transcription batch",
        "description": "Poll this endpoint until the batch reaches `complete` status.\n\n**Rate limit**: 120 requests per minute per API key.\n",
        "operationId": "getTranscriptionStatus",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StatusRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Current batch status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/inline_response_200"
                }
              }
            }
          },
          "4XX": {
            "$ref": "#/components/responses/ClientError"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ]
      }
    },
    "/output/{id}/{filename}": {
      "get": {
        "tags": [
          "Output"
        ],
        "summary": "Download completed output file",
        "description": "Download transcripts (.txt) or subtitles (.srt).\n\n**No authentication required** — these are time-limited capability URLs.\nFiles are available for **1 hour** after completion for privacy.\n\n**Rate limit**: 600 requests per minute per client IP.\n",
        "operationId": "downloadOutputFile",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The batch ID returned from /transcribe",
            "required": true,
            "schema": {
              "type": "string",
              "example": "a1B2c3D4e5F6g7H8"
            }
          },
          {
            "name": "filename",
            "in": "path",
            "description": "Filename from the urls array in status response",
            "required": true,
            "schema": {
              "type": "string",
              "example": "a1B2c3D4e5F6g7H8.txt"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "File content (text or subtitle file)",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "403": {
            "description": "File not ready yet or expired",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "TranscribeRequest": {
        "required": [
          "source-language"
        ],
        "type": "object",
        "properties": {
          "source": {
            "example": "https://www.youtube.com/watch?v=...",
            "oneOf": [
              {
                "type": "string",
                "description": "Single source (YouTube URL, audio URL, or video ID)"
              },
              {
                "maxItems": 10,
                "type": "array",
                "description": "Up to 10 sources",
                "items": {
                  "type": "string"
                }
              }
            ]
          },
          "source-language": {
            "type": "string",
            "description": "Source language code (100+ supported)",
            "example": "en"
          },
          "destination-language": {
            "type": "string",
            "description": "Comma-separated destination language codes (max 5). Cannot include source language.",
            "example": "es,it,fr"
          },
          "diarization": {
            "type": "string",
            "description": "Comma-separated speaker names (minimum 2 speakers)",
            "example": "Speaker1,Speaker2"
          }
        }
      },
      "TranscribeSuccessResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "ok"
            ]
          },
          "id": {
            "type": "string",
            "example": "a1B2c3D4e5F6g7H8"
          },
          "count": {
            "type": "integer",
            "example": 2
          }
        }
      },
      "StatusRequest": {
        "required": [
          "id"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "a1B2c3D4e5F6g7H8"
          }
        }
      },
      "StatusQueue": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "queue"
            ]
          },
          "count": {
            "type": "integer"
          }
        }
      },
      "StatusProcessing": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "processing"
            ]
          },
          "count": {
            "type": "integer"
          },
          "complete": {
            "type": "integer"
          },
          "queue": {
            "type": "integer"
          },
          "processing": {
            "type": "integer"
          }
        }
      },
      "StatusComplete": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "complete"
            ]
          },
          "count": {
            "type": "integer"
          },
          "urls": {
            "type": "array",
            "example": [
              "https://api.dadascribe.com/v1/output/a1B2c3D4e5F6g7H8/xxx.txt",
              "https://api.dadascribe.com/v1/output/a1B2c3D4e5F6g7H8/xxx.srt",
              "https://api.dadascribe.com/v1/output/a1B2c3D4e5F6g7H8/xxx_it.srt"
            ],
            "items": {
              "type": "string",
              "format": "uri"
            }
          }
        }
      },
      "StatusError": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ]
          },
          "message": {
            "type": "string"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ]
          },
          "message": {
            "type": "string",
            "example": "rate limit exceeded"
          }
        }
      },
      "transcribe_body": {
        "type": "object",
        "properties": {
          "file": {
            "type": "string",
            "description": "Single audio file upload",
            "format": "binary"
          },
          "source-language": {
            "type": "string"
          },
          "destination-language": {
            "type": "string"
          },
          "diarization": {
            "type": "string"
          },
          "data": {
            "type": "string",
            "description": "Optional JSON string containing the above fields (alternative to individual fields)"
          }
        }
      },
      "inline_response_200": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/StatusQueue"
          },
          {
            "$ref": "#/components/schemas/StatusProcessing"
          },
          {
            "$ref": "#/components/schemas/StatusComplete"
          },
          {
            "$ref": "#/components/schemas/StatusError"
          }
        ]
      }
    },
    "responses": {
      "ClientError": {
        "description": "Client error (400, 401, 402, 403, 404, 429)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "ServerError": {
        "description": "Server error (500+)",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "description": "API key in the format `dds_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`.\nGet your key at https://www.dadascribe.com/account/api.php\n",
        "scheme": "bearer",
        "bearerFormat": "Token"
      }
    }
  }
}