logo
All Docs
API

Deepgram MissionControl API (0.0.2)

Server

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

Authentication

basicAuth

Basic authentication is the simplest to use, but it requires the server to make a call to an authentication service, which incurs processing time and network latency. Therefore, it is not the most efficient for repeated requests.

Security Scheme Type HTTP
HTTP Authorization Scheme basic

bearerAuth

A JSON Web Token that was acquired via a successful POST to the /login endpoint.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

cookieAuth

This cookie contains a JSON Web Token. It is set by a successful POST to the /login endpoint.

Security Scheme Type API Key
Header parameter name: dgToken

headerAuth

The token that was used to generate the JWT for cookie auth. A new token can be generated by a POST to the /login endpoint, whether credentials are supplied or not.

Security Scheme Type API Key
Header parameter name: x-xsrf-token

Introduction

The MissionControl API is a RESTful API. It provides programatic access to many of the features found in Deepgram MissionControl. It provides predictable endpoints for preparing training data, training and deploying custom speech models, and managing your account.

To learn what Deepgram offers for automatic transcription, see the Speech Recognition API Reference.

Account

APIs related to account management and overall usage.

Create account

post/signup

Request body schema

NameDescription
first_name
string*
last_name
string*
email
string*
password
string*

Responses

StatusDescription
201 successAccount was created.
Show common responses
cURL
Send
curl --request POST \
  --url https://missioncontrol.deepgram.com/v1//signup \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json' \
  --data '{"first_name":"FirstName","last_name":"LastName","email":"user@example.com","password":"password"}'
Was this section helpful?
Yes No

Log in to account

post/login

Upon successful login, a JWT is generated and stored in a cookie, and a token is generated and returned in the response body. Subsequent requests to other API endpoints can be authenticated more efficiently by including both the token in the x-xsrf-token header and the JWT cookie.

Cookie Parameters

NameDescription
XSRF-TOKEN
string

Header Parameters

NameDescription
X-XSRF-TOKEN
string

Responses

StatusDescription
200 successUser successfully logged in.
Response Headers
NameDescription

Value of the token that may be used to set the BRAIN-TOKEN cookie or the XSRF-TOKEN cookie.

Examples:
Select Example
Response Schema
NameDescription
token
string*
auth
boolean*
user
any*
cURL
Send
curl --request POST \
  --url https://missioncontrol.deepgram.com/v1//login \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'X-XSRF-TOKEN: SOME_STRING_VALUE' \
  --header 'content-type: application/json'
Response

Client has successfully authenticated.

{
  • "auth": true,
  • "token": "a7cf9b9d-a766-44e3-961f-8964e83d5737",
  • "user": {
    }
}
Was this section helpful?
Yes No

Get summary of account usage

get/usage

Responses

StatusDescription
200 successModel usage information found.
Response Schema
NameDescription
total
object*
history
array*
training
object*
labels
object*
asr
object*
cURL
Send
curl --request GET \
  --url https://missioncontrol.deepgram.com/v1//usage \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "total": {
    },
  • "history": [
    ],
  • "training": {
    },
  • "labels": {
    },
  • "asr": {
    }
}
Was this section helpful?
Yes No

Get all of your API keys

get/keys

Responses

StatusDescription
200 successList of API keys.
Response Schema
NameDescription
result
array*
cURL
Send
curl --request GET \
  --url https://missioncontrol.deepgram.com/v1//keys \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "result": [
    ]
}
Was this section helpful?
Yes No

Create API keys

post/keys

Query Parameters

NameDescription
name
string

Responses

StatusDescription
201 successAPI key created.
Response Schema
NameDescription
key
string*
secret
string*
cURL
Send
curl --request POST \
  --url https://missioncontrol.deepgram.com/v1//keys \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "key": "string",
  • "secret": "string"
}
Was this section helpful?
Yes No

Delete API key

delete/keys

Query Parameters

NameDescription
key
string

Responses

StatusDescription
204 successAPI key deleted.
cURL
Send
curl --request DELETE \
  --url https://missioncontrol.deepgram.com/v1//keys \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Was this section helpful?
Yes No

Get limits associated with user account

get/limits

Query Parameters

NameDescription
user-id
string

Unique identifier of user for whom to retrieve limits. If not specified, defaults to the user making the request.

Example:

aaaaaaaa-1111-2222-3333-444444444444

Responses

StatusDescription
200 successThe user's account limits.
Response Schema
NameDescription
min_training_seconds
number*

Minimum number of seconds of audio required to train a model.

