# Usage

Note: If you have your own app/backend, and you want to integrate the API gateway as a service, we recommend you to read through [**Integration**](https://speech-ntu.gitbook.io/speech-gateway/guide-1/batch-transcribe/integration)**,** to help you reduce user management part and delegate to the API gateway instead

## Login

<mark style="color:green;">`POST`</mark> `https://gateway.speechlab.sg/auth/login`

This endpoint is used to log in into an existing account.

#### Request Body

| Name     | Type   | Description        |
| -------- | ------ | ------------------ |
| email    | string | Account's email    |
| password | string | Account's password |

{% tabs %}
{% tab title="200 Login successful" %}

```
{
    "accessToken": "Your token"
}
```

{% endtab %}

{% tab title="401 Email or Password is incorrect" %}

```
{
    "statusCode": 401,
    "message": "Unauthorized"
}
```

{% endtab %}
{% endtabs %}

## Register

<mark style="color:green;">`POST`</mark> `https://gateway.speechlab.sg/auth/register`

This endpoint is used to register an account.

#### Request Body

| Name     | Type   | Description                                                   |
| -------- | ------ | ------------------------------------------------------------- |
| name     | string | <p>Account's name<br>Must be longer than 2 characters</p>     |
| email    | string | Account's email                                               |
| password | string | <p>Account's password<br>Must be longer than 5 characters</p> |

{% tabs %}
{% tab title="201 Registration successful" %}

```
{
    "role": "user",
    "_id": "user_id",
    "name": "user_name",
    "email": "user@example.com",
    "createdAt": "2020-12-31T00:00:00.000Z"
}
```

{% endtab %}
{% endtabs %}

~~After successfully registering an account, an email verification link will sent to the email address to verify your email address. You need to click into verification link which is sent along with the email.~~

## Submit a job

<mark style="color:green;">`POST`</mark> `https://gateway.speechlab.sg/speech`

#### Headers

| Name          | Type   | Description                                                                         |
| ------------- | ------ | ----------------------------------------------------------------------------------- |
| Authorization | string | <p>Access Token.<br><strong>Bearer \<access token obtained from login></strong></p> |

#### Request Body

| Name          | Type        | Description                                                                                                                                                                  |
| ------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| file          | object      | File Object                                                                                                                                                                  |
| lang          | string      | <p>Language code<br>Examples (not exhaustive): <strong>'english', 'mandarin', 'malay', 'english-mandarin', 'english-malay'</strong></p>                                      |
| queue         | string      | <p>Queue that speech job will be assigned to<br>Example (not exhaustive): <strong>'normal'</strong><br>If not specified, will default to <strong>'normal'</strong> queue</p> |
| audioType     | string      | Examples: **'fartalk', 'closetalk', 'mobile', 'telephony', 'boundary'**                                                                                                      |
| audioTrack    | string      | Examples: **'single', 'multi'**                                                                                                                                              |
| sampling      | string      | <p>Example: '<strong>16khz'</strong><br>If not specified, will default to <strong>'16khz'</strong> </p>                                                                      |
| keywords      | array       | An array of strings                                                                                                                                                          |
| numChn        | number      | Number of audio channels                                                                                                                                                     |
| outputFormats | array       | <p>An array of file extensions<br>Example: <strong>\['txt', 'srt']</strong></p>                                                                                              |
| checksum      | string      | md5 checksum string of the file object to check if received file is identical                                                                                                |
| webhook       | string      | <p>API endpoint to receive update when your speech is completed<br>Example: <strong>'<http://your-api.com/status>'</strong></p>                                              |
| customData    | JSON object | <p>To pass other extra  metadata such as num\_spk and orgID.<br><br>Example:</p><p> {"num\_spk":-1} <br>-1 if no. of speaker is unknown.</p>                                 |

{% tabs %}
{% tab title="200 " %}

```
{
    "queue": "normal",
    "result": null,
    "status": "created",
    "formats": [
        "stm",
        "srt",
        "TextGrid"
    ],
    "sampling": "16khz",
    "lang": "english",
    "name": "Note",
    "_id": "609608c3ec54c0066abb7531", // Note down this value
    "type": "batch",
    "createdAt": "2021-05-08T03:42:59.708Z"
}
```

{% endtab %}

{% tab title="400 No "file" object was found in the request." %}

```
{
    "statusCode": 400,
    "message": "file must not be empty",
    "error": "Bad Request"
}
```

{% endtab %}

{% tab title="403 User is not allowed to submit jobs to the "queue" specified in the request." %}

```
{
    "statusCode": 403,
    "message": "You can only submit job to \"meadow9\" queue",
    "error": "Forbidden"
}
```

{% endtab %}

{% tab title="422 "lang" field provided was not one of the accepted values. Invalid values for other fields will also return 422 error code." %}

```
{
    "statusCode": 422,
    "message": "Language \"singlish\" does not exist",
    "error": "Unprocessable Entity"
}
```

{% endtab %}
{% endtabs %}

After request successfully, in the response returned, the field **\_id** is the ID of the job, also referred to as **'SpeechID'**. Note this value down (to be used in future requests).

About **audioType** and **audioTrack**:\
If **audioType** and **audioTrack** fields can be provided that best describes the audio file, our system will try to use our best-fit model to give a better result.

About **webhook**: \
An audio file may take a long time to decode (dependent on its duration, type,...), and the processing time is not deterministic (likely not the same for 2 identical jobs). \
Instead of calling our endpoint to check on the status of a job, a HTTP endpoint can be provided via the **webhook** field, and when the job is **done**, the HTTP endpoint provided will be notified of the job's completion. Subsequently, our other endpoint can be called to download the transcription file(s).

About **queue:** \
A queue is where the job will be running in, each queue will have some workers to pick up jobs and process.\
If not specified, the job will be submitted to **normal** queue and where this queue is shared among others. Therefore, when there are already existing jobs in the queue, this job will be pending until there are workers available. \
If you want to have dedicated queue that is not shared with others, please contact our support to get in touch.

## Get user's speech history

<mark style="color:blue;">`GET`</mark> `https://gateway.speechlab.sg/speech/history`

This endpoint is used to retrieve a user's speech history.\
Filter options "queue", "status", "lang", and "type" are optionally available to filter returned results.

#### Path Parameters

| Name   | Type   | Description                                                                                                                                                               |
| ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| email  | string | <p>Email of user's history to retrieve<br>For 'normal' accounts, only user's own email is accepted (but is optional as user can be identified by their token already)</p> |
| queue  | string | <p>Queue of speech jobs<br>Example (not exhaustive): <strong>'normal'</strong></p>                                                                                        |
| status | string | <p>Status of speech jobs<br>Examples (not exhaustive): <strong>'done', 'processing'</strong></p>                                                                          |
| lang   | string | <p>Language code of speech jobs<br>Examples (not exhaustive): <strong>'english', 'mandarin', 'malay', 'english-mandarin', 'english-malay'</strong></p>                    |
| type   | string | <p>Type of speech jobs<br>Examples: <strong>'live', 'batch'</strong></p>                                                                                                  |

#### Headers

| Name          | Type   | Description                                                                                 |
| ------------- | ------ | ------------------------------------------------------------------------------------------- |
| Authorization | string | <p>Access Token.<br>Format: <strong>Bearer \<access token obtained from login></strong></p> |

{% tabs %}
{% tab title="200 " %}

```
{
    "history": [
        {
            "queue": "normal",
            "status": "done",
            "formats": [
                "txt",
                "stm"
            ],
            "sampling": "16khz",
            "lang": "english",
            "name": "Note",
            "_id": "6135c0fc9dda32002d4d91d2",
            "userCreated": {
                "role": "admin",
                "type": "normal",
                "name": "user",
                "_id": "5f868425deb32e0029690890",
                "isBlocked": false,
                "isDeleted": false,
                "isVerified": true,
                "email": "user@example.com",
                "createdAt": "2020-10-14T04:52:53.905Z",
                "updatedAt": "2021-05-25T08:50:13.832Z",
                "__v": 0
            },
            "input": [
                {
                    "isSubmitted": true,
                    "errorCode": null,
                    "status": "done",
                    "progress": [
                        {
                            "content": "DECODING",
                            "createdAt": "2021-09-06T07:19:42.772Z"
                        },
                        {
                            "content": "DONE",
                            "createdAt": "2021-09-06T07:21:25.186Z"
                        }
                    ],
                    "_id": "6135c0fc9dda32002d4d91d4",
                    "file": {
                        "children": [],
                        "parent": null,
                        "_id": "6135c0fc9dda32002d4d91d3",
                        "originalName": "audio.wav",
                        "mimeType": "audio/wave",
                        "filename": "36436d30-701b-407b-9dfd-230a9d5ba600-1630912764391.wav",
                        "size": 187404,
                        "duration": 5.855,
                        "userCreated": "5f868425deb32e0029690890",
                        "createdAt": "2021-09-06T07:19:24.591Z"
                    }
                }
            ],
            "type": "batch",
            "createdAt": "2021-09-06T07:19:24.550Z",
            "updatedAt": "2021-09-06T07:21:25.333Z",
            "__v": 0,
            "sourceFile": {
                "children": [],
                "parent": null,
                "_id": "6135c0fc9dda32002d4d91d3",
                "originalName": "audio.wav",
                "mimeType": "audio/wave",
                "filename": "36436d30-701b-407b-9dfd-230a9d5ba600-1630912764391.wav",
                "size": 187404,
                "duration": 5.855,
                "userCreated": "5f868425deb32e0029690890",
                "createdAt": "2021-09-06T07:19:24.591Z"
            }
        }
    ],
    "totalHistory": 1
}
        
```

{% endtab %}

{% tab title="401 "Normal" account user tried to query for another user's history" %}

```
{
    "statusCode": 401,
    "message": "Your user token does not match email being queried",
    "error": "Unauthorized"
}
```

{% endtab %}
{% endtabs %}

## Get job status

<mark style="color:blue;">`GET`</mark> `https://gateway.speechlab.sg/speech/:id`

This endpoint is used to retrieve a speech job's status.\
Alternatively, consider passing **webhook** field when submitting a job as described in "**Submit a job**" endpoint above.

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
| id   | string | Speech's ID |

#### Headers

| Name          | Type   | Description                                                                                 |
| ------------- | ------ | ------------------------------------------------------------------------------------------- |
| Authorization | string | <p>Access Token.<br>Format: <strong>Bearer \<access token obtained from login></strong></p> |

{% tabs %}
{% tab title="200 " %}

```
{
    "status": "processing",
    "formats": [
        "stm",
        "srt",
        "TextGrid"
    ],
    "sampling": "16khz",
    "lang": "english",
    "name": "Note",
    "_id": "5f11c797b6d18b0029b60975",
    "queue": "normal",
    "input": [
        {
            "isSubmitted": true,
            "errorCode": null,
            "status": "processing",
            "progress": [{
                "content": "Decoding",
                "createdAt": "2020-07-17T15:45:27.941Z"
            }],
            "_id": "5f11c798b6d18b0029b60977",
            "file": {
                "_id": "5f11c797b6d18b0029b60976",
                "originalName": "james-test.wav",
                "mimeType": "audio/wave",
                "filename": "5f11c797b6d18b0029b60976.wav",
                "size": 187404,
                "duration": 5.855,
                "createdAt": "2020-07-17T15:45:27.941Z"
            }
        }
    ],
    "createdAt": "2020-07-17T15:45:27.882Z",
    "sourceFile": {
        "_id": "5f11c797b6d18b0029b60976",
        "originalName": "james-test.wav",
        "mimeType": "audio/wave",
        "filename": "5f11c797b6d18b0029b60976.wav",
        "size": 187404,
        "duration": 5.855,
        "createdAt": "2020-07-17T15:45:27.941Z"
    }
}
```

{% endtab %}

{% tab title="404 No speech job found for provided Speech ID" %}

```
{
    "statusCode": 404,
    "message": "Speech not found",
    "error": "Not Found"
}
```

{% endtab %}
{% endtabs %}

## Get transcription (Deprecated)

<mark style="color:blue;">`GET`</mark> `https://gateway.speechlab.sg/speech/result/:id`

This endpoint will redirect to a URL to download the transcription files if Speech status is **done**.

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
| id   | string | Speech's ID |

#### Headers

| Name          | Type   | Description                                                                                 |
| ------------- | ------ | ------------------------------------------------------------------------------------------- |
| Authorization | string | <p>Access Token.<br>Format: <strong>Bearer \<access token obtained from login></strong></p> |

{% tabs %}
{% tab title="200 " %}

```
Return transcription downloadable file
```

{% endtab %}

{% tab title="404 " %}

```
{
    "statusCode": 404,
    "message": "Speech not found",
    "error": "Not Found"
}
```

{% endtab %}
{% endtabs %}

## Get transcription (New)

<mark style="color:blue;">`GET`</mark> `https://gateway.speechlab.sg/speech/:id/result`

This endpoint will return a URL to download the transcription files if Speech status is **done**.

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
| id   | string | Speech's ID |

#### Headers

| Name          | Type   | Description                                                                                 |
| ------------- | ------ | ------------------------------------------------------------------------------------------- |
| Authorization | string | <p>Access Token.<br>Format: <strong>Bearer \<access token obtained from login></strong></p> |

{% tabs %}
{% tab title="200 " %}

```
{
    "url": "link to download transcription files"
}
```

{% endtab %}

{% tab title="404 " %}

```
{
    "statusCode": 404,
    "message": "Speech not found",
    "error": "Not Found"
}
```

{% endtab %}
{% endtabs %}

## Change account's password

<mark style="color:green;">`POST`</mark> `https://gateway.speechlab.sg/auth/change-password`

This endpoint is used to change an existing account's password.

#### Request Body

| Name               | Type   | Description                   |
| ------------------ | ------ | ----------------------------- |
| email              | string | Account's email               |
| currentPassword    | string | Account's current password    |
| newPassword        | string | New password                  |
| confirmNewPassword | string | New password for confirmation |

{% tabs %}
{% tab title="200 " %}

```
{
    "message": "Password changed successfully"
}
```

{% endtab %}

{% tab title="404 No account found with provided email" %}

```
{
    "statusCode": 404,
    "message": "Account not found",
    "error": "Not Found"
}
```

{% endtab %}
{% endtabs %}

## Forgot account's password

<mark style="color:green;">`POST`</mark> `https://gateway.speechlab.sg/auth/forgot-password`

This endpoint is used to reset an existing account's password. An email will be sent to the email address which contains a **code** used to reset password.

#### Request Body

| Name  | Type   | Description     |
| ----- | ------ | --------------- |
| email | string | Account's email |

{% tabs %}
{% tab title="200 Request to reset password send successfully, check email's inbox to get reset code" %}

```
{
    "message": "Please check your inbox for reset password code"
}
```

{% endtab %}

{% tab title="404 No account found with provided email" %}

```
{
    "statusCode": 404,
    "message": "Email not found",
    "error": "Not Found"
}
```

{% endtab %}
{% endtabs %}

## Reset password

<mark style="color:green;">`POST`</mark> `https://gateway.speechlab.sg/auth/reset-password`

This endpoint is used to reset an account's password with a **code** obtained from the "Forgot account's password" endpoint.

#### Request Body

| Name               | Type   | Description          |
| ------------------ | ------ | -------------------- |
| email              | string | Account's email      |
| code               | string | Forgot password code |
| newPassword        | string | New password         |
| confirmNewPassword | string | Confirm new password |

{% tabs %}
{% tab title="200 Account's password successfully reset." %}

```
{
    "message": "Your password has been reset"
}
```

{% endtab %}

{% tab title="404 No account found with the provided email, or the code is invalid." %}

```
{
    "statusCode": 404,
    "message": "Email not found or code is incorrect",
    "error": "Not Found"
}
```

{% endtab %}

{% tab title="406 Your newPassword and confirmNewPassword are not matched." %}

```
{
    "statusCode": 406,
    "message": "New passwords are not matched each other",
    "error": "Not Acceptable"
}

```

{% endtab %}
{% endtabs %}

## Change account's name

<mark style="color:blue;">`GET`</mark> `https://gateway.speechlab.sg/users/change-name`

This endpoint is for users to change their own account's name.

#### Headers

| Name          | Type   | Description                                                                                 |
| ------------- | ------ | ------------------------------------------------------------------------------------------- |
| Authorization | string | <p>Access Token.<br>Format: <strong>Bearer \<access token obtained from login></strong></p> |

#### Request Body

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| newName | string | John Doe    |

{% tabs %}
{% tab title="200 The response contains information about the updated User Account" %}

```
{
    "message": "Your name has been changed to John Doe"
}
```

{% endtab %}
{% endtabs %}

## Create an application

<mark style="color:green;">`POST`</mark> `https://gateway.speechlab.sg/applications`

The endpoint is used to create a third-party applications that makes use of Gateway's APIs.\
**Note:** If successful, app's **secret** will only be shown once, be sure to save it somewhere privately.

#### Headers

| Name          | Type   | Description                                                                                 |
| ------------- | ------ | ------------------------------------------------------------------------------------------- |
| Authorization | string | <p>Access Token.<br>Format: <strong>Bearer \<access token obtained from login></strong></p> |

#### Request Body

| Name | Type   | Description        |
| ---- | ------ | ------------------ |
| name | string | Application's name |

{% tabs %}
{% tab title="200 " %}

```
{
    "_id": "5f8d581e87bf680b226d3cc1", // App ID
    "name": "Test App",
    "key": "5f8d581e87bf680b226d3cc0", // Key ID (used to get public key to verify JWT token)
    "createdAt": "2020-10-19T09:10:54.482Z",
    "secret": "41d29bb4c52389441c1647764de94493c16a8c42e9529bdaa7502cccc7f111e7" // App secret
}
```

{% endtab %}
{% endtabs %}

## Get JWT Public Key

<mark style="color:blue;">`GET`</mark> `https://gateway.speechlab.sg/keys/:keyId`

This endpoint returns JWT public key, third-party will use this key in order to verify JWT token generated from API gateway.

#### Path Parameters

| Name  | Type   | Description                                            |
| ----- | ------ | ------------------------------------------------------ |
| keyId | string | Key ID returned after creating application (see above) |

{% tabs %}
{% tab title="200 " %}

```
public key in file
```

{% endtab %}
{% endtabs %}