Canvas¶

class canvasapi.Canvas(base_url, access_token)¶

The main class to be instantiated to provide access to Canvas’s API.

Parameters:	base_url (str) – The base URL of the Canvas instance’s API. access_token (str) – The API key to authenticate requests with.

clear_course_nicknames()¶

Remove all stored course nicknames.

Calls:	DELETE /api/v1/users/self/course_nicknames
Returns:	True if the nicknames were cleared, False otherwise.
Return type:	bool

conversations_batch_update(conversation_ids, event)¶

Calls:	PUT /api/v1/conversations
Parameters:	conversation_ids (list of str) – List of conversations to update. Limited to 500 conversations. event (str) – The action to take on each conversation.
Return type:	`canvasapi.progress.Progress`

conversations_get_running_batches()¶

Returns any currently running conversation batches for the current user. Conversation batches are created when a bulk private message is sent asynchronously.

Calls:	GET /api/v1/conversations/batches
Returns:	dict with list of batch objects - not currently a Class
Return type:	dict

conversations_mark_all_as_read()¶

Mark all conversations as read.

Calls:	POST /api/v1/conversations/mark_all_as_read
Return type:	bool

conversations_unread_count()¶

Get the number of unread conversations for the current user

Calls:	GET /api/v1/conversations/unread_count
Returns:	simple object with unread_count, example: {‘unread_count’: ‘7’}
Return type:	dict

create_account(**kwargs)¶

Create a new root account.

Calls:	POST /api/v1/accounts
Return type:	`canvasapi.account.Account`

create_appointment_group(appointment_group, **kwargs)¶

Create a new Appointment Group.

Calls:	POST /api/v1/appointment_groups
Parameters:	appointment_group (dict) – The attributes of the appointment group. title (str) – The title of the appointment group.
Return type:	`canvasapi.appointment_group.AppointmentGroup`

create_calendar_event(calendar_event, **kwargs)¶

Create a new Calendar Event.

Calls:	POST /api/v1/calendar_events
Parameters:	calendar_event (dict) – The attributes of the calendar event.
Return type:	`canvasapi.calendar_event.CalendarEvent`

create_conversation(recipients, body, **kwargs)¶

Create a new Conversation.

Calls:	POST /api/v1/conversations
Parameters:	recipients (list of str) – An array of recipient ids. These may be user ids or course/group ids prefixed with ‘course_’ or ‘group_’ respectively, e.g. recipients=[‘1’, ‘2’, ‘course_3’] body (str) – The body of the message being added.
Return type:	list of `canvasapi.conversation.Conversation`

create_group(**kwargs)¶

Create a group

Calls:	POST /api/v1/groups/
Return type:	`canvasapi.group.Group`

get_account(account, use_sis_id=False, **kwargs)¶

Retrieve information on an individual account.

Calls:	GET /api/v1/accounts/:id
Parameters:	account (int, str or `canvasapi.account.Account`) – The object or ID of the account to retrieve. use_sis_id (bool) – Whether or not account_id is an sis ID. Defaults to False.
Return type:	`canvasapi.account.Account`

get_accounts(**kwargs)¶

List accounts that the current user can view or manage.

Typically, students and teachers will get an empty list in response. Only account admins can view the accounts that they are in.

Calls:	GET /api/v1/accounts
Return type:	`canvasapi.paginated_list.PaginatedList` of `canvasapi.account.Account`

get_activity_stream_summary()¶

Return a summary of the current user’s global activity stream.

Calls:	GET /api/v1/users/self/activity_stream/summary
Return type:	dict

get_appointment_group(appointment_group)¶

Return single Appointment Group by id

Calls:	GET /api/v1/appointment_groups/:id
Parameters:	appointment_group (`canvasapi.appointment_group.AppointmentGroup` or int) – The ID of the appointment group.
Return type:	`canvasapi.appointment_group.AppointmentGroup`

get_calendar_event(calendar_event)¶

Return single Calendar Event by id