cURL
Send
curl --request GET \
  --url https://missioncontrol.deepgram.com/v1//limits \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "min_training_seconds": 0
}
Was this section helpful?
Yes No

Set limits associated with user account

put/limits

Query Parameters

NameDescription
user-id
string

Unique identifier of user for whom to set limits. If not specified, defaults to the user making the request.

Example:

aaaaaaaa-1111-2222-3333-444444444444

Request body schema

Object containing properties to set for the specified user.

NameDescription
min_training_seconds
number

Minimum number of seconds of audio required to train a model.

Responses

StatusDescription
200 successThe user's account limits.
Response Schema
NameDescription
min_training_seconds
number*

Minimum number of seconds of audio required to train a model.

cURL
Send
curl --request PUT \
  --url https://missioncontrol.deepgram.com/v1//limits \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json' \
  --data '{"min_training_seconds":0}'
Response
{
  • "min_training_seconds": 0
}
Was this section helpful?
Yes No

Datasets

A dataset is a collection of resources. Note that a resource can belong to multiple datasets.

In order to train a model, all the resources in the dataset must be transcribed. The status of a dataset will be LABELED if and only if the status of every resource in the dataset is LABELED.

A model is trained on a single dataset. You can add resources to a dataset and re-train a model to get better results.

Get all datasets

get/datasets

Responses

StatusDescription
200 successList of datasets.
Response Schema
NameDescription
result
array*
cURL
Send
curl --request GET \
  --url https://missioncontrol.deepgram.com/v1//datasets \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "result": [
    ]
}
Was this section helpful?
Yes No

Create dataset

post/datasets

Query Parameters

NameDescription
name
string*
Example:

MyDataset

Responses

StatusDescription
201 successDataset created.
Show common responses
Response Schema
NameDescription
id
string*
Example:

dddddddd-1111-2222-3333-444444444444

name
string*
Example:

MyDataset

created
string*
resource_count
integer*
Example:

12

total_duration
number*
Example:

12345

status
string*
Possible Values: UNLABELED, IN_PROGRESS OR LABELED
read_only
boolean*
cURL
Send
curl --request POST \
  --url 'https://missioncontrol.deepgram.com/v1//datasets?name=MyDataset' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "id": "dddddddd-1111-2222-3333-444444444444",
  • "name": "MyDataset",
  • "created": "2019-08-24T14:15:22Z",
  • "resource_count": 12,
  • "total_duration": 12345,
  • "status": "UNLABELED",
  • "read_only": true
}
Was this section helpful?
Yes No

Get dataset

get/datasets/{dataset_id}

Path Parameters

NameDescription
dataset_id
string*

Unique identifier of dataset.

Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Responses

StatusDescription
200 successSpecified dataset retrieved.
Response Schema
NameDescription
id
string*
Example:

dddddddd-1111-2222-3333-444444444444

name
string*
Example:

MyDataset

created
string*
resource_count
integer*
Example:

12

total_duration
number*
Example:

12345

status
string*
Possible Values: UNLABELED, IN_PROGRESS OR LABELED
read_only
boolean*
cURL
Send
curl --request GET \
  --url https://missioncontrol.deepgram.com/v1//datasets/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "id": "dddddddd-1111-2222-3333-444444444444",
  • "name": "MyDataset",
  • "created": "2019-08-24T14:15:22Z",
  • "resource_count": 12,
  • "total_duration": 12345,
  • "status": "UNLABELED",
  • "read_only": true
}
Was this section helpful?
Yes No

Update dataset

put/datasets/{dataset_id}

Updates parameters provided in request body for the specified dataset. Parameters that are not specified will keep their current values.

Path Parameters

NameDescription
dataset_id
string*

Unique identifier of dataset.

Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Request body schema

NameDescription
name
string

Responses

StatusDescription
200 successUpdated dataset.
Response Schema
NameDescription
id
string*
Example:

dddddddd-1111-2222-3333-444444444444

name
string*
Example:

MyDataset

created
string*
resource_count
integer*
Example:

12

total_duration
number*
Example:

12345

status
string*
Possible Values: UNLABELED, IN_PROGRESS OR LABELED
read_only
boolean*
cURL
Send
curl --request PUT \
  --url https://missioncontrol.deepgram.com/v1//datasets/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json' \
  --data '{"name":"string"}'
Response
{
  • "id": "dddddddd-1111-2222-3333-444444444444",
  • "name": "MyDataset",
  • "created": "2019-08-24T14:15:22Z",
  • "resource_count": 12,
  • "total_duration": 12345,
  • "status": "UNLABELED",
  • "read_only": true
}
Was this section helpful?
Yes No

