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.

Quickstart

Check out our user guides:

Quickstart Guide for the Deepgram MissionControl API

Train a Model to understand your speech data

Account

APIs related to account management and overall usage.

Create account

post/signup

Request body schema

Name	Description
first_name string*	first_name N/A
last_name string*	last_name N/A
email string*	email N/A
password string*	password N/A

Responses

Status	Description
201 success	201Account was created.
Show common responses

Shell + 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

Name	Description
XSRF-TOKEN string	XSRF-TOKEN N/A

Header Parameters

Name	Description
X-XSRF-TOKEN string	X-XSRF-TOKEN N/A

Responses

Status	Description
200 success	200User successfully logged in.

Shell + 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": {"id": "b43f882c-0215-4b5d-826f-ee4ceb1a9c49",
"email": "user@example.com",
"first_name": "FirstName",
"last_name": "LastName"
}
}

Was this section helpful? Yes No

Get summary of account usage

get/usage

Responses

Status	Description
200 success	200Model usage information found.

Shell + 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": {"total": {"name": "MyModel",
"id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"batch_count": 123,
"batch_duration": 4523,
"stream_count": 15,
"stream_duration": 3178
},
"model_usage": [{"name": "MyModel",
"id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"batch_count": 123,
"batch_duration": 4523,
"stream_count": 15,
"stream_duration": 3178
}
]
},
"history": [{"year": 2020,
"month": 1,
"total": {"name": "MyModel",
"id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"batch_count": 123,
"batch_duration": 4523,
"stream_count": 15,
"stream_duration": 3178
},
"model_usage": [{"name": "MyModel",
"id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"batch_count": 123,
"batch_duration": 4523,
"stream_count": 15,
"stream_duration": 3178
}
]
}
],
"training": {"models_trained": 0,
"models_trained_limit": 0,
"models_deployed": 0,
"models_deployed_limit": 0
},
"labels": {"duration_labeled": 0,
"duration_labeled_limit": 0
},
"asr": {"duration": 0,
"duration_limit": 0
}
}

Was this section helpful? Yes No

Get all of your API keys

get/keys

Responses

Status	Description
200 success	200List of API keys.

Shell + 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": [{"key": "string",
"name": "string"
}
]
}

Was this section helpful? Yes No

Create API keys

post/keys

Query Parameters

Name	Description
name string	name N/A

Responses

Status	Description
201 success	201API key created.

Shell + 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

Name	Description
key string	key N/A

Responses

Status	Description
204 success	204API key deleted.

Shell + 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

Name	Description	Examples
user-id string	user-id Unique identifier of user for whom to retrieve limits. If not specified, defaults to the user making the request.	aaaaaaaa-1111-2222-3333-444444444444

Responses

Status	Description
200 success	200The user's account limits.

Shell + 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

Name	Description	Examples
user-id string	user-id Unique identifier of user for whom to set limits. If not specified, defaults to the user making the request.	aaaaaaaa-1111-2222-3333-444444444444

Request body schema

Object containing properties to set for the specified user.

Name	Description
min_training_seconds number	min_training_seconds Minimum number of seconds of audio required to train a model.

Responses

Status	Description
200 success	200The user's account limits.

Shell + 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

Status	Description
200 success	200List of datasets.

Shell + 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": [{"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

Create dataset

post/datasets

Query Parameters

Name	Description	Examples
name string*	name N/A	MyDataset

Responses

Status	Description
201 success	201Dataset created.
Show common responses

Shell + 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

Name	Description	Examples
dataset_id string*	dataset_id Unique identifier of dataset.	aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Responses

Status	Description
200 success	200Specified dataset retrieved.

Shell + 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

Name	Description	Examples
dataset_id string*	dataset_id Unique identifier of dataset.	aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Request body schema

Name	Description
name string	name N/A

Responses

Status	Description
200 success	200Updated dataset.

Shell + 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

Name	Description	Examples
dataset_id string*	dataset_id Unique identifier of dataset.	aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Responses

Status	Description
204 success	204Dataset was deleted.
Show common responses

Shell + 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

Name	Description	Examples
dataset_id string*	dataset_id Unique identifier of dataset.	aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Responses

Status	Description
200 success	200List of resources for specified dataset.

Shell + 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": [{"id": "ffffffff-0000-0000-0000-ffffffffffff",
"name": "recording.wav",
"duration": 96.5,
"created": "2019-08-24T14:15:22Z",
"status": "UNLABELED",
"datasets": ["dddddddd-1111-2222-3333-444444444444"
],
"read_only": true
}
]
}

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

Name	Description	Examples
dataset_id string*	dataset_id Unique identifier of dataset.	aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
resource_id string*	resource_id Unique identifier of resource.	ffffffff-0000-0000-0000-ffffffffffff

Responses

Status	Description
200 success	200Information about specified resource retrieved.
Show common responses

Shell + 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": ["dddddddd-1111-2222-3333-444444444444"
],
"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.

To add a resource to a dataset while uploading it, use the optional `dataset-id` query parameter.

Path Parameters

