Microsoft Exchange Events API

openapi: 3.2.0
info:
  title: Microsoft Exchange Microsoft Graph Calendar Events API
  description: Manage calendar events, meetings, and scheduling for Exchange Online users through the Microsoft Graph API. Provides endpoints for creating, updating, and deleting events, managing attendees, handling recurring meetings, finding meeting times, and getting free/busy schedules. Supports both user calendars and Microsoft 365 group calendars.
  version: 1.0.0
  contact:
    name: Microsoft Support
    url: https://support.microsoft.com
    email: support@microsoft.com
  license:
    name: Microsoft API License
    url: https://www.microsoft.com/en-us/legal/terms-of-use
  x-date-modified: '2026-03-04'
servers:
- url: https://graph.microsoft.com/v1.0
  description: Microsoft Graph v1.0 production endpoint
security:
- oauth2: []
tags:
- name: Events
  description: Operations for managing calendar events
paths:
  /me/events:
    get:
      operationId: listEvents
      summary: Microsoft Exchange List events
      description: Retrieve a list of event objects in the user's mailbox. The list contains single-instance meetings and series masters. Supports OData query parameters to filter, order, and page results.
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/TopParam'
      - $ref: '#/components/parameters/SkipParam'
      - $ref: '#/components/parameters/SelectParam'
      - $ref: '#/components/parameters/FilterParam'
      - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Successfully retrieved events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventCollectionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createEvent
      summary: Microsoft Exchange Create event
      description: Create a new event in the user's default calendar or specified calendar. Supports creating single-instance and recurring events, and events with online meeting information.
      tags:
      - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
      responses:
        '201':
          description: Successfully created event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /me/events/{event-id}:
    get:
      operationId: getEvent
      summary: Microsoft Exchange Get event
      description: Get the properties and relationships of an event object. Returns the event details including attendees, location, recurrence, and online meeting information.
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/EventIdParam'
      - $ref: '#/components/parameters/SelectParam'
      responses:
        '200':
          description: Successfully retrieved event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateEvent
      summary: Microsoft Exchange Update event
      description: Update the properties of an event object. When updating the start or end time zones, use the list of supported time zones.
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/EventIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
      responses:
        '200':
          description: Successfully updated event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteEvent
      summary: Microsoft Exchange Delete event
      description: Delete an event from the user's calendar. If the event is a meeting and the user is the organizer, a cancellation message is sent to all attendees.
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/EventIdParam'
      responses:
        '204':
          description: Successfully deleted event
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /me/events/{event-id}/accept:
    post:
      operationId: acceptEvent
      summary: Microsoft Exchange Accept event
      description: Accept the specified event in a user calendar. Optionally sends a response to the organizer indicating the user has accepted.
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/EventIdParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                comment:
                  type: string
                  description: A comment to include in the acceptance response
                sendResponse:
                  type: boolean
                  description: Whether to send a response to the organizer
                  default: true
      responses:
        '202':
          description: Event accepted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /me/events/{event-id}/tentativelyAccept:
    post:
      operationId: tentativelyAcceptEvent
      summary: Microsoft Exchange Tentatively accept event
      description: Tentatively accept the specified event in a user calendar.
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/EventIdParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                comment:
                  type: string
                  description: A comment to include in the response
                sendResponse:
                  type: boolean
                  description: Whether to send a response to the organizer
                  default: true
                proposedNewTime:
                  $ref: '#/components/schemas/TimeSlot'
      responses:
        '202':
          description: Event tentatively accepted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /me/events/{event-id}/decline:
    post:
      operationId: declineEvent
      summary: Microsoft Exchange Decline event
      description: Decline invitation to the specified event in a user calendar.
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/EventIdParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                comment:
                  type: string
                  description: A comment to include in the decline response
                sendResponse:
                  type: boolean
                  description: Whether to send a response to the organizer
                  default: true
                proposedNewTime:
                  $ref: '#/components/schemas/TimeSlot'
      responses:
        '202':
          description: Event declined
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /me/events/{event-id}/cancel:
    post:
      operationId: cancelEvent
      summary: Microsoft Exchange Cancel event
      description: Send a cancellation message from the organizer to all the attendees and cancel the specified meeting. Only the organizer can cancel a meeting.
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/EventIdParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                comment:
                  type: string
                  description: A comment about the cancellation
      responses:
        '202':
          description: Event cancelled and cancellation messages sent
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /me/events/{event-id}/forward:
    post:
      operationId: forwardEvent
      summary: Microsoft Exchange Forward event
      description: Forward a meeting request to a new recipient. The organizer or attendee forwards the meeting request to a new recipient.
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/EventIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                toRecipients:
                  type: array
                  items:
                    $ref: '#/components/schemas/Recipient'
                  description: The recipients to forward the event to
                comment:
                  type: string
                  description: A comment to include with the forwarded event
              required:
              - toRecipients
      responses:
        '202':
          description: Event forwarded
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /me/events/{event-id}/instances:
    get:
      operationId: listEventInstances
      summary: Microsoft Exchange List event instances
      description: Get the occurrences of a recurring series within a specified time range. If the event is a seriesMaster type, this returns the occurrences and exceptions of that series.
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/EventIdParam'
      - name: startDateTime
        in: query
        required: true
        description: The start date and time of the time range in ISO 8601 format
        schema:
          type: string
          format: date-time
      - name: endDateTime
        in: query
        required: true
        description: The end date and time of the time range in ISO 8601 format
        schema:
          type: string
          format: date-time
      - $ref: '#/components/parameters/TopParam'
      - $ref: '#/components/parameters/SkipParam'
      responses:
        '200':
          description: Successfully retrieved event instances
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventCollectionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /me/events/{event-id}/attachments:
    get:
      operationId: listEventAttachments
      summary: Microsoft Exchange List event attachments
      description: Retrieve a list of attachment objects attached to an event.
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/EventIdParam'
      - $ref: '#/components/parameters/SelectParam'
      responses:
        '200':
          description: Successfully retrieved attachments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttachmentCollectionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: addEventAttachment
      summary: Microsoft Exchange Add event attachment
      description: Add a file, item, or reference attachment to an event. This operation limits the size of the attachment to 3 MB.
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/EventIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Attachment'
      responses:
        '201':
          description: Successfully added attachment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Attachment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /me/calendarView:
    get:
      operationId: listCalendarView
      summary: Microsoft Exchange List calendar view
      description: Get the occurrences, exceptions, and single instances of events in a calendar view defined by a time range, from the user's primary calendar. Recurring events are expanded into their occurrences within the time range.
      tags:
      - Events
      parameters:
      - name: startDateTime
        in: query
        required: true
        description: The start date and time of the time range in ISO 8601 format
        schema:
          type: string
          format: date-time
      - name: endDateTime
        in: query
        required: true
        description: The end date and time of the time range in ISO 8601 format
        schema:
          type: string
          format: date-time
      - $ref: '#/components/parameters/TopParam'
      - $ref: '#/components/parameters/SkipParam'
      - $ref: '#/components/parameters/SelectParam'
      - $ref: '#/components/parameters/FilterParam'
      responses:
        '200':
          description: Successfully retrieved calendar view
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventCollectionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /me/calendars/{calendar-id}/events:
    get:
      operationId: listCalendarEvents
      summary: Microsoft Exchange List events in calendar
      description: Retrieve a list of events in a specified calendar. The list contains single-instance meetings and series masters.
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/CalendarIdParam'
      - $ref: '#/components/parameters/TopParam'
      - $ref: '#/components/parameters/SkipParam'
      - $ref: '#/components/parameters/SelectParam'
      - $ref: '#/components/parameters/FilterParam'
      - $ref: '#/components/parameters/OrderByParam'
      responses:
        '200':
          description: Successfully retrieved events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventCollectionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createEventInCalendar
      summary: Microsoft Exchange Create event in calendar
      description: Create a new event in the specified calendar.
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/CalendarIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Event'
      responses:
        '201':
          description: Successfully created event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    EmailAddress:
      type: object
      description: The name and email address of a person
      properties:
        name:
          type: string
          description: The display name
        address:
          type: string
          format: email
          description: The email address
    PhysicalAddress:
      type: object
      description: Physical street address
      properties:
        street:
          type: string
        city:
          type: string
        state:
          type: string
        countryOrRegion:
          type: string
        postalCode:
          type: string
    DateTimeTimeZone:
      type: object
      description: Describes a date, time, and time zone
      properties:
        dateTime:
          type: string
          description: A date and time in ISO 8601 format
        timeZone:
          type: string
          description: A time zone name (e.g. Pacific Standard Time)
    OutlookGeoCoordinates:
      type: object
      description: Geographic coordinates and elevation of a location
      properties:
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
        accuracy:
          type: number
          format: double
        altitude:
          type: number
          format: double
        altitudeAccuracy:
          type: number
          format: double
    TimeSlot:
      type: object
      description: A time period
      properties:
        start:
          $ref: '#/components/schemas/DateTimeTimeZone'
        end:
          $ref: '#/components/schemas/DateTimeTimeZone'
    Attachment:
      type: object
      description: A file or item attached to an event
      properties:
        '@odata.type':
          type: string
        id:
          type: string
          readOnly: true
        name:
          type: string
        contentType:
          type: string
        size:
          type: integer
          readOnly: true
        isInline:
          type: boolean
        lastModifiedDateTime:
          type: string
          format: date-time
          readOnly: true
        contentBytes:
          type: string
          format: byte
    Location:
      type: object
      description: Represents location information for an event
      properties:
        displayName:
          type: string
          description: The name associated with the location
        locationType:
          type: string
          enum:
          - default
          - conferenceRoom
          - homeAddress
          - businessAddress
          - geoCoordinates
          - streetAddress
          - hotel
          - restaurant
          - localBusiness
          - postalAddress
          description: The type of location
        locationUri:
          type: string
          description: URI representing the location
        locationEmailAddress:
          type: string
          description: Email address of the location
        address:
          $ref: '#/components/schemas/PhysicalAddress'
        coordinates:
          $ref: '#/components/schemas/OutlookGeoCoordinates'
        uniqueId:
          type: string
          description: An internal identifier for the location
        uniqueIdType:
          type: string
          enum:
          - unknown
          - locationStore
          - directory
          - private
          - bing
    Recipient:
      type: object
      description: Represents the recipient of an event
      properties:
        emailAddress:
          $ref: '#/components/schemas/EmailAddress'
    ODataError:
      type: object
      description: OData error response
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            innerError:
              type: object
              properties:
                request-id:
                  type: string
                date:
                  type: string
                  format: date-time
    PatternedRecurrence:
      type: object
      description: The recurrence pattern and range for an event
      properties:
        pattern:
          $ref: '#/components/schemas/RecurrencePattern'
        range:
          $ref: '#/components/schemas/RecurrenceRange'
    ItemBody:
      type: object
      description: Represents the body content of an event
      properties:
        contentType:
          type: string
          enum:
          - text
          - html
          description: The type of the content
        content:
          type: string
          description: The content of the item body
    RecurrenceRange:
      type: object
      description: The duration of a recurrence
      properties:
        type:
          type: string
          enum:
          - endDate
          - noEnd
          - numbered
        startDate:
          type: string
          format: date
          description: The start date of the recurring series
        endDate:
          type: string
          format: date
          description: The end date of the recurring series
        recurrenceTimeZone:
          type: string
          description: Time zone for the start and end dates
        numberOfOccurrences:
          type: integer
          description: Number of times to repeat the event
    RecurrencePattern:
      type: object
      description: The frequency of an event recurrence
      properties:
        type:
          type: string
          enum:
          - daily
          - weekly
          - absoluteMonthly
          - relativeMonthly
          - absoluteYearly
          - relativeYearly
        interval:
          type: integer
          description: The number of units between occurrences
        month:
          type: integer
          description: The month in which the event occurs (1-12)
        dayOfMonth:
          type: integer
          description: The day of the month on which the event occurs
        daysOfWeek:
          type: array
          items:
            type: string
            enum:
            - sunday
            - monday
            - tuesday
            - wednesday
            - thursday
            - friday
            - saturday
        firstDayOfWeek:
          type: string
          enum:
          - sunday
          - monday
          - tuesday
          - wednesday
          - thursday
          - friday
          - saturday
        index:
          type: string
          enum:
          - first
          - second
          - third
          - fourth
          - last
    AttachmentCollectionResponse:
      type: object
      description: Collection of attachments
      properties:
        '@odata.context':
          type: string
        value:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
    Event:
      type: object
      description: An event in a user calendar or the default calendar of a Microsoft 365 group
      properties:
        id:
          type: string
          readOnly: true
          description: Unique identifier for the event
        subject:
          type: string
          description: The text of the event's subject line
        body:
          $ref: '#/components/schemas/ItemBody'
        bodyPreview:
          type: string
          readOnly: true
          description: The preview of the message associated with the event in text format
        start:
          $ref: '#/components/schemas/DateTimeTimeZone'
        end:
          $ref: '#/components/schemas/DateTimeTimeZone'
        location:
          $ref: '#/components/schemas/Location'
        locations:
          type: array
          items:
            $ref: '#/components/schemas/Location'
          description: The locations where the event is held or attended from
        attendees:
          type: array
          items:
            $ref: '#/components/schemas/Attendee'
          description: The collection of attendees for the event
        organizer:
          $ref: '#/components/schemas/Recipient'
        isAllDay:
          type: boolean
          description: Whether the event lasts all day
        isCancelled:
          type: boolean
          readOnly: true
          description: Whether the event has been canceled
        isDraft:
          type: boolean
          readOnly: true
          description: Whether the user has updated the event but not sent updates to attendees
        isOnlineMeeting:
          type: boolean
          description: Whether this event has online meeting information
        isOrganizer:
          type: boolean
          readOnly: true
          description: Whether the calendar owner is the organizer
        isReminderOn:
          type: boolean
          description: Whether an alert is set to remind the user
        onlineMeeting:
          $ref: '#/components/schemas/OnlineMeetingInfo'
        onlineMeetingProvider:
          type: string
          enum:
          - unknown
          - teamsForBusiness
          - skypeForBusiness
          - skypeForConsumer
          description: The online meeting service provider
        onlineMeetingUrl:
          type: string
          readOnly: true
          description: URL for an online meeting
        recurrence:
          $ref: '#/components/schemas/PatternedRecurrence'
        reminderMinutesBeforeStart:
          type: integer
          description: Minutes before start time that the reminder alert occurs
        responseRequested:
          type: boolean
          description: Whether the organizer requests invitees to send a response
        responseStatus:
          $ref: '#/components/schemas/ResponseStatus'
        sensitivity:
          type: string
          enum:
          - normal
          - personal
          - private
          - confidential
          description: The event sensitivity level
        seriesMasterId:
          type: string
          readOnly: true
          description: The ID for the recurring series master if this is part of a series
        showAs:
          type: string
          enum:
          - free
          - tentative
          - busy
          - oof
          - workingElsewhere
          - unknown
          description: The status to show for the event
        type:
          type: string
          readOnly: true
          enum:
          - singleInstance
          - occurrence
          - exception
          - seriesMaster
          description: The event type
        importance:
          type: string
          enum:
          - low
          - normal
          - high
          description: The importance of the event
        hasAttachments:
          type: boolean
          readOnly: true
          description: Whether the event has attachments
        categories:
          type: array
          items:
            type: string
          description: The categories associated with the event
        allowNewTimeProposals:
          type: boolean
          description: Whether the organizer allows invitees to propose new times
        iCalUId:
          type: string
          readOnly: true
          description: A unique identifier for an event across calendars
        changeKey:
          type: string
          readOnly: true
          description: Identifies the version of the event
        createdDateTime:
          type: string
          format: date-time
          readOnly: true
          description: The date and time the event was created
        lastModifiedDateTime:
          type: string
          format: date-time
          readOnly: true
          description: The date and time the event was last changed
        webLink:
          type: string
          format: uri
          readOnly: true
          description: The URL to open the event in Outlook on the web
        transactionId:
          type: string
          description: Custom identifier for client retries to avoid duplicate creation
        hideAttendees:
          type: boolean
          description: When true, each attendee only sees themselves in the meeting request
        originalStartTimeZone:
          type: string
          description: The start time zone set when the event was created
        originalEndTimeZone:
          type: string
          description: The end time zone set when the event was created
    OnlineMeetingInfo:
      type: object
      description: Details for joining an online meeting
      properties:
        joinUrl:
          type: string
          format: uri
          description: The URL to join the online meeting
        conferenceId:
          type: string
          description: The ID of the conference
        tollNumber:
          type: string
          description: The toll number for the online meeting
        tollFreeNumbers:
          type: array
          items:
            type: string
          description: Toll-free numbers for the online meeting
        quickDial:
          type: string
          description: Quick dial number for the online meeting
        phones:
          type: array
          items:
            type: object
            properties:
              number:
                type: string
              type:
                type: string
                enum:
                - unknown
                - home
                - business
                - mobile
                - other
                - pager
    ResponseStatus:
      type: object
      description: Response status of an attendee or organizer
      properties:
        response:
          type: string
          enum:
          - none
          - organizer
          - tentativelyAccepted
          - accepted
          - declined
          - notResponded
          description: The response type
        time:
          type: string
          format: date-time
          description: The date and time that the response was returned
    EventCollectionResponse:
      type: object
      description: Collection of events
      properties:
        '@odata.context':
          type: string
        '@odata.nextLink':
          type: string
          format: uri
        value:
          type: array
          items:
            $ref: '#/components/schemas/Event'
    Attendee:
      type: object
      description: An event attendee with response status
      properties:
        emailAddress:
          $ref: '#/components/schemas/EmailAddress'
        type:
          type: string
          enum:
          - required
          - optional
          - resource
          description: The type of attendee
        status:
          $ref: '#/components/schemas/ResponseStatus'
        proposedNewTime:
          $ref: '#/components/schemas/TimeSlot'
  parameters:
    CalendarIdParam:
      name: calendar-id
      in: path
      required: true
      description: The unique identifier of the calendar
      schema:
        type: string
    TopParam:
      name: $top
      in: query
      description: The number of items to return
      schema:
        type: integer
        minimum: 1
    EventIdParam:
      name: event-id
      in: path
      required: true
      description: The unique identifier of the event
      schema:
        type: string
    OrderByParam:
      name: $orderby
      in: query
      description: Comma-separated list of properties to sort by
      schema:
        type: string
    SelectParam:
      name: $select
      in: query
      description: Comma-separated list of properties to include in the response
      schema:
        type: string
    SkipParam:
      name: $skip
      in: query
      description: The number of items to skip
      schema:
        type: integer
        minimum: 0
    FilterParam:
      name: $filter
      in: query
      description: OData filter expression
      schema:
        type: string
  responses:
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataError'
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization with Microsoft identity platform
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
          scopes:
            Calendars.Read: Read user calendars
            Calendars.ReadWrite: 

# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-exchange/refs/heads/main/openapi/microsoft-exchange-events-api-openapi.yml