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