Speak AI

Get a pre-signed S3 URL for direct file upload to Speak AI storage. After getting the URL, PUT your file to it, then call upload_media with the S3 URL. For a simpler workflow, use upload_local_file instead which handles all steps automatically.

Import an audio or video file into Speak AI from a URL and start transcription. Accepts a direct public file URL, a URL returned by get_signed_upload_url, or a page link from a supported platform, which the server resolves to the underlying media. Supported page links: YouTube, TikTok, Instagram, X/Twitter, Facebook, Reddit, SoundCloud, Twitch, Dailymotion, Streamable, Snapchat, Pinterest, Tumblr, Bilibili, VK, OK.ru and Rutube. Vimeo and Loom page links are not supported. Creates a media item. The request fails if the file exceeds the plan's size limit or its duration cannot be read. Returns mediaId and state right away while processing continues in the background. Use get_media_status until state is 'processed', then get_transcript and get_media_insights.

List and search media files in the workspace with filtering, pagination, and sorting. Use filterName for text search, mediaType to filter by audio/video/text, folderId for folder-specific results, and from/to for date ranges. Use the include param to embed additional data (transcripts, speakers, keywords) inline with each result, avoiding N+1 API calls. Returns mediaIds you can pass to get_transcript or get_media_insights. For deep full-text search across transcripts, use search_media instead.

Retrieve AI-generated insights for a processed media file — topics, sentiment, keywords, action items, summaries, and more. The media must be in 'processed' state (check with get_media_status first). For a video, data.thumbnail has the thumbnail: url, source (auto or custom), pending while a requested frame is being made, and error if that frame failed.

Retrieve the full transcript for a media file with speaker labels and timestamps. Works on processed media and also returns the partial, in-progress transcript while a meeting bot is still recording (LIVE_TRANSCRIPT state). To fetch only the new sentences added since your previous call during a live meeting, use get_live_meeting_transcript instead. Use update_transcript_speakers to rename speaker labels after reviewing. For subtitle-formatted output, use get_captions instead.

Update or rename speaker labels in a single media transcript. Call get_transcript first to read the speaker list — a speaker's label is whatever it was last renamed to, not a fixed value, so ids from an earlier turn may be stale. Renaming a speaker to a name another speaker already has is refused as a collision. Re-sending a rename that has already been applied is a safe no-op, so do not retry a call that reported success.

Edit the official transcript text of a single media file by finding and replacing text. Replaces every occurrence of the original text with the replacement (leave replacement empty to delete the text) and reports how many occurrences were replaced. Use update_transcript_speakers to rename speaker labels instead.

Check the processing status of a media file. States: pending → transcribing → analyzing → processed (or failed). Poll this after upload_media until state is 'processed', then use get_transcript and get_media_insights to retrieve results. For a video, data.thumbnail has the thumbnail: url, source (auto or custom), pending while a requested frame is being made, and error if that frame failed.

Update metadata fields (name, description, tags, status) for an existing media file.

Permanently delete a media file and all associated transcripts and insights.

Get captions for a media file. Captions are separate from full transcripts and are formatted for display/subtitles.

List all languages supported for transcription. Use the language codes when uploading media with a specific sourceLanguage.

Takes no parameters.

Get workspace-level media statistics — total counts, processing status breakdown, storage usage, etc.

Takes no parameters.

Mark or unmark media files as favorites for quick access.

Re-run AI analysis on a media file using the latest models. Choose which parts to re-run via the flags below. Overwrites the existing results for the selected parts.

Normalise speaker names that are ALREADY correct across multiple media files — for example changing "Frederik S." to "Frederik" everywhere. Applies the same mapping to every specified media file. NOT a way to identify a speaker across a project: neither the numeric id nor a default label such as "Speaker 1" refers to the same person in different files, because speakers are numbered per file in order of appearance. Renaming "Speaker 1" across many files will label a different person in each one. Identify the speakers in each file first (get_transcript, or an identify-speakers automation), then use this tool only to tidy up naming that is already correct. Match by the speaker's current LABEL, not by numeric id. A file whose speakers do not match the mapping is left unchanged and reported as failed. Re-sending a mapping that has already been applied is a safe no-op, so do not retry a call that reported success.

Move multiple media files to a folder in a single operation. Use this for batch reorganization instead of updating media one by one.

Set a custom thumbnail for a video. Send exactly one of imageUrl, imageBase64 or atSeconds. The image must be JPEG, PNG or WebP and at most 10 MB; the type is judged from the file bytes, not the name. atSeconds uses the video frame at that moment; this tool waits up to 60 seconds for the frame and returns its url, or says it is still processing (check later with get_media_status, which carries the thumbnail field). Each call replaces the current custom thumbnail, and there is no way back to the automatic one. Needs permission to edit the media. Errors: 400 bad input, unsupported image, blocked link or failed frame; 413 image too large; 409 a frame is already being made; 503 frame service busy, try again shortly.

Create a new text note in Speak AI for analysis. The content will be analyzed for insights, topics, and sentiment.

Retrieve AI-generated insights for a text note, including topics, sentiment, summaries, and action items.

Trigger a re-analysis of an existing text note to regenerate insights with the latest AI models. Overwrites the note's current insights and sentiment.

Update an existing text note's name, content, or metadata. New text replaces the existing text. A note that has not been analyzed yet is analyzed after the update; an already analyzed note is not re-analyzed, so call reanalyze_text afterwards if its insights should reflect the new text.

Export a media file's transcript, insights or labels in various formats (pdf, docx, srt, vtt, txt, csv). Use fileType csv-labels for a labels CSV with one row per labelled passage and label (file name, group, label, times, speaker, excerpt, author, status, confidence, comment count). Generates the file and returns it without saving or sharing anything.

