Releases: deepgram/deepgram-js-sdk
Release list
v5.5.0
v5.4.0
5.4.0 (2026-06-01)
Adds a pluggable streaming-transport layer (the JS side of the cross-SDK SageMaker work) and fixes the TypeScript types exposed for the WebSocket helper clients. Fully backwards-compatible — every new option is optional with existing defaults, so current callers need no code changes.
Features
-
Pluggable transport interface for SageMaker support (#492) (4d43b1b)
Adds a
DeepgramTransport/DeepgramTransportFactoryinterface (src/transport.ts) and atransportFactoryoption onDeepgramClient. When set, thelisten.v1,listen.v2,speak.v1, andagent.v1createConnectionpaths route through a custom transport via aTransportWebSocketAdapterinstead of the default WebSocket; REST behaviour is unchanged. This is the seam the@deepgram/sagemakerpackage plugs into, validated end-to-end against live Nova-3 STT, Flux, and Aura TTS endpoints (including a 400-concurrent-connection burst). Mirrors the same work in the Python and Java SDKs. -
reconnectflag with auto-disable for custom transports (8dec8c9)New optional
reconnect?: booleanonDeepgramClient(defaulttrue, exposed read-only asclient.reconnect) controlling wrapper-level retry of streaming connections. Auto-disabled tofalsewhen atransportFactoryis supplied, so self-retrying transports aren't double-stacked with a second retry layer (which caused storm-on-storm behaviour under burst load). Opt back in with an explicitreconnect: true.
Bug Fixes
-
Expose WebSocket helper types (#501) (ac71def) — thanks @asim48-ctrl
The
agent/listen/speakgetters were typed against the generated client, which hid the wrapper'screateConnection()method and typedAuthorizationas required. They now expose typed WebSocket wrapper clients, soclient.listen.v1.createConnection({ model: "nova-3" })type-checks andAuthorizationis optional. Runtime behaviour is unchanged — this is a types-only fix. Fixes #489.
v5.3.0
chore(main): release 5.3.0 (#500)
:robot: I have created a release *beep* *boop*
## 5.3.0 — what's in this release
This release bundles the 2026-05-14 Fern SDK regeneration plus two
follow-up commits on top of #499.
See the full changelog:
[`v5.2.0...v5.3.0`](https://github.com/deepgram/deepgram-js-sdk/compare/v5.2.0...v5.3.0).
### Features
**Diarization v2 batch GA + listen-provider dedup + think/models route
fix — #499**
[`DeepgramEnvironment`](https://github.com/deepgram/deepgram-js-sdk/blob/main/src/environments.ts)
reshape (intentional upstream fix, not a runtime break):
-
[`DeepgramEnvironment.Agent`](https://github.com/deepgram/deepgram-js-sdk/blob/main/src/environments.ts)
removed;
[`Production`](https://github.com/deepgram/deepgram-js-sdk/blob/main/src/environments.ts)
gained an `agentRest` slot.
- The
[`agent.v1.settings.think.models`](https://github.com/deepgram/deepgram-js-sdk/blob/main/src/api/resources/agent/resources/v1/resources/settings/resources/think/resources/models/client/Client.ts)
endpoint now routes via HTTPS instead of WSS.
- Not a breaking change in practice — the old
`DeepgramEnvironment.Agent` would have routed every REST client at
`https://agent.deepgram.com` (404 on `/v1/listen`, etc.) and
`think/models` was misrouted over WSS, so no consumer could have had a
working flow through it. Driven by
[deepgram-docs#886](https://github.com/deepgram/deepgram-docs/pull/886)
+ [#887](https://github.com/deepgram/deepgram-docs/pull/887).
Diarization v2 batch GA (purely additive):
- New optional `diarize_model` field on
[`ListenV1RequestUrl`](https://github.com/deepgram/deepgram-js-sdk/blob/main/src/api/resources/listen/resources/v1/resources/media/client/requests/ListenV1RequestUrl.ts)
and
[`MediaTranscribeRequestOctetStream`](https://github.com/deepgram/deepgram-js-sdk/blob/main/src/api/resources/listen/resources/v1/resources/media/client/requests/MediaTranscribeRequestOctetStream.ts);
new
[`MediaTranscribeRequestDiarizeModel`](https://github.com/deepgram/deepgram-js-sdk/blob/main/src/api/resources/listen/resources/v1/resources/media/types/MediaTranscribeRequestDiarizeModel.ts)
enum.
Listen-provider dedup:
- New top-level exports
[`DeepgramListenProviderV1`](https://github.com/deepgram/deepgram-js-sdk/blob/main/src/api/types/DeepgramListenProviderV1.ts)
/
[`DeepgramListenProviderV2`](https://github.com/deepgram/deepgram-js-sdk/blob/main/src/api/types/DeepgramListenProviderV2.ts).
**Restore `AgentV1SettingsAgentContextListenProviderV2.LanguageHint`
nested namespace
([`ace680a`](https://github.com/deepgram/deepgram-js-sdk/commit/ace680ae192d85dcb5f54268984ccf0866aa62e9))**
- The dedup collapsed the nested
`AgentV1SettingsAgentContextListenProviderV2.LanguageHint` namespace
path. Restored as a one-line alias `type LanguageHint =
DeepgramListenProviderV2.LanguageHint` inside
[`AgentV1SettingsAgentContextListenProvider.ts`](https://github.com/deepgram/deepgram-js-sdk/blob/main/src/api/resources/agent/resources/v1/types/AgentV1SettingsAgentContextListenProvider.ts)
so existing consumers of the nested path keep working.
- Regression coverage in
[`tests/unit/compat-aliases.test.ts`](https://github.com/deepgram/deepgram-js-sdk/blob/main/tests/unit/compat-aliases.test.ts).
### Bug fixes
**Restore
[`client.fetch()`](https://github.com/deepgram/deepgram-js-sdk/blob/main/src/Client.ts)
default `baseUrl` to `api.deepgram.com`
([`56b8ce5`](https://github.com/deepgram/deepgram-js-sdk/commit/56b8ce555c09842e6021fcb889e4aff9e87b151d))**
- After the upstream spec introduced the new `agentRest` slot, the
generator switched the
[`client.fetch()`](https://github.com/deepgram/deepgram-js-sdk/blob/main/src/Client.ts)
passthrough helper's default `baseUrl` from `env.base`
(api.deepgram.com) to `env.agentRest` (agent.deepgram.com). Reverted
locally in
[`src/Client.ts`](https://github.com/deepgram/deepgram-js-sdk/blob/main/src/Client.ts)
— passthrough should default to the canonical Deepgram REST host. Likely
a Fern generator artifact; this freeze gets dropped once the upstream
fix lands.
### Patches preserved through regen (re-applied in #499)
No prior patches dropped — every existing freeze still addresses surface
the new regen misses.
-
[`package.json`](https://github.com/deepgram/deepgram-js-sdk/blob/main/package.json)
— kept `@types/node ^20.17.57` pin, re-added `@commitlint/cli`,
`@commitlint/config-conventional`, `tsx`, `playwright`, `vite`, `terser`
(generator's `5.2.1` version bump kept).
-
[`src/api/resources/manage/.../keys/client/Client.ts`](https://github.com/deepgram/deepgram-js-sdk/blob/main/src/api/resources/manage/resources/v1/resources/projects/resources/keys/client/Client.ts)
— restored optional `request?` parameter to
`manage.v1.projects.keys.create` (3 spots).
-
[`src/api/types/CreateKeyV1Request.ts`](https://github.com/deepgram/deepgram-js-sdk/blob/main/src/api/types/CreateKeyV1Request.ts)
— restored legacy `CreateKeyV1RequestOne` alias.
-
[`src/api/resources/agent/resources/v1/types/AgentV1Settings.ts`](https://github.com/deepgram/deepgram-js-sdk/blob/main/src/api/resources/agent/resources/v1/types/AgentV1Settings.ts)
— restored interface form of `Agent` with named sub-types +
`AgentReference = Agent | string` opt-in alias.
-
[`src/api/resources/agent/resources/v1/types/AgentV1SettingsAgentListenProvider.ts`](https://github.com/deepgram/deepgram-js-sdk/blob/main/src/api/resources/agent/resources/v1/types/AgentV1SettingsAgentListenProvider.ts)
— restored one-line alias to
[`AgentV1SettingsAgentContextListenProvider`](https://github.com/deepgram/deepgram-js-sdk/blob/main/src/api/resources/agent/resources/v1/types/AgentV1SettingsAgentContextListenProvider.ts).
### New freezes added this cycle (in #499)
-
[`biome.json`](https://github.com/deepgram/deepgram-js-sdk/blob/main/biome.json)
— generator emits `"vcs": { "enabled": false }`, which caused biome lint
to scan the gitignored `examples/browser/deepgram.js` bundle. Restored
`useIgnoreFile: true` and added to `.fernignore` so this patch survives
the next regen.
-
[`AgentV1SettingsAgentContextListenProvider.ts`](https://github.com/deepgram/deepgram-js-sdk/blob/main/src/api/resources/agent/resources/v1/types/AgentV1SettingsAgentContextListenProvider.ts)
— see the `LanguageHint` follow-up commit above.
-
[`src/Client.ts`](https://github.com/deepgram/deepgram-js-sdk/blob/main/src/Client.ts)
— see the `client.fetch()` bug-fix commit above.
### Validation
- `make build` — passes (CJS + ESM + ESM validation).
- `make test` — passes (535 unit tests + 132 wire tests, including 2 new
regression cases for the `LanguageHint` shim).
- `make test-esm` — passes (5 tests).
- `make lint` — passes (warnings only, no errors).
- `make examples` — 30/36 pass against the real API; remaining 6
failures are env-config (missing `DEEPGRAM_PROJECT_ID`) or transient
network, not regen-related.
- Example 9 (Voice Agent) exercises the rerouted
`agent.v1.settings.think.models.list()` endpoint end-to-end.
### Cross-SDK reference
The `agentRest` env fix has equivalents in
deepgram/deepgram-python-sdk#715 and deepgram/deepgram-java-sdk#59. JS
is the only SDK that additionally needed the
[`client.fetch()`](https://github.com/deepgram/deepgram-js-sdk/blob/main/src/Client.ts)
passthrough patch — Python's
[`client.py`](https://github.com/deepgram/deepgram-python-sdk/blob/main/src/deepgram/client.py)
and Java's `DeepgramClient`/`DeepgramClientBuilder` have no equivalent
passthrough.
---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).
v5.2.0
5.2.0 (2026-05-12)
Features
- alias AgentV1SettingsAgentListenProvider to *AgentContextListenProvider (150e663)
- preserve AgentV1Settings.Agent sub-types after regen (2efab2d)
- preserve SDK compatibility after regen (d2b8d62)
- restore Agent interface, add AgentReference for string-id flow (4c72d31)
- sdk regeneration 2026-04-30 (#491) (a618282)
- sdk regeneration 2026-05-06 with backward-compat preserved (#497) (2aed53e)
v5.1.0
v5.0.0
5.0.0 (2026-03-04)
⚠ BREAKING CHANGES
- release new codegen architecture and interfaces (#447)
- the interfaces for the voice agent have changed.
- resolve lint issue
- complete rearchitecture of the Node/JavaScript SDK to work in browsers and Node.
Release
Features
- abstract client rebuilt for namespace options (486fd86)
- add a method to send KeepAlive ws messages (#150) (880e943)
- add lint and build to workflow (1710c46)
- add linting for yaml files (f10d10d)
- add markdown linting (899b0e9)
- add missing feature toggles from q1 feature audit (#237) (7f972d1)
- add new models endpoints to SDK (630387d)
- add SpeakClient and example (a3112bc)
- add SpeakLiveClient and LiveTTSEvents (39a535d)
- add speechstarted event to sdk (#235) (1f80bab)
- add support for new beta release of summarisation (#143) (dfecdf2)
- add timeout mechanism to WebSocket mock waitForConnection method (a663956)
- add UtteranceEnd event to sdk (#234) (82f8b2f)
- add warning metadata and summarisation result to response type (#152) (1288778)
- adds support for agent mip_opt_out (#421) (76f9653)
- adds support for IUM (aa6cee2)
- adds support for speak fallback (#414) (8e59b55)
- adds ttl_seconds support (#420) (5ed8004)
- apply luke's suggestions (517ea3c)
- auth: add support for DEEPGRAM_ACCESS_TOKEN as per the other SDKs (7924959)
- Better VTT and SRT (#141) (c3cfc28)
- configurable websocket url (73e53e3)
- convert all legacy options to namespaced options (154ba30)
- errors: enhance WebSocket error output and abstract connection setup (36778e9)
- filler words release (74a4e56)
- filler words release (11b90b8)
- finish it up! (73e53e3)
- finishing touches TTS live client (5da606d)
- i feel like i'm getting nowhere here (73e53e3)
- implement
no_delay(726f676) - implement multi-lingual (034d5b0)
- implements
finalizeon the liveclient (cee0704) - improve experience around usage of custom API endpoints (#230) (b779348)
- latest spec fixes (1a37177)
- lint the examples (744fe1a)
- make provider objects generic (b0fc5cb)
- merge in new websocket transmitter changes (565ae2c)
- Merge pull request #238 from deepgram/release/jan-minor-1 (f598162)
- migrate to agent v1 (3a8493b)
- new metadata models endpoints (630387d)
- officially enable aura-2 in live text-to-speech (6b122f9)
- plug live client into new options (8510726)
- plug rest clients into new options (e2f3d8f)
- post-EA changes (630387d)
- rebuilding config and class interfaces (501d6d0)
- release new codegen architecture and interfaces (#447) (4c56fd9)
- release voice agent (73e53e3)
- release voice agent v1 (96753f9)
- Release/3.x.x 20240427 (#271) (7a76f75)
- remove container from websocket speak options (2a03f9a)
- remove specific error typing from the method definitions (#142) (8fbbee7)
- rename reset method to clear, respond with "Clear" payload (b409f8d)
- send back raw buffer instead of ArrayBuffer (298df5c)
- set up linting for typescript (6590d73)
- simplify and standardize examples (81689db)
- sits for JS sdk (#233) (d8de666)
- speak endpoint added (279ad76)
- speak endpoint added (8948856)
- support context length option ([7b22b07](7b22b07c802ff7ee5454eed757...
v5.0.0-beta.4
v5.0.0-beta.4
🎯 What's New
This beta release includes important documentation improvements, enhanced TypeScript support, and better test coverage.
✨ Enhancements
- Enhanced TypeScript Support: Types can now be imported directly (e.g.,
import { ListenV1Response } from "@deepgram/sdk") in addition to the namespace import, improving IDE autocomplete and discoverability - Improved Documentation:
- Clarified that proxy servers are required for browser REST API calls due to CORS header restrictions
- Added detailed explanation of why the proxy is needed (custom headers not whitelisted)
- Enhanced migration guide with examples of both direct and namespace type imports
- Improved README with better examples and explanations
- Better Binary Handling: Fixed critical issue where TTS audio streams were incorrectly parsed as JSON by removing autogenerated message handler
- Improved Examples: All middleware examples converted from JavaScript to TypeScript for better type safety and developer experience
- Enhanced Testing: Added comprehensive tests for custom providers, fallback configurations, and base URL priority handling
- Better Configuration: Improved base URL handling and configuration priority
🧪 Testing Improvements
- Added tests for agent custom providers and fallbacks
- Added tests for base URL configuration priority
- Added tests for custom base URL handling
- Expanded example coverage for middleware use cases
📝 Documentation
- Updated fernignore to protect custom test files
- Improved middleware example documentation
🔧 Internal Changes
- Multiple SDK regenerations to keep up with API changes
- Improved build and test infrastructure
📦 Installation
npm install @deepgram/sdk@5.0.0-beta.4🔗 Full Changelog
Commits since v5.0.0-beta.3:
- f155120 SDK regeneration
- fbd867c chore: update fernignore
- 16cf0fc Revert "feat: add custom middleware package (TODO: ws support, rest works)"
- 0600353 feat: add custom middleware package (TODO: ws support, rest works)
- 98248d8 feat: test custom providers and fallbacks maybe?
- b3df50c chore: sdk regeneration
- 4e7a1fd feat: convert middleware examples to typescript
- 5af2bab test: add tests for baseurl config priority
- e8f05eb chore: sdk regeneration
- 3fdcf28 SDK regeneration
⚠️ Beta Release Notice
This is a beta release of v5.0.0. Whilst we're confident in the stability, please report any issues you encounter!
- Report issues: https://github.com/deepgram/deepgram-js-sdk/issues
- Docs: https://developers.deepgram.com/
- Discord: https://discord.gg/deepgram
v5.0.0-beta.2
v5.0.0-beta.2
🐛 Bug Fixes
- fix: import file extension - Fixed missing
.jsextension inCustomClient.tsimport that was causing ESM build failures in React projects and other bundlers (8851047)
✨ Features
- feat(ci): use artifact so we only build once - CI now builds once and shares artifacts between jobs, improving build efficiency (
b648ab8) - feat(tests): add test to confirm ESM build - Added ESM build validation tests to catch import extension issues automatically (
68c3979)
🔒 Security
- Potential fix for code scanning alert no. 73 - Fixed shell command built from environment values (
1288efc)
📚 Documentation
- docs: update migration link in readme - Updated migration documentation link (
2a04883)
Full Changelog: v5.0.0-beta.1...v5.0.0-beta.2
v5.0.0-beta.1
We're thrilled to announce the first beta release of the Deepgram JavaScript SDK v5! This is a major rewrite that brings significant improvements to developer experience, type safety, and API consistency.
Highlights
- Auto-generated SDK built with Fern for better maintainability and API consistency
- Full TypeScript support with auto-generated types for all API responses
- Versioned API namespaces (
v1,v2) that mirror our REST API structure - Simplified error handling using standard try/catch instead of
{ result, error }destructuring - New V2 Live Transcription API with improved streaming capabilities
- Native access token support for short-lived authentication
Breaking Changes
Client Initialization
// Before (v4)
import { createClient } from "@deepgram/sdk";
const deepgram = createClient("YOUR_API_KEY");
// After (v5)
import { DeepgramClient } from "@deepgram/sdk";
const deepgram = new DeepgramClient({ apiKey: "YOUR_API_KEY" });API Method Paths
All API methods now include versioned namespaces:
| v4 | v5 |
|---|---|
listen.prerecorded.transcribeUrl() |
listen.v1.media.transcribeUrl() |
listen.live() |
listen.v1.connect() / listen.v2.connect() |
speak.request() |
speak.v1.audio.generate() |
speak.live() |
speak.v1.connect() |
read.analyzeText() |
read.v1.text.analyze() |
manage.getProjects() |
manage.v1.projects.list() |
auth.grantToken() |
auth.v1.tokens.grant() |
onprem.* |
selfHosted.v1.distributionCredentials.* |
models.getAll() |
manage.v1.models.list() |
Error Handling
// Before (v4)
const { result, error } = await deepgram.listen.prerecorded.transcribeUrl(...);
if (error) { /* handle error */ }
// After (v5)
try {
const data = await deepgram.listen.v1.media.transcribeUrl(...);
} catch (error) {
// Error includes: statusCode, body, rawResponse
}WebSocket Connections
// Before (v4)
const connection = deepgram.listen.live({ model: "nova-3" });
connection.on(LiveTranscriptionEvents.Transcript, (data) => { ... });
// After (v5)
const connection = await deepgram.listen.v1.connect({ model: "nova-3" });
connection.on("message", (data) => {
if (data.type === "Results") { ... }
});
connection.connect();
await connection.waitForOpen();New Features
V2 Live Transcription API
A new streaming transcription endpoint with improved features:
const connection = await deepgram.listen.v2.connect({ model: "flux-general-en" });
connection.on("message", (data) => {
if (data.type === "TurnInfo") {
console.log("Turn Info:", data);
}
});
connection.connect();
await connection.waitForOpen();
connection.sendMedia(audioChunk);Access Token Authentication
Native support for short-lived access tokens:
// Generate a token
const { accessToken } = await deepgram.auth.v1.tokens.grant();
// Use the token
const client = new DeepgramClient({ accessToken });Session ID Tracking
Automatic session ID generation for request tracking and debugging.
Migration Guide
For detailed migration instructions, see our Migration Guide.
Installation
npm install @deepgram/sdk@betaFeedback
This is a beta release and we'd love your feedback! Please open an issue on GitHub if you encounter any problems or have suggestions.
v5.0.0-alpha.2
This changelog covers all changes from v5.0.0-alpha.1 to v5.0.0-alpha.2.
🚀 Major Changes
Browser SDK Support
- Added: Full browser SDK compilation and support
- Added: Browser-compatible WebSocket implementation using custom client
- Added: Browser testing infrastructure with comprehensive test suite
- Changed: Migrated custom WebSocket logic to dedicated client implementation
Security Improvements
- Added:
.npmrcconfiguration for enhanced security - Changed: API keys are no longer stored in memory unnecessarily
✨ New Features
Browser Support
- Added: Browser SDK compilation that works without errors in examples
- Added: WebSocket support for browser environments
- Custom WebSocket client implementation
- Proper protocol handling (using protocol instead of headers for WebSockets)
- Audio handling fixes for browser WebSocket examples
- Added: Browser testing infrastructure
- Comprehensive browser test suite
- Test helpers for browser environment
- Examples can now run in browser context
Developer Experience
- Added: Makefile for running examples (
make run-examples) - Added: Improved Makefile with better help text and colors
- Added: Script to update imports before running wire tests (
tools/update-imports.js) - Added: Environment variable support for examples
- Examples now use environment variables
- CI environment configured to run examples
Infrastructure
- Added: Custom WebSocket client migration
- Migrated custom WebSocket logic to dedicated client
- Improved WebSocket connection handling
- Better separation of concerns
🐛 Bug Fixes
API Fixes
- Fixed: Support for keyterms with Flux models in
ListenLiveClient(#449)- Previously, the SDK would throw an error when using keyterms with Flux models
- Now supports both Nova-3 and Flux streaming models for keyterms
- Preserves validation behavior for unsupported models (e.g., nova-2)
- See: https://developers.deepgram.com/docs/keyterm
Browser Fixes
- Fixed: Audio handling in browser WebSocket examples
- Fixed issue where audio was incorrectly handled as a string
- Proper audio data handling for browser environments
- Fixed: Build order issues
- Browser build was deleting other builds during compilation
- Fixed build sequence to prevent conflicts
Tooling Fixes
- Fixed: Makefile issues
- Fixed broken Makefile commands
- Updated to use
pnpm execfor proper command execution
- Fixed: CI configuration
- Fixed CodeQL analysis to ignore examples (not production code)
- Improved CI permissions handling
🔧 Infrastructure & Tooling
Build System
- Improved: Build order handling
- Improved: Browser build process
- Added: Proper example ignoring in build processes
CI/CD
- Updated: CI to use Makefile for all commands
- Improved: CI permissions handling
- Fixed: CodeQL analysis configuration
- Examples are now properly ignored in CodeQL scans
- Added proper ignore patterns for non-production code
Development Tools
- Added: Makefile improvements
- Better help text with colors
- Unified command execution via
pnpm exec - Examples runner (
make run-examples)
- Added: Import update script for wire tests
- Script to automatically update imports before running wire tests
- Improves developer workflow
Configuration
- Added:
.npmrcfor security - Updated:
.fernignorepatterns- Better ignore patterns for examples
- Improved Fern configuration
📚 Documentation & Examples
Examples
- Updated: Examples now use environment variables
- Fixed: Browser WebSocket examples with proper audio handling
- Added: Makefile command to run examples easily
Code Quality
- Improved: CodeQL analysis configuration
- Updated: Fern ignore patterns for better code generation
🔄 SDK Regeneration
Multiple SDK regeneration commits were made during this period:
- Several SDK regenerations by
fern-api[bot] - Some regenerations were reverted and reapplied as part of the development process
- Final regeneration included in release
📦 Package Details
- Base Version: 5.0.0-alpha.1
- Current Commit: e83f09a (v5.0.0-alpha.2)
- Date Range: December 16-18, 2025
📝 Commits Summary
Features Added
- Browser SDK compilation and examples support
- Browser testing infrastructure
- WebSocket support in browser
- Custom WebSocket client migration
- Makefile improvements
- npmrc for security
- Import update script for wire tests
- Environment variable support for examples
- Security improvement: don't store API keys unnecessarily
Bug Fixes
- Keyterms support for Flux models in ListenLiveClient
- Audio handling in browser WebSocket examples
- Build order issues
- Makefile command execution
- CI CodeQL configuration
Chores
- Multiple SDK regenerations
- CI improvements
- Fern ignore pattern updates
- CodeQL analysis fixes
🙏 Contributors
- Naomi Carrigan
- Adrian Martinez
- fern-api[bot]
For questions or issues, please visit: