# Calendar Events
{% hint style="warning" %}
**Welcome to Our New API Docs!** This is the new home for all things API (previously at [Canvas LMS REST API Documentation](https://api.instructure.com)).
{% endhint %}
## Calendar Events API
API for creating, accessing and updating calendar events.
**A CalendarEvent object looks like:**
```js
{
// 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": "It's that time again!",
// 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, group, user,
// or account)
"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,
// the context name of the calendar this event belongs to (course, user or
// group)
"context_name": "Chemistry 101",
// a comma-separated list of all calendar contexts this event is part of
"all_context_codes": "course_123,course_456",
// 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": null,
// 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": false,
// 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": false,
// The type of participant to sign up for a slot: 'User' or 'Group'
"participant_type": "User",
// 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,
// Boolean indicating whether this has important dates.
"important_dates": true,
// Identifies the recurring event series this event may belong to.
"series_uuid": null,
// An iCalendar RRULE for defining how events in a recurring event series
// repeat.
"rrule": null,
// Boolean indicating if is the first event in the series of recurring events.
"series_head": null,
// A natural language expression of how events occur in the series.
"series_natural_language": "Daily 5 times",
// Boolean indicating whether this has blackout date.
"blackout_date": true
}
```
**An AssignmentEvent object looks like:**
```js
{
// 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": "Write an essay. Whatever you want.",
// the context code of the (course) calendar this assignment belongs to
"context_code": "course_123",
// Current state of the assignment ('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)
"assignment": null,
// The list of AssignmentOverrides that apply to this event (See the Assignments
// API). This information is useful for determining which students or sections
// this assignment-due event applies to.
"assignment_overrides": null,
// Boolean indicating whether this has important dates.
"important_dates": true,
// An iCalendar RRULE for defining how events in a recurring event series
// repeat.
"rrule": "FREQ=DAILY;INTERVAL=1;COUNT=5",
// Trueif this is the first event in the series of recurring events.
"series_head": null,
// A natural language expression of how events occur in the series.
"series_natural_language": "Daily 5 times"
}
```
### [List calendar events](#method.calendar_events_api.index)
[CalendarEventsApiController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/calendar_events_api_controller.rb)
**`GET /api/v1/calendar_events`**
**Scope:** `url:GET|/api/v1/calendar_events`
Retrieve the paginated list of calendar events or assignments for the current user
**Request Parameters:**
| Parameter | Type | Description |
| ----------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | Defaults to “event”
Allowed values: event, assignment, sub\_assignment
|
| `start_date` | `Date` | Only return events since the start\_date (inclusive). Defaults to today. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ. |
| `end_date` | `Date` | Only return events before the end\_date (inclusive). Defaults to start\_date. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ. If end\_date is the same as start\_date, then only events on that day are returned. |
| `undated` | `boolean` | Defaults to false (dated events only). If true, only return undated events and ignore start\_date and end\_date. |
| `all_events` | `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[]` | `string` | List of context codes of courses, groups, users, or accounts 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 |
| `excludes[]` | `Array` | Array of attributes to exclude. Possible values are “description”, “child\_events” and “assignment” |
| `includes[]` | `Array` | Array of optional attributes to include. Possible values are “web\_conference” and “series\_natural\_language” |
| `important_dates` | `boolean` | Defaults to false. If true, only events with important dates set to true will be returned. |
| `blackout_date` | `boolean` | Defaults to false. If true, only events with blackout date set to true will be returned. |
Returns a list of [CalendarEvent](#calendarevent) objects.
### [List calendar events for a user](#method.calendar_events_api.user_index)
[CalendarEventsApiController#user\_index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/calendar_events_api_controller.rb)
**`GET /api/v1/users/:user_id/calendar_events`**
**Scope:** `url:GET|/api/v1/users/:user_id/calendar_events`
Retrieve the paginated list of calendar events or assignments for the specified user. To view calendar events for a user other than yourself, you must either be an observer of that user or an administrator.
**Request Parameters:**
| Parameter | Type | Description |
| ---------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `string` | Defaults to “event”
Allowed values: event, assignment
|
| `start_date` | `Date` | Only return events since the start\_date (inclusive). Defaults to today. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ. |
| `end_date` | `Date` | Only return events before the end\_date (inclusive). Defaults to start\_date. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ. If end\_date is the same as start\_date, then only events on that day are returned. |
| `undated` | `boolean` | Defaults to false (dated events only). If true, only return undated events and ignore start\_date and end\_date. |
| `all_events` | `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[]` | `string` | List of context codes of courses, groups, users, or accounts 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 |
| `excludes[]` | `Array` | Array of attributes to exclude. Possible values are “description”, “child\_events” and “assignment” |
| `submission_types[]` | `Array` | When type is “assignment”, specifies the allowable submission types for returned assignments. Ignored if type is not “assignment” or if exclude\_submission\_types is provided. |
| `exclude_submission_types[]` | `Array` | When type is “assignment”, specifies the submission types to be excluded from the returned assignments. Ignored if type is not “assignment”. |
| `includes[]` | `Array` | Array of optional attributes to include. Possible values are “web\_conference” and “series\_natural\_language” |
| `important_dates` | `boolean` | Defaults to false If true, only events with important dates set to true will be returned. |
| `blackout_date` | `boolean` | Defaults to false If true, only events with blackout date set to true will be returned. |
Returns a list of [CalendarEvent](#calendarevent) objects.
### [Create a calendar event](#method.calendar_events_api.create)
[CalendarEventsApiController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/calendar_events_api_controller.rb)
**`POST /api/v1/calendar_events`**
**Scope:** `url:POST|/api/v1/calendar_events`
Create and return a new calendar event
**Request Parameters:**
| Parameter | Type | Description |
| --------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `calendar_event[context_code]` | Required `string` | Context code of the course, group, user, or account whose calendar this event should be added to. |
| `calendar_event[title]` | `string` | Short title for the calendar event. |
| `calendar_event[description]` | `string` | Longer HTML description of the event. |
| `calendar_event[start_at]` | `DateTime` | Start date/time of the event. |
| `calendar_event[end_at]` | `DateTime` | End date/time of the event. |
| `calendar_event[location_name]` | `string` | Location name of the event. |
| `calendar_event[location_address]` | `string` | Location address |
| `calendar_event[time_zone_edited]` | `string` | Time zone of the user editing the event. Allowed time zones are [IANA time zones](http://www.iana.org/time-zones) or friendlier [Ruby on Rails time zones](http://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html). |
| `calendar_event[all_day]` | `boolean` | When true event is considered to span the whole day and times are ignored. |
| `calendar_event[child_event_data][X][start_at]` | `DateTime` | 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]` | `DateTime` | Section-level end time(s) if this is a course event. |
| `calendar_event[child_event_data][X][context_code]` | `string` | Context code(s) corresponding to the section-level start and end time(s). |
| `calendar_event[duplicate][count]` | `number` | Number of times to copy/duplicate the event. Count cannot exceed 200. |
| `calendar_event[duplicate][interval]` | `number` | Defaults to 1 if duplicate `count` is set. The interval between the duplicated events. |
| `calendar_event[duplicate][frequency]` | `string` | Defaults to “weekly”. The frequency at which to duplicate the event
Allowed values: daily, weekly, monthly
|
| `calendar_event[duplicate][append_iterator]` | `boolean` | Defaults to false. If set to `true`, an increasing counter number will be appended to the event title when the event is duplicated. (e.g. Event 1, Event 2, Event 3, etc) |
| `calendar_event[rrule]` | `string` | The recurrence rule to create a series of recurring events. Its value is the [iCalendar RRULE](https://icalendar.org/iCalendar-RFC-5545/3-8-5-3-recurrence-rule.html) defining how the event repeats. Unending series not supported. |
| `calendar_event[blackout_date]` | `boolean` | If the blackout\_date is true, this event represents a holiday or some other special day that does not count in course pacing. |
**Example Request:**
```bash
curl 'https://