Calls:	GET /api/v1/calendar_events/:id
Parameters:	calendar_event (`canvasapi.calendar_event.CalendarEvent` or int) – The object or ID of the calendar event.
Return type:	`canvasapi.calendar_event.CalendarEvent`

get_conversation(conversation, **kwargs)¶

Return single Conversation

Calls:	GET /api/v1/conversations/:id
Parameters:	conversation (`canvasapi.conversation.Conversation` or int) – The object or ID of the conversation.
Return type:	`canvasapi.conversation.Conversation`

get_conversations(**kwargs)¶

Return list of conversations for the current user, most resent ones first.

Calls:	GET /api/v1/conversations
Return type:	`canvasapi.paginated_list.PaginatedList` of `canvasapi.conversation.Conversation`

get_course(course, use_sis_id=False, **kwargs)¶

Retrieve a course by its ID.

Calls:	GET /courses/:id
Parameters:	course (int, str or `canvasapi.course.Course`) – The object or ID of the course to retrieve. use_sis_id (bool) – Whether or not course_id is an sis ID. Defaults to False.
Return type:	`canvasapi.course.Course`

get_course_accounts()¶

List accounts that the current user can view through their admin course enrollments (Teacher, TA or designer enrollments).

Only returns id, name, workflow_state, root_account_id and parent_account_id.

Calls:	GET /api/v1/course_accounts
Return type:	`canvasapi.paginated_list.PaginatedList` of `canvasapi.account.Account`

get_course_nickname(course)¶

Return the nickname for the given course.

Calls:	GET /api/v1/users/self/course_nicknames/:course_id
Parameters:	course (`canvasapi.course.Course` or int) – The object or ID of the course.
Return type:	`canvasapi.course.CourseNickname`

get_course_nicknames()¶

Return all course nicknames set by the current account.

Calls:	GET /api/v1/users/self/course_nicknames
Return type:	`canvasapi.paginated_list.PaginatedList` of `canvasapi.course.CourseNickname`

get_courses(**kwargs)¶

Return a list of active courses for the current user.

Calls:	GET /api/v1/courses
Return type:	`canvasapi.paginated_list.PaginatedList` of `canvasapi.course.Course`

get_file(file, **kwargs)¶

Return the standard attachment json object for a file.

Calls:	GET /api/v1/files/:id
Parameters:	file (`canvasapi.file.File` or int) – The object or ID of the file to retrieve.
Return type:	`canvasapi.file.File`

get_folder(folder)¶

Return the details for a folder

Calls:	GET /api/v1/folders/:id
Parameters:	folder (`canvasapi.folder.Folder` or int) – The object or ID of the folder to retrieve.
Return type:	`canvasapi.folder.Folder`

get_group(group, use_sis_id=False, **kwargs)¶

Return the data for a single group. If the caller does not have permission to view the group a 401 will be returned.

Calls:	GET /api/v1/groups/:group_id
Parameters:	group (`canvasapi.group.Group` or int) – The object or ID of the group to get. use_sis_id (bool) – Whether or not group_id is an sis ID. Defaults to False.
Return type:	`canvasapi.group.Group`

get_group_category(category)¶

Get a single group category.

Calls:	GET /api/v1/group_categories/:group_category_id
Parameters:	category (`canvasapi.group.GroupCategory` or int) – The object or ID of the category.
Return type:	`canvasapi.group.GroupCategory`

get_outcome(outcome)¶

Returns the details of the outcome with the given id.

Calls:	GET /api/v1/outcomes/:id
Parameters:	outcome (`canvasapi.outcome.Outcome` or int) – The outcome object or ID to return.
Returns:	An Outcome object.
Return type:	`canvasapi.outcome.Outcome`

get_outcome_group(group)¶

Returns the details of the Outcome Group with the given id.

Calls:	GET /api/v1/global/outcome_groups/:id
Parameters:	group (`canvasapi.outcome.OutcomeGroup` or int) – The outcome group object or ID to return.
Returns:	An outcome group object.
Return type:	`canvasapi.outcome.OutcomeGroup`

