---
title: "Collect async voice and video with Speak AI recorders"
description: "Create and clone Speak AI recorders, set their questions and settings, generate share URLs, and read the recordings that respondents submit."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.speakai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Collect async voice and video with Speak AI recorders


import EndpointIndex from "@/components/api/EndpointIndex.astro";

The Speak AI API exposes 11 recorders and surveys endpoints under the base URL `https://api.speakai.co/v1`. Every request needs the `x-speakai-key` and `x-access-token` headers described in [Authentication](/api/authentication/).

Suvery endpoints serve the purpose of operating an surveys: listing the files, getting info, creating\\updating\\deleting a recorder, generating embeddable URL for it.

Embeddable supports checking it's status,uploading of the recordings directly and verification of password to access the recorder as a user.

## What can you do with the recorders and surveys endpoints?

Speak AI groups these 11 endpoints under the recorders and surveys resource. Each entry below links to the full reference for that endpoint further down this page.

| Method | Path | What it does |
| --- | --- | --- |
| `GET` | [`/recorder`](#get-recorder) | Recorder List |
| `GET` | [`/recorder/{recorderId}`](#get-recorder-recorder-id) | Recorder info |
| `DELETE` | [`/recorder/{recorderId}`](#delete-recorder-recorder-id) | Delete Recorder |
| `POST` | [`/recorder/clone`](#post-recorder-clone) | Clone Recorder |
| `POST` | [`/recorder/create`](#post-recorder-create) | Create Recorder |
| `POST` | [`/recorder/questions/{recorderId}`](#post-recorder-questions-recorder-id) | Update Recorder Questions |
| `GET` | [`/recorder/recordings/{recorderId}`](#get-recorder-recordings-recorder-id) | Recording Details |
| `PUT` | [`/recorder/settings/{recorderId}`](#put-recorder-settings-recorder-id) | Update Recorder Settings |
| `GET` | [`/recorder/status/{token}`](#get-recorder-status-token) | Check Recorder Status |
| `GET` | [`/recorder/url/{recorderId}`](#get-recorder-url-recorder-id) | Generate Recorder URL |
| `POST` | [`/recorder/verify`](#post-recorder-verify) | Verify Password |

<h2 id="get-recorder">Recorder List</h2>

#### API Endpoint: Retrieve Recorders

This endpoint retrieves a list of recorders with pagination and sorting options. It allows users to fetch details about available recorders based on specified parameters.

##### Request

**Method:** GET  
**URL:** `https://api.speakai.co/v1/recorder`

**Query Parameters:**

- `page` (integer): The page number of the results to retrieve. Default is `0`.

- `pageSize` (integer): The number of records to return per page. Default is `20`.

- `sortBy` (string): The field by which to sort the results, followed by the sorting order. For example, `createdAt:desc` sorts by the creation date in descending order.

##### Response

The response will contain a JSON object with the following structure:

- `status` (string): The status of the request.

- `data` (object): Contains the results of the request.

    - `totalCount` (integer): The total number of recorders available.

    - `page` (integer): The current page number of the results.

    - `recorderList` (array): A list of recorder objects, each containing:

        - `duration` (integer): The duration of the recording.

        - `isAutoAnalyze` (boolean): Indicates if the recorder is set for automatic analysis.

        - `isActive` (boolean): Indicates if the recorder is currently active.

        - `recordings` (array): An array of recordings associated with the recorder.

        - `createdAt` (string): The timestamp when the recorder was created.

        - `updatedAt` (string): The timestamp when the recorder was last updated.

        - `userId` (string): The ID of the user associated with the recorder.

        - `recorderId` (string): The unique ID of the recorder.

        - `token` (string): A token associated with the recorder.

        - `name` (string): The name of the recorder.

        - `meta` (object): Metadata about the recorder, including:

            - `type` (object): Specifies the types of media supported (e.g., video and audio).

            - `client` (object): Information about the client, including name and email.

##### Example Response

``` json
{
  "status": "",
  "data": {
"totalCount": 0,
"page": "",
"recorderList": [
  {
    "duration": 0,
    "isAutoAnalyze": true,
    "isActive": true,
    "recordings": [],
    "createdAt": "",
    "updatedAt": "",
    "userId": "",
    "recorderId": "",
    "token": "",
    "name": "",
    "meta": {
      "type": {
        "video": true,
        "audio": true
      },
      "client": {
        "name": true,
        "email": true
      }
    }
  }
]
  }
}

```

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | No |  |
| `pageSize` | query | integer | No |  |
| `filterName` | query | string | No |  |
| `sortBy` | query | string | No |  |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X GET 'https://api.speakai.co/v1/recorder?page=0&pageSize=20&filterName=recorder&sortBy=createdAt%3Adesc' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
```

</CodePanel>

<ResponsePanel id="get-recorder" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `data` | object |
| `data.totalCount` | integer |
| `data.page` | string |
| `data.recorderList` | object[] |

Deeper nested fields are not listed. See the example response below for the full shape.

Example response, `application/json`.

```json
{
  "status": "success",
  "data": {
"totalCount": 1,
"page": "1",
"recorderList": [
  {
    "duration": 120,
    "isAutoAnalyze": false,
    "isActive": true,
    "recordings": [],
    "createdAt": "2020-12-15T14:02:21.615Z",
    "updatedAt": "2020-12-15T14:02:21.616Z",
    "userId": "5d03a9d5d4bca272e9c8cf89",
    "recorderId": "70ea4d569736",
    "token": "recorder-9-4fb7713e267a",
    "name": "recorder-9",
    "meta": {
      "type": {
        "video": false,
        "audio": true
      },
      "client": {
        "name": false,
        "email": false
      }
    }
  }
]
  }
}
```

</div>

</ResponsePanel>

</div>

<h2 id="get-recorder-recorder-id">Recorder info</h2>

#### API Endpoint: Get Recorder Details

**Method:** GET  
**Endpoint:** `https://api.speakai.co/v1/recorder/{recorderId}`

This endpoint retrieves detailed information about a specific recorder identified by the `recorderId`. The response includes various attributes related to the recorder, such as its name, description, user information, recording settings, privacy options, and metadata.

##### Response Structure:

- **status**: Status of the request.

- **data**: Contains the details of the recorder:

- **recorderId**: Unique identifier for the recorder.

- **userId**: Identifier for the user associated with the recorder.

- **name**: Name of the recorder.

- **description**: Description of the recorder.

- **token**: Authentication token for the recorder.

- **recordings**: Array of recordings associated with the recorder.

- **minDuration**: Minimum duration for recordings.

- **maxDuration**: Maximum duration for recordings.

- **privacyMode**: Privacy settings for the recorder.

- **password**: Password for accessing the recorder, if applicable.

- **isAutoAnalyze**: Indicates if automatic analysis is enabled.

- **assignTo**: User or entity to which the recorder is assigned.

- **folderId**: Identifier for the folder containing the recorder.

- **sourceLanguage**: Language settings for the recorder.

- **meta**: Metadata related to the recorder, including:

- **backgroundImg**: Background image URL.

- **logo**: Logo URL.

- **primaryColor**: Primary color used in the recorder interface.

- **type**: Supported types of recordings (audio, video, screen share, etc.).

- **client**: Client-related information including name, email, and questions.

- **callToActionButtons**: Action buttons associated with the recorder.

- **notification**: Notification settings for the recorder.

- **isActive**: Indicates if the recorder is currently active.

- **createdAt**: Timestamp of when the recorder was created.

- **updatedAt**: Timestamp of when the recorder was last updated.

- **domain**: Domain associated with the recorder.

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `recorderId` | path | string | Yes |  |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X GET 'https://api.speakai.co/v1/recorder/RECORDER_ID' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
```

</CodePanel>

<ResponsePanel id="get-recorder-recorder-id" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `data` | object |
| `data.recorderId` | string |
| `data.userId` | string |
| `data.name` | string |
| `data.description` | string |
| `data.token` | string |
| `data.recordings` | string[] |
| `data.minDuration` | integer |
| `data.maxDuration` | integer |
| `data.privacyMode` | string |
| `data.password` | string |
| `data.isAutoAnalyze` | boolean |
| `data.assignTo` | string |
| `data.folderId` | string |
| `data.sourceLanguage` | string |
| `data.meta` | object |
| `data.notification` | object |
| `data.isActive` | boolean |
| `data.createdAt` | string (date-time) |
| `data.updatedAt` | string (date-time) |
| `data.domain` | string |

Deeper nested fields are not listed. See the example response below for the full shape.

Example response (Recorder info), `application/json`. Arrays are shortened to one entry and long strings are cut.

```json
{
  "status": "success",
  "data": {
"recorderId": "2f93b3d68937",
"userId": "5d03a9d5d4bca272e9c8cf89",
"name": "Recorder Mon Jun 24 2024",
"description": "",
"token": "recorder-mon-jun-24-2024-a3535823b1a8",
"recordings": [
  "667c643820f2e801e047953c"
],
"minDuration": 15,
"maxDuration": 300,
"privacyMode": "public",
"password": "",
"isAutoAnalyze": true,
"assignTo": "",
"folderId": "f89a9eac1b62",
"sourceLanguage": "en-AU",
"meta": {
  "backgroundImg": "",
  "logo": "",
  "primaryColor": "#c42860",
  "type": {
    "audio": true,
    "video": true,
    "screenShare": false,
    "upload": {
      "file": true,
      "url": true,
      "multiple": false,
      "text": null
    }
  },
  "client": {
    "name": false,
    "email": false,
    "questions": [
      {
        "id": "41db9890bab9",
        "question": "test question",
        "isRequired": true,
        "answerType": "single",
        "options": [],
        "includeOther": false,
        "fieldId": "",
        "_id": "66bd01f4507d676698028770"
      }
    ]
  },
  "callToActionButtons": []
},
"notification": {
  "client": true,
  "upload": true,
  "notifyUsers": []
},
"isActive": true,
"createdAt": "2024-06-24T15:05:41.703Z",
"updatedAt": "2024-06-24T15:05:41.703Z",
"domain": ""
  }
}
```

</div>

</ResponsePanel>

</div>

<h2 id="delete-recorder-recorder-id">Delete Recorder</h2>

#### DELETE /v1/recorder/\{recorderId\}

This endpoint allows clients to delete a specific recorder resource identified by the `recorderId`.

##### Parameters

- **recorderId** (path parameter): The unique identifier of the recorder that you wish to delete. This parameter is required.

##### Response

Upon successful deletion, the server will respond with a confirmation message indicating the result of the operation. The structure of the response will typically include:

- A status code indicating the success or failure of the operation.

- A message providing additional context about the deletion.

Ensure that the `recorderId` provided corresponds to an existing recorder, as attempting to delete a non-existent recorder may result in an error response.

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `recorderId` | path | string | Yes |  |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X DELETE 'https://api.speakai.co/v1/recorder/RECORDER_ID' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
```

</CodePanel>

<ResponsePanel id="delete-recorder-recorder-id" statuses={[{"code":"404","description":"Not Found"}]}>

<div slot="status-404">

**`404` Not Found**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `requestId` | string |
| `code` | integer |
| `message` | string |
| `hints` | string[] |

Example response, `application/json`.

```json
{
  "status": "failed",
  "requestId": "8389bb88-ad28-4210-a72b-b9326e51d9cd",
  "code": 404,
  "message": "Recorder Note not found!",
  "hints": [
"The requested operation failed because a resource associated with the request could not be found."
  ]
}
```

</div>

</ResponsePanel>

</div>

<h2 id="post-recorder-clone">Clone Recorder</h2>

**Clone Recorder to copy all the settings from the existing recorders**

**All the required fields are as below:**

`recorderId` - Pass the recorderId from the existing recorder

**Optional:**

`name` - New name for the recorder. If not pass, it will take the existing recorder name and add `(clone)` to the new recorder

`description` - New description for the recorder. If not pass, it will take the existing recorder description as is.

`folderId` - IMPORTANT! We recommend to pass the `folderId` to ensure the recordings save in the specific folder. If not pass, it will take the existing recorder folderId setting.

---

If you need to change any other settings, we recommend to use the `Create Recorder` API call.

### Request body

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.

| Field | Type |
| --- | --- |
| `recorderId` | string |
| `name` | string |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X POST 'https://api.speakai.co/v1/recorder/clone' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{
  "recorderId": "ce8f9465763c",
  "name": "Speak Clone test"
}'
```

</CodePanel>

<ResponsePanel id="post-recorder-clone" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `data` | object |
| `data.recorderData` | object |
| `data.recorderId` | string |
| `data.token` | string |

Deeper nested fields are not listed. See the example response below for the full shape.

Example response (Clone Recorder), `application/json`.

```json
{
  "status": "success",
  "data": {
"recorderData": {
  "notification": {
    "upload": true,
    "client": false
  },
  "recordings": [],
  "minDuration": 120,
  "maxDuration": 300,
  "privacyMode": "public",
  "password": "",
  "isAutoAnalyze": true,
  "assignTo": "",
  "folderId": "",
  "sourceLanguage": "en-US",
  "isActive": true,
  "isDisabled": false,
  "isDeleted": false,
  "_id": "640f5c18a33c35424caa86fc",
  "name": "Speak test",
  "description": "Speak recorder description",
  "companyId": "5e21c8dd2d77242c64214816",
  "userId": "5d03a9d5d4bca272e9c8cf89",
  "recorderId": "3a1c8f68f2de",
  "token": "speak-test-5b87d2c2d21e",
  "meta": {
    "backgroundImg": "https://speakai-storage.s3.amazonaws.com/backgroundImg/prod/5d03a9d5d4bca272e9c8cf89/1649768360045-blob",
    "logo": "https://speakai-storage.s3.amazonaws.com/logo/prod/5d03a9d5d4bca272e9c8cf89/1649768327203-Speak---Rectange-Logo---Black---5000px-Wide.png",
    "primaryColor": "#000000",
    "type": {
      "audio": true,
      "video": true,
      "screenShare": true,
      "upload": {
        "file": true,
        "multiple": false,
        "text": true
      }
    },
    "client": {
      "name": true,
      "email": true,
      "questions": []
    }
  },
  "createdAt": "2023-03-13T17:23:36.374Z",
  "updatedAt": "2023-03-13T17:23:36.374Z",
  "__v": 0
},
"recorderId": "3a1c8f68f2de",
"token": "speak-test-5b87d2c2d21e"
  }
}
```

</div>

</ResponsePanel>

</div>

<h2 id="post-recorder-create">Create Recorder</h2>

**Create a recorder and integrate with your platform easily.**

**All the required fields are as below:**

`name` - Name of the recorder

All the other fields are optional. Your recorder will be created automatically.

`description` - Assign description of the recorder for internal purpose.

`folderId` - Save all your recordings to the assigned FolderId.

---

**Duration of the recorder:**

- `minDuration` - 15 seconds (min) & 5 min (max)
    - Pass the duration in **seconds**

- `maxDuration` - 10 seconds (min) & 3 hours (max)
    - Pass the duration in seconds

---

**Source Language:**

- You can pass the `sourceLanguage` as a code.

- Other language codes available at the top of the page.

---

**Recorder options:**

- We allow to support creating recorder with the multiple options such as:
    - `audio` - Audio recorder

    - `video` - Video recorder

    - `screeShare` - Allow to screen share on browser (Mobile not supported)

    - `uploadFile` - Allow to upload various file formats
        - `allowMultiple` - Supporting multiple file uploads

---

**Notifications:**

`upload` - Recieve an email notification when anyone uploads a recording on the recorder

`client` - When your user submits a recording (have the email address in a form) - they will receive an submittion email

---

**Client Information Questions:**

`name` - Ask for their name

`email` - Ask for their email address

`questions` - Check an API endpoint to update different types of questions.

### Request body

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.

| Field | Type |
| --- | --- |
| `name` | string |
| `description` | string |
| `folderId` | string |
| `sourceLanguage` | string |
| `duration` | object |
| `duration.minDuration` | integer |
| `duration.maxDuration` | integer |
| `options` | object |
| `options.audio` | boolean |
| `options.video` | boolean |
| `options.screenShare` | boolean |
| `options.upload` | object |
| `notification` | object |
| `notification.upload` | boolean |
| `notification.client` | boolean |
| `clientInformation` | object |
| `clientInformation.name` | boolean |
| `clientInformation.email` | boolean |
| `clientInformation.questions` | any[] |

Deeper nested fields are not listed. See the example response below for the full shape.

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X POST 'https://api.speakai.co/v1/recorder/create' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Speak test 1",
  "description": "Speak recorder description",
  "folderId": "0648e533f72c",
  "sourceLanguage": "en-US",
  "duration": {
"minDuration": 120,
"maxDuration": 300
  },
  "options": {
"audio": true,
"video": true,
"screenShare": true,
"upload": {
  "file": false,
  "text": true,
  "multiple": true,
  "url": false
}
  },
  "notification": {
"upload": true,
"client": false
  },
  "clientInformation": {
"name": true,
"email": true,
"questions": []
  }
}'
```

</CodePanel>

<ResponsePanel id="post-recorder-create" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `data` | object |
| `data.recorderData` | object |
| `data.recorderId` | string |
| `data.token` | string |

Deeper nested fields are not listed. See the example response below for the full shape.

Example response (Create Recorder), `application/json`.

```json
{
  "status": "success",
  "data": {
"recorderData": {
  "notification": {
    "upload": true,
    "client": false
  },
  "recordings": [],
  "minDuration": 120,
  "maxDuration": 300,
  "privacyMode": "public",
  "password": "",
  "isAutoAnalyze": true,
  "assignTo": "",
  "folderId": "",
  "sourceLanguage": "en-US",
  "isActive": true,
  "isDisabled": false,
  "isDeleted": false,
  "_id": "640f5c18a33c35424caa86fc",
  "name": "Speak test",
  "description": "Speak recorder description",
  "companyId": "5e21c8dd2d77242c64214816",
  "userId": "5d03a9d5d4bca272e9c8cf89",
  "recorderId": "3a1c8f68f2de",
  "token": "speak-test-5b87d2c2d21e",
  "meta": {
    "backgroundImg": "https://speakai-storage.s3.amazonaws.com/backgroundImg/prod/5d03a9d5d4bca272e9c8cf89/1649768360045-blob",
    "logo": "https://speakai-storage.s3.amazonaws.com/logo/prod/5d03a9d5d4bca272e9c8cf89/1649768327203-Speak---Rectange-Logo---Black---5000px-Wide.png",
    "primaryColor": "#000000",
    "type": {
      "audio": true,
      "video": true,
      "screenShare": true,
      "upload": {
        "file": true,
        "multiple": false,
        "text": true
      }
    },
    "client": {
      "name": true,
      "email": true,
      "questions": []
    }
  },
  "createdAt": "2023-03-13T17:23:36.374Z",
  "updatedAt": "2023-03-13T17:23:36.374Z",
  "__v": 0
},
"recorderId": "3a1c8f68f2de",
"token": "speak-test-5b87d2c2d21e"
  }
}
```

</div>

</ResponsePanel>

</div>

<h2 id="post-recorder-questions-recorder-id">Update Recorder Questions</h2>

**Update a recorder questions:**

`questions` - Speak offer different set of questions to create and ask to your clients.

Here're the few examples with value:

1. Single Line - "single"
2. Multi Line - "multiple"
3. Checkbox\* - "checkbox"
4. Radio Button\* - "radiobutton"
5. Dropdown\* - "dropdownlist"
6. Date - "date"
7. Date & Time - "datetime"

Checkbox, Radio Button, Dropdown offers "Include Others" option.

Checkbox Sample:

``` json
{
"question":"My Checkbox question",
"isRequired":true,
"answerType":"checkbox",
"options":["Option A","Option B"],
"includeOther":false
}

```

Dropdown Sample with Include Other:

``` json
{
  "question": "My Dropdown Question with Include Others",
  "isRequired": true,
  "answerType": "dropdownlist",
  "options": [
"Value 1",
"Value 2"
  ],
  "includeOther": true
}

```

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `recorderId` | path | string | Yes |  |

### Request body

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.

| Field | Type |
| --- | --- |
| `question` | string |
| `isRequired` | boolean |
| `answerType` | string |
| `options` | any[] |
| `includeOther` | boolean |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X POST 'https://api.speakai.co/v1/recorder/questions/null' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{
  "question": "My First Sample Question",
  "isRequired": true,
  "answerType": "single",
  "options": [],
  "includeOther": false
}'
```

</CodePanel>

<ResponsePanel id="post-recorder-questions-recorder-id" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `data` | object |
| `data.message` | string |
| `data.recorderId` | string |

Example response, `application/json`.

```json
{
  "status": "success",
  "data": {
"message": "recorder-9 updated is successfully updated",
"recorderId": "70ea4d569736"
  }
}
```

</div>

</ResponsePanel>

</div>

<h2 id="get-recorder-recordings-recorder-id">Recording Details</h2>

Get Recording meta details such as:

*   Name
*   Email
*   Other asked questions

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `recorderId` | path | string | Yes |  |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X GET 'https://api.speakai.co/v1/recorder/recordings/RECORDER_ID' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
```

</CodePanel>

<ResponsePanel id="get-recorder-recordings-recorder-id" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `data` | object |
| `data.totalCount` | integer |
| `data.recordings` | object[] |

Deeper nested fields are not listed. See the example response below for the full shape.

Example response (Recording Details), `application/json`. Arrays are shortened to one entry and long strings are cut.

```json
{
  "status": "success",
  "data": {
"totalCount": 3,
"recordings": [
  {
    "_id": "66bd022e507d6766980287eb",
    "recorderId": "66798b454a53154b90d40077",
    "mediaId": {
      "_id": "66bd022e507d6766980287e9",
      "folderId": "f89a9eac1b62",
      "name": "Wed Aug 14 2024 15:14:54 GMT-0400 (Eastern Daylight Time)",
      "description": "Client's recording for Recorder Mon Jun 24 2024",
      "tags": [
        "Recorder Mon Jun 24 2024"
      ],
      "state": "processed",
      "duration": {
        "inSecond": 15,
        "end": "00:00:15.504",
        "start": "00:00:00.080"
      },
      "mediaId": "dc49faf822df",
      "createdAt": "2024-08-14T19:14:54.194Z",
      "publishedUrl": "media/5d03a9d5d4bca272e9c8cf89/audio/1723662893381-recorder_mon_jun_24_2024.mp3"
    },
    "client": {
      "name": "",
      "email": "",
      "questions": [
        {
          "id": "41db9890bab9",
          "question": "test question",
          "answer": "test 3",
          "answerType": "single"
        }
      ]
    },
    "isDeleted": false,
    "meta": {
      "isScreenShare": false,
      "microphoneMuted": false,
      "microphoneReadyState": "live",
      "microphoneName": "Default - MacBook Pro Microphone (Built-in)",
      "microphoneNumber": 5,
      "cameraMuted": false,
      "cameraReadyState": "live",
      "cameraName": "",
      "cameraNumber": 1
    },
    "createdAt": "2024-08-14T19:14:54.586Z",
    "updatedAt": "2024-08-14T19:14:54.586Z",
    "__v": 0
  }
]
  }
}
```

</div>

</ResponsePanel>

</div>

<h2 id="put-recorder-settings-recorder-id">Update Recorder Settings</h2>

**Update a recorder details.**

`name` - Name of the recorder

All the other fields are optional. Your recorder will be updated automatically.

---

**Duration of the recorder:**

- `minDuration` - 15 seconds (min) & 5 min (max)
    - Pass the duration in **seconds**
- `maxDuration` - 10 seconds (min) & 3 hours (max)
    - Pass the duration in seconds

---

**Source Language:**

- You can pass the `sourceLanguage` as a code.
- Other language codes available at the top of the page.

---

**Recorder options:**

- We allow to support creating recorder with the multiple options such as:
    - `audio` - Audio recorder
    - `video` - Video recorder
    - `screeShare` - Allow to screen share on browser (Mobile not supported)
    - `uploadFile` - Allow to upload various file formats
        - `allowMultiple` - Supporting multiple file uploads

---

**Notifications:**

`upload` - Recieve an email notification when anyone uploads a recording on the recorder

`client` - When your user submits a recording (have the email address in a form) - they will receive an submittion email

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `recorderId` | path | string | Yes |  |

### Request body

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.

| Field | Type |
| --- | --- |
| `name` | string |
| `description` | string |
| `folderId` | string |
| `sourceLanguage` | string |
| `duration` | object |
| `duration.minDuration` | integer |
| `duration.maxDuration` | integer |
| `options` | object |
| `options.audio` | boolean |
| `options.video` | boolean |
| `options.screenShare` | boolean |
| `options.upload` | object |
| `notification` | object |
| `notification.upload` | boolean |
| `notification.client` | boolean |

Deeper nested fields are not listed. See the example response below for the full shape.

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X PUT 'https://api.speakai.co/v1/recorder/settings/null' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "recorder-9",
  "description": "recorder-9 description",
  "folderId": "0648e533f72c",
  "sourceLanguage": "en-US",
  "duration": {
"minDuration": 120,
"maxDuration": 300
  },
  "options": {
"audio": true,
"video": true,
"screenShare": true,
"upload": {
  "file": false,
  "text": true,
  "multiple": true,
  "url": false
}
  },
  "notification": {
"upload": true,
"client": false
  }
}'
```

</CodePanel>

<ResponsePanel id="put-recorder-settings-recorder-id" statuses={[{"code":"200","description":"OK"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `data` | object |
| `data.message` | string |
| `data.recorderId` | string |

Example response, `application/json`.

```json
{
  "status": "success",
  "data": {
"message": "recorder-9 updated is successfully updated",
"recorderId": "70ea4d569736"
  }
}
```

</div>

</ResponsePanel>

</div>

<h2 id="get-recorder-status-token">Check Recorder Status</h2>

Reveals whether recorder is publically open or password-protected

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `token` | path | string | Yes |  |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X GET 'https://api.speakai.co/v1/recorder/status/recorder-9' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
```

</CodePanel>

<ResponsePanel id="get-recorder-status-token" statuses={[{"code":"404","description":"Not Found"}]}>

<div slot="status-404">

**`404` Not Found**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `requestId` | string |
| `code` | integer |
| `message` | string |
| `hints` | string[] |

Example response, `application/json`.

```json
{
  "status": "failed",
  "requestId": "eb3e08b0-3d91-47e1-81bc-8432f76be977",
  "code": 404,
  "message": "Recorder not found!",
  "hints": [
"The requested operation failed because a resource associated with the request could not be found."
  ]
}
```

</div>

</ResponsePanel>

</div>

<h2 id="get-recorder-url-recorder-id">Generate Recorder URL</h2>

#### API Endpoint: Get Recorder URL

**Method:** `GET`  
**Endpoint:** `https://api.speakai.co/v1/recorder/url/{recorderId}`

##### Description

This endpoint retrieves the URL associated with a specific recorder identified by `recorderId`. It is used to obtain the necessary information to access the recorder's iframe and page details.

##### Parameters

- **recorderId** (path parameter): The unique identifier for the recorder whose URL is being requested.

##### Response Format

The response will be in JSON format and includes the following fields:

- **status**: A string indicating the status of the request.

- **data**: An object containing:

- **iframe**: A string representing the iframe URL for the recorder.

- **page**: A string representing the page URL for the recorder.

##### Example Response

``` json
{
  "status": "",
  "data": {
"iframe": "",
"page": ""
  }
}

```

### Parameters

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `recorderId` | path | string | Yes |  |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X GET 'https://api.speakai.co/v1/recorder/url/RECORDER_ID' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000'
```

</CodePanel>

<ResponsePanel id="get-recorder-url-recorder-id" statuses={[{"code":"200","description":"OK"},{"code":"404","description":"Not Found"}]}>

<div slot="status-200">

**`200` OK**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `data` | object |
| `data.iframe` | string |
| `data.page` | string |

Example response, `application/json`.

```json
{
  "status": "success",
  "data": {
"iframe": "<iframe style=\"height: 800px !important; width: 960px !important;\" src=\"https://recorder.speakai.co/iframe/recorder-9-4fb7713e267a\" frameborder=\"0\" scrolling=\"no\"></iframe>",
"page": "https://recorder.speakai.co/recorder-9-4fb7713e267a"
  }
}
```

</div>

<div slot="status-404">

**`404` Not Found**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `requestId` | string |
| `code` | integer |
| `message` | string |
| `hints` | string[] |

Example response, `application/json`.

```json
{
  "status": "failed",
  "requestId": "1babfc3a-9f8f-4c22-83c8-0367cb2b7cb1",
  "code": 404,
  "message": "Recorder Id not found!",
  "hints": [
"The requested operation failed because a resource associated with the request could not be found."
  ]
}
```

</div>

</ResponsePanel>

</div>

<h2 id="post-recorder-verify">Verify Password</h2>

User to grant\prohobit access to a password-protected recorder

### Request body

Field types and names come from the request body the spec records. The spec does not mark request body fields as required, so read this as the shape the endpoint accepts rather than a required field list.

| Field | Type |
| --- | --- |
| `token` | string |
| `password` | string |

<div slot="code">

<CodePanel label="Example request">

```bash
curl -X POST 'https://api.speakai.co/v1/recorder/verify' \
  -H 'x-speakai-key: sk_test_speak_0000000000000000' \
  -H 'x-access-token: eyJhbGciOiJIUzI1NiJ9.test-access-token.0000000000' \
  -H 'Content-Type: application/json' \
  -d '{
  "token": "token",
  "password": "123"
}'
```

</CodePanel>

<ResponsePanel id="post-recorder-verify" statuses={[{"code":"404","description":"Not Found"}]}>

<div slot="status-404">

**`404` Not Found**

Response body, `application/json`.

| Field | Type |
| --- | --- |
| `status` | string |
| `requestId` | string |
| `code` | integer |
| `message` | string |
| `hints` | string[] |

Example response, `application/json`.

```json
{
  "status": "failed",
  "requestId": "32732927-3809-4973-a82b-82663013d36f",
  "code": 404,
  "message": "Recorder not found!",
  "hints": [
"The requested operation failed because a resource associated with the request could not be found."
  ]
}
```

</div>

</ResponsePanel>

</div>

## Related pages

- [API reference](/api/) for the base URL, authentication, and the error format.
- [Authenticate with the Speak AI API using access tokens](/api/authentication/)
- [Upload audio and video to Speak AI and read insights](/api/media/)
- [Create and update live transcription sessions in Speak AI](/api/live-transcription/)
- [Analyze text notes with the Speak AI text endpoints](/api/text/)

Get an API key on the [Speak AI developer page](https://app.speakai.co/developers?utm_source=docs&utm_medium=referral&utm_campaign=api-reference&utm_content=api-recorders).

Source: https://docs.speakai.co/api/recorders/index.mdx