Delete dataset

delete/datasets/{dataset_id}

Path Parameters

NameDescription
dataset_id
string*

Unique identifier of dataset.

Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Responses

StatusDescription
204 successDataset was deleted.
Show common responses
cURL
Send
curl --request DELETE \
  --url https://missioncontrol.deepgram.com/v1//datasets/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Was this section helpful?
Yes No

Get all resources in dataset

get/datasets/{dataset_id}/resources

Path Parameters

NameDescription
dataset_id
string*

Unique identifier of dataset.

Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Responses

StatusDescription
200 successList of resources for specified dataset.
Response Schema
NameDescription
result
array*
cURL
Send
curl --request GET \
  --url https://missioncontrol.deepgram.com/v1//datasets/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/resources \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "result": [
    ]
}
Was this section helpful?
Yes No

Get resource

get/datasets/{dataset_id}/resources/{resource_id}

This is equivalent to GET /resources/{resource_id}, except that it will return a 404 if the resource is not in the specified dataset.

Path Parameters

NameDescription
dataset_id
string*

Unique identifier of dataset.

Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

resource_id
string*

Unique identifier of resource.

Example:

ffffffff-0000-0000-0000-ffffffffffff

Responses

StatusDescription
200 successInformation about specified resource retrieved.
Show common responses
Response Schema
NameDescription
id
string*
Example:

ffffffff-0000-0000-0000-ffffffffffff

name
string*
Example:

recording.wav

duration
number*
Example:

96.5

created
string*
status
any*
Possible Values: UNLABELED, IN_PROGRESS OR LABELED
datasets
array*

The IDs of the datasets to which this resource belongs.

Example:

["dddddddd-1111-2222-3333-444444444444"]

read_only
boolean*
cURL
Send
curl --request GET \
  --url https://missioncontrol.deepgram.com/v1//datasets/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/resources/%7Bresource_id%7D \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "id": "ffffffff-0000-0000-0000-ffffffffffff",
  • "name": "recording.wav",
  • "duration": 96.5,
  • "created": "2019-08-24T14:15:22Z",
  • "status": "UNLABELED",
  • "datasets": [
    ],
  • "read_only": true
}
Was this section helpful?
Yes No

Add existing resource to dataset

put/datasets/{dataset_id}/resources/{resource_id}

Adds an existing resource to the specified dataset.

Path Parameters

NameDescription
dataset_id
string*

Unique identifier of dataset.

Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

resource_id
string*

Unique identifier of resource.

Example:

ffffffff-0000-0000-0000-ffffffffffff

Responses

StatusDescription
201 successResource added to the specified dataset.
Show common responses
cURL
Send
curl --request PUT \
  --url https://missioncontrol.deepgram.com/v1//datasets/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/resources/%7Bresource_id%7D \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "reason": "string"
}
Was this section helpful?
Yes No

Remove resource from dataset

delete/datasets/{dataset_id}/resources/{resource_id}

Path Parameters

NameDescription
dataset_id
string*

Unique identifier of dataset.

Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

resource_id
string*

Unique identifier of resource.

Example:

ffffffff-0000-0000-0000-ffffffffffff

Responses

StatusDescription
204 successResource removed from specified dataset.
Show common responses
cURL
Send
curl --request DELETE \
  --url https://missioncontrol.deepgram.com/v1//datasets/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/resources/%7Bresource_id%7D \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "reason": "string"
}
Was this section helpful?
Yes No

Resources

A resource is an audio file and associated data, such as a transcription.

Get all resources

get/resources

Query Parameters

NameDescription
dataset-id
string

Unique identifier of dataset to which retrieved resources should belong.

Example:

dddddddd-1111-2222-3333-444444444444

Responses

StatusDescription
200 successList of resources.
Response Schema
NameDescription
result
array*
cURL
Send
curl --request GET \
  --url https://missioncontrol.deepgram.com/v1//resources \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "result": [
    ]
}
Was this section helpful?
Yes No

Create resource

post/resources

Query Parameters

NameDescription
name
string*

Name of the resource to create.

dataset-id
string

Unique identifier of dataset to which resource should be added. If not specified, resource will be added to the default My Uploads dataset, which will be created if it does not already exist.

Example:

dddddddd-1111-2222-3333-444444444444

Request body schema

The body of the request should be either:

  • Raw binary audio data.
  • A JSON object with a url field from which the audio can be retrieved.
  • Empty; in this case, the audio should be added later using the PUT /resources/{resource_id}/audio endpoint.

