Calendar Events API

API for creating, accessing and updating calendar events.

A Calendar Event object looks like:

{
  // The ID of the calendar event
  id: 234,

  // The title of the calendar event
  title: "Paintball Fight!",

  // The start timestamp of the event
  start_at: "2012-07-19T15:00:00-06:00",

  // The end timestamp of the event
  end_at: "2012-07-19T16:00:00-06:00",

  // The HTML description of the event
  description: "<b>It's that time again!</b>",

  // The location name of the event
  location_name: "Greendale Community College",

  // The address where the event is taking place
  location_address: "Greendale, Colorado",

  // the context code of the calendar this event belongs to (course, user
  // or group)
  context_code: "course_123",

  // if specified, it indicates which calendar this event should be
  // displayed on. for example, a section-level event would have the
  // course's context code here, while the section's context code would
  // be returned above)
  effective_context_code: null,

  // Current state of the event ("active", "locked" or "deleted")
  // "locked" indicates that start_at/end_at cannot be changed (though
  // the event could be deleted). Normally only reservations or time
  // slots with reservations are locked (see the Appointment Groups API)
  workflow_state: "active",

  // Whether this event should be displayed on the calendar. Only true
  // for course-level events with section-level child events.
  hidden: false,

  // Normally null. If this is a reservation (see the Appointment Groups
  // API), the id will indicate the time slot it is for. If this is a
  // section-level event, this will be the course-level parent event.
  parent_event_id: null,

  // The number of child_events. See child_events (and parent_event_id)
  child_events_count: 0,

  // Included by default, but may be excluded (see include[] option).
  // If this is a time slot (see the Appointment Groups API) this will
  // be a list of any reservations. If this is a course-level event,
  // this will be a list of section-level events (if any)
  child_events: [],

  // URL for this calendar event (to update, delete, etc.)
  url: "https://example.com/api/v1/calendar_events/234",

  // URL for a user to view this event
  html_url: "https://example.com/calendar?event_id=234&include_contexts=course_123",

  // The date of this event
  all_day_date: "2012-07-19",

  // Boolean indicating whether this is an all-day event (midnight to
  // midnight)
  all_day: false,

  // When the calendar event was created
  created_at: "2012-07-12T10:55:20-06:00",

  // When the calendar event was last updated
  updated_at: "2012-07-12T10:55:20-06:00",

  ///////////////////////////////////////////////////////////////////////
  // Various Appointment-Group-related fields                          //
  //                                                                   //
  // These fields are only pertinent to time slots (appointments) and  //
  // reservations of those time slots. See the Appointment Groups API  //
  ///////////////////////////////////////////////////////////////////////

  // The id of the appointment group
  appointment_group_id: null,

  // The API URL of the appointment group
  appointment_group_url: null,

  // If the event is a reservation, this a boolean indicating whether it
  // is the current user's reservation, or someone else's
  own_reservation: null,

  // If the event is a time slot, the API URL for reserving it 
  reserve_url: null,

  // If the event is a time slot, a boolean indicating whether the user
  // has already made a reservation for it 
  reserved: null,

  // If the event is a time slot, this is the participant limit
  participants_per_appointment: null,

  // If the event is a time slot and it has a participant limit, an
  // integer indicating how many slots are available
  available_slots: null,

  // If the event is a user-level reservation, this will contain the user
  // participant JSON (refer to the Users API).
  user: null,

  // If the event is a group-level reservation, this will contain the
  // group participant JSON (refer to the Groups API).
  group: null
}

An Assignment Event object looks like:

{
  // A synthetic ID for the assignment
  id: "assignment_987",

  // The title of the assignment
  title: "Essay",

  // The due_at timestamp of the assignment
  start_at: "2012-07-19T23:59:00-06:00",

  // The due_at timestamp of the assignment
  end_at: "2012-07-19T23:59:00-06:00",

  // The HTML description of the assignment
  description: "<b>Write an essay. Whatever you want.</b>",

  // the context code of the (course) calendar this assignment belongs to
  context_code: "course_123",

  // Current state of the assignment ("available", "published" or
  // "deleted")
  workflow_state: "published",

  // URL for this assignment (note that updating/deleting should be done
  // via the Assignments API)
  url: "https://example.com/api/v1/calendar_events/assignment_987",

  // URL for a user to view this assignment
  html_url: "http://example.com/courses/123/assignments/987",

  // The due date of this assignment
  all_day_date: "2012-07-19",

  // Boolean indicating whether this is an all-day event (e.g. assignment
  // due at midnight)
  all_day: true,

  // When the assignment was created
  created_at: "2012-07-12T10:55:20-06:00",

  // When the assignment was last updated
  updated_at: "2012-07-12T10:55:20-06:00",

  // The full assignment JSON data (See the Assignments API)
  assigmment: { id: 987, ... }
}

List calendar events CalendarEventsApiController#index

GET /api/v1/calendar_events

Retrieve the list of calendar events or assignments for the current user

