knAtom See Building Goals in our implementation guide for more information about designing goals.

In this section:

Managing Goals

Create a New Goal

POST /learning-instances/{li_id}/scoped-goals

Authorization

This endpoint must be called by the partner admin user or a user registered as an instructor for the specified learning instance.

Path Parameters

Parameter	Type	Optional	Description
li_id	uuid	No	The ID of a learning instance that will own the goal

Request/Response Body

Parameter	Type	Optional	In/Out	Description
name	string	No	In/Out	Name of the goal Warning: Goal names must not contain any personally identifiable information (PII). Goal names containing email addresses in the name will be rejected.
targets	object	Yes	In/Out	Specifies the content to be learned for this assignment.
targets.include	string[]	Yes	In/Out	List of module IDs (mref’s) or learning objective IDs (lref’s) that identify the content to be learned for this assignment. Prefer using learning objectives. Exactly one of `targets` or `topics` must be specified.
targets.score	float	Yes	In/Out	Deprecated: prefer `completion_criteria` with learning objective targets. The minimum score the student must achieve to be eligible for target completion, using the Expected Score analytic. Exactly one of `targets.score` or `completion_criteria` must be specified.
targets.completion_behavior	string	Yes	In/Out	Deprecated. Valid values are `all` and `average`. A goal using `all` completes when students reach the target score on all targets. A goal using `average` completes when the average score on targets is above the target score. Defaults to `all`. ⚠ This field’s value cannot be changed when updating a goal.
topics	object[]	Yes	In/Out	List of groups of related targets, which can be specified instead of the flat `targets` list to better organize the student experience for larger goals that cover multiple topics. Exactly one of `targets` or `topics` must be specified.
topics[].id	string	No	In/Out	Name of the topic. May be any string that is unique among the topics for this goal. Should be less than 64 characters.
topics[].include	string[]	No	In/Out	List of learning objective IDs (lref’s) that describe the content to be learned for this topic.
topics[].exclude	string[]	Yes	In/Out	List of concept IDs (cref’s) that identify concepts to be avoided by the recommender when recommendations are requested for the goal. Only relevant for goals on graphs that contain concept information.
timing	object	No	In/Out	Specifies the deadline for learners to complete the goal, which must be within 2 years of the time of this request.
timing.end	datetime	Yes	In/Out	ISO 8601 datetime string specifying the absolute date and time by which learners are expected to complete the goal. Exactly one of `end` or `relative_deadline` must be specified.
timing.relative_deadline	duration	Yes	In/Out	ISO 8601 duration string specifying the date and time by which learners are expected to complete the goal, relative to the time of this request. Exactly one of `end` or `relative_deadline` must be specified.
scope	object	Yes	In/Out	Defines the “recommendable pool” - the set of content that the recommender can choose from when a recommendation is requested.
scope.remediation_depth	string	Yes	In/Out	Limit on how far back in the content domain a student can be remediated, specified as a max number of prerequisite hops away from the goal’s targets. One of “none”, “one”, “two”, “three”, or “maximum”. Exactly one of `include` or `remediation_depth` must be specified.
scope.include	string[]	Yes	In/Out	List of taxon IDs (tref’s) or module IDs (mref’s) to be included in the recommendable pool. Exactly one of `include` or `remediation_depth` must be specified.
scope.exclude	string[]	Yes	In/Out	List of taxon IDs (tref’s) or module IDs (mref’s) to be excluded from the recommendable pool. Defaults to [].
config.analytics_enabled	boolean	Yes	In/Out	Flag to indicate whether to compute Readiness Forecast, Active Time, and Expected Score for this goal. Defaults to false. If false, analytics requests for this goal will return empty payloads. ⚠ This field’s value cannot be changed when updating a goal.
config.assign_to	string	Yes	In/Out	Specifies the types of registrations to assign the goal to when it’s created. One of “learners”, “instructors” or “all”. Defaults to not assigning the goal to any registrations. ⚠ This field’s value cannot be changed when updating a goal.
completion_criteria	object	Yes	In/Out	Specifies the criteria for the goal to be considered completed for a learner, defining the parameters for the Status & Progress analtyic. Requires the goal to be defined with learning objective targets. Exactly one of `targets.score` or `completion_criteria` must be specified.
completion_criteria. min_predicted_mastery	float	Yes	In/Out	Minimum score the student must achieve to be eligible for target completion, using the Predicted Mastery analytic.
completion_criteria. min_work_per_target	integer	Yes	In/Out	Minimum number of assessing interactions the student must have on a target’s concepts to be eligible for target completion.
completion_criteria. max_work_on_goal	integer	Yes	In/Out	Maximum number of assessing and instructing interactions the student can have on a goal, including on-target and off-target work, before it is considered completed regardless of progress towards `min_predicted_mastery`.
adaptive_behavior	string	Yes	In/Out	Tells the recommendations engine how to structure the pedagogy concerning this goal. Valid values are `practice`,`introduce`, and `review`. The default value is `practice`. See Specifying Adaptive Behavior for Scoped Goals ⚠ This field’s value cannot be changed when updating a goal.
id	uuid	No	Out	Goal ID
last_modified	datetime	No	Out	Time the goal was last created or modified

