Account Calendars API

API for viewing and toggling visibility of account calendars.

An account calendar is available for each account in Canvas. All account calendars are visible by default, but administrators with the manage_account_calendar_visibility permission may hide calendars. Administrators with the manage_account_calendar_events permission can create events in visible account calendars, and users associated with an account can add the calendar and see its events (if the calendar is visible).

An AccountCalendar object looks like:

{
  // the ID of the account associated with this calendar
  "id": 204,
  // the name of the account associated with this calendar
  "name": "Department of Chemistry",
  // the account's parent ID, or null if this is the root account
  "parent_account_id": 1,
  // the ID of the root account, or null if this is the root account
  "root_account_id": 1,
  // whether this calendar is visible to users
  "visible": true,
  // number of this account's direct sub-accounts
  "sub_account_count": 0,
  // Asset string of the account
  "asset_string": "account_4",
  // Object type
  "type": "account",
  // url to get full detailed events
  "calendar_event_url": "/accounts/2/calendar_events/%7B%7B%20id%20%7D%7D",
  // whether the user can create calendar events
  "can_create_calendar_events": true,
  // API path to create events for the account
  "create_calendar_event_url": "/accounts/2/calendar_events",
  // url to open the more options event editor
  "new_calendar_event_url": "/accounts/6/calendar_events/new"
}

List available account calendars AccountCalendarsApiController#index

GET /api/v1/account_calendars

Scope: url:GET|/api/v1/account_calendars

Returns a paginated list of account calendars available to the current user. Includes visible account calendars where the user has an account association.

Request Parameters:

Parameter Type Description
search_term string

When included, searches available account calendars for the term. Returns matching results. Term must be at least 2 characters.

Example Request:

curl https://<canvas>/api/v1/account_calendars \
  -H 'Authorization: Bearer <token>'
Returns a list of AccountCalendar objects

Get a single account calendar AccountCalendarsApiController#show

GET /api/v1/account_calendars/:account_id

Scope: url:GET|/api/v1/account_calendars/:account_id

Get details about a specific account calendar.

Example Request:

curl https://<canvas>/api/v1/account_calendars/204 \
  -H 'Authorization: Bearer <token>'
Returns an AccountCalendar object

Update a calendar's visibility AccountCalendarsApiController#update

PUT /api/v1/account_calendars/:account_id

Scope: url:PUT|/api/v1/account_calendars/:account_id

Set an account calendar as hidden or visible. Requires the `manage_account_calendar_visibility` permission on the account.

Request Parameters:

Parameter Type Description
visible boolean

Allow administrators with `manage_account_calendar_events` permission to create events on this calendar, and allow users to view this calendar and its events.

Example Request:

curl https://<canvas>/api/v1/account_calendars/204 \
  -X PUT \
  -H 'Authorization: Bearer <token>' \
  -d 'visible=false'
Returns an AccountCalendar object

Update many calendars' visibility AccountCalendarsApiController#bulk_update

PUT /api/v1/accounts/:account_id/account_calendars

Scope: url:PUT|/api/v1/accounts/:account_id/account_calendars

Set visibility on many calendars simultaneously. Requires the `manage_account_calendar_visibility` permission on the account.

Accepts a JSON array of objects containing 2 keys each: `id` (the account's id), and `visible` (a boolean indicating whether the account calendar is visible).

Example Request:

curl https://<canvas>/api/v1/accounts/1/account_calendars \
  -X PUT \
  -H 'Authorization: Bearer <token>' \
  --data '[{"id": 1, "visible": true}, {"id": 13, "visible": false}]'
Returns an AccountCalendar object

List all account calendars AccountCalendarsApiController#all_calendars

GET /api/v1/accounts/:account_id/account_calendars

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

Returns a paginated list of account calendars for the provided account and its first level of sub-accounts. Includes hidden calendars in the response. Requires the `manage_account_calendar_visibility` permission.

Request Parameters:

Parameter Type Description
search_term string

When included, searches all descendent accounts of provided account for the term. Returns matching results. Term must be at least 2 characters. Can be combined with a filter value.
filter string

When included, only returns calendars that are either visible or hidden. Can be combined with a search term.

Allowed values: visible, hidden

Example Request:

curl https://<canvas>/api/v1/accounts/1/account_calendars \
  -H 'Authorization: Bearer <token>'
Returns a list of AccountCalendar objects

Count of all visible account calendars AccountCalendarsApiController#visible_calendars_count

GET /api/v1/accounts/:account_id/visible_calendars_count

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

Returns the number of visible account calendars.

Example Request:

curl https://<canvas>/api/v1/accounts/1/visible_calendars_count \
  -H 'Authorization: Bearer <token>'