get_root_outcome_group()¶

Redirect to root outcome group for context

Calls:	GET /api/v1/global/root_outcome_group
Returns:	The OutcomeGroup of the context.
Return type:	`canvasapi.outcome.OutcomeGroup`

get_section(section, use_sis_id=False, **kwargs)¶

Get details about a specific section.

Calls:	GET /api/v1/sections/:id
Parameters:	section (`canvasapi.section.Section` or int) – The object or ID of the section to get. use_sis_id (bool) – Whether or not section_id is an sis ID. Defaults to False.
Return type:	`canvasapi.section.Section`

get_todo_items()¶

Return the current user’s list of todo items, as seen on the user dashboard.

Calls:	GET /api/v1/users/self/todo
Return type:	dict

get_upcoming_events()¶

Return the current user’s upcoming events, i.e. the same things shown in the dashboard ‘Coming Up’ sidebar.

Calls:	GET /api/v1/users/self/upcoming_events
Return type:	dict

get_user(user, id_type=None)¶

Retrieve a user by their ID. id_type denotes which endpoint to try as there are several different IDs that can pull the same user record from Canvas.

Refer to API documentation’s User example to see the ID types a user can be retrieved with.

Calls:	GET /users/:id
Parameters:	user (`canvasapi.user.User` or int) – The user’s object or ID. id_type (str) – The ID type.
Return type:	`canvasapi.user.User`

list_appointment_groups(**kwargs)¶

List appointment groups.

Calls:	GET /api/v1/appointment_groups
Return type:	`canvasapi.paginated_list.PaginatedList` of `canvasapi.appointment_group.AppointmentGroup`

list_calendar_events(**kwargs)¶

List calendar events.

Calls:	GET /api/v1/calendar_events
Return type:	`canvasapi.paginated_list.PaginatedList` of `canvasapi.calendar_event.CalendarEvent`

list_group_participants(appointment_group, **kwargs)¶

List student group participants in this appointment group.

Calls:	GET /api/v1/appointment_groups/:id/groups
Parameters:	appointment_group (`canvasapi.appointment_group.AppointmentGroup` or int) – The object or ID of the appointment group.
Return type:	`canvasapi.paginated_list.PaginatedList` of `canvasapi.group.Group`

list_user_participants(appointment_group, **kwargs)¶

List user participants in this appointment group.

Calls:	GET /api/v1/appointment_groups/:id/users
Parameters:	appointment_group (`canvasapi.appointment_group.AppointmentGroup` or int) – The object or ID of the appointment group.
Return type:	`canvasapi.paginated_list.PaginatedList` of `canvasapi.user.User`

reserve_time_slot(calendar_event, participant_id=None, **kwargs)¶

Return single Calendar Event by id

Calls:	POST /api/v1/calendar_events/:id/reservations
Parameters:	calendar_event (`canvasapi.calendar_event.CalendarEvent` or int) – The object or ID of the calendar event. participant_id (str) – The ID of the participant, if given.
Return type:	`canvasapi.calendar_event.CalendarEvent`

search_accounts(**kwargs)¶

Return a list of up to 5 matching account domains. Partial matches on name and domain are supported.

Calls:	GET /api/v1/accounts/search
Return type:	dict

search_all_courses(**kwargs)¶

List all the courses visible in the public index. Returns a list of dicts, each containing a single course.

Calls:	GET /api/v1/search/all_courses
Return type:	list

search_recipients(**kwargs)¶

Find valid recipients (users, courses and groups) that the current user can send messages to. Returns a list of mixed data types.

Calls:	GET /api/v1/search/recipients
Return type:	list

set_course_nickname(course, nickname)¶

Set a nickname for the given course. This will replace the course’s name in the output of subsequent API calls, as well as in selected places in the Canvas web user interface.

Calls:	PUT /api/v1/users/self/course_nicknames/:course_id
Parameters:	course (`canvasapi.course.Course` or int) – The ID of the course. nickname (str) – The nickname for the course.
Return type:	`canvasapi.course.CourseNickname`