Beta Deepgram API (1.0.0)

Deepgram's API gives you streamlined access to Deepgram products, including automatic transcription from Deepgram's off-the-shelf and trained speech recognition models, and to all of your Deepgram resources, such as your account's projects, API keys, billing settings and balances, and usage statistics.

Our SDKs make integrating and interacting with our API quick and easy.

Server

URL
https://api.deepgram.com/v1

Authentication

Header

Send requests to the API with an Authorization header that references your project's API Key:

Authorization: Token <YOUR_DEEPGRAM_API_KEY>

You can create a Deepgram API Key in the Deepgram Console. You must create your first API Key using the Console.

Security Scheme Type API Key
Header parameter name: Authorization

Transcription

High-speed transcription of either pre-recorded or streaming audio. This feature is very fast, can understand nearly every audio format available, and is customizable. You can customize your transcript using various query parameters and apply general purpose and custom-trained AI models.

Transcribe Pre-recorded Audio

Transcribes the specified audio file.

Query Parameters

NameDescription
model
string

AI model used to process submitted audio.

Off-the-shelf Deepgram models include:

  • general: Optimized for everyday audio processing; if you aren't sure which model to select, start here.
  • meeting: Optimized for conference room settings, which include multiple speakers with a single microphone.
  • phonecall: Optimized for low-bandwidth audio phone calls.
  • conversationalai (Labs): Optimized to allow artificial intelligence technologies, such as chatbots, to interact with people in a human-like way.

You may also use a custom model associated with your account by including its custom_id.

Default: general
Possible Values: general, phonecall, meeting, conversationalai OR <custom_id>
Examples:
Select Example
version
string

Version of the model to use.

Default: latest
Possible Values: latest OR <version_id>
Examples:
Select Example
language
string

BCP-47 language tag that hints at the primary spoken language. To learn more, see Feature: Language. Language support is optimized for the following language/model combinations:

LanguageRegionModel(s)
English
en-GB
general
phonecall
en-IN
general
phonecall
en-NZ
general
en-US
general
meeting
phonecall
French
Labs
fr
general
Hindi
Labs
hi
general
Korean
ko
general
Portuguese
Labs
pt
general
pt-BR
general
Russian
Labs
ru
general
Spanish
es
general
Turkish
tr
general
Default: en-US
Possible Values: en-GB, en-IN, en-NZ, en-US, es, fr, hi, ko, pt, pt-BR, ru, tr OR null
Examples:
Select Example
punctuate
boolean

Indicates whether to add punctuation and capitalization to the transcript. To learn more, see Feature: Punctuate.

Examples:
Select Example
profanity_filter
boolean

Indicates whether to remove profanity from the transcript. To learn more, see Feature: Profanity Filter.

Examples:
Select Example
redact
any

Indicates whether to redact sensitive information, replacing redacted content with asterisks (*). Options include:

  • pci: Redacts sensitive credit card information, including credit card number, expiration date, and CVV
  • numbers (or true): Aggressively redacts strings of numerals
  • ssn (beta): Redacts social security numbers

To learn more, see Feature: Redaction.

Possible Values: pci, numbers, ssn, true OR null
Examples:
Select Example
diarize
boolean

Indicates whether to recognize speaker changes. When set to true, each word in the transcript will be assigned a speaker number starting at 0. To learn more, see Feature: Diarization

Examples:
Select Example
ner
boolean

Indicates whether to recognize alphanumeric strings. When set to true, whitespace will be removed between characters identified as part of an alphanumeric string. To learn more, see Feature: Named-Entity Recognition (NER)

Examples:
Select Example
multichannel
boolean

Indicates whether to transcribe each audio channel independently. When set to true, you will receive one transcript for each channel, which means you can apply a different model to each channel using the model parameter (e.g., set model to general:phonecall, which applies the general model to channel 0 and the phonecall model to channel 1).

Examples:
Select Example
alternatives
integer

Maximum number of transcript alternatives to return. Just like a human listener, Deepgram can provide multiple possible interpretations of what it hears.

Default: 1
Example:

alternatives=1

numerals
boolean

Indicates whether to convert numbers from written format (e.g., one) to numerical format (e.g., 1). To learn more, see Feature: Numerals.

Deepgram can format numbers up to 999,999.

Examples:
Select Example
search
any

Terms or phrases to search for in the submitted audio. Deepgram searches for acoustic patterns in audio rather than text patterns in transcripts because we have noticed that acoustic pattern matching is more performant.

"
Examples:
Select Example
callback
string

Callback URL to provide if you would like your submitted audio to be processed asynchronously. When passed, Deepgram will immediately respond with a request_id. When it has finished analyzing the audio, it will send a POST request to the provided URL with an appropriate HTTP status code.

