courses.md

Course endpoints

Get course

Retrieves information about a specified course.

Request property	Spec
Action	GET /courses/courseKey
SID header
depth param	Controls the amount of gadget data in the response. Can be one of the following values: lessons - the gadgets within each lesson are omitted from the response sections - only the Versal header/section gadgets are included within each lesson; all others are omitted full - all gadgets are included within each lesson in the response noblocking - all gadgets are included with all lessons regardless of lesson blocking If not specified, defaults to lessons.
deep param	[DEPRECATED] Boolean-valued parameter that was the precursor to depth. If true, equivalent to depth=full; otherwise, or if not specified, equivalent to depth=lessons. If depth is also specified, this is ignored.
Body model	no body
Scala	class GetCourse

The course instance that is sent back in the response depends on who is making the request. If SID is a partner key, or represents an author of the course, then the editable ("sandbox") instance is returned. Otherwise, the published instance is returned, if it exists.

Status	Response body spec
200	Course details
404	{"error": 404, "message": "Course '$courseKey' not found"} If courseKey does not identify a course.
403	{"error": 403, "message": "Insufficient permissions"} If SID does not have either of the EnrollInAPublishedCourse or ViewUnpublishedCourseAsLearner permissions.
403	{"error": 403, "message": "Course is not staged"} If SID is not a partner key or course author, and the course is not published.
401	Invalid credentials

Get lesson

Request property	Spec
Action	GET /courses/courseKey/lessons/lessonId
SID header
Body model	no body
Scala	class GetLesson

The lesson that is sent back in the response depends on who is making the request. If SID is a partner key, or represents an author of the course, then the lesson from the editable ("sandbox") course instance is returned. Otherwise, the lesson from the published instance is returned, if the course is published.

Status	Response body spec
200	Lesson
404	{"error": 404, "message": "Course '$courseKey' not found"} If courseKey does not identify a course.
404	{"error": 404, "message": "Lesson '$lessonId' not found"} If lessonId does not identify a lesson in the course identified by courseKey.
403	{"error": 403, "message": "Insufficient permissions"} If SID does not have either of the EnrollInAPublishedCourse or ViewUnpublishedCourseAsLearner permissions.
403	{"error": 403, "message": "Course is not staged"} If SID is not a partner key or course author, and the course is not published.
401	Invalid credentials

Add gadget to lesson

Inserts a new gadget instance of a specified type into a lesson. The new gadget will have the default config.

Request property	Spec
Action	POST /courses/courseKey/lessons/lessonId/gadgets
SID header	Must be a user SID.
Body model	Gadget instance request
Scala	class AddGadget

Status	Response body spec
201	{"id": "$gadgetInstanceId"}, where gadgetInstanceId is the ID of the new gadget instance.
404	{"error": 404, "message": "Course '$courseKey' not found"} If courseKey does not identify a course.
404	{"error": 404, "message": "Lesson '$lessonId' not found"} If lessonId does not identify a lesson in the course.
403	{"error": 403, "message": "User [$userId] is not a course author"} If the SID user is not an author of the course.
403	{"error": 403, "message": "Insufficient permissions: gadget visibility"} If there is not already a gadget of the same type in the course, and the gadget is owned by an org that is not the same as the course's org.
401	Invalid credentials, if SID is not for a user.
422	{"error": 422, "message": "No value for field $fieldName" } If gadget is a quiz and a required field is missing in quiz config.
422	{"error": 422, "message": "No questions" } If gadget is a quiz and the questions field is missing or is an empty list.
422	{"error": 422, "message": "No answers for a question" } If gadget is a quiz and answers field is missing or is an empty list for at least one of the questions.
422	{"error": 422, "message": "answerKey refers to non-existent answer" } If gadget is a quiz and answerKey refers to a non-existent answer.
422	{"error": 422, "message": "answerKey refers to non-existent question" } If gadget is a quiz and answerKey refers to a non-existent question.
422	{"error": 422, "message": "answerKey does not contain answers to all questions" } If gadget is a quiz and answerKey does not contain answers to all questions.
400	Bad request

Add many gadgets to lesson

Inserts an array of gadget instances into a lesson. Each new gadget will have its default config.

The path many_gadgets is active but deprecated in favor of the more descriptive insert_gadgets.

Request property	Spec
Action	POST /courses/courseKey/lessons/lessonId/many_gadgets
Action	POST /courses/courseKey/lessons/lessonId/insert_gadgets
SID header	Must be a user SID (session must be linked to a user account).
Body model	Many-gadgets request
Scala	class AddManyGadgets