Request Parameters:

  • type
    Optional, "event"|"assignment"

    Defaults to "event"

  • start_date
    Optional

    Only return events since the start_date (inclusive).

    Defaults to today. The value should be formatted as: yyyy-mm-dd.

  • end_date
    Optional

    Only return events before the end_date (inclusive).

    Defaults to start_date. The value should be formatted as: yyyy-mm-dd. If end_date is the same as start_date, then only events on that day are returned.

  • undated
    Optional

    Boolean, defaults to false (dated events only).

    If true, only return undated events and ignore start_date and end_date.

  • all_events
    Optional

    Boolean, defaults to false (uses start_date, end_date, and undated criteria).

    If true, all events are returned, ignoring start_date, end_date, and undated criteria.

  • context_codes[]
    Optional

    List of context codes of courses/groups/users whose events you want to see.

    If not specified, defaults to the current user (i.e personal calendar, no course/group events). Limited to 10 context codes, additional ones are ignored. The format of this field is the context type, followed by an underscore, followed by the context id. For example: course_42

Create a calendar event CalendarEventsApiController#create

POST /api/v1/calendar_events

Create and return a new calendar event

Request Parameters:

  • calendar_event[context_code]
    Required

    Context code of the course/group/user whose calendar this event should be added to

  • calendar_event[title]
    Optional

    Short title for the calendar event

  • calendar_event[description]
    Optional

    Longer HTML description of the event

  • calendar_event[start_at]
    Optional

    Start date/time of the event

  • calendar_event[end_at]
    Optional

    End date/time of the event

  • calendar_event[location_name]
    Optional

    Location name of the event

  • calendar_event[location_address]
    Optional

    Location address

  • calendar_event[time_zone_edited]
    Optional

    Time zone of the user editing the event. Allowed time zones are listed in The Ruby on Rails documentation.

  • calendar_event[child_event_data][X][start_at]
    Optional

    Section-level start time(s) if this is a course event. X can be any identifier, provided that it is consistent across the start_at, end_at and context_code

  • calendar_event[child_event_data][X][end_at]
    Optional

    Section-level end time(s) if this is a course event.

  • calendar_event[child_event_data][X][context_code]
    Optional

    Context code(s) corresponding to the section-level start and end time(s).

Example Request:

curl 'http://<canvas>/api/v1/calendar_events.json' \ 
     -X POST \ 
     -F 'calendar_event[context_code]=course_123' \ 
     -F 'calendar_event[title]=Paintball Fight!' \ 
     -F 'calendar_event[start_at]=2012-07-19T21:00:00Z' \ 
     -F 'calendar_event[end_at]=2012-07-19T22:00:00Z' \ 
     -H "Authorization: Bearer <token>"

Get a single calendar event or assignment CalendarEventsApiController#show

GET /api/v1/calendar_events/:id

Returns information for a single event or assignment

Reserve a time slot CalendarEventsApiController#reserve

POST /api/v1/calendar_events/:id/reservations

POST /api/v1/calendar_events/:id/reservations/:participant_id

Reserves a particular time slot and return the new reservation

Request Parameters:

  • participant_id

    [Optional]. User or group id for whom you are making the reservation (depends on the participant type). Defaults to the current user (or user's candidate group).

  • cancel_existing

    [Optional]. Defaults to false. If true, cancel any previous reservation(s) for this participant and appointment group.

Example Request:

curl 'http://<canvas>/api/v1/calendar_events/345/reservations.json' \ 
     -X POST \ 
     -F 'cancel_existing=true' \ 
     -H "Authorization: Bearer <token>"

Update a calendar event CalendarEventsApiController#update

PUT /api/v1/calendar_events/:id

Update and return a calendar event

Request Parameters:

  • calendar_event[title]
    Optional

    Short title for the calendar event

  • calendar_event[description]
    Optional

    Longer HTML description of the event

  • calendar_event[start_at]
    Optional

    Start date/time of the event

  • calendar_event[end_at]
    Optional

    End date/time of the event

  • calendar_event[location_name]
    Optional

    Location name of the event

  • calendar_event[location_address]
    Optional

    Location address

  • calendar_event[time_zone_edited]
    Optional

    Time zone of the user editing the event. Allowed time zones are listed in The Ruby on Rails documentation.

  • calendar_event[child_event_data][X][start_at]
    Optional

    Section-level start time(s) if this is a course event. X can be any identifier, provided that it is consistent across the start_at, end_at and context_code. Note that if any child_event_data is specified, it will replace any existing child events.

  • calendar_event[child_event_data][X][end_at]
    Optional

    Section-level end time(s) if this is a course event.

  • calendar_event[child_event_data][X][context_code]
    Optional

    Context code(s) corresponding to the section-level start and end time(s).

  • calendar_event[remove_child_events]
    Optional

    Boolean, indicates that all child events (i.e. section-level events) should be removed.

  • calendar_event[participants_per_appointment]
    Optional

    Maximum number of participants that may sign up for this time slot. Ignored for regular calendar events or reservations.

Example Request:

curl 'http://<canvas>/api/v1/calendar_events/234.json' \ 
     -X PUT \ 
     -F 'calendar_event[title]=Epic Paintball Fight!' \ 
     -H "Authorization: Bearer <token>"

Delete a calendar event CalendarEventsApiController#destroy

DELETE /api/v1/calendar_events/:id

Delete an event from the calendar and return the deleted event

Request Parameters:

  • cancel_reason
    Optional

    Reason for deleting/canceling the event.

Example Request:

curl 'http://<canvas>/api/v1/calendar_events/234.json' \ 
     -X DELETE \ 
     -F 'cancel_reason=Greendale layed off the janitorial staff :(' \ 
     -H "Authorization: Bearer <token>"