Responses

StatusDescription
201 successResource was created.
Response Schema
NameDescription
id
string*
Example:

ffffffff-0000-0000-0000-ffffffffffff

name
string*
Example:

recording.wav

duration
number*
Example:

96.5

created
string*
status
any*
Possible Values: UNLABELED, IN_PROGRESS OR LABELED
datasets
array*

The IDs of the datasets to which this resource belongs.

Example:

["dddddddd-1111-2222-3333-444444444444"]

read_only
boolean*
cURL
Send
curl --request POST \
  --url 'https://missioncontrol.deepgram.com/v1//resources?name=SOME_STRING_VALUE' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json' \
  --data '{"url":"http://username:password@example.com/audio"}'
Response
{
  • "id": "ffffffff-0000-0000-0000-ffffffffffff",
  • "name": "recording.wav",
  • "duration": 96.5,
  • "created": "2019-08-24T14:15:22Z",
  • "status": "UNLABELED",
  • "datasets": [
    ],
  • "read_only": true
}
Was this section helpful?
Yes No

Get resource

get/resources/{resource_id}

Path Parameters

NameDescription
resource_id
string*

Unique identifier of resource.

Example:

ffffffff-0000-0000-0000-ffffffffffff

Responses

StatusDescription
200 successResource returned.
Show common responses
Response Schema
NameDescription
id
string*
Example:

ffffffff-0000-0000-0000-ffffffffffff

name
string*
Example:

recording.wav

duration
number*
Example:

96.5

created
string*
status
any*
Possible Values: UNLABELED, IN_PROGRESS OR LABELED
datasets
array*

The IDs of the datasets to which this resource belongs.

Example:

["dddddddd-1111-2222-3333-444444444444"]

read_only
boolean*
cURL
Send
curl --request GET \
  --url https://missioncontrol.deepgram.com/v1//resources/%7Bresource_id%7D \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "id": "ffffffff-0000-0000-0000-ffffffffffff",
  • "name": "recording.wav",
  • "duration": 96.5,
  • "created": "2019-08-24T14:15:22Z",
  • "status": "UNLABELED",
  • "datasets": [
    ],
  • "read_only": true
}
Was this section helpful?
Yes No

Delete resource

delete/resources/{resource_id}

Removes specified resource from all datasets in which it resides.

Path Parameters

NameDescription
resource_id
string*

Unique identifier of resource.

Example:

ffffffff-0000-0000-0000-ffffffffffff

Responses

StatusDescription
204 successResource was deleted.
Show common responses
cURL
Send
curl --request DELETE \
  --url https://missioncontrol.deepgram.com/v1//resources/%7Bresource_id%7D \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "reason": "string"
}
Was this section helpful?
Yes No

Get audio for resource

get/resources/{resource_id}/audio

Path Parameters

NameDescription
resource_id
string*

Unique identifier of resource.

Example:

ffffffff-0000-0000-0000-ffffffffffff

Responses

StatusDescription
200 successAudio file returned.
Show common responses
Response Schema
cURL
Send
curl --request GET \
  --url https://missioncontrol.deepgram.com/v1//resources/%7Bresource_id%7D/audio \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "reason": "string"
}
Was this section helpful?
Yes No

Upload audio for resource

put/resources/{resource_id}/audio

Allows you to provide audio for a resource that has previously been created without audio. If the specified resource already has associated audio, then this endpoint returns an error.

Path Parameters

NameDescription
resource_id
string*

Unique identifier of resource.

Example:

ffffffff-0000-0000-0000-ffffffffffff

Request body schema

Accepts either raw binary audio data or a JSON object with a url field from which the audio can be retrieved.

Responses

StatusDescription
200 successAudio successfully uploaded.
Show common responses
Response Schema
NameDescription
id
string*
Example:

ffffffff-0000-0000-0000-ffffffffffff

name
string*
Example:

recording.wav

duration
number*
Example:

96.5

created
string*
status
any*
Possible Values: UNLABELED, IN_PROGRESS OR LABELED
datasets
array*

The IDs of the datasets to which this resource belongs.

Example:

["dddddddd-1111-2222-3333-444444444444"]

read_only
boolean*
cURL
Send
curl --request PUT \
  --url https://missioncontrol.deepgram.com/v1//resources/%7Bresource_id%7D/audio \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json' \
  --data '{"url":"http://username:password@example.com/audio"}'