Status	Response body spec
201	["id1", "id2", ...] - array of new gadget instance IDs.
404	{"error": 404, "message": "Course '$courseKey' not found"} If courseKey does not identify a course.
404	{"error": 404, "message": "Lesson '$lessonId' not found"} If lessonId does not identify a lesson in the course.
403	{"error": 403, "message": "User [$userId] is not a course author"} If the SID user is not an author of the course.
403	{"error": 403, "message": "Insufficient permissions: gadget visibility"} If there is not already a gadget of the same type in the course, and the gadget is owned by an org that is not the same as the course's org.
401	Invalid credentials, if SID is not for a user.
422	{"error": 422, "message": "No value for field $fieldName" } If gadget is a quiz and a required field is missing in quiz config.
422	{"error": 422, "message": "No questions" } If gadget is a quiz and the questions field is missing or is an empty list.
422	{"error": 422, "message": "No answers for a question" } If gadget is a quiz and answers field is missing or is an empty list for at least one of the questions.
422	{"error": 422, "message": "answerKey refers to non-existent answer" } If gadget is a quiz and answerKey refers to a non-existent answer.
422	{"error": 422, "message": "answerKey refers to non-existent question" } If gadget is a quiz and answerKey refers to a non-existent question.
422	{"error": 422, "message": "answerKey does not contain answers to all questions" } If gadget is a quiz and answerKey does not contain answers to all questions.
400	Bad request

Replace gadget instance config

Sets the configuration for the specified gadget instance to the value provided in the request body.

Specifying lessons/:lessonId in the request URL is deprecated.

Request property	Spec
Action	PUT /courses/courseId/lessons/lessonId/gadgets/gadgetId/config
Action	PUT /courses/courseId/gadgets/gadgetId/config
SID header	Must be a user SID.
Body model	Gadget config
Scala	class ReplaceGConfig

Note that if the body cannot be parsed as a JSON object, no error response will be generated, but the config will be treated as the empty JSON object ({}) in circumstances where it needs to be parsed by the API. This is for performance reasons, since parsing/validation is an expensive operation.

Status	Response body spec
200	{}
404	{"error": 404, "message": "Course '$courseId' not found"} If courseId does not identify a course.
404	{"error": 404, "message": "GadgetInstance '$gadgetId' not found"} If lessonId and gadgetId do not identify a gadget instance in the editable course instance.
403	{"error": 403, "message": "User [$userId] is not a course author"} If the requesting user does not have authoring permissions on the course.
403	{"error": 403, "message": "Resource locked"} If the gadget is locked by another user.
422	{"error": 422, "message": "No value for field $fieldName" } If gadget is a quiz and a required field is missing in quiz config.
422	{"error": 422, "message": "No questions" } If gadget is a quiz and the questions field is missing or is an empty list.
422	{"error": 422, "message": "No answers for a question" } If gadget is a quiz and answers field is missing or is an empty list for at least one of the questions.
422	{"error": 422, "message": "answerKey refers to non-existent answer" } If gadget is a quiz and answerKey refers to a non-existent answer.
422	{"error": 422, "message": "answerKey refers to non-existent question" } If gadget is a quiz and answerKey refers to a non-existent question.
422	{"error": 422, "message": "answerKey does not contain answers to all questions" } If gadget is a quiz and answerKey does not contain answers to all questions.
401	Invalid credentials, if SID is not for a user.

Replace gadget user state

Sets the user state for the SID user on the specified gadget instance to the value provided in the request body.

Specifying lessons/:lessonId in the request URL is deprecated.

Request property	Spec
Action	PUT /courses/courseKey/lessons/lessonId/gadgets/gadgetId/userstate
Action	PUT /courses/courseKey/gadgets/gadgetId/userstate
SID header	Must be a user SID.
Body model	Gadget user state
Scala	class ReplaceGuState

This endpoint is very permissive, and not in a good way. It doesn't check whether lessonId or gadgetId actually identify items within the course. It does check whether the SID user has learner permissions on the course, or authoring permissions if the course isn't published, but then it ignores those checks due to historical command log "rejections" (see UserState.allowUnstaged()).

