Studio Session Guide

The Bluebeam Developer Portal, for integrations development, is only available to active customers, channel partners, and software partners in the US, AU, DE, UK, and SE regions.

Think of a Studio Session like a digital conference room where PDF drawings can be marked up either simultaneously or asynchronously. This guide covers the general life cycle of a Studio Session and includes code examples. To learn more about Studio and Studio Sessions in general, visit our Studio FAQ page.

You can follow along with this guide and try many of the call outs in the Studio section of our API docs. See our Get started in the Bluebeam Developer Portal guide for instructions on how to get a valid access token.

There are region-specific base URLs that apply to all endpoints:

- US: https://api.bluebeam.com

- DE: https://api.bluebeamstudio.de

- AU: https://api.bluebeamstudio.com.au

- UK: https://api.bluebeamstudio.co.uk

- SE: https://api.bluebeamstudio.se

For example, https://api.bluebeam.com/publicapi/v1/sessions in the US would be https://api.bluebeamstudio.com.au/publicapi/v1/sessions in AU.

Studio Sessions lifecycle

The lifecycle of a Studio Session can be split up into 4 parts:

  1. Initialization – Opens up the "digital conference room"

  2. Add PDFs to the Session for viewing and mark up

  3. Add users to the Session so they can view and mark up

  4. Finalization – Closes the Session and returns the marked up PDFs to their originating system

The first phase of a Studio Session's lifecycle is its creation. To begin, make a POST command to the Sessions endpoint with the following parameters.

Endpoint

copy 
https://api.bluebeam.com/publicapi/v1/sessions

Be sure to include client_id in the header of your request.

Request parameters

Name

Description

Value Type / Possible Values

Name

Session Name

String

Notification

true: Current user will be subscribed to email notifications about changes to this Session.

false: Current user will not be subscribed to email notifications about changes to this Session.

Boolean

Restricted

true: Restricts the Session to only email addresses that have been invited or added.

false: Leaves the Session open to anyone who has the 9-digit Session ID.

Boolean

SessionEndDate

Once this date is reached, all participants except for the Host will be removed from the Session.

Must be formatted in UTC format.

DefaultPermissions

This permission set will apply to all users added to this Session except for the Host (the current user). The Host gets full control.

Define types of permissions and permissions themselves below.

Permission

Description

Value Type / Possible Values

Type

Type of permission

SaveCopy – Allow attendees to Save As.

PrintCopy – Allow attendees to print PDFs included in the Session.

Markup – Allow attendees to place markups.

AddDocuments – Allow attendees to add new documents to the Session.

FullControl – Give attendees admin rights to the Session.

MarkupAlert – Allow attendees to send and receive markup alerts during the Session.

Allow

Permission state

Allow, Deny, Default

Session End Date
Session End Dates are not required, but if a Session End Date is selected, participants of the Session will be notified via email at 7 days, 2 days, and 24 hours prior to the expiration date.

cURL example

copy 
cURL [https://api.bluebeam.com/publicapi/v1/sessions](https://api.bluebeam.com/publicapi/v1/sessions) \
-H "Authorization: Bearer {valid access_token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: [your client_id]" \
-d '{

    "Name":"Pied Piper Acquisition Review",

    "Notification": true,

    "Restricted": true,

    "SessionEndDate": "2016-08-17T21:09:07.5174221Z",

    "DefaultPermissions":[  
      {  
        "Type":"SaveCopy",  
        "Allow":"Allow"  
      },  
      {  
        "Type":"PrintCopy",  
        "Allow":"Allow"  
      },  
      {  
        "Type":"Markup",  
        "Allow":"Allow"  
      },  
      {  
        "Type":"MarkupAlert",  
        "Allow":"Allow"  
      },  
      {  
        "Type":"AddDocuments",  
        "Allow":"Deny"  
      }  
    ]
}' \
-X POST

Permissions
Current Studio users are often accustomed to specific Permissions defaults. It's always a good idea to either check what the default permissions should be or allow users to choose their permissions. When using the Bluebeam API to set permissions, 'Deny' is the default value.

Response Body

copy 
{
    "$id": "1",
    "Id": "123-456-789"
}

The next step is to add the PDF files. Adding files is a 3-step process:

  1. Create the Metadata Block for the file via the Bluebeam API

  2. Upload the file directly to AWS

  3. Confirm upload via the Bluebeam API

Note: Studio Sessions do not support PDF/A files.
Because PDF/A is an archival format, it does not allow editing and will cause step 4, below, to fail.

Endpoint

copy 
https://api.bluebeam.com/publicapi/v1/sessions/{sessionId}/files

Parameters

Name

Description

Value Type / Possible Values

Name

Name of file

String ending in ".pdf"

Source

Source path; this may help you identify where the file came from later on in the process

String

Size

File size; leave null for server to calculate

Integer

CRC

Leave null for server to calculate

String

cURL example

copy 
cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files) \
-H "Authorization: Bearer {valid access_token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: [your client_id]" \
-d '{  
      "Name":"Pied_Piper_Acquisition.pdf",  
      "Source":"[https://portfolio.raviga.com/primarybets/piedpiper/legaldocs/Pied_Piper_Acquisition.pdf](https://portfolio.raviga.com/primarybets/piedpiper/legaldocs/Pied_Piper_Acquisition.pdf)"
    }' \
-X POST

Example Response

copy 
{
  "Id": 1234567
  "UploadUrl":"{upload file to this URL}"
  "UploadContentType":"Application/PDF"
}

Upload window
Upload URL is valid for 10 minutes to start upload.

Once you have a Metadata Block placeholder for your file, make a PUT request to the returned UploadURL from the previous POST request. In your PUT request, include the following in the header:

  • "x-amz-server-side-encryption" with value "AES256"

  • "Content-Type" with value "application/pdf"