Response
{
  • "id": "ffffffff-0000-0000-0000-ffffffffffff",
  • "name": "recording.wav",
  • "duration": 96.5,
  • "created": "2019-08-24T14:15:22Z",
  • "status": "UNLABELED",
  • "datasets": [
    ],
  • "read_only": true
}
Was this section helpful?
Yes No

Retrieve transcript for resource

get/resources/{resource_id}/transcript

Path Parameters

NameDescription
resource_id
string*

Unique identifier of resource.

Example:

ffffffff-0000-0000-0000-ffffffffffff

Responses

StatusDescription
200 successCompleted transcript.
Show common responses
Response Schema
cURL
Send
curl --request GET \
  --url https://missioncontrol.deepgram.com/v1//resources/%7Bresource_id%7D/transcript \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
Once upon a midnight dreary, while I pondered, weak and weary...
Was this section helpful?
Yes No

Set transcript for resource

put/resources/{resource_id}/transcript

Path Parameters

NameDescription
resource_id
string*

Unique identifier of resource.

Example:

ffffffff-0000-0000-0000-ffffffffffff

Request body schema

Schema not provided

Responses

StatusDescription
200 successTranscript was successfully updated.
Show common responses
Response Schema
NameDescription
id
string*
Example:

ffffffff-0000-0000-0000-ffffffffffff

name
string*
Example:

recording.wav

duration
number*
Example:

96.5

created
string*
status
any*
Possible Values: UNLABELED, IN_PROGRESS OR LABELED
datasets
array*

The IDs of the datasets to which this resource belongs.

Example:

["dddddddd-1111-2222-3333-444444444444"]

read_only
boolean*
cURL
Send
curl --request PUT \
  --url https://missioncontrol.deepgram.com/v1//resources/%7Bresource_id%7D/transcript \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/text'
Response
{
  • "id": "ffffffff-0000-0000-0000-ffffffffffff",
  • "name": "recording.wav",
  • "duration": 96.5,
  • "created": "2019-08-24T14:15:22Z",
  • "status": "UNLABELED",
  • "datasets": [
    ],
  • "read_only": true
}
Was this section helpful?
Yes No

Labeling

This is the API for requesting professional data labeling for your data.

Request labels for resources.

post/label

Requests professional labels from Deepgram's transcriptionists. To request labels for a single resource, use the query parameter; to request labels for multiple resources, send a JSON body.

Query Parameters

NameDescription
resource-id
string

Unique identifier of the resource to label. To request labels for multiple resources, use the request body instead.

Example:

ffffffff-0000-0000-0000-ffffffffffff

Request body schema

Optional request body that allows you to request labels for multiple resources.

NameDescription
resource_ids
array*
Example:

["ffffffff-0000-0000-0000-ffffffffffff"]

Responses

StatusDescription
200 successLabels have been requested.
Show common responses
Response Schema
NameDescription
id
string*
Example:

ffffffff-0000-0000-0000-ffffffffffff

name
string*
Example:

recording.wav

duration
number*
Example:

96.5

created
string*
status
any*
Possible Values: UNLABELED, IN_PROGRESS OR LABELED
datasets
array*

The IDs of the datasets to which this resource belongs.

Example:

["dddddddd-1111-2222-3333-444444444444"]

read_only
boolean*
cURL
Send
curl --request POST \
  --url https://missioncontrol.deepgram.com/v1//label \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json' \
  --data '{"resource_ids":["ffffffff-0000-0000-0000-ffffffffffff"]}'
Response
{
  • "id": "ffffffff-0000-0000-0000-ffffffffffff",
  • "name": "recording.wav",
  • "duration": 96.5,
  • "created": "2019-08-24T14:15:22Z",
  • "status": "UNLABELED",
  • "datasets": [
    ],
  • "read_only": true
}
Was this section helpful?
Yes No

Models

This is the API for managing Trained models, including the files and datasets associated with them.

An example workflow looks like this:

# Set some variables
$ AUTH=user@example.com:password
$ URL=https://missioncontrol.deepgram.com/v1

# Create a model and capture its id in the MODEL_ID variable.
$ MODEL_ID=$(
  curl -u $AUTH -XPOST $URL/models \
    -H 'content-type: application/json' \
    --data `{"name": "test-model"}` |
  jq -r '.id'
)

# Add a dataset to the model. We'll pick an arbitrary dataset that we own.
$ DATASET_ID=$(
  curl -u $AUTH $URL/datasets |
  jq -r '.result[0].uuid'
)
$ curl -u $AUTH -XPUT $URL/models/$MODEL_ID/datasets/$DATASET_ID

