Deepgram MissionControl API (0.0.2)

Download OpenAPI specification:Download

Anthony Deschamps: product@deepgram.com

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.

For documentation on getting automatic transcription, also known as the /listen endpoint, visit docs.deepgram.com.

Account

APIs related to account management and overall usage.

Create a new account.

Request Body schema: application/json
first_name
required
string
last_name
required
string
email
required
string
password
required
string

Responses

201

An account was created.

409

The account already exists.

post/signup

BrainPlatform API powering MissionControl.

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

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "first_name": "FirstName",
  • "last_name": "LastName",
  • "email": "user@example.com",
  • "password": "password"
}

Login.

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

cookie Parameters
XSRF-TOKEN
string <uuid>
header Parameters
X-XSRF-TOKEN
string <uuid>

Responses

200

The user has successfully logged in.

Response Headers
Set-Cookie
string

This may set the BRAIN-TOKEN cookie or the XSRF-TOKEN cookie.

Response Schema: application/json
token
required
string <uuid>
auth
required
boolean
user
required
UserInfo (object) Nullable
post/login

BrainPlatform API powering MissionControl.

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

Response samples

Content type
application/json
Example

The client has successfully authenticated.

Copy
Expand all Collapse all
{
  • "auth": true,
  • "token": "a7cf9b9d-a766-44e3-961f-8964e83d5737",
  • "user":
    {
    }
}

Get account usage summary.

Responses

200

Model usage information.

Response Schema: application/json
total
required
object (UsageSummary)
history
required
Array of objects (MonthlyUsageSummary)
training
required
object
labels
required
object
asr
required
object
get/usage

BrainPlatform API powering MissionControl.

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "total":
    {
    },
  • "history":
    [
    ],
  • "training":
    {
    },
  • "labels":
    {
    },
  • "asr":
    {
    }
}

Get a list of your API keys.

Responses

200

A list of API keys.

Response Schema: application/json
result
required
Array of objects
get/keys

BrainPlatform API powering MissionControl.

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "result":
    [
    ]
}

Create a new API keys.

query Parameters
name
string

Responses

201

A new API key.

Response Schema: application/json
key
required
string
secret
required
string
post/keys

BrainPlatform API powering MissionControl.

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "key": "string",
  • "secret": "string"
}

Delete an API key

query Parameters
key
string

Responses

204

A key was deleted.

delete/keys

BrainPlatform API powering MissionControl.

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

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 the list of datasets.

Responses

200

A list of datasets.

Response Schema: application/json
result
required
Array of objects (DatasetInfo)
get/datasets

BrainPlatform API powering MissionControl.

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "result":
    [
    ]
}

Create a new dataset.

query Parameters
name
required
string (DatasetName)
Example: name=MyDataset

Responses

201

A new dataset was created.

Response Schema: application/json
id
required
string (DatasetId)
name
required
string (DatasetName)
created
required
string <date-time>
resource_count
required
integer
total_duration
required
number
status
required
string
Enum: "UNLABELED" "IN_PROGRESS" "LABELED"
read_only
required
boolean
409

The dataset already exists.

post/datasets

BrainPlatform API powering MissionControl.

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "dddddddd-1111-2222-3333-444444444444",
  • "name": "MyDataset",
  • "created": "2020-10-02T20:42:23Z",
  • "resource_count": 12,
  • "total_duration": 12345,
  • "status": "UNLABELED",
  • "read_only": true
}

Get a dataset

path Parameters
dataset_id
required
string
Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

The UUID of a dataset.

Responses

200

Information about the dataset.

Response Schema: application/json
id
required
string (DatasetId)
name
required
string (DatasetName)
created
required
string <date-time>
resource_count
required
integer
total_duration
required
number
status
required
string
Enum: "UNLABELED" "IN_PROGRESS" "LABELED"
read_only
required
boolean
get/datasets/{dataset_id}

BrainPlatform API powering MissionControl.

