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
(**kwargs)¶ 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, **kwargs)¶ 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
(**kwargs)¶ 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
(**kwargs)¶ Mark all conversations as read.
Calls: POST /api/v1/conversations/mark_all_as_read Return type: bool
-
conversations_unread_count
(**kwargs)¶ 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
-
create_jwt
(**kwargs)¶ Creates a unique JWT to use with other Canvas services.
Calls: POST /api/v1/jwts Return type: list of canvasapi.jwt.JWT
-
create_planner_note
(**kwargs)¶ Create a planner note for the current user
Calls: POST /api/v1/planner_notes Return type: canvasapi.planner.PlannerNote
-
create_planner_override
(plannable_type, plannable_id, **kwargs)¶ Create a planner override for the current user
Calls: Parameters: - plannable_type (str) – Type of the item that you are overriding in the planner
- plannable_id (int or
canvasapi.planner.PlannerOverride
) – ID of the item that you are overriding in the planner
Return type:
-
create_poll
(polls, **kwargs)¶ Create a new poll for the current user.
Calls: POST /api/v1/polls Parameters: polls (list of dict) – List of polls to create. ‘question’ key is required. Return type: canvasapi.poll.Poll
-
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_account_calendars
(**kwargs)¶ Returns a paginated list of account calendars available to the user.
Calls: GET /api/v1/account_calendars Return type: canvasapi.paginated_list.PaginatedList
ofcanvasapi.account_calendar.AccountCalendar
-
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
(**kwargs)¶ Return a summary of the current user’s global activity stream.
Calls: GET /api/v1/users/self/activity_stream/summary Return type: dict
-
get_announcements
(context_codes, **kwargs)¶ List announcements.
Calls: GET /api/v1/announcements Parameters: context_codes (list) – Course ID(s) or <Course> objects to request announcements from. Return type: canvasapi.paginated_list.PaginatedList
ofcanvasapi.discussion_topic.DiscussionTopic
-
get_appointment_group
(appointment_group, **kwargs)¶ 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_appointment_groups
(**kwargs)¶ List appointment groups.
Calls: GET /api/v1/appointment_groups Return type: canvasapi.paginated_list.PaginatedList
ofcanvasapi.appointment_group.AppointmentGroup
-
get_brand_variables
(**kwargs)¶ Get account brand variables
Calls: GET /api/v1/brand_variables Returns: JSON with brand variables for the account. Return type: dict
-
get_calendar_event
(calendar_event, **kwargs)¶ 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_calendar_events
(**kwargs)¶ List calendar events.
Calls: GET /api/v1/calendar_events Return type: canvasapi.paginated_list.PaginatedList
ofcanvasapi.calendar_event.CalendarEvent
-
get_comm_messages
(user, **kwargs)¶ Retrieve a paginated list of messages sent to a user.
Calls: GET /api/v1/comm_messages Parameters: user ( canvasapi.user.User
or int) – The object or ID of the user.Returns: Paginated list containing messages sent to user Return type: canvasapi.paginated_list.PaginatedList
ofcanvasapi.comm_message.CommMessage
-
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
(**kwargs)¶ 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, **kwargs)¶ 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
(**kwargs)¶ 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_current_user
()¶ Return a details of the current user.
Calls: GET /api/v1/users/:user_id Return type: canvasapi.current_user.CurrentUser
-
get_eportfolio
(eportfolio, **kwargs)¶ Get an eportfolio by ID.
Parameters: eportfolio – The object or ID of the eportfolio to retrieve. Calls: GET /api/v1/eportfolios/:id https://canvas.instructure.com/doc/api/e_portfolios.html#method.eportfolios_api.show Return type: canvasapi.eportfolio.EPortfolio
-
get_epub_exports
(**kwargs)¶ Return a list of epub exports for the associated course.
Calls: GET /api/v1/epub_exports Return type: canvasapi.paginated_list.PaginatedList
ofcanvasapi.course_epub_export.CourseEpubExport
-
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, **kwargs)¶ 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, **kwargs)¶ 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_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
-
get_outcome
(outcome, **kwargs)¶ 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, **kwargs)¶ 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_planner_note
(planner_note, **kwargs)¶ Retrieve a planner note for the current user
Calls: GET /api/v1/planner_notes/:id Parameters: planner_note (int or canvasapi.planner.PlannerNote
) – The ID of the planner note to retrieve.Return type: canvasapi.planner.PlannerNote
-
get_planner_notes
(**kwargs)¶ Retrieve the paginated list of planner notes
Calls: GET /api/v1/planner_notes Return type: canvasapi.paginated_list.PaginatedList
ofcanvasapi.planner.PlannerNote
-
get_planner_override
(planner_override, **kwargs)¶ Retrieve a planner override for the current user
Calls: GET /api/v1/planner/overrides/:id Parameters: planner_override (int or canvasapi.planner.PlannerOverride
) – The override or the ID of the planner override to retrieve.Return type: canvasapi.planner.PlannerOverride
-
get_planner_overrides
(**kwargs)¶ Retrieve a planner override for the current user
Calls: GET /api/v1/planner/overrides Return type: canvasapi.paginated_list.PaginatedList
ofcanvasapi.planner.PlannerOverride
-
get_poll
(poll, **kwargs)¶ Get a single poll, based on the poll id.
Calls: GET /api/v1/polls/:id Parameters: poll (int) – The ID of the poll or the poll to change. Return type: canvasapi.poll.Poll
-
get_polls
(**kwargs)¶ Returns a paginated list of polls for the current user
Calls: GET /api/1/polls Return type: canvasapi.paginated_list.PaginatedList
ofcanvasapi.poll.Poll
-
get_progress
(progress, **kwargs)¶ Get a specific progress.
Calls: GET /api/v1/progress/:id Parameters: progress (int, str or canvasapi.progress.Progress
) – The object or ID of the progress to retrieve.Return type: canvasapi.progress.Progress
-
get_root_outcome_group
(**kwargs)¶ 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
(**kwargs)¶ 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
(**kwargs)¶ 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, **kwargs)¶ 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 (
-
get_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
-
graphql
(query, variables=None, **kwargs)¶ Makes a GraphQL formatted request to Canvas
Calls: Parameters: - query (str) – The GraphQL query to execute as a String
- variables (dict) – The variable values as required by the supplied query
Return type: dict
-
refresh_jwt
(jwt, **kwargs)¶ Refreshes a JWT for reuse with other canvas services. It generates a different JWT each time it’s called; expires after one hour.
Calls: POST /api/v1/jwts/refresh Parameters: jwt (str or canvasapi.jwt.JWT
) – An existing JWT to refresh.Return type: canvasapi.jwt.JWT
-
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, **kwargs)¶ 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 (