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 from SpeechEngine, also known as the /listen endpoint, visit deepgram.com/docs.

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.

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.

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.

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.

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.

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.

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
{
  • "result":
    {
    }
}

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.

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-07-01T16:00:58Z",
  • "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.

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-07-01T16:00:58Z",
  • "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.

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.

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-07-01T16:00:58Z",
  • "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.

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
required
string (DatasetId)
Example: dataset-id=dddddddd-1111-2222-3333-444444444444

Add the new resource to a dataset.

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

Responses

201

A new resource was created.

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-07-01T16:00:58Z",
  • "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.

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-07-01T16:00:58Z",
  • "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.

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.

By re-uploading audio, the transcript for this resource might no longer be valid. If the resource was in the TRANSCRIBED state, then it will be changed to PENDING until the transcript is reviewed.

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

The UUID of a resource.

Responses

200

The audio was successfully updated.

400

The request was not properly formed.

put/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
{
  • "id": "ffffffff-0000-0000-0000-ffffffffffff",
  • "name": "recording.wav",
  • "duration": 96.5,
  • "created": "2020-07-01T16:00:58Z",
  • "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.

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.

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-07-01T16:00:58Z",
  • "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.

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-07-01T16:00:58Z",
  • "status": "UNLABELED",
  • "datasets":
    [
    ],
  • "read_only": true
}

Models

This is the API for managing custom 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.

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.

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-07-01T16:00:58Z",
  • "status": "TRAINED",
  • "last_trained": "2020-07-01T16:00:58Z",
  • "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.

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-07-01T16:00:58Z",
  • "status": "TRAINED",
  • "last_trained": "2020-07-01T16:00:58Z",
  • "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.

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-07-01T16:00:58Z",
  • "status": "TRAINED",
  • "last_trained": "2020-07-01T16:00:58Z",
  • "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.

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.

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.

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.

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.

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.

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.

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.

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 custom 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.

Responses

200

The model has already been submitted for training.

201

The model was submitted for training.

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-07-01T16:00:58Z",
  • "finished": "2020-07-01T16:00:58Z",
  • "status": "pending",
  • "parameters":
    {
    }
}

List models in the training queue.

Responses

200

The list of models currently in the training queue.

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 from SpeechEngine, also known as the /listen endpoint, visit deepgram.com/docs.