https://missioncontrol.deepgram.com/v1/datasets/{dataset_id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "dddddddd-1111-2222-3333-444444444444",
  • "name": "MyDataset",
  • "created": "2020-10-02T20:42:23Z",
  • "resource_count": 12,
  • "total_duration": 12345,
  • "status": "UNLABELED",
  • "read_only": true
}

Update a dataset

Any parameters provided in the request body will be updated. Any parameters that are not specified will keep their current values.

path Parameters
dataset_id
required
string
Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

The UUID of a dataset.

Request Body schema: application/json
name
string

Responses

200

The updated dataset.

Response Schema: application/json
id
required
string (DatasetId)
name
required
string (DatasetName)
created
required
string <date-time>
resource_count
required
integer
total_duration
required
number
status
required
string
Enum: "UNLABELED" "IN_PROGRESS" "LABELED"
read_only
required
boolean
put/datasets/{dataset_id}

BrainPlatform API powering MissionControl.

https://missioncontrol.deepgram.com/v1/datasets/{dataset_id}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "name": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "dddddddd-1111-2222-3333-444444444444",
  • "name": "MyDataset",
  • "created": "2020-10-02T20:42:23Z",
  • "resource_count": 12,
  • "total_duration": 12345,
  • "status": "UNLABELED",
  • "read_only": true
}

Delete a dataset

path Parameters
dataset_id
required
string
Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

The UUID of a dataset.

Responses

204

The dataset was deleted.

404

The dataset could not be found.

delete/datasets/{dataset_id}

BrainPlatform API powering MissionControl.

https://missioncontrol.deepgram.com/v1/datasets/{dataset_id}

Get the list of resources in a dataset.

path Parameters
dataset_id
required
string
Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

The UUID of a dataset.

Responses

200

A list of resources.

Response Schema: application/json
result
required
Array of objects (ResourceInfo)
get/datasets/{dataset_id}/resources

BrainPlatform API powering MissionControl.

https://missioncontrol.deepgram.com/v1/datasets/{dataset_id}/resources

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "result":
    [
    ]
}

Get a particular resource.

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
dataset_id
required
string
Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

The UUID of a dataset.

resource_id
required
string (ResourceId)
Example: ffffffff-0000-0000-0000-ffffffffffff

The UUID of a resource.

Responses

200

Information about the specified resource.

Response Schema: application/json
id
required
string (ResourceId)
name
required
string
duration
required
number
created
required
string <date-time>
status
required
any
Enum: "UNLABELED" "IN_PROGRESS" "LABELED"
datasets
required
Array of strings (DatasetId)

The IDs of the datasets to which this resource belongs.

read_only
required
boolean
400

The request was not properly formed.

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

BrainPlatform API powering MissionControl.

https://missioncontrol.deepgram.com/v1/datasets/{dataset_id}/resources/{resource_id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "ffffffff-0000-0000-0000-ffffffffffff",
  • "name": "recording.wav",
  • "duration": 96.5,
  • "created": "2020-10-02T20:42:23Z",
  • "status": "UNLABELED",
  • "datasets":
    [
    ],
  • "read_only": true
}

Add an existing resource to a dataset.

This call adds an existing resource to a dataset. Note that you can add an resource to a dataset while uploading it, using the optional dataset-id query parameter.

path Parameters
dataset_id
required
string
Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

The UUID of a dataset.

resource_id
required
string (ResourceId)
Example: ffffffff-0000-0000-0000-ffffffffffff

The UUID of a resource.

Responses

201

The resource was added to the dataset.

400

The request was not properly formed.

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

BrainPlatform API powering MissionControl.

https://missioncontrol.deepgram.com/v1/datasets/{dataset_id}/resources/{resource_id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "reason": "string"
}

Remove a resource from a dataset.

path Parameters
dataset_id
required
string
Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

The UUID of a dataset.

resource_id
required
string (ResourceId)
Example: ffffffff-0000-0000-0000-ffffffffffff

