@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api AssemblyAI API
@base https://api.assemblyai.com
@version 1.3.4
@auth ApiKey Authorization in header
@endpoints 10
@toc upload(1), transcript(9)

@group upload
@endpoint POST /v2/upload
@desc Upload a media file
@returns(200) {upload_url: str(url)} # Media file uploaded successfully
@errors {400: Bad request, 401: Unauthorized, 403: Cannot access uploaded file, 404: Not found, 429: Too many requests, 500: An error occurred while processing the request, 503: Service unavailable, 504: Gateway timeout}

@endgroup

@group transcript
@endpoint POST /v2/transcript
@desc Transcribe audio
@returns(200) {audio_channels: int, audio_duration: int?, audio_end_at: int?, audio_start_from: int?, audio_url: str(url), auto_chapters: bool?, auto_highlights: bool, auto_highlights_result: any, chapters: [map]?, confidence: num(double)?, content_safety: bool?, content_safety_labels: any, custom_spelling: [map]?, disfluencies: bool?, domain: str?, entities: [map]?, entity_detection: bool?, error: str, filter_profanity: bool?, format_text: bool?, iab_categories: bool?, iab_categories_result: any, id: str(uuid), keyterms_prompt: [str], language_code: any, language_codes: [str]?, language_confidence: num(double)?, language_confidence_threshold: num(float)?, language_detection: bool?, language_detection_options: map{expected_languages: [str], fallback_language: str, code_switching: bool, code_switching_confidence_threshold: num}, multichannel: bool?, prompt: str, punctuate: bool?, redact_pii: bool, redact_pii_audio: bool?, redact_pii_audio_options: map{return_redacted_no_speech_audio: bool, override_audio_redaction_method: str}, redact_pii_audio_quality: any, redact_pii_policies: [str]?, redact_pii_sub: str, sentiment_analysis: bool?, sentiment_analysis_results: [map]?, speaker_labels: bool?, speakers_expected: int?, speech_model_used: str, speech_models: [str]?, speech_threshold: num(float)?, speech_understanding: map{request: any, response: any}, status: str, summarization: bool, summary: str?, summary_model: str?, summary_type: str?, remove_audio_tags: any, temperature: num?, text: str?, throttled: bool?, utterances: [map]?, webhook_auth: bool, webhook_auth_header_name: str?, webhook_status_code: int?, webhook_url: str(url)?, words: [map]?, acoustic_model: str, custom_topics: bool?, language_model: str, speech_model: any, speed_boost: bool?, topics: [str], translated_texts: map{language_code: str}} # Transcript created and queued for processing
@errors {400: Bad request, 401: Unauthorized, 404: Not found, 429: Too many requests, 500: An error occurred while processing the request, 503: Service unavailable, 504: Gateway timeout}

