Skip to content
Versal Partner API
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
README.md
versal-partner-api-swagger.json
versal-partner-api-swagger.yaml

README.md

Versal Partner API

The Versal Partner API enables organizations to manage users, courses, and performance metrics from applications built on top of the Versal Platform.

To get started, try out our interactive API demo.

Concepts

API Keys

API keys grant broad access to organization data on Versal. Among other operations, they can be used to:

  • create and modify organization users
  • create sessions for organization users
  • retrieve organizational courses
  • retrieve learner metrics

If your existing organization has not received an API key, please contact Versal support and we will issue one. If you have not yet registered with Versal, sign up for a free trial to receive your API key.

User Sessions

User sessions grant a single user restricted access to organization resources. They can be used to retrieve, launch, and consume content using the Versal Course Player.

User Org Roles

Users are assigned a role within your organization.

Role Description
admin Admins have full control over all of the resources within the organization. They can add and remove users from the organization, manage user roles, edit and manage courses, and view course analytics.
instructor Instructors can view any course shared with the organization, create and manage their own courses, invite learners to courses, and view course analytics.
learner Learners can enroll in any course shared with the organization.
member Members are associated with the customer organization but have no permissions on any courses or individual orgs. These have to be explicitly granted.

User Course Roles

Users can be assigned a role on a course.

Please note that org roles take precedence over course roles

Role Description
author/contributor Authors or contributors can edit the course.
learner Learners can learn the course.
publisher Publishers can publish newer revisions of the course - all learners only see the latest revision.

Versal Course Player

The Versal Course Player is a browser-based runtime for Versal course content. An overview of its usage and API is available here.

Topics

Requests

All requests and responses reference the Versal Partner API available at: https://stack.versal.com/api2. Requests must be made over HTTPS; requests over standard HTTP will be redirected to the corresponding HTTPS endpoint.

Authentication

All requests to the Versal API must include an SID header with a valid API key or user session ID. If your organization has not received an API key, please please contact Versal support and we will issue one.

curl -H 'SID: YOUR_API_KEY' https://stack.versal.com/api2/courses/123

Pagination

All responses for collections of resources return a subset of the collection and an X-Pagination header describing the total volume of resources available. The body of the header is a JSON object containing pagination information:

X-Pagination: {"count":3737,"page":1,"nextPage":2,"perPage":20,"pageCount":187}

Subsequent pages from the collection endpoint may be retrieved by setting the page query parameter: curl https://stack.versal.com/api2/courses/123/userdata?page=2 -H 'SID: YOUR_API_KEY'

Version: 1.0

Additional Resources

Terms of service:
https://versal.com/terms

Contact Versal Support

This document is also available in Swagger 2.0 format.

Endpoints

Sessions

/sessions


POST

Summary: Add a new user API session

Description: User sessions include the SID needed to launch the Versal Course Player. User sessions have a 30-day lifetime. The session lifetime is refreshed with every use.

Parameters

Name Located in Description Required Schema
SID header API key Yes string (uuid)
body body Indicates the session owner user Yes Session_Input_Model

Responses

Code Description Schema
201 Session created Session_View_Model
400 Bad request Error_View_Model
401 Invalid credentials Error_View_Model
403 Insufficient permissions Error_View_Model
404 User not found Error_View_Model

Users

/orgs/{orgId}/delete_users


POST

Summary: Batch remove a list of users identified by user ID from your organization

Description: See DELETE /orgs/{orgId}/users/{userId}

Parameters

Name Located in Description Required Schema
SID header API key Yes string (uuid)
orgId path Yes integer
body body Yes Batch_Delete_Members_Input_Model

Responses

Code Description Schema
200 OK
400 Bad request Error_View_Model
401 Invalid credentials Error_View_Model
403 Insufficient permissions Error_View_Model
404 Org or User not found Error_View_Model

/orgs/{orgId}/users


POST

Summary: Add a new user to your organization with a role

Description: Add a new user to your organization with a role

Parameters

Name Located in Description Required Schema
SID header API key Yes string (uuid)
orgId path Yes integer
body body Yes Org_User_Input_Model

Responses

Code Description Schema
201 User created Org_User_View_Model
400 Bad request Error_View_Model
401 Invalid credentials Error_View_Model
403 Permission denied Error_View_Model

/user


GET

Summary: Retrieve the user associated with this SID

Description: Retrieve the user associated with this SID

Parameters

Name Located in Description Required Schema
SID header The session ID for the user of interest Yes string (uuid)