The UUID of a resource.

Responses

204

The resource was removed from the dataset.

400

The request was not properly formed.

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

BrainPlatform API powering MissionControl.

https://missioncontrol.deepgram.com/v1/datasets/{dataset_id}/resources/{resource_id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "reason": "string"
}

Resources

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

Get a list of all resources.

query Parameters
dataset-id
string (DatasetId)
Example: dataset-id=dddddddd-1111-2222-3333-444444444444

Limit the results to resources that belong to the specified dataset.

Responses

200

A list of all resources.

Response Schema: application/json
result
required
Array of objects (ResourceInfo)
get/resources

BrainPlatform API powering MissionControl.

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "result":
    [
    ]
}

Create a new resource.

query Parameters
name
required
string

The name of the new resource.

dataset-id
string (DatasetId)
Example: dataset-id=dddddddd-1111-2222-3333-444444444444

Add the new resource to a dataset. If this is not specified, then the resource will be added to the default My Uploads dataset, which will be created if it does not already exist.

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.
string <binary>

Responses

201

A new resource was created.

Response Schema: application/json
id
required
string (ResourceId)
name
required
string
duration
required
number
created
required
string <date-time>
status
required
any
Enum: "UNLABELED" "IN_PROGRESS" "LABELED"
datasets
required
Array of strings (DatasetId)

The IDs of the datasets to which this resource belongs.

read_only
required
boolean
post/resources

BrainPlatform API powering MissionControl.

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

Request samples

Content type
No sample

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "ffffffff-0000-0000-0000-ffffffffffff",
  • "name": "recording.wav",
  • "duration": 96.5,
  • "created": "2020-10-02T20:42:23Z",
  • "status": "UNLABELED",
  • "datasets":
    [
    ],
  • "read_only": true
}

Get a particular resource.

path Parameters
resource_id
required
string (ResourceId)
Example: ffffffff-0000-0000-0000-ffffffffffff

The UUID of a resource.

Responses

200

Information about a resource.

Response Schema: application/json
id
required
string (ResourceId)
name
required
string
duration
required
number
created
required
string <date-time>
status
required
any
Enum: "UNLABELED" "IN_PROGRESS" "LABELED"
datasets
required
Array of strings (DatasetId)

The IDs of the datasets to which this resource belongs.

read_only
required
boolean
400

The request was not properly formed.

get/resources/{resource_id}

BrainPlatform API powering MissionControl.

https://missioncontrol.deepgram.com/v1/resources/{resource_id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "ffffffff-0000-0000-0000-ffffffffffff",
  • "name": "recording.wav",
  • "duration": 96.5,
  • "created": "2020-10-02T20:42:23Z",
  • "status": "UNLABELED",
  • "datasets":
    [
    ],
  • "read_only": true
}

Delete a resource.

When deleting a resource, it is removed from any dataset in which it resides.

path Parameters
resource_id
required
string (ResourceId)
Example: ffffffff-0000-0000-0000-ffffffffffff

The UUID of a resource.

Responses

204

The resource was deleted.

400

The request was not properly formed.

delete/resources/{resource_id}

BrainPlatform API powering MissionControl.

https://missioncontrol.deepgram.com/v1/resources/{resource_id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "reason": "string"
}

Retrieve the audio for a resource.

path Parameters
resource_id
required
string (ResourceId)
Example: ffffffff-0000-0000-0000-ffffffffffff

The UUID of a resource.

Responses

200

An audio file.

Response Schema: application/octet-stream
string <binary>
400

The request was not properly formed.

get/resources/{resource_id}/audio

BrainPlatform API powering MissionControl.

https://missioncontrol.deepgram.com/v1/resources/{resource_id}/audio

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "reason": "string"
}

Upload audio for a resource.

If a resource was created without audio (by providing an empty body) then the audio can be provided later using this endpoint. If the resource already has audio associated with it, then this endpoint will return an error.

