Using Watershed's API

In addition to interacting with Watershed via xAPI, Activity providers can connect to Watershed’s API to get, set, modify and delete various data relating to Watershed’s configuration. This guide provides an introduction to Watershed’s API, some generic information that applies to several API resources and links to guides relating to specific aspects of the API.

This guide consists of 4 sections:

Connecting to Watershed’s API

To connect to Watershed’s API you need a set of credentials and organization id (unless you are creating an organization, then you don’t need the id).

To create a set of credentials, see How do I add an activity provider to Watershed? You are able to choose if credentials have access to the LRS API, the Reporting API or both. 

This is passed to the API using Basic HTTP Authentication. In addition to the Authorization header required for Basic Authentication, all POST and PUT requests must have a Content-Type header with the value application/json.

The easiest way to find the organization id is to log in to Watershed and go to the Settings/Data page. The organization id is included within the Watershed LRS Endpoint URL. For example if the endpoint URL is then the organization id is 1234.

Please note: Activity Provider credentials will only work for xAPI LRS requests; they cannot be used to interact with other resources.

Collections and Paging

Many resources, when responding to a GET request, will return results in the form of a collections object.






The number of records matching the filter.



An array of results returned.

These endpoints, in addition to the parameters listed in their documentation, also support parameters that can be used for paging. 






The maximum number of items to include in the collection’s results array. Limit defaults to 100 and has a maximum of 1000. 



The index of the first item to include in the collection's results array. Defaults to 0. 

Please note: some resources return a simple array rather than a collection object. These resources do not support the _limit and _offset parameters. See the documentation for individual resources.

Searching and sorting

Some resources support query parameters that can be used to match against when making a GET request. See the documentation for individual resources for available parameters. Normal behavior of these parameters is to search for exact matches, however any query parameter can be prefixed with in_ to enable partial matches. For example, in_description="course" would return records where the description contained the word “course”.

It’s also possible to sort results using the order_by parameter. The value of this parameter is any property of the object being requested which contains a string or integer value. For example, you can request people by id, name or created. You can’t order people by personas because the personas property contains an array.

Results are ordered ascending by default. Results can be ordered descending by prepending “-” to the sort property’s name. The order_by parameter can contain a single property to sort by or a comma separated list.

For example, order_by="name,-id" will first sort by name in ascending order, then sort by id in descending order.

Links to Specific API Documentation

Here's a list of published documentation around Watershed's APIs.

Was this article helpful?
1 out of 2 found this helpful

If you can't find what you need or you want to ask a real person a question, please contact customer support.