Name	Description	Examples
dataset_id string*	dataset_id Unique identifier of dataset.	aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
resource_id string*	resource_id Unique identifier of resource.	ffffffff-0000-0000-0000-ffffffffffff

Responses

Status	Description
201 success	201Resource added to the specified dataset.
Show common responses

Shell + 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

Name	Description	Examples
dataset_id string*	dataset_id Unique identifier of dataset.	aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
resource_id string*	resource_id Unique identifier of resource.	ffffffff-0000-0000-0000-ffffffffffff

Responses

Status	Description
204 success	204Resource removed from specified dataset.
Show common responses

Shell + 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

Name	Description	Examples
dataset-id string	dataset-id Unique identifier of dataset to which retrieved resources should belong.	dddddddd-1111-2222-3333-444444444444

Responses

Status	Description
200 success	200List of resources.

Shell + 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": [{"id": "ffffffff-0000-0000-0000-ffffffffffff",
"name": "recording.wav",
"duration": 96.5,
"created": "2019-08-24T14:15:22Z",
"status": "UNLABELED",
"datasets": ["dddddddd-1111-2222-3333-444444444444"
],
"read_only": true
}
]
}

Was this section helpful? Yes No

Create resource

post/resources

Query Parameters

Name	Description	Examples
name string*	name Name of the resource to create.	N/A
dataset-id string	dataset-id 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.	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

Status	Description
201 success	201Resource was created.

Shell + 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": ["dddddddd-1111-2222-3333-444444444444"
],
"read_only": true
}

Was this section helpful? Yes No

Get resource

get/resources/{resource_id}

Path Parameters

Name	Description	Examples
resource_id string*	resource_id Unique identifier of resource.	ffffffff-0000-0000-0000-ffffffffffff

Responses

Status	Description
200 success	200Resource returned.
Show common responses

Shell + 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": ["dddddddd-1111-2222-3333-444444444444"
],
"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

Name	Description	Examples
resource_id string*	resource_id Unique identifier of resource.	ffffffff-0000-0000-0000-ffffffffffff

Responses

Status	Description
204 success	204Resource was deleted.
Show common responses

Shell + 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

Name	Description	Examples
resource_id string*	resource_id Unique identifier of resource.	ffffffff-0000-0000-0000-ffffffffffff

Responses

Status	Description
200 success	200Audio file returned.
Show common responses

Shell + 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

Name	Description	Examples
resource_id string*	resource_id Unique identifier of resource.	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

Status	Description
200 success	200Audio successfully uploaded.
Show common responses

Shell + 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": ["dddddddd-1111-2222-3333-444444444444"
],
"read_only": true
}

Was this section helpful? Yes No

Retrieve transcript for resource

get/resources/{resource_id}/transcript

Path Parameters

Name	Description	Examples
resource_id string*	resource_id Unique identifier of resource.	ffffffff-0000-0000-0000-ffffffffffff

Responses

Status	Description
200 success	200Completed transcript.
Show common responses

Shell + 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

Name	Description	Examples
resource_id string*	resource_id Unique identifier of resource.	ffffffff-0000-0000-0000-ffffffffffff

Request body schema

Schema not provided

Responses

Status	Description
200 success	200Transcript was successfully updated.
Show common responses

Shell + 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": ["dddddddd-1111-2222-3333-444444444444"
],
"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

Name	Description	Examples
resource-id string	resource-id Unique identifier of the resource to label. To request labels for multiple resources, use the request body instead. This query parameter is maintained for backwards compatibility; it may be deprecated in the future.	ffffffff-0000-0000-0000-ffffffffffff

Request body schema

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

Name	Description	Examples
resource_ids array*	resource_ids N/A	Select Example

Responses

Status	Description
200 success	200Labels have been requested.
Show common responses

Shell + 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": ["dddddddd-1111-2222-3333-444444444444"
],
"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

Status	Description
200 success	200List of all custom models.

Shell + 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": [{"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"
}
]
}

Was this section helpful? Yes No

Create custom model

post/models

Request body schema

Model creation parameters.

Name	Description	Examples
name string*	name N/A	MyModel
datasets array	datasets An optional list of dataset IDs to associate to the model.	Select Example
train object	train If present, immediately add the model to the training queue.	N/A

Responses

Status	Description
200 success	200Custom model was successfully created.

Shell + 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

Name	Description	Examples
model_id string*	model_id Unique identifier of custom model.	aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Query Parameters

Name	Description	Examples
model-version string	model-version A specific version of a custom model. If omitted, the most recent version will be used.	12345678-1234-1234-1234-1234567890ab

Responses

Status	Description
200 success	200Information about a custom model.

Shell + 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

Name	Description	Examples
model_id string*	model_id Unique identifier of custom model.	aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Request body schema

Name	Description
name string	name Change the name of the model.

Responses

Status	Description
200 success	200The model was successfully updated.

Shell + 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

Name	Description	Examples
model_id string*	model_id Unique identifier of custom model.	aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Responses

Status	Description
200 success	200A custom model was successfully deleted.

Shell + 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

Name	Description	Examples
model_id string*	model_id Unique identifier of custom model.	aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Query Parameters