path Parameters
resource_id
required
string (ResourceId)
Example: ffffffff-0000-0000-0000-ffffffffffff

The UUID of a resource.

Request Body schema:

Like the resource creation endpoint, this endpoint accepts both raw binary audio data in the body of the request, or a JSON object with a url field from which the audio can be retrieved.

string <binary>

Responses

200

The audio was successfully uploaded.

Response Schema: application/json
id
required
string (ResourceId)
name
required
string
duration
required
number
created
required
string <date-time>
status
required
any
Enum: "UNLABELED" "IN_PROGRESS" "LABELED"
datasets
required
Array of strings (DatasetId)

The IDs of the datasets to which this resource belongs.

read_only
required
boolean
409

The resource already has audio associated with it.

put/resources/{resource_id}/audio

BrainPlatform API powering MissionControl.

https://missioncontrol.deepgram.com/v1/resources/{resource_id}/audio

Request samples

Content type
No sample

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "ffffffff-0000-0000-0000-ffffffffffff",
  • "name": "recording.wav",
  • "duration": 96.5,
  • "created": "2020-10-02T20:42:23Z",
  • "status": "UNLABELED",
  • "datasets":
    [
    ],
  • "read_only": true
}

Retrieve the transcript for a resource.

path Parameters
resource_id
required
string (ResourceId)
Example: ffffffff-0000-0000-0000-ffffffffffff

The UUID of a resource.

Responses

200

A completed transcript.

Response Schema: application/text
string
400

The request was not properly formed.

get/resources/{resource_id}/transcript

BrainPlatform API powering MissionControl.

https://missioncontrol.deepgram.com/v1/resources/{resource_id}/transcript

Response samples

Content type
application/text
Copy
Once upon a midnight dreary, while I pondered, weak and weary...

Set the transcript for a resource.

path Parameters
resource_id
required
string (ResourceId)
Example: ffffffff-0000-0000-0000-ffffffffffff

The UUID of a resource.

Request Body schema: application/text
Schema not provided

Responses

200

The transcript was successfully updated.

Response Schema: application/json
id
required
string (ResourceId)
name
required
string
duration
required
number
created
required
string <date-time>
status
required
any
Enum: "UNLABELED" "IN_PROGRESS" "LABELED"
datasets
required
Array of strings (DatasetId)

The IDs of the datasets to which this resource belongs.

read_only
required
boolean
400

The request was not properly formed.

put/resources/{resource_id}/transcript

BrainPlatform API powering MissionControl.

https://missioncontrol.deepgram.com/v1/resources/{resource_id}/transcript

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "ffffffff-0000-0000-0000-ffffffffffff",
  • "name": "recording.wav",
  • "duration": 96.5,
  • "created": "2020-10-02T20:42:23Z",
  • "status": "UNLABELED",
  • "datasets":
    [
    ],
  • "read_only": true
}

Labeling

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

Request labels for resources.

This requests professional labels from Deepgram's transcriptionists. Labels can be requested for a single resource using the query parameter, or for multiple resources by sending a JSON body.

query Parameters
resource-id
string (ResourceId)
Example: resource-id=ffffffff-0000-0000-0000-ffffffffffff

The ID of the resource to label. To request labels for multiple resources in a single request, use the request body. This query parameter is maintained for backwards compatibility. It is not deprecated now, but it may be in the future.

Request Body schema: application/json

An optional request body if the single-resource query parameter is not sufficient.

resource_ids
required
Array of strings (ResourceId)

Responses

200

Labels have been requested.

Response Schema: application/json
id
required
string (ResourceId)
name
required
string
duration
required
number
created
required
string <date-time>
status
required
any
Enum: "UNLABELED" "IN_PROGRESS" "LABELED"
datasets
required
Array of strings (DatasetId)

The IDs of the datasets to which this resource belongs.

read_only
required
boolean
429