Export multiple media files at once, optionally merged into a single file. With fileType csv-labels you get one labels CSV per file that has labels (files without labels are skipped), or one merged CSV with isMerged; it fails with not found when none of the files has labels.

Retrieve all saved views across all folders.

Takes no parameters.

Retrieve all saved views for a specific folder.

Create a new saved view for a folder with a custom set of display columns.

Update an existing saved view. Replaces the whole view, so `name`, `isDefault` and `columns` must all be supplied.

Duplicate an existing folder view into a target folder.

List all folders in the workspace with pagination and sorting.

Get detailed information about a specific folder including its contents.

Create a new folder in the workspace, optionally assigned to users or user groups.

Create a new folder copied from an existing folder's name and description. Media in the source folder is not copied. Set isSaveDefaultView to also copy the source folder's default view.

Update a folder. `name` must always be supplied (the server replaces the folder config). Pass `assignTo` to replace who can access it; omit it to keep the current assignment.

Permanently delete a folder. The folder must be empty: the request is refused if it still holds any media or if it is the workspace's last folder, so move or delete its media first.

Check whether a recorder/survey is active and accepting submissions.

Create a new recorder or survey for collecting audio/video submissions. The recorder is live as soon as it is created: anyone with its public link can submit. By default each submission emails the recorder owner (if they opted in) and any users in notifyUsers, and emails a confirmation to the respondent when they give an email (see `notification`), and it fires the workspace's embed_recorder.recording_received webhook and recording_received automations. Creating the recorder fires the workspace's embed_recorder.created webhook if one is registered.

List all recorders/surveys in the workspace.

Duplicate an existing recorder including all its settings and questions. The copy gets its own public link, accepts submissions right away and sends the same submission emails, webhooks and automations as any recorder. Fires the workspace's embed_recorder.created webhook if one is registered.

Get detailed information about a specific recorder including its settings and questions.

List all submissions/recordings collected by a specific recorder.

Retrieve the existing shareable URL and embed iframe code for a recorder/survey. Read-only lookup: returns the recorder's pre-existing share link; it does not create, modify, or publish anything.

Update configuration settings for a recorder (branding, capture options, etc.). Only the supplied settings change, and they apply to the recorder's live public page right away. `name` must always be supplied.

Update the survey questions and respondent-info settings for a recorder. The `questions` array replaces the recorder's existing questions, and changes apply to the recorder's live public page right away.

Permanently delete a recorder/survey. Its public link stops accepting submissions. Existing recordings are preserved. Fires the workspace's embed_recorder.deleted webhook if one is registered.

Create an embeddable player/transcript widget for a media file or a set of folders. Provide `mediaId` for a single-media embed, or `folderIds` for a folder/library embed. If an embed already exists for that media or folder set, it is returned instead. A single-media embed is viewable by anyone with the link while the media's privacy mode is public (the default); a folder embed is created with an auto-generated password. Use update_embed to change privacy or the password, or to show labels and comments (meta isLabels, isComments; off by default), or to brand a shared dashboard (meta logo, logoDark, theme, backgroundColor, primaryColor, titleColor, fontFamily).

Update an existing embed widget: appearance/feature toggles via `meta`, and privacy. Passing `mediaId` with `privacyMode` sets that privacy mode on the media file itself; a public mode makes the media viewable by anyone with the embed link. Setting `privacyMode` clears any existing password unless a new one is supplied in the same call.

Check if an embed exists for a media file and retrieve its configuration.

Get the iframe URL for embedding a media player/transcript on a webpage.

Viewing analytics for an embed the user owns: list the visits (sessions) to one embed, newest first by default. Each visit shows when it started and was last active, whether it is still live, total and active time, media opened, time watched, questions asked, traffic source and campaign tags, whether it was a bot, and the viewer's identity if they chose to share it. Returns sessions with totalCount, page and pageSize. Use get_embed_session with a session's _id for its full timeline.

Owner analytics for an embed: totals across its visits for a date range. Returns KPIs (sessions, unique and returning visitors, identified viewers, average active time, media opens, time watched, questions and sessions with questions), sessions and visitors per day, top traffic sources, and a paged table of media with opens, unique viewers, plays, time watched, completion rate, questions and downloads.

Viewing analytics for an embed the user owns: one visit in full. Returns the visit with the media it opened (time watched, plays, seeks, furthest position, completed), the questions asked in chat, and a paged list of its events in time order, plus how many earlier visits the same viewer has made to this embed. Use eventsPage and eventsPageSize to read long timelines.

Ask an AI-powered question about your media using Speak AI's AI Chat. Supports querying a single file, multiple files, entire folders, or your whole workspace. Pass mediaIds for specific files, folderIds for entire folders, or omit both to search across all media. Use assistantType to get specialized responses (e.g., 'researcher' for academic analysis, 'sales' for deal insights). To continue a conversation, pass the promptId from a previous response. Returns a promptId — save it to continue the conversation with follow-up questions. Set analysisMediaId + analysisInput to have the model listen to the audio or watch the video instead of reading the transcript alone. That is a premium feature and costs credits per hour of media — call get_analysis_quote first to check eligibility and price. Each question is charged to the account's chat usage. The assistant can also call other Speak AI tools and actions in the user's connected third-party apps (for example, sending a message), so a prompt can change data or send content outside this chat.

Check whether a media file can be analysed as audio or video, and what it will cost, before running ask_ai_chat with analysisInput. Returns { eligible, credits, seconds } and, when not eligible, a plain-English reason — an unavailable file is a normal result here, not an error. This is the only check that accounts for both the account's premium opt-in and the server-wide switch, so call it before committing to an expensive run.

