Chapter 12 GET POST

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/POST https://api-guide.bbbserver.com/bigbluebutton/api/publishRecordings?<parameter>&checksum=replace-with-checksum

Both GET and POST methods are supported. When using POST, send parameters as application/x-www-form-urlencoded in the request body.

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

POST Request with cURL

curl --request POST \
    --url "https://api-guide.bbbserver.com/bigbluebutton/api/publishRecordings" \
  --header "Content-Type: application/x-www-form-urlencoded" \
    --data "recordID=replace-with-recording-id&publish=true&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 but cannot be accessed by viewers.
  • 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.

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 permanently removes the files from the server and cannot be undone.

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.

Unpublishing a recording makes its playback URL inaccessible. Users who are currently viewing the recording may experience an interruption depending on how the playback client handles the change.