Requesting labels for these resoures would exceed the user's limit for professional labeling. Note that if labels were requested for multiple resources, it may still be possible to request labels for a subset of those resources without exceeding the limit.

post/label

BrainPlatform API powering MissionControl.

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

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "resource_ids":
    [
    ]
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "ffffffff-0000-0000-0000-ffffffffffff",
  • "name": "recording.wav",
  • "duration": 96.5,
  • "created": "2020-10-02T20:42:23Z",
  • "status": "UNLABELED",
  • "datasets":
    [
    ],
  • "read_only": true
}

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 a list of all custom models.

Responses

200

A list of custom models.

Response Schema: application/json
result
required
Array of objects (CustomModelInfo)
get/models

BrainPlatform API powering MissionControl.

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "result":
    [
    ]
}

Create a new custom model.

Request Body schema: application/json

Model creation parameters.

name
required
string (ModelName)
datasets
Array of strings (DatasetId)

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

train
object

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

Responses

200

A custom model was successfully created.

Response Schema: application/json
id
required
string (CustomModelId)
version_id
required
string (CustomModelVersionId)
name
required
string
created
required
string <date-time>
status
string
Enum: "DRAFT" "PENDING" "TRAINING" "TRAINED" "DEPLOY_REQUESTED" "DEPLOYED" "CANCELELD" "FAILED"
last_trained
string <date-time>
wer
number
model_type
required
string
Enum: "DEEPGRAM_BASE" "DEEPGRAM_TRAINED" "USER"
post/models

BrainPlatform API powering MissionControl.

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

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "name": "MyModel",
  • "datasets":
    [
    ],
  • "train":
    {
    }
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  • "version_id": "12345678-1234-1234-1234-1234567890ab",
  • "name": "string",
  • "created": "2020-10-02T20:42:23Z",
  • "status": "TRAINED",
  • "last_trained": "2020-10-02T20:42:23Z",
  • "wer": 0,
  • "model_type": "DEEPGRAM_BASE"
}

Get information about a custom model.

path Parameters
model_id
required
string (CustomModelId)
Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

The UUID of a custom model.

query Parameters
model-version
string (CustomModelVersionId)
Example: model-version=12345678-1234-1234-1234-1234567890ab

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

Responses

200

Information about a custom model.

Response Schema: application/json
id
required
string (CustomModelId)
version_id
required
string (CustomModelVersionId)
name
required
string
created
required
string <date-time>
status
string
Enum: "DRAFT" "PENDING" "TRAINING" "TRAINED" "DEPLOY_REQUESTED" "DEPLOYED" "CANCELELD" "FAILED"
last_trained
string <date-time>
wer
number
model_type
required
string
Enum: "DEEPGRAM_BASE" "DEEPGRAM_TRAINED" "USER"
get/models/{model_id}

BrainPlatform API powering MissionControl.

https://missioncontrol.deepgram.com/v1/models/{model_id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  • "version_id": "12345678-1234-1234-1234-1234567890ab",
  • "name": "string",
  • "created": "2020-10-02T20:42:23Z",
  • "status": "TRAINED",
  • "last_trained": "2020-10-02T20:42:23Z",
  • "wer": 0,
  • "model_type": "DEEPGRAM_BASE"
}

Modify a custom model.

path Parameters
model_id
required
string (CustomModelId)
Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

The UUID of a custom model.

Request Body schema: application/json
name
string

Change the name of the model.

Responses

200

The model was successfully updated.

Response Schema: application/json
id
required
string (CustomModelId)
version_id
required
string (CustomModelVersionId)
name
required
string
created
required
string <date-time>
status
string
Enum: "DRAFT" "PENDING" "TRAINING" "TRAINED" "DEPLOY_REQUESTED" "DEPLOYED" "CANCELELD" "FAILED"
last_trained
string <date-time>
wer
number
model_type
required
string
Enum: "DEEPGRAM_BASE" "DEEPGRAM_TRAINED" "USER"
patch/models/{model_id}