Retry a failed or incomplete AI Chat response. Use when a previous ask_ai_chat call returned an error or incomplete answer. The turn runs again with its original settings, replaces the earlier answer for that message, and is charged to the account's chat usage again. Like ask_ai_chat, the assistant can call other Speak AI tools and actions in connected third-party apps.

Get a list of recent AI Chat conversations. Returns conversation summaries with promptIds that can be used to retrieve full messages via get_chat_messages.

Get full message history for conversations. Can filter by promptId for a specific conversation, by media/folder, or search across all chat messages. Returns questions, answers, references, and metadata.

Delete an entire chat conversation from conversation history, so it and its messages no longer appear. No tool can restore it.

List recent AI Chat messages across the workspace, newest first, with each prompt, answer, references, and the media or folder it ran on. Returns messages from the 25 most recently updated conversations in the workspace, filtered to those the caller can access, so a member may see fewer.

Takes no parameters.

Get all prompts and answers that have been marked as favorites. Useful for finding saved insights and important AI-generated analysis.

Takes no parameters.

Mark or unmark a chat message as a favorite for easy retrieval later.

Update the title of a chat conversation for easier identification in history.

Submit feedback on a chat response (thumbs up/down). Replaces any earlier feedback on that message, and the score and reason are shared with the Speak AI team for review.

Get usage statistics for AI Chat / chat. Returns metrics on prompt usage, optionally filtered by date range.

Export a specific AI Chat answer. Useful for saving AI-generated summaries, reports, or analysis results.

List scheduled or completed meeting assistant events with filtering and pagination.

Schedule the Speak AI meeting assistant to join and record an online meeting (Zoom, Google Meet, Microsoft Teams, or Webex). The assistant joins as a participant other attendees can see, at meetingDate or right away when meetingDate is omitted.

Remove the Speak AI assistant from an active or scheduled meeting.

Cancel and delete a scheduled meeting assistant event.

Fetch new sentences from an in-progress or just-ended meeting transcript. Identify the meeting via meetingAssistantEventId (preferred) or mediaId. Pass back the previous response's nextCursor as sinceEndInSec to receive only what's been added since.

List all custom fields defined in the workspace. Each field returns a `slug` (for example `regulator_comment`) alongside its `id`, `name`, and `type`. Put `{{field.<slug>}}` in the prompt text you send and Speak substitutes that field's value for the media before the model sees it. A slug is unique per company and never changes when the field is renamed, so prefer it over the field name. A field with no slug yet resolves by `id` in the same token. Every other tool that takes a field id wants this `id` (12 characters), never the database `_id`.

Takes no parameters.

Create a new custom field for categorizing and tagging media. The response starts with the new field's `id`; use that `id` (not `_id`) wherever a field id is needed.

Set custom field values across media in a single batch operation, overwriting existing values. Scope the update with `mediaIds`, or with `folderId` to update every media in that folder; when both are given only `mediaIds` is used. Empty values are skipped, so this cannot clear a field. Shared dashboard links cache widget data, so field and media edits can take up to about 5 minutes to show for date ranges that include today (15 at most) and up to about 17 minutes for past ranges (60 at most); any dashboard update refreshes it at once.

Update a specific custom field by ID. `name` must always be supplied (the server replaces the field config).

List the workspace's labels as a tree: groups (isGroup true) carry their labels in `labels`, and ungrouped labels sit at the top level. Each item has labelId, name, description, color, parentId, source (`speak` for Speak label sets), usageCount and isActive. Use the labelIds of non-group labels with apply_label. Anyone in the workspace can read labels.

Create a label, or a label group with isGroup true. Labels are shared by the whole workspace and are applied to transcript words with apply_label. A label can sit in one group (parentId); groups cannot be nested, and a group has no color. Names are unique among active labels under the same parent, ignoring case and extra spaces: 409 means the name is taken. Requires the labels create permission (every member by default). The change is recorded in your Speak Notifications under Label (type label).

Rename, recolor, describe, move or reorder a label or group. Send only the fields to change. parentId null moves a label to the top level. An archived label cannot be edited (restore_label first), and a group cannot take a color or a parent. 409 means another active label under the same parent already has the name. Requires the labels update permission (every member by default). The change is recorded in your Speak Notifications under Label (type label).

Archive a label so it can no longer be applied; archiving a group archives its labels too. Labels already applied to transcripts stay where they are, and restore_label undoes this. Safe to repeat. Returns archivedCount. Requires the labels delete permission (owners and admins by default). The change is recorded in your Speak Notifications under Label (type label).

Restore an archived label; restoring a group also restores its archived labels. A label whose name is now used by an active label stays archived and is counted in skippedCount. 409 means the label's own name is taken (rename the active one first); a merged label cannot be restored, and a label cannot be restored while its group is archived. Requires the labels delete permission (owners and admins by default). The change is recorded in your Speak Notifications under Label (type label).

Merge one label into another: every place the source label is applied moves onto the target (a span that had both keeps one), then the source is archived with mergedInto set. This cannot be undone by restore_label. Both must be active, non-group labels and different. Returns movedCount. Requires both the labels update and labels delete permissions; only owners and admins have labels delete by default. The change is recorded in your Speak Notifications under Label (type label).

Add ready-made label groups from Speak: sales_qa (Unprofessional, Slang, Objection, Great moment, Compliance risk), research (Pain point, Motivation, Quote for report, Surprise, Follow-up), meetings (Decision, Action item, Risk, Open question) and transcript_feedback (Wrong split, Misheard word, Wrong speaker, Bad translation). Safe to repeat: a group or label that already exists with the same name is reused, and a set whose group name is taken by a plain label is skipped (listed in skippedSets). Requires the labels create permission (every member by default). The change is recorded in your Speak Notifications under Label (type label).