For streaming audio, callback can be used to redirect streaming responses to a different server:
  • If the callback URL begins with http:// or https://, then POST requests are sent to the callback server for each streaming response.
  • If the callback URL begins with ws:// or wss://, then a WebSocket connection is established with the callback server and WebSocket text messages are sent containing the streaming responses.
  • If a WebSocket callback connection is disconnected at any point, the entire real-time transcription stream is killed; this maintains the strong guarantee of a one-to-one relationship between incoming real-time connections and outgoing WebSocket callback connections.

keywords
any

Keywords to which the model should pay particular attention to boosting or suppressing to help it understand context. Just like a human listener, Deepgram can better understand mumbled, distorted, or otherwise hard-to-decipher speech when it knows the context of the conversation.

To learn more about the most effective way to use keywords and recognize context in your transcript, see Feature: Keyword Boosting.

Examples:
Select Example
utterances
boolean

Indicates whether Deepgram will segment speech into meaningful semantic units, which allows the model to interact more naturally and effectively with speakers' spontaneous speech patterns. For example, when humans speak to each other conversationally, they often pause mid-sentence to reformulate their thoughts, or stop and restart a badly-worded sentence. When utterances is set to true, these utterances are identified and returned in the transcript results.

By default, when utterances is enabled, it starts a new utterance after 0.8 s of silence. You can customize the length of time used to determine where to split utterances by submitting the utt_split parameter.

To learn more, see Feature: Utterances.

Examples:
Select Example
utt_split
number

Length of time in seconds of silence between words that Deepgram will use when determining where to split utterances. Used when utterances is enabled. Defaults to 0.8 s.

Default: 0.8
Example:

utt_split=1.5

Request body schema

Request body when submitting pre-recorded audio. Accepts either:

  • raw binary audio data. In this case, include a Content-Type header set to the audio MIME type.
  • JSON object with a single field from which the audio can be retrieved. In this case, include a Content-Type header set to application/json.
NameDescription
url
string*

Location of audio file to transcribe.

Responses

StatusDescription
200 successAudio submitted for transcription.
Response Schema
NameDescription
metadata
object

JSON-formatted ListenMetadata object.

results
object

JSON-formatted ListenResults object.

cURL
Send
curl --request POST \ --url 'https://api.deepgram.com/v1/listen' \ --header 'Authorization: Token <YOUR_DEEPGRAM_API_KEY>' \ --header 'content-type: application/json' \ --data '{"url":"string"}'
Response
{
  • "metadata": {
    },
  • "results": {
    }
}
Was this section helpful?
Yes No

Transcribe Streaming Audio

Deepgram provides its customers with real-time, streaming transcription via its streaming endpoints. These endpoints are high-performance, full-duplex services running over the tried-and-true WebSocket protocol, which makes integration with customer pipelines simple due to the wide array of client libraries available.

To use this endpoint, connect to wss://api.deepgram.com/v1/listen. TLS encryption will protect your connection and data.

All data is sent to the streaming endpoint as binary-type WebSocket messages containing payloads that are the raw audio data. Because the protocol is full-duplex, you can stream in real-time and still receive transcription responses while uploading data.

When you are finished, send an empty (length zero) binary message to the server. The server will interpret it as a shutdown command, which means it wil finish processing whatever data is still has cached, send the response to the client, send a summary metadata object, and then terminate the WebSocket connection.

To learn more about working with real-time streaming data and results, see Streaming Audio in Real-Time.

Query Parameters

NameDescription
model
string

AI model used to process submitted audio.

Off-the-shelf Deepgram models include:

  • general: Optimized for everyday audio processing; if you aren't sure which model to select, start here.
  • meeting: Optimized for conference room settings, which include multiple speakers with a single microphone.
  • phonecall: Optimized for low-bandwidth audio phone calls.
  • conversationalai (Labs): Optimized to allow artificial intelligence technologies, such as chatbots, to interact with people in a human-like way.

You may also use a custom model associated with your account by including its custom_id.

Default: general
Possible Values: general, phonecall, meeting, conversationalai OR <custom_id>
Examples:
Select Example
version
string

Version of the model to use.

Default: latest
Possible Values: latest OR <version_id>
Examples:
Select Example
language
string

BCP-47 language tag that hints at the primary spoken language. To learn more, see Feature: Language. Language support is optimized for the following language/model combinations:

LanguageRegionModel(s)
English
en-GB
general
phonecall
en-IN
general
phonecall
en-NZ
general
en-US
general
meeting
phonecall
French
Labs
fr
general
Hindi
Labs
hi
general
Korean
ko
general
Portuguese
Labs
pt
general
pt-BR
general
Russian
Labs
ru
general
Spanish
es
general
Turkish
tr
general
Default: en-US
Possible Values: en-GB, en-IN, en-NZ, en-US, es, fr, hi, ko, pt, pt-BR, ru, tr OR null
Examples:
Select Example
punctuate
boolean

Indicates whether to add punctuation and capitalization to the transcript. To learn more, see Feature: Punctuate.

Examples:
Select Example
profanity_filter
boolean

Indicates whether to remove profanity from the transcript. To learn more, see Feature: Profanity Filter.

Examples:
Select Example
redact
any

