🚀 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.
We have relocated to Instructure Developer Documentation Portal. 🎉 Please update your bookmarks. This page will automatically redirect after July 1, 2026.
Cohort Leaders API
List, add and remove the leaders of a cohort. A leader's rights reach the cohort and every cohort beneath it.
A CohortLeader object looks like:
// One leader assignment on one cohort.
{
// the ID of the assignment, used to update or remove it
"id": 5501,
// the cohort the assignment was returned for
"cohort_id": 4002,
// the leader
"user_id": 901,
// the root account of the cohort
"root_account_id": 1,
// the cohort leader role the assignment carries
"role_id": 12,
// the role's id, label and base_role_type (always CohortLeader)
"role": {"id":12,"label":"Cohort Leader","base_role_type":"CohortLeader"},
// always true; a leader's rights cannot be confined to one level
"applies_to_descendants": true,
// true when the assignment lives on an ancestor cohort and was returned because
// of include_inherited
"inherited": false,
// the cohort the assignment actually lives on; equal to cohort_id unless
// inherited
"source_cohort_id": 4002,
// the status of the assignment
"workflow_state": "active",
// when the assignment was created
"created_at": "2026-09-05T13:30:00Z",
// when the assignment was last updated
"updated_at": "2026-09-05T13:30:00Z",
// the leader's display fields: id, name, sortable_name and short_name, plus
// sis_user_id, login_id and email when the caller holds read_sis (or manage_sis
// on the root account), view_user_logins or read_email_addresses on the
// cohort's account; each is null when the leader has no value
"user": {"id":901,"name":"Dana Okafor","sortable_name":"Okafor, Dana","short_name":"Dana"}
}
List cohort leaders CohortLeadersController#index
GET /api/v1/accounts/:account_id/cohorts/:cohort_id/leaders
Scope:
Return the leaders assigned directly to a cohort, newest first. Paginated.
url:GET|/api/v1/accounts/:account_id/cohorts/:cohort_id/leaders
Request Parameters:
| Parameter | Type | Description | |
|---|---|---|---|
| include_inherited | boolean | Also return the leaders of every ancestor cohort. Those entries carry inherited true and a source_cohort_id naming the ancestor they live on. Defaults to false. | |
| sort | string |
The field to sort by. Defaults to created_at. user_name and
user_sortable_name sort on the leader's user. Ties are broken by id,
ascending.
Allowed values: |
|
| order | string |
The sort direction. Defaults to desc.
Allowed values: |
Add a leader to a cohort CohortLeadersController#create
POST /api/v1/accounts/:account_id/cohorts/:cohort_id/leaders
Scope:
Assign a user as a leader of a cohort. The assignment reaches the cohort
and every cohort beneath it. When the user already holds the role on this
cohort, the existing assignment is returned unchanged. A removed
assignment for the same user and role is reactivated.
url:POST|/api/v1/accounts/:account_id/cohorts/:cohort_id/leaders
Request Parameters:
| Parameter | Type | Description | |
|---|---|---|---|
| user_id | Required | string | The user to assign, as an id or an SIS id such as sis_user_id:abc. The user needs an active login in the cohort's root account. A user that doesn't exist or has no such login returns 404. |
| role_id | integer | A role whose base type is CohortLeader. Defaults to the built-in Cohort Leader role. |
Update a leader's role CohortLeadersController#update
PUT /api/v1/accounts/:account_id/cohorts/:cohort_id/leaders/:cohort_leader_id
Scope:
Change the role a leader assignment carries. The assignment keeps its
created_at; only updated_at advances. When the user already holds the
target role on this cohort through a separate assignment, the assignment
named in the path is removed and the other one is returned unchanged,
which also requires permission to remove leaders. An assignment inherited
from an ancestor cohort must be updated on the cohort that owns it.
url:PUT|/api/v1/accounts/:account_id/cohorts/:cohort_id/leaders/:cohort_leader_id
Request Parameters:
| Parameter | Type | Description | |
|---|---|---|---|
| role_id | Required | integer | A role whose base type is CohortLeader. |
Remove a leader from a cohort CohortLeadersController#destroy
DELETE /api/v1/accounts/:account_id/cohorts/:cohort_id/leaders/:cohort_leader_id
Scope:
Soft-delete a leader assignment that lives on this cohort. An assignment
inherited from an ancestor cohort must be removed from the cohort that
owns it.
Returns a
CohortLeader
object
url:DELETE|/api/v1/accounts/:account_id/cohorts/:cohort_id/leaders/:cohort_leader_id