Feature Flags

Manage optional features in Canvas.

Deprecated[2016-01-15] FeatureFlags previously had a locking_account_id field; it was never used, and has been removed. It is still included in API responses for backwards compatibility reasons. Its value is always null.

A Feature object looks like:

{
  // The symbolic name of the feature, used in FeatureFlags
  "feature": "fancy_wickets",
  // The user-visible name of the feature
  "display_name": "Fancy Wickets",
  // The type of object the feature applies to (RootAccount, Account, Course, or
  // User):
  // * RootAccount features may only be controlled by flags on root accounts.
  // * Account features may be controlled by flags on accounts and their parent
  // accounts.
  // * Course features may be controlled by flags on courses and their parent
  // accounts.
  // * User features may be controlled by flags on users and site admin only.
  "applies_to": "Course",
  // The FeatureFlag that applies to the caller
  "feature_flag": {"feature":"fancy_wickets","state":"allowed"},
  // If true, a feature that is 'allowed' globally will be 'off' by default in
  // root accounts. Otherwise, root accounts inherit the global 'allowed' setting,
  // which allows sub-accounts and courses to turn features on with no root
  // account action.
  "root_opt_in": true,
  // Whether the feature is a feature preview. If true, opting in includes ongoing
  // updates outside the regular release schedule.
  "beta": true,
  // Whether the details of the feature are autoexpanded on page load vs. the user
  // clicking to expand.
  "autoexpand": true,
  // A URL to the release notes describing the feature
  "release_notes_url": "http://canvas.example.com/release_notes#fancy_wickets"
}

A FeatureFlag object looks like:

{
  // The type of object to which this flag applies (Account, Course, or User).
  // (This field is not present if this FeatureFlag represents the global Canvas
  // default)
  "context_type": "Account",
  // The id of the object to which this flag applies (This field is not present if
  // this FeatureFlag represents the global Canvas default)
  "context_id": 1038,
  // The feature this flag controls
  "feature": "fancy_wickets",
  // The policy for the feature at this context.  can be 'off', 'allowed',
  // 'allowed_on', or 'on'.
  "state": "allowed",
  // If set, this feature flag cannot be changed in the caller's context because
  // the flag is set 'off' or 'on' in a higher context
  "locked": false
}

List features

FeatureFlagsController#index

`GET /api/v1/courses/:course_id/features`

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

`GET /api/v1/accounts/:account_id/features`

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

`GET /api/v1/users/:user_id/features`

Scope: url:GET|/api/v1/users/:user_id/features

A paginated list of all features that apply to a given Account, Course, or User.

Example Request:

curl 'http://<canvas>/api/v1/courses/1/features' \
  -H "Authorization: Bearer <token>"

Returns a list of Feature objects.

List enabled features

FeatureFlagsController#enabled_features

`GET /api/v1/courses/:course_id/features/enabled`

Scope: url:GET|/api/v1/courses/:course_id/features/enabled

`GET /api/v1/accounts/:account_id/features/enabled`

Scope: url:GET|/api/v1/accounts/:account_id/features/enabled

`GET /api/v1/users/:user_id/features/enabled`

Scope: url:GET|/api/v1/users/:user_id/features/enabled

A paginated list of all features that are enabled on a given Account, Course, or User. Only the feature names are returned.

Example Request:

curl 'http://<canvas>/api/v1/courses/1/features/enabled' \
  -H "Authorization: Bearer <token>"

Example Response:

["fancy_wickets", "automatic_essay_grading", "telepathic_navigation"]

List environment features

FeatureFlagsController#environment

`GET /api/v1/features/environment`

Scope: url:GET|/api/v1/features/environment

Return a hash of global feature options that pertain to the Canvas user interface. This is the same information supplied to the web interface as ENV.FEATURES.

Example Request:

curl 'http://<canvas>/api/v1/features/environment' \
  -H "Authorization: Bearer <token>"

Example Response:

{ "telepathic_navigation": true, "fancy_wickets": true, "automatic_essay_grading": false }

Get feature flag

FeatureFlagsController#show

`GET /api/v1/courses/:course_id/features/flags/:feature`

Scope: url:GET|/api/v1/courses/:course_id/features/flags/:feature

`GET /api/v1/accounts/:account_id/features/flags/:feature`

Scope: url:GET|/api/v1/accounts/:account_id/features/flags/:feature

`GET /api/v1/users/:user_id/features/flags/:feature`

Scope: url:GET|/api/v1/users/:user_id/features/flags/:feature

Get the feature flag that applies to a given Account, Course, or User. The flag may be defined on the object, or it may be inherited from a parent account. You can look at the context_id and context_type of the returned object to determine which is the case. If these fields are missing, then the object is the global Canvas default.

Example Request:

curl 'http://<canvas>/api/v1/courses/1/features/flags/fancy_wickets' \
  -H "Authorization: Bearer <token>"

Returns a FeatureFlag object.

Set feature flag

FeatureFlagsController#update

`PUT /api/v1/courses/:course_id/features/flags/:feature`

Scope: url:PUT|/api/v1/courses/:course_id/features/flags/:feature

`PUT /api/v1/accounts/:account_id/features/flags/:feature`

Scope: url:PUT|/api/v1/accounts/:account_id/features/flags/:feature

`PUT /api/v1/users/:user_id/features/flags/:feature`

Scope: url:PUT|/api/v1/users/:user_id/features/flags/:feature

Set a feature flag for a given Account, Course, or User. This call will fail if a parent account sets a feature flag for the same feature in any state other than “allowed”.

Request Parameters:

Parameter Type Description

Parameter	Type	Description
`state`	`string`	“off” The feature is not available for the course, user, or account and sub-accounts. “allowed” (valid only on accounts) The feature is off in the account, but may be enabled in sub-accounts and courses by setting a feature flag on the sub-account or course. “on” The feature is turned on unconditionally for the user, course, or account and sub-accounts. Allowed values: `off`, `allowed`, `on`

state

string

“off”
The feature is not available for the course, user, or account and sub-accounts.
“allowed”
(valid only on accounts) The feature is off in the account, but may be enabled in sub-accounts and courses by setting a feature flag on the sub-account or course.
“on”
The feature is turned on unconditionally for the user, course, or account and sub-accounts.

Allowed values: off, allowed, on

Example Request:

curl -X PUT 'http://<canvas>/api/v1/courses/1/features/flags/fancy_wickets' \
  -H "Authorization: Bearer " \
  -F "state=on"

Returns a FeatureFlag object.

Remove feature flag

FeatureFlagsController#delete

`DELETE /api/v1/courses/:course_id/features/flags/:feature`

Scope: url:DELETE|/api/v1/courses/:course_id/features/flags/:feature

`DELETE /api/v1/accounts/:account_id/features/flags/:feature`

Scope: url:DELETE|/api/v1/accounts/:account_id/features/flags/:feature

`DELETE /api/v1/users/:user_id/features/flags/:feature`

Scope: url:DELETE|/api/v1/users/:user_id/features/flags/:feature

Remove feature flag for a given Account, Course, or User. (Note that the flag must be defined on the Account, Course, or User directly.) The object will then inherit the feature flags from a higher account, if any exist. If this flag was ‘on’ or ‘off’, then lower-level account flags that were masked by this one will apply again.

Example Request:

curl -X DELETE 'http://<canvas>/api/v1/courses/1/features/flags/fancy_wickets' \
  -H "Authorization: Bearer <token>"

Returns a FeatureFlag object.

Last updated 12 days ago