Indicates whether to redact sensitive information, replacing redacted content with asterisks (*). Options include:

  • pci: Redacts sensitive credit card information, including credit card number, expiration date, and CVV
  • numbers (or true): Aggressively redacts strings of numerals
  • ssn (beta): Redacts social security numbers

To learn more, see Feature: Redaction.

Possible Values: pci, numbers, ssn, true OR null
Examples:
Select Example
diarize
boolean

Indicates whether to recognize speaker changes. When set to true, each word in the transcript will be assigned a speaker number starting at 0. To learn more, see Feature: Diarization

Examples:
Select Example
ner
boolean

Indicates whether to recognize alphanumeric strings. When set to true, whitespace will be removed between characters identified as part of an alphanumeric string. To learn more, see Feature: Named-Entity Recognition (NER)

Examples:
Select Example
multichannel
boolean

Indicates whether to transcribe each audio channel independently. When set to true, you will receive one transcript for each channel.

Examples:
Select Example
alternatives
integer

Maximum number of transcript alternatives to return. Just like a human listener, Deepgram can provide multiple possible interpretations of what it hears.

Default: 1
Example:

alternatives=1

numerals
boolean

Indicates whether to convert numbers from written format (e.g., one) to numerical format (e.g., 1). To learn more, see Feature: Numerals.

Deepgram can format numbers up to 999,999.

Examples:
Select Example
search
any

Terms or phrases to search for in the submitted audio. Deepgram searches for acoustic patterns in audio rather than text patterns in transcripts because we have noticed that acoustic pattern matching is more performant.

"
Examples:
Select Example
callback
string

Callback URL to provide if you would like your submitted audio to be processed asynchronously. When passed, Deepgram will immediately respond with a request_id. When it has finished analyzing the audio, it will send a POST request to the provided URL with an appropriate HTTP status code.

For streaming audio, callback can be used to redirect streaming responses to a different server:
  • If the callback URL begins with http:// or https://, then POST requests are sent to the callback server for each streaming response.
  • If the callback URL begins with ws:// or wss://, then a WebSocket connection is established with the callback server and WebSocket text messages are sent containing the streaming responses.
  • If a WebSocket callback connection is disconnected at any point, the entire real-time transcription stream is killed; this maintains the strong guarantee of a one-to-one relationship between incoming real-time connections and outgoing WebSocket callback connections.

keywords
any

Keywords to which the model should pay particular attention to boosting or suppressing to help it understand context. Just like a human listener, Deepgram can better understand mumbled, distorted, or otherwise hard-to-decipher speech when it knows the context of the conversation.

To learn more about the most effective way to use keywords and recognize context in your transcript, see Feature: Keyword Boosting.

Examples:
Select Example
interim_results
boolean

Indicates whether the streaming endpoint should send you updates to its transcription as more audio becomes available. By default, the streaming endpoint returns regular updates, which means transcription results will likely change for a period of time. You can avoid receiving these updates by setting this flag to false.

Examples:
Select Example
endpointing
boolean

Indicates whether Deepgram will detect whether a speaker has finished speaking (or paused for a significant period of time, indicating the completion of an idea). When Deepgram detects an endpoint, it assumes that no additional data will improve its prediction, so it immediately finalizes the result for the processed time range and returns the transcript with a speech_final parameter set to true.

For example, if you are working with a 15-second audio clip, but someone is speaking for only the first 3 seconds, endpointing allows you to get a finalized result after the first 3 seconds.

By default, endpointing is enabled and finalizes a transcript after 10 ms of silence. You can customize the length of time used to detect whether a speaker has finished speaking by submitting the vad_turnoff parameter.

To learn more, see Understand Endpointing.

Default: true
Examples:
Select Example
vad_turnoff
integer

Length of time in milliseconds of silence that voice activation detection (VAD) will use to detect that a speaker has finished speaking. Used when endpointing is enabled. Defaults to 10 ms. Deepgram customers may configure a value between 10 ms and 500 ms; on-premise customers may remove this restriction. To learn more, see Understand Endpointing.

Default: 10
Example:

vad_turnoff=30

encoding
string

Expected encoding of the submitted streaming audio.

Options include:

  • linear16: 16-bit, little endian, signed PCM WAV data
  • flac: FLAC-encoded data
  • mulaw: mu-law encoded WAV data
  • amr-nb: adaptive multi-rate narrowband codec (sample rate must be 8000)
  • amr-wb: adaptive multi-rate wideband codec (sample rate must be 16000)
  • opus: Ogg Opus
  • speex: Ogg Speex
Possible Values: amr-nb, amr-wb, flac, linear16, mulaw, opus OR speex
Example:

encoding=flac

channels
integer

Number of independent audio channels contained in submitted streaming audio. Only read when a value is provided for encoding.

Default: 1
Example:

channels=2

sample_rate
integer

Sample rate of submitted streaming audio. Required (and only read) when a value is provided for encoding.

Example:

sample_rate=16000

