Create a Browser

Add a browser to the workspace.

Details

Path: /workspaces/<workspace_id>/browsers
HTTP Method: POST
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheaderpath
SDK Method: addBrowserToWorkspace

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.

Body

Name Type Required? Default Description
x integer Optional 0 X position in the workspace.
y integer Optional 0 Y position in the workspace.
width integer Optional 800 Width of the browser widget
height integer Optional 600 Height of the browser widget
contentWidth integer Optional 1024 Width of the webpage rendered inside the browser widget. If larger than the width of the widget itself, viewing the entire webpage may require scrolling.
contentHeight integer Optional 768 Height of the webpage rendered inside the browser widget. If larger than the height of the widget itself, viewing the entire webpage may require scrolling.
url string Required URL of the webpage to load.
frameless boolean Optional If true, the browser widget will be drawn without a toolbar or borders.

Sample Body

{
  "x": 0,
  "y": 0,
  "width": 800,
  "height": 600,
  "contentWidth": 1024,
  "contentHeight": 768,
  "url": "",
  "frameless": true
}

Sample Response

{
  "browser": {
    "id": "",
    "x": 0,
    "y": 0,
    "height": 600,
    "width": 800,
    "contentWidth": 1024,
    "contentHeight": 768,
    "url": ""
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Delete a Browser

Delete the specified browser.

Details

Path: /workspaces/<workspace_id>/browsers/<browser_id>
HTTP Method: DELETE
Authorization: Bearer Token
Parameters: headerpath
SDK Method: deleteBrowser

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.
browser_id string Required Browser ID

Sample Response

{
  "message": ""
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Update a Browser

Update the specified browser.

Details

Path: /workspaces/<workspace_id>/browsers/<browser_id>
HTTP Method: PUT
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheaderpath
SDK Method: updateBrowser

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.
browser_id string Required Browser ID

Body

Name Type Required? Default Description
x integer Optional 0 X position in the workspace.
y integer Optional 0 Y position in the workspace.
width integer Optional Width of the browser widget
height integer Optional Height of the browser widget
url string Optional

Sample Body

{
  "x": 0,
  "y": 0,
  "width": 10,
  "height": 10,
  "url": ""
}

Sample Response

{
  "browser": {
    "id": "",
    "x": 0,
    "y": 0,
    "height": 600,
    "width": 800,
    "contentWidth": 1024,
    "contentHeight": 768,
    "url": ""
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Create a Canvas

Create a canvas in the workspace.

Details

Path: /workspaces/<workspace_id>/canvas
HTTP Method: POST
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheaderpath
SDK Method: addCanvasToWorkspace

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.

Body

Name Type Required? Default Description
x integer Optional 0 X position in the workspace.
y integer Optional 0 Y position in the workspace.
width integer Optional Width of the canvas
height integer Optional Height of the canvas
name string Required Name
borderColor string Optional Red Border color
Allowed values: "Red", "Yellow", "Green", "Blue"

Sample Body

{
  "x": 0,
  "y": 0,
  "width": 10,
  "height": 10,
  "name": "",
  "borderColor": "Red"
}

Sample Response

{
  "canvas": {
    "id": "",
    "x": 0,
    "y": 0,
    "width": 10,
    "height": 10,
    "name": "",
    "borderColor": "Red"
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Delete a Canvas

Delete the specified canvas.

Details

Path: /workspaces/<workspace_id>/canvas/<canvas_id>
HTTP Method: DELETE
Authorization: Bearer Token
Parameters: headerpath
SDK Method: deleteCanvas

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.
canvas_id string Required Canvas ID

Sample Response

{
  "message": ""
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Update a Canvas

Update the specified canvas.

Details

Path: /workspaces/<workspace_id>/canvas/<canvas_id>
HTTP Method: PUT
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheaderpath
SDK Method: updateCanvas

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.
canvas_id string Required Canvas ID

Body

Name Type Required? Default Description
name string Optional Name
borderColor string Optional Red Border color
Allowed values: "Red", "Yellow", "Green", "Blue"

Sample Body

{
  "name": "",
  "borderColor": "Red"
}

Sample Response

{
  "canvas": {
    "id": "",
    "x": 0,
    "y": 0,
    "width": 10,
    "height": 10,
    "name": "",
    "borderColor": "Red"
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Comment on an Object

Comment on the specified object. NOTE: Commenting on a document may not be available for several moments after the document is uploaded. The length of the delay depends on the size of the document and the load on the Bluescape system. Attempts to create a comment before the document has been processed will return a 404 response code.

Details

Path: /workspaces/<workspace_id>/<object_type>/<object_id>/comments
HTTP Method: POST
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheaderpath
SDK Method: addCommentToObject

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.
object_type string Required Type of the object being targeted.
Allowed values: "documents", "notes", "images", "text"
object_id string Required ID of the object being targeted.

Body

Name Type Required? Default Description
text string Required The body of the comment
parent string Optional Optional ID of parent comment if this is to be a child response. Only one level of nesting is supported

Sample Body

{
  "text": "",
  "parent": ""
}

Sample Response

{
  "comment": {
    "text": "",
    "parent": ""
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Create a Document

Upload a document to the workspace.

Details

Path: /workspaces/<workspace_id>/documents
HTTP Method: POST
Accepted content types: multipart/form-data
Authorization: Bearer Token
Parameters: formDataheaderpath
SDK Method: addDocumentToWorkspace

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: multipart/form-data

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.

Form Data

Name Type Required? Default Description
document file Required Document file data
pin boolean Optional false If true, the item will be "pinned" and immovable in the workspace.
scale number Optional 1 Digital resizing. 1 will render the image at its default size, 2 will double the width and height proportionately, etc.
title string Required Title
x integer Optional 0 X position
y integer Optional 0 Y position

Sample Response

{
  "document": {
    "id": "",
    "x": 0,
    "y": 0,
    "type": "",
    "title": "",
    "url": "",
    "pin": true,
    "scale": 1
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Delete a Document

Delete the specified document.

Details

Path: /workspaces/<workspace_id>/documents/<document_id>
HTTP Method: DELETE
Authorization: Bearer Token
Parameters: headerpath
SDK Method: deleteDocument

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.
document_id string Required Document ID

Sample Response

{
  "message": ""
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Update a Document

Update the specified document.

Details

Path: /workspaces/<workspace_id>/documents/<document_id>
HTTP Method: PUT
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheaderpath
SDK Method: updateDocument

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.
document_id string Required Document ID

Body

Name Type Required? Default Description
x integer Optional 0 X position in the workspace.
y integer Optional 0 Y position in the workspace.
pin boolean Optional false If true, the item will be "pinned" and immovable in the workspace.
scale number Optional 1 Digital resizing. 1 will render the image at its default size, 2 will double the width and height proportionately, etc.
Minimum: 0.5
Maximum: 4

Sample Body

{
  "x": 0,
  "y": 0,
  "pin": true,
  "scale": 1
}

Sample Response

{
  "document": {
    "id": "",
    "x": 0,
    "y": 0,
    "type": "",
    "title": "",
    "url": "",
    "pin": true,
    "scale": 1
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Create an Image

Upload an image to the workspace. The image may be uploaded as a binary attachment, multipart form data, or via a remote url.

Details

Path: /workspaces/<workspace_id>/images
HTTP Method: POST
Accepted content types: multipart/form-data
Authorization: Bearer Token
Parameters: formDataheaderpath
SDK Method: addImageToWorkspace

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: multipart/form-data

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.

Form Data

Name Type Required? Default Description
image file Required Image file data. Alternatively, a url can be provided and Bluescape will download the image data.
pin boolean Optional false If true, the item will be "pinned" and immovable in the workspace.
scale number Optional 1 Digital resizing. 1 will render the image at its default size, 2 will double the width and height proportionately, etc.
url string Optional URL
x integer Optional 0 X position
y integer Optional 0 Y position

Sample Response

{
  "image": {
    "id": "",
    "x": 0,
    "y": 0,
    "url": "",
    "pin": true,
    "scale": 1
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Delete an Image

Delete the specified image.

Details

Path: /workspaces/<workspace_id>/images/<image_id>
HTTP Method: DELETE
Authorization: Bearer Token
Parameters: headerpath
SDK Method: deleteImage

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.
image_id string Required Image ID

Sample Response

{
  "message": ""
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Update an Image

Update the position, scale or pin status of the specified image.

Details

Path: /workspaces/<workspace_id>/images/<image_id>
HTTP Method: PUT
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheaderpath
SDK Method: updateImage

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.
image_id string Required Image ID

Body

Name Type Required? Default Description
x integer Optional 0 X position in the workspace.
y integer Optional 0 Y position in the workspace.
pin boolean Optional false If true, the item will be "pinned" and immovable in the workspace.
scale number Optional 1 Digital resizing. 1 will render the image at its default size, 2 will double the width and height proportionately, etc.
Minimum: 0.5
Maximum: 4

Sample Body

{
  "x": 0,
  "y": 0,
  "pin": true,
  "scale": 1
}

Sample Response

{
  "image": {
    "id": "",
    "x": 0,
    "y": 0,
    "url": "",
    "pin": true,
    "scale": 1
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Create a Listener

Register a new listener. See the Listeners guide for more information about managing and using listeners.

Details

Path: /listeners
HTTP Method: POST
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheader
SDK Method: createListener

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Body

Name Type Required? Default Description
url string Required URL of your server. Bluescape will POST listener notifications to this URL.
workspaceId string Required Workspace ID
targetId string Optional ID of an object in the workspace (note, text). The listener will only be notified of activity related to this object.
eventTypes array of strings Required See the full list of event types here: https://developer.bluescape.com/reference/listener-events

Sample Body

{
  "url": "",
  "workspaceId": "",
  "targetId": "",
  "eventTypes": [
    ""
  ]
}

Sample Response

{
  "url": "",
  "targetId": "",
  "targetType": "",
  "eventTypes": [
    ""
  ]
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Delete a Listener

Delete a listener.

Details

Path: /listeners/<listener_id>
HTTP Method: DELETE
Authorization: Bearer Token
Parameters: headerpath
SDK Method: deleteListener

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Path

Name Type Required? Description
listener_id string Required Listener ID

Sample Response

{
  "message": ""
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Get a Listener

Get details for the specified listener.

Details

Path: /listeners/<listener_id>
HTTP Method: GET
Authorization: Bearer Token
Parameters: headerpath
SDK Method: getListener

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Path

Name Type Required? Description
listener_id string Required Listener ID

Sample Response

{
  "listeners": {
    "id": "",
    "workspaceId": "",
    "targetId": "",
    "targetType": "",
    "eventTypes": [
      ""
    ],
    "url": "",
    "status": [
      "ACTIVE"
    ]
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

List All Listeners

Get all listeners created by the authenticated user.

Details

Path: /listeners
HTTP Method: GET
Authorization: Bearer Token
Parameters: headerquery
SDK Method: getAllListeners

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Query

Name Type Required? Description
filter_by string Optional filter by field

Sample Response

{
  "listeners": {
    "id": "",
    "workspaceId": "",
    "targetId": "",
    "targetType": "",
    "eventTypes": [
      ""
    ],
    "url": "",
    "status": [
      "ACTIVE"
    ]
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Update a Listener

Update a listener.

Details

Path: /listeners/<listener_id>
HTTP Method: PUT
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheaderpath
SDK Method: updateListener

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Path

Name Type Required? Description
listener_id string Required Listener ID

Body

Name Type Required? Default Description
url string Optional URL of your server. Bluescape will POST listener notifications to this URL.
targetId string Optional ID of an object in the workspace (note, text). The listener will only be notified of activity related to this object.
eventTypes array of strings Optional Limit the events received by this listener to the listed event types.
status string Optional ACTIVE Set to 'ACTIVE' for normal operation, 'IN_ACTIVE' to disable the listener without deleting it.
Allowed values: "ACTIVE", "IN_ACTIVE"

Sample Body

{
  "url": "",
  "targetId": "",
  "eventTypes": [
    "ALL"
  ],
  "status": "ACTIVE"
}

Sample Response

{
  "url": "",
  "targetId": "",
  "targetType": "",
  "eventTypes": [
    ""
  ]
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Create a Note

Create a note in the workspace.

Details

Path: /workspaces/<workspace_id>/notes
HTTP Method: POST
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheaderpath
SDK Method: addNoteToWorkspace

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.

Body

Name Type Required? Default Description
x integer Optional 0 X position in the workspace.
y integer Optional 0 Y position in the workspace.
text string Required Note text
fontWeight string Optional normal Font weight
Allowed values: "normal", "bold"
textTransform string Optional inherit Text transform
Allowed values: "inherit", "uppercase"
backgroundColor string Optional Teal Background color
Allowed values: "Beige", "Blue", "Gold", "Grey", "Red", "Teal", "Yellow"
pin boolean Optional false If true, the item will be "pinned" and immovable in the workspace.
scale number Optional 1 Digital resizing. 1 will render the image at its default size, 2 will double the width and height proportionately, etc.
Minimum: 0.5
Maximum: 4

Sample Body

{
  "x": 0,
  "y": 0,
  "text": "",
  "fontWeight": "normal",
  "textTransform": "inherit",
  "backgroundColor": "Teal",
  "pin": true,
  "scale": 1
}

Sample Response

{
  "note": {
    "id": "",
    "x": 0,
    "y": 0,
    "width": 10,
    "height": 10,
    "text": "",
    "fontWeight": "normal",
    "textTransform": "inherit",
    "backgroundColor": "Teal",
    "pin": true,
    "scale": 1
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Delete a Note

Delete the specified note.

Details

Path: /workspaces/<workspace_id>/notes/<note_id>
HTTP Method: DELETE
Authorization: Bearer Token
Parameters: headerpath
SDK Method: deleteNote

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.
note_id string Required Note ID

Sample Response

{
  "message": ""
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Update a Note

Update the specified note.

Details

Path: /workspaces/<workspace_id>/notes/<note_id>
HTTP Method: PUT
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheaderpath
SDK Method: updateNote

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.
note_id string Required Note ID

Body

Name Type Required? Default Description
x integer Optional 0 X position in the workspace.
y integer Optional 0 Y position in the workspace.
text string Optional Note text
fontWeight string Optional normal Font weight
Allowed values: "normal", "bold"
textTransform string Optional inherit Text transform
Allowed values: "inherit", "uppercase"
backgroundColor string Optional Teal Background color
Allowed values: "Beige", "Blue", "Gold", "Grey", "Red", "Teal", "Yellow"
pin boolean Optional false If true, the item will be "pinned" and immovable in the workspace.
scale number Optional 1 Digital resizing. 1 will render the image at its default size, 2 will double the width and height proportionately, etc.
Minimum: 0.5
Maximum: 4

Sample Body

{
  "x": 0,
  "y": 0,
  "text": "",
  "fontWeight": "normal",
  "textTransform": "inherit",
  "backgroundColor": "Teal",
  "pin": true,
  "scale": 1
}

Sample Response

{
  "note": {
    "id": "",
    "x": 0,
    "y": 0,
    "width": 10,
    "height": 10,
    "text": "",
    "fontWeight": "normal",
    "textTransform": "inherit",
    "backgroundColor": "Teal",
    "pin": true,
    "scale": 1
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Add a User to an Organization

Invite a user to be a member of the specified organization. (Triggers an email invitation)

Details

Path: /organizations/<organization_id>/users
HTTP Method: POST
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheaderpath
SDK Method: addOrganizationUser

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Path

Name Type Required? Description
organization_id integer Required Organization ID

Body

Name Type Required? Default Description
email string Required Valid email of the user to invite. An email will be sent to this address.

Sample Body

{
  "email": ""
}

Sample Response

{
  "message": ""
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
500 Internal Server Error

Get an Organization

Get details for the specified organizaton.

Details

Path: /organizations/<organization_id>
HTTP Method: GET
Authorization: Bearer Token
Parameters: headerpath
SDK Method: getOrganization

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Path

Name Type Required? Description
organization_id integer Required Organization ID

Sample Response

{
  "organization": {
    "id": 10,
    "name": "",
    "locked_at": "",
    "account_id": 10,
    "created_at": "",
    "updated_at": "",
    "expiration": "",
    "plan": {
      "id": 10,
      "name": ""
    },
    "owner": {
      "id": 10,
      "email": "",
      "first_name": "",
      "last_name": "",
      "locked_at": "",
      "account_id": 10,
      "created_at": "",
      "updated_at": ""
    },
    "metadata": [
      {
        "key": "",
        "value": ""
      }
    ],
    "is_guest_invite_requires_approval": true
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
404 Resource Not Found
500 Internal Server Error

List an Organization's Members

Get all members of the specified organization.

Details

Path: /organizations/<organization_id>/users
HTTP Method: GET
Authorization: Bearer Token
Parameters: headerpathquery
SDK Method: getOrganizationUsers

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Path

Name Type Required? Description
organization_id integer Required Organization ID

Query

Name Type Required? Description
query string Optional Search term
order_by string Optional Field to base sort on.
order_direction string Optional Sort order for results.
Allowed values: "ASC", "DESC"
limit integer Optional Maximum number of results to return.
offset integer Optional Number of resources in the collection to skip before assembling the results array.
filter_by string Optional filter by field

Sample Response

{
  "organization_users": [
    {
      "id": 10,
      "email": "",
      "first_name": "",
      "last_name": "",
      "title": "",
      "industry": "",
      "phone_number": "",
      "locked_at": "",
      "created_at": "",
      "updated_at": "",
      "avatar_url": "",
      "invited_state": "PENDING_INVITE",
      "organization_role": {
        "id": 10,
        "name": "",
        "description": "",
        "role_type": "",
        "is_default": true,
        "display_order": 10,
        "organization_id": 10,
        "is_editable": true,
        "is_deletable": true,
        "can_add_user": true,
        "can_remove_user": true,
        "can_edit_user_info": true,
        "can_list_organization_users": true,
        "can_add_admin": true,
        "can_remove_admin": true,
        "can_edit_admin_info": true,
        "can_add_guest": true,
        "can_remove_guest": true,
        "can_edit_guest_info": true,
        "can_create_workspace": true,
        "can_view_public_workspace": true,
        "can_approve_guest_invite": true,
        "can_change_organization_settings": true,
        "can_add_organization_role": true,
        "can_edit_organization_role": true,
        "can_delete_organization_role": true,
        "can_add_workspace_role": true,
        "can_edit_workspace_role": true,
        "can_delete_workspace_role": true
      }
    }
  ],
  "total": 10,
  "limit": 10,
  "offset": 10,
  "size": 10,
  "paging": {
    "prev": "",
    "self": "",
    "next": ""
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
500 Internal Server Error

Remove a Member from an Organization

Remove a member from the specified organization.

Details

Path: /organizations/<organization_id>/users/<user_id>
HTTP Method: DELETE
Authorization: Bearer Token
Parameters: headerpath
SDK Method: removeOrganizationUser

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Path

Name Type Required? Description
organization_id integer Required Organization ID
user_id integer Required User ID

Sample Response

{
  "message": ""
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
500 Internal Server Error

Update a Member

Update the specified member's information including their role in the organization.

Details

Path: /organizations/<organization_id>/users/<user_id>
HTTP Method: PUT
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheaderpath
SDK Method: updateOrganizationUser

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Path

Name Type Required? Description
organization_id integer Required Organization ID
user_id integer Required User ID

Body

Name Type Required? Default Description
first_name string Optional First name
last_name string Optional Last name
phone_number string Optional Phone number
organization_role_id integer Optional ID of an organization role to assign to the member. (see Permissions for role types)
email string Optional Valid email address

Sample Body

{
  "first_name": "",
  "last_name": "",
  "phone_number": "",
  "organization_role_id": 10,
  "email": ""
}

Sample Response

{
  "message": ""
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
500 Internal Server Error

List Organization Roles

Users that are invited to join an organization are assigned a role that governs what permissions they have to edit the organization, invite new users, and view private workspaces. This API returns the list of standard roles defined by Bluescape that can be assigned to a user joining an organization.

Details

Path: /organizations/roles
HTTP Method: GET
Authorization: Bearer Token
Parameters: header
SDK Method: listMemberRoles

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Sample Response

{
  "organization_roles": [
    {
      "id": 10,
      "name": "",
      "description": "",
      "role_type": "",
      "is_default": true,
      "display_order": 10,
      "organization_id": 10,
      "is_editable": true,
      "is_deletable": true,
      "can_add_user": true,
      "can_remove_user": true,
      "can_edit_user_info": true,
      "can_list_organization_users": true,
      "can_add_admin": true,
      "can_remove_admin": true,
      "can_edit_admin_info": true,
      "can_add_guest": true,
      "can_remove_guest": true,
      "can_edit_guest_info": true,
      "can_create_workspace": true,
      "can_view_public_workspace": true,
      "can_approve_guest_invite": true,
      "can_change_organization_settings": true,
      "can_add_organization_role": true,
      "can_edit_organization_role": true,
      "can_delete_organization_role": true,
      "can_add_workspace_role": true,
      "can_edit_workspace_role": true,
      "can_delete_workspace_role": true
    }
  ]
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
500 Internal Server Error

List Workspace Roles

Users that are given access to a workspace are assigned a role that governs what permissions they have to modify, share and download workspace content. This API returns the list of standard roles that can be assigned when granting access to a workspace.

Details

Path: /workspaces/roles
HTTP Method: GET
Authorization: Bearer Token
Parameters: header
SDK Method: listWorkspaceRoles

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Sample Response

{
  "workspace_roles": [
    {
      "id": 10,
      "name": "",
      "description": "",
      "role_type": "",
      "is_default": true,
      "display_order": 10,
      "organization_id": 10,
      "is_editable": true,
      "is_deletable": true,
      "is_saml": true,
      "can_edit_metadata": true,
      "can_edit_workspace": true,
      "can_duplicate_workspace": true,
      "can_delete_workspace": true,
      "can_add_user": true,
      "can_remove_user": true,
      "can_add_guest": true,
      "can_remove_guest": true,
      "can_send_to_wall": true,
      "can_change_publish_state": true,
      "can_change_public_state": true,
      "can_download_assets": true,
      "can_change_user_role": true,
      "can_change_owner": true,
      "can_change_organization": true,
      "can_change_guest_role": true,
      "can_list_users": true
    }
  ]
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
500 Internal Server Error

Delete a Stroke

Delete the specified stroke.

Details

Path: /workspaces/<workspace_id>/strokes/<stroke_id>
HTTP Method: DELETE
Authorization: Bearer Token
Parameters: headerpath
SDK Method: deleteStrokeFromWorkspace

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.
stroke_id string Required Stroke ID

Sample Response

{
  "message": ""
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Draw Strokes on a Workspace

Draw a stroke directly on the workspace.

Details

Path: /workspaces/<workspace_id>/strokes
HTTP Method: POST
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheaderpath
SDK Method: drawStrokeOnWorkspace

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.

Body

Name Type Required? Default Description
penColor string Optional White Allowed values: "White", "Gray", "Yellow", "Red", "Green", "Purple", "Cyan"
brushSize integer Optional Minimum: 1
Maximum: 100
brushType string Optional Pen Allowed values: "Pen", "Eraser"
points array of integers Required Defined as a series of X,Y coordinates: [x1, y1, x2, y2]. For example, [0,0, 100,100] will draw a stroke from point 0,0 to point 100,100.

Sample Body

{
  "penColor": "White",
  "brushSize": 10,
  "brushType": "Pen",
  "points": [
    10
  ]
}

Sample Response

{
  "stroke": {
    "id": "",
    "penColor": "White",
    "size": 10,
    "brushType": "Pen",
    "points": [
      10
    ]
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Draw Strokes on an Object

Draw a stroke on the specified object.

Details

Path: /workspaces/<workspace_id>/<object_type>/<object_id>/strokes
HTTP Method: POST
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheaderpath
SDK Method: drawStrokeOnObject

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.
object_type string Required Type of the object being targeted.
Allowed values: "notes", "images"
object_id string Required ID of the object being targeted.

Body

Name Type Required? Default Description
penColor string Optional White Allowed values: "White", "Gray", "Yellow", "Red", "Green", "Purple", "Cyan"
brushSize integer Optional Minimum: 1
Maximum: 100
brushType string Optional Pen Allowed values: "Pen", "Eraser"
points array of integers Required Defined as a series of X,Y coordinates: [x1, y1, x2, y2]. For example, [0,0, 100,100] will draw a stroke from point 0,0 to point 100,100.

Sample Body

{
  "penColor": "White",
  "brushSize": 10,
  "brushType": "Pen",
  "points": [
    10
  ]
}

Sample Response

{
  "stroke": {
    "id": "",
    "penColor": "White",
    "size": 10,
    "brushType": "Pen",
    "points": [
      10
    ]
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Create Text

Create a text element in the workspace.

Details

Path: /workspaces/<workspace_id>/text
HTTP Method: POST
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheaderpath
SDK Method: addTextToWorkspace

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.

Body

Name Type Required? Default Description
x integer Optional 0 X position in the workspace.
y integer Optional 0 Y position in the workspace.
width integer Optional Width of the bounding box, affects how the text will wrap and the size of the background color.
height integer Optional Height of the bounding box, affects the size of the background color. Text will not be clipped.
text string Required Text to display.
fontFamily string Optional Dosis Allowed values: "Dosis", "Helvetica", "Times New Roman", "Source Code Pro", "Aleo", "Exo 2"
fontSize integer Optional 64 Font size, measured in pixels.
fontColor string Optional #ffffff Color specified in hex format (like CSS).
fontWeight string Optional normal Font weight
Allowed values: "normal", "bold"
fontStyle string Optional normal Allowed values: "normal", "italic"
textTransform string Optional inherit Text transform
Allowed values: "inherit", "uppercase"
backgroundColor string Optional #ea3e35 Color specified in hex format (like CSS).
pin boolean Optional false If true, the item will be "pinned" and immovable in the workspace.

Sample Body

{
  "x": 0,
  "y": 0,
  "width": 10,
  "height": 10,
  "text": "",
  "fontFamily": "Dosis",
  "fontSize": 64,
  "fontColor": "#ffffff",
  "fontWeight": "normal",
  "fontStyle": "normal",
  "textTransform": "inherit",
  "backgroundColor": "#ea3e35",
  "pin": true
}

Sample Response

{
  "text": {
    "id": "",
    "x": 0,
    "y": 0,
    "width": 10,
    "height": 10,
    "text": "",
    "fontFamily": "Dosis",
    "fontSize": 64,
    "fontColor": "#ffffff",
    "fontWeight": "normal",
    "fontStyle": "normal",
    "textTransform": "inherit",
    "backgroundColor": "#ea3e35",
    "pin": true
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Delete Text

Delete the specified text element.

Details

Path: /workspaces/<workspace_id>/text/<text_id>
HTTP Method: DELETE
Authorization: Bearer Token
Parameters: headerpath
SDK Method: deleteText

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.
text_id string Required Text ID

Sample Response

{
  "message": ""
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Update Text

Update the specified text element.

Details

Path: /workspaces/<workspace_id>/text/<text_id>
HTTP Method: PUT
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheaderpath
SDK Method: updateText

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.
text_id string Required Text ID

Body

Name Type Required? Default Description
x integer Optional 0 X position in the workspace.
y integer Optional 0 Y position in the workspace.
width integer Optional Width of the bounding box, affects how the text will wrap and the size of the background color.
height integer Optional Height of the bounding box, affects the size of the background color. Text will not be clipped.
text string Optional Text to display.
fontFamily string Optional Dosis Allowed values: "Dosis", "Helvetica", "Times New Roman", "Source Code Pro", "Aleo", "Exo 2"
fontSize integer Optional 64 Font size, measured in pixels.
fontColor string Optional #ffffff Color specified in hex format (like CSS).
fontWeight string Optional normal Font weight
Allowed values: "normal", "bold"
fontStyle string Optional normal Allowed values: "normal", "italic"
textTransform string Optional inherit Text transform
Allowed values: "inherit", "uppercase"
backgroundColor string Optional #ea3e35 Color specified in hex format (like CSS).
pin boolean Optional false If true, the item will be "pinned" and immovable in the workspace.

Sample Body

{
  "x": 0,
  "y": 0,
  "width": 10,
  "height": 10,
  "text": "",
  "fontFamily": "Dosis",
  "fontSize": 64,
  "fontColor": "#ffffff",
  "fontWeight": "normal",
  "fontStyle": "normal",
  "textTransform": "inherit",
  "backgroundColor": "#ea3e35",
  "pin": true
}

Sample Response

{
  "text": {
    "id": "",
    "x": 0,
    "y": 0,
    "width": 10,
    "height": 10,
    "text": "",
    "fontFamily": "Dosis",
    "fontSize": 64,
    "fontColor": "#ffffff",
    "fontWeight": "normal",
    "fontStyle": "normal",
    "textTransform": "inherit",
    "backgroundColor": "#ea3e35",
    "pin": true
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Get a User

Get details for the specified user.

Details

Path: /users/<user_id>
HTTP Method: GET
Authorization: Bearer Token
Parameters: headerpath
SDK Method: getUser

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Path

Name Type Required? Description
user_id integer Required User ID

Sample Response

{
  "user": {
    "id": 10,
    "email": "",
    "first_name": "",
    "last_name": "",
    "title": "",
    "industry": "",
    "phone_number": "",
    "locked_at": "",
    "archived": true,
    "avatar_url": "",
    "created_at": "",
    "updated_at": "",
    "application_role": {
      "id": 10,
      "name": "",
      "description": "",
      "role_type": "",
      "is_default": true,
      "display_order": 10,
      "can_list_users": true,
      "can_list_organizations": true,
      "can_create_organizations": true,
      "can_edit_organizations": true,
      "can_delete_organizations": true,
      "can_edit_users": true,
      "can_list_walls": true,
      "can_create_walls": true,
      "can_edit_walls": true,
      "can_delete_walls": true,
      "can_list_plans": true,
      "can_create_plans": true,
      "can_edit_plans": true,
      "can_delete_plans": true,
      "can_lock_users": true,
      "can_lock_organizations": true,
      "can_delete_users": true,
      "can_create_help_menu": true,
      "can_edit_help_menu": true,
      "can_delete_help_menu": true
    },
    "last_login_at": "",
    "organizations": [
      {
        "id": 10,
        "name": ""
      }
    ],
    "user_preference": {
      "notify_on_new_message": true
    }
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
404 Resource Not Found
500 Internal Server Error

Get the Authenticated User

Get details for the user associated to the access token being used.

Details

Path: /session/user
HTTP Method: GET
Authorization: Bearer Token
Parameters: header
SDK Method: getAuthenticatedUser

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Sample Response

{
  "user": {
    "id": 10,
    "email": "",
    "first_name": "",
    "last_name": "",
    "title": "",
    "industry": "",
    "phone_number": "",
    "locked_at": "",
    "archived": true,
    "avatar_url": "",
    "created_at": "",
    "updated_at": "",
    "application_role": {
      "id": 10,
      "name": "",
      "description": "",
      "role_type": "",
      "is_default": true,
      "display_order": 10,
      "can_list_users": true,
      "can_list_organizations": true,
      "can_create_organizations": true,
      "can_edit_organizations": true,
      "can_delete_organizations": true,
      "can_edit_users": true,
      "can_list_walls": true,
      "can_create_walls": true,
      "can_edit_walls": true,
      "can_delete_walls": true,
      "can_list_plans": true,
      "can_create_plans": true,
      "can_edit_plans": true,
      "can_delete_plans": true,
      "can_lock_users": true,
      "can_lock_organizations": true,
      "can_delete_users": true,
      "can_create_help_menu": true,
      "can_edit_help_menu": true,
      "can_delete_help_menu": true
    },
    "user_preference": {
      "notify_on_new_message": true
    }
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
500 Internal Server Error

List a User's Organizations

Get all organizations that the specified user is a member of.

Details

Path: /users/<user_id>/organizations
HTTP Method: GET
Authorization: Bearer Token
Parameters: headerpathquery
SDK Method: getUserOrganizations

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Path

Name Type Required? Description
user_id integer Required User ID

Query

Name Type Required? Description
query string Optional Search term
order_by string Optional Field to base sort on.
order_direction string Optional Sort order for results.
Allowed values: "ASC", "DESC"
limit integer Optional Maximum number of results to return.
offset integer Optional Number of resources in the collection to skip before assembling the results array.

Sample Response

{
  "organizations": [
    {
      "id": 10,
      "name": "",
      "locked_at": "",
      "account_id": 10,
      "created_at": "",
      "updated_at": "",
      "expiration": "",
      "is_guest_invite_requires_approval": true,
      "organization_role": {
        "id": 10,
        "name": "",
        "description": "",
        "role_type": "",
        "is_default": true,
        "display_order": 10,
        "organization_id": 10,
        "is_editable": true,
        "is_deletable": true,
        "can_add_user": true,
        "can_remove_user": true,
        "can_edit_user_info": true,
        "can_list_organization_users": true,
        "can_add_admin": true,
        "can_remove_admin": true,
        "can_edit_admin_info": true,
        "can_add_guest": true,
        "can_remove_guest": true,
        "can_edit_guest_info": true,
        "can_create_workspace": true,
        "can_view_public_workspace": true,
        "can_approve_guest_invite": true,
        "can_change_organization_settings": true,
        "can_add_organization_role": true,
        "can_edit_organization_role": true,
        "can_delete_organization_role": true,
        "can_add_workspace_role": true,
        "can_edit_workspace_role": true,
        "can_delete_workspace_role": true
      },
      "plan": {
        "id": 10,
        "name": ""
      }
    }
  ],
  "total": 10,
  "limit": 10,
  "offset": 10,
  "size": 10,
  "paging": {
    "prev": "",
    "self": "",
    "next": ""
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
500 Internal Server Error

List a User's Workspaces

Get workspaces that the specified user has access to, across all organizations they are a member of.

Details

Path: /users/<user_id>/workspaces
HTTP Method: GET
Authorization: Bearer Token
Parameters: headerpathquery
SDK Method: getUserWorkspaces

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Path

Name Type Required? Description
user_id integer Required User ID

Query

Name Type Required? Description
query string Optional Search term
order_by string Optional Field to base sort on.
order_direction string Optional Sort order for results.
Allowed values: "ASC", "DESC"
limit integer Optional Maximum number of results to return.
offset integer Optional Number of resources in the collection to skip before assembling the results array.

Sample Response

{
  "workspaces": [
    {
      "id": 10,
      "uid": "",
      "name": "",
      "description": "",
      "organization_id": 10,
      "public": true,
      "published_at": "",
      "published_url": "",
      "publish_state": "",
      "publish_state_at": "",
      "created_at": "",
      "updated_at": "",
      "workspace_role": {
        "id": 10,
        "name": "",
        "description": "",
        "role_type": "",
        "is_default": true,
        "display_order": 10,
        "organization_id": 10,
        "is_editable": true,
        "is_deletable": true,
        "is_saml": true,
        "can_edit_metadata": true,
        "can_edit_workspace": true,
        "can_duplicate_workspace": true,
        "can_delete_workspace": true,
        "can_add_user": true,
        "can_remove_user": true,
        "can_add_guest": true,
        "can_remove_guest": true,
        "can_send_to_wall": true,
        "can_change_publish_state": true,
        "can_change_public_state": true,
        "can_download_assets": true,
        "can_change_user_role": true,
        "can_change_owner": true,
        "can_change_organization": true,
        "can_change_guest_role": true,
        "can_list_users": true
      },
      "workspace_owner": {
        "id": 10,
        "email": "",
        "first_name": "",
        "last_name": "",
        "title": "",
        "industry": "",
        "phone_number": "",
        "avatar_url": "",
        "locked_at": "",
        "created_at": "",
        "updated_at": ""
      },
      "users_count": 10,
      "active_users_count": 10,
      "favorite": true
    }
  ],
  "total": 10,
  "limit": 10,
  "offset": 10,
  "size": 10,
  "paging": {
    "prev": "",
    "self": "",
    "next": ""
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
500 Internal Server Error

List a User's Workspaces in an Organization

Get workspaces within the specified organization that the specified user has access to.

Details

Path: /users/<user_id>/organizations/<organization_id>/workspaces
HTTP Method: GET
Authorization: Bearer Token
Parameters: headerpathquery
SDK Method: getUserWorkspacesInOrganization

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Path

Name Type Required? Description
user_id integer Required User ID
organization_id integer Required Organization ID

Query

Name Type Required? Description
query string Optional Search term
order_by string Optional Field to base sort on.
order_direction string Optional Sort order for results.
Allowed values: "ASC", "DESC"
limit integer Optional Maximum number of results to return.
offset integer Optional Number of resources in the collection to skip before assembling the results array.

Sample Response

{
  "workspaces": [
    {
      "id": 10,
      "uid": "",
      "name": "",
      "description": "",
      "organization_id": 10,
      "public": true,
      "published_at": "",
      "published_url": "",
      "publish_state": "",
      "publish_state_at": "",
      "created_at": "",
      "updated_at": "",
      "workspace_role": {
        "id": 10,
        "name": "",
        "description": "",
        "role_type": "",
        "is_default": true,
        "display_order": 10,
        "organization_id": 10,
        "is_editable": true,
        "is_deletable": true,
        "is_saml": true,
        "can_edit_metadata": true,
        "can_edit_workspace": true,
        "can_duplicate_workspace": true,
        "can_delete_workspace": true,
        "can_add_user": true,
        "can_remove_user": true,
        "can_add_guest": true,
        "can_remove_guest": true,
        "can_send_to_wall": true,
        "can_change_publish_state": true,
        "can_change_public_state": true,
        "can_download_assets": true,
        "can_change_user_role": true,
        "can_change_owner": true,
        "can_change_organization": true,
        "can_change_guest_role": true,
        "can_list_users": true
      },
      "workspace_owner": {
        "id": 10,
        "email": "",
        "first_name": "",
        "last_name": "",
        "title": "",
        "industry": "",
        "phone_number": "",
        "avatar_url": "",
        "locked_at": "",
        "created_at": "",
        "updated_at": ""
      },
      "users_count": 10,
      "active_users_count": 10,
      "favorite": true
    }
  ],
  "total": 10,
  "limit": 10,
  "offset": 10,
  "size": 10,
  "paging": {
    "prev": "",
    "self": "",
    "next": ""
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
500 Internal Server Error

Update a User

Update the specified user.

Details

Path: /users/<user_id>
HTTP Method: PUT
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheaderpath
SDK Method: updateUser

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Path

Name Type Required? Description
user_id integer Required User ID

Body

Name Type Required? Default Description
application_role_id integer Optional Organization Role ID to assign to the user.
first_name string Optional First name
last_name string Optional Last name
email string Optional Valid email address
new_password string Optional To reset a user's password, provide both the current password and the new password.
current_password string Optional To reset a user's password, provide both the current password and the new password.
user_preference object Optional User preferences. Not all properties must be specified when being updated.
user_preference.notify_on_new_message boolean Optional If true, Bluescape will send emails to the user when they are mentioned in comments. If false, no emails will be sent.

Sample Body

{
  "application_role_id": 10,
  "first_name": "",
  "last_name": "",
  "email": "",
  "new_password": "",
  "current_password": "",
  "user_preference": {
    "notify_on_new_message": true
  }
}

Sample Response

{
  "message": ""
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
404 Resource Not Found
500 Internal Server Error

Add User to Workspace

Give users access to the specified workspace. Users are identified by their email, must be assigned a workspace role, and must already be a member of the organization that the workspace falls under.

Details

Path: /workspaces/<workspace_id>/users
HTTP Method: POST
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheaderpath
SDK Method: addWorkspaceUser

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.

Body

Name Type Required? Default Description
users array of objects Required Each object in the array contains the information needed to invite a user to the workspace.
users.email string Required Valid email of the user to invite. An email will be sent to this address.
users.workspace_role_id integer Required ID of a workspace role to assign to the user when they accept the invite. (see Permissions for role types)

Sample Body

{
  "users": [
    {
      "email": "",
      "workspace_role_id": 10
    }
  ]
}

Sample Response

{
  "message": ""
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
500 Internal Server Error

Copy a Workspace

Duplicate the specified workspace.

Details

Path: /workspaces/<workspace_id>/copy
HTTP Method: PUT
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheaderpath
SDK Method: copyWorkspace

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.

Body

Name Type Required? Default Description
new_workspace_name string Optional Name of the new workspace.
new_workspace_description string Optional Description of the new workspace.

Sample Body

{
  "new_workspace_name": "",
  "new_workspace_description": ""
}

Sample Response

{
  "message": ""
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
404 Resource Not Found
500 Internal Server Error

Create a Workspace

Create a new workspace in the specified organization.

Details

Path: /organizations/<organization_id>/workspaces
HTTP Method: POST
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheaderpath
SDK Method: createWorkspace

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Path

Name Type Required? Description
organization_id integer Required Organization ID

Body

Name Type Required? Default Description
name string Required Name of the new workspace.
description string Optional Description of the new workspace.
public boolean Optional false If true, all members of the organization will have access to the workspace. If false, only members and guests explicity invited as collaborators will have access.
users array of objects Optional Users to invite to the new workspace.
users.email string Optional Valid email address where the invitation will be sent.
users.workspace_role_id integer Optional ID of a workspace role to assign to the user. (see Permissions for role types)

Sample Body

{
  "name": "",
  "description": "",
  "public": true,
  "users": [
    {
      "email": "",
      "workspace_role_id": 10
    }
  ]
}

Sample Response

{
  "workspace": {
    "title": "Workspace",
    "properties": {
      "id": 10,
      "uid": "",
      "publish_state": "",
      "name": "",
      "description": "",
      "organization_id": 10,
      "public": true,
      "users": [
        {
          "user_id": 10,
          "workspace_id": 10,
          "workspace_role_id": 10,
          "created_at": "",
          "updated_at": ""
        }
      ],
      "created_at": "",
      "updated_at": ""
    }
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
500 Internal Server Error

Delete a Workspace

Delete the specified workspace.

Details

Path: /workspaces/<workspace_id>
HTTP Method: DELETE
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheaderpath
SDK Method: deleteWorkspace

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.

Body

Name Type Required? Default Description
is_permanent boolean Optional false If false, the workspace will only be hidden from users, but the data will be retained. If true, delete will be permanent.

Sample Body

{
  "is_permanent": true
}

Sample Response

{
  "message": ""
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
500 Internal Server Error

Favorite a Workspace

Favorite or unfavorite the specified workspace for the user.

Details

Path: /workspaces/<workspace_id>/favorite
HTTP Method: POST
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheaderpath
SDK Method: favoriteWorkspace

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.

Body

Name Type Required? Default Description
favorite boolean Optional true If true, will be marked as a favorite workspace in the portal.

Sample Body

{
  "favorite": true
}

Sample Response

{
  "message": ""
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
404 Resource Not Found
500 Internal Server Error

Get a Workspace

Get details for the specified workspace.

Details

Path: /workspaces/<workspace_id>
HTTP Method: GET
Authorization: Bearer Token
Parameters: headerpath
SDK Method: getWorkspace

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.

Sample Response

{
  "workspace": {
    "title": "Workspace",
    "properties": {
      "id": 10,
      "uid": "",
      "name": "",
      "description": "",
      "organization_id": 10,
      "public": true,
      "published_at": "",
      "published_url": "",
      "publish_state": "",
      "publish_state_at": "",
      "created_at": "",
      "updated_at": "",
      "workspace_role": {
        "id": 10,
        "name": "",
        "description": "",
        "role_type": "",
        "is_default": true,
        "display_order": 10,
        "organization_id": 10,
        "is_editable": true,
        "is_deletable": true,
        "is_saml": true,
        "can_edit_metadata": true,
        "can_edit_workspace": true,
        "can_duplicate_workspace": true,
        "can_delete_workspace": true,
        "can_add_user": true,
        "can_remove_user": true,
        "can_add_guest": true,
        "can_remove_guest": true,
        "can_send_to_wall": true,
        "can_change_publish_state": true,
        "can_change_public_state": true,
        "can_download_assets": true,
        "can_change_user_role": true,
        "can_change_owner": true,
        "can_change_organization": true,
        "can_change_guest_role": true,
        "can_list_users": true
      }
    }
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
500 Internal Server Error

List Active Users in a Workspace

Get the users currently active in the specified workspace.

Details

Path: /workspaces/<workspace_id>/active_users
HTTP Method: GET
Authorization: Bearer Token
Parameters: headerpathquery
SDK Method: getActiveUsersInWorkspace

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.

Query

Name Type Required? Description
query string Optional Search term
order_by string Optional Field to base sort on.
order_direction string Optional Sort order for results.
Allowed values: "ASC", "DESC"
limit integer Optional Maximum number of results to return.
offset integer Optional Number of resources in the collection to skip before assembling the results array.

Sample Response

{
  "active_users": [
    {
      "id": 10,
      "type": "",
      "email": "",
      "first_name": "",
      "last_name": "",
      "leader": true
    }
  ],
  "total": 10,
  "limit": 10,
  "offset": 10,
  "size": 10,
  "paging": {
    "prev": "",
    "self": "",
    "next": ""
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

List Users with Access to a Workspace

Get all users with access to the specified workspace.

Details

Path: /workspaces/<workspace_id>/all_users
HTTP Method: GET
Authorization: Bearer Token
Parameters: headerpathquery
SDK Method: getWorkspaceUsers

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.

Query

Name Type Required? Description
filter_by string Optional filter by field

Sample Response

{
  "workspace_users": [
    {
      "id": 10,
      "email": "",
      "first_name": "",
      "last_name": ""
    }
  ],
  "total": 10
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
404 Resource Not Found
500 Internal Server Error

Publish a Workspace

Publish the specified workspace. Publishing may take several minutes depending on the size of the worskspace. An email will be sent when publishing is complete. Published workspaces can be accessed at https://viewer.bluescape.com/<workspace_id>.

Details

Path: /workspaces/<workspace_id>/publish
HTTP Method: PUT
Authorization: Bearer Token
Parameters: headerpath
SDK Method: publishWorkspace

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.

Sample Response

{
  "message": ""
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
404 Resource Not Found
500 Internal Server Error

Remove User from Workspace

Remove a user's access to the specified workspace.

Details

Path: /workspaces/<workspace_id>/users/<user_id>
HTTP Method: DELETE
Authorization: Bearer Token
Parameters: headerpath
SDK Method: removeWorkspaceUser

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.
user_id integer Required User ID

Sample Response

{
  "message": ""
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
500 Internal Server Error

Unpublish a Workspace

Unpublish the specified workspace.

Details

Path: /workspaces/<workspace_id>/unpublish
HTTP Method: PUT
Authorization: Bearer Token
Parameters: headerpath
SDK Method: unpublishWorkspace

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.

Sample Response

{
  "message": ""
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
403 ForbiddenError
404 Resource Not Found
500 Internal Server Error

Update User Role in Workspace

Update a user's role in the specified workspace.

Details

Path: /workspaces/<workspace_id>/users/<user_id>
HTTP Method: PUT
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheaderpath
SDK Method: updateWorkspaceUserRole

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.
user_id integer Required User ID

Body

Name Type Required? Default Description
workspace_role_id integer Required ID of a workspace role to assign to the user. (see Permissions for role types)

Sample Body

{
  "workspace_role_id": 10
}

Sample Response

{
  "message": ""
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
500 Internal Server Error

Update a Workspace

Update the specified workspace.

Details

Path: /workspaces/<workspace_id>
HTTP Method: PUT
Accepted content types: application/json
Authorization: Bearer Token
Parameters: bodyheaderpath
SDK Method: updateWorkspace

Headers

Name Type Required? Description
Authorization string Required Format: Bearer <access-token>
Content-Type string Required Value: application/json

Path

Name Type Required? Description
workspace_id string Required Workspace UID. Format: 20 alphanumeric characters.

Body

Name Type Required? Default Description
name string Optional New name for the workspace.
description string Optional New description for the workspace.
public boolean Optional If true, all members of the organization will have access to the workspace. If false, only members and guests explicity invited as collaborators will have access.
user_id integer Optional New owner for the workspace, must be a valid User ID.

Sample Body

{
  "name": "",
  "description": "",
  "public": true,
  "user_id": 10
}

Sample Response

{
  "message": ""
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing.

Code Description
400 Bad Request
401 Unauthorized
404 Resource Not Found
500 Internal Server Error