# Submit the model for training.
$ curl -u $AUTH -XPOST $URL/train?model-id=$MODEL_ID

# After some time, the trained model will be ready.
# We can retrieve some stats:
$ curl -u $AUTH $URL/models/$MODEL_ID/stats | jq

# ... and we can then deploy it:
$ curl -u $AUTH -XPOST $URL/models/$MODEL_ID/deploy

Get all custom models

get/models

Responses

StatusDescription
200 successList of all custom models.
Response Schema
NameDescription
result
array*
Example:

[{"name":"MyCustomModel","id":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee","last_trained":"2020-02-21T17:32:28.000Z","status":"pending","wer":10,"model_type":"deepgram","version":"1.2"},{"name":"AwesomeModel","id":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeea","status":"trained","last_trained":"2020-03-21T17:32:28.000Z","wer":15,"model_type":"user","version":"0.3"}]

cURL
Send
curl --request GET \
  --url https://missioncontrol.deepgram.com/v1//models \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "result": [
    ]
}
Was this section helpful?
Yes No

Create custom model

post/models

Request body schema

Model creation parameters.

NameDescription
name
string*
Example:

MyModel

datasets
array

An optional list of dataset IDs to associate to the model.

Example:

["dddddddd-1111-2222-3333-444444444444"]

train
object

If present, immediately add the model to the training queue.

Responses

StatusDescription
200 successCustom model was successfully created.
Response Schema
NameDescription
id
string*
Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

version_id
string*
Example:

12345678-1234-1234-1234-1234567890ab

name
string*
created
string*
status
string
Possible Values: DRAFT, PENDING, TRAINING, TRAINED, DEPLOY_REQUESTED, DEPLOYED, CANCELELD OR FAILED
Example:

TRAINED

last_trained
string
wer
number
model_type
string*
Possible Values: DEEPGRAM_BASE, DEEPGRAM_TRAINED OR USER
cURL
Send
curl --request POST \
  --url https://missioncontrol.deepgram.com/v1//models \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json' \
  --data '{"name":"MyModel","datasets":["dddddddd-1111-2222-3333-444444444444"],"train":{"base_model_id":"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee","model_type":"AUTO_TRAINED"}}'
Response
{
  • "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  • "version_id": "12345678-1234-1234-1234-1234567890ab",
  • "name": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "status": "TRAINED",
  • "last_trained": "2019-08-24T14:15:22Z",
  • "wer": 0,
  • "model_type": "DEEPGRAM_BASE"
}
Was this section helpful?
Yes No

Get information about a custom model.

get/models/{model_id}

Path Parameters

NameDescription
model_id
string*

Unique identifier of custom model.

Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Query Parameters

NameDescription
model-version
string

A specific version of a custom model. If omitted, the most recent version will be used.

Example:

12345678-1234-1234-1234-1234567890ab

Responses

StatusDescription
200 successInformation about a custom model.
Response Schema
NameDescription
id
string*
Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

version_id
string*
Example:

12345678-1234-1234-1234-1234567890ab

name
string*
created
string*
status
string
Possible Values: DRAFT, PENDING, TRAINING, TRAINED, DEPLOY_REQUESTED, DEPLOYED, CANCELELD OR FAILED
Example:

TRAINED

last_trained
string
wer
number
model_type
string*
Possible Values: DEEPGRAM_BASE, DEEPGRAM_TRAINED OR USER
cURL
Send
curl --request GET \
  --url https://missioncontrol.deepgram.com/v1//models/%7Bmodel_id%7D \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  • "version_id": "12345678-1234-1234-1234-1234567890ab",
  • "name": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "status": "TRAINED",
  • "last_trained": "2019-08-24T14:15:22Z",
  • "wer": 0,
  • "model_type": "DEEPGRAM_BASE"
}
Was this section helpful?
Yes No

Modify a custom model.

patch/models/{model_id}

Path Parameters

NameDescription
model_id
string*

Unique identifier of custom model.

Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Request body schema

NameDescription
name
string

Change the name of the model.

Responses

StatusDescription
200 successThe model was successfully updated.
Response Schema
NameDescription
id
string*
Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

version_id
string*
Example:

12345678-1234-1234-1234-1234567890ab

name
string*
created
string*
status
string
Possible Values: DRAFT, PENDING, TRAINING, TRAINED, DEPLOY_REQUESTED, DEPLOYED, CANCELELD OR FAILED
Example:

TRAINED