Responses

Code Description Schema
200 OK User_View_Model
401 Invalid credentials Error_View_Model

/users/{userId}


PUT

Summary: Update a user record

Description: Both API keys and user session IDs may be used to modify existing users. Note that the PUT verb in this instances behaves as a PATCH: attributes omitted in an update request will simply be ignored by the server.

Parameters

Name Located in Description Required Schema
SID header API integration key or session belonging to the user of interest Yes string (uuid)
userId path Numeric user ID Yes integer
body body Yes User_Patch_Model

Responses

Code Description Schema
201 OK User_View_Model
400 Bad request Error_View_Model
401 Invalid credentials Error_View_Model
403 Insufficient permissions Error_View_Model
404 User not found Error_View_Model

/orgs/{orgId}/users/{userId}


DELETE

Summary: Remove a user from your organization

Description: Removes the user from organization member lists. Revokes the user's permission to interact with resources in your organization. Removes the user's enrollment records for courses in your organization. Untracks the user from course learner reporting.

Parameters

Name Located in Description Required Schema
SID header API integration key Yes string (uuid)
orgId path Your numeric organization ID Yes integer
userId path The numeric user ID Yes integer

Responses

Code Description Schema
200 OK
400 Bad request Error_View_Model
401 Invalid credentials Error_View_Model
403 Insufficient permissions Error_View_Model
404 Org or User not found Error_View_Model
PUT

Summary: Update a user's role in your organization

Description: Change or remove a user's role within your organization

Parameters

Name Located in Description Required Schema
SID header API integration key Yes string (uuid)
orgId path Your numeric organization ID Yes integer
userId path The numeric user ID Yes integer
body body Describes user's updated role Yes Role_Update_Input_Model

Responses

Code Description Schema
201 OK object
400 Bad request Error_View_Model
401 Invalid credentials Error_View_Model
403 Insufficient permissions Error_View_Model
404 Org or User not found Error_View_Model

/orgs/{orgId}/members


GET

Summary: List users in your organization

Description: The organization member listing displays users in your organization and their assigned role. Users that are part of the organization but have not been assigned a role are shown with an empty roles:[] record. Returns a paginated result set.

Parameters

Name Located in Description Required Schema
SID header API integration key Yes string (uuid)
orgId path Your numeric organization ID Yes integer
page query View page of a paginated result set No integer
perPage query Set page size of a paginated result set No integer

Responses

Code Description Schema
200 OK [ Org_Member_View_Model ]
400 Bad request Error_View_Model
401 Invalid credentials Error_View_Model
403 Insufficient permissions Error_View_Model
404 Org not found Error_View_Model

Courses

/courses


GET

Summary: List available courses

Description: Lists courses available to the calling session. Published course revisions are returned when the calling session does not have edit rights for the course. In-edit (sandbox) course revisions are returned when the calling session has edit rights for the course. Returns a paginated result set.

Parameters

Name Located in Description Required Schema
SID header API integration key or user session ID Yes string (uuid)
title query Filter for courses with title containing this string (case insensitive) No string
author query Filter for courses where the given user ID has permission to edit and/or publish the course No integer
catalog query Filter for courses that are published ("labs") or unpublished ("sandbox") No string
page query View page of a paginated result set No integer
perPage query Set page size of a paginated result set No integer

Responses

Code Description Schema
200 OK [ Base_Course_View_Model ]
400 Bad request Error_View_Model
401 Invalid credentials Error_View_Model

/courses/{courseId}


GET

Summary: Retrieve content and metadata of a course

Description: Deep course requests (?depth=full) retrieve the complete content of a course. These requests expose the lesson and gadget IDs required by subsequent requests. The published course revision is returned when the calling session does not have edit rights for the course. The in-edit (sandbox) course revision is returned when the calling session has edit rights for the course. To request the published course revision with a privileged session, use "GET /catalogs/staged/courses/{courseId}"

Parameters

Name Located in Description Required Schema
SID header API integration key or user session ID Yes string (uuid)
courseId path Yes string
depth query Depth "full" returns all course lessons and gadgets. Depth "lessons" returns course lessons only and omits the lesson.gadget[] arrays. No string

Responses

Code Description Schema
200 OK Extended_Course_View_Model
401 Invalid credentials Error_View_Model
403 Permission denied Error_View_Model
404 Not found Error_View_Model

/catalogs/staged/courses/{courseId}


GET

Summary: Request the published revision of the given Course. See "GET /courses/{courseId}"

