Migrating-v2-to-v3.md

v2 to v3+ Migration Guide

This guide helps you migrate from Deepgram Node SDK v2 to the Deepgram JavaScript SDK v3+ (versions 3.0.0 and above). The v3+ release introduces significant improvements including isomorphic JavaScript/Node.js support, better error handling, scoped configuration, and support for future products.

Table of Contents

• Installation
• Configuration Changes
• API Method Changes
  • Listen V1
  • Manage V1
  • Self-Hosted V1
• Breaking Changes Summary

Installation

npm install @deepgram/sdk

Configuration Changes

v2 Client Initialization

import { Deepgram } from "@deepgram/sdk";

const deepgram = new Deepgram(DEEPGRAM_API_KEY);

v3+ Client Initialization

import { createClient } from "@deepgram/sdk";

const deepgram = createClient(DEEPGRAM_API_KEY);

// With scoped configuration
const deepgram = createClient(DEEPGRAM_API_KEY, {
  global: { url: "http://localhost:8080" },
});

API Method Changes

Listen V1

Transcribe File

v2

import fs from "fs";

const response = await deepgram.transcription.preRecorded(
  {
    stream: fs.createReadStream("./examples/spacewalk.wav"),
    mimetype: MIMETYPE_OF_FILE,
  },
  {
    model: "nova-3",
  }
);

v3+

import fs from "fs";

const { result, error } = await deepgram.listen.prerecorded.transcribeFile(
  fs.createReadStream("./examples/spacewalk.wav"),
  {
    model: "nova-3",
  }
);

Transcribe URL

v2

const response = await deepgram.transcription.preRecorded(
  {
    url: "https://dpgr.am/spacewalk.wav",
  },
  {
    model: "nova-3",
  }
);

v3+

const { result, error } = await deepgram.listen.prerecorded.transcribeUrl(
  {
    url: "https://dpgr.am/spacewalk.wav",
  },
  {
    model: "nova-3",
  }
);

Transcribe File with Callback

v2

import fs from "fs";

const response = await deepgram.transcription.preRecorded(
  {
    stream: fs.createReadStream("./examples/spacewalk.wav"),
    mimetype: MIMETYPE_OF_FILE,
  },
  {
    model: "nova-3",
    callback: "http://callback/endpoint",
  }
);

v3+

import { createClient, CallbackUrl } from "@deepgram/sdk";
import fs from "fs";

const { result, error } =
  await deepgram.listen.prerecorded.transcribeFileCallback(
    fs.createReadStream("./examples/spacewalk.wav"),
    new CallbackUrl("http://callback/endpoint"),
    {
      model: "nova-3",
    }
  );

Transcribe URL with Callback

v2

const response = await deepgram.transcription.preRecorded(
  {
    url: "https://dpgr.am/spacewalk.wav",
  },
  {
    model: "nova-3",
    callback: "http://callback/endpoint",
  }
);

v3+

import { createClient, CallbackUrl } from "@deepgram/sdk";

const { result, error } =
  await deepgram.listen.prerecorded.transcribeUrlCallback(
    {
      url: "https://dpgr.am/spacewalk.wav",
    },
    new CallbackUrl("http://callback/endpoint"),
    {
      model: "nova-3",
    }
  );

WebSocket Streaming (Listen V1)

v2

const dgConnection = await deepgram.transcription.live({
  model: "nova-3",
});

source.addListener("got-some-audio", async (event) => {
  dgConnection.send(event.raw_audio_data);
});

dgConnection.addListener("transcriptReceived", (transcription) => {
  console.log(transcription.data);
});

v3+

import { LiveTranscriptionEvents } from "@deepgram/sdk";

const dgConnection = deepgram.listen.live({ model: "nova-3" });

dgConnection.on(LiveTranscriptionEvents.Open, () => {
  dgConnection.on(LiveTranscriptionEvents.Transcript, (data) => {
    console.log(data);
  });

  source.addListener("got-some-audio", async (event) => {
    dgConnection.send(event.raw_audio_data);
  });
});

Manage V1

Projects

v2

// Get projects
const result = await deepgram.projects.list();

// Get project
const result = await deepgram.projects.get(projectId);

// Update project
const result = await deepgram.projects.update(projectId, options);

// Delete project
await deepgram.projects.delete(projectId);

v3+

// Get projects
const { result, error } = await deepgram.manage.getProjects();

// Get project
const { result, error } = await deepgram.manage.getProject(projectId);

// Update project
const { result, error } = await deepgram.manage.updateProject(
  projectId,
  options
);

// Delete project
const { error } = await deepgram.manage.deleteProject(projectId);

Keys

v2

// List keys
const result = await deepgram.keys.list(projectId);

// Get key
const result = await deepgram.keys.get(projectId, projectKeyId);

// Create key
const result = await deepgram.keys.create(
  projectId,
  comment,
  scopes,
  options
);

// Delete key
await deepgram.keys.delete(projectId, projectKeyId);

v3+

// List keys
const { result, error } = await deepgram.manage.getProjectKeys(projectId);

// Get key
const { result, error } = await deepgram.manage.getProjectKey(
  projectId,
  projectKeyId
);

// Create key
const { result, error } = await deepgram.manage.createProjectKey(
  projectId,
  options
);

// Delete key
const { error } = await deepgram.manage.deleteProjectKey(
  projectId,
  projectKeyId
);