Name	Description	Examples
model-version string	model-version A specific version of a custom model. If omitted, the most recent version will be used.	12345678-1234-1234-1234-1234567890ab

Responses

Status	Description
200 success	200List of datasets associated with specified model.

Shell + 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": [{"id": "dddddddd-1111-2222-3333-444444444444",
"name": "string"
}
]
}

Was this section helpful? Yes No

Set all datasets associated with model

put/models/{model_id}/datasets

Path Parameters

Name	Description	Examples
model_id string*	model_id Unique identifier of custom model.	aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Request body schema

Array ()

Responses

Status	Description
200 success	200List of datasets associated with specified model.

Shell + 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": [{"id": "dddddddd-1111-2222-3333-444444444444",
"name": "string"
}
]
}

Was this section helpful? Yes No

Add dataset to custom model

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

Path Parameters

Name	Description	Examples
model_id string*	model_id Unique identifier of custom model.	aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
dataset_id string*	dataset_id Unique identifier of dataset.	aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Responses

Status	Description
200 success	200List of datasets currently associated with specified model.

Shell + 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": [{"id": "dddddddd-1111-2222-3333-444444444444",
"name": "string"
}
]
}

Was this section helpful? Yes No

Remove dataset from custom model

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

Path Parameters

Name	Description	Examples
model_id string*	model_id Unique identifier of custom model.	aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
dataset_id string*	dataset_id Unique identifier of dataset.	aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Responses

Status	Description
200 success	200List of datasets associated with specified model.

Shell + 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": [{"id": "dddddddd-1111-2222-3333-444444444444",
"name": "string"
}
]
}

Was this section helpful? Yes No

Get resources used to train model

get/models/{model_id}/resources

Path Parameters

Name	Description	Examples
model_id string*	model_id Unique identifier of custom model.	aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Responses

Status	Description
200 success	200Resources used to train this model returned.

Shell + 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": [{"id": "ffffffff-0000-0000-0000-ffffffffffff",
"name": "recording.wav",
"duration": 96.5,
"created": "2019-08-24T14:15:22Z",
"status": "UNLABELED",
"datasets": ["dddddddd-1111-2222-3333-444444444444"
],
"read_only": true
}
]
}

Was this section helpful? Yes No

Get all versions of model

get/models/{model_id}/versions

Path Parameters

Name	Description	Examples
model_id string*	model_id Unique identifier of custom model.	aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Responses

Status	Description
200 success	200List of model IDs.

Shell + 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": [{"version_id": "12345678-1234-1234-1234-1234567890ab",
"model_name": "string",
"date": "2019-08-24T14:15:22Z",
"wer": 0
}
]
}

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.

To get the `wer` property of a model info object, you must test that model against a validation set that was automatically created when you submitted resources to assign to your model. The validation set was not used for training; instead, it is used to estimate model performance.

To conduct a thorough evaluation of your model's performance, generate a WER by comparing your model's results against an accurate human transcript. See our blog post for best practices on calculating word error rates.

Path Parameters

Name	Description	Examples
model_id string*	model_id Unique identifier of custom model.	aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Responses

Status	Description
200 success	200Model statistics found.

Shell + 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": {"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"
},
"wers": [{"model": {"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"
},
"wer_comparison": 0
}
]
}

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

Name	Description	Examples
model-id string*	model-id Unique identifier of the model to be trained.	aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
base-model-id string	base-model-id 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.	aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
model-type string	model-type Type of training to perform. `AUTO_ML` and `EXPERT_TRAINED` are premium features, which require approval from Deepgram's sales team. If you are just starting to explore Mission Control, you likely want to use the default value of `AUTO_TRAINED`. Default: AUTO_TRAINED Possible Values: AUTO_TRAINED, AUTO_ML OR EXPERT_TRAINED	N/A

Responses

Status	Description
200 success	200Model has already been submitted for training.
Show common responses

Shell + 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": {"base_model_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"resource_ids": ["ffffffff-0000-0000-0000-ffffffffffff"
]
}
}

Was this section helpful? Yes No

List models in training queue

get/train

Responses

Status	Description
200 success	200List of models in the training queue.

Shell + 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": [{"id": "12345678-1234-1234-1234-1234567890ab",
"submitted": "2019-08-24T14:15:22Z",
"finished": "2019-08-24T14:15:22Z",
"status": "pending",
"parameters": {"base_model_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"resource_ids": ["ffffffff-0000-0000-0000-ffffffffffff"
]
}
}
]
}

Was this section helpful? Yes No

Cancel training job

delete/train

Removes a job from the training queue.

Query Parameters

Name	Description	Examples
model-version string*	model-version ID of the model version for which training should be cancelled.	12345678-1234-1234-1234-1234567890ab

Responses

Status	Description
200 success	200Job was cancelled successfully.

Shell + 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

Name	Description	Examples
model-id string*	model-id N/A	aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Responses

Status	Description
200 success	200Model scheduled for deployment.

Shell + 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

Name	Description	Examples
model-id string*	model-id N/A	aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Responses

Status	Description
200 success	200The model has been undeployed.

Shell + 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.