Parameters

Name Located in Description Required Schema
courseId path Yes string

Responses

Code Description Schema
200 OK Extended_Course_View_Model
401 Invalid credentials Error_View_Model
403 Permission denied Error_View_Model
404 Not found Error_View_Model

Course Learners

/courses/{courseId}/users/{userId}


PATCH

Summary: Mark a learner as tracked for a course

Description: Tracking a user within a course will include that learner's progress in subsequent course progress reports.

Parameters

Name Located in Description Required Schema
SID header API integration key Yes string (uuid)
courseId path Course where learner's progress will be tracked Yes string
userId path Learner's user ID Yes string
body body Toggles learner tracking for the user Yes User_Tracking_Input_Model

Responses

Code Description Schema
200 OK object
400 Bad request Error_View_Model
401 Invalid credentials Error_View_Model
403 Permission denied Error_View_Model
404 Not found Error_View_Model

Course Learner Progress

/courses/{courseId}/userdata


GET

Summary: Retrieve learner progress summaries for a course

Description: Learner progress requests retrieve a summary of the progress of all users enrolled in a specific course. Returns a paginated result set.

Parameters

Name Located in Description Required Schema
SID header API integration key Yes string (uuid)
courseId path Yes string
page query View page of a paginated result set No integer
perPage query Set page size of a paginated result set No integer
userIds query Comma-separated list of user IDs. Results will be filtered to users in this list. No string (CSV)

Responses

Code Description Schema
200 OK Learner_Progress_View_Model
400 Bad request Error_View_Model
401 Invalid credentials Error_View_Model
403 Permission denied Error_View_Model
404 Not found Error_View_Model

Gadget Configurations

/courses/{courseId}/gadgets/{gadgetId}/config


GET

Summary: Retrieve the configuration for a single gadget

Description: Gadget configurations include all user-defined metadata (e.g. the title and questions of a survey) attached to a particular gadget. Schema varies by gadget type. When the calling session belongs to any client with edit permissions on the parent course, the in-edit (sandbox) version of the gadget configuration is returned. When the calling session belongs to a client without edit permissions on the course, the published version of the gadget configuration is returned. When the calling session belongs to a user with edit permissions on the parent course, the response will include the gadget's private fields (e.g., the answer key for a quiz gadget). For all other calling session types, gadget private fields will be redacted from the response.

Parameters

Name Located in Description Required Schema
courseId path ID for the course containing the gadget Yes string
gadgetId path Gadget ID Yes string
SID header API integration key or user session Yes string (uuid)

Responses

Code Description Schema
200 OK object
401 Invalid credentials Error_View_Model
403 Permission denied Error_View_Model
404 Not found Error_View_Model

/catalogs/staged/courses/{courseId}/gadgets/{gadgetId}/config


GET

Summary: Retrieve the published version of the configuration for a single gadget

Description: See "GET /courses/{courseId}/gadgets/{gadgetId}/config"

Parameters

Name Located in Description Required Schema
courseId path ID for the parent course Yes string
gadgetId path Gadget ID Yes string
SID header API integration key or user session Yes string (uuid)

Responses

Code Description Schema
200 OK object
401 Invalid credentials Error_View_Model
403 Permission denied Error_View_Model
404 Not found Error_View_Model

Gadget Learner Data

/courses/{courseId}/lessons/{lessonId}/gadgets/{gadgetId}/userdata


GET

Summary: Retrieve user data for a single gadget

Description: Gadget user data requests return the interactions of all users with a particular gadget (e.g. user responses to a quiz). Returns a paginated result set.

Parameters

Name Located in Description Required Schema
courseId path ID for the parent course Yes string
lessonId path ID for the parent lesson Yes string
gadgetId path Gadget ID Yes string
page query View page of a paginated result set No integer
perPage query Set page size of a paginated result set No integer
SID header API integration key or user session Yes string (uuid)

Responses

Code Description Schema
200 OK [ Gadget_User_Data_View_Model ]
401 Invalid credentials Error_View_Model
403 Permission denied Error_View_Model
404 Not found Error_View_Model

Models


Base_Course_View_Model

Name Type Description
catalogs [ string ] Contains 'labs' if the course has been published
courseId string Duplicate of id.
coverImage object Course cover image metadata. Omitted if the course does not have a cover image.
createdAt date Course creation time
id string Unique, API-generated course identifier
public boolean Indicates whether the course is publicly available
longDesc string A paragraph statement describing the course. Omitted if not defined.
shortDesc string A summary statement of the course. Omitted if not defined.
tags [ string ] A list of user-defined tags indicating course metadata
title string Course title. Omitted if not defined.
users [ User_View_Model ] Lists users with rights to edit and/or publish the course