Sample Request Body: with completion criteria

{
  "name": "Addition of single digit numbers",
  "targets": {
    "include": [
      "lref-lo56204",
      "lref-lo99879"
    ]
  },
  "scope": {
    "remediation_depth": "two",
    "exclude": [
      "tref-TOC:Unit5"
    ]
  },
  "completion_criteria": {
    "min_predicted_mastery": 0.7,
    "min_work_per_target": 3
  },
  "config": {
    "analytics_enabled": true,
    "assign_to": "all"
  },
  "adaptive_behavior": "introduce"
}

Sample Response Body: with completion criteria

{
  "id": "57466e95-6019-498d-9c42-9180aa663309",
  "last_updated": "2020-12-27T08:32:27.808Z",
  "name": "Addition of single digit numbers",
  "targets": {
    "include": [
      "lref-lo56204",
      "lref-lo99879"
    ]
  },
  "scope": {
    "remediation_depth": "two",
    "exclude": ["tref-TOC:Unit5"]
  },
  "completion_criteria": {
    "min_predicted_mastery": 0.7,
    "min_work_per_target": 3
  },
  "config": {
    "analytics_enabled": true,
    "assign_to": "all"
  },
  "adaptive_behavior": "introduce"
}

Sample Request Body: with topics

{
  "name":"Addition of single digit numbers",
  "topics":[
    {
      "id":"Whole Numbers",
      "include":[
        "lref-lo22911",
        "lref-lo39955"
      ]
    },
    {
      "id":"Fractions",
      "include":[
        "lref-lo49459",
        "lref-lo49460"
      ]
    }
  ],
  "scope":{
    "remediation_depth":"two",
    "exclude":[
      "tref-TOC:Unit5"
    ]
  },
  "completion_criteria":{
    "min_predicted_mastery":0.7,
    "min_work_per_target":3
  },
  "config":{
    "analytics_enabled":true,
    "assign_to":"all"
  },
  "adaptive_behavior": "introduce"
}

Sample Response Body: with topics

{
  "id": "57466e95-6019-498d-9c42-9180aa663309",
  "last_updated": "2020-12-27T08:32:27.808Z",
  "name": "Addition of single digit numbers",
  "topics":[
    {
      "id":"Whole Numbers",
      "include":[
        "lref-lo22911",
        "lref-lo39955"
      ]
    },
    {
      "id":"Fractions",
      "include":[
        "lref-lo49459",
        "lref-lo49460"
      ]
    }
  ],
  "scope": {
    "remediation_depth": "two",
    "exclude": ["tref-TOC:Unit5"]
  },
  "completion_criteria": {
    "min_predicted_mastery": 0.7,
    "min_work_per_target": 3
  },
  "config": {
    "analytics_enabled": true,
    "assign_to": "all"
  },
  "adaptive_behavior": "introduce"
}

Sample Request Body: with target score

{
  "name": "Addition of single digit numbers",
  "targets": {
    "include": [
      "lref-lo56204",
      "lref-lo99879"
    ],
    "score": 0.75
  },
  "timing": {
    "relative_deadline": "P2W1D8H"
  },
  "scope": {
    "remediation_depth": "none",
    "exclude": [
      "tref-TOC:Unit5"
    ]
  },
  "config": {
    "analytics_enabled": false,
    "assign_to": "all"
  },
  "adaptive_behavior": "introduce"
}

Sample Response Body: with target score

{
  "id": "57466e95-6019-498d-9c42-9180aa663304",
  "last_updated": "2013-04-12T17:00:00.000Z",
  "name": "Addition of single digit numbers",
  "targets": {
    "include": [
      "lref-lo56204",
      "lref-lo99879"
    ],
    "score": 0.75
  },
  "timing": {
    "end": "2013-04-28T01:00:00.000Z",
    "relative_deadline": "P2W1D8H"
  },
  "scope": {
    "remediation_depth": "none",
    "exclude": ["tref-TOC:Unit5"]
  },
  "config": {
    "analytics_enabled": false,
    "assign_to": "all"
  },
  "adaptive_behavior": "introduce"
}

Update an Existing Goal

PUT /learning-instances/{li_id}/scoped-goals/{goal_id}

Update an existing goal. This change will apply to all registrations which currently have the goal assigned as the time of the update.

The following fields cannot be updated:

id
config.analytics_enabled
config.assign_to
targets.completion_behavior
adaptive_behavior

Authorization

This endpoint must be called by the partner admin user or a user registered as an instructor for the specified learning instance.

Note: No partial updates, you must post the entire goal body

Path Parameters

Parameter	Type	Optional	Description
li_id	uuid	No	The ID of the learning instance that owns the goal
goal_id	uuid	No	The ID of the goal to update

Request/Response Body

See Create a new goal.

Delete an Existing Goal

DELETE /learning-instances/{li_id}/scoped-goals/{goal_id}

Delete an existing goal.

Authorization

This endpoint must be called by the partner admin user or a user registered as an instructor for the specified learning instance.

