Media Embed

Update Embed

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.

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

Path parameters

embedIdstring required

Request body

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.

passwordstring

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.

mediaIdstring

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.

folderIdsstring[]

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.

sizestring

Accepted but ignored. The stored iframe size is not changed by this endpoint. Optional. An empty string is allowed.

isActiveboolean

Accepted but ignored. This endpoint does not turn an embed on or off. Optional.

_idstring

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

OK

statusstring

Changes

No recorded changes to this operation across all 2 revisions of this API.