List the labels applied to a media file's transcript, in transcript order, with the file's current transcriptRevision. Each item has mediaLabelId, labelIds and an anchor: startWord and endWord (inclusive word indices), exact (the labelled words), startInSec, endInSec, speakerIds and status. Status active means the same words; shifted means the transcript was edited and most of the words survived; needs_review means the words changed too much, so anchor holds a suggested range and lastResolved the last confirmed one (confirm or move it with update_media_label). Anyone who can open the file can read its labels.

Apply one or more labels to a span of words in a media file's transcript. Give the span as quote (words copied from get_transcript; this tool finds their position and the current transcriptRevision for you) or as range plus expectedTranscriptRevision. If the same span already has labels, the new ones are added to it. Check the returned anchor.exact to confirm the right words were labelled. A 409 that says the transcript changed means someone edited it after your revision was read: read the transcript again (get_transcript) and retry with the new range or quote. Nothing was saved. A 400 means the range is outside the transcript or a label is archived, a group, or not in this workspace. Requires the labels assign permission (every member by default). The change is recorded in your Speak Notifications under Label (type label).

Change a labelled span on a transcript. Do exactly one of: labelIds to replace its labels; action keep to confirm its current anchor (after the transcript was edited and its status is shifted or needs_review); or action replace with a new quote or range to move it. A 409 that says the transcript changed means someone edited it after your revision was read: read the transcript again (get_transcript) and retry with the new range or quote. Nothing was saved. Keep also answers 409 when the anchor was built on an older revision: list_media_labels again first. Requires the labels assign permission (every member by default). The change is recorded in your Speak Notifications under Label (type label).

Remove a labelled span from a transcript. The label itself stays in the workspace, and comments linked to the span stay without the link. Requires the labels assign permission (every member by default). The change is recorded in your Speak Notifications under Label (type label).

List the comment threads on a media file, with the file's current transcriptRevision. Each thread is its first comment with `replies` (oldest first). A comment on words carries an anchor (startWord, endWord, exact, times, status as in list_media_labels); a whole-file comment has none. A deleted first comment that has replies stays with an empty body and isDeleted true. Anyone who can open the file can read its comments.

Add a comment to a media file. Three kinds: on the whole file (no quote or range), on words in the transcript (quote, or range plus expectedTranscriptRevision, exactly as in apply_label), or a reply to a thread (parentId, with no span of its own). Replies go one level deep, so parentId must be a thread's first comment. A reply notifies the thread's starter in Speak, unless the starter wrote the reply. mediaLabelId links the comment to a labelled span on this file. A 409 that says the transcript changed means someone edited it after your revision was read: read the transcript again (get_transcript) and retry with the new range or quote. Nothing was saved. Requires the comments create permission (every member by default). The change is recorded in your Speak Notifications under Comment (type comment).

Edit the text of a comment. Only the comment's author can edit its text (403 otherwise). To resolve or reopen a thread, use resolve_comment. The change is recorded in your Speak Notifications under Comment (type comment).

Resolve a comment thread, or reopen it with resolved false. Only a thread's first comment can be resolved (400 on a reply). Resolving or reopening someone else's thread notifies its starter in Speak. Requires the comments update permission (every member by default). The change is recorded in your Speak Notifications under Comment (type comment).

Delete a comment. Deleting a thread's first comment keeps its replies visible under an empty placeholder. You can always delete your own comments; deleting someone else's needs the comments delete permission (owners and admins by default), otherwise 403. The change is recorded in your Speak Notifications under Comment (type comment).

List automation rules in the workspace, with paging and filters.

List the names and ids of active automations that contain an AI chat (magic prompt) step. Inactive automations and automations without an AI chat step are not included; use list_automations for the full list.

Takes no parameters.

Get detailed information about a specific automation rule, including its trigger and step graph.

Get the run history (executions) for an automation, with paging and optional status filter.

Create an automation: a trigger plus ordered steps (V2 graph model). The automation is active by default and then runs on its own every time its trigger fires. Depending on its steps, each run can send email to any address, post to the workspace's Slack, send HTTP requests to any webhook URL, fetch a file from a URL into Speak, run actions in connected third-party apps through Composio. An inbound-webhook trigger creates a public URL that accepts payloads (returned as inboundWebhook.inboundUrl). A Composio app-event trigger subscribes to events on the connected third-party account. Valid trigger and step types come from list_automation_triggers and list_automation_actions. To map inbound-webhook payload fields, send a test payload to the URL with ?test=1, read the tokens with get_inbound_webhook, then call update_automation.

Update an existing automation rule. This replaces the whole automation (name, trigger, and steps), so fetch the current values with get_automation first and pass them all back with your changes. The saved steps run automatically on later triggers and can send email, post to Slack, call webhook URLs, and run actions in connected third-party apps. Changing a Composio app-event trigger updates the subscription on that third-party account.

Toggle an automation rule between active and inactive. This flips the current state, so call get_automation first if you need to know which way it will flip. An active automation runs on its own every time its trigger fires, and its steps can send email, post to Slack, call webhook URLs, and run actions in connected third-party apps. For a Composio app-event trigger, this also creates or removes the event subscription on the connected third-party account.

Activate or deactivate multiple automations at once. An active automation runs on its own every time its trigger fires, and its steps can send email, post to Slack, call webhook URLs, and run actions in connected third-party apps. For Composio app-event triggers, this also creates or removes the event subscription on the connected third-party account.

Set the folder scope for multiple automations at once. Pass an empty folderIds array to remove the folder restriction (run on all folders).

Manually run one or more automations against one or more media items now (outside the normal trigger). Only active automations run; inactive or unknown automation ids and unknown media ids are skipped without an error. The runs happen in the background and this returns only an acknowledgement, so check results with get_automation_runs. Every step executes for real: it can send email, post to Slack, call webhook URLs, and run actions in connected third-party apps.