Responses

StatusDescription
201 successAudio submitted for transcription.
Response Schema
NameDescription
channel_index
array

Information about the active channel in the form [channel_index, total_number_of_channels].

duration
number

Duration in seconds.

start
number

Offset in seconds.

is_final
boolean

Indicates that Deepgram has identified a point at which its transcript has reached maximum accuracy and is sending a definitive transcript of all audio up to that point. To learn more, see Understand Interim Transcripts.

speech_final
boolean

Indicates that Deepgram has detected an endpoint and immediately finalized its results for the processed time range. To learn more, see Understand Endpointing.

channel
object
Javascript
Send
// Connect to the streaming endpoint. var establishConnection = function() { console.log("Establishing connection."); // Configure the websocket connection. // This requires ws installed using 'npm i ws'. const WebSocket = require('ws'); socket = new WebSocket( 'wss://api.deepgram.com/v1/listen', { // Replace with your Deepgram project's API Key. headers: { Authorization: 'Token YOUR_DEEPGRAM_API_KEY', }, } ); socket.onopen = (m) => { console.log("Socket opened!"); // Grab an audio file. var fs = require('fs'); var contents = fs.readFileSync('/path/to/audio/file.wav'); // Send the audio to the Deepgram API all at once (works if audio is relatively short). // socket.send(contents); // Send the audio to the Deepgram API in chunks of 1000 bytes. chunk_size = 1000; for (i = 0; i < contents.length; i += chunk_size) { slice = contents.slice(i, i + chunk_size); socket.send(slice); } // Send the message to close the connection. socket.send(new Uint8Array(0)); }; socket.onclose = (m) => { console.log("Socket closed."); }; socket.onmessage = (m) => { m = JSON.parse(m.data); // Log the received message. console.log(m); // Log just the words from the received message. if (m.hasOwnProperty('channel')) { let words = m.channel.alternatives[0].words; console.log(words); } }; }; var socket = null; establishConnection();
Response
{
  • "channel_index": [
    ],
  • "duration": 0,
  • "start": 0,
  • "is_final": true,
  • "speech_final": true,
  • "channel": {
    }
}
Was this section helpful?
Yes No

Projects

A Project organizes all of your Deepgram resources, including your datasets and models, into logical groups. Projects also give you access to API keys and billing settings for Deepgram services.

Get Projects

Retrieves all Projects to which the authenticated API key belongs.

Required account scope(s): project:read.

Responses

StatusDescription
200 successProjects found.
Response Schema
NameDescription
projects
array*

Array of project objects.

cURL
Send
curl --request GET \ --url https://api.deepgram.com/v1/projects \ --header 'Authorization: Token <YOUR_DEEPGRAM_API_KEY>' \ --header 'content-type: application/json'
Response
{
  • "projects": [
    ]
}
Was this section helpful?
Yes No

Get Project

Retrieves basic information about the specified project.

Required account/project scope(s): project:read.

Path Parameters

NameDescription
project_id
string*

Identifier of the project for which you want to retrieve information.

Responses

StatusDescription
200 successProject found.
Show common responses
Response Schema
NameDescription
project_id
string*

Identifier of the project.

name
string*

Name of the project.

company
string

Name of the company associated with the project. Optional.

cURL
Send
curl --request GET \ --url 'https://api.deepgram.com/v1/projects/{project_id}' \ --header 'Authorization: Token <YOUR_DEEPGRAM_API_KEY>' \ --header 'content-type: application/json'
Response
{
  • "project_id": "string",
  • "name": "string",
  • "company": "string"
}
Was this section helpful?
Yes No

Update Project

Updates the specified project.

Required account scope(s): project:write. Required project scope(s): project:write:settings.

Path Parameters

NameDescription
project_id
string*

Identifier of the project that you want to update.

Request body schema

NameDescription
name
string

Name of the project. Optional.

company
string

Name of the company associated with the project. Optional.

Responses

StatusDescription
200 successProject updated.
Response Schema
NameDescription
message
string*

Success message.

cURL
Send
curl --request PATCH \ --url 'https://api.deepgram.com/v1/projects/{project_id}' \ --header 'Authorization: Token <YOUR_DEEPGRAM_API_KEY>' \ --header 'content-type: application/json' \ --data '{"name":"string","company":"string"}'
Response
{
  • "message": "string"
}
Was this section helpful?
Yes No

Delete Project

Deletes the specified project.

Required account scope(s): project:write. Required project scope(s): project:write:destroy.

Path Parameters

NameDescription
project_id
string*

Identifier of the project that you want to delete.

Responses

StatusDescription
200 successProject deleted.
cURL
Send
curl --request DELETE \ --url 'https://api.deepgram.com/v1/projects/{project_id}' \ --header 'Authorization: Token <YOUR_DEEPGRAM_API_KEY>' \ --header 'content-type: application/json'
Was this section helpful?
Yes No

Keys

