Basic API Requests

This guide assumes you have obtained an access token from an authorized user. You can obtain an access token either by completing the OAuth flow (see the User Authentication guide) or by using the Access Token Generator to generate a token using your own Bluescape login information.

The Base URL

All API endpoints share the same base URL:

https://api.apps.us.bluescape.com

Assembling a Request

URL

A request URL is assembled from the base URL and the path information for an operation as found in the reference. For example, Add a User to an Organization is an operation with path /organizations/<organization_id>/users. Combining this path with the base URL gives us a request URL of:

https://api.apps.us.bluescape.com/organizations/<organization_id>/users

Parameters

The path for the operation above, like many in the Bluescape API, contains a parameter. Adding a user to an organization requires we identify the organization to which the new user should be invited. To finish preparing this request URL, we must replace <organization_id> with a valid organization ID, such as one obtained from the List a User's Organizations operation. Replacing the parameter placeholder with a sample organization ID yields a request URL of:

https://api.apps.us.bluescape.com/organizations/18223/users

In addition to path parameters, some requests will have query, body and form data parameters. Reviewing the documentation for Add a User to an Organization, we see that this operation has a JSON-format body parameter with a required email field. When an operation requires a body parameter, be sure to send your request with a Content-Type header of application/json. When a form data parameter is expected, be sure to send your request with a Content-Type header of multipart/form-data. A valid body for this request looks like:

{
  "email": "michael.scott@bluescape.com"
}

Authorization Header

Lastly, all operations require an Authorization header based on the access tokens received from the OAuth flow. The value of this header should match the format of Bearer <access-token>.

Assembled Request

Putting this all together, a request to Add a User to an Organization looks like:

curl -X POST https://api.apps.us.bluescape.com/organizations/18223/users \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsImtpZCI6Imp3d...' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "michael.scott@bluescape.com"
  }'
const accessToken = 'eyJhbGciOiJIUzI1NiIsImtpZCI6Imp3d...';
const options = {
    authorization: `Bearer ${accessToken}`
};
const organizationID = 18223;
const body = { 
    email: "michael.scott@bluescape.com" 
};

const client = new Bluescape(options);
client.addOrganizationUser(organizationID, body);

Example Request Flow

Let's walk through assembling and sending a chain of requests that will result in creating a new note in a workspace. Starting with just an access token, we will 1) request the ID of the user connected to the access token, 2) use the user's ID to request a list of workspaces that the user has access to, and 3) create a note in one of those workspaces.

Get the Authenticated User

First, let's request information about the user associated to the access token you have so we can get their user ID. We will use the Get Authenticated User endpoint. This operation has no parameters.

curl -X GET https://api.apps.us.bluescape.com/session/user \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsImtpZCI6Imp3d...'
client.getAuthenticatedUser();

You should receive a response similar to:

{
    "user": {
        "id": 15055,
        "email": "dwight.schrute@bluescape.com",
        "first_name": "Dwight",
        "last_name": "Schrute",
        "title": null,
        "industry": "Technology",
        "phone_number": "3104295040",
        "locked_at": null,
        "archived": false,
        "avatar_url": null,
        "created_at": "2017-04-07T22:49:20.000Z",
        "updated_at": "2018-06-26T20:47:53.000Z",
        "application_role": {
            "id": 2,
            "name": "User",
            "role_type": "user",
            "is_default": true,
            "display_order": 2,
            "can_list_users": false,
            ...
        },
        "user_preference": {
            "notify_on_new_message": true
        }
    }
}

Among the details returned by the API about this user, we can see the user ID at the path user.id which we can use for requests that contain a user_id parameter in their path.

Get the User's Workspaces

Now, let's request a list of workspaces this user has access to. Be sure to replace the <user_id> path parameter with the user ID you received from the previous request. The operation to List a User's Workspaces has no other parameters.

curl -X GET https://api.apps.us.bluescape.com/users/15055/workspaces \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsImtpZCI6Imp3d...'
const userID = 15055;

client.getUserWorkspaces(userID);

You should receive a response similar to:

{
    "total": 50,
    "limit": 25,
    "offset": 0,
    "size": 25,
    "paging": {
        "prev": null,
        "self": "/api/users/15055/workspaces?order_by=&order_direction=ASC&limit=25&offset=0",
        "next": "/api/users/15055/workspaces?order_by=&order_direction=ASC&limit=25&offset=25"
    },
    "workspaces": [
        {
            "id": "31231",
            "uid": "jyUEbzzKgaXYvBkfypBg",
            "name": "Alpha Project",
            "description": "",
            "company_id": 4,
            "public": true,
            ...
        },
        ...
    ]
}

Create a Note in a Workspace

Finally, let's use one of the workspace UIDs we received in the previous response to create a new note. We will replace the workspace_id parameter in the path with a UID for the Create a Note operation, and provide a JSON-format body indicating the text, background color, and position of the note we want to create.

curl -X POST https://api.apps.us.bluescape.com/workspaces/jyUEbzzKgaXYvBkfypBg/notes \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsImtpZCI6Imp3d...' \
  -H 'Content-Type: application/json' \
  -d '{
    "x": 0,
    "y": 0,
    "text": "The Bluescape API is fun!",
    "backgroundColor": "Red"
  }'
const workspaceID = "jyUEbzzKgaXYvBkfypBg";
const body = {
    "x": 0,
    "y": 0,
    "text": "The Bluescape API is fun!",
    "backgroundColor": "Red"
  };
  
client.addNoteToWorkspace(workspaceID, body);

You should receive a response similar to:

{
   "note": {
     "id": "5b4524f253f5c84952000002",
     "x": 0,
     "y": 0,
     "text": "The Bluescape API is fun!",
     "fontWeight": "normal",
     "textTransform": "none",
     "backgroundColor": "Red",
     "pin": false,
     "scale": 1
   }
}

This response indicates a note was created as requested. Save this note ID for use in operations that can use one, such as Update a Note or Create a Listener. Open the workspace you specified, and check for your new note in the center. Congratulations, you've created Bluescape content using the Bluescape API.

Next Steps

Go for it! Now that you have successfully requested information from Bluescape and made changes to a workspace, you should be comfortable taking advantage of all the functionality offered by the Bluescape API. Check out the API reference for the full list of endpoints available to your application.