{ "openapi": "3.0.3", "info": { "title": "Speak AI API", "version": "v1", "description": "Welcome to the Speak Ai API.\n\n_Documentation is a work in progress and subject to change._\n\n# Requirements\n\nThe Speak Ai API is made available to all paying subscribers. With the API you can programmatically upload your media files for insights extraction, transcription, download the resulting insights and transcript in various formats and create an embed iframe and a page.\n\n# API Key\n\nIf you are subscribed to Speak Ai (paid subscription), you can access your API key in your Speak account and going to the [developer page](https://app.speakai.co/developer).\n\n## Base URL and Versioning\n\nThe base URL for the API is `https://api.speakai.co/[version]`. The current version is **v1**, so the base URL for the current API version is `https://api.speakai.co/v1`.\n\n# Supported Languages\n\nSpeak Ai supports 100+ languages for transcription and analysis.\n\nFor the full list of supported languages, see: [What languages do you support?](https://docs.speakai.co/help/transcription/languages/)\n\n---\n\n# MCP (Model Context Protocol) Integration\n\nSpeak Ai provides an MCP server that enables AI models and agents to interact with the Speak Ai API programmatically.\n\n**GitHub Repository:** [https://github.com/speakai/speakai-mcp](https://github.com/speakai/speakai-mcp)\n\n## MCP Server URL\n\nUse the following Streamable HTTP endpoint to connect to the Speak Ai MCP server:\n\n```\nhttps://api.speakai.co/v1/mcp\n\n ```\n\n## NPX Package\n\nYou can run the Speak Ai MCP server locally using the `speakai-mcp` npm package via npx:\n\n``` bash\nnpx speakai-mcp\n\n ```\n\nOr install it globally:\n\n``` bash\nnpm install -g speakai-mcp\n\n ```\n\n## CLI Usage\n\nAfter installation, you can use the CLI to start the MCP server locally:\n\n``` bash\nspeakai-mcp --api-key YOUR_API_KEY\n\n ```\n\n---\n\n# Security & Privacy\n\nFor information about Speak Ai's security practices and privacy policies, visit our [Security & Privacy documentation](https://docs.speakai.co/help/security/).\n\n---\n\n# Support\n\nIf you have any questions, please write to us at [accounts@speakai.co](mailto:accounts@speakai.co). We'd love to hear from you!\n\n---\n\n# How this specification is maintained\n\nThis specification is hand-maintained in the speak-docs repository at `openapi/speak-api.json`. It is the source of truth for the Speak AI API reference and it is no longer exported from the Speak AI Postman collection.\n\nPaths, parameters, and response shapes are verified against the Speak AI API server source before they are added. To correct the reference, edit this file and re-run `node scripts/generate-api-docs.mjs`.", "contact": { "name": "Speak AI support", "email": "accounts@speakai.co" } }, "servers": [ { "url": "https://api.speakai.co/v1", "description": "Speak AI API v1" } ], "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ], "tags": [ { "name": "Authentication", "description": "All Speak AI API operations require two headers:\n\n`x-speakai-key: your_speak_ai_api_key_here`\n\n`x-access-token: generated_access_token`\n\n---\n\n### Authentication Flow\n\n1. **Get Access Token**: Call `POST /v1/auth/accessToken` with your `x-speakai-key` and `Content-Type: application/json` headers. The request body should be `{}` (empty JSON) when using API key authentication.\nOn success, the response returns your `accessToken` and `refreshToken` inside the `data` object.\n\n2. **Use Access Token**: Include the access token in the `x-access-token` header for all subsequent API calls, alongside your `x-speakai-key`.\n\n3. **Refresh Token**: When the access token expires, call `POST /v1/auth/refreshToken` with both `x-speakai-key` and `x-access-token` headers (include the expired access token), and pass `{\"refreshToken\": \"...\"}` in the request body. You will receive a new `accessToken` and `refreshToken` pair.\n\n**Example Response**\n\n```json\n{\n \"data\": {\n \"email\": \"you@example.com\",\n \"accessToken\": \"eyJhbG...\",\n \"refreshToken\": \"eyJhbG...\"\n }\n}\n```\n\n---\n\n### Token Expiry\n\n| Token | Expiry | Action on Expiry |\n|---|---|---|\n| Access Token | 80 minutes | Call Refresh Token endpoint |\n| Refresh Token | 24 hours | Re-authenticate via Get Access Token |\n\n---\n\n### Rate Limits\n\nBoth `/v1/auth/accessToken` and `/v1/auth/refreshToken` are limited to **5 requests per 60 seconds**. Exceeding this returns `429 Too Many Requests`.\n\n---\n\n### Error Handling\n\n- **Expired Access Token**: Returns `401 Unauthorized`. Use the Refresh Token endpoint to obtain a new token pair.\n- **Expired Refresh Token**: Returns an error response. Re-authenticate from scratch via the Get Access Token endpoint.\n- **Rate Limited**: Returns `429`. Wait and retry \u2014 implement exponential backoff for automated clients." }, { "name": "Media (Audio/Video)", "description": "This media collection of endpoints enables operation of list, insights, transcript and export.\n\n## Uploading audio or video\n\nWhen uploading a file, a media file URL (accessible to our servers) must be provided.\n\nThis can be a publicly accessible URL hosted by yourselves or a third-party. \n\nYou can upload files directly to our storage (AWS S3 bucket) and upload the file using the returned URL.\n\n### Step 2, PUT the file to the presigned URL\n\nThis step targets the storage host returned in `preSignedUrl`, not `api.speakai.co`, so it is described here rather than as a Speak AI endpoint.\n\n### PUT Request to Upload Audio File\n\nThis endpoint allows you to upload an audio file (in this case, an MP3 file) to an Amazon S3 bucket. The request is made using the HTTP PUT method, which is commonly used for updating resources.\n\n#### Request URL\n\n```\nhttps://xs3.amazonaws.com/video/1622234682034-medianame.mp3?AWSAccessKeyId=x&Content-Type=audio/mp3&Expires=1622245482&Signature=nQWU4yxBuUjQJD1yTr92qblQx6s=&x-amz-acl=public-read\n\n ```\n\n#### Query Parameters\n\n- `AWSAccessKeyId`: Your AWS access key ID, used for authentication.\n \n- `Content-Type`: Specifies the media type of the resource being uploaded (in this case, `audio/mp3`).\n \n- `Expires`: A timestamp indicating when the URL will expire.\n \n- `Signature`: A signature for authentication, ensuring the request is valid.\n \n- `x-amz-acl`: Sets the access control list (ACL) for the uploaded file. Here, it is set to `public-read`, allowing public access to the file.\n \n\n#### Request Body\n\nThe request does not specify a body type, indicating that the audio file is uploaded directly to the specified URL.\n\n#### Expected Response\n\nThe response from a successful upload typically includes:\n\n- A confirmation of the upload status (e.g., HTTP status code 200 OK).\n \n- Metadata about the uploaded file, such as its URL and size.\n \n\nEnsure that the audio file being uploaded adheres to the specified content type and that all required parameters are included in the request." }, { "name": "Text", "description": "Text notes are operable as well, complete listing of media can be requested, insight to particular analyzed media, analytics on top of our analysis, and of course, you can delete your note !\n\nAttention:\n`id` is the required parameter here instead of `mediaId` as in Media functionalities\n\nRe-analyzing a text note runs through `GET /media/reanalyze/{mediaId}`, which covers text notes and uploaded files alike. It is documented on the [Media](/api/media/) page." }, { "name": "Exports", "description": "Export collection enables export of media (audio, video + text) details: transcript, analytics and insights." }, { "name": "Folder", "description": "Manage Folder workflow. Create, Update, Delete folders." }, { "name": "Recorder/Survey", "description": "Suvery endpoints serve the purpose of operating an surveys: listing the files, getting info, creating\\\\updating\\\\deleting a recorder, generating embeddable URL for it.\n\nEmbeddable supports checking it's status,uploading of the recordings directly and verification of password to access the recorder as a user." }, { "name": "Media Embed", "description": "Embed Individual Media Player or the Folder (as repository) to make the insights, transcription and insights publicly visible or share with others." }, { "name": "AI Chat", "description": "Fetch all your Speak AI Chat Responses." }, { "name": "Meeting Assistant Events", "description": "Manage Meeting Assistant Events.\n\nFetch all your scheduled, complete or pending meeting assistant events." }, { "name": "Fields", "description": "Manage Fields." }, { "name": "Labels", "description": "Labels mark passages of a transcript, such as an objection on a sales call or a quote for a report. Your company keeps one list of labels, with one level of groups, and anyone with the **Labels: Assign** permission can put them on any transcript they can open.\n\n### Permissions\n\nAdmins set these per person in Team management. Owners pass every check. Reading labels needs no permission.\n\n| Permission | Allows | Admin default | Member default |\n| --- | --- | --- | --- |\n| Labels: Create | Create labels and groups, add Speak label sets | Yes | Yes |\n| Labels: Update | Rename, recolour, describe, regroup, reorder; merge with Delete | Yes | Yes |\n| Labels: Delete | Archive and restore; merge with Update | Yes | No |\n| Labels: Assign | Apply, change and remove labels on transcripts | Yes | Yes |\n\nA missing permission returns `403` with `{\"status\": \"failed\", \"message\": \"You do not have permission to perform this action\"}`.\n\n### Transcript revisions\n\nEvery saved change to a transcript increases the media's `transcriptRevision`. Passages are addressed by word position on a given revision, so labelling and commenting send `expectedTranscriptRevision` and get 409 when it is stale. When a transcript is edited, labelled passages move with their words; a passage whose words changed too much is marked `needs_review` with a suggested new position, and nothing is deleted.\n\n### Notifications\n\nEvery label change, in the library or on a transcript, is listed for the person who made it under the `label` category of [GET /v1/notification](/api/notifications/)." }, { "name": "Comments", "description": "Comment threads on a passage of a transcript or on the whole file, with one level of replies, resolve and reopen. Comments on passages follow their words when the transcript is edited, the same way labels do.\n\n### Permissions\n\nAdmins set these per person in Team management. Owners pass every check. Reading comments needs no permission, and you can always edit and delete your own comments.\n\n| Permission | Allows | Admin default | Member default |\n| --- | --- | --- | --- |\n| Comments: Create | Start a thread and reply | Yes | Yes |\n| Comments: Update | Resolve and reopen threads | Yes | Yes |\n| Comments: Delete | Delete other people's comments | Yes | No |\n\n### Notifications\n\nEvery comment change is listed for the person who made it under the `comment` category of [GET /v1/notification](/api/notifications/). The person who started a thread is also told when someone else replies to it, resolves it or reopens it." }, { "name": "Notifications", "description": "The in-app notifications the Speak app lists under **Notifications**: uploads and analysis, payments, team changes, and label and comment activity. Read them a page at a time with filters, and mark your own as read." }, { "name": "Dashboards", "description": "Create and update analytics dashboards, including the viewer settings that decide what a dashboard's share link shows: custom fields, the Feedback button, labels, comments, and, through the feedback submitter names, who a viewer may write as.\n\n### Labels and comments on a share link\n\n| Setting | Shape | Rule |\n| --- | --- | --- |\n| `labels` | `{ isEnabled, mode: \"view\" \\| \"apply\", labelGroupIds }` | `labelGroupIds` (at most 100) must be active label groups of your company (400 on save). Empty means every active label. |\n| `comments` | `{ isEnabled, mode: \"view\" \\| \"reply\" }` | |\n\nEach section replaces itself when sent and keeps its stored value when left out. Everything is off and read-only until you turn it on. Viewers use the [shared link](/api/shared-links/) routes." }, { "name": "Shared Links", "description": "The routes a dashboard's share link uses to read and write labels and comments on its media, and that a media or folder embed uses to read them. There is no signed-in user: the link token in `?token=` is the only credential, so these routes take no API key or access token.\n\n### Embeds\n\nMedia and folder embeds have `meta.isLabels` and `meta.isComments`, both off by default and set with `PUT /embed/{embedId}`. Embeds are read-only: the two GET routes answer an embed token only while its flag is on, for the embed's own media or media in its folders, and every write route refuses an embed token.\n\n### Refusals\n\nEvery refusal (unknown or revoked token, expired subscription, the setting off, view mode on a write, media outside the dashboard's folders, a name that is not allowed, someone else's entry) returns the same `404 {\"message\": \"Not found.\"}`, so a link holder cannot tell which check failed. Validation errors still return 400 and a stale transcript revision 409. Reads allow 120 requests a minute per IP address and writes 30; past that the routes return 429.\n\n### Writing as a reviewer\n\nWrites need `labels.mode` set to `apply` or `comments.mode` set to `reply` on the dashboard, and send a `reviewerName` from `annotationSettings.reviewers`, the dashboard's feedback submitter names. When `allowOtherReviewer` is true (the dashboard's `feedback.allowOtherSubmitter` is on), a name that is not listed is also accepted. With no names listed and other names off, nobody can write. Link writes are not authenticated: the link holder chooses the name, and Speak AI records the entry under it without checking who sent it, the same as feedback. Only the dashboard's feedback names are accepted, plus any other name when other names are allowed. Speak AI accepts this by design. Every entry is shown as made via the dashboard under the chosen name, a name can change or delete only the entries written under it from that dashboard, and revoking the link stops everything at once. Link responses carry the author's display name only. Linking a comment to a passage, moving passages and resolving threads stay in the app." }, { "name": "Automations", "description": "Best way to automate your workflow with Automations." }, { "name": "Admin", "description": "Manage your team." }, { "name": "Webhook", "description": "Receive Webhooks from Speak to your platform. Manage webhook workflows and select events." }, { "name": "Live Transcription", "description": "Live transcription turns a running audio or video session into a transcript while the session is still going. The three REST endpoints below open the session, feed it, and close it.\n\nA session runs in three steps. Create the media record with `POST /live-transcription/create`, mint a handshake token with `POST /live-transcription/token`, then send transcribed words to `POST /live-transcription/update/{mediaId}` as they arrive.\n\nWhen the session ends, send the finished recording to the same update endpoint. Speak Ai transcodes it and runs the full analysis, so a live session ends up with the same transcript, speakers, and insights as an uploaded file.\n\nThe audio itself streams over a separate WebSocket connection that the handshake token authorizes. That connection is not part of the REST API and its host is not documented here.\n\n### Supported languages\n\nPass one of these codes as `sourceLanguage` when you create the session.\n\n| value | name |\n| --- | --- |\n| en-US | English (US) |\n| en-AU | English (Australia) |\n| en-GB | English (British) |\n| en-IN | English (Indian) |\n| en-IE | English (Irish) |\n| en-NZ | English (New Zealand) |\n| en-AB | English (Scottish) |\n| en-ZA | English (South African) |\n| en-ES | English + Spanish (Multiple) |\n| fr-FR | French |\n| fr-CA | French (Canada) |\n| es-ES | Spanish |\n| es-MX | Spanish (Mexico) |\n| bg-BG | Bulgarian |\n| ca-ES | Catalan |\n| zh-CN | Chinese (Simplified) |\n| zh-TW | Chinese (Traditional) |\n| zh-HK | Chinese (Cantonese, Traditional) |\n| cs-CZ | Czech |\n| da-DK | Danish |\n| nl-NL | Dutch |\n| et-EE | Estonian |\n| nl-BE | Flemish |\n| fi-FI | Finnish |\n| de-CH | German (Swiss) |\n| de-DE | German |\n| el-GR | Greek |\n| hi-IN | Hindi |\n| hi-Latn | Hindi (Latin) |\n| hu-HU | Hungarian |\n| id-ID | Indonesian |\n| it-IT | Italian |\n| ja-JP | Japanese |\n| ko-KR | Korean |\n| lt-LT | Lithuanian |\n| lv-LV | Latvian |\n| ms-MY | Malay |\n| nb-NO | Norwegian |\n| pl-PL | Polish |\n| pt-BR | Portuguese (Brazilian) |\n| pt-PT | Portuguese (Portugal) |\n| ro-RO | Romanian |\n| ru-RU | Russian |\n| sk-SK | Slovak |\n| sv-SE | Swedish |\n| taq | Tamasheq |\n| th-TH | Thai |\n| tr-TR | Turkish |\n| uk-UA | Ukrainian |\n| vi-VN | Vietnamese |" }, { "name": "Voice Agents", "description": "Create and manage voice agents. Mutations (create/update/delete) require the OWNER or ADMIN role." }, { "name": "Voice Agent Avatars", "description": "The avatar catalog voice agents attach for video calls: the shared system catalog plus your company's own uploads. Mutations require the OWNER or ADMIN role and only ever apply to your company's own uploads, never the shared catalog." }, { "name": "Voice Agent Testing", "description": "Scripted test scenarios and run history for a voice agent. The run lifecycle (queue/pause/resume/cancel) is live; the execution engine that actually drives a simulated conversation is not wired up yet, so a run stays queued until that lands." } ], "paths": { "/auth/accessToken": { "post": { "tags": [ "Authentication" ], "summary": "Get Access Token", "operationId": "authentication-get-access-token", "description": "This endpoint allows you to obtain an access token by providing the necessary authentication credentials.\n\nThe request body for this endpoint should include the your authentication credentials. Upon successful authentication, the server will respond with a status of \"success\" and provide the your email, access token, and refresh token in the response data.\n\n**Request rules.** The request body is entirely optional: you can post an empty JSON object. Authentication comes from your API key in the x-speakai-key request header, not from the body, and a missing or invalid key returns 401. A deactivated account returns 200 with a deactivated status rather than tokens. This endpoint is rate limited to 5 requests per minute per IP address.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "deviceType": { "type": "string", "description": "Labels the kind of client requesting the token so the resulting session is identified correctly in your login history. Leave it out and the session is labeled as an API session. Send zapier when you want a plain token pair with no session recorded; in that case the refresh token you get back cannot be exchanged later, so request a new access token instead of refreshing. Any value outside the accepted list is rejected when the session is saved, and you still get a working access token but no session record and no usable refresh token. Optional string. Defaults to api when you omit it or send an empty value. Only web, android, ios, zapier, api and desktop are stored successfully.", "enum": [ "web", "android", "ios", "zapier", "api", "desktop" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "email": { "type": "string" }, "accessToken": { "type": "string" }, "refreshToken": { "type": "string" } } } } }, "examples": { "get-access-token": { "summary": "Get Access Token", "value": { "status": "success", "data": { "email": "your_email_id", "accessToken": "access_token", "refreshToken": "refresh_token" } } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "requestId": { "type": "string" }, "code": { "type": "integer" }, "message": { "type": "string" }, "hints": { "type": "array", "items": { "type": "string" } } } }, "examples": { "get-access-token-failure-no-value-found-for-speak-ai-key": { "summary": "Get Access Token - Failure (No value found for Speak Ai Key)", "value": { "status": "failed", "requestId": "ca665625-645e-438a-867d-366a6e3f133a", "code": 401, "message": "The authorization api key provided for the request is invalid.", "hints": [ "The authorization api key provided for the request is invalid." ] } }, "get-access-token-failure-invalid-api-key": { "summary": "Get Access Token - Failure - Invalid API Key", "value": { "status": "failed", "requestId": "358bc130-e798-41c2-9864-2cd2ce9b766d", "code": 401, "message": "The authorization api key provided for the request is invalid.", "hints": [ "The authorization api key provided for the request is invalid." ] } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/auth/refreshToken": { "post": { "tags": [ "Authentication" ], "summary": "Refresh Token", "operationId": "authentication-refresh-token", "description": "This endpoint is used to refresh the access token by providing the refresh token in the request body.\n\nThe refreshToken expires in 24 hour.\n\n### Request Body\n\n- refreshToken (string, required): The refresh token used to obtain a new access token.\n\n\n### Response\n\n- status (string): Indicates the status of the request, where \"success\" means the request was successful.\n- data (object): Contains the new access token and refresh token.\n - accessToken (string): The new access token.\n - refreshToken (string): The new refresh token.\n\n**Request rules.** You must send refreshToken in the body unless the request already carries Speak's refresh token session cookie, which only browser clients signed in through Speak's own web apps have. The server reads the body value first and falls back to that cookie, so an API integration that omits the field always gets a 404. This endpoint is rate limited to 5 requests per minute per IP address.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "refreshToken": { "type": "string", "description": "The refresh token you received the last time you signed in or requested a token. Send it here to get back a new access token and a new refresh token. Refresh tokens are single use: once you exchange one, the old value stops working, so store the new one from the response and use that next time. Replaying an already used refresh token ends the whole session and forces a fresh sign in. A missing token, or one that does not match an active session, returns 404. A token that is expired, tampered with, or otherwise not valid returns 401. Must be a string. An empty value or a value that is not a string is treated as missing and returns 404. Sending a non-string value also cancels the cookie fallback, so send either a real token string or no field at all. Required for API callers, since the only alternative the server accepts is a browser session cookie." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "accessToken": { "type": "string" }, "refreshToken": { "type": "string" } } } } }, "examples": { "refresh-token": { "summary": "Refresh Token", "value": { "status": "success", "data": { "accessToken": "new_access_token", "refreshToken": "new_refresh_token" } } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "requestId": { "type": "string" }, "code": { "type": "integer" }, "message": { "type": "string" } } }, "examples": { "refresh-token-failure-invalid-expired-token": { "summary": "Refresh Token - Failure - Invalid / Expired Token", "value": { "status": "failed", "requestId": "3fcf7e0c-a977-4c37-bae5-a72485206cd0", "code": 404, "message": "We were unable to find a valid token. Your token may have expired or invalid. Please contact development team." } } } } } } }, "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ] } }, "/media/upload/signedurl": { "get": { "tags": [ "Media (Audio/Video)" ], "summary": "Get a Signed Url", "operationId": "media-audio-video-get-a-signed-url", "description": "If you have a locally saved file and you want to upload it to our system using API, you'll have to follow through 3 simple steps:\n\n### Process\n\n1. Run this endpoint to retrieve an upload link for a placeholder on our storage bucket. You'll have `preSignedUrl.`\n\n2. This `preSignedUrl` is your ticket to which you `PUT` your local file using `curl` or any other HTTP client.\n\n3. Use \"[Upload your file with the Signed Url or External URL](https://docs.speakai.co/#c6106a66-6a3d-4b05-b4a2-4a68a4c1e95d)\" to upload your file on Speak.\n\n### How does this work?\n\nYou can find more information about uploading a file using signed URLs [here](https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html).\nIf you still find this unenlightening, shoot a message to us on success@speakai.co!\n\n### Expiry\n\nThe link will expire in 2 hours.", "x-speak-group": "Audio or Video Upload", "parameters": [ { "name": "mediaType", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "audio", "video" ] }, "description": "The kind of file you are uploading. It decides the storage prefix, so it has to match the real file: a video signed as audio is stored as audio and can never be analysed as video. Required. The prefix is chosen before any bytes exist, so the server cannot work it out for you: omit it and the request is rejected. Nothing is read from the extension on filename.", "example": "audio" }, { "name": "filename", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Filename with the extension is required", "example": "media_name.mp3" }, { "name": "mimeType", "in": "query", "required": false, "schema": { "type": "string" }, "description": "For example audio/mpeg, audio/mp4, audio/wav or video/mp4", "example": "audio/mpeg" } ], "responses": { "200": { "description": "Success", "content": { "text/plain": { "schema": { "type": "string" }, "examples": { "get-a-signed-url-audio": { "summary": "Get a Signed Url (Audio)", "value": "" }, "get-a-signed-url-video": { "summary": "Get a Signed Url (Video)", "value": "" } } } } } } } }, "/media/upload": { "post": { "tags": [ "Media (Audio/Video)" ], "summary": "Upload your file with the Signed Url or External URL", "operationId": "media-audio-video-upload-your-file-with-the-signed-url-or-external-url", "description": "If you want to add a hosted media (you must have a valid `URL`) to your media library, do it here.\n\n### Parameters\n\nPlease must specify `mediaType` as `audio` or `video`\n\n```\nname: String required\ndescription: string;\nurl: string required; // public URL or AWS signed URL\nmediaType: 'audio'; // 'video'\nuserId: \"\"; // for enterprise users only (optional)\nmedicalId: \"\" // custom media Id or medical Id for your reference (optional)\ncreatedAt: \"2021-08-09T00:13:11.717Z\" // must match the date format (optional)\ntags: \"comma separated strings\",\nfolderId: \"folder Id\" // to save in the folder\nfields: { id: string, value: string } = []; (Optional)\n\n ```\n\n### Webhook Callback URL:\n\n- If you created a webhook for media events and want to receive a callback to a specific URL for this text note, you can assign `callbackUrl` - `string` in a `req.body`.\n\n- Speak will consider the `callbackUrl` and will skip the callbackUrl created via [Webhook API](https://docs.speakai.co/#5777a89c-a6c3-4d0e-aab1-d33fdec5cbe8).\n\n\n**Fields:**\n\nYou can pass the **id and value** in the Fields array to include related to your media files.\n\n**Upload Considerations:**\n\n- Maximum duration limit of 3 hours for a media URL.\n\n- The URL needs to be accessible publicly. For Example - Google Drive, Dropbox are not supported.\n\n- Valid YouTube URL examples are: `https://www.youtube.com/watch?v=pTJ-yvNWCUE`.\n\n- **Supported File Formats are**:\n\n - Audio - `mp3 (recommended), m4a, wav, ogg, webm, m4p`\n\n - Video - `mp4 (recommended), m4v, wmv, avi, mov, flv`", "x-speak-group": "Audio or Video Upload", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The title you want the uploaded file to have in Speak. Required. Trimmed. No maximum length and no pattern." }, "description": { "type": "string", "description": "A short description stored alongside the file. Optional. Trimmed. An empty string is allowed. The schema declares a default of an empty string, but the validation middleware discards the schema defaults, so an omitted value simply stays unset." }, "url": { "type": "string", "description": "The link Speak fetches the file from. YouTube, Google Drive, Amazon S3 and the social platforms the resolver supports (TikTok, Instagram, X, Facebook, Reddit, SoundCloud, Twitch, Dailymotion, Streamable, Snapchat, Pinterest, Tumblr, Bilibili, VK, OK.ru and Rutube) are all handled. Vimeo and Loom page links are not resolved here: import Vimeo through the connected Vimeo integration instead. Required. Plain string with no uri format check, so the server does not reject a malformed link at validation time." }, "mediaType": { "type": "string", "description": "The kind of file you are uploading, and the field that decides how it is stored and what can be run on it later. Send it whenever you know which you want, including for a page link: asking for audio on a YouTube link imports the audio track only. Leave it out when you do not know, and the server works it out from better evidence than you have: it inspects the file for a direct URL, and for a page link the resolver returns the best track the platform offers, which can still be audio when no video rendition fits the size limit. Either way the stored type follows what was actually fetched. It has no default, so leaving it out is a real choice rather than a value invented on your behalf, and the only fallback is audio when nothing else can be determined. Do not send a value guessed from the file extension. A value you send is kept, which means it stops the server inspecting the file, and a video stored as audio can never be analysed as video afterwards. Lowercased before validation, so uppercase values such as VIDEO are accepted. 'all' is a filter value that leaked into this schema: it validates but is not a real upload type.", "enum": [ "audio", "video", "text", "media", "csv", "all" ] }, "sourceLanguage": { "type": "string", "description": "The language spoken in the file, given as a transcription language code such as en-US. Optional. Any string passes, because the validator substitutes rather than rejects. An unrecognized code becomes auto. The schema declares a default of 'en-US', but that default is discarded by the middleware, so if you omit it the server uses the source language on your account onboarding and falls back to auto. Defined." }, "callbackUrl": { "type": "string", "description": "A URL you want Speak to call when the file finishes processing. Optional. Trimmed. An empty string is allowed. Stored on the media as webhookMetaData.callbackUrl. No uri format check." }, "tags": { "type": "string", "description": "Tags to attach to the file, as a single comma separated string. Optional. Declared as a union, the schema) and allows null and an empty string, so an array also passes validation. The controller only reads a string and splits it on commas, so an array is accepted and then ignored." }, "createdAt": { "type": "string", "description": "The creation timestamp to store on the file instead of the time of upload. Optional. An empty string is allowed. Parsed with new Date, so send an ISO 8601 string." }, "isTranscriptionOnly": { "type": "boolean", "description": "Not used by this endpoint. Nothing in the upload flow reads it. Optional. Declared with a default of false, but that default is discarded and the value is never destructured or read by the controller.", "deprecated": true }, "folderId": { "type": "string", "description": "The folder you want the file to land in. If no folder with that id exists on your account, the server puts the file in your first folder. Optional. An empty string is allowed." }, "fields": { "type": "array", "items": { "type": "object" }, "description": "Custom field values to attach to the file. Each entry pairs the id of a field you created in Speak with the value you want stored. Optional. An unconstrained array, so validation does not check the item shape and does not cap the length. The controller expects objects with id and value, checks each id against your account fields, and silently drops the ones that do not match (checkForValidFields ends with.filter(Boolean))." } }, "required": [ "name", "url" ] }, "example": { "name": "Vatsal Test 1", "description": "Vatsal Description", "url": "https://kns.im/msgs/files/32dc84df-9650-4c17-b633-e80a5097ba6f.ogg", "mediaType": "video", "sourceLanguage": "he-IL", "tags": "your custom tags1, tag 2, tag 3", "fields": [ { "id": "FIELD_ID_CREATED_BY_SPEAK", "value": "YOUR_VALUE" } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "mediaId": { "type": "string" }, "state": { "type": "string" } } } } }, "examples": { "success": { "summary": "success", "value": { "status": "success", "data": { "mediaId": "86a36b59b38e", "state": "uploaded" } } } } } } } } } }, "/media": { "get": { "tags": [ "Media (Audio/Video)" ], "summary": "List", "operationId": "media-audio-video-list", "description": "If you are looking for a paginated, sorted and filtered listing of your media library.\n\n- You can pass `userId` in `params` to get data for a user. (Only for enterprise use cases)", "parameters": [ { "name": "mediaType", "in": "query", "required": false, "schema": { "type": "string" }, "description": "audio, video, text", "example": "audio" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Default `1`st page", "example": "1" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Default `50`", "example": "50" }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Default Created At in Descending order\n\nSort by: Created At, positive, neutral, negative\n\n`asc` or `desc`", "example": "createdAt:desc" }, { "name": "filterMedia", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "0 -- Uploaded\n1 -- Assigned Media to a User\n2 -- Uploaded OR Assigned\n\nDefault: `0`", "example": "0" }, { "name": "filterName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search from media name, keywords, labels, faces, brands, people, locations and transcription." }, { "name": "folderId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pass folderId to fetch only those records", "example": "568sd56899" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "totalCount": { "type": "integer" }, "pages": { "type": "integer" }, "mediaList": { "type": "array", "items": { "type": "object", "properties": { "duration": { "type": "object", "properties": { "inSecond": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" } } }, "privacyMode": { "type": "string" }, "processingProgress": { "type": "string" }, "state": { "type": "string" }, "remark": { "type": "string" }, "_id": { "type": "string" }, "sentiment": { "type": "array", "items": {} }, "mediaId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "thumbnailUrl": { "type": "string", "description": "A signed link to the video's thumbnail, custom or automatic. Present only when the file has one. It expires, so do not store it." } } } } } } } }, "examples": { "success": { "summary": "success", "value": { "status": "success", "data": { "totalCount": 71, "pages": 71, "mediaList": [ { "duration": { "inSecond": "60", "start": "0:00:00", "end": "0:01:00.182" }, "privacyMode": "Public", "processingProgress": "100", "state": "processed", "remark": "", "_id": "5f46c87668ee9913005e5bef", "sentiment": [], "mediaId": "50ek03r4kebud105", "name": "vatsal-30", "description": "url-test", "createdAt": "2020-08-26T20:39:18.870Z" } ] } } } } } } } }, "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ] } }, "/media/insight/{mediaId}": { "get": { "tags": [ "Media (Audio/Video)" ], "summary": "Insights", "operationId": "media-audio-video-insights", "description": "Load the results of analysis (sentiment, transcription, named entities, etc) for your media object here.\n\n- You can pass `userId` in `params` to get specifically for any user.", "parameters": [ { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "5a4690abf255" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "insight": { "type": "object", "properties": { "isAnalyze": { "type": "boolean" }, "transcript": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "text": { "type": "string" }, "confidence": { "type": "number" }, "speakerId": { "type": "integer" }, "language": { "type": "string" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "adjustedStart": { "type": "string" }, "adjustedEnd": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" } } } } } } }, "faces": { "type": "array", "items": {} }, "keywords": { "type": "array", "items": { "type": "object", "properties": { "isDeleted": { "type": "boolean" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "adjustedStart": { "type": "string" }, "adjustedEnd": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" } } } }, "id": { "type": "integer" }, "name": { "type": "string" } } } }, "labels": { "type": "array", "items": {} }, "brands": { "type": "array", "items": {} }, "topics": { "type": "array", "items": { "type": "object", "properties": { "isDeleted": { "type": "boolean" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "adjustedStart": { "type": "string" }, "adjustedEnd": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" } } } }, "id": { "type": "integer" }, "name": { "type": "string" } } } }, "people": { "type": "array", "items": {} }, "locations": { "type": "array", "items": {} }, "arts": { "type": "array", "items": {} }, "dates": { "type": "array", "items": {} }, "events": { "type": "array", "items": {} }, "geopolitical": { "type": "array", "items": {} }, "languages": { "type": "array", "items": {} }, "laws": { "type": "array", "items": {} }, "money": { "type": "array", "items": {} }, "ordinals": { "type": "array", "items": {} }, "percentages": { "type": "array", "items": {} }, "quantities": { "type": "array", "items": {} }, "times": { "type": "array", "items": {} }, "cardinals": { "type": "array", "items": {} }, "nationalities": { "type": "array", "items": {} }, "products": { "type": "array", "items": {} } } }, "duration": { "type": "object", "properties": { "inSecond": { "type": "string" }, "end": { "type": "string" }, "start": { "type": "string" } } }, "summary": { "type": "object", "properties": { "original": { "type": "object", "properties": { "text": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } } }, "tags": { "type": "array", "items": {} }, "translationSource": { "type": "object", "description": "Present only on a file Speak AI created by translating another one. It says whether the original source-language transcript can be read, so a client can offer the control without fetching the transcript. Fetch the transcript itself from GET /media/transcript/{mediaId}/source, which documents every reason value.", "properties": { "available": { "type": "boolean" }, "reason": { "type": "string", "description": "Why the original cannot be read. Present only when available is false." }, "sourceMediaId": { "type": "string" }, "sourceLanguage": { "type": "string" }, "mediaType": { "type": "string" } } }, "isTranscriptionOnly": { "type": "boolean" }, "processingProgress": { "type": "string" }, "state": { "type": "string" }, "remark": { "type": "string" }, "sentiment": { "type": "array", "items": { "type": "object", "properties": { "document": { "type": "object", "properties": { "Negative": { "type": "integer" }, "Neutral": { "type": "integer" }, "Positive": { "type": "integer" } } }, "sentences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "instances": { "type": "array", "items": {} }, "score": { "type": "object", "properties": { "compound": { "type": "integer" }, "neg": { "type": "integer" }, "neu": { "type": "integer" }, "pos": { "type": "integer" } } }, "text": { "type": "string" } } } } } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "description": { "type": "string" }, "publishedUrl": { "type": "string" }, "mediaId": { "type": "string" }, "originalCreatedAt": { "type": "string", "format": "date-time" }, "faceSpriteImg": { "type": "string" }, "transcriptRevision": { "type": "integer", "description": "Revision of the transcript. Starts at 0 and increases by one on every saved change to the transcript. Send it back as `expectedTranscriptRevision` when you save the transcript, label a passage or comment on one." }, "thumbnail": { "type": "object", "description": "The video's thumbnail. An empty object when the file has none, which includes every audio file and text note. Use it to follow a frame asked for with PUT /media/{mediaId}/thumbnail: pending is true while the frame is being made, and error is set when it failed, while url still shows the previous thumbnail.", "properties": { "url": { "type": "string", "description": "A signed link to the current thumbnail. Present only when the file has one. It expires, so do not store it." }, "source": { "type": "string", "enum": [ "auto", "custom" ], "description": "`auto` for the thumbnail Speak AI made, `custom` for one you set. Present only when the file has a thumbnail." }, "pending": { "type": "boolean", "description": "Present and true while a requested frame is still being made." }, "error": { "type": "string", "description": "Why the last requested frame was not saved, for example \"The frame took too long. Try again.\" Present only when it failed." } } } } } } }, "examples": { "success": { "summary": "success", "value": { "status": "success", "data": { "insight": { "isAnalyze": true, "transcript": [ { "id": 1, "text": "Both. Hello hello good how are you?", "confidence": 0.8278, "speakerId": 1, "language": "en-US", "instances": [ { "adjustedStart": "0:00:00", "adjustedEnd": "0:00:05.92", "start": "0:00:00", "end": "0:00:05.92" } ] } ], "faces": [], "keywords": [ { "isDeleted": false, "instances": [ { "adjustedStart": "0:00:08.44", "adjustedEnd": "0:00:13.84", "start": "0:00:08.44", "end": "0:00:13.84" } ], "id": 1, "name": "company" } ], "labels": [], "brands": [], "topics": [ { "isDeleted": false, "instances": [ { "adjustedStart": "0:00:00", "adjustedEnd": "0:00:47.744", "start": "0:00:00", "end": "0:00:47.744" } ], "id": 1, "name": "Promotions" } ], "people": [], "locations": [], "arts": [], "dates": [], "events": [], "geopolitical": [], "languages": [], "laws": [], "money": [], "ordinals": [], "percentages": [], "quantities": [], "times": [], "cardinals": [], "nationalities": [], "products": [] }, "duration": { "inSecond": "47", "end": "0:00:47.744", "start": "0:00:00" }, "summary": { "original": { "text": "", "createdAt": "2020-09-04T16:16:19.118Z" } }, "tags": [], "isTranscriptionOnly": false, "processingProgress": "100", "state": "processed", "remark": "", "sentiment": [ { "document": { "Negative": 0, "Neutral": 0, "Positive": 0 }, "sentences": [ { "id": 1, "instances": [], "score": { "compound": 0, "neg": 0, "neu": 1, "pos": 0 }, "text": "Sentence 1" } ] } ], "createdAt": "2020-08-22T23:05:57.000Z", "updatedAt": "2020-08-22T23:11:11.288Z", "name": "REc557e3c8f2ac42a828973c39f1d6be37", "description": "", "publishedUrl": "media/5d03a9d5d4bca272e9c8cf89/audio/1598137553998-rec557e3c8f2ac42a828973c39f1d6be37.mp3", "mediaId": "81c226f66705", "originalCreatedAt": "2020-11-08T16:40:10.706Z", "faceSpriteImg": "", "transcriptRevision": 3 } }, "x-abridged": true }, "insights-notuploaded": { "summary": "Insights - notUploaded", "value": { "status": 200, "state": "notUploaded", "message": { "insight": { "isAnalyze": false, "faces": [], "keywords": [], "sentiments": [], "emotions": [], "labels": [], "brands": [], "topics": [], "transcript": [], "speakers": [] }, "duration": { "inSecond": "0" }, "createdAt": "2019-09-25T14:32:19.000Z", "_id": "5d8b7a730838363d90a17e86", "videoId": "QHw2hPhk9-R7rrlPKBZk-FBY9P8rDBV", "name": "ForBiggerBlazes - Copy", "description": "", "privacyMode": "Public", "size": "0", "processingProgress": "0", "state": "notUploaded", "publishedUrl": "video/5cc37a170eb2173efcfc1f7d/1569421938203-ForBiggerBlazesCopymp4.mp4", "videoFormat": 1, "sourceLanguage": "en-US", "order": 0, "__v": 0 } } } } } } } }, "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ] } }, "/media/transcript/{mediaId}": { "get": { "tags": [ "Media (Audio/Video)" ], "summary": "Transcript", "operationId": "media-audio-video-transcript", "parameters": [ { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "b4994aa1267c" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "folderId": { "type": "string" }, "mediaType": { "type": "string" }, "name": { "type": "string" }, "sourceLanguage": { "type": "string" }, "insight": { "type": "object", "properties": { "transcript": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "text": { "type": "string" }, "speakerId": { "type": "string" }, "confidence": { "type": "integer" }, "language": { "type": "string" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "startInSec": { "type": "number" }, "endInSec": { "type": "number" } } } }, "entities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "confidence": { "type": "number" }, "speakerId": { "type": "string" }, "language": { "type": "string" }, "instances": { "type": "object", "properties": { "startInSec": { "type": "number" }, "endInSec": { "type": "number" } } } } } } } } }, "speakers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "startInSec": { "type": "number" }, "endInSec": { "type": "number" } } } }, "totalWords": { "type": "integer" }, "duration": { "type": "integer" }, "wpm": { "type": "integer" } } } } } }, "duration": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "inSecond": { "type": "number" } } }, "createdAt": { "type": "string", "format": "date-time" }, "mediaId": { "type": "string" }, "mediaUrl": { "type": "string" }, "transcriptRevision": { "type": "integer", "description": "Revision of the transcript. Starts at 0 and increases by one on every saved change to the transcript. Send it back as `expectedTranscriptRevision` when you save the transcript, label a passage or comment on one." } } } } }, "examples": { "transcript": { "summary": "Transcript", "value": { "status": "success", "data": { "folderId": "0648e533f72c", "mediaType": "audio", "name": "vatsal", "sourceLanguage": "en-US", "insight": { "transcript": [ { "id": 0, "text": "Okay. Let's do the testing for transcription.", "speakerId": "0", "confidence": 1, "language": "en-US", "instances": [ { "start": "00:00:00.240", "end": "00:00:02.994", "startInSec": 0.24, "endInSec": 2.9940499999999997 } ], "entities": [ { "id": "1", "text": "Okay.", "confidence": 0.99782515, "speakerId": "0", "language": "en-US", "instances": { "startInSec": 0.24, "endInSec": 0.48 } } ] } ], "speakers": [ { "id": 0, "name": "0", "instances": [ { "start": "00:00:00.240", "end": "00:00:02.994", "startInSec": 0.24, "endInSec": 2.9940499999999997 } ], "totalWords": 10, "duration": 3, "wpm": 200 } ] }, "duration": { "start": "00:00:00.240", "end": "00:00:12.144", "inSecond": 12.144 }, "createdAt": "2025-10-17T17:25:57.608Z", "mediaId": "b4994aa1267c", "mediaUrl": "MEDIA_URL", "transcriptRevision": 3 } }, "x-abridged": true } } } } } }, "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ] }, "put": { "tags": [ "Media (Audio/Video)" ], "summary": "Update Transcript", "operationId": "media-audio-video-update-transcript", "description": "Replaces the transcript of a media file with the array you send. Read the transcript first with `GET /media/transcript/{mediaId}`, change what you need, and send the whole array back.\n\n#### Avoid overwriting someone else's save\n\nSend `expectedTranscriptRevision` with the `transcriptRevision` you read. If anyone saved the transcript since, the request returns 409 \"This transcript changed since you opened it. Reload to keep editing.\" and changes nothing: read the transcript again, reapply your change, and save with the new revision. Leave it out and the save always goes through, replacing whatever is there.\n\nA successful save increases the revision by one and returns the new value. Labels and comments on passages are then moved to follow their words in the background.\n\n#### Request rules\n\n- `transcript` needs at least one sentence; an empty transcript cannot be saved.\n- Sentence `id` values must be unique when you send `expectedTranscriptRevision`.\n- Keys that are not listed below return 400.\n\n#### Errors\n\n- `400` when the body fails validation.\n- `404` when your company has no media with that id.\n- `409` when `expectedTranscriptRevision` is stale.", "parameters": [ { "name": "mediaId", "in": "path", "required": true, "description": "Id of the media file.", "schema": { "type": "string" }, "example": "b4994aa1267c" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transcript": { "type": "array", "minItems": 1, "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Sentence id. Must be unique across the array when you send `expectedTranscriptRevision`." }, "speakerId": { "type": "string", "description": "Speaker id. Trimmed, required." }, "speaker": { "type": "object", "properties": { "userId": { "type": "string", "description": "Matched user id.", "nullable": true }, "name": { "type": "string", "description": "Matched name.", "nullable": true }, "email": { "type": "string", "description": "Matched email.", "nullable": true } }, "description": "The team member matched to this speaker, when there is one. Every key may be empty or `null`." }, "text": { "type": "string", "description": "Sentence text. Trimmed. An empty string is accepted." }, "confidence": { "type": "number", "description": "Sentence confidence, as returned by the transcript endpoint." }, "language": { "type": "string", "description": "Language code, as returned by the transcript endpoint." }, "score": { "type": "object", "properties": { "compound": { "type": "number" }, "neg": { "type": "number" }, "neu": { "type": "number" }, "pos": { "type": "number" } }, "required": [ "compound", "neg", "neu", "pos" ], "description": "Sentence sentiment, as returned by the transcript endpoint. Send it back so a save does not drop it." }, "instances": { "type": "array", "description": "Timing of the sentence.", "items": { "type": "object", "properties": { "start": { "type": "string", "description": "Start time as `HH:MM:SS.mmm`. Required." }, "end": { "type": "string", "description": "End time as `HH:MM:SS.mmm`. Required." }, "startInSec": { "type": "number" }, "endInSec": { "type": "number" }, "adjustedStart": { "type": "string", "description": "Adjusted start time." }, "adjustedEnd": { "type": "string", "description": "Adjusted end time." } }, "required": [ "start", "end" ] } }, "entities": { "type": "array", "items": { "type": "object" }, "description": "Word-level entries, as returned by the transcript endpoint. Not validated further." } }, "required": [ "id", "speakerId", "text", "confidence" ] }, "description": "The full transcript, as an array of sentences. At least one." }, "expectedTranscriptRevision": { "type": "integer", "description": "Optional. The `transcriptRevision` you read the transcript at. Integer, 0 or more. When it is stale the save returns 409 and nothing is written.", "minimum": 0 } }, "required": [ "transcript" ] }, "example": { "transcript": [ { "id": 0, "text": "Okay. Let's do the testing for transcription.", "speakerId": "0", "confidence": 1, "language": "en-US", "instances": [ { "start": "00:00:00.240", "end": "00:00:02.994", "startInSec": 0.24, "endInSec": 2.994 } ], "entities": [] } ], "expectedTranscriptRevision": 3 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "`success`.", "enum": [ "success" ] }, "message": { "type": "string", "description": "`Updated successfully.`" }, "data": { "type": "object", "properties": { "transcriptRevision": { "type": "integer", "description": "The transcript revision after this save." } } } } }, "examples": { "success": { "summary": "Success", "value": { "status": "success", "message": "Updated successfully.", "data": { "transcriptRevision": 4 } } } } } } }, "400": { "description": "The body failed validation", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "`failed`.", "enum": [ "failed" ] }, "requestId": { "type": "string", "description": "Id of this request, for support." }, "code": { "type": "integer", "description": "The HTTP status code again." }, "message": { "type": "string", "description": "What went wrong, in words you can show to a person." }, "hints": { "type": "array", "items": { "type": "string" }, "description": "Generic hints for this kind of error." } } }, "examples": { "error-400": { "summary": "The body failed validation", "value": { "status": "failed", "requestId": "req_0000000000000000", "code": 400, "message": "\"transcript\" must contain at least 1 items", "hints": [ "The API request is invalid or improperly formed." ] } } } } } }, "404": { "description": "No media with that id in your company", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "`failed`.", "enum": [ "failed" ] }, "requestId": { "type": "string", "description": "Id of this request, for support." }, "code": { "type": "integer", "description": "The HTTP status code again." }, "message": { "type": "string", "description": "What went wrong, in words you can show to a person." }, "hints": { "type": "array", "items": { "type": "string" }, "description": "Generic hints for this kind of error." } } }, "examples": { "error-404": { "summary": "No media with that id in your company", "value": { "status": "failed", "requestId": "req_0000000000000000", "code": 404, "message": "Media details not found", "hints": [ "The requested operation failed because a resource associated with the request could not be found." ] } } } } } }, "409": { "description": "The transcript changed since you read it", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "`failed`.", "enum": [ "failed" ] }, "requestId": { "type": "string", "description": "Id of this request, for support." }, "code": { "type": "integer", "description": "The HTTP status code again." }, "message": { "type": "string", "description": "What went wrong, in words you can show to a person." }, "hints": { "type": "array", "items": { "type": "string" }, "description": "Generic hints for this kind of error." } } }, "examples": { "error-409": { "summary": "The transcript changed since you read it", "value": { "status": "failed", "requestId": "req_0000000000000000", "code": 409, "message": "This transcript changed since you opened it. Reload to keep editing.", "hints": [ "Please use PUT for update instead of POST", "The requested operation failed because it tried to create a resource that already exists." ] } } } } } } }, "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ] } }, "/media/transcript/{mediaId}/source": { "get": { "tags": [ "Media (Audio/Video)" ], "summary": "Source transcript of a translated file", "operationId": "media-audio-video-source-transcript", "description": "Returns the transcript of the original source-language file behind a translated one, so you can read a translation against the text it came from.\n\nPass the media id of the **translated** file. Speak AI resolves the original from the translation record, either as the separate media the two-step flow keeps or, when the translation replaced the text in place, by rebuilding the original from the words the transcription engine stored.\n\nWhen the original cannot be shown, the request still answers 200. Read `data.available` first: `false` carries a `reason` and nothing else, and `true` carries the transcript. There is no 404 for an unavailable original.\n\nThe sentence shape matches `GET /media/transcript/{mediaId}`. The rebuilt in-place original omits the per-sentence `entities` array; the two-step original carries whatever the source media holds. `confidence` on every sentence is the confidence the transcription engine reported for the original, not a measure of the translation.", "parameters": [ { "name": "mediaId", "in": "path", "required": true, "description": "The id of the translated media. Sending the id of the original returns available false with reason no-link.", "schema": { "type": "string" }, "example": "b4994aa1267c" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "available": { "type": "boolean", "description": "Whether the original transcript can be shown. Everything below is present only when this is true." }, "reason": { "type": "string", "enum": [ "no-link", "original-not-retained", "source-deleted", "source-missing", "source-not-ready", "source-has-no-transcript" ], "description": "Why the original cannot be shown. Present only when available is false. no-link: this file is not a translation, or its translation has not finished. original-not-retained: a text note, whose original text the translation overwrote. source-deleted: the original media was deleted. source-missing: the original is not in your workspace, or your folder access does not reach it. source-not-ready: the original is still processing. source-has-no-transcript: the original holds no transcript to return." }, "sourceMediaId": { "type": "string", "description": "The id of the original media. On an in-place translation this is the same id you asked for, because one media holds both versions." }, "sourceLanguage": { "type": "string", "description": "The language the original was transcribed in. It can be auto on a file uploaded without a declared language." }, "mediaType": { "type": "string" }, "name": { "type": "string" }, "duration": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "inSecond": { "type": "number" } } }, "createdAt": { "type": "string", "format": "date-time" }, "insight": { "type": "object", "properties": { "transcript": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "text": { "type": "string" }, "speakerId": { "type": "string" }, "confidence": { "type": "number" }, "language": { "type": "string" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "startInSec": { "type": "number" }, "endInSec": { "type": "number" } } } } } } }, "speakers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } } } } } } }, "examples": { "available": { "summary": "The original is available", "value": { "status": "success", "data": { "available": true, "sourceMediaId": "0648e533f72c", "sourceLanguage": "en-US", "mediaType": "audio", "name": "Kickoff call", "duration": { "start": "00:00:00.000", "end": "00:00:12.480", "inSecond": 12.48 }, "createdAt": "2026-08-20T10:14:52.117Z", "insight": { "transcript": [ { "id": 0, "text": "Okay. Let's do the testing for transcription.", "speakerId": "0", "confidence": 0.98, "language": "en-US", "instances": [ { "start": "00:00:00.240", "end": "00:00:02.994", "startInSec": 0.24, "endInSec": 2.994 } ] } ], "speakers": [ { "id": 0, "name": "Speaker 1" } ] } } } }, "unavailable": { "summary": "The original cannot be shown", "value": { "status": "success", "data": { "available": false, "reason": "source-not-ready" } } } } } } } }, "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ] } }, "/media/speakers/{mediaId}": { "put": { "tags": [ "Media (Audio/Video)" ], "summary": "Update Transcript Speakers", "operationId": "media-audio-video-update-transcript-speakers", "description": "### Request Description\n\nThis API endpoint allows you to update speaker names in the transcription of a media object.\n\n#### Endpoint\n\n`PUT /v1/media/speakers/:mediaId`\n\n#### Method\n\n`PUT`\n\n#### Purpose\n\nThe purpose of this request is to update the speaker information associated with a specific media object. This includes modifying the names of the speakers in the transcription data.\n\n#### Input Parameters\n\n- `mediaId` (path parameter): The unique identifier for the media object whose speaker information you wish to update.\n\n- **Request Body**: The request body should be a JSON array containing objects with the following structure:\n\n - **id** (string): The unique identifier for the speaker **(ORIGINAL)**.\n\n - **name** (string): The new name of the speaker.\n\n\n#### Response Structure\n\nThe response will return a JSON object containing the following fields:\n\n- **status**: Indicates the status of the request.\n\n- **message**: String\n\n\n#### Example Response\n\n``` json\n{\n \"status\": \"\",\n \"message\": \"\"\n}\n\n ```\n\n#### Notes\n\n- Ensure that the `mediaId` provided in the URL corresponds to an existing media object.\n\n- The request body must be formatted as a JSON array, even if updating a single speaker.\n\n- The response will confirm the status of the update operation, along with any relevant data about the media analysis.\n\n**Request rules.** The body is an array, one entry per speaker you are relabelling, and every entry needs `id` and `name`. Omit `segmentIds` to relabel every segment for that speaker, or pass them to limit the rename to one paragraph. Pass `mergeIntoId` to merge this speaker into an existing one.", "parameters": [ { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "b4994aa1267c" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "description": "One entry per speaker you want to relabel.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The speaker you are renaming, given as either the speaker's current label or its numeric speaker id. Required on every array entry. Trimmed. The server matches the current label first and the numeric id second (resolveTargetSpeaker at, so a label wins when both could match." }, "name": { "type": "string", "description": "The new name for that speaker. Required on every array entry. Trimmed. Reusing another speaker's name returns 400 unless you also send mergeIntoId on the same entry." }, "segmentIds": { "type": "array", "items": { "type": "number" }, "description": "The transcript segment ids you want renamed. Send it to limit the change to one paragraph, and leave it out to rename every segment belonging to that speaker. Optional. Items must be numbers. No minimum or maximum item count." }, "mergeIntoId": { "type": "string", "description": "The id of the speaker you are merging this one into. Sending it confirms you meant to combine two speakers, so the duplicate name check is skipped for this entry. Optional. An empty string is allowed, and an empty string counts as not set." } }, "required": [ "id", "name" ] } }, "example": [ { "id": "0", "name": "Vatsal" } ] } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "insight": { "type": "object", "properties": { "isAnalyze": { "type": "boolean" }, "transcript": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "text": { "type": "string" }, "confidence": { "type": "number" }, "speakerId": { "type": "integer" }, "language": { "type": "string" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "adjustedStart": { "type": "string" }, "adjustedEnd": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" } } } } } } }, "faces": { "type": "array", "items": {} }, "keywords": { "type": "array", "items": { "type": "object", "properties": { "isDeleted": { "type": "boolean" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "adjustedStart": { "type": "string" }, "adjustedEnd": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" } } } }, "id": { "type": "integer" }, "name": { "type": "string" } } } }, "labels": { "type": "array", "items": {} }, "brands": { "type": "array", "items": {} }, "topics": { "type": "array", "items": { "type": "object", "properties": { "isDeleted": { "type": "boolean" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "adjustedStart": { "type": "string" }, "adjustedEnd": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" } } } }, "id": { "type": "integer" }, "name": { "type": "string" } } } }, "people": { "type": "array", "items": {} }, "locations": { "type": "array", "items": {} }, "arts": { "type": "array", "items": {} }, "dates": { "type": "array", "items": {} }, "events": { "type": "array", "items": {} }, "geopolitical": { "type": "array", "items": {} }, "languages": { "type": "array", "items": {} }, "laws": { "type": "array", "items": {} }, "money": { "type": "array", "items": {} }, "ordinals": { "type": "array", "items": {} }, "percentages": { "type": "array", "items": {} }, "quantities": { "type": "array", "items": {} }, "times": { "type": "array", "items": {} }, "cardinals": { "type": "array", "items": {} }, "nationalities": { "type": "array", "items": {} }, "products": { "type": "array", "items": {} } } }, "duration": { "type": "object", "properties": { "inSecond": { "type": "string" }, "end": { "type": "string" }, "start": { "type": "string" } } }, "summary": { "type": "object", "properties": { "original": { "type": "object", "properties": { "text": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } } } } }, "tags": { "type": "array", "items": {} }, "isTranscriptionOnly": { "type": "boolean" }, "processingProgress": { "type": "string" }, "state": { "type": "string" }, "remark": { "type": "string" }, "sentiment": { "type": "array", "items": { "type": "object", "properties": { "document": { "type": "object", "properties": { "Negative": { "type": "integer" }, "Neutral": { "type": "integer" }, "Positive": { "type": "integer" } } }, "sentences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "instances": { "type": "array", "items": {} }, "score": { "type": "object", "properties": { "compound": { "type": "integer" }, "neg": { "type": "integer" }, "neu": { "type": "integer" }, "pos": { "type": "integer" } } }, "text": { "type": "string" } } } } } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "description": { "type": "string" }, "publishedUrl": { "type": "string" }, "mediaId": { "type": "string" }, "originalCreatedAt": { "type": "string", "format": "date-time" }, "faceSpriteImg": { "type": "string" } } } } }, "examples": { "success": { "summary": "success", "value": { "status": "success", "data": { "insight": { "isAnalyze": true, "transcript": [ { "id": 1, "text": "Both. Hello hello good how are you?", "confidence": 0.8278, "speakerId": 1, "language": "en-US", "instances": [ { "adjustedStart": "0:00:00", "adjustedEnd": "0:00:05.92", "start": "0:00:00", "end": "0:00:05.92" } ] } ], "faces": [], "keywords": [ { "isDeleted": false, "instances": [ { "adjustedStart": "0:00:08.44", "adjustedEnd": "0:00:13.84", "start": "0:00:08.44", "end": "0:00:13.84" } ], "id": 1, "name": "company" } ], "labels": [], "brands": [], "topics": [ { "isDeleted": false, "instances": [ { "adjustedStart": "0:00:00", "adjustedEnd": "0:00:47.744", "start": "0:00:00", "end": "0:00:47.744" } ], "id": 1, "name": "Promotions" } ], "people": [], "locations": [], "arts": [], "dates": [], "events": [], "geopolitical": [], "languages": [], "laws": [], "money": [], "ordinals": [], "percentages": [], "quantities": [], "times": [], "cardinals": [], "nationalities": [], "products": [] }, "duration": { "inSecond": "47", "end": "0:00:47.744", "start": "0:00:00" }, "summary": { "original": { "text": "", "createdAt": "2020-09-04T16:16:19.118Z" } }, "tags": [], "isTranscriptionOnly": false, "processingProgress": "100", "state": "processed", "remark": "", "sentiment": [ { "document": { "Negative": 0, "Neutral": 0, "Positive": 0 }, "sentences": [ { "id": 1, "instances": [], "score": { "compound": 0, "neg": 0, "neu": 1, "pos": 0 }, "text": "Sentence 1" } ] } ], "createdAt": "2020-08-22T23:05:57.000Z", "updatedAt": "2020-08-22T23:11:11.288Z", "name": "REc557e3c8f2ac42a828973c39f1d6be37", "description": "", "publishedUrl": "media/5d03a9d5d4bca272e9c8cf89/audio/1598137553998-rec557e3c8f2ac42a828973c39f1d6be37.mp3", "mediaId": "81c226f66705", "originalCreatedAt": "2020-11-08T16:40:10.706Z", "faceSpriteImg": "" } }, "x-abridged": true } } } } } }, "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ] } }, "/media/status/{mediaId}": { "get": { "tags": [ "Media (Audio/Video)" ], "summary": "Status", "operationId": "media-audio-video-status", "description": "If you need a list or a quick preview of a media you can request meta-data about media objects with this endpoint, this will include all information except for results of analysis, transcripts, etc.", "parameters": [ { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "duration": { "type": "object", "properties": { "inSecond": { "type": "string" }, "end": { "type": "string" }, "start": { "type": "string" } } }, "tags": { "type": "array", "items": {} }, "processingProgress": { "type": "string" }, "state": { "type": "string" }, "remark": { "type": "string" }, "_id": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "description": { "type": "string" }, "publishedUrl": { "type": "string" }, "mediaId": { "type": "string" }, "originalCreatedAt": { "type": "string", "format": "date-time" }, "thumbnail": { "type": "object", "description": "The video's thumbnail. An empty object when the file has none, which includes every audio file and text note. Use it to follow a frame asked for with PUT /media/{mediaId}/thumbnail: pending is true while the frame is being made, and error is set when it failed, while url still shows the previous thumbnail.", "properties": { "url": { "type": "string", "description": "A signed link to the current thumbnail. Present only when the file has one. It expires, so do not store it." }, "source": { "type": "string", "enum": [ "auto", "custom" ], "description": "`auto` for the thumbnail Speak AI made, `custom` for one you set. Present only when the file has a thumbnail." }, "pending": { "type": "boolean", "description": "Present and true while a requested frame is still being made." }, "error": { "type": "string", "description": "Why the last requested frame was not saved, for example \"The frame took too long. Try again.\" Present only when it failed." } } } } } } }, "examples": { "success": { "summary": "success", "value": { "status": "success", "data": { "duration": { "inSecond": "47", "end": "0:00:47.744", "start": "0:00:00" }, "tags": [], "processingProgress": "100", "state": "processed", "remark": "", "_id": "5f41a4d5c35d8d0fd556e075", "createdAt": "2020-08-22T23:05:57.000Z", "updatedAt": "2020-08-22T23:11:11.288Z", "name": "REc557e3c8f2ac42a828973c39f1d6be37", "description": "", "publishedUrl": "media/5d03a9d5d4bca272e9c8cf89/audio/1598137553998-rec557e3c8f2ac42a828973c39f1d6be37.mp3", "mediaId": "81c226f66705", "originalCreatedAt": "2020-11-08T16:40:10.706Z" } } }, "insights-notuploaded": { "summary": "Insights - notUploaded", "value": { "status": 200, "state": "notUploaded", "message": { "insight": { "isAnalyze": false, "faces": [], "keywords": [], "sentiments": [], "emotions": [], "labels": [], "brands": [], "topics": [], "transcript": [], "speakers": [] }, "duration": { "inSecond": "0" }, "createdAt": "2019-09-25T14:32:19.000Z", "_id": "5d8b7a730838363d90a17e86", "videoId": "QHw2hPhk9-R7rrlPKBZk-FBY9P8rDBV", "name": "ForBiggerBlazes - Copy", "description": "", "privacyMode": "Public", "size": "0", "processingProgress": "0", "state": "notUploaded", "publishedUrl": "video/5cc37a170eb2173efcfc1f7d/1569421938203-ForBiggerBlazesCopymp4.mp4", "videoFormat": 1, "sourceLanguage": "en-US", "order": 0, "__v": 0 } } } } } } } } } }, "/media/reanalyze/{mediaId}": { "get": { "tags": [ "Media (Audio/Video)" ], "summary": "Re-analyze a media file or text note", "operationId": "media-reanalyze", "description": "Run the Speak Ai analysis again over a record that has already been processed, and replace the insights it produced the first time.\n\nOne route covers both kinds of record. Pass the `mediaId` of an uploaded audio or video file, or the `mediaId` of a text note, and Speak Ai re-analyzes whichever record the id belongs to.\n\n### What the call does\n\nThe record moves into the `preparingAnalysis` state and the analysis runs in the background, so the response comes back before the new insights exist. Poll `GET /media/status/{mediaId}` to follow it, or subscribe to the `media.reanalyzed` and `text.reanalyzed` webhook events.\n\nThe query parameters select which parts of the analysis run again. Omit all of them to re-run the default analysis.", "parameters": [ { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Id of the media file or text note to re-analyze.", "example": "3f8d1ec6ca39" }, { "name": "isInsights", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Re-run insight extraction.", "example": "true" }, { "name": "isSentiment", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Re-run sentiment analysis.", "example": "true" }, { "name": "isFillerWords", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Re-run filler word detection.", "example": "true" }, { "name": "isEmbeddings", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Rebuild the embeddings used by AI chat.", "example": "true" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "reanalyze": { "summary": "Re-analysis started", "value": { "status": "success", "message": "Leon Wednesday Meeting re-analyzed successfully!" } }, "reanalyze-failed-media": { "summary": "Record already in the failed state", "value": { "status": "success", "message": "Media analysis failed. Please contact support if you need assistance." } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "requestId": { "type": "string" }, "code": { "type": "integer" }, "message": { "type": "string" }, "hints": { "type": "array", "items": { "type": "string" } } } }, "examples": { "internal-server-error": { "summary": "Internal server error", "value": { "status": "failed", "requestId": "ca665625-645e-438a-867d-366a6e3f133a", "code": 500, "message": "Something went wrong. Please try again later.", "hints": [ "Something went wrong. Please try again later." ] } } } } } } } } }, "/media/{mediaId}": { "put": { "tags": [ "Media (Audio/Video)" ], "summary": "Update meta-data", "operationId": "media-audio-video-update-meta-data", "description": "If you want to rename, edit description or add a tag to your media, you can do it here.", "parameters": [ { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "createdAt": { "type": "string", "description": "The creation date to store on the file. Optional. An empty string is allowed, but the controller only writes the value when it is truthy, so an empty string does not clear the existing date." }, "description": { "type": "string", "description": "A short description for the file. Optional. Trimmed. An empty string is allowed by validation, but the controller only writes a non empty value, so you cannot clear the description this way." }, "folderId": { "type": "string", "description": "The id of the folder you want to move the file into. Optional. An empty string is allowed but is treated as no change." }, "mediaId": { "type": "string", "description": "Ignored. The server takes the media id from the path, not from the body. Optional. An empty string is allowed. Accepted by validation and never destructured by the controller.", "deprecated": true }, "manageBy": { "type": "string", "description": "The id of the user you want the file assigned to. Optional. An empty string is allowed but is treated as no change. Stored as a reference to a user record (media model: Schema.Types.ObjectId, ref 'User')." }, "name": { "type": "string", "description": "The new title for the file. Required. Minimum length 1. This is the only property the controller always writes, so every update overwrites the title." }, "remark": { "type": "string", "description": "A note stored with the file. Optional. An empty string is allowed but is treated as no change." }, "status": { "type": "string", "description": "The workflow status of the file. Optional and unconstrained by the schema, so any string passes validation. The media model recognizes '', pending, progress, completed and pendingPayment, and the update runs through findOneAndUpdate without runValidators, so the model enum is not enforced on this path. Only written when not empty." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "The full list of tags for the file. The list you send replaces the existing one. Optional. Items are strings and empty strings are allowed. There is no cap on the number of items. Only written when the property is present, and an empty array is truthy so it does clear the tags." } }, "required": [ "name" ] }, "example": { "name": "update-1", "description": "description-1", "tags": [ "work", "personal" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "update-media-data-success": { "summary": "Update Media data - success", "value": { "status": "success", "message": "Updated successfully." } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "requestId": { "type": "string" }, "code": { "type": "integer" }, "message": { "type": "string" }, "hints": { "type": "array", "items": { "type": "string" } } } }, "examples": { "update-media-data-failure": { "summary": "Update Media data - failure", "value": { "status": "failed", "requestId": "7ed88c1e-e1ee-44b0-afa5-50041d2b2309", "code": 404, "message": "Media does not exist!", "hints": [ "The requested operation failed because a resource associated with the request could not be found." ] } } } } } } } }, "delete": { "tags": [ "Media (Audio/Video)" ], "summary": "Delete File", "operationId": "media-audio-video-delete-file", "description": "If you want to remove media from your library - you can do it here.\n\nWe can revert the changes if you send us a request.", "parameters": [ { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "text/plain": { "schema": { "type": "string" }, "examples": { "delete": { "summary": "Delete", "value": "" } } } } } } } }, "/media/{mediaId}/thumbnail": { "put": { "tags": [ "Media (Audio/Video)" ], "summary": "Set a custom thumbnail", "operationId": "media-audio-video-set-thumbnail", "description": "Replace a video's thumbnail with your own image or with a frame from the video. Send exactly one of:\n\n- an image file as multipart form data in the `image` field, for example `-F 'image=@cover.png'`\n- JSON `{ \"url\": \"https://...\" }`, a public https link to an image, which the server downloads\n- JSON `{ \"seekSec\": 12.5 }`, to use the video frame at that many seconds from the start\n\nThe image must be JPEG, PNG or WebP and at most 10 MB. The server checks the file's content, not its name or declared type, so a GIF is refused. A `url` must be https and point to a public address, every redirect included. The server follows up to 3 redirects and gives up after 8 seconds.\n\nA frame request answers `202` straight away and the frame is saved in the background. A `seekSec` past the end of the video uses the frame one second before the end. To follow it, poll `GET /media/status/{mediaId}` and read `data.thumbnail`: `pending` is true while the frame is being made, `error` says why it failed, and once it is saved `url` points to the new frame and `source` is `custom`. While a frame request for the video is still running, another one returns `409`. A request that has not finished after 5 minutes no longer blocks a new one.\n\nEach change replaces the current thumbnail and deletes the previous custom image. There is no way back to the automatic thumbnail. Only a video can have a thumbnail, and a frame cannot be taken from an archived video. You need permission to edit media.\n\n#### Errors\n\n- `400` when the request does not carry exactly one of `image`, `url` and `seekSec`: \"Send exactly one of an image file, an https url or seekSec.\"\n- `400` when `url` is not https or `seekSec` is below 0, with the validation message.\n- `400` when the media is not a video: \"Only a video can have a thumbnail.\"\n- `400` when the image is not a JPEG, PNG or WebP file: \"Use one JPEG, PNG or WebP image of up to 10 MB.\"\n- `400` when the link is blocked or cannot be downloaded: \"That image url could not be downloaded.\"\n- `400` when a frame is asked of an archived video, or of one whose file Speak does not hold: \"A frame cannot be taken from this video.\"\n- `400` when the frame service refuses the request: \"That frame could not be taken.\"\n- `403` when you do not have permission to edit media.\n- `404` when the media does not exist.\n- `409` when a frame is already being taken for this video.\n- `413` when the image is larger than 10 MB: \"Use one JPEG, PNG or WebP image of up to 10 MB.\"\n- `503` when the frame service is busy: \"Thumbnails are busy right now. Try again in a minute.\"", "parameters": [ { "name": "mediaId", "in": "path", "required": true, "description": "Id of the video.", "schema": { "type": "string" }, "example": "b4994aa1267c" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "A public https link to a JPEG, PNG or WebP image of up to 10 MB. The server downloads it. Send this or `seekSec`, not both." }, "seekSec": { "type": "number", "minimum": 0, "description": "Use the video frame at this many seconds from the start. A value past the end uses the frame one second before the end. Send this or `url`, not both." } } }, "example": { "url": "https://example.com/images/cover.png" } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "image": { "type": "string", "format": "binary", "description": "The image file: JPEG, PNG or WebP, up to 10 MB." } }, "required": [ "image" ] } } } }, "responses": { "200": { "description": "The image is saved as the thumbnail", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "`success` on every 2xx response.", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "thumbnail": { "type": "object", "properties": { "url": { "type": "string", "description": "A signed link to the new thumbnail. It expires, so do not store it." }, "source": { "type": "string", "enum": [ "custom" ], "description": "`custom` for a thumbnail you set." } } } } } } }, "example": { "status": "success", "data": { "thumbnail": { "url": "https://media.example.com/media/abc123/thumbnail/b4994aa1267c-1a2b3c4d5e6f7a8b.png?Expires=1767225600&Signature=abc", "source": "custom" } } } } } }, "202": { "description": "The frame request is accepted and runs in the background", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "`success` on every 2xx response.", "enum": [ "success" ] }, "data": { "type": "object", "properties": { "thumbnail": { "type": "object", "properties": { "pending": { "type": "boolean", "enum": [ true ], "description": "Always `true`. The frame is still being taken." } } } } } } }, "example": { "status": "success", "data": { "thumbnail": { "pending": true } } } } } }, "400": { "description": "Not exactly one of image, url and seekSec, an unsupported image, a link that cannot be downloaded, or a frame that cannot be taken", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "`failed`.", "enum": [ "failed" ] }, "requestId": { "type": "string", "description": "Id of this request, for support." }, "code": { "type": "integer", "description": "The HTTP status code again." }, "message": { "type": "string", "description": "What went wrong, in words you can show to a person." }, "hints": { "type": "array", "items": { "type": "string" }, "description": "Generic hints for this kind of error." } } }, "example": { "status": "failed", "code": 400, "message": "Send exactly one of an image file, an https url or seekSec." } } } }, "403": { "description": "You do not have permission to edit media", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "`failed`.", "enum": [ "failed" ] }, "message": { "type": "string", "description": "What went wrong." } } }, "example": { "status": "failed", "message": "You do not have permission to perform this action" } } } }, "404": { "description": "The media does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "`failed`.", "enum": [ "failed" ] }, "requestId": { "type": "string", "description": "Id of this request, for support." }, "code": { "type": "integer", "description": "The HTTP status code again." }, "message": { "type": "string", "description": "What went wrong, in words you can show to a person." }, "hints": { "type": "array", "items": { "type": "string" }, "description": "Generic hints for this kind of error." } } }, "example": { "status": "failed", "code": 404, "message": "Media details not found" } } } }, "409": { "description": "A frame is already being taken for this video", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "`failed`.", "enum": [ "failed" ] }, "requestId": { "type": "string", "description": "Id of this request, for support." }, "code": { "type": "integer", "description": "The HTTP status code again." }, "message": { "type": "string", "description": "What went wrong, in words you can show to a person." }, "hints": { "type": "array", "items": { "type": "string" }, "description": "Generic hints for this kind of error." } } }, "example": { "status": "failed", "code": 409, "message": "A frame is already being taken for this video." } } } }, "413": { "description": "The image is larger than 10 MB", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "`failed`.", "enum": [ "failed" ] }, "requestId": { "type": "string", "description": "Id of this request, for support." }, "code": { "type": "integer", "description": "The HTTP status code again." }, "message": { "type": "string", "description": "What went wrong, in words you can show to a person." }, "hints": { "type": "array", "items": { "type": "string" }, "description": "Generic hints for this kind of error." } } }, "example": { "status": "failed", "code": 413, "message": "Use one JPEG, PNG or WebP image of up to 10 MB." } } } }, "503": { "description": "The frame service is busy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "`failed`.", "enum": [ "failed" ] }, "requestId": { "type": "string", "description": "Id of this request, for support." }, "code": { "type": "integer", "description": "The HTTP status code again." }, "message": { "type": "string", "description": "What went wrong, in words you can show to a person." }, "hints": { "type": "array", "items": { "type": "string" }, "description": "Generic hints for this kind of error." } } }, "example": { "status": "failed", "code": 503, "message": "Thumbnails are busy right now. Try again in a minute." } } } } } } }, "/live-transcription/create": { "post": { "tags": [ "Live Transcription" ], "summary": "Create a live transcription session", "operationId": "live-transcription-create", "description": "Create the media record that a live transcription session writes into, and get back the `mediaId` the streaming connection needs.\n\nCall this first. The record is created in the `liveTranscript` state with its processing progress already at 100, so it appears in the folder straight away and fills with words as the session runs.\n\nEvery field in the body is optional. When `folderId` is left out, Speak Ai stores the record in the first folder on the account.\n\n### Sessions that already exist\n\nPass `meetingAssistantId` to attach the session to a scheduled meeting assistant event. When that event already has a media record, Speak Ai returns the existing `mediaId` instead of creating a second one, so the call is safe to repeat.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name for the media record. A meeting assistant event overrides this with its own title." }, "mediaType": { "type": "string", "description": "Recording MIME type, for example `audio/webm` or `video/mp4`. Speak Ai keeps the part before the slash, and stores anything it does not recognise as `audio`." }, "sourceLanguage": { "type": "string", "description": "Language code for the session. Defaults to `en-us`." }, "folderId": { "type": "string", "description": "Folder to store the record in. Defaults to the first folder on the account." }, "tag": { "type": "string", "description": "Single tag stored on the record." }, "meetingAssistantId": { "type": "string", "description": "Id of a scheduled meeting assistant event to attach the session to." }, "recorderToken": { "type": "string", "description": "Token of a recorder, when the session comes from an embedded recorder. Speak Ai then takes the folder and the source language from the recorder." } } }, "example": { "name": "Weekly customer call", "mediaType": "audio/webm", "sourceLanguage": "en-us", "folderId": "your_folder_id_here" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "mediaId": { "type": "string" }, "folderId": { "type": "string" }, "userId": { "type": "string" }, "message": { "type": "string" } } } } }, "examples": { "live-transcription-create": { "summary": "Session created", "value": { "status": "success", "data": { "mediaId": "3f8d1ec6ca39", "folderId": "your_folder_id_here", "userId": "609d7de35bde285f4c98ca63", "message": "Live transcript media created successfully" } } }, "live-transcription-create-existing": { "summary": "Meeting assistant event already had a record", "value": { "status": "success", "data": { "mediaId": "3f8d1ec6ca39", "folderId": "your_folder_id_here", "userId": "609d7de35bde285f4c98ca63", "message": "Existing live transcript media returned successfully" } } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "requestId": { "type": "string" }, "code": { "type": "integer" }, "message": { "type": "string" }, "hints": { "type": "array", "items": { "type": "string" } } } }, "examples": { "internal-server-error": { "summary": "Internal server error", "value": { "status": "failed", "requestId": "ca665625-645e-438a-867d-366a6e3f133a", "code": 500, "message": "Something went wrong. Please try again later.", "hints": [ "Something went wrong. Please try again later." ] } } } } } } } } }, "/live-transcription/update/{mediaId}": { "post": { "tags": [ "Live Transcription" ], "summary": "Update a live transcription session", "operationId": "live-transcription-update", "description": "Append transcribed words to a live transcription session, and hand Speak Ai the finished recording when the session ends.\n\nSend `words` while the session runs. Speak Ai merges them into sentences by speaker and language and appends them to the transcript already on the record.\n\nSend `aws` once, after the recording is uploaded. That moves the record into the `preparingAnalysis` state, triggers transcoding, and starts the same analysis an uploaded file gets. Include `totalDuration` with it so the duration is right when the uploaded file does not report one.\n\nBoth fields are optional and they can be sent in the same call.", "parameters": [ { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Id returned by `POST /live-transcription/create`.", "example": "3f8d1ec6ca39" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "words": { "type": "array", "description": "Words transcribed since the last call, in order.", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Position of the word in the session." }, "text": { "type": "string", "description": "The word itself." }, "confidence": { "type": "number", "description": "Recogniser confidence for the word, from 0 to 1." }, "language": { "type": "string", "description": "Language code the word was recognised in." }, "speakerId": { "type": "string", "description": "Speaker the word is attributed to." }, "instances": { "type": "object", "description": "Where the word sits in the recording.", "properties": { "startInSec": { "type": "number" }, "endInSec": { "type": "number" } } }, "email": { "type": "string", "description": "Email of the speaker, when the session knows it." }, "userId": { "type": "string", "description": "Speak Ai user id of the speaker, when the session knows it." } } } }, "aws": { "type": "object", "description": "Location of the finished recording. Send this once, at the end of the session.", "properties": { "bucket": { "type": "string" }, "key": { "type": "string" }, "location": { "type": "string" } } }, "totalDuration": { "type": "number", "description": "Length of the session in seconds, used when the uploaded file reports a duration of 0." } } }, "example": { "words": [ { "id": 1, "text": "hello", "confidence": 0.95, "language": "en", "speakerId": "speaker-1", "instances": { "startInSec": 1.2, "endInSec": 1.5 } } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "live-transcription-update": { "summary": "Words appended", "value": { "status": "success", "message": "Live transcription updated successfully" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "requestId": { "type": "string" }, "code": { "type": "integer" }, "message": { "type": "string" }, "hints": { "type": "array", "items": { "type": "string" } } } }, "examples": { "live-transcription-update-missing": { "summary": "No media record for that id", "value": { "status": "failed", "requestId": "3fcf7e0c-a977-4c37-bae5-a72485206cd0", "code": 404, "message": "Media does not exist!", "hints": [ "The requested operation failed because a resource associated with the request could not be found." ] } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "requestId": { "type": "string" }, "code": { "type": "integer" }, "message": { "type": "string" }, "hints": { "type": "array", "items": { "type": "string" } } } }, "examples": { "internal-server-error": { "summary": "Internal server error", "value": { "status": "failed", "requestId": "ca665625-645e-438a-867d-366a6e3f133a", "code": 500, "message": "Something went wrong. Please try again later.", "hints": [ "Something went wrong. Please try again later." ] } } } } } } } } }, "/live-transcription/token": { "post": { "tags": [ "Live Transcription" ], "summary": "Mint a live transcription handshake token", "operationId": "live-transcription-token", "description": "Mint the short-lived token that opens a live transcription streaming connection for the calling session.\n\nThe token is scoped to live transcription only. It is rejected anywhere else in the API, so it cannot stand in for an access token.\n\nThis endpoint takes no request body. The response carries the token and the number of seconds it stays valid for.\n\n### Rate limit\n\nThis endpoint is limited to 5 requests per 60 seconds per IP address. Going over returns `429` with a plain text body, so mint one token per session and reuse it until it expires.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "token": { "type": "string" }, "expiresIn": { "type": "string" } } } } }, "examples": { "live-transcription-token": { "summary": "Token minted", "value": { "status": "success", "data": { "token": "eyJhbGciOiJIUzI1NiJ9.test-live-token.0000000000", "expiresIn": "18000s" } } } } } } }, "429": { "description": "Too Many Requests", "content": { "text/plain": { "schema": { "type": "string" }, "examples": { "live-transcription-token-rate-limited": { "summary": "Rate limited", "value": "Too many token requests from this IP, please try again after a minute" } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "requestId": { "type": "string" }, "code": { "type": "integer" }, "message": { "type": "string" }, "hints": { "type": "array", "items": { "type": "string" } } } }, "examples": { "internal-server-error": { "summary": "Internal server error", "value": { "status": "failed", "requestId": "ca665625-645e-438a-867d-366a6e3f133a", "code": 500, "message": "Something went wrong. Please try again later.", "hints": [ "Something went wrong. Please try again later." ] } } } } } } } } }, "/text/create": { "post": { "tags": [ "Text" ], "summary": "Create Text note", "operationId": "text-create-text-note", "description": "## PARAMETERS\n\nThe difference between `rawText` and `text.`\n\n`text` (required): Text is an HTML field to display content on the editor. It helps users to identify `bold,` `italic` or any other editor functionality.\n\n**Important:** If you don't have an HTML editor in your application, you can pass normal text content.\n\n`rawText` (required): This helps Speak Ai to analyze text notes.\n\n`remark`: If you want to pass any remarks from the user to display on Speak and also in your application.\n\n``` json\nuserId: String; // optional\nfolderId: String, // optional\nname: String, // required,\ndescription: string, // optional\ntags: [], // optional\ntext: \"HTML content\", // required\nrawText: \"raw text content\", // required\nremark: \"string\", // optional\n\n ```\n\n### Webhook Callback URL:\n\n- If you created a webhook for text events and want to receive a callback to a specific URL for this text note, you can assign `callbackUrl` - `string` in a `req.body`.\n- Speak will consider the `callbackUrl` and will skip the callbackUrl created via [Webhook API](https://docs.speakai.co/#5777a89c-a6c3-4d0e-aab1-d33fdec5cbe8).\n\n---\n\n## Response\n\nYou can select from the examples attached to this API endpoint or find below:\n\n```\n{\n \"status\": \"success\",\n \"data\": {\n \"mediaId\": \"xxxxxxxxx\",\n \"folderId\": \"\"\n }\n}\n\n ```\n\n**Request rules.** Nothing in the body is unconditionally required. The body is validated, and any property not listed below is rejected with a 400, so do not send extra keys.\n\nIn practice: send name, text and rawText. If you omit name, the note is titled with the creation timestamp in YYYY-MM-DD HH:mm:ss form. If rawText is missing or empty the note is saved but never analyzed, so you get no insights, sentiment, keywords or search embeddings for it.\n\nfolderId: if you omit it or send an empty string, the note goes into the first folder belonging to the note owner, and one is created for them if they have none. The folder actually used comes back in the response.\n\ncount: if you omit it, word and character counts are calculated from rawText. If you send it, your numbers are stored as given and no counting is done.\n\ntags: only the comma separated string form is saved on this endpoint. An array passes validation and is then discarded, leaving the note with no tags.\n\nBilling: if the workspace has no text note credit left, the request still returns HTTP 200, but the body carries a failed status with code 402 and no note is created.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Names the note. Surrounding whitespace is removed. If you leave it out, Speak titles the note with the creation timestamp in YYYY-MM-DD HH:mm:ss form. String. Optional. Stored trimmed. Falls back to a generated timestamp title." }, "text": { "type": "string", "description": "Holds the display copy of the note. It can contain HTML so an editor keeps bold, italic and other formatting. If your application has no rich text editor, send the same plain content you send in rawText. This copy is stored and shown, but it is not what gets analyzed. String. Empty string allowed. Stored trimmed. Stored as an empty string if you omit it." }, "rawText": { "type": "string", "description": "Carries the plain text that Speak analyzes. This is what produces insights, sentiment, keywords and the search index for the note, so send it whenever you want the note analyzed. If it is empty, the note is saved but no analysis runs. String. Empty string allowed. Stored trimmed. Stored as an empty string if you omit it." }, "description": { "type": "string", "description": "Adds a short summary shown alongside the note. String. Empty string allowed. Stored trimmed. Defaults to an empty string." }, "tags": { "type": "string", "description": "Labels the note. Send a comma separated string such as \"sales,q3\" and Speak splits it into separate tags. A string with no comma becomes a single tag. An array passes validation on this endpoint but is not saved, so use the string form when you create a note. String or array. Only the string form is stored on create. Split on commas. An empty string leaves the note with no tags." }, "folderId": { "type": "string", "description": "Files the note in one of your folders. Leave it out or send an empty string and Speak puts the note in the first folder belonging to the owner, creating one if they have none. The folder that was used comes back in the response. String. Empty string allowed." }, "fields": { "type": "array", "items": { "type": "object" }, "description": "Sets values for the custom fields on the note. Each entry takes an id and a value. Entries whose id does not match a custom field in your workspace are dropped and the remaining ones are saved. If none of the ids match, no custom field values are saved. Array of objects shaped {id, value}. Every entry must carry an id. Value can be any JSON type. Unknown ids are silently removed." }, "count": { "type": "object", "description": "Overrides the word and character counts stored on the note. Send wordCount, characterCount and characterCountWithoutSpace. Leave it out and Speak counts them from rawText for you. Object. Keys read: wordCount, characterCount, characterCountWithoutSpace, all numbers. Any object shape is accepted, and keys you leave out are stored as empty." }, "createdAt": { "type": "string", "description": "Sets the creation date recorded on the note, so you can backdate content you are importing. Defaults to the time of the request. Date. Accepts an ISO 8601 date string or a timestamp." }, "callbackUrl": { "type": "string", "description": "Stores a webhook delivery URL on the note. Speak uses it in place of the URL configured on your webhook only for deliveries that carry the whole note record, which on this endpoint means the failure event sent if the note cannot be saved. The note created and note analyzed events from this endpoint always go to the URL configured on your webhook. String. Empty string allowed. Stored exactly as sent, without trimming. Stored as an empty string if you omit it." }, "userId": { "type": "string", "description": "Assigns the new note to another user in your workspace, using that user's 24 character id. Leave it out and the note belongs to the account making the request. The owner also decides which folder is used when you do not name one. String. Must be the 24 character id of a user. Any other value fails the save and returns a 500." }, "remark": { "type": "string", "description": "A free text remark on the note. Postman's example sends this on create, but the value is not saved at creation time. Add a remark by updating the note afterwards." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "mediaId": { "type": "string" } } } } }, "examples": { "create-text-note": { "summary": "Create Text note", "value": { "status": "success", "data": { "mediaId": "c55125c7cc32" } } } } } } } } } }, "/text/insight/{mediaId}": { "get": { "tags": [ "Text" ], "summary": "Text Insight", "operationId": "text-text-insight", "description": "You need to call this API to find the insights from your text note.\n\nPlease check an example find the return response and an object.\n\n## Response\n\n```\n{\n \"status\": \"success\",\n \"data\": {\n \"count\": {\n \"wordCount\": 0,\n \"characterCount\": 0,\n \"characterCountWithoutSpace\": 0\n },\n \"insight\": {\n \"intents\": {\n \"needs\": [\n {\n \"id\": 32,\n \"text\": \"Sentence 1\"\n }\n ],\n \"wants\": [\n {\n \"id\": 50,\n \"text\": \"Sentence 1\"\n }\n ]\n },\n \"state\": \"processed\",\n \"updatedAt\": \"2021-04-13T00:30:26.720Z\",\n \"arts\": [\n {\n \"isDeleted\": false,\n \"instances\": [\n {\n \"endChar\": 512,\n \"startChar\": 489\n }\n ],\n \"isCustom\": false,\n \"name\": \"xxxxx\",\n \"id\": 0\n },\n {\n \"isDeleted\": false,\n \"instances\": [\n {\n \"endChar\": 1397,\n \"startChar\": 1386\n }\n ],\n \"isCustom\": false,\n \"name\": \"xxxxxxx\",\n \"id\": 1\n }\n ],\n \"brands\": [\n {\n \"isDeleted\": false,\n \"instances\": [\n {\n \"endChar\": 202,\n \"startChar\": 198\n },\n {\n \"endChar\": 356,\n \"startChar\": 352\n }\n ],\n \"isCustom\": false,\n \"name\": \"xxxxx\",\n \"id\": 0\n },\n {\n \"isDeleted\": false,\n \"instances\": [\n {\n \"endChar\": 333,\n \"startChar\": 310\n }\n ],\n \"isCustom\": false,\n \"name\": \"xxxxx\",\n \"id\": 1\n },\n {\n \"isDeleted\": false,\n \"instances\": [\n {\n \"endChar\": 721,\n \"startChar\": 713\n },\n {\n \"endChar\": 3009,\n \"startChar\": 3001\n },\n {\n \"endChar\": 6074,\n \"startChar\": 6066\n },\n {\n \"endChar\": 6391,\n \"startChar\": 6383\n },\n {\n \"endChar\": 6615,\n \"startChar\": 6607\n },\n {\n \"endChar\": 6854,\n \"startChar\": 6846\n },\n {\n \"endChar\": 6914,\n \"startChar\": 6906\n }\n ],\n \"isCustom\": false,\n \"name\": \"xxxxx\",\n \"id\": 2\n }\n ],\n \"cardinals\": [\n {\n \"isDeleted\": false,\n \"instances\": [\n {\n \"endChar\": 1797,\n \"startChar\": 1794\n },\n {\n \"endChar\": 1850,\n \"startChar\": 1847\n }\n ],\n \"isCustom\": false,\n \"name\": \"xxxxx\",\n \"id\": 0\n },\n {\n \"isDeleted\": false,\n \"instances\": [\n {\n \"endChar\": 3028,\n \"startChar\": 3022\n }\n ],\n \"isCustom\": false,\n \"name\": \"xxxxx\",\n \"id\": 1\n }\n ],\n \"dates\": [\n {\n \"isDeleted\": false,\n \"instances\": [\n {\n \"endChar\": 755,\n \"startChar\": 739\n }\n ],\n \"isCustom\": false,\n \"name\": \"xxxxx\",\n \"id\": 0\n }\n ],\n \"events\": [\n {\n \"isDeleted\": false,\n \"instances\": [\n {\n \"endChar\": 755,\n \"startChar\": 739\n }\n ],\n \"isCustom\": false,\n \"name\": \"xxxxx\",\n \"id\": 0\n }\n ],\n \"facs\": [\n {\n \"isDeleted\": false,\n \"instances\": [\n {\n \"endChar\": 755,\n \"startChar\": 739\n }\n ],\n \"isCustom\": false,\n \"name\": \"xxxxx\",\n \"id\": 0\n }\n ],\n \"geopolitical\": [\n {\n \"isDeleted\": false,\n \"instances\": [\n {\n \"endChar\": 172,\n \"startChar\": 163\n }\n ],\n \"isCustom\": false,\n \"name\": \"xxxxx\",\n \"id\": 0\n }\n ],\n \"keywords\": [\n {\n \"isDeleted\": false,\n \"instances\": [\n {\n \"endChar\": 172,\n \"startChar\": 163\n }\n ],\n \"isCustom\": false,\n \"name\": \"xxxxx\",\n \"id\": 0\n }\n ],\n \"languages\": [\n {\n \"isDeleted\": false,\n \"instances\": [\n {\n \"endChar\": 172,\n \"startChar\": 163\n }\n ],\n \"isCustom\": false,\n \"name\": \"xxxxx\",\n \"id\": 0\n }\n ],\n \"laws\": [\n {\n \"isDeleted\": false,\n \"instances\": [\n {\n \"endChar\": 172,\n \"startChar\": 163\n }\n ],\n \"isCustom\": false,\n \"name\": \"xxxxx\",\n \"id\": 0\n }\n ],\n \"locations\": [\n {\n \"isDeleted\": false,\n \"instances\": [\n {\n \"endChar\": 172,\n \"startChar\": 163\n }\n ],\n \"isCustom\": false,\n \"name\": \"xxxxx\",\n \"id\": 0\n }\n ],\n \"money\": [\n {\n \"isDeleted\": false,\n \"instances\": [\n {\n \"endChar\": 172,\n \"startChar\": 163\n }\n ],\n \"isCustom\": false,\n \"name\": \"xxxxx\",\n \"id\": 0\n }\n ],\n \"nationalities\": [\n {\n \"isDeleted\": false,\n \"instances\": [\n {\n \"endChar\": 1284,\n \"startChar\": 1275\n }\n ],\n \"isCustom\": false,\n \"name\": \"Republish\",\n \"id\": 0\n }\n ],\n \"ordinals\": [\n {\n \"isDeleted\": false,\n \"instances\": [\n {\n \"endChar\": 2812,\n \"startChar\": 2807\n },\n {\n \"endChar\": 2851,\n \"startChar\": 2846\n }\n ],\n \"isCustom\": false,\n \"name\": \"xxxxx\",\n \"id\": 0\n }\n ],\n \"people\": [\n {\n \"isDeleted\": false,\n \"instances\": [\n {\n \"endChar\": 196,\n \"startChar\": 188\n },\n {\n \"endChar\": 350,\n \"startChar\": 342\n }\n ],\n \"isCustom\": false,\n \"name\": \"xxxxx\",\n \"id\": 0\n }\n ],\n \"percentages\": [\n {\n \"isDeleted\": false,\n \"instances\": [\n {\n \"endChar\": 196,\n \"startChar\": 188\n },\n {\n \"endChar\": 350,\n \"startChar\": 342\n }\n ],\n \"isCustom\": false,\n \"name\": \"xxxxx\",\n \"id\": 0\n }\n ],\n \"products\": [\n {\n \"isDeleted\": false,\n \"instances\": [\n {\n \"endChar\": 4930,\n \"startChar\": 4926\n }\n ],\n \"isCustom\": false,\n \"name\": \"xxxxx\",\n \"id\": 0\n }\n ],\n \"quantities\": [\n {\n \"isDeleted\": false,\n \"instances\": [\n {\n \"endChar\": 4930,\n \"startChar\": 4926\n }\n ],\n \"isCustom\": false,\n \"name\": \"xxxxx\",\n \"id\": 0\n }\n ],\n \"times\": [\n {\n \"isDeleted\": false,\n \"instances\": [\n {\n \"endChar\": 4930,\n \"startChar\": 4926\n }\n ],\n \"isCustom\": false,\n \"name\": \"xxxxx\",\n \"id\": 0\n }\n ],\n \"topics\": []\n },\n \"description\": \"xxxxx\",\n \"tags\": [\n \"tag1\",\n \"tag2\"\n ],\n \"text\": \"Hello, This is sample text\",\n \"rawText\": \"Hello, This is sample text\",\n \"state\": \"processed\",\n \"assignTo\": \"\",\n \"remark\": \"\",\n \"sentiment\": [\n {\n \"document\": {\n \"Negative\": 0.00000,\n \"Neutral\": 0.00000,\n \"Positive\": 0.00000\n },\n \"sentences\": [\n {\n \"id\": 1,\n \"instances\": [],\n \"score\": {\n \"compound\": 0,\n \"neg\": 0,\n \"neu\": 1,\n \"pos\": 0\n },\n \"text\": \"Sentence 1\"\n },\n {\n \"id\": 2,\n \"instances\": [],\n \"score\": {\n \"compound\": 0,\n \"neg\": 0,\n \"neu\": 1,\n \"pos\": 0\n },\n \"text\": \"Sentence 2\"\n },\n {\n \"id\": 3,\n \"instances\": [],\n \"score\": {\n \"compound\": 0.7269,\n \"neg\": 0.037,\n \"neu\": 0.809,\n \"pos\": 0.154\n },\n \"text\": \"Sentence 3\"\n }\n ]\n }\n ],\n \"createdAt\": \"2021-04-13T00:30:26.721Z\",\n \"originalCreatedAt\": \"2021-04-13T00:30:26.721Z\",\n \"name\": \"xxxxx\"\n }\n}\n\n ```", "parameters": [ { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "c1f4c82dec47" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "count": { "type": "object", "properties": { "wordCount": { "type": "integer" }, "characterCount": { "type": "integer" }, "characterCountWithoutSpace": { "type": "integer" } } }, "insight": { "type": "object", "properties": { "intents": { "type": "object", "properties": { "needs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "text": { "type": "string" } } } }, "wants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "text": { "type": "string" } } } } } }, "state": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" }, "arts": { "type": "array", "items": { "type": "object", "properties": { "isDeleted": { "type": "boolean" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "endChar": { "type": "integer" }, "startChar": { "type": "integer" } } } }, "isCustom": { "type": "boolean" }, "name": { "type": "string" }, "id": { "type": "integer" } } } }, "brands": { "type": "array", "items": { "type": "object", "properties": { "isDeleted": { "type": "boolean" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "endChar": { "type": "integer" }, "startChar": { "type": "integer" } } } }, "isCustom": { "type": "boolean" }, "name": { "type": "string" }, "id": { "type": "integer" } } } }, "cardinals": { "type": "array", "items": { "type": "object", "properties": { "isDeleted": { "type": "boolean" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "endChar": { "type": "integer" }, "startChar": { "type": "integer" } } } }, "isCustom": { "type": "boolean" }, "name": { "type": "string" }, "id": { "type": "integer" } } } }, "dates": { "type": "array", "items": { "type": "object", "properties": { "isDeleted": { "type": "boolean" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "endChar": { "type": "integer" }, "startChar": { "type": "integer" } } } }, "isCustom": { "type": "boolean" }, "name": { "type": "string" }, "id": { "type": "integer" } } } }, "events": { "type": "array", "items": { "type": "object", "properties": { "isDeleted": { "type": "boolean" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "endChar": { "type": "integer" }, "startChar": { "type": "integer" } } } }, "isCustom": { "type": "boolean" }, "name": { "type": "string" }, "id": { "type": "integer" } } } }, "facs": { "type": "array", "items": { "type": "object", "properties": { "isDeleted": { "type": "boolean" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "endChar": { "type": "integer" }, "startChar": { "type": "integer" } } } }, "isCustom": { "type": "boolean" }, "name": { "type": "string" }, "id": { "type": "integer" } } } }, "geopolitical": { "type": "array", "items": { "type": "object", "properties": { "isDeleted": { "type": "boolean" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "endChar": { "type": "integer" }, "startChar": { "type": "integer" } } } }, "isCustom": { "type": "boolean" }, "name": { "type": "string" }, "id": { "type": "integer" } } } }, "keywords": { "type": "array", "items": { "type": "object", "properties": { "isDeleted": { "type": "boolean" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "endChar": { "type": "integer" }, "startChar": { "type": "integer" } } } }, "isCustom": { "type": "boolean" }, "name": { "type": "string" }, "id": { "type": "integer" } } } }, "languages": { "type": "array", "items": { "type": "object", "properties": { "isDeleted": { "type": "boolean" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "endChar": { "type": "integer" }, "startChar": { "type": "integer" } } } }, "isCustom": { "type": "boolean" }, "name": { "type": "string" }, "id": { "type": "integer" } } } }, "laws": { "type": "array", "items": { "type": "object", "properties": { "isDeleted": { "type": "boolean" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "endChar": { "type": "integer" }, "startChar": { "type": "integer" } } } }, "isCustom": { "type": "boolean" }, "name": { "type": "string" }, "id": { "type": "integer" } } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "isDeleted": { "type": "boolean" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "endChar": { "type": "integer" }, "startChar": { "type": "integer" } } } }, "isCustom": { "type": "boolean" }, "name": { "type": "string" }, "id": { "type": "integer" } } } }, "money": { "type": "array", "items": { "type": "object", "properties": { "isDeleted": { "type": "boolean" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "endChar": { "type": "integer" }, "startChar": { "type": "integer" } } } }, "isCustom": { "type": "boolean" }, "name": { "type": "string" }, "id": { "type": "integer" } } } }, "nationalities": { "type": "array", "items": { "type": "object", "properties": { "isDeleted": { "type": "boolean" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "endChar": { "type": "integer" }, "startChar": { "type": "integer" } } } }, "isCustom": { "type": "boolean" }, "name": { "type": "string" }, "id": { "type": "integer" } } } }, "ordinals": { "type": "array", "items": { "type": "object", "properties": { "isDeleted": { "type": "boolean" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "endChar": { "type": "integer" }, "startChar": { "type": "integer" } } } }, "isCustom": { "type": "boolean" }, "name": { "type": "string" }, "id": { "type": "integer" } } } }, "people": { "type": "array", "items": { "type": "object", "properties": { "isDeleted": { "type": "boolean" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "endChar": { "type": "integer" }, "startChar": { "type": "integer" } } } }, "isCustom": { "type": "boolean" }, "name": { "type": "string" }, "id": { "type": "integer" } } } }, "percentages": { "type": "array", "items": { "type": "object", "properties": { "isDeleted": { "type": "boolean" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "endChar": { "type": "integer" }, "startChar": { "type": "integer" } } } }, "isCustom": { "type": "boolean" }, "name": { "type": "string" }, "id": { "type": "integer" } } } }, "products": { "type": "array", "items": { "type": "object", "properties": { "isDeleted": { "type": "boolean" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "endChar": { "type": "integer" }, "startChar": { "type": "integer" } } } }, "isCustom": { "type": "boolean" }, "name": { "type": "string" }, "id": { "type": "integer" } } } }, "quantities": { "type": "array", "items": { "type": "object", "properties": { "isDeleted": { "type": "boolean" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "endChar": { "type": "integer" }, "startChar": { "type": "integer" } } } }, "isCustom": { "type": "boolean" }, "name": { "type": "string" }, "id": { "type": "integer" } } } }, "times": { "type": "array", "items": { "type": "object", "properties": { "isDeleted": { "type": "boolean" }, "instances": { "type": "array", "items": { "type": "object", "properties": { "endChar": { "type": "integer" }, "startChar": { "type": "integer" } } } }, "isCustom": { "type": "boolean" }, "name": { "type": "string" }, "id": { "type": "integer" } } } }, "topics": { "type": "array", "items": {} } } }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "text": { "type": "string" }, "rawText": { "type": "string" }, "state": { "type": "string" }, "assignTo": { "type": "string" }, "remark": { "type": "string" }, "sentiment": { "type": "array", "items": { "type": "object", "properties": { "document": { "type": "object", "properties": { "Negative": { "type": "integer" }, "Neutral": { "type": "integer" }, "Positive": { "type": "integer" } } }, "sentences": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "instances": { "type": "array", "items": {} }, "score": { "type": "object", "properties": { "compound": { "type": "integer" }, "neg": { "type": "integer" }, "neu": { "type": "integer" }, "pos": { "type": "integer" } } }, "text": { "type": "string" } } } } } } }, "createdAt": { "type": "string", "format": "date-time" }, "originalCreatedAt": { "type": "string", "format": "date-time" }, "name": { "type": "string" } } } } }, "examples": { "text-insight": { "summary": "Text Insight", "value": { "status": "success", "data": { "count": { "wordCount": 0, "characterCount": 0, "characterCountWithoutSpace": 0 }, "insight": { "intents": { "needs": [ { "id": 32, "text": "Sentence 1" } ], "wants": [ { "id": 50, "text": "Sentence 1" } ] }, "state": "processed", "updatedAt": "2021-04-13T00:30:26.720Z", "arts": [ { "isDeleted": false, "instances": [ { "endChar": 512, "startChar": 489 } ], "isCustom": false, "name": "xxxxx", "id": 0 } ], "brands": [ { "isDeleted": false, "instances": [ { "endChar": 202, "startChar": 198 } ], "isCustom": false, "name": "xxxxx", "id": 0 } ], "cardinals": [ { "isDeleted": false, "instances": [ { "endChar": 1797, "startChar": 1794 } ], "isCustom": false, "name": "xxxxx", "id": 0 } ], "dates": [ { "isDeleted": false, "instances": [ { "endChar": 755, "startChar": 739 } ], "isCustom": false, "name": "xxxxx", "id": 0 } ], "events": [ { "isDeleted": false, "instances": [ { "endChar": 755, "startChar": 739 } ], "isCustom": false, "name": "xxxxx", "id": 0 } ], "facs": [ { "isDeleted": false, "instances": [ { "endChar": 755, "startChar": 739 } ], "isCustom": false, "name": "xxxxx", "id": 0 } ], "geopolitical": [ { "isDeleted": false, "instances": [ { "endChar": 172, "startChar": 163 } ], "isCustom": false, "name": "xxxxx", "id": 0 } ], "keywords": [ { "isDeleted": false, "instances": [ { "endChar": 172, "startChar": 163 } ], "isCustom": false, "name": "xxxxx", "id": 0 } ], "languages": [ { "isDeleted": false, "instances": [ { "endChar": 172, "startChar": 163 } ], "isCustom": false, "name": "xxxxx", "id": 0 } ], "laws": [ { "isDeleted": false, "instances": [ { "endChar": 172, "startChar": 163 } ], "isCustom": false, "name": "xxxxx", "id": 0 } ], "locations": [ { "isDeleted": false, "instances": [ { "endChar": 172, "startChar": 163 } ], "isCustom": false, "name": "xxxxx", "id": 0 } ], "money": [ { "isDeleted": false, "instances": [ { "endChar": 172, "startChar": 163 } ], "isCustom": false, "name": "xxxxx", "id": 0 } ], "nationalities": [ { "isDeleted": false, "instances": [ { "endChar": 1284, "startChar": 1275 } ], "isCustom": false, "name": "Republish", "id": 0 } ], "ordinals": [ { "isDeleted": false, "instances": [ { "endChar": 2812, "startChar": 2807 } ], "isCustom": false, "name": "xxxxx", "id": 0 } ], "people": [ { "isDeleted": false, "instances": [ { "endChar": 196, "startChar": 188 } ], "isCustom": false, "name": "xxxxx", "id": 0 } ], "percentages": [ { "isDeleted": false, "instances": [ { "endChar": 196, "startChar": 188 } ], "isCustom": false, "name": "xxxxx", "id": 0 } ], "products": [ { "isDeleted": false, "instances": [ { "endChar": 4930, "startChar": 4926 } ], "isCustom": false, "name": "xxxxx", "id": 0 } ], "quantities": [ { "isDeleted": false, "instances": [ { "endChar": 4930, "startChar": 4926 } ], "isCustom": false, "name": "xxxxx", "id": 0 } ], "times": [ { "isDeleted": false, "instances": [ { "endChar": 4930, "startChar": 4926 } ], "isCustom": false, "name": "xxxxx", "id": 0 } ], "topics": [] }, "description": "xxxxx", "tags": [ "tag1" ], "text": "Hello, This is sample text", "rawText": "Hello, This is sample text", "state": "processed", "assignTo": "", "remark": "", "sentiment": [ { "document": { "Negative": 0, "Neutral": 0, "Positive": 0 }, "sentences": [ { "id": 1, "instances": [], "score": { "compound": 0, "neg": 0, "neu": 1, "pos": 0 }, "text": "Sentence 1" } ] } ], "createdAt": "2021-04-13T00:30:26.721Z", "originalCreatedAt": "2021-04-13T00:30:26.721Z", "name": "xxxxx" } }, "x-abridged": true } } } } } } } }, "/text/update/{mediaId}": { "put": { "tags": [ "Text" ], "summary": "Update Text Note", "operationId": "text-update-text-note", "description": "## PARAMETERS\n\nIf you want to update your customer unique `medicalId` key then you can pass as a `string`.\n\nThe difference between `rawText` and `text`\n\n`text`: Text is an HTML field to display content on the editor. It helps users to identify `bold`, `italic` or any other editor functionality.\n\n**Important:** If you don't have HTML editor in your application then you can pass normal text content.\n\n`rawText`: This helps Speak Ai to analyze text notes.\n\n`remark`: If you want to pass any remarks from the user to display on Speak and also in your application.\n\n```\nmedicalId: String, // optional\nname: String, // required,\ndescription: string, // optional\ntags: [], // optional\ntext: \"HTML content\", // see below\nrawText: \"raw text content\", // see below\nremark: \"string\", // optional\n```\n\n**Request rules.** The mediaId in the path is required and must belong to a note in your workspace that is not deleted. If it does not, you get a 404 before the controller runs. Body validation happens first, so a bad body returns a 400 before that check.\n\nNothing in the body is unconditionally required, but any property not listed below is rejected with a 400, so do not send extra keys.\n\n**Updating the note's text is an all-or-nothing operation, everything else is a partial update.** Omit `rawText` entirely and the note's `text`, `rawText`, sentiment, and word/character counts are left completely unchanged \u2014 nothing else in the request affects them. If you include `rawText` at all (even as an empty string), this endpoint replaces rather than patches the text content: an empty or wordless `rawText` clears both `rawText` and `text` on the note and empties its stored sentiment. So: to update the note's text, always send the complete `text` and `rawText` you want to keep together in the same request; to update anything else (name, description, tags, remark, status, manageBy) without touching the note's content, leave `rawText` out entirely.\n\ndescription, manageBy, remark, status and createdAt are only written when you send a value that is not empty. Sending an empty string for any of them leaves the current value in place instead of clearing it. tags behaves differently: an empty string leaves the current tags alone, but an empty array is written and clears them.\n\nOmitting name leaves the stored title unchanged.\n\nSet isAutoSave to true for background editor saves. That skips reanalysis and skips the in-app update notification. On a normal save, Speak reanalyzes the note only if it has not been processed before, and a note analyzed webhook is attempted when it does.\n", "parameters": [ { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "2b12351c8146" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "rawText": { "type": "string", "description": "Replaces the plain text that Speak analyzes. Omit this field entirely and the note's text, rawText, sentiment, and word/character counts are left completely unchanged, regardless of what else is in the request. If you include it at all \u2014 even as an empty string, or text with no words in it \u2014 this endpoint replaces rather than patches: Speak clears both the analyzed text and the display text on the note and empties its stored sentiment. If you're updating the note's text, always send the complete note body you want to keep. String. Empty string allowed (clears the note). Stored trimmed. The word count derived from this value decides whether text and rawText are stored or cleared, but only when this field is present in the request at all." }, "text": { "type": "string", "description": "Replaces the display copy of the note, which can contain HTML so an editor keeps bold, italic and other formatting. Only takes effect when rawText is also present in the request \u2014 see rawText. If the rawText you send has no words, Speak clears this instead. If the rawText you send has words but you leave text out, the current display copy stays as it is. String. Empty string allowed. Stored trimmed. Cleared whenever the rawText you send has no words." }, "name": { "type": "string", "description": "Replaces the note title. It also appears in the success message and in the in-app update notification. Leave it out and the current title stays as it is. String. Stored trimmed." }, "description": { "type": "string", "description": "Replaces the short summary shown alongside the note. An empty string leaves the current summary in place rather than clearing it. String. Empty string allowed but treated as no change. Stored trimmed." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Replaces the tags on the note. Send an array of strings. A comma separated string is accepted but is stored as one tag on this endpoint, so use the array form here. Leave it out to keep the existing tags, or send an empty array to remove them all. String or array. Stored as sent. An empty array clears the tags; an empty string is treated as no change." }, "remark": { "type": "string", "description": "Replaces the free text remark on the note. An empty string or null leaves the current remark in place rather than clearing it. String. Empty string and null allowed but treated as no change." }, "status": { "type": "string", "description": "Sets the status recorded on the note. An empty string leaves the current status in place. String. Empty string allowed but treated as no change. Values outside the listed set are stored as sent but are not recognized anywhere in the product, so stay within the list.", "enum": [ "", "pending", "progress", "completed", "pendingPayment" ] }, "manageBy": { "type": "string", "description": "Assigns the note to a user in your workspace, using that user's 24 character id. An empty string leaves the current assignee in place. String. Must be the 24 character id of a user. Empty string allowed but treated as no change. Any other value fails the update and returns a 500." }, "isAutoSave": { "type": "boolean", "description": "Marks the request as a background save from an editor. Send true and Speak skips reanalyzing the note and skips the in-app update notification, which keeps frequent autosaves cheap. Send false or leave it out for a normal save. Boolean. Defaults to a normal save when absent." }, "count": { "type": "object", "description": "Overrides the word and character counts stored on the note. Only takes effect when rawText is also present in the request. Send wordCount, characterCount and characterCountWithoutSpace. Leave rawText out and these counts are left unchanged regardless of what you send here; include rawText without this and Speak recounts from the rawText you sent. These numbers do not decide whether the body is kept: only the rawText you send does that. Object. Keys read: wordCount, characterCount, characterCountWithoutSpace, all numbers." }, "createdAt": { "type": "string", "description": "Changes the creation date recorded on the note. Leave it out to keep the current date. Date. Accepts an ISO 8601 date string or a timestamp. Only written when present." } } } } } }, "responses": { "200": { "description": "Success", "content": { "text/plain": { "schema": { "type": "string" }, "examples": { "update-text-note": { "summary": "Update Text Note", "value": "" } } } } } } } }, "/text/{mediaId}": { "delete": { "tags": [ "Text" ], "summary": "Delete Text Note", "operationId": "text-delete-text-note", "description": "## DELETE Request to Remove a Text Resource\n\nThis endpoint is used to delete a specific text resource identified by its unique `mediaId`. By sending a DELETE request to this endpoint, the client can remove the text resource from the server.\n\n### Request Parameters\n\n- **mediaId** (path parameter): A unique identifier for the text resource that you wish to delete. This is a required parameter and should be included in the URL.\n\n\n### Response Structure\n\nUpon successful deletion of the text resource, the server will respond with a status code indicating the outcome of the request:\n\n- **204 No Content**: Indicates that the resource was successfully deleted and there is no additional content to return.\n\n- **404 Not Found**: Indicates that the specified `mediaId` does not correspond to any existing resource.\n\n\n### Example\n\nTo delete a text resource with a specific `mediaId`, the request would look like:\n\n```\nDELETE {{url}}/v1/text/12345\n\n ```\n\nThis request would attempt to delete the text resource with the ID `12345`.\n\nMake sure to handle the response appropriately to confirm the deletion or to manage any errors that may arise.", "parameters": [ { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "3722e7826784" } ], "responses": { "200": { "description": "Success", "content": { "text/plain": { "schema": { "type": "string" }, "examples": { "delete-text-note": { "summary": "Delete Text Note", "value": "" } } } } } } } }, "/media/export/{mediaId}/{fileType}": { "post": { "tags": [ "Exports" ], "summary": "Export a media file", "operationId": "exports-export-media", "description": "Export one audio or video file from Speak Ai as a document, a caption file, or its source file.\n\n### Which formats can you export?\n\nPass the format as the `fileType` path parameter. Speak AI documents PDF, TXT, DOCX, SRT, VTT, and the source file itself as MP4.\n\n### How do you export a file's labels?\n\nPass `csv-labels` as `fileType` to get the labels on the transcript as a CSV, with one row for each labelled passage and label. A passage with two labels gives two rows. The response carries `Content-Disposition: attachment; filename=\"-labels.csv\"`. A file with no labels returns the header row only.\n\nThe columns, in order, are File name, Media ID, Folder, Group, Label, Label colour, Start, End, Speaker, Excerpt, Added by, Added at, Status, Confidence %, Comment count.\n\n- `Start` and `End` are times in the transcript, as `HH:mm:ss.SSS`.\n- `Speaker` holds the speaker names, joined with ` / ` when a passage spans speakers.\n- `Added by` is the team member who applied the label, or the name a reviewer gave on a dashboard link.\n- `Added at` is an ISO 8601 date.\n- `Status` is `active`, `shifted` or `needs_review`. A passage is `needs_review` when a transcript edit changed its words too much to place it with confidence.\n- `Confidence %` is the average transcription confidence of the passage's words. It is empty when the transcript has no word confidences, or while the passage is still being moved after a transcript edit.\n- `Comment count` counts the comments and replies on the passage, without deleted ones.\n- Archived labels are left out.\n- A text cell that starts with `=`, `+`, `-`, `@`, a tab or a carriage return gets a leading `'`, so a spreadsheet does not run it as a formula.\n\n### Which formats are unsupported?\n\nNot every format fits every record. You cannot export a text note as `srt`, `vtt`, `sourceFile`, `csv-transcript` or `csv-transcript-sentiment`, and you cannot export an audio or video file as `html`. Every one of those combinations returns `500` with the generic `Internal Server Error` body, so the response does not tell you which rule you hit. Quote the `requestId` it returns when you ask support about one.\n\n`ttml`, `md` and `mp4` pass validation, but Speak AI builds no export for any of them. The request returns neither a file nor an error, so it hangs until your client or the network times it out. Use `srt` or `vtt` for captions, and `sourceFile` for the original media.\n\n### Which prefix do you use?\n\nThe export route is mounted at three prefixes, `/media`, `/text`, and `/prompt`, and all three reach the same handler. The prefix does not change the result. Speak Ai reads the record that `mediaId` belongs to and exports it in the format `fileType` names, so `POST /media/export/{mediaId}/{fileType}` and `POST /text/export/{mediaId}/{fileType}` return the same file for the same id.", "parameters": [ { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "a59b93b67685", "description": "Id of the record to export." }, { "name": "fileType", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "csv", "csv-insights", "csv-labels", "csv-transcript", "csv-transcript-sentiment", "csv-text-sentiment", "docx", "html", "json", "md", "pdf", "sourceFile", "srt", "ttml", "txt", "vtt", "mp4" ] }, "description": "Name the format to export the record in. One of `csv`, `csv-insights`, `csv-labels`, `csv-transcript`, `csv-transcript-sentiment`, `csv-text-sentiment`, `docx`, `html`, `json`, `md`, `pdf`, `sourceFile`, `srt`, `ttml`, `txt`, `vtt` or `mp4`. Any other value, `word` among them, is rejected as a validation error, and the unsupported combinations above still apply.", "example": "csv" } ], "responses": { "200": { "description": "OK", "content": { "text/plain": { "schema": { "type": "string" }, "examples": { "txt": { "summary": "TXT", "value": "Speak Transcript - txt\nVideo Name: How To Find Your First Analyzed Video\nDate: Monday, December 14, 2020 12:09 PM\n\n0:00:00\r\nSpeaker #1\r\nHey there, in this video will show you how you can actually access the first \r\n\r\n\r\n0:00:03\r\nSpeaker #2\r\nvideo that you've uploaded. So right now we're in the sign in screen. All you have to do hit the sign in button. You're going to be redirected to the dashboard and you can sort of see some of the statistics and everything there, but what you're actually looking to do is hit the button where you can see the little video icon.\r\n\r\nYour list is actually going to\n...", "x-abridged": true }, "srt": { "summary": "SRT", "value": "1\n00:00:00,000 --> 00:00:05,920\nUpdated\n\n2\n00:00:05,920 --> 00:00:08,440\nIs this speak AI? Yes it is.\n\n3\n00:00:08,440 --> 00:00:13,840\nYeah, I was looking at the company and\nnotice here that you develop software\nright?\n\n4\n00:00:13,840 --> 00:00:19,240\nYes, and I wanted to see if your\ncompany's ever applied for the irap\ngrants.\n\n5\n00:00:19,240 --> 00:00:22,480\nYes we have. We have a have a person\n\n6\n00:00:22,480 --> 00:00:25,360\nthat we've sponsored right now and then\nwe,\n\n7\n00:00:25,360 --> 00:00:28,240\nyou know, I wrap your kickoff projects\nhere.\n\n8\n00:00:28,240 --> 00:00:31,840\nSo we've got \n...", "x-abridged": true } } }, "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "unsupported-format": { "summary": "unsupported format.", "value": { "status": "failed", "message": "Can't export text object to .srt, try .docx or .pdf instead." } }, "json": { "summary": "JSON", "value": { "mediaId": "875777809d88", "name": "How To Customize Your Account & Interactive Media Players Globally", "description": "Tyler shows you how to customize your account at the global level for audio and video.", "tags": [ "speak" ], "duration": "136", "createdAt": "2020-08-19T01:34:31.000Z", "state": "processed", "remark": "", "summary": "Hi there, in this video I'm going to show you how you can actually customize your account globally, so that if you're sharing I frames are custom landing pages, whether audio or.", "sentiment": { "document": { "Negative": 2.857142857142857, "Neutral": 28.57142857142857, "Positive": 68.57142857142857 }, "sentences": [ { "id": 1, "instances": [ { "adjustedEnd": "0:00:05.85", "adjustedStart": "0:00:00", "end": "0:00:05.85", "start": "0:00:00" } ], "score": { "compound": 0, "neg": 0, "neu": 1, "pos": 0 }, "text": "Hi there, in this video I'm going to show you how you can actually customize your account globally," } ] }, "transcript": [ { "speakerId": 1, "text": "Hi there, in this video I'm going to show you how you can actually customize your account globally, so that if you're sharing I frames are custom landing pages, whether audio or vi...", "start": "0:00:00", "link": "https://app.speakai.co/video/insight/875777809d88?insight=transcript&timeStart=0:00:00" } ] }, "x-abridged": true } } }, "text/csv": { "schema": { "type": "string" }, "examples": { "csv": { "summary": "CSV", "value": "MediaId,Media Name,Tags,Duration,Created At,State,Remark,Summary,Overall sentiment,Sentence id,Speaker name,Sentence start time,Sentence end time,Sentence duration,Transcript,Sentiment,Insight category,Insight,Insight starts at,Insight ends at\n875777809d88,How To Customize Your Account & Interactive Media Players Globally,speak,136,Tue Aug 18 2020 21:34:31 GMT-0400 (Eastern Daylight Time),processed,,Hi there, in this video I'm going to show you how you can actually customize your account globally, so that if you're sharing I frames are custom landing pages, whether audio or video, that the s\n...", "x-abridged": true } } } } } }, "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "isSpeakerNames": { "type": "boolean", "description": "Set to true to print speaker names next to each segment of the transcript." }, "isSpeakerEmail": { "type": "boolean", "description": "Set to true to print speaker email addresses next to each segment of the transcript. Null is accepted. The schema declares a default of false, but the validation middleware discards the schema's converted output, so omitting the property leaves it unset. Every export writer reads it for truthiness, so unset behaves the same as false." }, "isTimeStamps": { "type": "boolean", "description": "Set to true to print a timestamp on each segment of the transcript." }, "isInsightVisualized": { "type": "boolean", "description": "Set to true to render insights as charts and visuals in the exported file instead of plain text." }, "isRedacted": { "type": "boolean", "description": "Set to true to redact sensitive content from the exported file." }, "redactedCategories": { "type": "array", "items": { "type": "string" }, "description": "List the categories of sensitive content you want redacted when isRedacted is true. the schema with no.items call, so the server does not validate the item type and applies no maximum array length. The server code types the value as string[]." } } } } } } } }, "/text/export/{mediaId}/{fileType}": { "post": { "tags": [ "Exports" ], "summary": "Export a text note", "operationId": "exports-export-text", "description": "Export one text note from Speak Ai as a document. The response is the same as the `/media` prefix returns for the same id.\n\n### Which formats can you export?\n\nPass the format as the `fileType` path parameter. Speak AI documents PDF, TXT, DOCX, SRT, VTT, and the source file itself as MP4.\n\n### Which formats are unsupported?\n\nNot every format fits every record. You cannot export a text note as `srt`, `vtt`, `sourceFile`, `csv-transcript` or `csv-transcript-sentiment`, and you cannot export an audio or video file as `html`. Every one of those combinations returns `500` with the generic `Internal Server Error` body, so the response does not tell you which rule you hit. Quote the `requestId` it returns when you ask support about one.\n\n`ttml`, `md` and `mp4` pass validation, but Speak AI builds no export for any of them. The request returns neither a file nor an error, so it hangs until your client or the network times it out. Use `srt` or `vtt` for captions, and `sourceFile` for the original media.\n\n### Which prefix do you use?\n\nThe export route is mounted at three prefixes, `/media`, `/text`, and `/prompt`, and all three reach the same handler. The prefix does not change the result. Speak Ai reads the record that `mediaId` belongs to and exports it in the format `fileType` names, so `POST /media/export/{mediaId}/{fileType}` and `POST /text/export/{mediaId}/{fileType}` return the same file for the same id.", "parameters": [ { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "a59b93b67685", "description": "Id of the record to export." }, { "name": "fileType", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "csv", "csv-insights", "csv-labels", "csv-transcript", "csv-transcript-sentiment", "csv-text-sentiment", "docx", "html", "json", "md", "pdf", "sourceFile", "srt", "ttml", "txt", "vtt", "mp4" ] }, "description": "Name the format to export the record in. One of `csv`, `csv-insights`, `csv-labels`, `csv-transcript`, `csv-transcript-sentiment`, `csv-text-sentiment`, `docx`, `html`, `json`, `md`, `pdf`, `sourceFile`, `srt`, `ttml`, `txt`, `vtt` or `mp4`. Any other value, `word` among them, is rejected as a validation error, and the unsupported combinations above still apply.", "example": "csv" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "unsupported-format": { "summary": "Unsupported format", "value": { "status": "failed", "message": "Can't export text object to .srt, try .docx or .pdf instead." } } } } } } }, "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "isSpeakerNames": { "type": "boolean", "description": "Set to true to print speaker names next to each segment of the transcript." }, "isSpeakerEmail": { "type": "boolean", "description": "Set to true to print speaker email addresses next to each segment of the transcript. Null is accepted. The schema declares a default of false, but the validation middleware discards the schema's converted output, so omitting the property leaves it unset. Unset behaves the same as false." }, "isTimeStamps": { "type": "boolean", "description": "Set to true to print a timestamp on each segment of the transcript." }, "isInsightVisualized": { "type": "boolean", "description": "Set to true to render insights as charts and visuals in the exported file instead of plain text." }, "isRedacted": { "type": "boolean", "description": "Set to true to redact sensitive content from the exported file." }, "redactedCategories": { "type": "array", "items": { "type": "string" }, "description": "List the categories of sensitive content you want redacted when isRedacted is true. the schema with no.items call, so the server does not validate the item type and applies no maximum array length. The server code types the value as string[]." } } } } } } } }, "/prompt/export/{mediaId}/{fileType}": { "post": { "tags": [ "Exports" ], "summary": "Export through the prompt prefix", "operationId": "exports-export-prompt", "description": "Export one record from Speak Ai through the `/prompt` prefix. The response is the same as the `/media` prefix returns for the same id.\n\n### Which formats can you export?\n\nPass the format as the `fileType` path parameter. Speak AI documents PDF, TXT, DOCX, SRT, VTT, and the source file itself as MP4.\n\n### Which formats are unsupported?\n\nNot every format fits every record. You cannot export a text note as `srt`, `vtt`, `sourceFile`, `csv-transcript` or `csv-transcript-sentiment`, and you cannot export an audio or video file as `html`. Every one of those combinations returns `500` with the generic `Internal Server Error` body, so the response does not tell you which rule you hit. Quote the `requestId` it returns when you ask support about one.\n\n`ttml`, `md` and `mp4` pass validation, but Speak AI builds no export for any of them. The request returns neither a file nor an error, so it hangs until your client or the network times it out. Use `srt` or `vtt` for captions, and `sourceFile` for the original media.\n\n### Which prefix do you use?\n\nThe export route is mounted at three prefixes, `/media`, `/text`, and `/prompt`, and all three reach the same handler. The prefix does not change the result. Speak Ai reads the record that `mediaId` belongs to and exports it in the format `fileType` names, so `POST /media/export/{mediaId}/{fileType}` and `POST /text/export/{mediaId}/{fileType}` return the same file for the same id.", "parameters": [ { "name": "mediaId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "a59b93b67685", "description": "Id of the record to export." }, { "name": "fileType", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "csv", "csv-insights", "csv-labels", "csv-transcript", "csv-transcript-sentiment", "csv-text-sentiment", "docx", "html", "json", "md", "pdf", "sourceFile", "srt", "ttml", "txt", "vtt", "mp4" ] }, "description": "Name the format to export the record in. One of `csv`, `csv-insights`, `csv-labels`, `csv-transcript`, `csv-transcript-sentiment`, `csv-text-sentiment`, `docx`, `html`, `json`, `md`, `pdf`, `sourceFile`, `srt`, `ttml`, `txt`, `vtt` or `mp4`. Any other value, `word` among them, is rejected as a validation error, and the unsupported combinations above still apply.", "example": "csv" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "unsupported-format": { "summary": "Unsupported format", "value": { "status": "failed", "message": "Can't export text object to .srt, try .docx or .pdf instead." } } } } } } }, "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "isSpeakerNames": { "type": "boolean", "description": "Set to true to print speaker names next to each segment of the transcript." }, "isSpeakerEmail": { "type": "boolean", "description": "Set to true to print speaker email addresses next to each segment of the transcript. Null is accepted. The schema declares a default of false, but the validation middleware discards the schema's converted output, so omitting the property leaves it unset. Unset behaves the same as false." }, "isTimeStamps": { "type": "boolean", "description": "Set to true to print a timestamp on each segment of the transcript." }, "isInsightVisualized": { "type": "boolean", "description": "Set to true to render insights as charts and visuals in the exported file instead of plain text." }, "isRedacted": { "type": "boolean", "description": "Set to true to redact sensitive content from the exported file." }, "redactedCategories": { "type": "array", "items": { "type": "string" }, "description": "List the categories of sensitive content you want redacted when isRedacted is true. the schema with no.items call, so the server does not validate the item type and applies no maximum array length. The server code types the value as string[]." } } } } } } } }, "/media/exportMultiple": { "post": { "tags": [ "Exports" ], "summary": "Multi-export", "operationId": "exports-multi-export", "description": "You can export multiple media at once. We're going to zip the documents and send it to you as an `arraybuffer`.\n\n**Request rules.** No field is conditionally required. Some behaviour depends on what you send rather than on validation, so read the field descriptions below.\n\nWith `fileType` set to `csv-labels`, the ZIP holds one `-labels.csv` for each file that has labels, and files without labels are left out. With `isMerged` set to true it holds one `merged_export.csv` with the rows of every file. When none of the files has labels, the request returns a JSON body instead of a ZIP, with HTTP status 200, `status` set to `failed` and `message` set to `No labels found for these files`. Check the response content type before you save it as a ZIP. The columns are the same as for a single export.\n\nA text note in the set is skipped rather than failed when `fileType` is `sourceFile`, `csv-transcript` or `csv-transcript-sentiment`, so the ZIP can hold fewer files than you asked for. The notification Speak AI raises when the export finishes counts the files it actually wrote against the number you requested.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mediaIds": { "type": "array", "items": { "type": "string" }, "description": "List the IDs of the media files you want to export together. Required. the schema with no.items call, so the server does not validate the item type and applies no maximum array length. Pass an empty array to fall back to exporting a whole folder through folderId." }, "fileType": { "type": "string", "description": "Choose the file format used for every file in the export. Must be one of the accepted values. There is no default, and the schema does not mark it required, but the controller dereferences it unconditionally, so omitting it returns a 500 rather than a validation error. Treat it as required in practice.", "enum": [ "csv", "csv-insights", "csv-labels", "csv-transcript", "csv-transcript-sentiment", "csv-text-sentiment", "docx", "html", "json", "md", "pdf", "sourceFile", "srt", "ttml", "txt", "vtt", "mp4" ] }, "isSpeakerNames": { "type": "boolean", "description": "Set to true to print speaker names next to each segment of the transcript." }, "isSpeakerEmail": { "type": "boolean", "description": "Set to true to print speaker email addresses next to each segment of the transcript. Null is accepted. The schema declares a default of false, but the validation middleware discards the schema's converted output, so omitting the property leaves it unset. Unset behaves the same as false." }, "isTimeStamps": { "type": "boolean", "description": "Set to true to print a timestamp on each segment of the transcript." }, "isInsightVisualized": { "type": "boolean", "description": "Set to true to render insights as charts and visuals in the exported files instead of plain text." }, "isRedacted": { "type": "boolean", "description": "Set to true to redact sensitive content from the exported files." }, "redactedCategories": { "type": "array", "items": { "type": "string" }, "description": "List the categories of sensitive content you want redacted when isRedacted is true. the schema with no.items call, so the server does not validate the item type and applies no maximum array length. The server code types the value as string[]." }, "folderId": { "type": "string", "description": "Give the ID of a folder to export every media file inside it. The server uses this only when mediaIds is empty. An empty string is explicitly allowed. The schema declares a default of empty string, but the validation middleware discards the schema's converted output, so an omitted folderId reaches the controller as undefined rather than as an empty string." }, "isMerged": { "type": "boolean", "description": "Set to true to combine every media file into one document instead of one file per media inside the ZIP. The schema declares a default of false, but that default is not written back to the request, so omitting it leaves it unset. Unset behaves the same as false." } }, "required": [ "mediaIds" ] }, "example": { "mediaIds": [ "a59b93b67685", "dsd33b676asd" ], "fileType": "pdf", "isSpeakerNames": true, "isTimeStamps": true, "isInsightVisualized": true, "isRedacted": true, "isMerged": false } } } }, "responses": { "200": { "description": "Success", "content": { "text/plain": { "schema": { "type": "string" }, "examples": { "multi-export": { "summary": "Multi-export", "value": "" } } } } } } } }, "/folder/views": { "get": { "tags": [ "Folder" ], "summary": "Get All Views", "operationId": "folder-get-all-views", "description": "Get all views across all folders for the company. Used to populate dropdown for cloning views.", "x-speak-group": "Folder Views", "responses": { "200": { "description": "Success. This spec records no example response body for this endpoint." } }, "x-doc-group": "Views" } }, "/folder/{folderId}/views": { "get": { "tags": [ "Folder" ], "summary": "Get Views by Folder ID", "operationId": "folder-get-views-by-folder-id", "description": "Get all views for a specific folder", "x-speak-group": "Folder Views", "parameters": [ { "name": "folderId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the folder to get views for", "example": "your_folder_id_here" } ], "responses": { "200": { "description": "Success. This spec records no example response body for this endpoint." } }, "x-doc-group": "Folder Views" }, "post": { "tags": [ "Folder" ], "summary": "Create View", "operationId": "folder-create-view", "description": "Create a new view for a specific folder. Column types can be:\n\n**FieldType values:**\n- text\n- url\n- boolean\n- date\n- datetime\n- number\n- currency\n\n**DefaultViewColumn values:**\n- name\n- duration\n- tags\n- sentiment\n- datetime\n- createdAt\n- updatedAt", "x-speak-group": "Folder Views", "parameters": [ { "name": "folderId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the folder to create view for", "example": "your_folder_id_here" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name for the new view. Required." }, "isDefault": { "type": "boolean", "description": "Whether this view becomes the folder's default view. Setting it to true clears the default flag on your other active views in the folder. Optional. The schema declares a default of false, but the middleware discards the schema's converted value, so an omitted isDefault reaches the handler as undefined. The stored value still ends up false, because the FolderView model defaults isDefault to false." }, "columns": { "type": "array", "items": { "type": "object", "properties": { "fieldId": { "type": "string", "description": "The ID of the custom field this column shows. Leave it empty for a built-in column. Optional. Empty string and null are accepted." }, "name": { "type": "string", "description": "The heading shown for this column. Required." }, "type": { "type": "string", "description": "What kind of value the column holds. The accepted set is the FieldType values followed by the DefaultViewColumn values. Required. The value must be one of the listed values. The set is built from Object.values(FieldType) and Object.values(DefaultViewColumn), both declared in speak-shared and re-exported through and The raw.valid list contains \"datetime\" twice, because it appears in both enums; the accepted set is the 15 distinct values listed here.", "enum": [ "text", "url", "boolean", "date", "datetime", "number", "currency", "name", "duration", "tags", "sentiment", "size", "mediaType", "createdAt", "updatedAt" ] }, "definition": { "type": "string", "description": "An optional label describing what the column is derived from. Optional. Empty string and null are accepted." }, "order": { "type": "number", "description": "The position of the column in the view, counting from zero. The server replaces a value of 0 with the column's position in the array you sent, so a column with order 0 in third position is stored as 2. Required. Declared as Any number passes; there is no minimum and no integer-only rule. The handler stores col.order || index, which is why 0 is overwritten." } } }, "description": "The columns the view shows, in the order you want them displayed. Required. Each entry must be an object matching columnSchema. No cap on the number of entries. An empty array passes validation, because the array has no.min." } }, "required": [ "name", "columns" ] }, "example": { "name": "My Custom View", "isDefault": false, "columns": [ { "fieldId": "", "name": "Name", "type": "name", "definition": "", "order": 0 }, { "fieldId": "", "name": "Duration", "type": "duration", "definition": "duration", "order": 1 }, { "fieldId": "", "name": "Tags", "type": "tags", "definition": "tags", "order": 2 }, { "fieldId": "", "name": "Sentiment", "type": "sentiment", "definition": "sentiment", "order": 3 }, { "fieldId": "", "name": "Created At", "type": "datetime", "definition": "createdAt", "order": 4 } ] } } } }, "responses": { "200": { "description": "Success. This spec records no example response body for this endpoint." } }, "x-doc-group": "Folder Views" } }, "/folder/{folderId}/views/{viewId}": { "put": { "tags": [ "Folder" ], "summary": "Update View", "operationId": "folder-update-view", "description": "Update an existing view. Note: isDefault is required in update operation.", "x-speak-group": "Folder Views", "parameters": [ { "name": "folderId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the folder", "example": "your_folder_id_here" }, { "name": "viewId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the view to update", "example": "your_view_id_here" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The new name for the view. Required." }, "isDefault": { "type": "boolean", "description": "Whether this view is the folder's default view. Unlike the create call, you must send this value on every update. Setting it to true clears the default flag on your other active views in the folder. Required, with no default declared, so omitting it returns 400." }, "columns": { "type": "array", "items": { "type": "object", "properties": { "fieldId": { "type": "string", "description": "The ID of the custom field this column shows. Leave it empty for a built-in column. Optional. Empty string and null are accepted." }, "name": { "type": "string", "description": "The heading shown for this column. Required." }, "type": { "type": "string", "description": "What kind of value the column holds. The accepted set is the FieldType values followed by the DefaultViewColumn values. Required. The value must be one of the listed values. The set is built from Object.values(FieldType) and Object.values(DefaultViewColumn), both declared in speak-shared and re-exported through and The raw.valid list contains \"datetime\" twice, because it appears in both enums; the accepted set is the 15 distinct values listed here.", "enum": [ "text", "url", "boolean", "date", "datetime", "number", "currency", "name", "duration", "tags", "sentiment", "size", "mediaType", "createdAt", "updatedAt" ] }, "definition": { "type": "string", "description": "An optional label describing what the column is derived from. Optional. Empty string and null are accepted." }, "order": { "type": "number", "description": "The position of the column in the view, counting from zero. The server replaces a value of 0 with the column's position in the array you sent, so a column with order 0 in third position is stored as 2. Required. Declared as Any number passes; there is no minimum and no integer-only rule. The handler stores col.order || index, which is why 0 is overwritten." } } }, "description": "The full set of columns the view shows, in display order. This replaces the view's existing columns. Required. Each entry must be an object matching columnSchema. No cap on the number of entries. An empty array passes validation, because the array has no.min." } }, "required": [ "name", "isDefault", "columns" ] }, "example": { "name": "Updated View Name", "isDefault": true, "columns": [ { "fieldId": "", "name": "Name", "type": "name", "definition": "", "order": 0 }, { "fieldId": "", "name": "Duration", "type": "duration", "definition": "duration", "order": 1 }, { "fieldId": "", "name": "Tags", "type": "tags", "definition": "tags", "order": 2 }, { "fieldId": "", "name": "Sentiment", "type": "sentiment", "definition": "sentiment", "order": 3 }, { "fieldId": "", "name": "Created At", "type": "datetime", "definition": "createdAt", "order": 4 } ] } } } }, "responses": { "200": { "description": "Success. This spec records no example response body for this endpoint." } }, "x-doc-group": "Folder Views" }, "delete": { "tags": [ "Folder" ], "summary": "Delete View", "operationId": "folder-delete-view", "description": "Delete a view (soft delete - sets isActive to false)", "x-speak-group": "Folder Views", "parameters": [ { "name": "folderId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the folder", "example": "your_folder_id_here" }, { "name": "viewId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the view to delete", "example": "your_view_id_here" } ], "responses": { "200": { "description": "Success. This spec records no example response body for this endpoint." } }, "x-doc-group": "Folder Views" } }, "/folder/views/clone": { "post": { "tags": [ "Folder" ], "summary": "Clone View", "operationId": "folder-clone-view", "description": "Clone a view from source folder to target folder. Use 'Get All Views' to get available view IDs for cloning.\n\n**Request rules.** `targetFolderId` must differ from `sourceFolderId`. Sending the same id for both is rejected.", "x-speak-group": "Folder Views", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceFolderId": { "type": "string", "description": "The ID of the folder that holds the view you want to copy. Required." }, "targetFolderId": { "type": "string", "description": "The ID of the folder you want the copied view added to. It must be a different folder from sourceFolderId. Required. Rejected when it equals sourceFolderId,. invalid(the schema). The error message is \"Source and target folder IDs cannot be the same\"." }, "viewId": { "type": "string", "description": "The ID of the view inside the source folder that you want to copy. It must belong to an active view, otherwise the request returns 404. Required." }, "name": { "type": "string", "description": "The name for the copied view in the target folder. Required." }, "isDefault": { "type": "boolean", "description": "Whether the copied view becomes the default view for the target folder. Setting it to true clears the default flag on your other active views in that folder. Optional. The schema declares a default of false, but the middleware discards the schema's converted value, so an omitted isDefault reaches the handler as undefined. The stored value still ends up false, because the FolderView model defaults isDefault to false." } }, "required": [ "sourceFolderId", "targetFolderId", "viewId", "name" ] }, "example": { "sourceFolderId": "source_folder_id_here", "targetFolderId": "target_folder_id_here", "viewId": "view_id_to_clone_here", "name": "Cloned View Name", "isDefault": false } } } }, "responses": { "200": { "description": "Success. This spec records no example response body for this endpoint." } }, "x-doc-group": "Views" } }, "/folder": { "get": { "tags": [ "Folder" ], "summary": "Get folders", "operationId": "folder-get-folders", "description": "## Get Folders\n\nThis endpoint retrieves a list of folders based on pagination and sorting criteria.\n\n### Request Parameters\n\n- **page** (integer, required): The page number to retrieve. This parameter is used for pagination.\n\n- **pageSize** (integer, required): The number of folders to return per page. This parameter controls the size of the result set.\n\n- **sortBy** (string, required): The field by which to sort the folders. In this case, it is sorted by `createdAt`.\n\n\n### Response Format\n\nThe response will contain the following structure:\n\n- **status** (string): The status of the request.\n\n- **data** (object): Contains the details of the folders retrieved.\n\n - **totalCount** (integer): The total number of folders available.\n\n - **pages** (integer or null): The total number of pages available based on the pagination.\n\n - **folders** (array): An array of folder objects, each containing:\n\n - **_id** (string): The unique identifier for the folder.\n\n - **defaultAssignTo** (string): The default user assigned to the folder.\n\n - **showOrder** (integer): The order in which the folder should be displayed.\n\n - **name** (string): The name of the folder.\n\n - **folderId** (string): The identifier for the folder.\n\n - **createdAt** (string): The creation date of the folder.\n\n - **updatedAt** (string): The last updated date of the folder.\n\n - **user** (object): An object representing the user associated with the folder.\n\n - **_id** (string): The unique identifier for the user.\n\n - **firstName** (string): The first name of the user.\n\n - **lastName** (string): The last name of the user.\n\n - **userId** (string): The identifier for the user associated with the folder.\n\n\n### Notes\n\n- Ensure that the `page` and `pageSize` parameters are set correctly to retrieve the desired set of folders.\n\n- The response may return an empty array if no folders are available for the specified page and size.", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "0" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "5" }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string" }, "example": "createdAt" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "You can pass in the dateFormat", "x-postman-disabled": true }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "You can pass in the dateFormat", "x-postman-disabled": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "totalCount": { "type": "integer" }, "pages": { "type": "string", "nullable": true }, "folders": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "defaultAssignTo": { "type": "string" }, "showOrder": { "type": "integer" }, "name": { "type": "string" }, "folderId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "user": { "type": "object", "properties": { "_id": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" } } }, "userId": { "type": "string" } } } } } } } }, "examples": { "get-folders": { "summary": "Get folders", "value": { "status": "success", "data": { "totalCount": 93, "pages": null, "folders": [ { "_id": "61e3d27bxxxx5041a7", "defaultAssignTo": "", "showOrder": 1, "name": "AudioAudioAudioAudioAudioAudioAudioAudioAu", "folderId": "905c208f1c07", "createdAt": "2022-01-16T08:08:27.821Z", "updatedAt": "2025-01-06T15:05:38.939Z", "user": { "_id": "5d03a9d5xxxx8cf89", "firstName": "Vatsal", "lastName": "Shah" }, "userId": "5d03a9d5dxxxxc8cf89" } ] } } } } } } } }, "x-doc-group": "Folder" }, "post": { "tags": [ "Folder" ], "summary": "Create folder", "operationId": "folder-create-folder", "description": "### Create a New Folder\n\nThis endpoint allows you to create a new folder by sending an HTTP POST request to the specified URL.\n\n#### Request Body\n\n- **name** (string, required): The name of the folder to be created.\n\n\nExample:\n\n``` json\n{\n \"name\": \"Folder name 2\"\n}\n\n ```\n\n#### Response\n\n- **status** (string): The status of the request.\n\n- **data**\n\n - **folderId** (string): The ID of the newly created folder.\n\n - **message** (string): A message related to the folder creation.\n\n\nExample:\n\n``` json\n{\n \"status\": \"\",\n \"data\": {\n \"folderId\": \"\",\n \"message\": \"\"\n }\n}\n\n ```", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "folderId": { "type": "string", "description": "An existing folder ID. The create handler ignores this value, so you can leave it out. Optional. Empty string and null are accepted." }, "name": { "type": "string", "description": "The name you want to give the folder. Leading and trailing whitespace is stripped before the folder is saved. Required. The schema declares.trim, but the validation middleware discards the schema's converted value, so the trimming you see comes from the handler itself (it calls name.trim for both the duplicate check and the saved value) and from the Folder model, which sets trim: true on name. No maximum length is enforced anywhere.", "deprecated": true }, "defaultAssignTo": { "type": "string", "description": "A single user ID to assign the folder to. Use assignTo instead. When you send this and omit assignTo, the server wraps the value into a one-item assignTo array. Optional. Empty string and null are accepted. The schema declares a default of an empty string, but that default never reaches the handler because the middleware throws away the schema's converted value.", "deprecated": true }, "assignTo": { "type": "array", "items": { "type": "string" }, "description": "The user IDs you want the folder assigned to. Optional. No cap on the number of entries. The schema declares a default of an empty array, but that default never reaches the handler. Omitting assignTo is exactly what lets defaultAssignTo take effect, because the handler checks Array.isArray(assignTo) first." }, "description": { "type": "string", "description": "A short description of what the folder holds. It is saved exactly as you send it. Optional. Empty string and null are accepted. The schema declares.trim and a default of an empty string, but neither takes effect: the middleware discards the schema's converted value and the Folder model does not trim description, so leading and trailing whitespace is preserved." }, "source": { "type": "object", "description": "Where the folder's content comes from. The create handler ignores this value, so it only takes effect on PUT /folder/{folderId}. Optional, and null is accepted. Accepts three optional inner keys: type (string, empty string and null allowed), subCategory (string, empty string and null allowed), and fields (array, null allowed, with no item schema declared so any entries pass). Any other inner key is rejected, including goal, which the Folder model stores but this schema does not accept." } }, "required": [ "name" ] }, "example": { "name": "Folder name 2" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "folderId": { "type": "string" }, "message": { "type": "string" } } } } }, "examples": { "create-folder": { "summary": "Create folder", "value": { "status": "success", "data": { "folderId": "0648e533f72c", "message": "Folder name 2 folder created successfully" } } } } } } } }, "x-doc-group": "Folder" } }, "/folder/{folderId}": { "get": { "tags": [ "Folder" ], "summary": "Get folders info", "operationId": "folder-get-folders-info", "description": "## Get Folder Details\n\nThis endpoint retrieves the details of a specific folder identified by its unique `folderId`.\n\n### Request Parameters\n\n- `folderId` (path parameter): The unique identifier of the folder you want to retrieve. This should be a valid ID corresponding to an existing folder in the system.\n\n\n### Response\n\nThe response will contain a JSON object with the following structure:\n\n- `status`: A string indicating the status of the request.\n\n- `data`: An object containing detailed information about the folder:\n\n - `_id`: The unique identifier of the folder.\n\n - `companyId`: The ID of the company associated with the folder.\n\n - `userId`: The ID of the user who owns the folder.\n\n - `folderType`: The type of folder.\n\n - `name`: The name of the folder.\n\n - `description`: A brief description of the folder.\n\n - `defaultAssignTo`: The default user assigned to the folder (can be null).\n\n - `showOrder`: An integer indicating the order in which the folder is displayed.\n\n - `userShowOrder`: An object mapping user IDs to their specific display order for the folder.\n\n - `isDeleted`: A boolean indicating whether the folder has been deleted.\n\n - `folderId`: The ID of the folder.\n\n - `createdAt`: The timestamp when the folder was created.\n\n - `updatedAt`: The timestamp when the folder was last updated.\n\n - `__v`: The version key for the document.\n\n - `source`: An object containing:\n\n - `type`: The type of source associated with the folder.\n\n - `subCategory`: The subcategory of the source.\n\n - `shared`: An array containing information about users or entities with whom the folder is shared.\n\n\n### Notes\n\n- Ensure that the `folderId` provided in the request is valid, as an invalid ID will result in an error response.\n\n- The `isDeleted` field in the response indicates whether the folder is currently active or has been marked for deletion.", "parameters": [ { "name": "folderId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "e88575b384b6" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "_id": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string" }, "folderType": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "defaultAssignTo": { "type": "string", "nullable": true }, "showOrder": { "type": "integer" }, "userShowOrder": { "type": "object", "properties": { "5d03a9d5d4bca272e9c8cf89": { "type": "integer" } } }, "isDeleted": { "type": "boolean" }, "folderId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "__v": { "type": "integer" }, "source": { "type": "object", "properties": { "type": { "type": "string" }, "subCategory": { "type": "string" } } }, "shared": { "type": "array", "items": {} } } } } }, "examples": { "get-folders-info": { "summary": "Get folders info", "value": { "status": "success", "data": { "_id": "6776f1459df32xxx30f8", "companyId": "5e21c8ddxxxxxx2c64214816", "userId": "5d03a9d5d4xxxxxc8cf89", "folderType": "sub", "name": "v35", "description": "", "defaultAssignTo": null, "showOrder": 2, "userShowOrder": { "5d03a9d5d4bca272e9c8cf89": 2 }, "isDeleted": false, "folderId": "e8857xxx4b6", "createdAt": "2025-01-02T20:04:21.511Z", "updatedAt": "2025-01-06T15:05:38.939Z", "__v": 0, "source": { "type": "content", "subCategory": "podcast" }, "shared": [] } } } } } } } }, "x-doc-group": "Folder" }, "put": { "tags": [ "Folder" ], "summary": "Update folder", "operationId": "folder-update-folder", "description": "\n## Update Folder\n\nThis endpoint allows you to update the details of a specific folder identified by its `folderId`.\n\n### Request\n\n- **Method**: `PUT`\n- **Endpoint**: `{{url}}/v1/folder/:folderId`\n- **Path Parameter**:\n - `folderId` (string): The unique identifier of the folder you wish to update.\n\n### Request Body\n\n`name` (string) is the only required field. `description`, `assignTo`, `defaultAssignTo`, and `source` are all optional \u2014 **omit a field entirely to leave its current value unchanged.** This is a partial update: only fields you actually include in the request body are written.\n\nTo explicitly clear a value instead of leaving it as-is, send it as an empty string (`description`) or an empty array (`assignTo`) \u2014 that is different from omitting the field.\n\n- `name` (string, required): The new name for the folder.\n- `description` (string, optional): Short description of the folder's contents. Omit to leave unchanged; send `\"\"` to clear.\n- `assignTo` (string[], optional): User IDs the folder is shared with. Omit (and omit `defaultAssignTo`) to leave the current sharing list unchanged; send `[]` to clear it.\n- `defaultAssignTo` (string, deprecated): Single-user convenience form of `assignTo`. Prefer `assignTo`.\n- `source` (object, optional): Where the folder's content comes from; sending it replaces the stored source.\n\n**Example Request Body** (rename only \u2014 sharing and description are left untouched):\n```json\n{\n \"name\": \"Folder name 2 Updated\"\n}\n```\n\n**Example Request Body** (rename and replace the sharing list):\n```json\n{\n \"name\": \"Folder name 2 Updated\",\n \"assignTo\": [\"64f0a1b2c3d4e5f678901234\"]\n}\n```\n\n### Response\n\nUpon a successful update, the response will be in JSON format and will include the following fields:\n\n- `status` (string): The status of the request.\n- `data` (object): Contains additional information about the update.\n - `folderId` (string): The ID of the updated folder.\n - `message` (string): A message indicating the result of the update.\n - `fields` (array): An array that may contain any relevant fields related to the update.\n\n**Example Response**:\n```json\n{\n \"status\": \"\",\n \"data\": {\n \"folderId\": \"\",\n \"message\": \"\",\n \"fields\": []\n }\n}\n```\n\n### Notes\n\nEnsure that the `folderId` in the URL is valid and that you have the necessary permissions to update the folder.\n", "parameters": [ { "name": "folderId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "0648e533f72c" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "folderId": { "type": "string", "description": "An existing folder ID. The update handler takes the folder from the path instead, so this body value is ignored. Optional. Empty string and null are accepted." }, "name": { "type": "string", "description": "The new name for the folder. Leading and trailing whitespace is stripped before it is saved. Required. The schema declares.trim, but the middleware discards the schema's converted value, so the trimming comes from the Folder model, which sets trim: true on name. No maximum length is enforced." }, "defaultAssignTo": { "type": "string", "description": "A single user ID to assign the folder to. Use assignTo instead. When you send this and omit assignTo, the server wraps the value into a one-item assignTo array. Optional. Empty string and null are accepted. The schema declares a default of an empty string, but that default never reaches the handler.", "deprecated": true }, "assignTo": { "type": "array", "items": { "type": "string" }, "description": "The user IDs you want the folder assigned to. Sending this replaces the current assignment list. Omitting both assignTo and defaultAssignTo leaves the current assignment list unchanged \u2014 send an empty array explicitly if you want to clear it. Optional. No cap on the number of entries. The schema declares a default of an empty array, but that default never reaches the handler." }, "description": { "type": "string", "description": "A short description of what the folder holds. It is saved exactly as you send it. Omitting this field entirely leaves the existing description unchanged; sending an empty string clears it. Optional. Empty string and null are accepted. The schema declares.trim and a default of an empty string, but neither takes effect, so leading and trailing whitespace is preserved." }, "source": { "type": "object", "description": "Where the folder's content comes from. Sending it replaces the folder's stored source, and sending source.fields with entries also creates the matching folder fields and a new default view for the folder. Optional, and null is accepted. Accepts three optional inner keys: type (string, empty string and null allowed), subCategory (string, empty string and null allowed), and fields (array, null allowed, with no item schema declared so any entries pass). Only type and subCategory are persisted on the folder document; the Folder model's source sub-schema has no fields path, so fields is consumed to create folder fields rather than stored." } }, "required": [ "name" ] }, "example": { "name": "Folder name 2 Updated" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "folderId": { "type": "string" }, "message": { "type": "string" }, "fields": { "type": "array", "items": {} } } } } }, "examples": { "update-folder": { "summary": "Update folder", "value": { "status": "success", "data": { "folderId": "0648e533f72c", "message": "Folder name 2 Updated folder updated successfully", "fields": [] } } } } } } } }, "x-doc-group": "Folder" }, "delete": { "tags": [ "Folder" ], "summary": "Delete folder", "operationId": "folder-delete-folder", "description": "### DELETE /v1/folder/:folderId\n\nThis endpoint is used to delete a specific folder identified by the `folderId`. The deletion operation will remove the folder and all its contents from the system.\n\n#### Request Parameters\n\n- `folderId` (path parameter): The unique identifier of the folder that you wish to delete. This parameter is required.\n\n\n#### Response Structure\n\nUpon successful deletion, the response will return a JSON object with the following structure:\n\n- `status`: A string indicating the status of the operation (e.g., success or failure).\n\n- `message`: A string providing additional information about the result of the deletion operation.\n\n\n#### Example Response\n\n``` json\n{\n \"status\": \"success\",\n \"message\": \"Folder deleted successfully.\"\n}\n\n ```\n\nIn case of an error, the response may contain an appropriate error message indicating what went wrong.", "parameters": [ { "name": "folderId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "0648e533f72c" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "delete-folder": { "summary": "Delete folder", "value": { "status": "success", "message": "Folder successfully deleted." } } } } } } }, "x-doc-group": "Folder" } }, "/folder/clone": { "post": { "tags": [ "Folder" ], "summary": "Clone Folder", "operationId": "folder-clone-folder", "description": "### Clone Folder\n\nThis endpoint allows the user to clone a folder by making an HTTP POST request to the specified URL.\n\n#### Request Body\n\n- `folderId` (string) - The ID of the folder to be cloned.\n\n- `name` (string) - The name of the new folder.\n\n- `description` (string) - The description of the new folder.\n\n- `defaultAssignTo` (string) - The default assignee for the new folder.\n\n- `isSaveDefaultView` (boolean) - Indicates whether the default view should be saved.\n\n\n#### Response\n\nThe response of this request is a JSON object with the following schema:\n\n``` json\n{\n \"type\": \"object\",\n \"properties\": {\n \"status\": {\n \"type\": \"string\"\n },\n \"data\": {\n \"type\": \"object\",\n \"properties\": {\n \"folderId\": {\n \"type\": \"string\"\n },\n \"message\": {\n \"type\": \"string\"\n }\n }\n }\n }\n}\n\n ```\n\n#### Example Response\n\n``` json\n{\n \"status\": \"\",\n \"data\": {\n \"folderId\": \"\",\n \"message\": \"\"\n }\n}\n\n ```", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "folderId": { "type": "string", "description": "The ID of the folder you want to copy. Required. Empty string and null are not accepted." }, "name": { "type": "string", "description": "The name for the new copy. Leave it out and the server names the copy \" (Clone)\". Optional. Empty string and null are accepted. An empty string is treated as absent by the handler, because it falls back on a falsy check." }, "description": { "type": "string", "description": "A description for the new copy. Leave it out and the original folder's description is carried over, falling back to an empty string. Optional. Empty string and null are accepted. An empty string is treated as absent by the handler, because it falls back on a falsy check." }, "defaultAssignTo": { "type": "string", "description": "A single user ID to assign the copy to. Use assignTo instead. When you send this and omit assignTo, the server wraps the value into a one-item assignTo array. Optional. Empty string and null are accepted. No default is declared.", "deprecated": true }, "assignTo": { "type": "array", "items": { "type": "string" }, "description": "The user IDs you want the new copy assigned to. The copy does not inherit the original folder's assignment list, so send this if you want the assignment carried over. Optional. No cap on the number of entries. The schema declares a default of an empty array, but that default never reaches the handler; omitting assignTo is what lets defaultAssignTo take effect." }, "isSaveDefaultView": { "type": "boolean", "description": "Whether to copy the source folder's default view onto the new folder. Send true explicitly if you want the view copied. Optional. The schema declares a default of true, but the middleware discards the schema's converted value, so an omitted isSaveDefaultView reaches the handler as undefined and the default view is not copied. There is no model-level default to fall back on here, because the flag only gates a branch in the handler." } }, "required": [ "folderId" ] }, "example": { "folderId": "905c208f1c07", "name": "New Folder Name", "description": "New Folder description", "defaultAssignTo": "", "isSaveDefaultView": true } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "folderId": { "type": "string" }, "message": { "type": "string" } } } } }, "examples": { "create-folder": { "summary": "Create folder", "value": { "status": "success", "data": { "folderId": "0648e533f72c", "message": "Folder name 2 folder created successfully" } } } } } } } }, "x-doc-group": "Folder" } }, "/recorder/status/{token}": { "get": { "tags": [ "Recorder/Survey" ], "summary": "Check Recorder Status", "operationId": "recorder-survey-check-recorder-status", "description": "Reveals whether recorder is publically open or password-protected", "x-speak-group": "Recorder Embed", "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "example": "recorder-9" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "isSecure": { "type": "boolean", "description": "True when the recorder is password-protected, so the page must collect a password and call POST /v1/recorder/verify before recording. False when the recorder is open to anyone with the link." }, "email": { "type": "string", "description": "Email address of the user who owns the recorder." }, "userId": { "type": "string", "description": "Id of the user who owns the recorder." }, "companyId": { "type": "string", "description": "Id of the company the recorder belongs to." }, "isExpired": { "type": "boolean", "description": "Carries the recorder's disabled flag. It is always false on a 200, because a disabled recorder returns 404 with 'Embedded Recorder is disabled!' before the payload is built." }, "name": { "type": "string", "description": "Recorder name, shown as the heading on the recording page unless the recorder hides the title." }, "description": { "type": "string", "description": "Recorder description, shown under the heading unless the recorder hides the description." }, "bucketId": { "type": "string", "description": "Storage bucket the recording is uploaded to. It comes from the company's subscription and falls back to speakai-storage-us-east-1 when the subscription does not name one." }, "meta": { "type": "object", "description": "Branding and capture settings for the recording page. It carries the recorder's own meta, with primaryColor, logo, backgroundImg and fontFamily falling back to the company's branding when the recorder leaves them empty, customCSS sanitized before it is returned, hideImages defaulting to false, and isFooter from the subscription's recorder features. isFooter true renders the Speak footer at the bottom of the recording page, and is false for accounts whose plan includes recorder customization. S3 logo and background URLs are rewritten to their CloudFront address." }, "minDuration": { "type": "integer", "description": "Shortest recording the recorder accepts, in seconds." }, "maxDuration": { "type": "integer", "description": "Longest recording the recorder accepts, in seconds." }, "sourceLanguage": { "type": "string", "description": "Transcription language code the recorder is set to, such as en-US, or multi for a recorder that expects more than one language in the same recording. Open the live transcription socket with this value: a client that assumes en-US instead drops the sentences spoken in the recorder's other languages." } } } } }, "examples": { "check-recorder-status": { "summary": "Check Recorder Status", "value": { "status": "success", "data": { "isSecure": false, "email": "demo@example.com", "userId": "66f0a1b2c3d4e5f60718293a", "companyId": "66f0a1b2c3d4e5f60718293b", "isExpired": false, "name": "Customer feedback recorder", "description": "Tell us how the call went.", "bucketId": "speakai-storage-ca-central-1", "meta": { "logo": "", "backgroundImg": "", "primaryColor": "#4338ca", "fontFamily": "Lato", "customCSS": "", "hideImages": false, "isFooter": true }, "minDuration": 15, "maxDuration": 7200, "sourceLanguage": "en-US" } } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "requestId": { "type": "string" }, "code": { "type": "integer" }, "message": { "type": "string" }, "hints": { "type": "array", "items": { "type": "string" } } } }, "examples": { "404": { "summary": "404", "value": { "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." ] } } } } } } }, "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ] } }, "/recorder/verify": { "post": { "tags": [ "Recorder/Survey" ], "summary": "Verify Password", "operationId": "recorder-survey-verify-password", "description": "User to grant\\prohobit access to a password-protected recorder", "x-speak-group": "Recorder Embed", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Pass the recorder's embed token, the same token that appears in the public recorder URL. Required. An empty string is rejected. A token that matches no recorder returns 404 with 'Recorder not found!'." }, "password": { "type": "string", "description": "Pass the password a viewer typed so Speak can check it against the recorder. Required. An empty string is rejected. Unlike most string fields on the recorder endpoints this one is a plain the schema with no.trim, so leading and trailing spaces are compared as typed." } }, "required": [ "token", "password" ] }, "example": { "token": "token", "password": "123" } } } }, "responses": { "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "requestId": { "type": "string" }, "code": { "type": "integer" }, "message": { "type": "string" }, "hints": { "type": "array", "items": { "type": "string" } } } }, "examples": { "404": { "summary": "404", "value": { "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." ] } } } } } } }, "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ] } }, "/recorder/create": { "post": { "tags": [ "Recorder/Survey" ], "summary": "Create Recorder", "operationId": "recorder-survey-create-recorder", "description": "**Create a recorder and integrate with your platform easily.**\n\n**All the required fields are as below:**\n\n`name` - Name of the recorder\n\nAll the other fields are optional. Your recorder will be created automatically.\n\n`description` - Assign description of the recorder for internal purpose.\n\n`folderId` - Save all your recordings to the assigned FolderId.\n\n---\n\n**Duration of the recorder:**\n\n- `minDuration` - 15 seconds (min) & 5 min (max)\n - Pass the duration in **seconds**\n\n- `maxDuration` - 10 seconds (min) & 3 hours (max)\n - Pass the duration in seconds\n\n\n---\n\n**Source Language:**\n\n- You can pass the `sourceLanguage` as a code.\n\n- Other language codes available at the top of the page.\n\n\n---\n\n**Recorder options:**\n\n- We allow to support creating recorder with the multiple options such as:\n - `audio` - Audio recorder\n\n - `video` - Video recorder\n\n - `screeShare` - Allow to screen share on browser (Mobile not supported)\n\n - `uploadFile` - Allow to upload various file formats\n - `allowMultiple` - Supporting multiple file uploads\n\n\n---\n\n**Notifications:**\n\n`upload` - Recieve an email notification when anyone uploads a recording on the recorder\n\n`client` - When your user submits a recording (have the email address in a form) - they will receive an submittion email\n\n---\n\n**Client Information Questions:**\n\n`name` - Ask for their name\n\n`email` - Ask for their email address\n\n`questions` - Check an API endpoint to update different types of questions.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name the recorder. This is the only field you have to send. Required. An empty or whitespace-only value is rejected because the validator is the schema.trim with no.allow(''). The value is stored exactly as you send it, including any surrounding whitespace." }, "description": { "type": "string", "description": "Describe the recorder for your own reference. Optional. An empty string is allowed." }, "isAutoAnalyze": { "type": "boolean", "description": "Analyze each recording automatically as soon as it is submitted. Optional. If you leave it out, the recorder is saved with automatic analysis on, which is the default on the Recorder model." }, "sourceLanguage": { "type": "string", "description": "Set the spoken language Speak transcribes recordings in. Optional. Must be one of the transcription language codes the server compiles at start up from the static list (137 entries, including auto and multi). An unrecognized code returns 400 with the message 'sourceLanguage must be a valid transcription language code'. GET /v1/media/supportedLanguages returns the list the server is currently serving, which can be refreshed from the database at runtime while the accepted set for this field stays as it was at start up, so the two can drift. If you leave the field out, the recorder is saved with en-US." }, "folderId": { "type": "string", "description": "Save every recording from this recorder into the folder you name here. Optional. An empty string is allowed and is the only value that makes Speak pick your first folder. Leaving the field out is not the same: the recorder is saved with an empty folderId instead. A folderId that does not exist in your company returns 400 with 'Folder not found'." }, "duration": { "type": "object", "description": "Set how long a recording is allowed to run. Optional. Two optional number keys, both in seconds. minDuration accepts 0 to 300, maxDuration accepts 15 to 10800. The create handler applies 15 and 300 when you leave the object or either key out." }, "notification": { "type": "object", "description": "Choose who gets an email when a recording comes in. Optional. Two optional booleans, both treated as true when you leave them out. upload emails the users in notifyUsers when a recording arrives. client emails the respondent a confirmation, and only fires when they gave an email address." }, "options": { "type": "object", "description": "Turn the individual capture and upload modes on or off. Optional. Keys are all optional booleans unless noted: audio (true when omitted), video (true), screenShare (true), liveTranscription (false, also accepts null), and upload, a nested object with file (true), text (false), multiple (false) and url (true). The create handler applies those fallbacks." }, "notifyUsers": { "type": "array", "items": { "type": "string" }, "description": "List the user IDs that get emailed when a recording arrives. Optional. Each item is a non-empty string. Stored under the recorder's notification block and used only when notification.upload is on." }, "clientInformation": { "type": "object", "description": "Decide what you ask a respondent for before they record. Optional. Reuses the updateQuestions schema at:33-46. Keys: name (boolean, true when omitted), email (boolean, true when omitted), questions (array, items unconstrained), and consent, a nested object with isEnabled (boolean, false), title (string, empty allowed), description (string, empty allowed), yesButtonLabel (string, 'Yes'), noButtonLabel (string, 'No'), isRequired (boolean, false) and fieldId (string, empty allowed, ''). The whole object is stored as sent." }, "meta": { "type": "object", "description": "Customize the recorder page. On create, only the layout fields below take effect. Optional. The create handler reads only customCSS, hideWaveform, hideTitle, hideDescription, hideSubmitButton, submitButtonLabel, countdown and hideImages. customCSS is capped at 50000 characters and is run through a CSS sanitizer before it is stored; when you leave it out or send an empty string, the company's stored customCSS is used. The booleans are false when omitted and submitButtonLabel is 'Upload' when omitted. primaryColor, backgroundImg, logo, fontColor, fontFamily and theme are accepted by the validator but ignored on create: a new recorder always inherits those six from your company branding. Use PUT /recorder/settings/{recorderId} to change them." }, "assignTo": { "type": "string", "description": "Accepted by the request validator but never used. Optional, empty string allowed. The create handler never reads this field and nothing in the recorder module references it, so sending it has no effect." } }, "required": [ "name" ] }, "example": { "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": [] } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "recorderData": { "type": "object", "properties": { "notification": { "type": "object", "properties": { "upload": { "type": "boolean" }, "client": { "type": "boolean" } } }, "recordings": { "type": "array", "items": {} }, "minDuration": { "type": "integer" }, "maxDuration": { "type": "integer" }, "privacyMode": { "type": "string" }, "password": { "type": "string" }, "isAutoAnalyze": { "type": "boolean" }, "assignTo": { "type": "string" }, "folderId": { "type": "string" }, "sourceLanguage": { "type": "string" }, "isActive": { "type": "boolean" }, "isDisabled": { "type": "boolean" }, "isDeleted": { "type": "boolean" }, "_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string" }, "recorderId": { "type": "string" }, "token": { "type": "string" }, "meta": { "type": "object", "properties": { "backgroundImg": { "type": "string" }, "logo": { "type": "string" }, "primaryColor": { "type": "string" }, "type": { "type": "object", "properties": { "audio": { "type": "boolean" }, "video": { "type": "boolean" }, "screenShare": { "type": "boolean" }, "upload": { "type": "object", "properties": { "file": { "type": "boolean" }, "multiple": { "type": "boolean" }, "text": { "type": "boolean" } } } } }, "client": { "type": "object", "properties": { "name": { "type": "boolean" }, "email": { "type": "boolean" }, "questions": { "type": "array", "items": {} } } } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "__v": { "type": "integer" } } }, "recorderId": { "type": "string" }, "token": { "type": "string" } } } } }, "examples": { "create-recorder": { "summary": "Create Recorder", "value": { "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" } } } } } } } }, "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ] } }, "/recorder": { "get": { "tags": [ "Recorder/Survey" ], "summary": "Recorder List", "operationId": "recorder-survey-recorder-list", "description": "## API Endpoint: Retrieve Recorders\n\nThis endpoint retrieves a list of recorders with pagination and sorting options. It allows users to fetch details about available recorders based on specified parameters.\n\n### Request\n\n**Method:** GET\n**URL:** `{{url}}/v1/recorder`\n\n**Query Parameters:**\n\n- `page` (integer): The page number of the results to retrieve. Default is `0`.\n\n- `pageSize` (integer): The number of records to return per page. Default is `20`.\n\n- `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.\n\n\n### Response\n\nThe response will contain a JSON object with the following structure:\n\n- `status` (string): The status of the request.\n\n- `data` (object): Contains the results of the request.\n\n - `totalCount` (integer): The total number of recorders available.\n\n - `page` (integer): The current page number of the results.\n\n - `recorderList` (array): A list of recorder objects, each containing:\n\n - `duration` (integer): The duration of the recording.\n\n - `isAutoAnalyze` (boolean): Indicates if the recorder is set for automatic analysis.\n\n - `isActive` (boolean): Indicates if the recorder is currently active.\n\n - `recordings` (array): An array of recordings associated with the recorder.\n\n - `createdAt` (string): The timestamp when the recorder was created.\n\n - `updatedAt` (string): The timestamp when the recorder was last updated.\n\n - `userId` (string): The ID of the user associated with the recorder.\n\n - `recorderId` (string): The unique ID of the recorder.\n\n - `token` (string): A token associated with the recorder.\n\n - `name` (string): The name of the recorder.\n\n - `meta` (object): Metadata about the recorder, including:\n\n - `type` (object): Specifies the types of media supported (e.g., video and audio).\n\n - `client` (object): Information about the client, including name and email.\n\n\n### Example Response\n\n``` json\n{\n \"status\": \"\",\n \"data\": {\n \"totalCount\": 0,\n \"page\": \"\",\n \"recorderList\": [\n {\n \"duration\": 0,\n \"isAutoAnalyze\": true,\n \"isActive\": true,\n \"recordings\": [],\n \"createdAt\": \"\",\n \"updatedAt\": \"\",\n \"userId\": \"\",\n \"recorderId\": \"\",\n \"token\": \"\",\n \"name\": \"\",\n \"meta\": {\n \"type\": {\n \"video\": true,\n \"audio\": true\n },\n \"client\": {\n \"name\": true,\n \"email\": true\n }\n }\n }\n ]\n }\n}\n\n ```", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "0" }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer" }, "example": "20" }, { "name": "filterName", "in": "query", "required": false, "schema": { "type": "string" }, "example": "recorder", "x-postman-disabled": true }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string" }, "example": "createdAt:desc" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "totalCount": { "type": "integer" }, "page": { "type": "string" }, "recorderList": { "type": "array", "items": { "type": "object", "properties": { "duration": { "type": "integer" }, "isAutoAnalyze": { "type": "boolean" }, "isActive": { "type": "boolean" }, "recordings": { "type": "array", "items": {} }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "userId": { "type": "string" }, "recorderId": { "type": "string" }, "token": { "type": "string" }, "name": { "type": "string" }, "meta": { "type": "object", "properties": { "type": { "type": "object", "properties": { "video": { "type": "boolean" }, "audio": { "type": "boolean" } } }, "client": { "type": "object", "properties": { "name": { "type": "boolean" }, "email": { "type": "boolean" } } } } } } } } } } } }, "examples": { "200": { "summary": "200", "value": { "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 } } } ] } } } } } } } }, "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ] } }, "/recorder/clone": { "post": { "tags": [ "Recorder/Survey" ], "summary": "Clone Recorder", "operationId": "recorder-survey-clone-recorder", "description": "**Clone Recorder to copy all the settings from the existing recorders**\n\n**All the required fields are as below:**\n\n`recorderId` - Pass the recorderId from the existing recorder\n\n**Optional:**\n\n`name` - New name for the recorder. If not pass, it will take the existing recorder name and add `(clone)` to the new recorder\n\n`description` - New description for the recorder. If not pass, it will take the existing recorder description as is.\n\n`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.\n\n---\n\nIf you need to change any other settings, we recommend to use the `Create Recorder` API call.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recorderId": { "type": "string", "description": "Name the recorder you want to copy. Required. An empty or whitespace-only value is rejected. A recorderId that matches no recorder returns 404 with 'Recorder not found'." }, "name": { "type": "string", "description": "Name the copy. Optional, empty string allowed. If you leave it out or send an empty string, the copy is named after the source recorder with ' (Clone)' appended." }, "description": { "type": "string", "description": "Describe the copy. Optional, empty string allowed. If you leave it out or send an empty string, the copy inherits the source recorder's description." }, "folderId": { "type": "string", "description": "Put the copy in this folder. Optional, empty string allowed. If you leave it out or send an empty string, the copy stays in the source recorder's folder. A folderId that matches no folder returns 404 with 'Folder not found. Please create or select a valid folder Id.'" } }, "required": [ "recorderId" ] }, "example": { "recorderId": "ce8f9465763c", "name": "Speak Clone test" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "recorderData": { "type": "object", "properties": { "notification": { "type": "object", "properties": { "upload": { "type": "boolean" }, "client": { "type": "boolean" } } }, "recordings": { "type": "array", "items": {} }, "minDuration": { "type": "integer" }, "maxDuration": { "type": "integer" }, "privacyMode": { "type": "string" }, "password": { "type": "string" }, "isAutoAnalyze": { "type": "boolean" }, "assignTo": { "type": "string" }, "folderId": { "type": "string" }, "sourceLanguage": { "type": "string" }, "isActive": { "type": "boolean" }, "isDisabled": { "type": "boolean" }, "isDeleted": { "type": "boolean" }, "_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "companyId": { "type": "string" }, "userId": { "type": "string" }, "recorderId": { "type": "string" }, "token": { "type": "string" }, "meta": { "type": "object", "properties": { "backgroundImg": { "type": "string" }, "logo": { "type": "string" }, "primaryColor": { "type": "string" }, "type": { "type": "object", "properties": { "audio": { "type": "boolean" }, "video": { "type": "boolean" }, "screenShare": { "type": "boolean" }, "upload": { "type": "object", "properties": { "file": { "type": "boolean" }, "multiple": { "type": "boolean" }, "text": { "type": "boolean" } } } } }, "client": { "type": "object", "properties": { "name": { "type": "boolean" }, "email": { "type": "boolean" }, "questions": { "type": "array", "items": {} } } } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "__v": { "type": "integer" } } }, "recorderId": { "type": "string" }, "token": { "type": "string" } } } } }, "examples": { "clone-recorder": { "summary": "Clone Recorder", "value": { "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" } } } } } } } }, "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ] } }, "/recorder/{recorderId}": { "get": { "tags": [ "Recorder/Survey" ], "summary": "Recorder info", "operationId": "recorder-survey-recorder-info", "description": "### API Endpoint: Get Recorder Details\n\n**Method:** GET\n**Endpoint:** `{{url}}/v1/recorder/:recorderId`\n\nThis 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.\n\n#### Response Structure:\n\n- **status**: Status of the request.\n\n- **data**: Contains the details of the recorder:\n\n - **recorderId**: Unique identifier for the recorder.\n\n - **userId**: Identifier for the user associated with the recorder.\n\n - **name**: Name of the recorder.\n\n - **description**: Description of the recorder.\n\n - **token**: Authentication token for the recorder.\n\n - **recordings**: Array of recordings associated with the recorder.\n\n - **minDuration**: Minimum duration for recordings.\n\n - **maxDuration**: Maximum duration for recordings.\n\n - **privacyMode**: Privacy settings for the recorder.\n\n - **password**: Password for accessing the recorder, if applicable.\n\n - **isAutoAnalyze**: Indicates if automatic analysis is enabled.\n\n - **assignTo**: User or entity to which the recorder is assigned.\n\n - **folderId**: Identifier for the folder containing the recorder.\n\n - **sourceLanguage**: Language settings for the recorder.\n\n - **meta**: Metadata related to the recorder, including:\n\n - **backgroundImg**: Background image URL.\n\n - **logo**: Logo URL.\n\n - **primaryColor**: Primary color used in the recorder interface.\n\n - **type**: Supported types of recordings (audio, video, screen share, etc.).\n\n - **client**: Client-related information including name, email, and questions.\n\n - **callToActionButtons**: Action buttons associated with the recorder.\n\n - **notification**: Notification settings for the recorder.\n\n - **isActive**: Indicates if the recorder is currently active.\n\n - **createdAt**: Timestamp of when the recorder was created.\n\n - **updatedAt**: Timestamp of when the recorder was last updated.\n\n - **domain**: Domain associated with the recorder.", "parameters": [ { "name": "recorderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "recorderId": { "type": "string" }, "userId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "token": { "type": "string" }, "recordings": { "type": "array", "items": { "type": "string" } }, "minDuration": { "type": "integer" }, "maxDuration": { "type": "integer" }, "privacyMode": { "type": "string" }, "password": { "type": "string" }, "isAutoAnalyze": { "type": "boolean" }, "assignTo": { "type": "string" }, "folderId": { "type": "string" }, "sourceLanguage": { "type": "string" }, "meta": { "type": "object", "properties": { "backgroundImg": { "type": "string" }, "logo": { "type": "string" }, "primaryColor": { "type": "string" }, "type": { "type": "object", "properties": { "audio": { "type": "boolean" }, "video": { "type": "boolean" }, "screenShare": { "type": "boolean" }, "upload": { "type": "object", "properties": { "file": { "type": "boolean" }, "url": { "type": "boolean" }, "multiple": { "type": "boolean" }, "text": { "type": "string", "nullable": true } } } } }, "client": { "type": "object", "properties": { "name": { "type": "boolean" }, "email": { "type": "boolean" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "isRequired": { "type": "boolean" }, "answerType": { "type": "string" }, "options": { "type": "array", "items": {} }, "includeOther": { "type": "boolean" }, "fieldId": { "type": "string" }, "_id": { "type": "string" } } } } } }, "callToActionButtons": { "type": "array", "items": {} } } }, "notification": { "type": "object", "properties": { "client": { "type": "boolean" }, "upload": { "type": "boolean" }, "notifyUsers": { "type": "array", "items": {} } } }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "domain": { "type": "string" } } } } }, "examples": { "recorder-info": { "summary": "Recorder info", "value": { "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": "" } }, "x-abridged": true } } } } } }, "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ] }, "delete": { "tags": [ "Recorder/Survey" ], "summary": "Delete Recorder", "operationId": "recorder-survey-delete-recorder", "description": "## DELETE /v1/recorder/:recorderId\n\nThis endpoint allows clients to delete a specific recorder resource identified by the `recorderId`.\n\n### Parameters\n\n- **recorderId** (path parameter): The unique identifier of the recorder that you wish to delete. This parameter is required.\n\n\n### Response\n\nUpon successful deletion, the server will respond with a confirmation message indicating the result of the operation. The structure of the response will typically include:\n\n- A status code indicating the success or failure of the operation.\n\n- A message providing additional context about the deletion.\n\n\nEnsure that the `recorderId` provided corresponds to an existing recorder, as attempting to delete a non-existent recorder may result in an error response.", "parameters": [ { "name": "recorderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "requestId": { "type": "string" }, "code": { "type": "integer" }, "message": { "type": "string" }, "hints": { "type": "array", "items": { "type": "string" } } } }, "examples": { "404": { "summary": "404", "value": { "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." ] } } } } } } } } }, "/recorder/recordings/{recorderId}": { "get": { "tags": [ "Recorder/Survey" ], "summary": "Recording Details", "operationId": "recorder-survey-recording-details", "description": "Get Recording meta details such as:\n\n* Name\n* Email\n* Other asked questions", "parameters": [ { "name": "recorderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "totalCount": { "type": "integer" }, "recordings": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "recorderId": { "type": "string" }, "mediaId": { "type": "object", "properties": { "_id": { "type": "string" }, "folderId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string" }, "duration": { "type": "object", "properties": { "inSecond": { "type": "integer" }, "end": { "type": "string" }, "start": { "type": "string" } } }, "mediaId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "publishedUrl": { "type": "string" } } }, "client": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "answer": { "type": "string" }, "answerType": { "type": "string" } } } } } }, "isDeleted": { "type": "boolean" }, "meta": { "type": "object", "properties": { "isScreenShare": { "type": "boolean" }, "microphoneMuted": { "type": "boolean" }, "microphoneReadyState": { "type": "string" }, "microphoneName": { "type": "string" }, "microphoneNumber": { "type": "integer" }, "cameraMuted": { "type": "boolean" }, "cameraReadyState": { "type": "string" }, "cameraName": { "type": "string" }, "cameraNumber": { "type": "integer" } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "__v": { "type": "integer" } } } } } } } }, "examples": { "recording-details": { "summary": "Recording Details", "value": { "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 } ] } }, "x-abridged": true } } } } } }, "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ] } }, "/recorder/url/{recorderId}": { "get": { "tags": [ "Recorder/Survey" ], "summary": "Generate Recorder URL", "operationId": "recorder-survey-generate-recorder-url", "description": "### API Endpoint: Get Recorder URL\n\n**Method:** `GET`\n**Endpoint:** `{{url}}/v1/recorder/url/:recorderId`\n\n#### Description\n\nThis 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.\n\n#### Parameters\n\n- **recorderId** (path parameter): The unique identifier for the recorder whose URL is being requested.\n\n\n#### Response Format\n\nThe response will be in JSON format and includes the following fields:\n\n- **status**: A string indicating the status of the request.\n\n- **data**: An object containing:\n\n - **iframe**: A string representing the iframe URL for the recorder.\n\n - **page**: A string representing the page URL for the recorder.\n\n\n#### Example Response\n\n``` json\n{\n \"status\": \"\",\n \"data\": {\n \"iframe\": \"\",\n \"page\": \"\"\n }\n}\n\n ```", "parameters": [ { "name": "recorderId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "iframe": { "type": "string" }, "page": { "type": "string" } } } } }, "examples": { "200": { "summary": "200", "value": { "status": "success", "data": { "iframe": "", "page": "https://recorder.speakai.co/recorder-9-4fb7713e267a" } } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "requestId": { "type": "string" }, "code": { "type": "integer" }, "message": { "type": "string" }, "hints": { "type": "array", "items": { "type": "string" } } } }, "examples": { "404": { "summary": "404", "value": { "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." ] } } } } } } }, "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ] } }, "/recorder/settings/{recorderId}": { "put": { "tags": [ "Recorder/Survey" ], "summary": "Update Recorder Settings", "operationId": "recorder-survey-update-recorder-settings", "description": "**Update a recorder details.**\n\n`name` - Name of the recorder\n\nAll the other fields are optional. Your recorder will be updated automatically.\n\n---\n\n**Duration of the recorder:**\n\n- `minDuration` - 15 seconds (min) & 5 min (max)\n - Pass the duration in **seconds**\n- `maxDuration` - 10 seconds (min) & 3 hours (max)\n - Pass the duration in seconds\n\n---\n\n**Source Language:**\n\n- You can pass the `sourceLanguage` as a code.\n- Other language codes available at the top of the page.\n\n\n---\n\n**Recorder options:**\n\n- We allow to support creating recorder with the multiple options such as:\n - `audio` - Audio recorder\n - `video` - Video recorder\n - `screeShare` - Allow to screen share on browser (Mobile not supported)\n - `uploadFile` - Allow to upload various file formats\n - `allowMultiple` - Supporting multiple file uploads\n\n---\n\n**Notifications:**\n\n`upload` - Recieve an email notification when anyone uploads a recording on the recorder\n\n`client` - When your user submits a recording (have the email address in a form) - they will receive an submittion email\n\n---\n\n**Not found:**\n\nThe lookup is scoped to your own workspace. If no recorder with that `recorderId` belongs to it, the call returns 404 and nothing is updated.", "parameters": [ { "name": "recorderId", "in": "path", "required": true, "schema": { "type": "string" }, "example": null } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Set the recorder name. Required on every call, even when you only mean to change something else. An empty or whitespace-only value is rejected. Sending the current name back is how you make a partial update." }, "description": { "type": "string", "description": "Describe the recorder for your own reference. Optional, empty string allowed. The handler writes this only when the value is truthy, so an empty string leaves the stored description as it was." }, "isAutoAnalyze": { "type": "boolean", "description": "Analyze each recording automatically as soon as it is submitted. Optional. Leaving it out leaves the stored setting alone. Send false to turn automatic analysis off." }, "sourceLanguage": { "type": "string", "description": "Set the spoken language Speak transcribes recordings in. Optional. Leaving it out or sending an empty string leaves the stored language alone. Must be one of the transcription language codes the server compiles at start up from the static list (137 entries, including auto and multi). An unrecognized code returns 400 with 'sourceLanguage must be a valid transcription language code'." }, "folderId": { "type": "string", "description": "Move new recordings from this recorder into the folder you name here. Optional, empty string allowed. The handler writes the folder only when the value is truthy, so an empty string leaves the current folder alone. A folderId that does not exist in your company returns 400 with 'Folder not found'." }, "notifyUsers": { "type": "array", "items": { "type": "string" }, "description": "List the user IDs that get emailed when a recording arrives. Optional. Each item is a non-empty string. The handler persists this list only when you also send a notification object with at least one of upload or client set, so notifyUsers on its own is accepted and then ignored." }, "duration": { "type": "object", "description": "Set how long a recording is allowed to run. Optional. Two optional number keys, both in seconds. minDuration accepts 0 to 300, maxDuration accepts 15 to 10800. Each key is written only when it is truthy, so 0 does not overwrite the stored minDuration." }, "notification": { "type": "object", "description": "Choose who gets an email when a recording comes in. Optional. Two optional booleans. upload emails the users in notifyUsers when a recording arrives. client emails the respondent a confirmation, and only fires when they gave an email address. Sending this object with at least one key also writes notifyUsers, and any key you leave out is cleared on the stored notification block." }, "options": { "type": "object", "description": "Turn the individual capture and upload modes on or off. Optional. Keys are all optional booleans unless noted: audio, video, screenShare, liveTranscription (also accepts null), and upload, a nested object with file, text, multiple and url. When you send this object the handler replaces the whole stored block, so send every mode you want kept or the ones you leave out are cleared." }, "meta": { "type": "object", "description": "Brand and customize the recorder page. Optional, and unlike POST /recorder/create every key here takes effect. Strings, each written only when truthy: primaryColor, fontColor, fontFamily, theme, backgroundImg, logo. backgroundImg and logo are normalized from a signed CloudFront URL back to an S3 URI before storage. customCSS is capped at 50000 characters, is run through a CSS sanitizer before it is stored, and is written whenever you send it, so an empty string clears it. Booleans, each written whenever you send it: hideWaveform, hideTitle, hideDescription, hideSubmitButton, countdown, hideImages. submitButtonLabel is a string written only when truthy." } }, "required": [ "name" ] }, "example": { "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 } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "message": { "type": "string" }, "recorderId": { "type": "string" } } } } }, "examples": { "200": { "summary": "200", "value": { "status": "success", "data": { "message": "recorder-9 updated is successfully updated", "recorderId": "70ea4d569736" } } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "requestId": { "type": "string" }, "code": { "type": "integer" }, "message": { "type": "string" }, "hints": { "type": "array", "items": { "type": "string" } } } }, "examples": { "404": { "summary": "404", "value": { "status": "failed", "requestId": "3f0c1c2e-6c1b-4a3f-9a2d-7c5f0b1e4d88", "code": 404, "message": "Recorder not found", "hints": [ "The requested operation failed because a resource associated with the request could not be found." ] } } } } } } }, "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ] } }, "/recorder/questions/{recorderId}": { "post": { "tags": [ "Recorder/Survey" ], "summary": "Update Recorder Questions", "operationId": "recorder-survey-update-recorder-questions", "description": "**Update a recorder questions:**\n\n`questions` - Speak offer different set of questions to create and ask to your clients.\n\nHere're the few examples with value:\n\n1. Single Line - \"single\"\n2. Multi Line - \"multiple\"\n3. Checkbox\\* - \"checkbox\"\n4. Radio Button\\* - \"radiobutton\"\n5. Dropdown\\* - \"dropdownlist\"\n6. Date - \"date\"\n7. Date & Time - \"datetime\"\n\n\nCheckbox, Radio Button, Dropdown offers \"Include Others\" option.\n\nCheckbox Sample:\n\n``` json\n{\n\"question\":\"My Checkbox question\",\n\"isRequired\":true,\n\"answerType\":\"checkbox\",\n\"options\":[\"Option A\",\"Option B\"],\n\"includeOther\":false\n}\n\n```\n\nDropdown Sample with Include Other:\n\n``` json\n{\n \"question\": \"My Dropdown Question with Include Others\",\n \"isRequired\": true,\n \"answerType\": \"dropdownlist\",\n \"options\": [\n \"Value 1\",\n \"Value 2\"\n ],\n \"includeOther\": true\n}\n\n```", "parameters": [ { "name": "recorderId", "in": "path", "required": true, "schema": { "type": "string" }, "example": null } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Send the id of an existing question to edit it. Leave it out to add a new question. Optional. Accepts an empty string and null, both of which are treated as 'add a new question'. If you send an id that no question on the recorder matches, the request still returns 200 but nothing changes and questionData comes back empty." }, "question": { "type": "string", "description": "Write the question text a respondent sees. Required. An empty or whitespace-only value is rejected." }, "isRequired": { "type": "boolean", "description": "Make the respondent answer this question before they can submit. Required. There is no fallback, so you have to send it on every call, including edits." }, "answerType": { "type": "string", "description": "Set the kind of answer control the question uses. Required. An empty or whitespace-only value is rejected. This route puts no.valid constraint on the value, so the server stores whatever string you send. The recorder reads these values from the RecorderAnswerType enum in @speakai/shared: single, multiple, checkbox, radiobutton, dropdownlist, date, time, datetime. The public submission route does enforce that enum with.valid, so a value outside the set is stored here and then rejected when a respondent submits an answer." }, "options": { "type": "array", "items": { "type": "string" }, "description": "List the choices for a question that offers a fixed set of answers. Optional. Each item is a non-empty string. There is no cap on the number of items." }, "includeOther": { "type": "boolean", "description": "Add an 'Other' choice alongside the options you listed. Optional. No fallback, so it is stored as undefined when you leave it out." }, "fieldId": { "type": "string", "description": "Map the answers to one of your custom fields. Optional. Accepts an empty string and null." } }, "required": [ "question", "isRequired", "answerType" ] }, "example": { "question": "My First Sample Question", "isRequired": true, "answerType": "single", "options": [], "includeOther": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "message": { "type": "string" }, "recorderId": { "type": "string" } } } } }, "examples": { "200": { "summary": "200", "value": { "status": "success", "data": { "message": "recorder-9 updated is successfully updated", "recorderId": "70ea4d569736" } } } } } } } }, "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ] } }, "/embed": { "post": { "tags": [ "Media Embed" ], "summary": "Create Embed", "operationId": "media-embed-create-embed", "description": "Create an Interactive Media Player by passing the value for `mediaId` OR `folderIds`\n\n- By passing `mediaId` - Create an individual media player.\n\n- By passing `folderIds` - Create a repository for a folder to share with others.\n\n\nMake sure you have access to Shareable Media Repository in your subscription.\n\n**Request rules.** Send either a media id or a set of folder ids. A non-empty media id creates a single media player, and the request is rejected with 403 unless your plan includes the media player feature and your role allows sharing media. An empty or absent media id switches to the library path, which is rejected with 403 unless your plan includes the media library feature. A media id that matches no media file in your workspace returns 404.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "mediaId": { "type": "string", "description": "The id of the media file you want to publish as a standalone player. Send it to create a media player. Leave it out, or send an empty string, when you want a shared library built from folders instead. If that media file already has a player, you get the existing one back instead of a duplicate. Optional. An empty string is allowed and is treated the same as leaving it out." }, "folderIds": { "type": "array", "items": { "type": "string" }, "description": "The folders whose media you want to publish together as a shared library. Send folder ids with no media id to create one. If a library already exists for the same folder ids in the same order, you get that one back instead of a duplicate. Whenever you send folder ids, they are recorded on the new embed and a password is generated for it, and that password comes back in the response. Optional. A list of folder ids, with no minimum or maximum length. Folder ids that match nothing in your workspace do not cause an error." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "_id": { "type": "string" }, "meta": { "type": "object", "properties": { "callToActionButtons": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "label": { "type": "string" } } } }, "features": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "isActive": { "type": "boolean" } } } }, "isDataVizDownloadable": { "type": "boolean" }, "isDescription": { "type": "boolean" }, "isSEOIndexing": { "type": "boolean" }, "isRemarks": { "type": "boolean" }, "isPromptAsk": { "type": "boolean" }, "isPromptHistory": { "type": "boolean" }, "isTitle": { "type": "boolean" }, "primaryColor": { "type": "string" } } }, "mediaId": { "type": "string" }, "folderIds": { "type": "array", "items": {} }, "mediaType": { "type": "string" }, "token": { "type": "string" }, "privacyMode": { "type": "string" }, "page": { "type": "string" }, "iframe": { "type": "string" } } } } }, "examples": { "create-embed": { "summary": "Create Embed", "value": { "status": "success", "data": { "_id": "65660bf97f916888ccc2f4ca", "meta": { "callToActionButtons": [ { "url": "https://speakai.co", "label": "Speak Ai" } ], "features": [ { "name": "labels", "isActive": true } ], "isDataVizDownloadable": false, "isDescription": false, "isSEOIndexing": false, "isRemarks": true, "isPromptAsk": true, "isPromptHistory": true, "isTitle": true, "primaryColor": "#c42860" }, "mediaId": "3afc714552cd", "folderIds": [], "mediaType": "video", "token": "how-to-edit-the-transcript-79a590aa126b", "privacyMode": "private", "page": "", "iframe": "" } }, "x-abridged": true } } } } } }, "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ] }, "get": { "tags": [ "Media Embed" ], "summary": "Check Embed", "operationId": "media-embed-check-embed", "description": "Checks if an embed already exits and returns status and token id.", "parameters": [ { "name": "mediaId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ID of the media file to check for an embed" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "backgroundImg": { "type": "string" }, "logo": { "type": "string" }, "primaryColor": { "type": "string" }, "isDataVizDownloadable": { "type": "boolean" }, "isSEOIndexing": { "type": "boolean" }, "isTitle": { "type": "boolean" }, "isDescription": { "type": "boolean" }, "callToActionButtons": { "type": "array", "items": {} }, "features": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "isActive": { "type": "boolean" } } } } } }, "_id": { "type": "string" }, "mediaId": { "type": "string" }, "token": { "type": "string" }, "privacyMode": { "type": "string" } } } } }, "examples": { "200": { "summary": "200", "value": { "status": "success", "data": { "meta": { "backgroundImg": "", "logo": "", "primaryColor": "", "isDataVizDownloadable": true, "isSEOIndexing": true, "isTitle": true, "isDescription": true, "callToActionButtons": [], "features": [ { "name": "transcript", "isActive": true } ] }, "_id": "61280763ec13780791f004b2", "mediaId": "e4e3079e3da9", "token": "daily-standup-august-23-2021-239819a49b2d", "privacyMode": "public" } }, "x-abridged": true } } } } } }, "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ] } }, "/embed/{embedId}": { "put": { "tags": [ "Media Embed" ], "summary": "Update Embed", "operationId": "media-embed-update-embed", "description": "Update an existing Embed Media Player.\n\n- Make sure to pass in path `embedId` to update your existing player\n\n**Request rules.** The embedId value in the path is required and must be a string. Nothing in the body is required on its own, but only meta, privacyMode, password and mediaId change anything. Password handling runs only when privacyMode is present: private stores the trimmed password you send, or an empty one if you send none, and any other privacy value clears the password. The media file's own privacy mode is changed only when mediaId is present and not empty, and a media id that matches no media file in your workspace returns 404. Inside meta.callToActionButtons every item must carry both url and label. Inside meta.features every item must carry both name and isActive. An embed id that matches no embed returns 404.", "parameters": [ { "name": "embedId", "in": "path", "required": true, "schema": { "type": "string" }, "example": "65660bf97f916888ccc2f4ca" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "type": "object", "description": "The look and behavior of the embedded player. Every top level key you send is applied on its own, so keys you leave out keep their current values. Arrays and the lead capture group are the exception: sending one replaces the stored value in full. Optional. Unknown keys inside it are rejected with 400.", "properties": { "backgroundImg": { "type": "string", "description": "The background image shown behind the player. Send an empty string to clear it. If you send a signed delivery URL it is converted back to its underlying storage location before being saved, and a delivery URL that cannot be converted leaves the current image unchanged. Optional. An empty string is allowed and clears the image. Null is accepted but ignored, so it leaves the current image unchanged." }, "logo": { "type": "string", "description": "The logo shown on the player. Send an empty string to remove it. As with the background image, a signed delivery URL is converted back to its storage location before being saved, and one that cannot be converted leaves the current logo unchanged. Optional. An empty string is allowed and clears the logo. Null is accepted but ignored, so it leaves the current logo unchanged." }, "callToActionButtons": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Where the button sends the viewer. Required on every button you send." }, "label": { "type": "string", "description": "The text shown on the button. Required on every button you send." } } }, "description": "The buttons shown to viewers alongside the media. Send the full list you want, because this replaces any buttons already set. Send an empty array to remove them all. Optional. Each item must have both url and label, and both must be strings." }, "features": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The insight category this entry controls. Use the same name the insight is reported under, for example keywords, topics or sentiment. Custom categories you have created use their own names. Required on every feature you send." }, "isActive": { "type": "boolean", "description": "Set it to true to show this category to viewers and false to hide it. Required on every feature you send." }, "isCustom": { "type": "boolean", "description": "Accepted on a feature entry but not saved. Only the name and the active state of each feature are stored, so sending this has no effect. Optional." } } }, "description": "Which insight categories are switched on in the player, such as keywords, topics or sentiment. Send the full list you want, because this replaces the stored list. The list an embed starts with is built from the insights found on its media. Optional. Each item must have name and isActive. Only the name and the active state of each entry are stored. The list also carries rows that are not insights: on a shared dashboard, `{ \"name\": \"fieldsFocus\", \"isActive\": false }` stops recordings opened from the dashboard leading with their fields, and with no `fieldsFocus` row they do. Keep such rows when you resend the list." }, "isTitle": { "type": "boolean", "description": "Set it to true to show the media title in the player and false to hide it. Optional. A new embed inherits this from your workspace player settings, which start it on." }, "isDescription": { "type": "boolean", "description": "Set it to true to show the media description in the player and false to hide it. Optional. A new embed inherits this from your workspace player settings, which start it on." }, "isRemarks": { "type": "boolean", "description": "Set it to true to let viewers see remarks and comments left on the media. Optional. A new embed inherits this from your workspace player settings, which start it off." }, "isSEOIndexing": { "type": "boolean", "description": "Set it to true to let search engines index the shared page and false to keep it out of search results. Optional. A new embed inherits this from your workspace player settings, which start it on." }, "isDataVizDownloadable": { "type": "boolean", "description": "Set it to true to let viewers download the charts and visualizations shown in the player. Optional. A new embed inherits this from your workspace player settings, which start it on." }, "isMediaExport": { "type": "boolean", "description": "Set it to true to let viewers export or download the media itself. Optional. A new embed inherits this from your workspace player settings, which start it off." }, "isPromptAsk": { "type": "boolean", "description": "Set it to true to let viewers ask the AI assistant questions about the media from inside the player. Optional. A new embed inherits this from your workspace player settings, which start it off." }, "isPromptHistory": { "type": "boolean", "description": "Set it to true to show viewers the earlier questions and answers from the assistant, and false to start every visitor with a clean slate. Optional. A new embed inherits this from your workspace player settings, which start it off." }, "chatWelcomeMessage": { "type": "string", "description": "The greeting the AI assistant opens with in the player. Send an empty string to use no greeting. Optional. An empty string is allowed, and null is accepted and stored as no greeting." }, "assistantTemplateId": { "type": "string", "description": "The saved assistant template the player's AI chat answers with, so viewers get the tone and instructions you have already set up. Send an empty string to fall back to the default assistant. Optional. An empty string is allowed, and null is accepted and stored as no template." }, "primaryColor": { "type": "string", "description": "The accent color used for controls and highlights in the player. Send a CSS color value such as a hex code. Optional. An empty string is allowed. A new embed inherits this from your workspace player settings, which start it at a dark grey. The value is stored as sent and is not checked for a valid color." }, "titleColor": { "type": "string", "description": "The color of the title text in the player. Send a CSS color value such as a hex code. Optional. An empty string is allowed. A new embed inherits this from your workspace player settings, which start it at a dark grey. The value is stored as sent and is not checked for a valid color." }, "logoDark": { "type": "string", "maxLength": 2048, "description": "A shared dashboard's logo for viewers in dark mode. It must be an image already stored in Speak AI as a logo; any other link returns 400. When empty, the dashboard uses `logo`. Optional. An empty string or null clears it." }, "theme": { "type": "string", "enum": [ "light", "dark", "" ], "description": "Forces a shared dashboard into `light` or `dark` for every viewer and hides their theme switch. An empty string lets each viewer choose. Optional. Null clears it." }, "backgroundColor": { "type": "string", "description": "A hex color (`#rgb` or `#rrggbb`) for a shared dashboard's page background. Pair it with `theme` so text stays readable. Optional. An empty string or null clears it." }, "fontFamily": { "type": "string", "maxLength": 60, "description": "A Google Fonts family name for a shared dashboard, such as `Arimo`: letters, digits and spaces, up to 60 characters. Anything else returns 400. It overrides your account font for this embed. Optional. An empty string or null falls back to the account font." }, "leadCapture": { "type": "object", "description": "Asks viewers for their email before they can watch, so you can see who is viewing. Send the full set of lead capture values you want, because sending this replaces the whole group rather than merging into it. It stays inactive until you switch it on. Optional. Unknown keys inside it are rejected with 400.", "properties": { "isEnabled": { "type": "boolean", "description": "The main switch. Set it to true to prompt viewers for their details, and while it is false no prompt appears no matter what the other lead capture values say. Optional. New embeds start with this off." }, "collectName": { "type": "boolean", "description": "Set it to true to ask viewers for their name as well as their email. Optional. New embeds start with this off." }, "requireConsent": { "type": "boolean", "description": "Set it to true to make viewers tick a consent box before they can submit their details. Optional. New embeds start with this off." }, "consentText": { "type": "string", "description": "The wording shown next to the consent box. Write your own so it matches your privacy policy. Optional. An empty string is allowed, and null is accepted." } } }, "isLabels": { "type": "boolean", "description": "Set it to true to show the media's labels read-only in a media or folder embed. Viewers can never add or change labels. Optional. Off by default." }, "isComments": { "type": "boolean", "description": "Set it to true to show the media's comment threads read-only in a media or folder embed. Viewers can never comment. Optional. Off by default." } } }, "privacyMode": { "type": "string", "description": "Controls whether viewers need a password. Send private together with the password you want, or send public to remove password protection. Leave this out and the current password is left alone, so an update that only changes appearance cannot wipe it. When you also send a media id, the media file itself is switched to the same privacy mode. Optional. An empty string is allowed. The value is not checked against the list, and anything other than private is treated as public and clears the password.", "enum": [ "public", "private" ] }, "password": { "type": "string", "description": "The password viewers must enter. It is used only when you also send a privacy mode of private, and surrounding spaces are trimmed. Send private with no password, or with an empty string, and the embed ends up with no password at all. Optional. An empty string is allowed. Ignored unless privacyMode is present." }, "mediaId": { "type": "string", "description": "The media file behind this embed. Send it when you are changing the privacy mode, so the media file is switched over too. It does not move the embed to a different media file. Optional. An empty string is allowed and is treated as not sent. A non-empty value that does not match a media file in your workspace returns 404." }, "folderIds": { "type": "array", "items": { "type": "string" }, "description": "Accepted but ignored. This endpoint does not change which folders a library embed covers, so sending different folder ids has no effect. Optional. A list of folder ids." }, "mediaType": { "type": "string", "description": "Accepted but ignored. The media type is set when the embed is created and this endpoint does not change it. Optional. An empty string is allowed. The value is not checked against the list.", "enum": [ "audio", "video", "text", "media", "csv" ] }, "embedType": { "type": "string", "description": "Accepted but ignored. Whether the embed is a single media player, a folder library or a dashboard is decided when it is created and cannot be switched here. Optional. An empty string is allowed. The value is not checked against the list.", "enum": [ "mediaPlayer", "repository", "dashboard" ] }, "size": { "type": "string", "description": "Accepted but ignored. The stored iframe size is not changed by this endpoint. Optional. An empty string is allowed." }, "isActive": { "type": "boolean", "description": "Accepted but ignored. This endpoint does not turn an embed on or off. Optional." }, "_id": { "type": "string", "description": "The embed's own id. The Speak app sends it when it posts a whole embed object back. The embed that gets updated is always the one named in the path, so you can leave this out." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "_id": { "type": "string" }, "meta": { "type": "object", "properties": { "backgroundImg": { "type": "string" }, "callToActionButtons": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "label": { "type": "string" } } } }, "features": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "isActive": { "type": "boolean" } } } }, "isDataVizDownloadable": { "type": "boolean" }, "isDescription": { "type": "boolean" }, "isSEOIndexing": { "type": "boolean" }, "isRemarks": { "type": "boolean" }, "isPromptAsk": { "type": "boolean" }, "isPromptHistory": { "type": "boolean" }, "isTitle": { "type": "boolean" }, "logo": { "type": "string" }, "primaryColor": { "type": "string" } } }, "mediaId": { "type": "string" }, "folderIds": { "type": "array", "items": {} }, "embedType": { "type": "string" }, "isActive": { "type": "boolean" }, "isDeleted": { "type": "boolean" }, "analytics": { "type": "array", "items": {} }, "companyId": { "type": "string" }, "userId": { "type": "string" }, "mediaType": { "type": "string" }, "token": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "__v": { "type": "integer" }, "password": { "type": "string" } } } } }, "examples": { "update-embed": { "summary": "Update Embed", "value": { "status": "success", "data": { "_id": "65660bf97f916888ccc2f4ca", "meta": { "backgroundImg": "", "callToActionButtons": [ { "url": "https://speakai.co", "label": "Speak Ai" } ], "features": [ { "name": "keywords", "isActive": true } ], "isDataVizDownloadable": true, "isDescription": true, "isSEOIndexing": true, "isRemarks": true, "isPromptAsk": false, "isPromptHistory": true, "isTitle": true, "logo": "", "primaryColor": "#c42860" }, "mediaId": "3afc714552cd", "folderIds": [], "embedType": "mediaPlayer", "isActive": true, "isDeleted": false, "analytics": [], "companyId": "5e21c8dd2d77242c64214816", "userId": "5d03a9d5d4bca272e9c8cf89", "mediaType": "video", "token": "how-to-edit-the-transcript-79a590aa126b", "createdAt": "2023-11-28T15:49:13.511Z", "updatedAt": "2023-11-28T15:55:58.403Z", "__v": 0, "password": "" } }, "x-abridged": true } } } } } }, "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ] } }, "/embed/privacyState": { "get": { "tags": [ "Media Embed" ], "summary": "Check Embed Privacy Mode", "operationId": "media-embed-check-embed-privacy-mode", "description": "### Endpoint Description\n\nThis endpoint retrieves the privacy state of the application based on the provided token. It is primarily used to check whether the current privacy settings are secure.\n\n### Request\n\n- **Method**: GET\n\n- **URL**: `{{url}}/v1/embed/privacyState?token={token}`\n\n\n#### Query Parameters\n\n- `token` (string): A unique token that identifies the user's session or request. This parameter is required for the request to be processed.\n\n\n### Response\n\nThe response will contain the following structure:\n\n- **status** (string): A status message indicating the result of the request.\n\n- **data** (object): An object containing the privacy state information.\n\n - **isSecure** (boolean): A boolean value indicating whether the privacy settings are secure (`true` or `false`).\n\n\n### Example Response\n\n``` json\n{\n \"status\": \"\",\n \"data\": {\n \"isSecure\": true\n }\n}\n\n ```\n\nThis response indicates that the privacy settings are currently secure.", "parameters": [ { "name": "token", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "isSecure": { "type": "boolean" } } } } }, "examples": { "check-embed-privacy-mode": { "summary": "Check Embed Privacy Mode", "value": { "status": "success", "data": { "isSecure": false } } } } } } } }, "security": [ { "ApiKeyAuth": [], "AccessTokenAuth": [] } ] } }, "/embed/iframe": { "get": { "tags": [ "Media Embed" ], "summary": "Get Iframe URL", "operationId": "media-embed-get-iframe-url", "description": "Get Embed Iframe and Page URL\n\nEither pass `mediaId` for individaul file.\n\nOR\n\nPass `folderId` for a repository URLs.", "parameters": [ { "name": "mediaId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Either Folder ID or Media ID", "example": "''" }, { "name": "folderId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Either Folder ID or Media ID", "x-postman-disabled": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object", "properties": { "iframe": { "type": "string" }, "page": { "type": "string" } } } } }, "examples": { "get-iframe-url": { "summary": "Get Iframe URL", "value": { "status": "success", "data": { "iframe": "