Permanently delete an automation rule. If it has an inbound webhook URL, that URL stops accepting payloads, and any event subscription it holds on a connected third-party account through Composio is removed.

Get one automation run in full: every step, in dependency order, with what it produced and why it stopped. Use this after test_automation or to explain a run that went the wrong way. On a branched automation the run's overall status is not the whole story — a filter that stops one leg marks the entire run "killed" even when the other leg finished its work — so read the per-step summary this returns, not just the status.

Aggregate run counts for an automation over a period — how many completed, failed, or were stopped.

Run one automation once against one media item to see which way it branches. This is a real run, not a dry run, and it works on inactive automations too. Only the run's own status notifications are suppressed and translation steps are skipped. Notify steps still send their email or Slack message, outbound webhooks still fire, and Composio actions still run against the connected third-party account. Confirm with the user before testing an automation that sends anything outside Speak. It needs a mediaId and sends no webhook payload, so on an inbound-webhook automation the payload tokens resolve to empty. Returns a runId; read the result with get_automation_run.

Check a step graph without saving anything. Reports the same problems create_automation and update_automation would refuse — branch wiring, rules a condition cannot actually read, shapes the Speak web editor could not reopen — plus non-blocking warnings. Use it to iterate on a branched automation instead of discovering the problems one failed save at a time.

Show a saved automation's steps as an indented branch tree instead of a flat list. Worth calling before update_automation, which replaces the whole automation: editing one leg means re-sending every step with its dependsOn intact, and this shows what the shape currently is.

List the apps in Speak's automation catalog: Speak's built-in apps plus, when enabled, third-party apps available through Composio, each marked connected or not_connected for this user. Read-only: the list comes from Speak's own catalog and the user's saved connections, and no third-party service is called. Use the app slugs with list_automation_triggers and list_automation_actions.

Takes no parameters.

List the trigger types available in the automation catalog. Optionally filter by app.

List the step types (actions) available in Speak's automation catalog, optionally for one app slug, plus the fields each filter or condition step can test. Read-only: served from Speak's own catalog and the user's saved connections, with no third-party calls. Listing an action does not run it.

Create an outbound webhook. From then on, Speak automatically POSTs a JSON payload to callbackUrl, an external endpoint, for each subscribed event (event type, ids such as mediaId or folderId, state, and for chat events the prompt and answer text).

List all configured webhooks in the workspace.

Takes no parameters.

Update an existing webhook. This is a partial update — only the fields you supply are changed; `callbackUrl` is always required, the rest are left untouched if omitted.

Provision a standalone inbound webhook and get its public receive URL (inboundUrl) BEFORE creating an automation. Webhook-first flow: provision, send a test payload to the URL (append ?test=1 to only capture a sample without running anything), inspect mappable payload paths with get_inbound_webhook, then pass the webhookId as trigger.webhookId to create_automation.

Takes no parameters.

Get an inbound webhook's public receive URL, captured sample payload, and the ready-to-paste {{trigger.payload.*}} tokens for mapping payload values into automation steps (speak-upload name/sourceUrl, fieldsMap custom-field values, notify/outbound-webhook templates). Pass either the webhookId or the automationId of an inbound-webhook automation. If no sample has been captured yet, send a test payload to the inboundUrl first (append ?test=1 to capture without running the automation).

Get the delivery log for an inbound webhook: each received request with its HTTP acknowledgement status (200 = sample captured, 202 = accepted and run started, 401/403 = rejected) and the automation run it started. Use get_automation_runs for the run outcomes themselves.

Permanently delete an outbound webhook and its delivery attempt history; its endpoint stops receiving notifications. Cannot be undone.

Deep search across all media transcripts, insights, and metadata. Returns matching media with sentiment data, tags, and content excerpts. Use this to find specific topics, keywords, or themes across your entire library. For filtering by media type, folder, tags, or speakers, use the filterList parameter. Results are scoped by date range — defaults to current year if not specified.

Create a highlight clip from one or more media files by specifying time ranges. Clips are processed asynchronously (states: queued, processing, completed, failed) — use get_clips to check status. Maximum total clip duration is 30 minutes. Use multiple timeRanges to stitch segments from different media files together.

List clips, optionally filtered by folder or media files. If clipId is provided, returns a single clip with its download URL (when processed).

Update a clip's title, description, or tags.

Permanently delete a clip and its associated media file.

High-level automation builder: create (or update) a Speak automation from a friendly spec without knowing the wire format. Accepts folder/custom-field NAMES (resolved to ids; missing folders are auto-created), payload.<path> shorthand for webhook tokens, and simple step types (filter, branch, upload, ai_chat, translate, notify, call_webhook). For inbound-webhook automations the result includes the receive URL and mappable payload tokens. create_automation takes the raw wire format instead. Passing automationId replaces that whole automation. The automation is active by default and then runs on its own every time its trigger fires: upload steps fetch a file from any URL, slack notify steps post to the workspace's Slack, and call_webhook steps send HTTP requests to any URL. An inbound_webhook trigger creates a public URL that accepts payloads.

Upload and transcribe media from a URL — a direct/public file URL, OR a shareable social/video page link, which Speak resolves to the underlying media automatically. Supported page links: YouTube, TikTok, Instagram, X/Twitter, Facebook, Reddit, SoundCloud, Twitch, Dailymotion, Streamable, Snapchat, Pinterest, Tumblr, Bilibili, VK, OK.ru and Rutube. Vimeo and Loom page links are not supported. Each accepted upload creates a media item. Returns media_id immediately; after this returns, poll get_media_status until state is 'processed' (typically 1-3 min for under 60min audio), then call get_media_insights for AI summaries. This async pattern is required for remote MCP transports — long blocking calls die at proxy idle timeouts.