Members

v2

// Get members
const result = await deepgram.members.listMembers(projectId);

// Remove member
const result = await deepgram.members.removeMember(projectId, projectMemberId);

v3+

// Get members
const { result, error } = await deepgram.manage.getProjectMembers(projectId);

// Remove member
const { error } = await deepgram.manage.removeProjectMember(
  projectId,
  projectMemberId
);

Scopes

v2

// Get scopes
const result = await deepgram.scopes.get(projectId, projectMemberId);

// Update scope
const result = await deepgram.scopes.update(
  projectId,
  projectMemberId,
  scope
);

v3+

// Get scopes
const { result, error } = await deepgram.manage.getProjectMemberScopes(
  projectId,
  projectMemberId
);

// Update scope
const { result, error } = await deepgram.manage.updateProjectMemberScope(
  projectId,
  projectMemberId,
  options
);

Invitations

v2

// List invites
const result = await deepgram.invitation.list(projectId);

// Send invite
const result = await deepgram.invitation.send(projectId, options);

// Delete invite
const result = await deepgram.invitation.delete(projectId, email);

// Leave project
const result = await deepgram.invitation.leave(projectId);

v3+

// List invites
const { result, error } = await deepgram.manage.getProjectInvites(projectId);

// Send invite
const { result, error } = await deepgram.manage.sendProjectInvite(
  projectId,
  options
);

// Delete invite
const { error } = await deepgram.manage.deleteProjectInvite(projectId, email);

// Leave project
const { result, error } = await deepgram.manage.leaveProject(projectId);

Usage

v2

// Get all requests
const result = await deepgram.usage.listRequests(projectId, options);

// Get request
const result = await deepgram.usage.getRequest(projectId, requestId);

// Get usage summary
const result = await deepgram.usage.getUsage(projectId, options);

// Get usage fields
const result = await deepgram.usage.getFields(projectId, options);

v3+

// Get all requests
const { result, error } = await deepgram.manage.getProjectUsageRequests(
  projectId,
  options
);

// Get request
const { result, error } = await deepgram.manage.getProjectUsageRequest(
  projectId,
  requestId
);

// Get usage summary
const { result, error } = await deepgram.manage.getProjectUsageSummary(
  projectId,
  options
);

// Get usage fields
const { result, error } = await deepgram.manage.getProjectUsageFields(
  projectId,
  options
);

Billing

v2

// Get all balances
const result = await deepgram.billing.listBalances(projectId);

// Get balance
const result = await deepgram.billing.getBalance(projectId, balanceId);

v3+

// Get all balances
const { result, error } = await deepgram.manage.getProjectBalances(projectId);

// Get balance
const { result, error } = await deepgram.manage.getProjectBalance(
  projectId,
  balanceId
);

Self-Hosted V1

Distribution Credentials

v2

Not available in v2.

v3+

// List credentials
const { result, error } = await deepgram.onprem.listCredentials(projectId);

// Get credentials
const { result, error } = await deepgram.onprem.getCredentials(
  projectId,
  credentialId
);

// Create credentials
const { result, error } = await deepgram.onprem.createCredentials(
  projectId,
  options
);

// Delete credentials
const { result, error } = await deepgram.onprem.deleteCredentials(
  projectId,
  credentialId
);

Breaking Changes Summary

Major Changes

1. SDK Structure: Renamed from Node SDK to JavaScript SDK with isomorphic support
2. Client Initialization: New createClient() function replaces new Deepgram() class
3. Module Support: ESM and UMD support added for browser usage
4. API Structure: Namespaced API structure (listen.prerecorded, manage)
5. Callback Methods: Separated into dedicated *Callback methods
6. WebSocket Implementation: New event system using LiveTranscriptionEvents enum
7. Error Handling: New { result, error } destructuring pattern
8. HTTP Client: Switched from request to fetch

Removed Features

• Old Deepgram class (replaced with createClient function)
• Direct transcription.preRecorded() method (split into transcribeFile, transcribeUrl)
• Old addListener / transcriptReceived event system (replaced with on / LiveTranscriptionEvents)
• Old management API namespaces (projects, keys, members, scopes, invitation, usage, billing)

New Features in v3+

• Isomorphic Support: Works in both Node.js and browsers
• ESM/UMD Modules: CDN support for browser usage
• Scoped Configuration: Configure SDK aspects from initialization
• Self-Hosted APIs: New on-premise deployment support
• Better Error Handling: Structured { result, error } return pattern
• Captions Package: WebVTT and SRT captions available as standalone package (deepgram-js-captions)

Migration Checklist

• Update to latest version: npm install @deepgram/sdk
• Replace new Deepgram() with createClient()
• Update import from Deepgram to createClient
• Update transcription.preRecorded() calls to listen.prerecorded.transcribeFile() or listen.prerecorded.transcribeUrl()
• Move callback-based transcriptions to dedicated *Callback methods using CallbackUrl
• Update WebSocket event handling to use LiveTranscriptionEvents enum
• Update management API calls from direct namespaces to manage.*
• Add { result, error } destructuring to all API responses
• Remove mimetype from file transcription calls
• Test all functionality with new API structure

Notes

• WebVTT and SRT captions are now available as a standalone package: deepgram-js-captions
• Self-hosted API functionality is new in v3+