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: 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:
-
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: Parameters: - appointment_group (dict) – The attributes of the appointment group.
- title (str) – The title of the appointment group.
Return type:
-
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: 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:
-
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: 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: - account (int, str or
-
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
ofcanvasapi.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
ofcanvasapi.conversation.Conversation
-
get_course
(course, use_sis_id=False, **kwargs)¶ Retrieve a course by its ID.
Calls: 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: - course (int, str or
-
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
ofcanvasapi.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
ofcanvasapi.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
ofcanvasapi.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: 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: - 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: 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: - 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: Parameters: - user (
canvasapi.user.User
or int) – The user’s object or ID. - id_type (str) – The ID type.
Return type: - user (
-
list_appointment_groups
(**kwargs)¶ List appointment groups.
Calls: GET /api/v1/appointment_groups Return type: canvasapi.paginated_list.PaginatedList
ofcanvasapi.appointment_group.AppointmentGroup
-
list_calendar_events
(**kwargs)¶ List calendar events.
Calls: GET /api/v1/calendar_events Return type: canvasapi.paginated_list.PaginatedList
ofcanvasapi.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
ofcanvasapi.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
ofcanvasapi.user.User
-
reserve_time_slot
(calendar_event, participant_id=None, **kwargs)¶ Return single Calendar Event by id
Calls: 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: - calendar_event (
-
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: Parameters: - course (
canvasapi.course.Course
or int) – The ID of the course. - nickname (str) – The nickname for the course.
Return type: - course (