Create a Canvas and add a Note to it

Objective: create a new Canvas in your Workspace and add a Note to this new Canvas. You will learn how to get the IDs of newly created objects within your Workspace, and how to use them to associate other objects with them. You will need the Workspace ID.

Create Canvas

Endpoint /v1/workspaces/<workspace_id>/elements/canvas
Method POST
Comments You need to know the workspace ID.

Create Note within Canvas

Endpoint /v1/workspaces/<workspace_id>/canvas/<canvas_id>/notes
Method POST
Comments You need to know the Canvas ID.

Code sample

See below code samples in Python and Node.js.

Python Code (python 3.5+)

import requests
import datetime
import pprint

'''

Required modules:
    requests 2.22.0

'''

token = 'ADD_YOUR_TOKEN_HERE'        

if __name__ == "__main__":
    portal = 'https://api.apps.us.bluescape.com' 
    workspace_id = 'ADD_YOUR_WORKSPACE_ID'  # REMEMBER TO ADD WORKSPACE ID

    # Create new Canvas
    # Path:     /v1/workspaces//elements/canvas

    API_endpoint = '/v1/workspaces/' + workspace_id + '/elements/canvas'

    timestamp = datetime.datetime.now()

    data_load = {
        'x': 10000,
        'y': 1000,
        'width': 4000,
        'height': 4000,
        'name': "New Canvas - Creation time: " + str(timestamp),
        'borderColor': 'Yellow'
    }

    the_request = requests.post(
        portal + API_endpoint,
        headers={"Authorization": "Bearer " + token,
                    "Content-Type": "application/json"
                    },
        json=data_load
    )

    json_response = the_request.json()
    # pprint.pprint(json_response) 

    canvas_id = json_response['canvas']['id']


    # Add a Note to a canvas  
    # Path: 	/v1/workspaces//elements/canvas//notes

    API_endpoint = '/v1/workspaces/' + workspace_id + '/elements/canvas/' + canvas_id + '/notes'
    params = ''

    timestamp = datetime.datetime.now()

    # The X and Y coordinates for objects within a Canvas are relative to the top left corner of the Canvas
    data_load = {
        "x": 400,
        "y": 400,
        "text": "Hello! New note, added at " + str(timestamp),
        "backgroundColor": "Red"
    }

    the_request = requests.post(
        portal + API_endpoint,
        headers={"Authorization": "Bearer " + token,
                    "Content-Type": "application/json"
                    },
        json=data_load
    )

    json_response = the_request.json()

    pprint.pprint(json_response)

    note_id = json_response['note']['id']

Node.js Javascript

var axios = require('axios');

/*

How to run:
node this_script_name.js

Requires "axios" module (0.19.0), run:
npm install axios

website: https://github.com/axios/axios

*/

const token = 'SET_YOUR_TOKEN_HERE';
const portal = 'https://api.apps.us.bluescape.com';
const workspace_id = 'SET_WORKSPACE_ID_HERE';
const api_version = 'v1';
var api_endpoint = '/workspaces/' + workspace_id + '/elements/images';

function runRequest(portal,api_version,api_endpoint,the_method,data_load) {
    var request_values = {
        url : portal + '/' + api_version + api_endpoint,
        method : the_method ,
        headers : {
            'Authorization': "Bearer " + token,
            'Content-Type' : 'application/json'    
        },
        data : data_load,
    };

    let req = axios(request_values)
            .catch(error => { 
                console.error('ERROR processing ' + portal + '/' + api_version + api_endpoint);
                console.error(error.message); 
                console.error(error.response.data);
                return Promise.reject(error);
            });;
    
    return req;
}

async function runAPIRequests() {
    try {

        // Create canvas

        api_endpoint = '/workspaces/' + workspace_id + '/elements/canvas';
        the_method = 'POST';
        var currtime = new Date().toISOString().slice(0,16).replace('T',' ');

        data_load = {
            'x': 1000,
            'y': 1000,
            'width': 4000,
            'height': 4000,
            'name': "New Canvas - Creation time: " + currtime ,
            'borderColor': 'Yellow'
        }
        
        var canvas_creation = await runRequest(portal,api_version,api_endpoint,the_method,data_load);

        const canvas_id = canvas_creation.data.canvas.id;

        console.log("canvas ID: " + canvas_id);

        // Now add a Note to the Canvas

        currtime = new Date().toISOString().slice(0,16).replace('T',' ');

        api_endpoint = '/workspaces/' + workspace_id + '/elements/canvas/' + canvas_id + '/notes'
        method = 'POST';
        data_load = {
            "x": 400,
            "y": 400,
            "text": "Hello! New note, added at " + currtime,
            "backgroundColor": "Red"
        }


        var note_creation = await runRequest(portal,api_version,api_endpoint,the_method,data_load);

        var note_id = note_creation.data.note.id;

        console.log('Note ID: ' + note_id);

    } catch (error) {
        console.error('ERROR:');
        console.error(error.message);
    }
}

// Run the requests
runAPIRequests();

OUTPUT

Each time you run a POST API, you will get back a Response Body with the properties of the newly created object. Within this data you can get the object ID and other important information.

Element Json Comments
Image ID ['images'][N]['id'] where N is the N-th workspace in the list.
Image Title ['workspaces'][N]['title'] where N is the N-th workspace in the list.
Image URL ['workspaces'][N]['url'] where N is the N-th image in the list.

Output Json sample

Canvas creation

From this answer you can obtain the newly created Canvas ID: ['canvas']['id']
{'canvas': {'borderColor': 'Yellow',
            'height': 4000,
            'id': '5d3f40a660c539001477f4ea',
            'name': 'New Canvas - Creation time: 2019-07-29 11:53:26.290894',
            'order': 215,
            'width': 4000,
            'x': 10000,
            'y': 1000}
}    

Note Creation

{'note': {'backgroundColor': 'Red',
            'fontWeight': 'normal',
            'height': 320,
            'id': '5d3f40a7b068af0014933ae2',
            'order': 216,
            'pin': False,
            'scale': 1,
            'text': 'Hello! New note, added at 2019-07-29 11:53:26.791257',
            'width': 560,
            'x': 10400,
            'y': 1400}
}

If you have any questions or comments, please contact us at Bluescape support.