Import up to 25 audio or video URLs in one call. Each URL is imported the same way as upload_and_analyze, and transcription starts for each one. At most 5 uploads run at once. Each URL may be a direct public file URL or a page link from a supported platform, which the server resolves to the underlying media. Supported page links: YouTube, TikTok, Instagram, X/Twitter, Facebook, Reddit, SoundCloud, Twitch, Dailymotion, Streamable, Snapchat, Pinterest, Tumblr, Bilibili, VK, OK.ru and Rutube. Vimeo and Loom page links are not supported. Each accepted upload creates a media item. A failed URL does not stop the others, and the result lists every URL as uploaded (with its mediaId) or failed (with the reason). Returns once the uploads are accepted. Use get_media_status per mediaId, or list_media on the folder, to follow processing.

Upload a local file to Speak AI for transcription and analysis. Reads the file from disk, gets a pre-signed S3 URL, uploads the file, then creates the media entry. Works with any audio or video file on the local filesystem. Each upload creates a media item. After upload, use get_media_status to poll for completion, then get_transcript and get_media_insights.

List the users (members) in the workspace/company, with their ids, names, emails, and permissions. Use the returned _id values when assigning members to user groups.

List all user groups in the company. Each group includes its members (hydrated names/emails) and member ids. Use this to discover group ids and current membership before updating or deleting a group.

Takes no parameters.

Create a new user group and assign members. Member ids come from list_users. Fails with a 409 if a group with the same name already exists in the company.

Update a user group's name and member list. NOTE: the users array is a FULL REPLACEMENT, not a delta — any member id you omit is removed from the group. Fetch the current members with list_user_groups first and send the complete list.

Permanently delete a user group. The users themselves are not deleted, but members lose any access that was shared with the group (for example dashboards assigned to it).

List all analytics dashboards the caller can access, including share state and each dashboard's current `revision` (needed for update_dashboard).

Takes no parameters.

Get a single dashboard's full spec: title, description, source, date range, sections, widgets, and the current `revision` (pass that revision back to update_dashboard). Saved viewer settings, including settings.profiles groups (fieldId, label, imageShape, and entries with id, name, description, link, imageKey, and a signed imageUrl preview that is ignored if sent back), are included when the server returns them.

Discovery + how-to helper for building and customizing dashboards. Returns every widget type with what it shows and the exact strict `config` shape it accepts, the shared vocabulary (metric grammar, groupBy, per-widget binding, filters, thresholds, sources, date-range presets, sections), design rules for composing a dashboard that reads well, two complete worked example payloads, and tips for managing dashboards. Call this before create_dashboard / update_dashboard.

Takes no parameters.

Create an analytics dashboard. Only `title` is required — source defaults to the whole workspace and dateRange to last30days. Add widgets by listing their types (the MCP assigns ids and lays them out automatically), scope with source ({type:"folders",folderIds} | {type:"team"} | {type:"workspace"}) and dateRange ({preset}), and optionally group widgets into sections. Design guidance: lead with a narrative widget as the first widget; group sections by the QUESTION they answer, not by widget type; don't pad — every widget earns its place (aim for 4-16 widgets on a full build); if something can't be expressed by the widget catalog, put it in a narrative widget's focus instead of faking it. Call list_dashboard_widgets first for the widget catalog, config vocabulary, design rules, and full examples. Creating a dashboard does not share it publicly; only share_dashboard creates a public link. If settings.feedback.sheetWebhookUrl is set, each Feedback submission made on the shared dashboard is posted to that external Google Apps Script URL. Shared dashboard links cache widget data, so field and media edits can take up to about 5 minutes to show for date ranges that include today (15 at most) and up to about 17 minutes for past ranges (60 at most); any dashboard update refreshes it at once. Viewer settings (the settings input): Do not pass settings unless the user explicitly asks to change this dashboard's viewer settings. Saving fields, feedback or fieldEdits moves that dashboard onto the settings flow immediately: its media pages use these groups and this Feedback setup from then on. Each section (fields, feedback, fieldEdits, labels, comments, profiles) replaces that whole section when sent; a section left out keeps its saved value. Call get_dashboard first and resend every key of the section you change; a key left out resets to its default. Get field ids from list_fields. Ids that are not the company's fields are dropped when saving and returned in droppedFieldIds. When

Update a dashboard. Two modes. (1) Metadata-only: pass just icon/assignTo/filters/isDefault/settings, with no spec fields and no revision, except that saving settings.profiles also needs the `revision` from get_dashboard (a stale one returns a 409). (2) Spec update: pass the FULL spec — title, source, dateRange, sections, widgets — plus `revision`. Widgets and sections are REPLACED, not merged, so call get_dashboard first and resend everything you want to keep. `revision` is the optimistic-concurrency token from get_dashboard/list_dashboards: the server accepts the write only if it still matches, then increments it. A 409 conflict means another writer saved first — re-fetch with get_dashboard, rebuild your changes on the fresh spec, and retry with the new revision. If settings.feedback.sheetWebhookUrl is set, each Feedback submission made on the shared dashboard is posted to that external Google Apps Script URL. Shared dashboard links cache widget data, so field and media edits can take up to about 5 minutes to show for date ranges that include today (15 at most) and up to about 17 minutes for past ranges (60 at most); any dashboard update refreshes it at once. Viewer settings (the settings input): Do not pass settings unless the user explicitly asks to change this dashboard's viewer settings. Saving fields, feedback or fieldEdits moves that dashboard onto the settings flow immediately: its media pages use these groups and this Feedback setup from then on. Each section (fields, feedback, fieldEdits, labels, comments, profiles) replaces that whole section when sent; a section left out keeps its saved value. Call get_dashboard first and resend every key of the section you change; a key left out resets to its default. Get field ids from list_fields. Ids that are not the company's fields are dropped when saving and returned in droppedFieldIds. When feedback.isEnabled is true, pass a non-empty feedback.fieldIds (score fields) rather than leaving it empty. Only set feedba

