# Feature Flags

{% hint style="warning" %}
**Welcome to Our New API Docs!** This is the new home for all things API (previously at [Canvas LMS REST API Documentation](https://api.instructure.com)).
{% endhint %}

## Feature Flags API

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:**

```js
{
  // 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,
  // Indicates the feature is part of the Early Access Program.
  "early_access_program": false,
  // 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:**

```js
{
  // 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](#method.feature_flags.index) <a href="#method.feature_flags.index" id="method.feature_flags.index"></a>

[FeatureFlagsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/feature_flags_controller.rb)

**`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.

**Request Parameters:**

| Parameter                | Type      | Description                                                                                             |
| ------------------------ | --------- | ------------------------------------------------------------------------------------------------------- |
| `hide_inherited_enabled` | `boolean` | When true, feature flags that are enabled in a higher context and cannot be overridden will be omitted. |

**Example Request:**

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

Returns a list of [Feature](#feature) objects.

### [List enabled features](#method.feature_flags.enabled_features) <a href="#method.feature_flags.enabled_features" id="method.feature_flags.enabled_features"></a>

[FeatureFlagsController#enabled\_features](https://github.com/instructure/canvas-lms/blob/master/app/controllers/feature_flags_controller.rb)

**`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:**

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

**Example Response:**

```js
["fancy_wickets", "automatic_essay_grading", "telepathic_navigation"]
```

### [List environment features](#method.feature_flags.environment) <a href="#method.feature_flags.environment" id="method.feature_flags.environment"></a>

[FeatureFlagsController#environment](https://github.com/instructure/canvas-lms/blob/master/app/controllers/feature_flags_controller.rb)

**`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:**

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

**Example Response:**

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

### [Get feature flag](#method.feature_flags.show) <a href="#method.feature_flags.show" id="method.feature_flags.show"></a>

[FeatureFlagsController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/feature_flags_controller.rb)

**`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:**

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

Returns a [FeatureFlag](#featureflag) object.

### [Set feature flag](#method.feature_flags.update) <a href="#method.feature_flags.update" id="method.feature_flags.update"></a>

[FeatureFlagsController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/feature_flags_controller.rb)

**`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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `state`   | `string` | <ul><li><p>“off”</p><p>The feature is not available for the course, user, or account and sub-accounts.</p></li><li><p>“allowed”</p><p>(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.</p></li><li><p>“on”</p><p>The feature is turned on unconditionally for the user, course, or account and sub-accounts.</p></li></ul><p>Allowed values: <code>off</code>, <code>allowed</code>, <code>on</code></p> |

**Example Request:**

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

Returns a [FeatureFlag](#featureflag) object.

### [Remove feature flag](#method.feature_flags.delete) <a href="#method.feature_flags.delete" id="method.feature_flags.delete"></a>

[FeatureFlagsController#delete](https://github.com/instructure/canvas-lms/blob/master/app/controllers/feature_flags_controller.rb)

**`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:**

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

Returns a [FeatureFlag](#featureflag) object.

***

This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developerdocs.instructure.com/services/canvas/resources/feature_flags.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.