API version: 4.x latest 3.x

You are viewing the API documentation for BigBlueButton 3.x. The current version is BigBlueButton 4.x. Planning an upgrade? The migration guide lists every change your API calls need.

Chapter 12 GET

publishRecordings – Publish/Unpublish

The publishRecordings endpoint toggles the visibility of one or more recordings. You can publish recordings to make them accessible via their playback URL, or unpublish them to hide them from viewers while keeping the files on the server.

Endpoint

GET https://api-guide.bbbserver.com/bigbluebutton/api/publishRecordings?<parameter>&checksum=replace-with-checksum

This endpoint only supports GET requests. POST requests are not accepted.

Parameters

Parameter Type Description
recordID String Required. A comma-separated list of recording IDs to publish or unpublish. You can specify one or more IDs in a single request.
publish Boolean Required. Set to true to publish the recordings (make them accessible), or false to unpublish them (hide them from viewers).

Example Request

Publish a Single Recording

GET https://api-guide.bbbserver.com/bigbluebutton/api/publishRecordings
    ?recordID=replace-with-recording-id
  &publish=true
    &checksum=replace-with-checksum

Unpublish Multiple Recordings

GET https://api-guide.bbbserver.com/bigbluebutton/api/publishRecordings
    ?recordID=replace-with-recording-id-1,replace-with-recording-id-2
  &publish=false
    &checksum=replace-with-checksum

Example Response

Success

<response>
  <returncode>SUCCESS</returncode>
  <published>true</published>
</response>

Error — Recording Not Found

<response>
  <returncode>FAILED</returncode>
  <messageKey>notFound</messageKey>
  <message>We could not find recordings</message>
</response>

Error Responses

messageKey Description
checksumError The checksum is invalid. Verify that you are using the correct shared secret and that the checksum algorithm matches the server configuration.
missingParamRecordID The required recordID parameter was not provided.
missingParamPublish The required publish parameter was not provided.
notFound No recording was found matching any of the specified recording IDs.

Tips

Use the getRecordings endpoint to retrieve the current publish state of your recordings before toggling their visibility. The published field in the response indicates whether each recording is currently visible.

  • A published recording is accessible via its playback URL. An unpublished recording remains on the server.
  • This action is fully reversible — recordings can be published and unpublished any number of times.
  • You can batch-process multiple recordings by passing a comma-separated list of recording IDs in a single request.
  • If you want to permanently remove a recording instead of just hiding it, use the deleteRecordings endpoint.

Deviation between BigBlueButton and bbbserver.de
If you unpublish a recording in bbbserver Integration-API, it is shown as unpublished in the API and external services process it accordingly. However, the recording itself can still be opened if the playback link is known.

When you pass multiple recording IDs and at least one of them is valid, the call will return SUCCESS. Only if none of the provided IDs match an existing recording will the server return FAILED with the notFound error.

Frequently Asked Questions

Unpublishing a recording hides it from viewers but keeps the recording files on the server. You can re-publish it at any time. Deleting a recording moves it to the deleted state: it can no longer be played back and cannot be restored through the API.

Yes. Pass a comma-separated list of recording IDs in the recordID parameter. All specified recordings will be set to the same publish state in a single request.

If at least one of the provided recording IDs is valid, the call returns SUCCESS and applies the change to all valid recordings. The server only returns FAILED with notFound if none of the IDs match an existing recording.

Use the getRecordings endpoint and inspect the published field in the response XML. It will be set to true for published recordings and false for unpublished ones.