Keys are associated with Deepgram Projects. They enable you to use the Deepgram API, identify the Project calling the API, and associate usage information with Projects. Keys are assigned Scopes, which determine which actions they can be used to perform in the associated Project. For each Project, you can create multiple Keys and assign different Scopes for each Key.

Get Keys

Retrieves keys for the specified project. If the authenticated account has access to the members:read, admins:read, and owners:read project scopes, it will list all keys for the project. Otherwise, it will only list keys that belong to the authenticated account.

Required account/project scope(s): keys:read. Optional project scope(s): members:read, admins:read, owners:read.

Path Parameters

NameDescription
project_id
string*

Identifier of the project for which you want to get keys.

Responses

StatusDescription
200 successKeys found.
Response Schema
NameDescription
api_keys
array*

Array of API Key objects.

cURL
Send
curl --request GET \ --url 'https://api.deepgram.com/v1/projects/{project_id}/keys' \ --header 'Authorization: Token <YOUR_DEEPGRAM_API_KEY>' \ --header 'content-type: application/json'
Response
{
  • "api_keys": [
    ]
}
Was this section helpful?
Yes No

Create Key

Creates a new key in the specified project. You must create your first API Key using the Deepgram Console.

Required account/project scope(s): keys:write.

Path Parameters

NameDescription
project_id
string*

Identifier of the project for which you want to create a key.

Request body schema

NameDescription
comment
string

Comments associated with the key you would like to create. Must be between 1 and 128 characters long, not including whitespace.

scopes
array

Scopes for the key you would like to create. Scopes cannot be empty.

The requested account scopes for the new key cannot exceed the scopes of the authenticated account making the request.

The requested project scopes for the new key cannot exceed the scopes of the authenticated account making the request.

Responses

StatusDescription
201 successKey created.
Response Schema
NameDescription
key
string*

Value of the API Key. This is the only chance to read the Key value; it cannot be recovered later.

api_key_id
string*

Identifier of the API Key.

comment
string*

Comments associated with the API Key.

created
string*

Date and time when the API Key was created.

scopes
array*

Project scopes associated with the API Key.

cURL
Send
curl --request POST \ --url 'https://api.deepgram.com/v1/projects/{project_id}/keys' \ --header 'Authorization: Token <YOUR_DEEPGRAM_API_KEY>' \ --header 'content-type: application/json' \ --data '{"comment":"string","scopes":["string"]}'
Response
{
  • "key": "string",
  • "api_key_id": "string",
  • "comment": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "scopes": [
    ]
}
Was this section helpful?
Yes No

Get Key

Retrieves basic information about the specified key. If the authenticated account has access to the members:read, admins:read, and owners:read project scopes, it will retrieve the information for any key in the project. Otherwise, it will retrieve the information for only one of the keys that belong to the authenticated account.

Required account/project scope(s): keys:read. Optional project scope(s): members:read, admins:read, owners:read.

Path Parameters

NameDescription
project_id
string*

Identifier of the project for which you want to retrieve information.

key_id
string*

Identifier of the key that you want to retrieve.

Responses

StatusDescription
200 successKey found.
Show common responses
Response Schema
NameDescription
api_key_id
string*

Identifier of the API Key.

comment
string*

Comments associated with the API Key.

created
string*

Date and time when the API Key was created.

scopes
array*

Scopes associated with the API Key.

cURL
Send
curl --request GET \ --url 'https://api.deepgram.com/v1/projects/{project_id}/keys/{key_id}' \ --header 'Authorization: Token <YOUR_DEEPGRAM_API_KEY>' \ --header 'content-type: application/json'
Response
{
  • "api_key_id": "string",
  • "comment": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "scopes": [
    ]
}
Was this section helpful?
Yes No

Delete Key

Deletes the specified key in the specified project. If the authenticated account has access to the members:write, admins:write, and owners:write project scopes, it will delete any key in the project. Otherwise, it will delete only keys belonging to the authenticated account.

Required account/project scope(s): keys:write. Optional project scope(s): members:write, admins:write, owners:write.

Path Parameters

NameDescription
project_id
string*

Identifier of the project that contains the key that you want to delete.

key_id
string*

Identifier of the key that you want to delete.

Responses

StatusDescription
200 successKey deleted.
cURL
Send
curl --request DELETE \ --url 'https://api.deepgram.com/v1/projects/{project_id}/keys/{key_id}' \ --header 'Authorization: Token <YOUR_DEEPGRAM_API_KEY>' \ --header 'content-type: application/json'
Was this section helpful?
Yes No

Members

Members are users who have been given access to a specified Deepgram Project. Members are assigned Scopes, which determine what they can do in their assigned Project. Members can be assigned to multiple Projects and have different Scopes for each Project.

Get Members

Retrieves account objects for all of the accounts in the specified project.

Required account scope(s): project:read. Required project scope(s): project:read, members:read, admins:read, owners:read.

Path Parameters

NameDescription
project_id
string*

Identifier of the project for which you want to get members.

Responses