To avoid the performance hit of always parsing the user state JSON in the request body, the manifest corresponding to the specified gadget instance is retrieved, and its exec field is checked. If the value is quiz or publicQuiz, then the user state JSON is parsed and quiz grading is performed. Otherwise, the user state is stored exactly as sent, without parsing (even if it's not actually JSON).

The quiz grading process is complex, and modifies the user state provided in the request body before it is persisted. Please refer to UserState.processQuiz() and UserState.processPublicQuiz() in the code for more details.

An informal rule for this endpoint is to be robust to error conditions. There are several places in the code where data lookups can fail; these are all generally handled in the same way, by setting the user state to an empty value. The few errors that can actually occur are documented below.

Status	Response body spec
200	The new value of the gadget user state.
400	{"error": 400, "message": "Course '$courseKey' not found"} If courseKey does not identify a course.
401	Invalid credentials, if SID is not for a user.

Update course progress

Records the lesson that the SID user is currently learning from.

Requires a user session (not partner key or authenticator session).

Request property	Spec
Action	PUT /courses/courseKey/progress
SID header	Must be a user SID.
Body model	Progress update
Scala	class ReplaceProgress

The SID user is also recorded as starting the course if they aren't already a learner; this replaces the functionality of the deprecated start course endpoint. This was done to avoid an extra request, since the frontend updates the progress for the first lesson anyway.

Status	Response body spec
200	Progress update
400	{"error": 400, "message": "Course '$courseKey' not found"} If courseKey does not identify a course.
400	{"error": 400, "message": "Lesson index or lesson ID is required"} If neither lessonIndex nor currentLessonId is given in the request body.
403	{"error": 403, "message": "Insufficient permissions"} If SID does not have either of the EnrollInAPublishedCourse or ViewUnpublishedCourseAsLearner permissions.
403	{"error": 403, "message": "Course is not staged"} If SID is not a partner key or course author, and the course is not published.
404	{"error": 404, "message": "Requested lesson not found"} If currentLessonId in the request body is not a valid lesson ID for a lesson in this course, or if lessonIndex in the request body is not between 1 and the number of lessons, inclusive.
403	{"error": 403, "message": "Can't start at or progress to blocked lesson"} If lessonIndex is greater than the index of the first blocked lesson, and the SID user is not a course author.
401	Invalid credentials, if SID is not for a user.

Using lessonIndex in the request body is deprecated. Use currentLessonId instead.

Update course position

Records the lesson or section that the SID user is currently learning from.

Requires a user session (not partner key or authenticator session).

Request property	Spec
Action	PUT /courses/courseKey/position
SID header	Must be a user SID.
Body model	Position update
Scala	class ReplacePosition

The SID user is also recorded as starting the course if they aren't already a learner.

Status	Response body spec
200	Position update
400	{"error": 400, "message": "Course '$courseKey' not found"} If courseKey does not identify a course.
400	{"error": 400, "message": "currentLessonId is required"} If displaySection is LESSON but currentLessonId is missing in the request body.
400	{"error": 400, "message": "Invalid slug format"} If displaySection contains not alphanumeric char.
400	{"error": 400, "message": "Invalid input: displaySection is ... chars, exceeding limit of 128"} If displaySection is too long.
403	{"error": 403, "message": "Insufficient permissions"} If SID does not have either of the EnrollInAPublishedCourse or ViewUnpublishedCourseAsLearner permissions.
403	{"error": 403, "message": "Course is not staged"} If SID is not a partner key or course author, and the course is not published.
404	{"error": 404, "message": "Requested lesson not found"} If currentLessonId in the request body is not a valid lesson ID for a lesson in this course.
403	{"error": 403, "message": "Can't start at or progress to blocked lesson"} If currentLessonId is after the first blocked lesson, and the SID user is not a course author.
401	Invalid credentials, if SID is not for a user.

Add learner to course

Add a course learner.

Request property	Spec
Action	PUT /courses/courseId/learners/learnerId
SID header	Must be a partner key; other sessions get a 401
Body model	no body
Scala	class AddLearnerToCourse

A timestamp is recorded for the course start time.

Status	Response body spec
200	{}
404	{"error": 404, "message": "Course '$courseId' not found"} The path parameter courseId does not identify a course.
404	{"error": 404, "message":" User '$learnerId' not found"} The path parameter learnerId does not identify a user.
403	{"error": 403, "message": "Course is not staged"} The requesting user is not an author of the course and the course is not published.
401	Invalid credentials; the SID is not a partner key.

Start course

[DEPRECATED] Join a course as a learner.

Request property	Spec
Action	POST /courses/courseId/start
SID header	Must be the SID of a user; partner keys and authenticators will get a 401
Body model	no body
Scala	class StartCourse

A timestamp is recorded for the course start time.

Status	Response body spec
201	{"id": "$courseId"}
404	{"error": 404, "message": "Course '$courseId' not found"} The path parameter courseId does not identify a course.
403	{"error": 403, "message": "Insufficient permissions"} The requesting user does not have learner permissions in the course's program.
403	{"error": 403, "message": "Course is not staged"} The requesting user is not an author of the course and the course is not published.
Invalid credentials; the SID was not for a user.

List courses

Retrieves all courses matching criteria specified in the request.

Request property	Spec
Action	GET /courses
SID header
Pagination params
author param	Restricts results to courses where the given user ID is a course creator (VFO context dependent) or course contributor (VFO context agnostic).
role param	Accepts a comma-separated list of roles. Restricts results to courses where the calling session has the given role with respect to the course. Valid roles are publisher (a.k.a creator, VFO context dependent), author (a.k.a. contributor, VFO context agnostic), instructor (a.k.a educator, VFO context dependent), and learner (VFO context agnostic).
permission param	Accepts a comma-separated list of permissions. Restricts results to courses where the calling session has the given permission with respect to the course.
orgId param	Restricts results to courses belonging to the given legacy org ID or org name.
title param	Restricts results to courses with titles containing the given string value.
catalog param	With value labs, restricts results to published courses. With value sandbox, restricts results to courses the requesting user can edit. All other values are ignored.
orgshares param	Accepts a comma-separated list of VFO Org ID. Restricts results to courses shared with any of the VFO Orgs in the list. Orgs must cohere with the session's VFO container. Caller must be a member (via any VFO permission) of each org in the list.
rootOrgId param	Restricts results to courses attached to the VFO container VFO_Org ID.
viewModel param	Valid values are: full - print full course view model (default), ids - print only course ID property of view model, i.e.,{"id":"CourseID"}
Body model	no body
Scala	object GetCourses

The courses that are listed depend on who is making the request, as follows:

• If SID is a partner key, list only sandbox instances
• If SID is for a user session, each course listed must meet at least one of the following criteria:
  • the course belongs to a free program and the given SID was issued by the Versal authenticator
  • the course belongs to an org program and the given SID is for an admin of that org
  • the given SID and its authenticator both have either EnrollInAPublishedCourse or ViewUnpublishedCourseAsLearner permissions in the course's program

The particular instance listed for each course depends on the following:

• If SID is a partner key, or representing a user that can edit the course, the sandbox instance is listed
• Otherwise, if the course is published, the published instance is listed
• Otherwise, no instances of that course are listed

Status	Response body spec
200	paginated array of base course
401	Invalid credentials
400	Bad request

| [Invalid pagination parameters](responses.md#invalid-pagination-parameters)

Search courses

Retrieves all courses matching specified criteria

Request property	Spec
Action	GET /courses/search
SID header
Pagination params
authorname	Author name: string
authorid	Author: user ID
containerId	Container ID VFO_Org ID
portalId	Portal ID VFO_Org ID
topicId	Topic ID VFO_Org ID
gadget	gadget name string
tag	tag string
text	course content full text search criterion string
viewModel	Valid values are: full - print full course view model (default), ids - print only course ID property of view model, i.e.,{"id":"CourseID"}
portalView	true or false. Optional. Default false.
Body model	no body
Scala	object SearchCourses

Status	Response body spec
200	paginated array of: base course if viewModel is full course ID if viewModel is ids
401	Invalid credentials
400	Bad request
400	Invalid pagination parameters

Create course

Request property	Spec
Action	POST /courses
Scala	object AddCourse

Clone course

Request property	Spec
Action	POST /courses/courseId/clone
Scala	object CloneCourse

Status	Response body spec
201	{} If course is successfully cloned.
401	Invalid credentials
404	{"error": 404, "message": "Course '$courseKey' not found"} If courseKey does not identify a course.

Get course palette

Request property	Spec
Action	GET /courses/courseId/palette
Scala	class GetPalette

Upgrade palette

Request property	Spec
Action	PUT /courses/courseId/palette/devKey/gadgetName/gadgetVersion
Scala	class UpgradePalette

Get gadget instance

Specifying lessons/:lessonId in the request URL is deprecated.

Request property	Spec
Action	GET /courses/courseId/lessons/lessonId/gadgets/gadgetId
Action	GET /courses/courseId/gadgets/gadgetId
Scala	class GetGadget

Replace gadget instance

Request property	Spec
Action	PUT /courses/courseId/lessons/lessonId/gadgets/gadgetId
Scala	class ReplaceGadget

Status	Response body spec
200	{}
403	{"error": 403, "message": "Resource locked"} If some gadgets in the course are locked by another user.
422	{"error": 422, "message": "No value for field $fieldName" } If gadget is a quiz and a required field is missing in quiz config.
422	{"error": 422, "message": "No questions" } If gadget is a quiz and the questions field is missing or is an empty list.
422	{"error": 422, "message": "No answers for a question" } If gadget is a quiz and answers field is missing or is an empty list for at least one of the questions.
422	{"error": 422, "message": "answerKey refers to non-existent answer" } If gadget is a quiz and answerKey refers to a non-existent answer.
422	{"error": 422, "message": "answerKey refers to non-existent question" } If gadget is a quiz and answerKey refers to a non-existent question.
422	{"error": 422, "message": "answerKey does not contain answers to all questions" } If gadget is a quiz and answerKey does not contain answers to all questions.

Delete gadget

Request property	Spec
Action	DELETE /courses/courseId/lessons/lessonId/gadgets/gadgetId
Scala	class DeleteGadget

Status	Response body spec
204
403	{"error": 403, "message": "Resource locked"} If the gadget is locked by another user.

Delete many gadgets from lesson

Delete a list of gadget instances from a lesson. Gadget IDs must be valid for tr

Request property	Spec
Action	POST /courses/courseKey/lessons/lessonId/delete_gadgets
SID header
Body model	{"gadgets": List of gadgetId}
Scala	class DeleteManyGadgets

Status	Response body spec
201	["id1", "id2", ...] - array of new gadget instance IDs.
404	{"error": 404, "message": "Course '$courseKey' not found"} If courseKey does not identify a course.
404	{"error": 404, "message": "Lesson '$lessonId' not found"} If lessonId does not identify a lesson in the course.
403	{"error": 403, "message": "User [$userId] is not a course author"} If the SID user is not an author of the course.
400	{"error": 400, "message": "Empty gadget list"}
404	{"error": 404, "message": "Invalid gadget instance IDs: 1, 2, ..., n"}
403	{"error": 403, "message": "Locked gadget instance IDs: 1, 2, ..., n"} If some of the gadgets are locked by another user.
401	Invalid credentials, if SID is not for a user.
400	Bad request

Get gadget instance config

Specifying lessons/:lessonId in the request URL is deprecated.

Request property	Spec
Action	GET /courses/courseId/lessons/lessonId/gadgets/gadgetId/config
Action	GET /courses/courseId/gadgets/gadgetId/config
Scala	class GetGConfig

Patch course

Makes a course public or private.

Request property	Spec
Action	PATCH /courses/courseId
Body model	{ "public": true or false }
Scala	class PatchCourse

"Partially overwrite" course

The request body contains a full or partial course JSON. In that course JSON, all lesson IDs and gadget instance IDs must be distinct.

Any new metadata will be merged into the existing course metadata. For example: If lessons exist in the request body, all the previous lesson and gadget data will be replaced by the new lesson and gadget data from the request body. If lessons does not exist in the request body, the previous lesson and gadget data will remain unchanged. The same applies to other fields such as tags, etc.

The course will be updated in sandbox but the published revision (if it exists) will remain the same.

Request property	Spec
Action	PUT /courses/courseId
Body model	Course details without palette and catalogs, and with all top-level fields optional.
Scala	class PartiallyOverwriteCourse

Status	Response body spec
200	{}
400	{"error": 400, "message": "Lesson IDs and gadget instance IDs must be unique within course"} If the given course JSON contains any duplicate lesson IDs or gadget instance IDs.
403	{"error": 403, "message": "Locked gadget instance IDs: 1, 2, ..., n"} If some gadgets in the course are locked by another user.

Delete course

Calling session must be a partner key or user. Calling session must have ArchivePermission on the course via direct grant or VFO administrator status.

Request property	Spec
Action	DELETE /courses/courseId
Scala	class DeleteCourse

Status | Response body spec 204 | 403 | {"error": 403, "message": "Locked gadget instance IDs: 1, 2, ..., n"}
If some gadgets in the course are locked by another user.

Undelete Course

Calling session must be a partner key or user. Calling session must have ArchivePermission on the course via direct grant or VFO administrator status.

Request property	Spec
Action	PUT /courses/courseId/restore
Scala	class RestoreCourse

Status | Response body spec 200 | {} 40x | {"error": 40x, "message": "Varies"}

Get course index

DEPRECATED

Request property	Spec
Action	GET /courses/courseId/index
Scala	class GetCourseIndex

Get lessons

Request property	Spec
Action	GET /courses/courseId/lessons
Scala	class GetLessons

Create lesson

Adds a lesson at the end of the course.

Request body contains a lesson JSON.

Request property	Spec
Action	POST /courses/courseId/lessons
Scala	class AddLesson

Update lesson metadata

Request property	Spec
Action	PUT /courses/courseId/lessons/lessonId
Scala	class ChangeLessonMetaData

Delete lesson

Request property	Spec
Action	DELETE /courses/courseId/lessons/lessonId
Scala	class DeleteLesson

Status | Response body spec 204 | 403 | {"error": 403, "message": "Locked gadget instance IDs: 1, 2, ..., n"}
If some gadgets in the course are locked by another user.

Reorder lessons

DEPRECATED

Request property	Spec
Action	PUT /courses/courseId/lessons/order
Body model	A JSON list of lesson IDs as strings.
Scala	class ReorderLessons

Warning: If some existing lesson IDs are missing in the body of this request, these lessons will be deleted from the course.

Status	Response body spec
200	{}
400	"Invalid ordering"

Get gadget instances

Request property	Spec
Action	GET /courses/courseId/lessons/lessonId/gadgets
Scala	class GetGadgets

Reorder gadget instances

DEPRECATED

Request property	Spec
Action	PUT /courses/courseId/lessons/lessonId/gadgets/order
Body model	A JSON list of lesson IDs as strings.
Scala	class ReorderGadgets

Status	Response body spec
200	{}
400	"Invalid ordering"
403	{"error": 403, "message": "Locked gadget instance IDs: 1, 2, ..., n"} If some gadgets in the course are locked by another user.

Get course completion

Request property	Spec
Action	GET /courses/courseId/completion
Scala	class GetCompletion

Update course completion

Request property	Spec
Action	PUT /courses/courseId/completion
Scala	class CourseCompletion

Get course progress

Permissions: Any authenticated user or partner key.

Request property	Spec
Action	GET /courses/courseId/progress
Scala	class GetProgress

Get course overview

Request property	Spec
Action	GET /courses/courseId/overview
Scala	class GetOverview

Get all gadget user states

Permissions: must be the same user, a course creator (publisher), or partner.

Request property	Spec
Action	GET /courses/courseId/users/userId/userstates
Scala	class GetCourseUserStates

Status	Response body spec
200	course userstate response
401	Invalid credentials

Get gadget grades

For a quiz-like gadget, returns the grades for all users that have a userstate for this gadget.

Endpoint can be used by partner key or by course creator (publisher) or by a course author (contributor).

Specifying lessons/:lessonId in the request URL is deprecated.

Request property	Spec
Action	GET /courses/courseId/lessons/lessonId/gadgets/gadgetId/grades
Action	GET /courses/courseId/gadgets/gadgetId/grades
Scala	class GetGadgetGrades

Status	Response body spec
200	paginated array of gadget grade response
403	Course is not staged
401	Invalid credentials

Drop course

Delete the course learner data about the SID user (make it as if the user has not started the course).

Requires a user SID (not partner key).

Request property	Spec
Action	DELETE /courses/courseId/start
Scala	class DropCourse

Drop course

Delete the course learner data about the specified user userId (make it as if the user has not started the course).

Requires the session user to have permission PublishCourses on the course.

Request property	Spec
Action	DELETE /courses/courseId/users/userId/start
Scala	class DropCourseForUser

Get gadget user state

Specifying lessons/:lessonId in the request URL is deprecated.

Request property	Spec
Action	GET /courses/courseId/lessons/lessonId/gadgets/gadgetId/userstate
Action	GET /courses/courseId/gadgets/gadgetId/userstate
Scala	class GetGuState

Get gadget user states

Specifying lessons/:lessonId in the request URL is deprecated.

Request property	Spec
Action	GET /courses/courseId/lessons/lessonId/gadgets/gadgetId/userstates
Action	GET /courses/courseId/gadgets/gadgetId/userstates
Scala	class GetGuStates

Delist from labs

DEPRECATED

Request property	Spec
Action	POST /courses/courseId/delist/labs
Scala	class DelistFromLabs

Unpublish course

DEPRECATED

Request property	Spec
Action	POST /courses/courseId/unpublish/labs
Scala	class DelistFromLabs

Stage course

DELETED

An old endpoint for publishing a course. Superceded by POST /catalogs/staged/courses

Request property	Spec
Action	POST /courses/courseId/stage
Scala	class StageCourse

Replace course brand image

The session user should have PublishCourses permission on the course, or be an org admin.

Request property	Spec
Action	POST /courses/courseId/coursebrandimage
Scala	class ReplaceCourseBrandImage

Delete course brand image

The session user should have PublishCourses permission on the course, or be an org admin.

Request property	Spec
Action	DELETE /courses/courseId/coursebrandimage
Scala	class DeleteCourseBrandImage

Replace course cover image

The session user should have PublishCourses permission on the course, or be an org admin.

Request property	Spec
Action	POST /courses/courseId/coverimage
Scala	class ReplaceCoverImage

Delete course cover image

The session user should have PublishCourses permission on the course, or be an org admin.

Request property	Spec
Action	DELETE /courses/courseId/coverimage
Scala	class DeleteCoverImage

Delete course cover color

The session user should have PublishCourses permission on the course, or be an org admin.

Request property	Spec
Action	DELETE /courses/courseId/covercolor
Scala	class DeleteCoverColor

Set course settings

In order to update course settings, the caller must be a user session and at least one of the following conditions must hold:

• the caller has the permission PublishCourses for the course
• the course is shared on a VFO org, and the caller has AdministerOrg permission in that org

Request property	Spec
Action	PUT /courses/courseId/settings
Body model	Any valid JSON object (models.md#object)
Scala	class SetCourseSettings

Status	Response body spec
200	{}
401	Invalid credentials
403	{"error": 403, "message": "Insufficient permissions"} If SID does not have PublishCourses permission for the course, nor AdministerOrg permission in the org.
404	{"error": 404, "message": "Course '$courseKey' not found"} If courseKey does not identify a course.

Create course revision

In order to be able to publish a course, at least one of the following conditions must hold:

• the caller has the permission PublishCourses for the course
• the course belongs to a legacy org, and the caller has either Admin or Author role in that org
• the course is shared on a VFO org, and the caller has AdministerOrg permission in that org

Request property	Spec
Action	POST /courses/courseId/revisions
Body model	empty
Scala	class AddCourseRevision

Status	Response body spec
201	Course revision data

Revert course edits

Request property	Spec
Action	PUT /courses/courseId/head
Scala	class ReplaceCourseHead

Get all tracked users in the course

Endpoint can be used by partner key or by course creator (publisher) or by a course author (contributor).

Results are produced for the latest published version of the course. If no published revision exists, an error is returned.

Request property	Spec
Action	GET /courses/courseId/users?tracked=true
name param	text field to search in the display name
Scala	class GetCourseUsers

Note: the parameter tracked=true is mandatory. (See class GetCourseUsers in CourseEndpoints.scala.)

Status	Response body spec
200	paginated array of course user response
401	Invalid credentials
400	Bad request also when tracked=true is omitted
403	Course is not staged

Each gadget object now has a userState with a pass value. This value is computed and normally not originally present in the gadget's user state.

Get gadget user data

DEPRECATED

Request property	Spec
Action	GET /courses/courseId/lessons/lessonId/gadgets/gadgetId/userdata
Action	GET /courses/courseId/gadgets/gadgetId/userdata
Scala	class GetGadgetUserdata

Get course user data

Endpoint can be used by partner key or by course creator (publisher) or by a course author (contributor).

Results are produced for the latest published version of the course. If no published revision exists, an error is returned.

Request property	Spec
Action	GET /courses/courseId/userdata
userIds param	Restricts the results to users given by a comma-separated list of userId
Scala	class GetCourseUserdata

Status	Response body spec
200	paginated array of course user data response
403	Course is not staged

Get course user

Endpoint can be used by partner key or by course creator (publisher) or by a course author (contributor).

Results are produced for the latest published version of the course. If no published revision exists, an error is returned.

Request property	Spec
Action	GET /courses/courseId/users/userId
Scala	class GetCourseUser

Status	Response body spec
200	course user response
403	Course is not staged

Patch course user

This endpoint has exactly the same implemented behavior as PUT with the same URL (see below).

Request property	Spec
Action	PATCH /courses/courseId/users/userId
Scala	class UpdateCourseUser

Update properties of course user

For a given course, set tracked state of given user, and set user's role for the course. Supported roles are author, contributor, publisher. Currently author and contributor are the same role.

To be able to set tracked state, the requesting user must have a TrackLearners permission for the course, or (if the course belongs to a VFO org) have the VFO TeachCourses permission in that org.

The requesting user is allowed to update course roles only if condition (1) or (2) holds:

1. The user has ManageAllAuthoringInvitationsAndPermissions permission on the course.
2. The user has InsertConfigureDeleteYourOwnGadgetInstances, is asking to change their own permissions (not another user's), and is not asking to set ManageAllAuthoringInvitationsAndPermissions (the "publisher" role).

Also, it is not permitted to remove the sole author of the course from the author role.

Request property	Spec
Action	PUT /courses/courseId/users/userId
Body model	Course user update request
Scala	class UpdateCourseUser

Status	Response body spec
200	course user update response
403	{"error": 403, "message": "Insufficient permissions"} If none of the above conditions are met.
403	{"error": 403, "message": "Cannot remove the only course author"} If requesting to remove the author role from the only remaining author.
404	"Role[s] not valid" if some role names are not one of "author", "contributor", "publisher"

Get full course data and user progress

Request property	Spec
Action	GET /courses/courseId/users/userId/state
Scala	class GetFullCourseUserProgressData

Delete course state

Request property	Spec
Action	DELETE /courses/courseId/users/userId/state
Scala	class DeleteCourseState

Get cumulative user grade for course

Endpoint can be used by partner key or by course creator (publisher).

Results are produced for the latest published version of the course. If no published revision exists, an error is returned.

Request property	Spec
Action	GET /courses/courseId/users/userId/grade
Scala	class GetCourseUserGrade

Status	Response body spec
200	{ cumulativeGrade: 0.0 }
403	Course is not staged
401	Invalid credentials

For the definition of "cumulative grade", see [models.md#cumulative-grade].

Get user's quiz grades for course

Endpoint can be used by partner key or by course creator (publisher).

Results are produced for the latest published version of the course. If no published revision exists, an error is returned.

Request property	Spec
Action	GET /courses/courseId/users/userId/grades
Scala	class GetCourseUserGrade

Status	Response body spec
200	{ cumulativeGrade: 0.0, gadgets: array of [course user quiz grade response](models.md#course-user-quiz-grade-response)}
403	Course is not staged
401	Invalid credentials

For the definition of "cumulative grade", see [models.md#cumulative-grade].

Get cumulative grade statistics for course

Endpoint can be used only by course creator (publisher).

Results are produced for the latest published version of the course. If no published revision exists, an error is returned.

Request property	Spec
Action	GET /courses/courseId/grade_statistics
Scala	class GetCourseStatistics

Status	Response body spec
200	grade statistics response
403	Course is not staged
401	Invalid credentials

Learner Class Decoration

Create learner class

Request property	Spec
Action	POST /courses/courseId/users/userId/class
Body model	learnerClass
Scala	object AddCohort

Get learner class

Request property	Spec
Action	GET /courses/courseId/users/userId/class
Scala	class GetCohort

Update learner class

Request property	Spec
Action	PUT /courses/courseId/users/userId/class
Body model	learnerClass
Scala	class UpdateCohort

Patch learner class

This endpoint has exactly the same implemented behavior as PUT with the same URL (see above).

Request property	Spec
Action	PATCH /courses/courseId/users/userId/class
Body model	learnerClass
Scala	class UpdateCohort

Delete LearnerClass

Request property	Spec
Action	DELETE /courses/courseId/users/userId/class
Scala	class DeleteCohort

Learners Report

In order to facilitate the front end, a GET method is needed to download reports. An download token that will expire in a configured time (60 seconds recommended) is sent back. To get the report, before the token expires the caller has to call GET http(s)://URL_BASE/api2/reports/downloads?token=token-value with no SID. The caller can check if report is ready to download by calling GET http(s)://URL_BASE/api2/reports/downloadstatus?token=token-value

Start generating report

Request property	Spec
Action	POST /reports/learnersdownload
Body model	learnersReport
Scala	class GenerateLearnerReport

Status	Response body spec
200	A download token value in the form {"downloadToken":"token-value"}
400	{"error": 400, "message":"One and only one course must be specified"} if zero or more than one course specified
403	{"error": 403, "message": "Insufficient permissions"} If SID does not have the ViewCourseAnalytics permission
404	{"error": 404, "message": "Course '$courseKey' not found"} If courseKey does not identify a course.
413	Data set too large if requested report will be too large (it is configured by reporting.max-records-per-report parameter)

Check report status

Request property	Spec
Action	GET /reports/downloadstatus?token=token-value
Scala	class GetReportStatus

Request property	Spec
200	Report status {"status":"status_value"} possible status_value are: incomplete, failure, ready
404	Token 'token-value' not found

Download report

Request property	Spec
Action	GET /reports/downloads?token=token-value
Scala	class GetLearnerReport

Request property	Spec
200	Report content
404	Token 'token-value' not found

Update user group access

Request property	Spec
Action	PUT /courses/courseId/usergroups/groupId
Permissions	Session must have the ManageAllAuthoringInvitationsAndPermissions permission in the program.
Body model	{"role":"role_name"}
Scala	class ReplaceUserGroupCourseAccess

Status	Response body spec
200
400	{"error": 400, "message": "User groups are not enabled"} if feature flag enableUserGroups not enabled
400	{"error": 400, "message": "Invalid role '...'"} if invalid role provided
400	{"error": 400, "message": "Invalid user group ID specified : '...'"} if provided user group id is not numeric
403	{"error": 403, "message": "Insufficient permissions"}
404	{"error": 404, "message": "Course '...' not found"} If courseId not found
404	{"error": 404, "message": "User group '...' not found"} If groupId not found

Revoke user group access

Request property	Spec
Action	DELETE /courses/courseId/usergroups/groupId
Permissions	Session must be associated with a user ID. The user must have

        | the `ManageAllAuthoringInvitationsAndPermissions` permission in the program.

Scala | class RevokeUserGroupCourseAccess

Status	Response body spec
200
400	{"error": 400, "message": "User groups are not enabled"} if feature flag enableUserGroups not enabled
400	{"error": 400, "message": "Invalid role '...'"} if invalid role provided
400	{"error": 400, "message": "Invalid user group ID specified : '...'"} if provided user group id is not numeric
403	{"error": 403, "message": "Insufficient permissions"}
404	{"error": 404, "message": "Course '...' not found"} If courseId not found
404	{"error": 404, "message": "User group '...' not found"} If groupId not found

Create SCORM key

Request property	Spec
Action	POST /courses/courseId/scorm_keys
Permissions	Caller must be a Partner Key or an author
Scala	class AddScormKey

Status	Response body spec
201	{key: UUID, containerId: VFOOrgId, courseKey: CourseKey, maxUsers: Int}
400	{"error": 400, "message": "Not a VFO course"} if course is not part of a VFO container
401	{"error": 401, "message": "Invalid credentials"}
403	{"error": 403, "message": "Insufficient permissions"}
404	{"error": 404, "message": "Course '...' not found"} If courseId not found

Create SCORM session

Request property	Spec
Action	POST /courses/courseId/scorm_sessions
Permissions	Caller must be a SCORM key
Body model	{"learnerId": String (optional), "learnerName": String (optional)}
Scala	class AddScormSession

Status	Response body spec
201	{key: UUID, containerId: VFOOrgId, courseKey: CourseKey, userId: UserId}
401	{"error": 401, "message": "Invalid credentials"}
403	{"error": 401, "message": "Invalid VFO credentials"}
403	{"error": 403, "message": "Anonymous users are not allowed for private courses"} If course is private and no learner identifiers are given
404	{"error": 404, "message": "Course '...' not found"} If courseId not found

Delete SCORM key

Request property	Spec
Action	DELETE /courses/courseId/scorm_keys/key
Permissions	Caller must be a Partner Key or an author
Body model
Scala	class DeleteScormKey

Status	Response body spec
200
401	{"error": 401, "message": "Invalid credentials"}
403	{"error": 401, "message": "Invalid VFO credentials"}
403	{"error": 403, "message": "Insufficient permissions"}
404	{"error": 404, "message": "Course '...' not found"} If courseId not found