BrainPlatform API powering MissionControl.

https://missioncontrol.deepgram.com/v1/models/{model_id}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "name": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  • "version_id": "12345678-1234-1234-1234-1234567890ab",
  • "name": "string",
  • "created": "2020-10-02T20:42:23Z",
  • "status": "TRAINED",
  • "last_trained": "2020-10-02T20:42:23Z",
  • "wer": 0,
  • "model_type": "DEEPGRAM_BASE"
}

Delete a custom model.

path Parameters
model_id
required
string (CustomModelId)
Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

The UUID of a custom model.

Responses

200

A custom model was successfully deleted.

Response Schema: application/json
result
string
Value: "deleted"
delete/models/{model_id}

BrainPlatform API powering MissionControl.

https://missioncontrol.deepgram.com/v1/models/{model_id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "result": "deleted"
}

Get the list of datasets associated with this model.

path Parameters
model_id
required
string (CustomModelId)
Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

The UUID of a custom model.

query Parameters
model-version
string (CustomModelVersionId)
Example: model-version=12345678-1234-1234-1234-1234567890ab

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

Responses

200

A list of datasets.

Response Schema: application/json
model_id
string (CustomModelId)
datasets
Array of objects (CustomModelDataset)
get/models/{model_id}/datasets

BrainPlatform API powering MissionControl.

https://missioncontrol.deepgram.com/v1/models/{model_id}/datasets

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "model_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  • "datasets":
    [
    ]
}

Set the exact list of datasets associated with the model.

path Parameters
model_id
required
string (CustomModelId)
Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

The UUID of a custom model.

Request Body schema: application/json
Array
string

Responses

200

The list of datasets currently associated with this model.

Response Schema: application/json
model_id
string (CustomModelId)
datasets
Array of objects (CustomModelDataset)
put/models/{model_id}/datasets

BrainPlatform API powering MissionControl.

https://missioncontrol.deepgram.com/v1/models/{model_id}/datasets

Request samples

Content type
application/json
Copy
Expand all Collapse all
[
  • "string"
]

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "model_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  • "datasets":
    [
    ]
}

Add a dataset to a custom model.

path Parameters
model_id
required
string (CustomModelId)
Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

The UUID of a custom model.

dataset_id
required
string
Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

The UUID of a dataset.

Responses

200

The list of datasets currently associated with this model.

Response Schema: application/json
model_id
string (CustomModelId)
datasets
Array of objects (CustomModelDataset)
put/models/{model_id}/datasets/{dataset_id}

BrainPlatform API powering MissionControl.

https://missioncontrol.deepgram.com/v1/models/{model_id}/datasets/{dataset_id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "model_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  • "datasets":
    [
    ]
}

Remove a dataset from a custom model.

path Parameters
model_id
required
string (CustomModelId)
Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

The UUID of a custom model.

dataset_id
required
string
Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

The UUID of a dataset.

Responses

200

The list of datasets currently associated with this model.

Response Schema: application/json
model_id
string (CustomModelId)
datasets
Array of objects (CustomModelDataset)
delete/models/{model_id}/datasets/{dataset_id}

BrainPlatform API powering MissionControl.

https://missioncontrol.deepgram.com/v1/models/{model_id}/datasets/{dataset_id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "model_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  • "datasets":
    [
    ]
}

Get the resources that were used to train this model.

path Parameters
model_id
required
string (CustomModelId)
Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

The UUID of a custom model.

Responses

200

The resources that were used to train this model.

Response Schema: application/json
result
required
Array of objects (ResourceInfo)
get/models/{model_id}/resources

BrainPlatform API powering MissionControl.

https://missioncontrol.deepgram.com/v1/models/{model_id}/resources

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "result":
    [
    ]
}

Get a list of all the versions of this model.

path Parameters
model_id
required
string (CustomModelId)
Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

The UUID of a custom model.

Responses

200

