models.md

Types and request/response models

Primitive types

object

The JSON object type.

string

The JSON string type.

number

The JSON number type.

integer

A number that does not have a fractional part.

boolean

One of the JSON values true or false.

date

A string with a date in ISO 8601 format.

date-time

A string containing a date and time in ISO 8601 format.

slug

A string containing only the following ASCII characters:

• Uppercase letters (A-Z)
• Lowercase letters (a-z)
• Digits (0-9)
• +, -, or _

email

A string containing an email address. Our (non-standard) definition of an email address is given by the following grammar:

• email ::= email-char+ @ email-char+
• email-char ::= any character other than the following:
  • @ (at-sign)
  • (space)
  • \t (horizontal tab)
  • \n (new line)
  • \v (vertical tab)
  • \f (form feed)
  • \r (carriage return)

org role

A string having one of the following values:

• admin
• instructor
• learner

org status

A string having one of the following values:

• TRIAL
• ACTIVE
• EXPIRED

This field indicates whether a VFO container is a trial, a paid org (active) or an expired trial. All orgs start out as trials.

org type

A string having one of the following values:

• container
• base
• portal
• topic

location data

Field	Type	Description
streetAddress	string	House number and street.
extendedAddress	string	(Optional) A second line in the address.
locality	string	Name of the town, city, or other locality.
region	string	US state (e.g. "California") or other regional division within country.
postalCode	string	US or other country postal code.
countryName	string	E.g. "USA" or other country name.

uuid

A string containing a UUID produced by calling the Java method java.util.UUID.randomUUID.

gadget type

A string in the format $devKey/$name, with an optional suffix @$version, where devKey is the user key of the gadget developer, name is the slug-format name of the gadget, and version is the gadget version.

gadget version

A string in the format $major.$minor.$patch, where major, minor, and patch are non-negative integers.

gadget catalog

A string having one of the following values:

• sandbox: The gadget has been uploaded, and can be used in courses, but those courses cannot be published.
• approved: The gadget is approved for use in published courses.
• rejected: The gadget is rejected for use in published (or any) courses, and will not appear to authors.
• deprecated: A newer version of a gadget with the same developer and name has been uploaded and approved.

user key

A string that is either a username (in slug format) or a user ID.

course key

A string that is either a course ID or encodes a 64-bit signed integer, which is the "internal" database ID of the course. The internal ID is still in use for historical reasons, but should eventually be phased out.

ID types

To be valid, a value of an ID type must denote an existing object.

ID type	Base type	Additional constraints
asset	uuid	None.
asset representation	uuid	None.
bundle id	string	Parseable as a 64-bit signed integer.
course	string	An arbitrary sequence of lowercase letters (a-z) and digits (0-9). Minimum length of six characters. The intent is for the IDs to be non-sequential and therefore hard to guess.
course instance	string	Parseable as a 64-bit signed integer.
gadget instance	string	None.
gadget manifest	string	Parseable as a 64-bit signed integer.
lesson	string	None.
org	string	Parseable as a 64-bit signed integer
program	string	Parseable as a 64-bit signed integer.
session	uuid	None.
tray label	string	None.
user	string	Parseable as a 64-bit signed integer.
lock	string	Parseable as a 64-bit signed integer.
userGroupId	string	Parseable as a 64-bit signed integer.

Models

When JSON object models are supplied in request bodies, it should be assumed that all specified fields are required, and all unspecified fields are ignored. Any differences from the default behavior should be documented in each endpoint. For JSON object models supplied in response bodies, each field will be provided unless it is undefined, again with execeptions from the rule documented on a per-endpoint basis.

Address

Field	Type	Description
streetAddress	string	Number and street
extendedAddress	string	Apartment, suite, floor, etc.
locality	string	City, town, village, etc.
region	string	State, county, province, etc.
postalCode	string	e.g. ZIP code
countryName	string	e.g. United States of America or USA

Asset

Field	Type	Description
id	asset ID	Unique API-generated identifier.
title	string	Asset title.
tags	array of string	A sorted sequence of labels, intended to describe the asset and be useful for categorizing it or finding it in a search.
representations	array of asset representation	Contains metadata about each specific media file that can be used to display the asset.

Asset representation

Field	Type	Description
id	asset representation ID	Unique API-generated identifier.
location	string	The path under which the representation's content can be found in storage.
contentType	string	The Internet media type of the representation.
original	bool	true if the representation was uploaded by an API client; false if the representation was generated from the original.
scale	string	The height and width of the representation in pixels, e.g. "640x480".
available	bool	true if the representation is available at location in storage; false if is not (yet) available; and omitted if it will never be available (e.g., because video transcoding was disabled when the asset was uploaded).

Authenticator access

Field	Type	Description
authenticator	authenticator ID	Unique API-generated identifier
role	program role	Authenticator's role within a program

Billing contact