Soft-delete a dashboard. This also deactivates its public share link.

Clone an existing dashboard into a new dashboard owned by the caller. The copy keeps the source's widgets (same widget ids), sections, filters, and viewer settings, gets a "<name> (copy)" title, has no shared users and no public link, and starts at revision 0. Edit it afterwards with update_dashboard.

Enable public sharing for a dashboard and return its share token + embed id. WARNING: by default the public link resolves with no passphrase, so anyone with the token can view the dashboard data until an owner sets one.

Compute a speakers breakdown for a given folder scope, date range, and field filters. Standalone analytics — does not require a dashboard to exist.

List the voice agents in the company (newest first). Each agent includes its agentId, name, personality/instructions, and voice/stt/llm/avatar configuration. Use the returned agentId with get_voice_agent or to filter list_voice_conversations.

Takes no parameters.

Fetch a single voice agent by its agentId. Returns the full agent configuration. A cross-company agentId returns 404.

List the company's voice conversations (newest first). Optionally filter to a single agent. Each conversation includes its conversationId, agentId, status, duration, transcript summary, and usage/costs. Use conversationId with get_voice_conversation for the full record.

Fetch a single voice conversation by its conversationId, including transcript, usage, costs, and analysis. A cross-company conversationId returns 404.

Owner analytics for one voice agent over a date range. Returns the range used; conversation totals with completion rate, average duration and returning callers; conversations per day split into web and phone; where callers are, their devices, browsers and traffic sources; web callers who left without saying anything and the number of open knowledge gaps (questions the agent could not answer); leads captured, handoffs and action items; engagement, sentiment, top topics, end reasons and satisfaction; busiest hours, weekdays and languages; and web versus phone counts. Test calls are left out unless includeTests is true, and the count of test calls is always returned. Leave start empty for all time; a start more than 5 years before end is moved up to 5 years. A cross-company agentId returns 404.

Create a voice agent. Requires the OWNER or ADMIN role. name, personality, instructions, and voice (provider + voiceId) are required; everything else can be set now or later with update_voice_agent. Call list_voice_avatars or list_voices first to get valid ids.

Update a voice agent. Requires the OWNER or ADMIN role. Send only the top-level fields you want to change; agentId, companyId, and userId are immutable and silently dropped if sent. Object fields (voice, llm, avatar, chatSettings) each replace the stored object whole, not merge -- fetch get_voice_agent first and resend every key of an object field you're not fully replacing.

List the video avatars available to attach to a voice agent (your company's own uploads plus the shared system catalog). Use the returned avatarId with create_voice_agent or update_voice_agent.

Takes no parameters.

List the text-to-speech voices available to a voice agent. Use the returned provider/voiceId with create_voice_agent or update_voice_agent's voice field. When an agent's llm.model is a Live (speech-to-speech) model, its usable voices are a fixed, smaller set scoped to that model instead of this full catalog.

Takes no parameters.

Delete a voice agent. Requires the OWNER or ADMIN role. The agent is marked deleted and no tool can restore it: it stops appearing in list_voice_agents, and its share link, embedded widget, questions, and test suite stop working. Its stored data is not erased, past conversations stay in list_voice_conversations, and phone numbers assigned to it are not released.

Create a new voice agent from a plain-English description, via an LLM call. Requires the OWNER or ADMIN role. Saves a draft agent, then generates and saves its name, personality, instructions, chat settings, and default voice, speech-to-text, and LLM settings. Does not assign a phone number. The response includes the new agentId plus either the generated agent, or needsFollowUp: true with a followUpQuestion when the prompt is too vague. In that case the draft agent still exists with placeholder settings; call generate_voice_agent_config on that agentId with more detail.

Run the same prompt-to-config generation as create_voice_agent_from_prompt, but against an existing agent instead of creating a new one. Requires the OWNER or ADMIN role. On success the generated config is saved onto the agent immediately, overwriting its current name, personality, instructions, chat settings, and voice, speech-to-text, and LLM settings. If the prompt is too thin and manualInstructions was not sent, the response has needsFollowUp: true with a follow-up question instead — call this again with more detail.

Discovery + how-to helper for building and operating a Speak AI voice agent end to end. Returns the four configuration pieces every agent is built from, which tool covers each one, the recommended build order, and how testing/questions/knowledge-base/intelligence tools chain together after the agent exists. Call this before create_voice_agent or create_voice_agent_from_prompt if you are not already familiar with this tool surface.

Takes no parameters.

Get a voice agent's test suite (its scenarios and run settings). Returns null in data.suite if none has been created yet — not a 404.

Create or update a voice agent's test suite. Requires the OWNER or ADMIN role. Upserts. Send the full scenarios array you want to keep — it replaces the stored one, it is not merged.

Auto-generate a default test suite for a voice agent from its configuration (name, personality, instructions, welcome message, topics to avoid), via an LLM call. Requires the OWNER or ADMIN role. Overwrites the suite's existing scenarios.

Start a test run of a voice agent's scripted test suite. The run sends each enabled scenario's user messages to the agent as text, in order, and grades every criterion; it does not place phone calls. Requires the OWNER or ADMIN role. Returns the run in queued status; poll get_active_voice_test_run for progress and results. Returns 404 if the agent or its test suite does not exist, and 409 if the suite has no enabled scenarios or the agent already has a queued, running, or paused run.

Get a voice agent's currently active test run (queued, running, or paused). Returns null in data.run if none is active — not a 404.

Pause a voice agent's test run. Requires the OWNER or ADMIN role. Valid only from queued or running. Takes effect after the current scenario finishes.

Resume a paused voice agent test run, transitioning it back to running. Requires the OWNER or ADMIN role. Valid only from paused. The run continues from the next scenario.

Cancel a voice agent test run. Requires the OWNER or ADMIN role. Valid from queued, running, or paused. The run stops at its next AI call. Terminal — a cancelled run can never be resumed.

List a voice agent's test runs, most recent first. Capped at 100 regardless of limit.

Get a test run's full detail, including scenarioResults and recommendations. Scoped to your company; agentId is not used to filter this lookup, only runId.

Apply a test run recommendation's quick action to the agent (e.g. patch_instructions appends the suggested fix to the agent's instructions). Requires the OWNER or ADMIN role.

