{"openapi":"3.1.0","info":{"title":"WhoScribe","description":"Read the signed-in user's own audio and video transcripts.","version":"1.0.0"},"servers":[{"url":"https://whoscribe.ai"}],"paths":{"/api/v1/transcripts":{"get":{"operationId":"listTranscripts","summary":"List or search the transcripts in the account","description":"Without query, returns the most recent transcripts. With query, returns only those whose title or text contains that wording. The full text is not included — call getTranscript to read one.","parameters":[{"name":"query","in":"query","required":false,"description":"Words to search for in the title and the text.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Defaults to completed — only completed transcripts have text.","schema":{"type":"string","enum":["completed","processing","failed","any"]}},{"name":"limit","in":"query","required":false,"description":"How many to return.","schema":{"type":"integer","minimum":1,"maximum":25}}],"responses":{"200":{"description":"A readable summary plus the matching transcripts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptListResponse"}}}},"401":{"description":"The account is not connected or the authorization has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request could not be fulfilled; the error field explains why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/transcripts/{id}":{"get":{"operationId":"getTranscript","summary":"Read one transcript in full","description":"Returns the transcript text. Ask for timestamps when you intend to cite a moment in the recording.","parameters":[{"name":"id","in":"path","required":true,"description":"The transcript id returned by listTranscripts.","schema":{"type":"string"}},{"name":"with_timestamps","in":"query","required":false,"description":"Prefix every line with its start time as (m:ss).","schema":{"type":"boolean"}},{"name":"language","in":"query","required":false,"description":"Two-letter code of an existing translation. Omit for the original.","schema":{"type":"string"}}],"responses":{"200":{"description":"The transcript text with its heading.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptTextResponse"}}}},"401":{"description":"The account is not connected or the authorization has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request could not be fulfilled; the error field explains why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/account":{"get":{"operationId":"getAccount","summary":"Plan, transcript count and remaining daily quota","responses":{"200":{"description":"A readable account summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountResponse"}}}},"401":{"description":"The account is not connected or the authorization has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request could not be fulfilled; the error field explains why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Transcript":{"type":"object","properties":{"id":{"type":"string","description":"Pass this to getTranscript."},"title":{"type":"string"},"status":{"type":"string"},"language":{"type":"string"},"duration":{"type":"string"},"created_at":{"type":"string"},"has_speakers":{"type":"boolean"},"url":{"type":"string","description":"Where the user can open it on whoscribe.ai."},"excerpt":{"type":"string","description":"Only on search results: the wording around the match."}}},"TranscriptListResponse":{"type":"object","properties":{"summary":{"type":"string","description":"Ready-to-read text; prefer this over rebuilding it from data."},"data":{"type":"object","properties":{"query":{"type":"string"},"transcripts":{"type":"array","items":{"$ref":"#/components/schemas/Transcript"}}}}}},"TranscriptTextResponse":{"type":"object","properties":{"summary":{"type":"string","description":"The transcript text, preceded by its title, date and duration."},"data":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"language":{"type":"string"},"duration":{"type":"string"},"created_at":{"type":"string"},"has_speakers":{"type":"boolean"},"url":{"type":"string"},"truncated":{"type":"boolean","description":"True when the text was cut short; say so instead of implying you read all of it."},"characters":{"type":"integer"}}}}},"AccountResponse":{"type":"object","properties":{"summary":{"type":"string"},"data":{"type":"object","properties":{"plan":{"type":"string"},"transcripts":{"type":"integer"},"completed":{"type":"integer"},"transcribed_duration":{"type":"string"},"remaining_minutes_this_month":{"type":"integer","description":"Readable transcript minutes left this month. Null on the Pro plan and for guests, neither of which is metered by the month."},"remaining_today":{"type":"integer","description":"Daily pace limit, not the main one. Null on the Pro plan, which has no daily limit."}}}}},"Error":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong, in plain words."}}}},"securitySchemes":{"oauth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://whoscribe.ai/oauth/authorize","tokenUrl":"https://whoscribe.ai/oauth/token","refreshUrl":"https://whoscribe.ai/oauth/token","scopes":{"transcripts.read":"Read the transcripts in the account"}}}}}},"security":[{"oauth":["transcripts.read"]}]}