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:

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(**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:

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

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:

POST /api/v1/planner/overrides

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:

canvasapi.planner.PlannerOverride

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:

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_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 of canvasapi.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 of canvasapi.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 of canvasapi.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 of canvasapi.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 of canvasapi.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 of canvasapi.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 of canvasapi.conversation.Conversation

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

Retrieve a course by its ID.

Calls:

GET /api/v1/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(**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 of canvasapi.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 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_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 of canvasapi.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:

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, **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 of canvasapi.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 of canvasapi.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 of canvasapi.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 of canvasapi.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:

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(**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:

GET /api/v1/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

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 of canvasapi.user.User

graphql(query, variables=None, **kwargs)

Makes a GraphQL formatted request to Canvas

Calls:

POST /api/graphql

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:

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, **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:

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