{"openapi":"3.0.3","info":{"title":"transcript1 API","version":"1.0.0"},"servers":[{"url":"https://api.transcript1.com/v1"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"transcript1 API key (t1_...) or OAuth access token (t1o_...)"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"invalid_request"},"message":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","retryable"],"additionalProperties":{"nullable":true}}},"required":["error"]},"InsufficientMinutesError":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["insufficient_minutes"]},"message":{"type":"string"},"retryable":{"type":"boolean"},"action_url":{"type":"string","description":"Where to top up","example":"https://transcript1.com/dashboard/billing"},"minutes_needed":{"type":"integer","nullable":true,"description":"Minutes this transcription needs, when the media duration is known"},"minutes_remaining":{"type":"integer","description":"Usable minutes left on the account"}},"required":["code","message","retryable","action_url","minutes_needed","minutes_remaining"]}},"required":["error"]},"Account":{"type":"object","properties":{"object":{"type":"string","enum":["account"]},"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"}},"required":["id","email"]},"plan":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"minutes":{"type":"object","properties":{"remaining":{"type":"number"},"cycle":{"type":"number"},"topup":{"type":"number"},"topup_usable":{"type":"boolean"},"resets_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["remaining","cycle","topup","topup_usable","resets_at"]},"renews_at":{"type":"string","nullable":true,"format":"date-time"},"limits":{"type":"object","properties":{"requests_per_minute":{"type":"number"},"max_active_jobs":{"type":"number"}},"required":["requests_per_minute","max_active_jobs"]}},"required":["object","user","plan","minutes","renews_at","limits"]},"Transcription":{"type":"object","properties":{"id":{"type":"string","example":"tr_4fHq8ZbN2xLm0PqRsTuVwX"},"object":{"type":"string","enum":["transcription"]},"status":{"type":"string","enum":["awaiting_upload","queued","fetching","transcribing","completed","failed","canceled"]},"source":{"anyOf":[{"type":"object","properties":{"platform":{"type":"string"},"url":{"type":"string","nullable":true},"media_id":{"type":"string","nullable":true}},"required":["platform","url","media_id"]},{"type":"object","properties":{"platform":{"type":"string","enum":["upload"]},"filename":{"type":"string","nullable":true},"size":{"type":"number","nullable":true}},"required":["platform","filename","size"]}]},"media":{"type":"object","nullable":true,"properties":{"title":{"type":"string","nullable":true},"author":{"type":"string","nullable":true},"author_url":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"filename":{"type":"string"},"mime_type":{"type":"string"},"size":{"type":"number"},"duration_seconds":{"type":"number","nullable":true}}},"options":{"type":"object","properties":{"source":{"type":"string","enum":["auto","captions","stt"]},"language":{"type":"string","example":"auto"},"diarize":{"type":"boolean"}},"required":["source","language","diarize"]},"transcript_source":{"type":"string","nullable":true,"enum":["youtube_captions","speech_to_text"]},"caption_kind":{"type":"string","nullable":true,"enum":["manual","auto_generated"]},"language":{"type":"string","nullable":true},"billed_minutes":{"type":"integer","nullable":true},"cached":{"type":"boolean"},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string","nullable":true}},"required":["code","message"]},"created_at":{"type":"string","nullable":true,"format":"date-time"},"completed_at":{"type":"string","nullable":true,"format":"date-time"},"deleted_at":{"type":"string","nullable":true,"format":"date-time","description":"When the transcription was deleted. Always null unless the request passed include_deleted=true"},"transcript":{"type":"object","properties":{"text":{"type":"string"},"speakers":{"type":"array","items":{"type":"string"}},"segments":{"type":"array","items":{"type":"object","properties":{"start":{"type":"number"},"end":{"type":"number"},"speaker":{"type":"string","nullable":true},"language":{"type":"string","nullable":true},"text":{"type":"string"},"words":{"type":"array","nullable":true,"items":{"type":"object","properties":{"start":{"type":"number"},"end":{"type":"number"},"text":{"type":"string"},"confidence":{"type":"number","nullable":true},"speaker":{"type":"string","nullable":true}},"required":["start","end","text","speaker"]}}},"required":["start","end","speaker","language","text"]}}},"required":["text","speakers","segments"],"description":"Present on GET for completed transcriptions"}},"required":["id","object","status","source","media","options","transcript_source","caption_kind","language","billed_minutes","cached","error","created_at","completed_at","deleted_at"]},"TranscriptionList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Transcription"}},"next_cursor":{"type":"string","nullable":true}},"required":["object","data","next_cursor"]}},"parameters":{}},"paths":{"/account":{"get":{"summary":"Get the caller account","description":"Returns the authenticated user, current plan and remaining transcription minutes.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The caller account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"description":"Missing or invalid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No account found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/transcriptions":{"post":{"summary":"Create a transcription","description":"Transcribes a platform URL (YouTube) or an uploaded file. Returns 200 when the result is already final (for example a cache hit), 201 when the transcription is awaiting an upload, and 202 while it is processing. Pass `wait` to hold the request up to 60 seconds for a final status. Pass `reuse_recent=true` with a platform URL to get a recent transcription of the same video back (`reused: true`) instead of being charged again; an Idempotency-Key replay takes precedence over it.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","nullable":true,"minimum":0,"maximum":60,"default":0},"required":false,"name":"wait","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"false","description":"Platform URLs only, and not with webhook_url: return the team's most recent transcription of the same video with the same source, language and diarize created in the last 24 hours (not failed or canceled) instead of creating and charging a new one"},"required":false,"name":"reuse_recent","in":"query"},{"schema":{"type":"string","maxLength":255,"description":"Replays the original transcription for a repeated request with the same parameters"},"required":false,"name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"platform":{"type":"string","enum":["youtube"]},"url":{"type":"string","example":"https://www.youtube.com/watch?v=dQw4w9WgXcQ"},"source":{"type":"string","enum":["auto","captions","stt"]},"language":{"type":"string","example":"auto"},"diarize":{"type":"boolean"},"webhook_url":{"type":"string","format":"uri"}},"required":["platform","url"]},{"type":"object","properties":{"upload":{"type":"object","properties":{"filename":{"type":"string","example":"interview.m4a"},"size":{"type":"integer","example":48210334},"mime_type":{"type":"string","example":"audio/mp4"}},"required":["filename","size"]},"source":{"type":"string","enum":["auto","stt"]},"language":{"type":"string","example":"auto"},"diarize":{"type":"boolean"},"webhook_url":{"type":"string","format":"uri"}},"required":["upload"]}]}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"},"source":{"type":"string","enum":["auto","stt"]},"language":{"type":"string"},"diarize":{"type":"boolean"},"webhook_url":{"type":"string","format":"uri"}},"required":["file"]}}}},"responses":{"200":{"description":"The transcription reached a final status","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Transcription"},{"type":"object","properties":{"reused":{"type":"boolean","description":"True when reuse_recent returned an earlier transcription instead of creating one"}},"required":["reused"]}]}}}},"201":{"description":"The transcription is awaiting a chunked upload; `upload` describes where to send each chunk","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Transcription"},{"type":"object","properties":{"reused":{"type":"boolean","description":"True when reuse_recent returned an earlier transcription instead of creating one"}},"required":["reused"]},{"type":"object","properties":{"upload":{"type":"object","properties":{"chunk_url_template":{"type":"string","example":"https://api.transcript1.com/v1/transcriptions/tr_4fHq8ZbN2xLm0PqRsTuVwX/upload/chunks/{index}"},"headers":{"type":"object","properties":{"X-Upload-Token":{"type":"string"}},"required":["X-Upload-Token"]},"expires_at":{"type":"string","format":"date-time"},"chunks":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"offset":{"type":"integer"},"size":{"type":"integer"}},"required":["index","offset","size"]}}},"required":["chunk_url_template","headers","expires_at","chunks"]}},"required":["upload"]}]}}}},"202":{"description":"The transcription is processing","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Transcription"},{"type":"object","properties":{"reused":{"type":"boolean","description":"True when reuse_recent returned an earlier transcription instead of creating one"}},"required":["reused"]}]}}}},"401":{"description":"Missing or invalid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough minutes (every body form)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientMinutesError"}}}},"403":{"description":"Insufficient scope, unverified email or cross-site request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency-Key reused with different parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The upload is too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid request, URL or platform","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List transcriptions","description":"Lists the team transcriptions newest first, without transcripts. Pass `next_cursor` back as `cursor` for the next page. Deleted transcriptions are hidden unless `include_deleted=true`.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string","enum":["awaiting_upload","queued","fetching","transcribing","completed","failed","canceled"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string"},"required":false,"name":"platform","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"false","description":"Also return deleted transcriptions, read-only and without a transcript. Their `deleted_at` is set. Default false"},"required":false,"name":"include_deleted","in":"query"}],"responses":{"200":{"description":"A page of transcriptions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptionList"}}}},"401":{"description":"Missing or invalid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid query parameters or cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/transcriptions/{id}":{"get":{"summary":"Get a transcription","description":"Returns the transcription. Completed transcriptions include the transcript; `format` renders it as text, SRT or WebVTT. A rendered format requested before completion returns the JSON object with 202 while processing and 200 once failed or canceled. With `include_deleted=true` a deleted transcription is returned as a record without a transcript; `wait` is ignored and rendered formats return 404.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"tr_4fHq8ZbN2xLm0PqRsTuVwX"},"required":true,"name":"id","in":"path"},{"schema":{"type":"integer","nullable":true,"minimum":0,"maximum":60,"default":0},"required":false,"name":"wait","in":"query"},{"schema":{"type":"string","enum":["json","text","srt","vtt"],"default":"json"},"required":false,"name":"format","in":"query"},{"schema":{"type":"string","enum":["words"]},"required":false,"name":"include","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"false"},"required":false,"name":"timestamps","in":"query"},{"schema":{"type":"string","enum":["true","false"],"default":"false","description":"Also return deleted transcriptions, read-only and without a transcript. Their `deleted_at` is set. Default false"},"required":false,"name":"include_deleted","in":"query"}],"responses":{"200":{"description":"The transcription, or the rendered transcript","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transcription"}},"text/plain":{"schema":{"type":"string"}},"application/x-subrip":{"schema":{"type":"string"}},"text/vtt":{"schema":{"type":"string"}}}},"202":{"description":"A rendered format was requested while the transcription is still processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transcription"}}}},"401":{"description":"Missing or invalid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Transcription not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Cancel or delete a transcription","description":"Cancels an active or awaiting-upload transcription and refunds any charged minutes. A completed, failed or canceled transcription is deleted together with its stored transcript.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"tr_4fHq8ZbN2xLm0PqRsTuVwX"},"required":true,"name":"id","in":"path"}],"responses":{"204":{"description":"Canceled or deleted"},"401":{"description":"Missing or invalid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope or cross-site request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Transcription not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/transcriptions/{id}/upload/chunks/{index}":{"put":{"summary":"Upload one chunk","description":"Sends one chunk of a chunked upload as `application/octet-stream`. Authenticated by the `X-Upload-Token` from the create response, not by a bearer credential. The body must be exactly the planned chunk size; re-sending a chunk replaces it.","parameters":[{"schema":{"type":"string","example":"tr_4fHq8ZbN2xLm0PqRsTuVwX"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","example":"0"},"required":true,"name":"index","in":"path"},{"schema":{"type":"string"},"required":true,"name":"X-Upload-Token","in":"header"}],"requestBody":{"required":true,"content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"The chunk was stored","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["upload_chunk"]},"index":{"type":"integer"},"size":{"type":"integer"}},"required":["object","index","size"]}}}},"401":{"description":"Missing, invalid or expired upload token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Transcription not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The transcription is no longer awaiting an upload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Index outside the chunk plan or wrong body size","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/transcriptions/{id}/upload":{"get":{"summary":"Get upload progress","description":"Lists the received chunks of a chunked upload so an interrupted upload can resume.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"tr_4fHq8ZbN2xLm0PqRsTuVwX"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Upload progress","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["upload"]},"status":{"type":"string","enum":["awaiting_upload","queued","fetching","transcribing","completed","failed","canceled"]},"total_bytes":{"type":"integer"},"uploaded_bytes":{"type":"integer"},"received_chunks":{"type":"array","items":{"type":"integer"}},"chunks":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"offset":{"type":"integer"},"size":{"type":"integer"}},"required":["index","offset","size"]}},"expires_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["object","status","total_bytes","uploaded_bytes","received_chunks","chunks","expires_at"]}}}},"401":{"description":"Missing or invalid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Transcription or upload not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/transcriptions/{id}/upload/complete":{"post":{"summary":"Complete a chunked upload","description":"Verifies that every planned chunk arrived with the planned size, assembles the file and queues the transcription.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","example":"tr_4fHq8ZbN2xLm0PqRsTuVwX"},"required":true,"name":"id","in":"path"}],"responses":{"202":{"description":"The transcription is queued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transcription"}}}},"401":{"description":"Missing or invalid credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient scope or cross-site request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Transcription or upload not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Chunks are missing (`upload_incomplete`, with `missing_chunks`) or the transcription is not awaiting an upload (`invalid_state`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}