🚀 Heads up: Our API Docs Have Moved!
We have relocated to Instructure Developer Documentation Portal. 🎉 Please update your bookmarks. This page will automatically redirect after July 1, 2026.

Proficiency Ratings API

API for customizing proficiency ratings

A ProficiencyRating object looks like:

{
  // The description of the rating
  "description": "Exceeds Mastery",
  // A non-negative number of points for the rating
  "points": 4,
  // Indicates the rating where mastery is first achieved
  "mastery": false,
  // The hex color code of the rating
  "color": "02672D"
}

A Proficiency object looks like:

{
  // An array of proficiency ratings. See the ProficiencyRating specification
  // above.
  "ratings": []
}

Create/update proficiency ratings OutcomeProficiencyApiController#create

POST /api/v1/accounts/:account_id/outcome_proficiency

Scope: url:POST|/api/v1/accounts/:account_id/outcome_proficiency

POST /api/v1/courses/:course_id/outcome_proficiency

Scope: url:POST|/api/v1/courses/:course_id/outcome_proficiency

Create or update account-level proficiency ratings. These ratings will apply to all sub-accounts, unless they have their own account-level proficiency ratings defined.

Request Parameters:

Parameter Type Description
ratings[][description] string

The description of the rating level.
ratings[][points] integer

The non-negative number of points of the rating level. Points across ratings should be strictly decreasing in value.
ratings[][mastery] integer

Indicates the rating level where mastery is first achieved. Only one rating in a proficiency should be marked for mastery.
ratings[][color] integer

The color associated with the rating level. Should be a hex color code like ‘00FFFF’.

Example Request:

curl 'https://<canvas>/api/v1/accounts/<account_id>/outcome_proficiency' \
     -X POST \
     -F 'ratings[][description]=Exceeds Mastery' \
     -F 'ratings[][points]=4' \
     -F 'ratings[][color]=02672D' \
     -F 'ratings[][mastery]=false' \
     -F 'ratings[][description]=Mastery' \
     -F 'ratings[][points]=3' \
     -F 'ratings[][color]=03893D' \
     -F 'ratings[][mastery]=true' \
     -F 'ratings[][description]=Near Mastery' \
     -F 'ratings[][points]=2' \
     -F 'ratings[][color]=FAB901' \
     -F 'ratings[][mastery]=false' \
     -F 'ratings[][description]=Below Mastery' \
     -F 'ratings[][points]=1' \
     -F 'ratings[][color]=FD5D10' \
     -F 'ratings[][mastery]=false' \
     -F 'ratings[][description]=Well Below Mastery' \
     -F 'ratings[][points]=0' \
     -F 'ratings[][color]=E62429' \
     -F 'ratings[][mastery]=false' \
     -H "Authorization: Bearer <token>"
Returns a Proficiency object

Get proficiency ratings OutcomeProficiencyApiController#show

GET /api/v1/accounts/:account_id/outcome_proficiency

Scope: url:GET|/api/v1/accounts/:account_id/outcome_proficiency

GET /api/v1/courses/:course_id/outcome_proficiency

Scope: url:GET|/api/v1/courses/:course_id/outcome_proficiency

Get account-level proficiency ratings. If not defined for this account, it will return proficiency ratings for the nearest super-account with ratings defined. Will return 404 if none found.

Examples:
  curl https://<canvas>/api/v1/accounts/<account_id>/outcome_proficiency \
      -H 'Authorization: Bearer <token>'
Returns a Proficiency object