@endpoint GET /v2/transcript
@desc List transcripts
@optional {limit: int=10 # Maximum amount of transcripts to retrieve, status: str # Filter by transcript status, created_on: str(date) # Only get transcripts created on this date, before_id: str(uuid) # Get transcripts that were created before this transcript ID, after_id: str(uuid) # Get transcripts that were created after this transcript ID, throttled_only: bool=false # Only get throttled transcripts, overrides the status filter}
@returns(200) {page_details: map{limit: int, result_count: int, current_url: str(url), prev_url: str(url)?, next_url: str(url)?}, transcripts: [map]} # A list of transcripts. Transcripts are sorted from newest to oldest. The previous URL always points to a page with older transcripts.
@errors {400: Bad request, 401: Unauthorized, 404: Not found, 429: Too many requests, 500: An error occurred while processing the request, 503: Service unavailable, 504: Gateway timeout}

@endpoint GET /v2/transcript/{transcript_id}
@desc Get transcript
@required {transcript_id: str # ID of the transcript}
@returns(200) {audio_channels: int, audio_duration: int?, audio_end_at: int?, audio_start_from: int?, audio_url: str(url), auto_chapters: bool?, auto_highlights: bool, auto_highlights_result: any, chapters: [map]?, confidence: num(double)?, content_safety: bool?, content_safety_labels: any, custom_spelling: [map]?, disfluencies: bool?, domain: str?, entities: [map]?, entity_detection: bool?, error: str, filter_profanity: bool?, format_text: bool?, iab_categories: bool?, iab_categories_result: any, id: str(uuid), keyterms_prompt: [str], language_code: any, language_codes: [str]?, language_confidence: num(double)?, language_confidence_threshold: num(float)?, language_detection: bool?, language_detection_options: map{expected_languages: [str], fallback_language: str, code_switching: bool, code_switching_confidence_threshold: num}, multichannel: bool?, prompt: str, punctuate: bool?, redact_pii: bool, redact_pii_audio: bool?, redact_pii_audio_options: map{return_redacted_no_speech_audio: bool, override_audio_redaction_method: str}, redact_pii_audio_quality: any, redact_pii_policies: [str]?, redact_pii_sub: str, sentiment_analysis: bool?, sentiment_analysis_results: [map]?, speaker_labels: bool?, speakers_expected: int?, speech_model_used: str, speech_models: [str]?, speech_threshold: num(float)?, speech_understanding: map{request: any, response: any}, status: str, summarization: bool, summary: str?, summary_model: str?, summary_type: str?, remove_audio_tags: any, temperature: num?, text: str?, throttled: bool?, utterances: [map]?, webhook_auth: bool, webhook_auth_header_name: str?, webhook_status_code: int?, webhook_url: str(url)?, words: [map]?, acoustic_model: str, custom_topics: bool?, language_model: str, speech_model: any, speed_boost: bool?, topics: [str], translated_texts: map{language_code: str}} # The transcript resource
@errors {400: Bad request, 401: Unauthorized, 404: Not found, 429: Too many requests, 500: An error occurred while processing the request, 503: Service unavailable, 504: Gateway timeout}

@endpoint DELETE /v2/transcript/{transcript_id}
@desc Delete transcript
@required {transcript_id: str # ID of the transcript}
@returns(200) {audio_channels: int, audio_duration: int?, audio_end_at: int?, audio_start_from: int?, audio_url: str(url), auto_chapters: bool?, auto_highlights: bool, auto_highlights_result: any, chapters: [map]?, confidence: num(double)?, content_safety: bool?, content_safety_labels: any, custom_spelling: [map]?, disfluencies: bool?, domain: str?, entities: [map]?, entity_detection: bool?, error: str, filter_profanity: bool?, format_text: bool?, iab_categories: bool?, iab_categories_result: any, id: str(uuid), keyterms_prompt: [str], language_code: any, language_codes: [str]?, language_confidence: num(double)?, language_confidence_threshold: num(float)?, language_detection: bool?, language_detection_options: map{expected_languages: [str], fallback_language: str, code_switching: bool, code_switching_confidence_threshold: num}, multichannel: bool?, prompt: str, punctuate: bool?, redact_pii: bool, redact_pii_audio: bool?, redact_pii_audio_options: map{return_redacted_no_speech_audio: bool, override_audio_redaction_method: str}, redact_pii_audio_quality: any, redact_pii_policies: [str]?, redact_pii_sub: str, sentiment_analysis: bool?, sentiment_analysis_results: [map]?, speaker_labels: bool?, speakers_expected: int?, speech_model_used: str, speech_models: [str]?, speech_threshold: num(float)?, speech_understanding: map{request: any, response: any}, status: str, summarization: bool, summary: str?, summary_model: str?, summary_type: str?, remove_audio_tags: any, temperature: num?, text: str?, throttled: bool?, utterances: [map]?, webhook_auth: bool, webhook_auth_header_name: str?, webhook_status_code: int?, webhook_url: str(url)?, words: [map]?, acoustic_model: str, custom_topics: bool?, language_model: str, speech_model: any, speed_boost: bool?, topics: [str], translated_texts: map{language_code: str}} # The deleted transcript response
@errors {400: Bad request, 401: Unauthorized, 404: Not found, 429: Too many requests, 500: An error occurred while processing the request, 503: Service unavailable, 504: Gateway timeout}

@endpoint GET /v2/transcript/{transcript_id}/{subtitle_format}
@desc Get subtitles for transcript
@required {transcript_id: str # ID of the transcript, subtitle_format: str # The format of the captions}
@optional {chars_per_caption: int # The maximum number of characters per caption}
@returns(200) The exported captions as text
@errors {400: Bad request, 401: Unauthorized, 404: Not found, 429: Too many requests, 500: An error occurred while processing the request, 503: Service unavailable, 504: Gateway timeout}

@endpoint GET /v2/transcript/{transcript_id}/sentences
@desc Get sentences in transcript
@required {transcript_id: str # ID of the transcript}
@returns(200) {id: str(uuid), confidence: num(double), audio_duration: num, sentences: [map]} # Exported sentences
@errors {400: Bad request, 401: Unauthorized, 404: Not found, 429: Too many requests, 500: An error occurred while processing the request, 503: Service unavailable, 504: Gateway timeout}

@endpoint GET /v2/transcript/{transcript_id}/paragraphs
@desc Get paragraphs in transcript
@required {transcript_id: str # ID of the transcript}
@returns(200) {id: str(uuid), confidence: num(double), audio_duration: num, paragraphs: [map]} # Exported paragraphs
@errors {400: Bad request, 401: Unauthorized, 404: Not found, 429: Too many requests, 500: An error occurred while processing the request, 503: Service unavailable, 504: Gateway timeout}

@endpoint GET /v2/transcript/{transcript_id}/word-search
@desc Search words in transcript
@required {transcript_id: str # ID of the transcript, words: [str] # Keywords to search for}
@returns(200) {id: str(uuid), total_count: int, matches: [map]} # Word search response
@errors {400: Bad request, 401: Unauthorized, 404: Not found, 429: Too many requests, 500: An error occurred while processing the request, 503: Service unavailable, 504: Gateway timeout}

@endpoint GET /v2/transcript/{transcript_id}/redacted-audio
@desc Get redacted audio
@required {transcript_id: str # ID of the transcript}
@returns(200) {status: str, redacted_audio_url: str(url)} # The redacted audio object containing the status and URL to the redacted audio
@errors {400: Bad request, 401: Unauthorized, 404: Not found, 429: Too many requests, 500: An error occurred while processing the request, 503: Service unavailable, 504: Gateway timeout}

@endgroup

@end