StatusDescription
200 successMembers found.
Response Schema
NameDescription
members
array*

Array of Members.

cURL
Send
curl --request GET \ --url 'https://api.deepgram.com/v1/projects/{project_id}/members' \ --header 'Authorization: Token <YOUR_DEEPGRAM_API_KEY>' \ --header 'content-type: application/json'
Response
{
  • "members": [
    ]
}
Was this section helpful?
Yes No

Remove Member

Removes the specified account from the specified project. API keys created by this member for the specified project will also be deleted.

If the account being removed has scope member, then the requesting account must have scope members:write:kick. If the account being removed has scope admin, then the requesting account must have scope admins:write:kick. If the account being removed has scope owner, then the requesting account must have scope owners:write:kick. The account being removed must not be the sole account with the scope owner.

Required account scope(s): project:write. Required project scopes(s): members:write:kick or admins:write:kick or owners:write:kick.

Path Parameters

NameDescription
project_id
string*

Identifier of the project that contains the account you want to remove.

member_id
string*

Identifier of the account that you want to remove.

Responses

StatusDescription
200 successAccount removed.
cURL
Send
curl --request DELETE \ --url 'https://api.deepgram.com/v1/projects/{project_id}/members/{member_id}' \ --header 'Authorization: Token <YOUR_DEEPGRAM_API_KEY>' \ --header 'content-type: application/json'
Was this section helpful?
Yes No

Scopes

Scopes are permissions required to perform actions in a specified Deepgram Project. Scopes can be associated with Keys or Users. When associated with a Key, Scopes determine the actions that the Key can be used to perform in the Key's associated Project. When associated with a Member, Scopes determine what the user can do in their assigned Project. For more information, see Working with Roles.

Get Member Scopes

Lists the specified project scopes assigned to the specified member. If the authenticated account has access to the members:read:scopes, admins:read:scopes, and owners:read:scopes project scopes, it will retrieve project scopes for any member of the specified project. Otherwise, it will retrieve project scopes for only the authenticated account.

Required account scope(s): account:read, project:read. Required project scope(s): project:read. Optional project scope(s): members:read:scopes, admins:read:scopes, owners:read:scopes.

Path Parameters

NameDescription
project_id
string*

Identifier of the project that contains the member for whom you want to get scopes.

member_id
string*

Identifier of the member for whom you want to get scopes.

Responses

StatusDescription
200 successScopes found.
Response Schema
NameDescription
scopes
array*

Array of scopes associated with the member.

cURL
Send
curl --request GET \ --url 'https://api.deepgram.com/v1/projects/{project_id}/members/{member_id}/scopes' \ --header 'Authorization: Token <YOUR_DEEPGRAM_API_KEY>' \ --header 'content-type: application/json'
Response
{
  • "scopes": [
    ]
}
Was this section helpful?
Yes No

Update Scope

Updates the specified project scopes assigned to the specified member.

If the specified member has the scope member or the scope being added is member, the requesting account must have the scope members:write:scopes. If the specified member has the scope admin or the scope being added is admin, the requesting account must have the scope admins:write:scopes. If the specified member has the scope owner or the scope being added is owner, the requesting account must have the scope owners:write:scopes.

If the scope being added is member, admin, or owner, it will replace the existing member, admin, or owner scope of the specified member unless the specified member is the only member with the owner scope. In this case, the request will fail.

If the scope being added is not member, admin, or owner, then the requesting account must also have the scope that it is trying to add to the specified member. For example, if the requesting account tries to add the project:write:settings project scope to a specified member, but the requesting account itself does not have the scope project:write:settings, then the request will fail.

Required account scope(s): project:write. Optional project scope(s): See the description.

Path Parameters

NameDescription
project_id
string*

Identifier of the project that contains the specified member and scope that you want to update.

member_id
string*

Identifier of the member for whom you want to update the scope.

Request body schema

NameDescription
scope
string*

Scope for the specified member and project.

Responses

StatusDescription
200 successScope updated.
Response Schema
NameDescription
message
string*

Success message.

cURL
Send
curl --request PUT \ --url 'https://api.deepgram.com/v1/projects/{project_id}/members/{member_id}/scopes' \ --header 'Authorization: Token <YOUR_DEEPGRAM_API_KEY>' \ --header 'content-type: application/json' \ --data '{"scope":"string"}'
Response
{
  • "message": "string"
}
Was this section helpful?
Yes No

Invitations

To add a Member to a Deepgram Project, you can use the Deepgram Console or the Deepgram API to send an Invitation. When sending an Invitation, you provide an email address for the Member, and Deepgram generates an invitation link and emails it to them.

Leave Project

Removes the authenticated account from the specified project. Will also delete API Keys created by the account for the specified project. If the authenticated account is the only account on the project with the scope owner, the call will fail.

Required account scope(s): project:write.

Path Parameters

NameDescription
project_id
string*

Identifier of the project from which you want to remove the authenticated account.

Responses

StatusDescription
200 successAccount removed from project.
Response Schema
NameDescription
message
string*