Path Parameters

Parameter	Type	Optional	Description
li_id	uuid	No	The ID of the learning instance that owns the goal
goal_id	uuid	No	The ID of the goal to delete

Goals and Registrations

Assign a Goal to a Single Registration

PUT /learning-instances/{li_id}/scoped-goals/{goal_id}/registrations/{reg_id}

Assign a goal to a registration in order for recommendations and analytics to be generated.

Authorization

This endpoint must be called by the partner admin user or a user registered as an instructor for the specified learning instance.

Path Parameters

Parameter	Type	Optional	Description
li_id	uuid	No	The ID of the learning instance that owns the goal
goal_id	uuid	No	The ID of the goal to assign
reg_id	uuid	No	The ID of the registration for which to assign the goal

Response Body

Parameter	Type	Optional	Description
goal_id	uuid	No	The ID of the goal that has been assigned
registration_id	uuid	No	The ID of the registration that has been assigned the goal

Sample Response Body

{
  "goal_id": "1538cf56-2fec-4734-b477-6b74ab489273",
  "registration_id": "6b74ab48-7f56-6b74-6b74-6b741538cf56"
}

Check if a Registration Has Been Assigned a Goal

GET /learning-instances/{li_id}/scoped-goals/{goal_id}/registrations/{reg_id}

Check if the registration has been assigned to this goal. If an HTTP 404 Not Found is returned, then it has not been assigned, otherwise it has been.

Authorization

This endpoint must be called by the partner admin user, a user registered as an instructor for the specified learning instance, or the user that corresponds to the registration.

Response Body

Parameter	Type	Optional	Description
goal_id	uuid	No	The ID of the goal that has been assigned
registration_id	uuid	No	The ID of the registration that has been assigned the goal

{
  "goal_id": "1538cf56-2fec-4734-b477-6b74ab489273",
  "registration_id": "6b74ab48-7f56-6b74-6b74-6b741538cf56"
}

Unassign a Goal From a Registration

DELETE /learning-instances/{li_id}/scoped-goals/{goal_id}/registrations/{reg_id}

Unassign the goal for a specific registration.

Authorization

This endpoint must be called by the partner admin user or a user registered as an instructor for the specified learning instance.

Path Parameters

Parameter	Type	Optional	Description
li_id	uuid	No	The ID of the learning instance that owns the goal
goal_id	uuid	No	The ID of the goal to assign
reg_id	uuid	No	The ID of the registration for which to assign the goal

Assign (or Unassign) a Goal To (or From) Multiple Registrations

PUT /learning-instances/{li_id}/scoped-goals/{goal_id}/registrations

Assign (or unassign) a goal to (or from) multiple registrations in a single call.

Authorization

This endpoint must be called by the partner admin user or a user registered as an instructor for the specified learning instance.

Path Parameters

Parameter	Type	Optional	Description
li_id	uuid	No	The ID of the learning instance that owns the goal
goal_id	uuid	No	The ID of the goal to assign

Request Body

Parameter	Type	Optional	Description
action	string	No	Must be either “assign” or “unassign”
registration_type	string	Yes	Type of batch call - can be either “all”, “learners”, or “instructors”. Only one of registration_type or registration_ids can be specified.
registration_ids	uuid[]	Yes	List of registration ids to assign or unassign. Only one of registration_type or registration_ids can be specified.

Sample Request Body

{
  "action": "assign",
  "registration_ids": [
    "1538cf56-2fec-4734-b477-6b74ab489273",
    "6b74ab48-7f56-6b74-6b74-6b741538cf56"
  ]
}

Response Body

Parameter	Type	Optional	Description
action	string	No	Must be either “assign” or “unassign”
registration_type	string	Yes	Type of batch call - can be either “all”, “learners”, or “instructors”. Only one of registration_type or registration_ids can be specified.
registration_ids	uuid[]	Yes	List of registration ids to assign or unassign. Only one of registration_type or registration_ids can be specified.
success.code	integer	Yes	Part of a partial response, the HTTP status code for this part
success.body	object	Yes	Part of a partial response, contains the successfully updated registration ids
success.body.registration_ids	uuid[]	Yes	The IDs for the registrations successfully updated
failure[].code	integer	Yes	Part of a partial response, the HTTP status for this part of the errors
failure[].message	string	Yes	Part of a partial response, a string description of the error that occurred
failure[].error_id	uuid	Yes	Part of a partial response, a unique error ID for this failure
failure[].body	object	Yes	Part of a partial response, contains the unsuccessfully updated registration IDs
failure[].body.registration_ids	uuid[]	Yes	The IDs for the registrations not successfully updated

Sample Response Body:

{
  "action": "assign",
  "registration_ids": [
    "1538cf56-2fec-4734-b477-6b74ab489273",
    "6b74ab48-7f56-6b74-6b74-6b741538cf56"
  ],
  "success": {
    "code": 200,
    "body": {
      "registration_ids": [
        "1538cf56-2fec-4734-b477-6b74ab489273",
        "6b74ab48-7f56-6b74-6b74-6b741538cf56"
      ]
    }
  }
}