A list of model IDs.

Response Schema: application/json
model_id
required
string (CustomModelId)
versions
required
Array of objects
get/models/{model_id}/versions

BrainPlatform API powering MissionControl.

https://missioncontrol.deepgram.com/v1/models/{model_id}/versions

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "model_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  • "versions":
    [
    ]
}

Get statistics about a model.

The supplied word error rate (wer) is defined with respect to two things - a model, and a set of test resources. Note that the wer property of a model info object is acquired by testing that model against a validation set that was automatically created when you submitted assigned resources to your model_id. This validation set was not used for training, and is used to provide a helpful estimate of model performance.

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

path Parameters
model_id
required
string (CustomModelId)
Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

The UUID of a custom model.

Responses

200

Model statistics.

Response Schema: application/json
model
object (CustomModelInfo)
wers
Array of objects
get/models/{model_id}/stats

BrainPlatform API powering MissionControl.

https://missioncontrol.deepgram.com/v1/models/{model_id}/stats

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "model":
    {
    },
  • "wers":
    [
    ]
}

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 a request to train the given model.

This request will add a job to the training queue. If the model already has a job in the queue, or if it has been previously trained, then it will not be re-added.

query Parameters
model-id
required
string (CustomModelId)
Example: model-id=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

The UUID of the model to be trained.

base-model-id
string (CustomModelId)
Example: base-model-id=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

The UUID of the model that should be used as the starting point for training this one. If not specified, an intelligent default will be chosen.

model-type
string
Default: "AUTO_TRAINED"
Enum: "AUTO_TRAINED" "AUTO_ML" "EXPERT_TRAINED"

Select the type of training to perform. Note that AUTO_ML and EXPERT_TRAINED are a premium feature and require approval from Deepgram's sales team. If you are just starting to explore MissionControl, you likely want to use the default value of AUTO_TRAINED.

Responses

200

The model has already been submitted for training.

Response Schema: application/json
id
required
string (CustomModelVersionId)
submitted
required
string <date-time>
finished
required
string <date-time>
status
required
string
Enum: "pending" "training" "finished"
parameters
required
object (TrainingParameters)

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

201

The model was submitted for training.

Response Schema: application/json
id
required
string (CustomModelVersionId)
submitted
required
string <date-time>
finished
required
string <date-time>
status
required
string
Enum: "pending" "training" "finished"
parameters
required
object (TrainingParameters)

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

post/train

BrainPlatform API powering MissionControl.

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "12345678-1234-1234-1234-1234567890ab",
  • "submitted": "2020-10-02T20:42:23Z",
  • "finished": "2020-10-02T20:42:23Z",
  • "status": "pending",
  • "parameters":
    {
    }
}

List models in the training queue.

Responses

200

The list of models currently in the training queue.

Response Schema: application/json
result
required
Array of objects (TrainingQueueItem)
get/train

BrainPlatform API powering MissionControl.

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "result":
    [
    ]
}

Cancel a training job.

This will remove a job from the training queue.

query Parameters
model-version
required
string (CustomModelVersionId)
Example: model-version=12345678-1234-1234-1234-1234567890ab

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

Responses

200

The job was cancelled successfully.

delete/train

BrainPlatform API powering MissionControl.

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

Deploy

Deploy a model.

This will deploy a model so that it can be used to create automatic transcripts. Once deployed, see the /listen endpoint for instructions on how to transcribe with your model_id.

query Parameters
model-id
required
string (CustomModelId)
Example: model-id=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Responses

200

The model has been scheduled for deployment.

post/deploy

BrainPlatform API powering MissionControl.

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

Undeploy a model.

query Parameters
model-id
required
string (CustomModelId)
Example: model-id=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

Responses

200

The model has been undeployed.

post/undeploy

BrainPlatform API powering MissionControl.

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

Transcribing

For documentation on getting automatic transcription, also known as the /listen endpoint, visit docs.deepgram.com.