Success message.

cURL
Send
curl --request DELETE \ --url 'https://api.deepgram.com/v1/projects/{project_id}/leave' \ --header 'Authorization: Token <YOUR_DEEPGRAM_API_KEY>' \ --header 'content-type: application/json'
Response
{
  • "message": "string"
}
Was this section helpful?
Yes No

Usage

Deepgram tracks requests made to Deepgram services and associates usage information with Projects.

Get All Requests

Generates a list of requests sent to the Deepgram API for the specified project over a given time range. Uses pagination to limit the number of results returned.

Path Parameters

NameDescription
project_id
string*

Identifier of the project for which you want to retrieve requests.

Query Parameters

NameDescription
start
string

Start date of the requested date range. Format is YYYY-MM-DD. Defaults to the time of your first request.

If no time zone is specified, defaults to Coordinated Universal Time (UTC).

Default: null
Examples:
Select Example
end
string

End date of the requested date range. Format is YYYY-MM-DD. Defaults to the current time.

If no time zone is specified, defaults to Coordinated Universal Time (UTC).

Examples:
Select Example
page
integer

Page number to return from within the list of requests.

0
Examples:
Select Example
limit
integer

Number of results to return per page.

Default: 10
status
string

Status of requests to return. Enables you to filter requests depending on whether they have succeeded or failed. If not specified, returns requests with all statuses.

Default: null
Possible Values: null, succeeded OR failed

Responses

StatusDescription
200 successRequests found. Requests will be returned in descending order based on creation time (newest first).
Response Schema
NameDescription
limit
integer*

Number of results to return per page. Used for pagination.

page
integer*

Page number that should be returned. Used for pagination.

requests
array*
cURL
Send
curl --request GET \ --url 'https://api.deepgram.com/v1/projects/{project_id}/requests' \ --header 'Authorization: Token <YOUR_DEEPGRAM_API_KEY>' \ --header 'content-type: application/json'
Response
{
  • "limit": 0,
  • "page": 0,
  • "requests": [
    ]
}
Was this section helpful?
Yes No

Get Request

Retrieves the details of the specified request sent to the Deepgram API for the specified project.

Path Parameters

NameDescription
project_id
string*

Identifier of the project for which you want to retrieve the specified request.

request_id
string*

Identifier of the request that you want to retrieve.

Responses

StatusDescription
200 successRequest found.
Show common responses
Response Schema
NameDescription
request_id
string*

Identifier of request.

created
string*

Date/time when request was created.

path
string*

Path of endpoint to which request was submitted.

api_key_id
string

Identifier of the API Key with which the request was submitted.

response
object*

Response generated by the request. If a response has not yet been generated, this object will be empty.

callback
object*

Only exists if a callback was included in the request. If a callback was included in the request, but the request has not completed yet, then this object will exist, but it will be empty.

cURL
Send
curl --request GET \ --url 'https://api.deepgram.com/v1/projects/{project_id}/requests/{request_id}' \ --header 'Authorization: Token <YOUR_DEEPGRAM_API_KEY>' \ --header 'content-type: application/json'
Response
{
  • "request_id": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "path": "string",
  • "api_key_id": "string",
  • "response": {
    },
  • "callback": {
    }
}
Was this section helpful?
Yes No

Summarize Usage

Retrieves a summary of usage statistics. You can specify a date range.

Path Parameters

NameDescription
project_id
string*

Identifier of the project for which you want to summarize usage.

Query Parameters

NameDescription
start
string

Start date of the requested date range. Format: YYYY-MM-DD. If a full timestamp is given, it will be truncated to a day. Dates are UTC. Defaults to the date of your first request.

Default: null
Examples:
Select Example
end
string

End date of the requested date range. Format is YYYY-MM-DD. If a full timestamp is given, it will be truncated to a day. Dates are UTC. Defaults to the current date.

Examples:
Select Example
accessor
string

Limits results to requests made using the API key corresponding to the given accessor. If not specified, returns requests made using all API keys. To include multiple API Keys, send multiple instances in query string (e.g., accessor=2ed1307e-14f2-48a2-b996-97ea009cfa4e&accessor=1dc0296d-03e1-37z1-1885-86dz998bez3d).

Examples:
Select Example
tag
string

Limits results to requests associated with the specified tag. If not specified, returns requests with all tags. To include multiple tags, send multiple instances in query string (e.g., tag=dev&tag=production).

Examples:
Select Example
method
string

Limits results to requests processed using the specified method. If not specified, returns requests with all processing methods. To include multiple methods, send multiple instances in query string (e.g., method=sync&method=streaming).

Possible values include:

  • sync
  • async
  • streaming
Possible Values: sync, async OR streaming
Examples:
Select Example
model
string

Limits results to requests run with the specified model applied. If not specified, returns requests with all models. To include multiple models, send multiple instances in query string (e.g., model=general&method=meeting).

Examples:
Select Example
multichannel
boolean