Endpoint

copy 
https://api.bluebeam.com/publicapi/v1/sessions/{sessionId}/files/{id}/confirm-upload

cURL example

copy 
cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files/1234567/confirm-upload](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files/1234567/confirm-upload) \
-H "Authorization: Bearer {valid access_token}" \
-H "client_id: [your client id]" \
-X POST

Response

If successful, you will get a 204 response. For errors, see the Common HTML response codes at the bottom of our Authentication Guide .

 

Now that you have a Session with PDFs in it, it's time to add users to the Session. The initiator of the Session (the current user) automatically becomes the Host of the Session and is automatically added to the Session's users. More users can always be added while the Session is active. There are 2 methods for adding users:

This method is best to invite users who may not yet have a Studio account. An email is sent to the invitee with an opportunity to create a free Studio account.

Endpoint

copy 
https://api.bluebeam.com/publicapi/v1/sessions/{sessionId}/invite

Parameters

Name

Description

Email

Email address to send the invitation to

Message

Custom message that displays in the email

Example

copy 
cURL https://api.bluebeam.com/publicapi/v1/sessions/{session}/invite \
-H "Authorization: Bearer {token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: {client_id}" \
-d '{  
      "Email":"gavin.belson@hooli.com",  
      "Message":"Please join this Session to review documents regarding the Pied Piper acquisition."
    }' \
-X POST

Response

If successful, you will get a 204 response. For errors, see the Common HTML response codes at the bottom of our Authentication Guide .

OR

This method is best if you know that the email address is already associated with a Studio account and you want them to be added to a Studio Session without opting in. If the user does not have an account or if they are unsure if they do, use Method A: Invite user. Using Method B: Add user, the user is added to the Studio Session's attendees, and the Studio Session appears under their Attended Sessions within the Studio tab of the Revu interface.

Endpoint

copy 
https://api.bluebeam.com/publicapi/v1/sessions/{sessionId}/users

Parameters

Name

Description

Email

Email address of the known Studio account

SendEmail

Boolean; True: send an email to the invitee, False: do not send an email notification to the invitee

Message

Custom message that displays in the email

Example

copy 
cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/users](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/users)
-H "Authorization: Bearer {valid access_token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: [your client id]" \
-d '{  
      "Email": "peter.gregory@raviga.com",
      "SendEmail": true,
      "Message": "As requested, here is the Session to review the Pied Piper acquisition documents."
    }' \
-X POST

Response

If successful, you will get a 204 response. For errors, see the Common HTML response codes at the bottom of our Authentication Guide .

Sample Session invite email

 

To end a Session (typically done after the attendees have finished marking up or the Session expiration date has been reached), its Status must be changed, its files must be dealt with, and the Session itself must be properly disposed of.

Setting a Session's Status to Finalizing removes all users from the Session, except the Host. This is done to prevent further changes to the Session files after they are downloaded.

Endpoint

copy 
https://api.bluebeam.com/publicapi/v1/sessions/{id}

Example

copy 
cURL https://api.bluebeam.com/publicapi/v1/sessions/123-456-789 \
-H "Authorization: Bearer {valid access_token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: [your client id]" \
-d '{"Status": "Finalizing"}' \
-X PUT

Downloading the marked up Session files is a 2-part process. Follow the steps below for each file in the Session.

i. Create a Snapshot

While in a Session, PDFs and markups are stored separately. A Snapshot combines the PDF content with the markup layer into a single PDF so that the markups are viewable on the PDF outside of the Studio Session.

Endpoint

copy 
https://api.bluebeam.com/publicapi/v1/sessions/{sessionId}/files/{id}/snapshot

Example

copy 
cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files/1234567/snapshot](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files/1234567/snapshot) \
-H "Authorization: Bearer {valid access_token}" \
-H "client_id: [your client id]" \

ii. Check status of Snapshot, download if complete

Make a GET request to the Snapshot endpoint until the Status is either Complete or Error.

  • If Error: We will include an error message that can be presented to the user.

  • If Complete: Use the DownloadUrl to download the Snapshot

Endpoint

copy 
https://api.bluebeam.com/publicapi/v1/sessions/{sessionId}/files/{id}/snapshot

Example

copy 
cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files/1234567/](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files/1234567/)
-H "Authorization: Bearer {valid access_token}" \
-H "client_id: [your client id]" \
-X GET

Response Body

copy 
{
    "Status": "Complete",
    "StatusTime": "{The last time the Status was changed}",
    "LastSnapshotTime": "{Time of last successful Snapshot}",
    "DownloadUrl": "{A download URL for the last successful Snapshot}"
}

Status options

Status

Description

NoSnapshot

When a Snapshot has never been called on a file

Requested

The Snapshot job has not yet started, but we received the request

InProgress

The Snapshot job is in progress

Complete

The Snapshot job is finished and can be downloaded via DownloadUrl

Error

The Snapshot job failed. The status will include an error message.

Now that you have the marked up PDF(s), you can dispose of the Session by sending a DELETE request to the Session ID endpoint.

Endpoint

copy 
https://api.bluebeam.com/publicapi/v1/sessions/{id}

Example for closing out a Session

copy 
cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789) \
-H "Authorization: Bearer {valid access_token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: [your client id]" \
-X DELETE

 

Conclusion

Returning the file to its originating location and archiving the Session completes the typical Studio Session lifecycle. Though there are many different ways to work with Studio Sessions, we hope this walk-through has given you a good grasp of the basics.

 

See also:

Resources

Revu 21

Developer Portal

Developer Portal

This Developer Portal guide covers the general life cycle of a Studio Session and includes code examples.