Transcribe API

Voice-to-text transcription tokens, history, and usage tracking

The Transcribe API provides Deepgram token vending for real-time WebSocket transcription, transcription history management, audio storage, and usage tracking.

Base URL

https://api.do.dev/v1/transcribe

Authentication

Transcribe endpoints require API key authentication with appropriate scopes.

Scope	Description
`transcribe:token`	Generate Deepgram transcription tokens
`transcribe:history`	Manage transcription history and audio
`transcribe:usage`	View usage statistics and limits
`transcribe:*`	Full transcribe access

Endpoints

Token

Method	Path	Scope	Description
GET	`/v1/transcribe/token`	`transcribe:token`	Generate a temporary Deepgram token for WebSocket transcription

The token endpoint vends short-lived Deepgram JWT tokens (30s TTL) for client-side WebSocket connections. The WebSocket connection stays open after the token expires -- the token is only validated at connection time.

Usage limits are checked before vending a token.

curl -H "Authorization: Bearer do_live_..." \
  https://api.do.dev/v1/transcribe/token

{
  "token": "eyJ...",
  "expiresIn": 30,
  "remaining": 950
}

History

Method	Path	Scope	Description
GET	`/v1/transcribe/history`	`transcribe:history`	List transcription history
POST	`/v1/transcribe/history`	`transcribe:history`	Add a transcription entry
DELETE	`/v1/transcribe/history/{id}`	`transcribe:history`	Delete a history entry

List History

curl -H "Authorization: Bearer do_live_..." \
  "https://api.do.dev/v1/transcribe/history?limit=20&offset=0"

Add History Entry

curl -X POST -H "Authorization: Bearer do_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "rawTranscript": "hello world",
    "cleanedText": "Hello, world.",
    "durationMs": 2500,
    "targetApp": "notes",
    "confidence": 0.95,
    "wordCount": 2
  }' \
  https://api.do.dev/v1/transcribe/history

Field	Type	Required	Description
`rawTranscript`	string	Yes	Raw transcript from Deepgram
`cleanedText`	string	Yes	Cleaned/formatted text
`durationMs`	number	Yes	Recording duration in milliseconds
`targetApp`	string	No	Target application name
`tone`	string	No	Tone/style applied
`confidence`	number	No	Deepgram confidence score
`wordCount`	number	No	Word count
`audioDurationSec`	number	No	Deepgram audio duration in seconds
`model`	string	No	Deepgram model used
`requestId`	string	No	Deepgram request ID

Audio Storage

Method	Path	Scope	Description
POST	`/v1/transcribe/history/audio/upload-url`	`transcribe:history`	Get a pre-signed upload URL
POST	`/v1/transcribe/history/{id}/audio`	`transcribe:history`	Attach uploaded audio to a history entry
GET	`/v1/transcribe/history/{id}/audio`	`transcribe:history`	Get audio download URL

Audio storage uses Convex file storage. Upload flow:

Request an upload URL via POST /history/audio/upload-url
Upload the audio file directly to the returned URL
Attach the resulting storageId to a history entry via POST /history/{id}/audio

Usage

Method	Path	Scope	Description
GET	`/v1/transcribe/usage`	`transcribe:usage`	Current month usage stats
GET	`/v1/transcribe/usage/daily`	`transcribe:usage`	Daily usage breakdown
GET	`/v1/transcribe/usage/check-limit`	`transcribe:usage`	Check remaining quota

Get Usage

curl -H "Authorization: Bearer do_live_..." \
  "https://api.do.dev/v1/transcribe/usage?months=3"

Returns monthly usage including dictation count, audio minutes, word count, and estimated cost.

Check Limits

curl -H "Authorization: Bearer do_live_..." \
  "https://api.do.dev/v1/transcribe/usage/check-limit?timezone=America/New_York"

{
  "allowed": true,
  "dailyWordsUsed": 250,
  "dailyWordsLimit": 1000,
  "dailyWordsRemaining": 750,
  "weeklyWordsUsed": 1200,
  "weeklyWordsLimit": 3000,
  "weeklyWordsRemaining": 1800,
  "limitType": null,
  "plan": "hobby"
}