last_trained
string
wer
number
model_type
string*
Possible Values: DEEPGRAM_BASE, DEEPGRAM_TRAINED OR USER
cURL
Send
curl --request PATCH \
  --url https://missioncontrol.deepgram.com/v1//models/%7Bmodel_id%7D \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json' \
  --data '{"name":"string"}'
Response
{
  • "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  • "version_id": "12345678-1234-1234-1234-1234567890ab",
  • "name": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "status": "TRAINED",
  • "last_trained": "2019-08-24T14:15:22Z",
  • "wer": 0,
  • "model_type": "DEEPGRAM_BASE"
}
Was this section helpful?
Yes No

Delete a custom model.

delete/models/{model_id}

Path Parameters

NameDescription
model_id
string*

Unique identifier of custom model.

Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Responses

StatusDescription
200 successA custom model was successfully deleted.
Response Schema
NameDescription
result
string
Possible Values: OR deleted
cURL
Send
curl --request DELETE \
  --url https://missioncontrol.deepgram.com/v1//models/%7Bmodel_id%7D \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "result": "deleted"
}
Was this section helpful?
Yes No

Get all datasets associated with model

get/models/{model_id}/datasets

Path Parameters

NameDescription
model_id
string*

Unique identifier of custom model.

Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Query Parameters

NameDescription
model-version
string

A specific version of a custom model. If omitted, the most recent version will be used.

Example:

12345678-1234-1234-1234-1234567890ab

Responses

StatusDescription
200 successList of datasets associated with specified model.
Response Schema
NameDescription
model_id
string
Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

datasets
array
cURL
Send
curl --request GET \
  --url https://missioncontrol.deepgram.com/v1//models/%7Bmodel_id%7D/datasets \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "model_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  • "datasets": [
    ]
}
Was this section helpful?
Yes No

Set all datasets associated with model

put/models/{model_id}/datasets

Path Parameters

NameDescription
model_id
string*

Unique identifier of custom model.

Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Request body schema

Array of

Responses

StatusDescription
200 successList of datasets associated with specified model.
Response Schema
NameDescription
model_id
string
Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

datasets
array
cURL
Send
curl --request PUT \
  --url https://missioncontrol.deepgram.com/v1//models/%7Bmodel_id%7D/datasets \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json' \
  --data '["string"]'
Response
{
  • "model_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  • "datasets": [
    ]
}
Was this section helpful?
Yes No

Add dataset to custom model

put/models/{model_id}/datasets/{dataset_id}

Path Parameters

NameDescription
model_id
string*

Unique identifier of custom model.

Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

dataset_id
string*

Unique identifier of dataset.

Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Responses

StatusDescription
200 successList of datasets currently associated with specified model.
Response Schema
NameDescription
model_id
string
Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

datasets
array
cURL
Send
curl --request PUT \
  --url https://missioncontrol.deepgram.com/v1//models/%7Bmodel_id%7D/datasets/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "model_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  • "datasets": [
    ]
}
Was this section helpful?
Yes No

Remove dataset from custom model

delete/models/{model_id}/datasets/{dataset_id}

Path Parameters

NameDescription
model_id
string*

Unique identifier of custom model.

Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

dataset_id
string*

Unique identifier of dataset.

Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Responses

StatusDescription
200 successList of datasets associated with specified model.
Response Schema
NameDescription
model_id
string
Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

datasets
array
cURL
Send
curl --request DELETE \
  --url https://missioncontrol.deepgram.com/v1//models/%7Bmodel_id%7D/datasets/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "model_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  • "datasets": [
    ]
}
Was this section helpful?
Yes No

Get resources used to train model

get/models/{model_id}/resources

Path Parameters

NameDescription
model_id
string*

Unique identifier of custom model.

Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Responses

StatusDescription
200 successResources used to train this model returned.
Response Schema
NameDescription
result
array*
cURL
Send
curl --request GET \
  --url https://missioncontrol.deepgram.com/v1//models/%7Bmodel_id%7D/resources \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "result": [
    ]
}
Was this section helpful?
Yes No

Get all versions of model

get/models/{model_id}/versions

Path Parameters

NameDescription
model_id
string*

Unique identifier of custom model.

Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Responses

StatusDescription
200 successList of model IDs.
Response Schema
NameDescription
model_id
string*
Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

versions
array*
cURL
Send
curl --request GET \
  --url https://missioncontrol.deepgram.com/v1//models/%7Bmodel_id%7D/versions \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "model_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  • "versions": [
    ]
}
Was this section helpful?
Yes No

Get statistics for model

get/models/{model_id}/stats

