---
title: "Update Embed"
method: PUT
path: "/embed/{embedId}"
tags: ["Media Embed"]
---

# Update Embed

`PUT /embed/{embedId}`

## Request

- Base URL: `https://api.speakai.co/v1`
- URL: `https://api.speakai.co/v1/embed/{embedId}`
- Auth: API key in header `x-speakai-key` and API key in header `x-access-token`

Update an existing Embed Media Player.

- Make sure to pass in path `embedId` to update your existing player

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

## Path parameters

- `embedId` string, required

## Request body

- object
  - `meta` object: 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.
    - `backgroundImg` string: 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` string: 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` object[]: 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.
      - `url` string: Where the button sends the viewer. Required on every button you send.
      - `label` string: The text shown on the button. Required on every button you send.
    - `features` object[]: 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.
      - `name` string: 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` boolean: Set it to true to show this category to viewers and false to hide it. Required on every feature you send.
      - `isCustom` boolean: 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.
    - `isTitle` boolean: 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` boolean: 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` boolean: 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` boolean: 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` boolean: 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` boolean: 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` boolean: 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` boolean: 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` string: 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` string: 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` string: 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` string: 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` string: 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` 'light' | 'dark' | '': 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` string: 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` string: 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` object: 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.
      - `isEnabled` boolean: 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` boolean: Set it to true to ask viewers for their name as well as their email. Optional. New embeds start with this off.
      - `requireConsent` boolean: 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` string: 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` boolean: 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` boolean: 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` 'public' | 'private': 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.
  - `password` string: 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` string: 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` string[]: 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` 'audio' | 'video' | 'text' | 'media' | 'csv': 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.
  - `embedType` 'mediaPlayer' | 'repository' | 'dashboard': 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.
  - `size` string: Accepted but ignored. The stored iframe size is not changed by this endpoint. Optional. An empty string is allowed.
  - `isActive` boolean: Accepted but ignored. This endpoint does not turn an embed on or off. Optional.
  - `_id` string: 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.

## Response `200`

OK

- object
  - `status` string
  - `data` object
    - `_id` string
    - `meta` object
      - `backgroundImg` string
      - `callToActionButtons` object[]
        - `url` string
        - `label` string
      - `features` object[]
        - `name` string
        - `isActive` boolean
      - `isDataVizDownloadable` boolean
      - `isDescription` boolean
      - `isSEOIndexing` boolean
      - `isRemarks` boolean
      - `isPromptAsk` boolean
      - `isPromptHistory` boolean
      - `isTitle` boolean
      - `logo` string
      - `primaryColor` string
    - `mediaId` string
    - `folderIds` unknown[]
      - unknown
    - `embedType` string
    - `isActive` boolean
    - `isDeleted` boolean
    - `analytics` unknown[]
      - unknown
    - `companyId` string
    - `userId` string
    - `mediaType` string
    - `token` string
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
    - `__v` integer
    - `password` string

---

[API](https://skmtc.dev/speakai/apis/speak-ai-api.md) · [All operations](https://skmtc.dev/speakai/apis/speak-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/speakai/apis/speak-ai-api/revisions/52d777e6d46e?raw)