Field	Type	Description
address	address	The billing address.
name	string	Name of the person or entity being billed.
phone	string	Contact phone number.
email	string	Contact email address.

Command rejection

A JSON object of the form {"$commandId": {"_1": $status, "_2": "$message"}}, where

• commandId is the ID of the command that was rejected;
• status is the HTTP status code of the response;
• message is the error message provided with the response.

Base course

Field	Type	Description
authorBio	string	A description of the author(s) of the course. Omitted if not defined.
catalogs	array of string	Always contains sandbox, because the course is always editable. Will also contain labs if the course has been published.
courseId	course ID	Duplicate of id.
coverImage	asset	An image representing the course. Omitted if the course does not have a cover image.
createdAt	date-time	The creation time of the course.
currentPosition	progress	Information on the user's progress in the course. If null, the user does not have any progress (i.e., they have not started the course).
duration	string	Legacy field defining the number of seconds a session of this course would last, formatted as an integer.
id	course ID	Unique, API-generated identifier.
isEditable	boolean	Has value true if the requesting user can edit the course; false otherwise.
longDesc	string	A paragraph or longer description of the course. Omitted if not defined.
org	org	Information about the course's org, if it belongs to one. Otherwise omitted.
palette	array of gadget manifest	The manifests of all gadget instances in the course.
programId	program ID	The ID of the program the course belongs to.
public	boolean	Whether or not the course is in a public program.
revision	course revision	Omitted if the course state does not correspond to a saved revision. Has value null if the course sandbox is published (legacy publishing). Otherwise, the value is an object describing what revision the course state corresponds to.
shortDesc	string	A summary statement of the course. Omitted if not defined.
status	string	Has the value complete if the requesting user has finished the course. Omitted otherwise.
tags	array of string	Tags associated with the course, ordered lexicographically.
title	string	The title of the course. Omitted if the course doesn't have a title.
theme	theme revision	The theme revision assigned for the course. Optional.
themeId	theme ID	The ID of theme to be assigned for the course. Optional.
users	array of course publisher	The users with publishing rights for the course.
vfo	array of response org	The list of VFO orgs where the course is shared (possibly, an empty list).
isBlendedCover	boolean
coverColor	string	html color value: from #000 to #fff and from #000000 to #ffffff, case insensitive
containerId	org ID	VFO container Id for a course, if it belongs to one
settings	object	Any valid JSON object.

Course details

A base course extended with the following fields:

Field	Type	Description
assetUrlTemplate	string	Provides a template which, when an asset ID is substituted into it, produces a URL where that asset's content can be retrieved. This allows clients to not have to know where assets are stored; they can determine the location using this field.
isTracked	boolean	Whether or not the user is tracked in the course's program.
isBlocked	boolean	Whether or not completion of the course is blocked, e.g., by a quiz that must be passed to proceed.
lessons	array of lesson	The lessons of the course, in order.
lastPublished	date-time	Timestamp of the recent revision publishing.

Course response

A base course extended with the following fields:

Field	Type	Description
authors	array of course author	Information on each author of the course.

Course author

Field	Type	Description
id	user ID	The user ID of the course author.

Course publisher

A response user object with only the fields username, fn, fullName, image, and the following extra field:

Field	Type	Description
permissions	array of string	An array, either empty or containing the single element PublishCourses.

Theme revision

JSON object representation of the most recent revision for specific theme ID.

Field	Type	Description
themeId	theme ID	Theme ID
revisionId	theme revision ID	Revision ID. Most recent for specific theme ID.

Course revision

Field	Type	Description
createdAt	string	The date and time when the course revision was created, as specified by java.sql.Timestamp.toString().
revisionId	course instance ID	Unique, API-generated identifier.

Course revision data

Field	Type	Description
courseId	course ID	A new revision was created for this course.
revisionId	course instance ID	Unique, API-generated identifier for the new course revision.

Course grade statistics response

Field	Type	Description
total_learners	integer	Total number of all tracked learners in the course.
avg_score	number	Average cumulative grade among all tracked learners who completed the course, between 0 and 1.
quizzes	array of course grade statistics quiz response	Average scores for each quiz-like gadgets.

Course grade statistics quiz response