Get a voice agent's best-scoring completed test run, used to detect regressions on later runs. Returns null in data.baseline if no run has completed yet.

Get completed-run score points for a voice agent, most recent first, for charting. Capped at 100 regardless of limit. Only status=completed runs are included.

List the questions configured on a voice agent, in the order it asks them. Each is an agent-level instance of a question template with its own required/attempts/no-response settings and optional field mapping.

Fetch a single voice agent question by its fieldId, scoped to your company.

Attach a question template to a voice agent. Requires the OWNER or ADMIN role. agentId and templateId are both required and must belong to your company (or, for templateId, be a public system template) — 404 if either isn't found. Returns 409 if the agent already has an enabled question whose template has the same name, ignoring case and spacing (they save to the same answer key); disable or delete that question first, or create this one with enabled: false.

Partially update a voice agent question — only the fields you send are changed. Requires the OWNER or ADMIN role. agentId and templateId are fixed after create; sending them is silently dropped. Returns 409 when setting enabled: true on a disabled question while another enabled question on the same agent has a template with the same name, ignoring case and spacing (they save to the same answer key); other edits to an existing duplicate still succeed.

Permanently remove a question from a voice agent and decrement the underlying template's usageCount. Requires the OWNER or ADMIN role. The template itself is not deleted and can be attached to another agent later.

Set the order a voice agent asks its questions in. Requires the OWNER or ADMIN role. Bulk-writes the order value on each listed question (written directly, not resequenced), then returns the agent's full question list in its new order. Entries whose fieldId doesn't belong to agentId are silently skipped.

List the question templates visible to your company: Speak's shared system templates, plus your own company's templates. Use the returned templateId with create_voice_question.

Create a company-scoped question template — the "custom question" a user names themselves rather than picking from Speak's shared library. Requires the OWNER or ADMIN role. The server stamps companyId and forces isSystemTemplate to false, so this template is only ever visible to your company.

List a voice agent's pending knowledge-base gaps — questions callers asked that the agent answered with low confidence or an explicit "I don't know," surfaced automatically after calls. Up to the 50 most recent pending gaps, newest first.

Trigger knowledge-base gap analysis over a voice agent's recent calls. Requires the OWNER or ADMIN role. Runs in the background and returns immediately — new gaps appear in list_voice_kb_gaps once analysis finishes, not synchronously with this response.

Write a knowledge-base gap's answer into the voice agent's attached knowledge base as a new document, and mark the gap added. Requires the OWNER or ADMIN role. Fails with 409 if the gap was already added or dismissed, or if the agent has no knowledge base collection to write into.

Mark a voice agent's knowledge-base gap dismissed without writing anything to the knowledge base. Requires the OWNER or ADMIN role.

List a voice agent's pending FAQ suggestions — questions multiple callers asked in similar form, clustered and drafted into a reusable question/answer pair. Up to the 20 largest clusters, largest first.

Trigger FAQ clustering over a voice agent's recent calls. Requires the OWNER or ADMIN role. Runs in the background and returns immediately — new suggestions appear in list_voice_faq_suggestions once generation finishes, not synchronously with this response.

Write an FAQ suggestion's question/answer into the voice agent's attached knowledge base as a new document, and mark the suggestion added. Requires the OWNER or ADMIN role. Fails with 409 if the suggestion was already added or dismissed, or if the agent has no knowledge base collection to write into.

Edit a still-pending FAQ suggestion's question and/or answer before adding it. Requires the OWNER or ADMIN role. Fails with 400 if the suggestion was already added or dismissed.

Mark a voice agent's FAQ suggestion dismissed without writing anything to the knowledge base. Requires the OWNER or ADMIN role.

List the knowledge documents/links a voice agent searches during calls — separate from KB gaps and FAQ suggestions, which are the self-improvement layer that surfaces what an agent is missing, not the content itself.

Add one document/link to a voice agent's knowledge base. Requires the OWNER or ADMIN role. The server does not fetch the URL; it embeds the title, description, and URL slug so the agent can retrieve the link during live calls.

Add up to 100 documents/links to a voice agent's knowledge base in one call. Requires the OWNER or ADMIN role. The URLs are not fetched; each entry's title, description, and URL slug is embedded independently. Use this instead of calling create_voice_agent_resource in a loop.

Partially update a voice agent resource — send at least one field. Requires the OWNER or ADMIN role. agentId cannot be changed. Changing url, title, or description re-triggers embedding.

Soft-delete a voice agent resource — it stops appearing in lists and the agent stops searching it, but the document is not physically removed. Requires the OWNER or ADMIN role.

Advisory only — compares a voice agent's current instructions against anchors/original intent/recent call summaries you supply and suggests up to 3 patches. Requires the OWNER or ADMIN role. Nothing is written; pass a suggestion's suggestedPatch to apply_voice_instruction_gap to actually apply it.

Insert a suggested instruction patch into a voice agent's instructions and persist the result. Requires the OWNER or ADMIN role. suggestedPatch is typically taken directly from analyze_voice_instruction_gaps.