Limits results to requests that include the multichannel feature.

interim_results
boolean

Limits results to requests that include the interim_results feature.

punctuate
boolean

Limits results to requests that include the punctuate feature.

ner
boolean

Limits results to requests that include the ner feature.

utterances
boolean

Limits results to requests that include the utterances feature.

replace
boolean

Limits results to requests that include the replace feature.

profanity_filter
boolean

Limits results to requests that include the profanity_filter feature.

keywords
boolean

Limits results to requests that include the keywords feature.

sentiment
boolean

Limits results to requests that include the sentiment feature.

diarize
boolean

Limits results to requests that include the diarize feature.

detect_language
boolean

Limits results to requests that include the detect_language feature.

search
boolean

Limits results to requests that include the search feature.

redact
boolean

Limits results to requests that include the redact feature.

alternatives
boolean

Limits results to requests that include the alternatives feature.

numerals
boolean

Limits results to requests that include the numerals feature.

Responses

StatusDescription
200 successUsage statistics found.
Show common responses
Response Schema
NameDescription
start
string*

Start date for included requests.

end
string*

End date for included requests.

resolution
object*
results
array*
cURL
Send
curl --request GET \ --url 'https://api.deepgram.com/v1/projects/{project_id}/usage' \ --header 'Authorization: Token <YOUR_DEEPGRAM_API_KEY>' \ --header 'content-type: application/json'
Response
{
  • "start": "2019-08-24T14:15:22Z",
  • "end": "2019-08-24T14:15:22Z",
  • "resolution": {
    },
  • "results": [
    ]
}
Was this section helpful?
Yes No

Get Fields

Lists the features, models, tags, languages, and processing method used for requests in the specified project. You can specify a time range.

Path Parameters

NameDescription
project_id
string*

Identifier of the project for which you want to retrieve fields.

Query Parameters

NameDescription
start
string

Start date of the requested date range. Format is YYYY-MM-DD. If a full timestamp is given, it will be truncated to a day. Dates are UTC.

Defaults to the date of your first request.

Examples:
Select Example
end
string

End date of the requested date range. Format is YYYY-MM-DD. If a full timestamp is given, it will be truncated to a day. Dates are UTC.

Defaults to the current date.

Examples:
Select Example

Responses

StatusDescription
200 successRequest fields found.
Response Schema
NameDescription
tags
array*

Array of included tags.

Possible Values: dev OR production
models
array*

Array of included models.

processing_methods
array*

Array of processing methods.

Possible Values: sync, async OR streaming
languages
array*

Array of included languages.

features
array*

Array of included features.

Possible Values: multichannel, interim_results, punctuate, ner, utterances, replace, profanity_filter, keywords, sentiment, diarize, detect_language, search, redact, alternatives OR numerals
cURL
Send
curl --request GET \ --url 'https://api.deepgram.com/v1/projects/{project_id}/usage/fields' \ --header 'Authorization: Token <YOUR_DEEPGRAM_API_KEY>' \ --header 'content-type: application/json'
Response
{
  • "tags": [
    ],
  • "models": [
    ],
  • "processing_methods": [
    ],
  • "languages": [
    ],
  • "features": [
    ]
}
Was this section helpful?
Yes No

Billing

Deepgram tracks individual transactions and transaction summaries for Deepgram services.

Get All Balances

Generates a list of outstanding balances for the specified project. To see balances, the authenticated account must be a project owner or administrator.

Path Parameters

NameDescription
project_id
string*

Identifier of the project for which you want to retrieve outstanding balances.

Responses

StatusDescription
200 successBalances found.
Response Schema
NameDescription
balances
array*

Array of balance objects.

cURL
Send
curl --request GET \ --url 'https://api.deepgram.com/v1/projects/{project_id}/balances' \ --header 'Authorization: Token <YOUR_DEEPGRAM_API_KEY>' \ --header 'content-type: application/json'
Response
{
  • "balances": [
    ]
}
Was this section helpful?
Yes No

Get Balance

Retrieves details about the specified balance. To see balances, the authenticated account must be a project owner or administrator.

Path Parameters

NameDescription
project_id
string*

Identifier of the project for which you want to retrieve the specified balance.

balance_id
string*

Identifier of the balance that you want to retrieve.

Responses

StatusDescription
200 successBalance found.
Show common responses
Response Schema
NameDescription
balance_id
string*

Identifier of the balance.

amount
number*

Amount of the balance.

units
string*

Units of the balance. May use usd or hour, depending on the project billing settings.

purchase
string*

Identifier of the purchase order associated with the balance.

cURL
Send
curl --request GET \ --url 'https://api.deepgram.com/v1/projects/{project_id}/balances/{balance_id}' \ --header 'Authorization: Token <YOUR_DEEPGRAM_API_KEY>' \ --header 'content-type: application/json'
Response
{
  • "balance_id": "string",
  • "amount": 0,
  • "units": "string",
  • "purchase": "string"
}
Was this section helpful?
Yes No