Field	Type	Description
name	boolean	Name of the quiz-like gadget.
title	string	The title of the quiz-like gadget. (The title attribute of the gadget's config.)
learners	integer	The number of tracked learners who submitted any responses for this gadget.
avg_score	number	Average score, between 0 and 1, over all tracked learners who submitted any responses to this gadget.

Course user quiz grade response

Field	Type	Description
id	string	Gadget instance ID in the course.
name	boolean	Name of the quiz-like gadget.
title	string	The title of the quiz-like gadget. (The title attribute of the gadget's config.)
score	number	Score, between 0 and 1, computed for this gadget.

Course user data response

Field	Type	Description
id	user ID	User ID
email	string	User's email
title	string	Title of the course
lastActivity	date-time	Timestamp of last activity of the user in the course
courseCompleted	boolean	True if course was completed
currentLessonId	lesson ID	Last visited lesson's ID
lastSurveyCompleted	string	Title of the last survey completed (if applicable)

Course user update request

Field	Type	Description
tracked	boolean	(Optional) Set the user to tracked or not tracked for the given course
roles	Array of string	(Optional) Set the user's roles in the given course. Allowed roles: "author", "contributor", "publisher". One or more roles can be specified.

Course user update response

A Course user update request augmented with the following fields:

Field	Type	Description
user	Response user	User whose permission information was requested.

Note that the "publisher" role subsumes the "author" role, and the "author" role is listed only if "publisher" is not present.

Field	Type	Description
tracked	boolean	(Optional) Set the user to tracked or not tracked for the given course
roles	Array of string	(Optional) Set the user's roles in the given course. Allowed roles: "author", "contributor", "publisher". One or more roles can be specified.

Course progress response

Field	Type	Description
completed	boolean	Whether the user has completed the course.
currentPosition	progress	Information on the user's progress in the course. If null, the user does not have any progress (i.e., they have not started the course).
cumulativeGrade	number	Cumulative grade of the user in the course.

Course userstate response

Field	Type	Description
currentPosition	progress	Information on the user's progress in the course. If null, the user does not have any progress (i.e., they have not started the course).
userstates	map from gadget instance IDs to gadget user states

Cumulative grade

The cumulative grade is a floating-point number between 0 and 1, rounded to 2 digits after the decimal point. This is the score achieved by the user in the course, counting all quiz-like gadgets in the course.

Quiz-like gadgets are gadgets complying with the Quiz 1.0 API. Currently these gadgets are whitelisted in the code (see CourseEndpoints.scala, in the class GetCourseStatistics, the value allowedGadgetNames) as quiz, am-sample-quiz (used in tests only), critical-reading, math, writing.

The cumulative grade is computed by finding all quiz-like gadgets in the course, grading each one on the scale between 0 and 1 (so all quiz-like gadgets have equal weight). All these gadget scores are added and divided by the total number of quiz-like gadgets in the course. So, the cumulative grade is 1.0 only if the user has achieved 100% on each quiz-like gadget in the course.

If the user never submitted a quiz, the grade is 0 for that quiz. The cumulative grade is also 0 if there are no quiz-like gadgets in the course.

Gadget grade response

This response applies to quiz-like gadgets.

Field	Type	Description
user	{"id": user ID}	The user's id
grade	number	Grade for that user

Course user response

Field	Type	Description
course	course progress response	The current progress of the user in the course.
gadgets	array of gadget instance response	All gadgets in the course, with their userstates for this user.
user	response user	User information.

Features

Field	Type	Description
key	String	The feature key name
isEnabled	Boolean
config	String	Optional configuration data for the feature

Here are the features currently known to the API:

• disassociateCourseIdWithCommandId
• enforceIncrementalGadgetVersions
• gadgetApproval
• restrictUpdateCourseUser
• superadminPutCourse
• usernames
• validateGadgetPalette
• autoEnrollCourses

Use the update features endpoint to create a new feature name.

autoEnrollCourses takes a comma-separated list of course keys as its config value. For example: "crs123","crs456". Other features do not use the config field.

Gadget config

An arbitrary JSON object that defines the appearance and behavior of a gadget instance in a course. There is no spec for it because each gadget stores different data in it.

Base gadget instance

Field	Type	Description
config	gadget config	The configuration of the gadget instance.
type	gadget type	The gadget type that the instance derives from.

Gadget instance request

This is used to insert a new gadget into a lesson.

Contains all of the fields in base gadget instance, plus the following:

Field	Type	Description
index	integer	(Optional) The zero-based index at which to insert the gadgets into the lesson. Default is to add to the end of lesson.

Many gadgets request

This is used to insert many new gadgets at once into a lesson.

Field	Type	Description
index	integer	(Optional) The zero-based index at which to insert the gadgets into the lesson. Default is to add to the end of lesson.
gadgets	Array of base gadget instance

Gadget instance response

Contains all of the fields in base gadget instance, plus the following:

Field	Type	Description
id	gadget instance ID	Gadget instance identifier. Must be unique within the instance's lesson, but it is not required to be globally unique. Can be specified by the user in certain cases.
userState	gadget user state	The user state of the gadget instance, for a particular user.

Gadget manifest

Field	Type	Description
author	string	Name of the gadget's author. (Optional.)
documentationUrl	string	URL for a tutorial document explaining the usage of the gadget. (Optional.)
defaultConfig	gadget config	Config to use when an instance of the gadget is added to a course.
description	string	Description of the gadget.
exampleUrl	string	URL for a brief demonstration of the gadget. (Optional.)
exec	string	How gadget logic is executed on the server, if applicable. (Optional.)
id	gadget manifest ID	Unique, API-generated identifier.
latestVersion	gadget version	The highest approved version out of all gadget manifests having the same developer user and gadget name.
launcher	string	Used only by the frontend. Admissible values include "iframe" and "react". (Optional.)
name	slug	Name of the gadget. A developer can upload multiple gadgets related by name, but having different versions.
noToggleSwitch	boolean	Used only by the frontend.
noAudioRecorder	boolean	Used only by the frontend.
noAudioPlayer	boolean	Used only by the frontend.
private	array of string	Names of gadget config fields that should only be seen by authors, e.g. a quiz answer key. The fields will be removed from gadget configs before sending them to learners.
responsive	boolean	Indicates whether the gadget supports responsive (mobile) display. Defaults to false.
status	gadget status	Modifiable properties of the gadget.
title	string	Display name of the gadget.
username	string	The developer's username if it exists, otherwise their user ID.
version	gadget version	The version number of the gadget.
baseUrl	string	The base URL of the gadget project.

Note: baseUrl is a computed field, that is, the gadget author does not need to specify it when uploading a gadget, and if specified, this field will be ignored during upload. The platform will compute this URL when fetching the gadget manifest. An example value is /gadgets/versal/slideshow-iframe/0.2.4/

Gadget status

Field	Type	Description
catalog	gadget catalog	The lifecycle state of the gadget.
hidden	boolean	Whether or not the gadget is hidden from the user interface.

Gadget user state

An arbitrary JSON object that stores any persistent state of a user's interaction with a gadget instance. There is no spec for it because each gadget stores different data in it.

Lesson

Field	Type	Description
gadgets	array of gadget instance response	The gadget instances in the lesson, in order of appearance.
id	lesson ID	Lesson identifier. Must be unique within the course instance, but it is not required to be globally unique. Can be specified by the user in certain cases.
isAccessible	boolean	Whether or not the lesson can be viewed, due to blocking from e.g. a quiz that must be passed to proceed. Lessons after a blocked lesson are not accessible.
title	string	The lesson title.

Org

Field	Type	Description
address	address	The mailing address of the org. Omitted if not defined.
billing	billing contact	Contact information for billing the org. Omitted if not defined.
id	org ID	Unique, API-generated identifier.
image	asset	Asset metadata for the image representing the org. Omitted if not defined.
title	string	Word or short phrase naming or describing the org. Omitted if not defined.
orgName	slug	A unique, human-readable user identifier. It is used in the type strings of gadgets created by the org in place of the org ID, if defined.
users	array of org member	Contains one element for each user belonging to the org.

Org member

Field	Type	Description
user	user	The user belonging to the org.
roles	array of org role	The user's roles in the org.

Org member role update

Field	Type	Description
roles	array of org role	The user's roles in the org.

Progress

Field	Type	Description
currentLesson	integer	One-based index of the lesson in the most recent progress update.
lastLesson	integer	One-based index given by currentLesson before the most recent progress update.
currentLessonId	string	Lesson ID of the current lesson in the most recent progress update.
visitedRevisionId	course instance ID	The ID of the last visited course revision.
maxLessonId	string	The ID of the highest-indexed lesson the learner has visited in the course.
availableLessonCount	integer	Total number of lessons available in the last visited course revision.
updatedAt	date-time	Date and time of the most recent progress update.

Progress update

Field	Type	Description
lessonIndex	integer	DEPRECATED One-based index of the lesson that the learner has reached. (Optional, deprecated.)
currentLesson	integer	DEPRECATED One-based index of the lesson that the learner has reached. (Optional, deprecated.)
currentLessonId	string	Lesson ID of the lesson that the learner has reached. (Optional until transition to new site code.)

When this data is used as request body for updating the progress information, one or both of lessonIndex or currentLessonId may be specified. If currentLessonId is specified, lessonIndex is ignored.

When this data is used as response for fetching the progress information, all three fields will be reported (for compatibility).

Position update

Field	Type	Description
displaySection	slug	Learner current page in standalone player
currentLessonId	string	Lesson ID of the lesson that the learner has reached. (Required if displaySection value is LESSON)

When this data is used as request body for updating the progress information. If displaySection is not equal LESSON, currentLessonId is ignored.

Session

Request session

Field	Type	Description
userId	user ID	The session user.
email	email	The email address of the session user.
expiresIn	number	DEPRECATED - HAS NO EFFECT The duration of the session, in milliseconds. Must be a non-negative integer.

Response session

Field	Type	Description
sessionId	session ID	Unique, API-generated identifier.
user	response user	The owner of the session.

Response session information

Field	Type	Description
sessionType	string	Self-explanatory. It is one of the following values: PartnerKey, InternalIntegrationKey, LegacyAuthenticator, VFOAccessKey, VFOUserSession, PlainUserSession.
userId	user ID	The session user if user session. Otherwise not present.
vfoRootOrgId	org ID	ID of the VFO org if VFO session. Otherwise not present.
isVFOContainerLocked	boolean	Self-explanatory.

Subscription

Field	Type	Description
type	string	Self-explanatory. It currently has a single allowed value, VersalPro.

Using an object instead of a string leaves room for adding more fields in the future.

User

Base user

Field	Type	Description
username	slug	A unique, human-readable user identifier. It is used in the type strings of gadgets created by the user in place of their user ID, if defined.
email	email	Unique email address.
firstname	string	Given name.
lastname	string	Family name.
fullname	string	Full name.
fn	string	Alternate full name.
displayname	string	Formatted display name chosen from user's non-null name fields. Display name is chosen in the following order: fullName, fn, firstName + " " + lastName, firstName, lastName, "Unknown"
company	string	Legacy field.
country	string	Legacy field.
location	string	Place of residence.
longDesc	string	A paragraph about the user.
name	string	Legacy field.
newsletter	string	Legacy field.
newsletter_lang	string	Legacy field.
registered	boolean	Legacy field.
shortDesc	string	A brief statement about the user.
state	string	Legacy field.
usage	string	Legacy field.
website	string	The URL of the user's website.
zip	string	Legacy field.

Response user

A base user extended with the following fields:

Field	Type	Description
id	user ID	Unique API-generated identifier.
image	asset	Profile image asset metadata.
orgs	array of org	Orgs the user belongs to.
subscriptions	array of subscription	Subscriptions granted to the user.
marketingRoles	marketing roles	Marketing roles of the user.

Marketing roles

A set of fields, which describe user roles:

Field	Type	Description
isAdmin	boolean	If user has AdministerOrg permission in at least one org.
isInstructor	boolean	If user has TeachCourses permission without AdministerOrg in at least one org.
isLearner	boolean	If user is enrolled in at least one course, but he is not administrator, instructor, nor course editor.

Version

Text, not JSON. An example:

 project: rest-api
 version: 0.110.3
git hash: 27e80d2
   built: 10 Feb 2015 16:42:14 PST
     tag: rapi6

Healthcheck

Healthcheck result

Field	Type	Description
passed	boolean	true if single check passed.
details	Any	Optional details of why the single check passed or failed.

Healthcheck summary

Field	Type	Description
passed	boolean	true if application is ready to take requests.
results	Map(string, healthcheck result)	Results of each single check.

Custom trays

Custom tray request

Field	Type	Description
label	slug	Tray ID
title	string	Human-readable title of the tray.
public	boolean	(Optional, default = false) Whether the tray is public (can be read by other users).

Custom tray response

Field	Type	Description
title	string	Human-readable title of the tray.
bundles	array of bundle item responses	An ordered collection of bundle items that exist in the tray.

Bundle item response

Field	Type	Description
id	bundle ID	ID of the bundle.
title	string	(Optional) A short title of the bundle.
icon	string	(Optional) The bundle's icon URL.
provider_id	string	(Optional) The ID of this bundle as given by the bundle's provider.
gadgets	array of base gadget instance	An ordered collection of gadget items in the bundle.
manifests	array of gadget manifest	A set of manifests for all gadget items in the bundle, sorted by gadget type.

Bundle item metadata request

Field	Type	Description
title	string	(Optional) A short title of the bundle.
icon	string	(Optional) The bundle's icon URL.

Bundle item request

Field	Type	Description
index	integer	(Optional, default = 0) Zero-based index at which a new bundle must be inserted into a tray.
title	string	(Optional) A short title of the bundle.
icon	string	(Optional) The bundle's icon URL.
provider_id	string	(Optional) The ID of this bundle as given by the bundle's provider.
gadgets	array of base gadget instance	An ordered collection of gadget items in the new bundle.

Versal For Organizations (VFO)

Base org

Field	Type	Description
name	string	(Optional) A short name of the org.
status	org status	(Optional) Org Status
website	string	(Optional) Website
location	string	(Optional) Location
image	asset	(Optional) Asset metadata for the image representing the org. When creating org, the asset can contain only the asset id.
location	location data	(Optional) Organization's geographical location.
website	string	(Optional) The org's website URL.

VFO org info request

Field	Type	Description
name	string	(Optional) A short name of the org.
image_id	asset ID	(Optional) Unique API-generated identifier for the org image (obtained from the API after uploading an image asset).
location	location data	(Optional) Organization's geographical location.
website	string	(Optional) The org's website URL.

Response org

Base org extended with the following fields:

Field	Type	Description
id	org ID	ID of the org.
parentId	org ID	ID of the org's parent
containerId	org ID	ID of the org's container
orgType	org type
settings	object	Any valid JSON object.

Org Status Update Model

Field	Type	Description
orgStatus	org status	New value for org status

Org Status Response Model

Field	Type	Description
orgId	org ID	ID of the org
orgStatus	org status	New value for org status

Org configs

Field	Type	Description
isPortalEnabled	boolean	Does this org have org portals?
defaultOrgPortalId	org ID	ID of the default org portal
providers	Array of String	(Optional) Org Portal providers
learnerTrackingMethod	string	(Optional) Valid values - per-course or org-wide; defaults to org-wide
defaultThemeId	theme ID	(Optional) Theme ID.
settings	object	Any valid JSON object.

Reorder Org Courses

Field	Type	Description
courseKey	course id	Course Key
newIndex	integer	1 based index - new position

SSO configs

Field	Type	Description
isSSOEnabled	boolean	Is SSO enabled for the organization?
ssoMethod	string	(Optional) SSO Method. Mandatory if isSSOEnabled is set to true
ssoDetails	model	(Optional) SSO details. Mandatory if isSSOEnabled is set to true.

SSO details

Configure SSO details.

SAML config

Field	Type	Description
samlIdpEntityId	string	Entity ID at the IDP for this SAML integration
samlIdpUrl	string	URL for the IDP
samlAssertionIsSigned	boolean	Does the IDP sign assertions?
samlRequestIsSigned	boolean	Does the IDP sign requests?
samlNameIDFormat	string	Format of the user ID we receive from the IDP. Acceptable values: "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress", "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
samlJITProvisioningEnabled	boolean	If true, when we receive a valid SSO request a user will be created automatically if one does not already exist. Mutually exclusive with samlScimEnabled
samlUserDataDictionary	Map(string, string)	Maps properties of our User model to properties received from the IDP. Valid keys: "GIVEN_NAME", "FAMILY_NAME", "FULL_NAME". Required if samlJITProvisioningEnabled is true.
samlScimEnabled	boolean	If false, SCIM endpoints will be unavailable for org. Defaults to false. Mutually exclusive with samlJITProvisioningEnabled

Certificate

Field	Type	Description
id	boolean	Certificate ID.
certificateType	string	Certificate Type. Only PEM for now.
expirationDate	model	Certificate expiration date.

Create topic

Field	Type	Description
name	string	(Mandatory) name - maximum 80 characters.
description	Topic	(Optional) topic description.
settings	object	Any valid JSON object.

Org topic

Field	Type	Description
id	org ID	ID of the org. Present in responses. Ignored in requests.
name	string	(Mandatory) Topic name - maximum 40 characters.
description	string	(Mandatory) Free description string.
coursesCount	integer	(Optional) number of courses associated with topic.
settings	object	Any valid JSON object.

Org topic tree

Field	Type	Description
id	org ID	ID of the org. Present in responses. Ignored in requests.
name	string	(Mandatory) Topic name - maximum 40 characters.
description	string	(Mandatory) Free description string.
topics	List(topics)(#org-topic-tree)	The recursive list of subtopics.

Patch topic

Field	Type	Description
name	string	(Optional) Topic name - maximum 80 characters.
description	string	(Optional) Free description string.
settings	object	Any valid JSON object.

Org portal

Field	Type	Description
orgId	org ID	ID of the org.
name	string	(Mandatory) Portal name - maximum 80 characters.
description	string	(Mandatory) Free description string.
isPublic	boolean	(Mandatory) Indicator whether portal is public.
selfProvisioningEnabled	boolean	(Mandatory) Indicator whether self provisioning is enabled for public portal.
anonymousAccessEnabled	boolean	(Mandatory) Indicator whether anonymous (i.e. unknown signed in user) can access.
allCoursesViewEnabled	boolean	(Mandatory) Indicator whether portal is turn on or off
enabled	boolean	(Mandatory)
brandImage	Asset	(Updated separately)
settings	object	Any valid JSON object.

Create org portal

Field	Type	Description
name	string	(Mandatory) name - maximum 80 characters.
description	string	(Optional) Free description string.
isPublic	boolean	(Mandatory) Indicator whether portal is public.
selfProvisioningEnabled	boolean	(Optional) Indicator whether self provisioning is enabled for public portal. Defaults to false.
anonymousAccessEnabled	boolean	(Mandatory) Indicator whether anonymous (i.e. unknown signed in user) can access.
allCoursesViewEnabled	boolean	(Optional) Indicator whether for enabling/disabling all topics page in portals UI. Defaults to false.
enabled	boolean	(Optional) Indicator whether portal is turn on or off. Defaults to true.
settings	object	Any valid JSON object.

Patch org portal

Field	Type	Description
name	string	(Optional) Portal name - maximum 80 characters.
description	string	(Optional) Free description string.
isPublic	boolean	(Optional) Indicator whether portal is public (default is false).
selfProvisioningEnabled	boolean	(Optional) Indicator whether self provisioning is enabled for public portal. Defaults to false.
anonymousAccessEnabled	boolean	(Mandatory) Indicator whether anonymous (i.e. unknown signed in user) can access.
allCoursesViewEnabled	boolean	(Optional) Indicator whether for enabling/disabling all topics page in portals UI. Defaults to false.
enabled	boolean	(Optional) Indicator whether portal is turn on or off. Defaults to true.
settings	object	Any valid JSON object.

Portal course author

Field	Type	Description
id	user ID	Unique API-generated identifier.
name	string	(Optional) user name.
email	string	(Optional) email address.
bio	string	(Optional) user bio.
image	assets	(Optional) user image.

Portal course view model

Field	Type	Description
courseId	Course Key	Unique API-generated identifier.
authors	array of users	course authors
image	array of assets	(Optional)
title	string	course title
isAuthor	boolean	Has value true if the requesting user is author of the course; false otherwise.
updated	integer	last edit timestamp
created	integer	creation time timestamp
longDesc	string	(Optional) Course long description
shortDesc	string	(Optional) Course short description
tags	array of string	Course tags
isBookmarked	boolean	Has value true if the requesting user bookmarked thiscourse; false otherwise.

Org tree

Response org extended with the following fields` |

Field	Type	Description
permissions	array of string	A non-empty array, currently supported VFO permissions include AdministerOrg and TeachCourses.
orgs	array of org tree	(Optional) The org's child orgs if they exist.

Request VFO session

Field	Type	Description
userId	user ID	(Optional) The user for whom a session is requested.
email	email	The email address of the user for whom a session is requested.
expiresIn	number	(Optional) The initial duration of the session, in milliseconds. Must be a non-negative integer.

Response VFO session

Field	Type	Description
sessionId	session ID	Unique, API-generated identifier.
userId	user ID	The user to whom the session belongs.
expiresIn	number	The initial duration of the session, in milliseconds.

VFO Org permissions

Field	Type	Description
permissions	array of string	A non-empty array, currently supported VFO permissions include AdministerOrg TeachCourses, and LearnCourses.

Response VFO user permissions

Field	Type	Description
user	VFO short user
memberships	array of VFO user membership	A non-empty array listing all explicit memberships of a user in suborgs.

VFO short user

Field	Type	Description
id	user ID	Unique API-generated identifier.
username	slug	A unique, human-readable user identifier. It is used in the type strings of gadgets created by the user in place of their user ID, if defined.
email	email	Unique email address.
fullname	string	Alternate full name.
displayname	string	Formatted display name chosen from user's non-null name fields. Display name is chosen in the following order: fullName, fn, firstName + " " + lastName, firstName, lastName, "Unknown"

VFO user membership

Field	Type	Description
orgId	org ID	ID of the org.
permissions	array of string	A non-empty array, currently supported VFO permissions include AdministerOrg and TeachCourses.

VFO move course data

Field	Type	Description
id	course ID	Course id for the course being moved.

VFO move course request

Field	Type	Description
courses	array of VFO move course data	A possibly empty array of course data for courses that need to be moved.

VFO single sign-on (SSO) authorization request input model

Field	Type	Description
method	string	Single sign-on method. Accepted values: "SAML"
resource	string	URL for the protected page or resource the end user is trying to access

VFO single sign-on (SSO) authorization request response model

Field	Type	Description
SAMLRequest	string	Base64-encoded XML document
destination	string	URL for the Identity Provider's SSO request endpoint

VFO single sign-on (SSO) session request input model

method | string | Single sign-on method. Accepted values: "SAML" data | object | Varies according to SSO method. Accepted shapes: {"SAMLResponse":string}

VFO single sign-on (SSO) session request response model

Field	Type	Description
resource	string	URL for the protected page or resource the end user is trying to access
session	VFO Session	The created VFO session

User group

Field	Type	Description
name	string	User group name - maximum 40 characters.

Response user group

Field	Type	Description
id	user group ID	Unique API-generated identifier.
name	string	User group name - maximum 40 characters.

Permissions

Get Course Permissions Legacy View Model

Field	Type	description
permissions	array of string	The course permissions for specified session for the specified course

Get Course Permissions New View Model

Field	Type	description
coursePermissions	Map from string to Set of string	Map of course key to set of course permissions for specified session for that course

Get Org Permissions View Model

Field	Type	description
orgPermissions	Map from string to Set of string	Map of stringified org ids to set of VFO org permissions for specified session for that org

Report Gen

Learners Report

The body for the learners report generation request

Field	Type	description
courses	List(courses)(#course-key)	List of course keys containing one and only one course key

Course completion report

The body for the course completion report generation request

Field	Type	description
startDate	date	A start date for a report
endDate	date	An end date for a report

Learner Class Decoration

Learner class (also in course details response)

Field	Type	Description
courseId	course ID	Course ID
userId	user ID	User ID
linkMode	string	"course" OR "overview"
class	class	class properties
parent	parent	parent properties
provider	provider	provider properties

learnerClass class

Field	Type	Description
id	string	class id
title	string	class title
description	string	class description
startDate	date-time	class start date

learnerClass parent

Field	Type	Description
url	string	parent url
`title'	string	parent title

learnerClass provider

Field	Type	Description
id	string	provider id
name	string	provider name

Locks

Gadget lock subject

Field	Type	Description
courseId	course ID	Course ID
gadgetId	gadget ID	Gadget ID

Lock request

Field	Type	Description
type	string	Resource type. For now, only gadget is acceptable.
subject	lock subject	Resource lock subject. For now, only gadgets can be locked.

Resource lock

Field	Type	Description
type	string	Resource type. For now, it's always gadget.
subject	lock subject	Resource lock subject. For now, only gadgets can be locked.
ownerId	user ID	Lock owner. Only the owner can perform updates on the locked resource.
expiresIn	integer	Number of milliseconds after which the lock will be released.

Themes

Theme

Field	Type	Description
ownerType	string	Mandatory when creating new theme. Ignored when updating. Owner type. Currently only VFO_ORG is supported.
ownerId	org_ID	Mandatory when creating new theme. Ignored when updating. Currently always the Org ID.
theme	theme object	Mandatory. Theme object.

Theme object

An arbitrary JSON object that stores any theme attributes. There is no spec for this object.

SCIM

SCIM token response

Field	Type	Description
token	string	token value
expiryDate	date-time	token expiry date

SCIM get users response

SCIM get users response is defined by RFC-7644 and RFC-643.

Field	Type	Description
schemas	string	["urn:ietf:params:scim:api:messages:2.0:ListResponse"]
totalResults	integer
startIndex	integer	The 1-based index of the first result in the current set of list results. REQUIRED when partial results are returned due to pagination.
itemsPerPage	integer	The number of resources returned in a list response page. REQUIRED when partial results are returned due to pagination.
Resources	Array of users

SCIM user

Field	Type	Desctiption
id	integer
externalId	string	Optional user id from external system
userName	email	user email
displayName	string	full name
name	SCIM user name	user name

SCIM user name

Field	Type	Desctiption
formatted	string	The full name
givenName	string
familyName	string

Create SCIM user request

Create SCIM user response is defined by RFC-7644 and RFC-7643.

Field	Type	Description
schemas	string	["urn:ietf:params:scim:schames:core:2.0:User"]
userName	email	user email
externalId	string	Optional user id from external system
name	SCIM user name	user name

Create SCIM user response

Create SCIM user response is defined by RFC-7644 and RFC-7643. The URI of the created user is included in the HTTP Location header and in meta.location field

Field	Type	Description
id	integer
schemas	string	["urn:ietf:params:scim:schames:core:2.0:User"]
externalId	string	Optional user id from external system
userName	email	user email
displayName	string	full name
name	SCIM user name	user name
meta	SCIM meta

SCIM meta

Field	Type	Description
location	string	URL to the newly created user

Get SCIM user response

Get SCIM user response is defined by RFC-7644 and RFC-7643.

Field	Type	Description
id	integer
schemas	string	["urn:ietf:params:scim:schames:core:2.0:User"]
externalId	string	Optional user id from external system
userName	email	user email
displayName	string	full name
name	SCIM user name	user name
meta	SCIM meta

Replace SCIM user request

Replace SCIM user response is defined by RFC-7644 and RFC-7643.

Field	Type	Description
schemas	string	["urn:ietf:params:scim:schames:core:2.0:User"]
userName	email	user email
name	SCIM user name	user name

Patch SCIM user request

Patch SCIM user response is defined by RFC-7644.

Field	Type	Description
schemas	string	["urn:ietf:params:scim:schames:core:2.0:PatchOp"]
Operations	SCIM patch operation	Array of operations to be applied

SCIM patch operation

Field	Type	Description
op	string	Type of operation. One of add, remove, replace. Case insensitive.
path	string	Path to the value that is being changed. Currently supported: userName, name.givenName, name.familyName, name.formatted.
value	array	Array of single object with the single property value inside.

Replace SCIM user response

Replace SCIM user response is defined by RFC-7644 and RFC-7643. The URI of the replaced user is included in the HTTP Location header and in meta.location field

Field	Type	Description
id	integer
externalId	string	Optional user id from external system
schemas	string	["urn:ietf:params:scim:schames:core:2.0:User"]
userName	email	user email
displayName	string	full name
name	SCIM user name	user name
meta	SCIM meta

Dashboard user courses

Field	Type	Description
title	string
status	string	Available statuses: started, in-progress, completed
percentageCompleted	integer	progress
startDate	date-time	The start date of the course.
finishDate	date-time	The finish date of the course.
score	number	Cumulative grade, between 0 and 1.

Org Portal Types

Org portal search response

Field	Type	Description
orgId	org ID	ID of the org.
defaultOrgPortal	Org Portal	Object representing the default portal

Org portal domain name update

Field	Type	Description
subdomain	String	(Mandatory) New portal subdomain

Plan features

Plan

Text representing valid JSON.

Plan feature overrides

Field	Type	Description
overrides	string	Text representing valid JSON.