Skip navigation
All Places > Blackboard Developer Community > Blackboard Learn Developers > Blog > 2019 > June

We've had reports of REST API calls not working where the sole issue was the System Role Privileges not being set as required. I discovered this because I was trying to duplicate the issue and made this exact mistake - clicking the Ok button at the bottom of the page instead of using the Restrict or  Permit Privileges menu on the page.


Here's the When Ok is NOT OK Video Explanation.



Posted by mkauffman Jun 18, 2019

If you're running into an issue connecting to an AMI instance or a Developer Virtual machine where you get nowhere, or get a response like 'This site can't be reached. The connection was reset.' Use HTTPS!!


https://<my learn site><:port # if any>/


If it's a DVM or an AMI instance that's not had a valid SSL cert installed, you'll have to tell your browser to accept the cert.

I'm writing this blog to help you if you're having difficulty placing content in a course using REST APIs. For this example we'll use an LTI "managed placement" in an Original course. We'll show how to set the managed placement for a Course content tool that has an icon associated with it. One that looks like this Administrator Panel -> LTI Tool Providers -> Manage Placements: -> Edit placement page. (All credit to for the Map tool used in this example.)



1. The first step is to determine the JSON you need for the REST call to create the content. The easy way to do that is to use the Learn UI to go into a course as an instructor and use the UI to place the LTI managed placement link. We did that in a course without much else in it. Course -> Content -> Build Content -> A Tsugi Store Map


2. Now you want to see what the JSON should look like for the REST API call you will make that adds another "A Tsugi Store Map" link to the course. You need the course ID which is shown in the above screenshot as _1465_1. As the instructor, or admin, you can place the following in a web-browsers address field see how that JSON will look.


You will, of course, modify the URL for the Learn system and course you are working with:



The output includes the following JSON. You are looking for a stanza that starts with ,{"id":  and ends with },

,{"id":"_15790_1","parentId":"_15789_1","title":"A Tsugi Store Map","body":"<p>Course Content tool link placed in this Original course by the Instructor Using the UI.</p>","created":"2019-06-03T22:38:57.503Z","modified":"2019-06-03T22:38:57.511Z","position":0,"availability":{"available":"Yes","allowGuests":true,"adaptiveRelease":{}},"contentHandler":{"id":"resource/x-bb-bltiplacement-atsugistoremap","placementHandle":"atsugistoremap"}},


3. Now you can build JSON for the content you want to place. The JSON you create should look like the JSON for the content you discovered, less the id and created fields. For example:

{"title":"Yet Another Tsugi Store Map","body":"<p>Course Content tool link placed in this Original course by a REST API Call.</p>","availability":{"available":"Yes","allowGuests":true,"adaptiveRelease":{}},"contentHandler":{"id":"resource/x-bb-bltiplacement-atsugistoremap","placementHandle":"atsugistoremap"}}


4. Now you can add that to the course. First you get your access token. Then, as an example, use that to make the following call:

ganymede:~ mbk$ curl -k -X POST -H "Authorization: Bearer ZAEwWWGKqbMi3d2lBJOsaFXHbPLn60OF" -H "Content-Type: application/json" --data '{"title":"Yet Another Tsugi Store Map","body":"<p>Course Content tool link placed in this Original course by a REST  API Call.</p>","availability":{"available":"Yes","allowGuests":true,"adaptiveRelease":{}},"contentHandler":{"id":"resource/x-bb-bltiplacement-atsugistoremap","placementHandle":"atsugistoremap"}}'


You should see something like the following as a response:

{"id":"_17041_1","parentId":"_15789_1","title":"Yet Another Tsugi Store Map","body":"<p>Course Content tool link placed in this Original course by a REST API Call.</p>","created":"2019-06-13T00:11:18.660Z","modified":"2019-06-13T00:11:18.675Z","position":2,"availability":{"available":"Yes","allowGuests":true,"adaptiveRelease":{}},"contentHandler":{"id":"resource/x-bb-bltiplacement-atsugistoremap","placementHandle":"atsugistoremap"}}


And... Success! You have your new content in the course:

In conclusion you can use a similar to understand how to use REST to set any of the LTI managed placement  types as content, or any other content type supported by the REST API POST /learn/api/public/v1/courses/{courseId}/contents/{contentId}/children 



Remember to check the model!

If you're getting a 400 response from a REST API call to add a string to Ultra content with the message: "Could not read document: Invalid Blackboard Markup found in..." it's because Ultra restricts input to only valid BbML, a small subset of HTML.  While  your input worked for a Classic course, it does not work for an Ultra course.  For example, the style attribute of the p element is not considered valid BbML. 


So if you were to attempt POST to courses/(courseId)/gradebook/columns for an Ultra course,  and have the following HTML in the description field of the JSON:

{ "name": "A Grade Column Name", "description": "<p style=\"display: none;\">[]</p>",...


you get the 400 response and message.


See: for more details. 


Use only valid BbML.