Watershed's APIs

Watershed is a learning analytics platform that provides actionable insights from your training and performance data. Built using modern practices for data processing and cloud-based platforms, we provide several APIs that allow you to integrate Watershed with external applications.

These APIs allow outside applications to access a wide range of Watershed’s capabilities, including:

  • sending data into the learning record store (LRS);
  • retrieving aggregated report data; and
  • managing core entities—such as organizational metadata, dashboards, reports, accomplishments, and accounts.

Connecting to Watershed’s APIs

Our family of REST APIs are made accessible through a secure SSL connection over HTTP, using basic authentication or OAuth 2. To connect to Watershed’s API you need a set of credentials and organization 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, the APIs or both.

The easiest way to find the organization id is to log in to Watershed and go to the Data > xAPI Data page. 

The organization id is included within the Watershed LRS Endpoint URL. For example if the endpoint URL is https://watershedlrs.com/api/organizations/1234/lrs/ then the organization id is 1234.

You can also use the Credentials API to create new API credentials.

Rate Limiting

Watershed limits each set of credentials to 3000 requests a minute. Anything over this rate will be responded to with a HTTP 429 Too Many Requests response status code.

LRS APIs

Conforming with the core Experience API (xAPI) specification, our LRS API allows applications to interact with the data in your LRS using the standardized xAPI communication protocol.

The Statements API provides the ability to add and retrieve xAPI interaction statements, void statements, and search for statements by agent, activity, or context data.

The Agent, Activity, and State APIs allow for flexible data to be stored and retrieved from an LRS. These key-value stores let applications manage stateful data about an agent, activity, or a combination of the two.

For more information about the xAPI API resources please consult the xAPI specification.

Aggregation API

Our Aggregation API demonstrates one of Watershed’s most valuable capabilities: aggregating xAPI and organizational data into reporting results that provide insights. Some of the features made possible by these APIs include:

  • Data retrieval for an existing report or set of reports created through the Watershed application
  • A highly flexible query and Aggregation API to filter, group, and sort data according to any fields available in your LRS or organizational data
  • Valuable reports such as:
    • activity timelines,
    • score results,
    • assessment question analysis,
    • learning program results,
    • and many more.

Any person or group of people in your organization can filter these reports. Furthermore, reports are filtered according to the specific account holder’s permissions, which can be modified via the Watershed interface or our Groups API.

Data Import and Export APIs

Our Data Import API allows applications to import data that is not already in the standard xAPI format. Specifically, the CSV format can be used to import data that has been exported from another system or tool into Watershed. This API allows outside systems to import data on a regular schedule and provides a great avenue for bringing important data into Watershed.

The Export API allows applications to download the full set of xAPI data from the LRS in the form of JSON or CSV, which can then be accessed with other external tools or sent to another LRS. The API also has the ability to create connections with other LRSs that automatically import or export data on a regular schedule.

Dashboards and Reports APIs

Our Dashboard and Reports API allows outside applications to save and organize reports while also allowing users to see these reports in the Watershed interface. With this API, for example, an integrated application can create a new activity report for the most active courses in its library or manage dashboards for each group of users present in the application.

Groups, People and Permissions APIs

The Groups, People and Permissions APIs enable outside HR systems or employee data record systems to import and modify data about the people and groups in your organization and control who can access it. Examples of data that can be imported include:

  • Organizational hierarchy (e.g., teams, divisions, regions)
  • Functional groups (e.g., managers, sales staff, production staff)
  • Location-based groups (e.g., United States, Europe, Asia)
  • Any other flat or hierarchical set of groups

Group information can be used in any of the reports provided by Watershed, such that aggregated data can be filtered, categorized, or sorted according to groups. Additionally, the Groups and Permissions APIs manage reporting permissions, which are then automatically used across all reporting capabilities.

Administration APIs

The Administration APIs can be used to manage various aspects of Watershed, such as:

  • Credentials and permissions for Learning Record Provider accounts
  • Account membership and permissions for an organization
  • Profile information for an authenticated account
  • Organization information, such as name and logo
  • Debug logging for the LRS
Was this article helpful?
0 out of 0 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.