Batch_Delete_Members_Input_Model

Name Type Description
users [string] List of user IDs

Error_View_Model

Name Type Description
error integer HTTP error code
message string Describes the error condition

Extended_Course_View_Model

Name Type Description
catalogs [ string ] Contains 'labs' if the course has been published
courseId string Duplicate of id.
coverImage object Course cover image metadata. Omitted if the course does not have a cover image.
currentPosition Learner_Course_Position_View_Model Information about the session user's most recent course activity. Omitted if the user has not visited the course or if the calling session is an API key.
createdAt date Course creation time
id string Unique, API-generated course identifier
public boolean Indicates whether the course is publicly available
longDesc string A paragraph statement describing the course. Omitted if not defined.
shortDesc string A summary statement of the course. Omitted if not defined.
status string "complete" if the session user has completed the course. Omitted if the user has not completed the course or if the calling session is an API key.
tags [ string ] A list of user-defined tags indicating course metadata
title string Course title. Omitted if not defined.
users [ User_View_Model ] Lists users with rights to edit and/or publish the course
lastPublished date Date of most recent course publication
lessons [ Lesson_View_Model ]

Gadget_View_model

Name Type Description
id string Gadget identifier. Unique within a course.
type string Gadget type
config object Schema varies by gadget type

Gadget_User_Data_View_Model

Name Type Description
user User_View_Model
state object Schema varies by gadget type

Learner_Course_Position_View_Model

Name Type Description
currentLessonId string Learner's last visited lesson ID
currentLessonIndex integer Learner's last visited lesson index
updatedAt date Learner's last course visit date

Learner_Progress_View_Model

Name Type Description
completeDate date Date learner completed the course. Omitted if learner has not completed the course.
lastActivity date Date learner last visited the course
email string (email) Learner's email address. Omitted if not available.
courseCompleted boolean Indicates whether learner has completed the course
firstname string Learner's given name. Omitted if not available.
currentLesson integer Index of last visited lesson
lastname string Learner's family name. Omitted if not available.
id string Learner's user ID
fullname string Learner's full name. Omitted if not available.
title string Course title
startDate date Date learner started the course
currentLessonId string ID of last visited lesson

Lesson_View_Model

Name Type Description
id string Lesson identifier. Unique within a course.
title string Lesson title.
gadgets [ Gadget_View_model ]

Member_View_Model

Name Type Description
id string User API ID
firstname string Given name
lastname string Family name
fullname string Full name
email string (email)

Org_Member_View_Model

Name Type Description
user Member_View_Model
roles [ string ] Accepted values: "admin", "instructor", "learner"

Org_User_Input_Model

Name Type Description Required
roles [ string ] Accepted values: "admin", "instructor", "learner", "member" Yes
user User_Input_Model Yes

Org_User_View_Model

Name Type Description
roles [ string ] Values: "admin", "instructor", "learner"
user User_View_Model

Role_Update_Input_Model

Name Type Description Required
roles [ string ] Accepted values: "admin", "instructor", "learner" Yes

Session_Input_Model

Name Type Description Required
userId string (int64) Required if email is not given (Yes)
email string (email) Required if userId is not given (Yes)

Session_View_Model

Name Type Description
sessionId string
user User_View_Model

User_Input_Model

Name Type Description Required
email string (email) Unique email address Yes
firstname string Given name No
lastname string Family name No
fullname string Full name No
longDesc string A paragraph about the user No
shortDesc string A brief statement about the user No

User_Patch_Model

Name Type Description Required
firstname string Given name No
lastname string Family name No
fullname string Full name No
longDesc string A paragraph about the user No
shortDesc string A brief statement about the user No

User_Tracking_Input_Model

Name Type Description
tracked boolean Whether the user is tracked for the course
roles [ string ] Accepted values: "learner", "author", "contributor", "publisher"

User_View_Model

Name Type Description
id string (int64) Unique API-generated identifier
username string A unique, human-readable user identifier
email string (email) Unique email address
firstname string Given name
lastname string Family name
fullname string Full name
fn string Alternate full name
displayname string A calculated display name based on available non-null name fields
longDesc string A paragraph about the user
shortDesc string A brief statement about the user
image object Profile image asset metadata
You can’t perform that action at this time.