Supplies a word error rate (WER) defined with respect to a model and a set of test resources.

Path Parameters

NameDescription
model_id
string*

Unique identifier of custom model.

Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Responses

StatusDescription
200 successModel statistics found.
Response Schema
NameDescription
model
object
wers
array
cURL
Send
curl --request GET \
  --url https://missioncontrol.deepgram.com/v1//models/%7Bmodel_id%7D/stats \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "model": {
    },
  • "wers": [
    ]
}
Was this section helpful?
Yes No

Training

This is the API for training models. Once the user has uploaded datasets and transcripts, and is ready to train a model, they will add a job to the training queue like this:

$ curl -XPOST $URL/train?model-id=$MODEL_ID

At this point, the training job will be added to the queue. The state of the model will be frozen; its version_id will always refer to its current state. Any future changes to the model will generate a new version_id.

Occasionally, a model can fail to train. Common reasons why that may be are documented below:

Common reasons why training can fail:

  • The supplied resources don't contain enough speech to train on. Even if the audio files may be long, they need to contain speech, not just silence or noise.
  • Incomplete or incorrect labels. If we can't match up the labels to the audio, then we can't extract useful training data. Follow the instructions in MissionControl's trancript editor to learn how to optimally label your audio data.
  • Not enough resources supplied. To achieve the best results possible, train on multiple resources totaling greater than 10 minutes of audio. This prevents overtraining.

Submit request to train selected model

post/train

Adds a job to the training queue for the specified model. If a job for the model already exists in the queue, or if the model has been previously trained, the job will not be added to the queue.

Query Parameters

NameDescription
model-id
string*

Unique identifier of the model to be trained.

Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

base-model-id
string

Unique identifier of the model to use as the starting point for training the specified model. If not specified, an intelligent default will be chosen.

Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

model-type
string

Type of training to perform.

Default: AUTO_TRAINED
Possible Values: AUTO_TRAINED, AUTO_ML OR EXPERT_TRAINED

Responses

StatusDescription
200 successModel has already been submitted for training.
Show common responses
Response Schema
NameDescription
id
string*
Example:

12345678-1234-1234-1234-1234567890ab

submitted
string*
finished
string*
status
string*
Possible Values: pending, training OR finished
parameters
object*

This object is not considered part of the public API. It is an internal detail used for training, and may change without notice.

cURL
Send
curl --request POST \
  --url 'https://missioncontrol.deepgram.com/v1//train?model-id=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "id": "12345678-1234-1234-1234-1234567890ab",
  • "submitted": "2019-08-24T14:15:22Z",
  • "finished": "2019-08-24T14:15:22Z",
  • "status": "pending",
  • "parameters": {
    }
}
Was this section helpful?
Yes No

List models in training queue

get/train

Responses

StatusDescription
200 successList of models in the training queue.
Response Schema
NameDescription
result
array*
cURL
Send
curl --request GET \
  --url https://missioncontrol.deepgram.com/v1//train \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Response
{
  • "result": [
    ]
}
Was this section helpful?
Yes No

Cancel training job

delete/train

Removes a job from the training queue.

Query Parameters

NameDescription
model-version
string*

ID of the model version for which training should be cancelled.

Example:

12345678-1234-1234-1234-1234567890ab

Responses

StatusDescription
200 successJob was cancelled successfully.
cURL
Send
curl --request DELETE \
  --url 'https://missioncontrol.deepgram.com/v1//train?model-version=12345678-1234-1234-1234-1234567890ab' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Was this section helpful?
Yes No

Deploy

Deploy model

post/deploy

Deploys a model, so it can be used to create automatic transcripts. To learn how to transcribe audio using your deployed model, see the Speech Recognition API Reference.

Query Parameters

NameDescription
model-id
string*
Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Responses

StatusDescription
200 successModel scheduled for deployment.
cURL
Send
curl --request POST \
  --url 'https://missioncontrol.deepgram.com/v1//deploy?model-id=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Was this section helpful?
Yes No

Undeploy model

post/undeploy

Query Parameters

NameDescription
model-id
string*
Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Responses

StatusDescription
200 successThe model has been undeployed.
cURL
Send
curl --request POST \
  --url 'https://missioncontrol.deepgram.com/v1//undeploy?model-id=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee' \
  --header 'Authorization: Basic REPLACE_BASIC_AUTH' \
  --header 'content-type: application/json'
Was this section helpful?
Yes No

Transcribing

For documentation on getting automatic transcription, also known as the /listen endpoint, visit the Speech Recognition API Reference.