Microsoft Graph-compatible Calendar API for Purple Suite. When a request carries a caller identity (X-PS-Impersonate-User header, or the instance's default MCP user), Outlook-style permissions apply: `private` events are masked on reads unless the caller is the organizer or an attendee, and event PATCH/DELETE/cancel are organizer-only (403 ErrorAccessDenied otherwise; attendees respond via accept/decline/tentativelyAccept). Requests without a caller identity are unrestricted.
Microsoft Graph-compatible Calendar API for Purple Suite. When a request carries a caller identity (X-PS-Impersonate-User header, or the instance's default MCP user), Outlook-style permissions apply: `private` events are masked on reads unless the caller is the organizer or an attendee, and event PATCH/DELETE/cancel are organizer-only (403 ErrorAccessDenied otherwise; attendees respond via accept/decline/tentativelyAccept). Requests without a caller identity are unrestricted.
Operations
GET /events
List Purple Calendar events
Every meeting and appointment stored in Purple Calendar, across all users, as Microsoft Graph-shaped Event objects in a `value` array. This op only pages with _top/_skip — when the question is about a person or a date range, prefer the calendarView tools, which take startDateTime/endDateTime.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "List Purple Calendar events",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"$ref": "#/components/parameters/Top"
},
{
"$ref": "#/components/parameters/Skip"
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"default": 50
},
"description": "Alias for $top — max items per page (default 50)"
}
],
"responses": {
"200": {
"description": "Paginated list of events",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Event"
}
},
"@odata.nextLink": {
"type": "string",
"nullable": true,
"description": "OData next-page link, absent on the last page"
}
}
}
}
}
}
},
"description": "Every meeting and appointment stored in Purple Calendar, across all users, as Microsoft Graph-shaped Event objects in a `value` array. This op only pages with _top/_skip — when the question is about a person or a date range, prefer the calendarView tools, which take startDateTime/endDateTime."
}
POST /events
Schedule a calendar event
Creates a meeting in Purple Calendar — subject, start/end as DateTimeTimeZone, attendees, location or room, and optional recurrence (which makes it a series master). It does not check availability: use the free/busy schedule or findMeetingTimes tools first if the time isn't already agreed.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Schedule a calendar event",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Event"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Event"
}
}
}
}
},
"description": "Creates a meeting in Purple Calendar — subject, start/end as DateTimeTimeZone, attendees, location or room, and optional recurrence (which makes it a series master). It does not check availability: use the free/busy schedule or findMeetingTimes tools first if the time isn't already agreed."
}
GET /events/{id}
Get event
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Get event",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Event"
}
}
}
},
"404": {
"description": "Not found"
}
}
}
PATCH /events/{id}
Update a calendar event
Partially updates an existing Purple Calendar event — reschedule its times, change the subject/body, or amend the attendee list. To call a meeting off, prefer the cancel tool, which keeps the record and marks it isCancelled.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Update a calendar event",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Fields to update (partial)",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Event"
}
}
}
},
"responses": {
"200": {
"description": "Updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Event"
}
}
}
},
"404": {
"description": "Not found"
}
},
"description": "Partially updates an existing Purple Calendar event — reschedule its times, change the subject/body, or amend the attendee list. To call a meeting off, prefer the cancel tool, which keeps the record and marks it isCancelled."
}
DELETE /events/{id}
Delete a calendar event
Permanently removes an event from Purple Calendar. Destructive and irreversible, and it leaves attendees no cancellation record — use the cancel tool instead whenever a meeting is simply called off.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Delete a calendar event",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No content"
},
"404": {
"description": "Not found"
}
},
"description": "Permanently removes an event from Purple Calendar. Destructive and irreversible, and it leaves attendees no cancellation record — use the cancel tool instead whenever a meeting is simply called off."
}
POST /users/{email}/events/{id}/accept
Accept event invitation
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Accept event invitation",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "email",
"required": true,
"schema": {
"type": "string",
"format": "email"
},
"description": "User email — or the literal \"me\" to act as the current impersonated user (the X-PS-Impersonate-User header, or the instance's configured default MCP user)."
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"comment": {
"type": "string",
"example": "Looking forward to it!"
},
"sendResponse": {
"type": "boolean",
"example": true
}
}
}
}
}
},
"responses": {
"202": {
"description": "Accepted"
},
"404": {
"description": "Not found"
}
}
}
POST /users/{email}/events/{id}/decline
Decline event invitation
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Decline event invitation",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "email",
"required": true,
"schema": {
"type": "string",
"format": "email"
},
"description": "User email — or the literal \"me\" to act as the current impersonated user (the X-PS-Impersonate-User header, or the instance's configured default MCP user)."
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"comment": {
"type": "string",
"example": "Conflict — will catch the recording."
},
"sendResponse": {
"type": "boolean",
"example": true
},
"proposedNewTime": {
"type": "object",
"nullable": true
}
}
}
}
}
},
"responses": {
"202": {
"description": "Accepted"
},
"404": {
"description": "Not found"
}
}
}
POST /users/{email}/events/{id}/tentativelyAccept
Tentatively accept event invitation
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Tentatively accept event invitation",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "email",
"required": true,
"schema": {
"type": "string",
"format": "email"
},
"description": "User email — or the literal \"me\" to act as the current impersonated user (the X-PS-Impersonate-User header, or the instance's configured default MCP user)."
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"comment": {
"type": "string",
"example": "Will try to join."
},
"sendResponse": {
"type": "boolean",
"example": true
},
"proposedNewTime": {
"type": "object",
"nullable": true
}
}
}
}
}
},
"responses": {
"202": {
"description": "Accepted"
},
"404": {
"description": "Not found"
}
}
}
POST /events/{id}/cancel
Cancel event (bare path alias)
Cancels the event (sets isCancelled: true, showAs: free). Does not delete the event. Cancelling a seriesMaster cancels the whole series; cancelling a generated occurrence (id in the form seriesMasterId_yyyymmdd) cancels just that date by materializing an exception. Also available at /users/{email}/events/{id}/cancel.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Cancel event (bare path alias)",
"description": "Cancels the event (sets isCancelled: true, showAs: free). Does not delete the event. Cancelling a seriesMaster cancels the whole series; cancelling a generated occurrence (id in the form seriesMasterId_yyyymmdd) cancels just that date by materializing an exception. Also available at /users/{email}/events/{id}/cancel.",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"comment": {
"type": "string",
"description": "Cancellation message",
"example": "Meeting is no longer needed."
}
}
}
}
}
},
"responses": {
"202": {
"description": "Accepted"
},
"404": {
"description": "Not found"
}
}
}
POST /users/{email}/events/{id}/cancel
Cancel event (user-scoped path)
Cancels the event (sets isCancelled: true, showAs: free). Does not delete the event. Cancelling a seriesMaster cancels the whole series; cancelling a generated occurrence (id in the form seriesMasterId_yyyymmdd) cancels just that date by materializing an exception.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Cancel event (user-scoped path)",
"description": "Cancels the event (sets isCancelled: true, showAs: free). Does not delete the event. Cancelling a seriesMaster cancels the whole series; cancelling a generated occurrence (id in the form seriesMasterId_yyyymmdd) cancels just that date by materializing an exception.",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "email",
"required": true,
"schema": {
"type": "string",
"format": "email"
},
"description": "User email — or the literal \"me\" to act as the current impersonated user (the X-PS-Impersonate-User header, or the instance's configured default MCP user)."
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"comment": {
"type": "string",
"description": "Cancellation message",
"example": "Meeting is no longer needed."
}
}
}
}
}
},
"responses": {
"202": {
"description": "Accepted"
},
"404": {
"description": "Not found"
}
}
}
GET /events/{id}/instances
List occurrences of an event series (bare path alias)
Expands a seriesMaster into its occurrence instances within the time window (stored exceptions included). For a non-recurring event, returns the event itself when it intersects the window. Also available at /users/{email}/events/{id}/instances.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "List occurrences of an event series (bare path alias)",
"description": "Expands a seriesMaster into its occurrence instances within the time window (stored exceptions included). For a non-recurring event, returns the event itself when it intersects the window. Also available at /users/{email}/events/{id}/instances.",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "startDateTime",
"required": true,
"schema": {
"type": "string",
"format": "date-time"
},
"example": "2026-06-01T00:00:00Z"
},
{
"in": "query",
"name": "endDateTime",
"required": true,
"schema": {
"type": "string",
"format": "date-time"
},
"example": "2026-06-30T23:59:59Z"
}
],
"responses": {
"200": {
"description": "Occurrences in range",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Event"
}
}
}
}
}
}
},
"400": {
"description": "startDateTime and endDateTime are required"
},
"404": {
"description": "Not found"
}
}
}
GET /users/{email}/events/{id}/instances
List occurrences of an event series (user-scoped path)
Expands a seriesMaster into its occurrence instances within the time window (stored exceptions included). For a non-recurring event, returns the event itself when it intersects the window.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "List occurrences of an event series (user-scoped path)",
"description": "Expands a seriesMaster into its occurrence instances within the time window (stored exceptions included). For a non-recurring event, returns the event itself when it intersects the window.",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "email",
"required": true,
"schema": {
"type": "string",
"format": "email"
},
"description": "User email — or the literal \"me\" to act as the current impersonated user (the X-PS-Impersonate-User header, or the instance's configured default MCP user)."
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "startDateTime",
"required": true,
"schema": {
"type": "string",
"format": "date-time"
},
"example": "2026-06-01T00:00:00Z"
},
{
"in": "query",
"name": "endDateTime",
"required": true,
"schema": {
"type": "string",
"format": "date-time"
},
"example": "2026-06-30T23:59:59Z"
}
],
"responses": {
"200": {
"description": "Occurrences in range",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Event"
}
}
}
}
}
}
},
"400": {
"description": "startDateTime and endDateTime are required"
},
"404": {
"description": "Not found"
}
}
}
POST /findMeetingTimes
Find meeting time suggestions (bare path)
Suggests meeting times when all attendees are available, based on their calendar events. Also available at /users/{email}/findMeetingTimes.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Find meeting time suggestions (bare path)",
"description": "Suggests meeting times when all attendees are available, based on their calendar events. Also available at /users/{email}/findMeetingTimes.",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "header",
"name": "Prefer",
"schema": {
"type": "string"
},
"description": "Optional response timezone override, e.g. `outlook.timezone=\"Pacific Standard Time\"`",
"example": "outlook.timezone=\"Pacific Standard Time\""
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"attendees": {
"type": "array",
"items": {
"type": "object",
"properties": {
"emailAddress": {
"$ref": "#/components/schemas/EmailAddress"
},
"type": {
"type": "string",
"enum": [
"required",
"optional",
"resource"
]
}
}
},
"example": [
{
"emailAddress": {
"address": "bob.martinez@acme.com",
"name": "Bob Martinez"
},
"type": "required"
}
]
},
"timeConstraint": {
"type": "object",
"properties": {
"activityDomain": {
"type": "string",
"enum": [
"work",
"personal",
"unrestricted"
],
"example": "work"
},
"timeSlots": {
"type": "array",
"items": {
"type": "object",
"properties": {
"start": {
"$ref": "#/components/schemas/DateTimeTimeZone"
},
"end": {
"$ref": "#/components/schemas/DateTimeTimeZone"
}
}
},
"example": [
{
"start": {
"dateTime": "2026-06-02T08:00:00.0000000",
"timeZone": "Pacific Standard Time"
},
"end": {
"dateTime": "2026-06-02T17:00:00.0000000",
"timeZone": "Pacific Standard Time"
}
}
]
}
}
},
"meetingDuration": {
"type": "string",
"description": "ISO 8601 duration, e.g. PT1H, PT30M",
"default": "PT30M",
"example": "PT30M"
},
"maxCandidates": {
"type": "integer",
"default": 5,
"example": 5
},
"minimumAttendeePercentage": {
"type": "number",
"default": 50,
"example": 50
},
"isOrganizerOptional": {
"type": "boolean",
"default": false,
"example": false
},
"returnSuggestionReasons": {
"type": "boolean",
"default": false,
"example": false
}
}
}
}
}
},
"responses": {
"200": {
"description": "Meeting time suggestions",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"emptySuggestionsReason": {
"type": "string",
"example": ""
},
"meetingTimeSuggestions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"confidence": {
"type": "number",
"example": 100
},
"order": {
"type": "integer",
"example": 1
},
"organizerAvailability": {
"type": "string",
"example": "free"
},
"suggestionReason": {
"type": "string"
},
"attendeeAvailability": {
"type": "array",
"items": {
"type": "object",
"properties": {
"attendee": {
"type": "object"
},
"availability": {
"type": "string"
}
}
}
},
"locations": {
"type": "array",
"items": {
"type": "object"
}
},
"meetingTimeSlot": {
"type": "object",
"properties": {
"start": {
"$ref": "#/components/schemas/DateTimeTimeZone"
},
"end": {
"$ref": "#/components/schemas/DateTimeTimeZone"
}
}
}
}
}
}
}
}
}
}
}
}
}
POST /users/{email}/findMeetingTimes
Find meeting time suggestions (user-scoped path)
Organizer-scoped variant. Uses the organizer's timezone from their mailboxSettings for activityDomain filtering.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Find meeting time suggestions (user-scoped path)",
"description": "Organizer-scoped variant. Uses the organizer's timezone from their mailboxSettings for activityDomain filtering.",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "email",
"required": true,
"schema": {
"type": "string",
"format": "email"
},
"description": "User email — or the literal \"me\" to act as the current impersonated user (the X-PS-Impersonate-User header, or the instance's configured default MCP user)."
},
{
"in": "header",
"name": "Prefer",
"schema": {
"type": "string"
},
"description": "Optional response timezone override, e.g. `outlook.timezone=\"Pacific Standard Time\"`",
"example": "outlook.timezone=\"Pacific Standard Time\""
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"attendees": {
"type": "array",
"items": {
"type": "object",
"properties": {
"emailAddress": {
"$ref": "#/components/schemas/EmailAddress"
},
"type": {
"type": "string",
"enum": [
"required",
"optional",
"resource"
]
}
}
},
"example": [
{
"emailAddress": {
"address": "bob.martinez@acme.com",
"name": "Bob Martinez"
},
"type": "required"
}
]
},
"timeConstraint": {
"type": "object",
"properties": {
"activityDomain": {
"type": "string",
"enum": [
"work",
"personal",
"unrestricted"
],
"example": "work"
},
"timeSlots": {
"type": "array",
"items": {
"type": "object",
"properties": {
"start": {
"$ref": "#/components/schemas/DateTimeTimeZone"
},
"end": {
"$ref": "#/components/schemas/DateTimeTimeZone"
}
}
},
"example": [
{
"start": {
"dateTime": "2026-06-02T08:00:00.0000000",
"timeZone": "Pacific Standard Time"
},
"end": {
"dateTime": "2026-06-02T17:00:00.0000000",
"timeZone": "Pacific Standard Time"
}
}
]
}
}
},
"meetingDuration": {
"type": "string",
"description": "ISO 8601 duration, e.g. PT1H, PT30M",
"default": "PT30M",
"example": "PT30M"
},
"maxCandidates": {
"type": "integer",
"default": 5,
"example": 5
},
"minimumAttendeePercentage": {
"type": "number",
"default": 50,
"example": 50
},
"isOrganizerOptional": {
"type": "boolean",
"default": false,
"example": false
},
"returnSuggestionReasons": {
"type": "boolean",
"default": false,
"example": false
}
}
}
}
}
},
"responses": {
"200": {
"description": "Meeting time suggestions",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"emptySuggestionsReason": {
"type": "string",
"example": ""
},
"meetingTimeSuggestions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"confidence": {
"type": "number",
"example": 100
},
"order": {
"type": "integer",
"example": 1
},
"organizerAvailability": {
"type": "string",
"example": "free"
},
"suggestionReason": {
"type": "string"
},
"attendeeAvailability": {
"type": "array",
"items": {
"type": "object",
"properties": {
"attendee": {
"type": "object"
},
"availability": {
"type": "string"
}
}
}
},
"locations": {
"type": "array",
"items": {
"type": "object"
}
},
"meetingTimeSlot": {
"type": "object",
"properties": {
"start": {
"$ref": "#/components/schemas/DateTimeTimeZone"
},
"end": {
"$ref": "#/components/schemas/DateTimeTimeZone"
}
}
}
}
}
}
}
}
}
}
}
}
}
GET /calendarView
Get calendar view — all events in time range
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Get calendar view — all events in time range",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "query",
"name": "startDateTime",
"required": true,
"schema": {
"type": "string",
"format": "date-time"
},
"example": "2026-06-02T00:00:00Z"
},
{
"in": "query",
"name": "endDateTime",
"required": true,
"schema": {
"type": "string",
"format": "date-time"
},
"example": "2026-06-06T23:59:59Z"
},
{
"$ref": "#/components/parameters/Top"
},
{
"$ref": "#/components/parameters/Skip"
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"default": 50
},
"description": "Alias for $top — max items per page (default 50)"
}
],
"responses": {
"200": {
"description": "Events in range",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Event"
}
},
"@odata.nextLink": {
"type": "string",
"nullable": true,
"description": "OData next-page link, absent on the last page"
}
}
}
}
}
},
"400": {
"description": "startDateTime and endDateTime are required"
}
}
}
GET /users/{email}/calendarView
Get calendar view for a specific user (events in time range)
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Get calendar view for a specific user (events in time range)",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "email",
"required": true,
"schema": {
"type": "string",
"format": "email"
},
"description": "User email — or the literal \"me\" to act as the current impersonated user (the X-PS-Impersonate-User header, or the instance's configured default MCP user)."
},
{
"in": "query",
"name": "startDateTime",
"required": true,
"schema": {
"type": "string",
"format": "date-time"
},
"example": "2026-06-02T00:00:00Z"
},
{
"in": "query",
"name": "endDateTime",
"required": true,
"schema": {
"type": "string",
"format": "date-time"
},
"example": "2026-06-06T23:59:59Z"
}
],
"responses": {
"200": {
"description": "User events in range",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Event"
}
}
}
}
}
}
},
"400": {
"description": "startDateTime and endDateTime are required"
}
}
}
GET /users/{email}/events
List all events for a specific user
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "List all events for a specific user",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "email",
"required": true,
"schema": {
"type": "string",
"format": "email"
},
"description": "User email — or the literal \"me\" to act as the current impersonated user (the X-PS-Impersonate-User header, or the instance's configured default MCP user)."
},
{
"$ref": "#/components/parameters/Top"
},
{
"$ref": "#/components/parameters/Skip"
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"default": 50
},
"description": "Alias for $top — max items per page (default 50)"
}
],
"responses": {
"200": {
"description": "User events",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Event"
}
},
"@odata.nextLink": {
"type": "string",
"nullable": true,
"description": "OData next-page link, absent on the last page"
}
}
}
}
}
}
}
}
POST /users/{email}/events
Create event (user-scoped path)
User-scoped twin of POST /events. Defaults the organizer to the resolved user when the body doesn't set one.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"x-mcp": false,
"summary": "Create event (user-scoped path)",
"description": "User-scoped twin of POST /events. Defaults the organizer to the resolved user when the body doesn't set one.",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "email",
"required": true,
"schema": {
"type": "string",
"format": "email"
},
"description": "User email — or the literal \"me\" to act as the current impersonated user (the X-PS-Impersonate-User header, or the instance's configured default MCP user)."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Event"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Event"
}
}
}
}
}
}
GET /users/{email}/events/{id}
Get event (user-scoped path)
User-scoped twin of GET /events/{id}.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"x-mcp": false,
"summary": "Get event (user-scoped path)",
"description": "User-scoped twin of GET /events/{id}.",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "email",
"required": true,
"schema": {
"type": "string",
"format": "email"
},
"description": "User email — or the literal \"me\" to act as the current impersonated user (the X-PS-Impersonate-User header, or the instance's configured default MCP user)."
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Event"
}
}
}
},
"404": {
"description": "Not found"
}
}
}
PATCH /users/{email}/events/{id}
Update event (user-scoped path)
User-scoped twin of PATCH /events/{id}.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"x-mcp": false,
"summary": "Update event (user-scoped path)",
"description": "User-scoped twin of PATCH /events/{id}.",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "email",
"required": true,
"schema": {
"type": "string",
"format": "email"
},
"description": "User email — or the literal \"me\" to act as the current impersonated user (the X-PS-Impersonate-User header, or the instance's configured default MCP user)."
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Fields to update (partial)",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Event"
}
}
}
},
"responses": {
"200": {
"description": "Updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Event"
}
}
}
},
"404": {
"description": "Not found"
}
}
}
DELETE /users/{email}/events/{id}
Delete event (user-scoped path)
User-scoped twin of DELETE /events/{id}.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"x-mcp": false,
"summary": "Delete event (user-scoped path)",
"description": "User-scoped twin of DELETE /events/{id}.",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "email",
"required": true,
"schema": {
"type": "string",
"format": "email"
},
"description": "User email — or the literal \"me\" to act as the current impersonated user (the X-PS-Impersonate-User header, or the instance's configured default MCP user)."
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No content"
},
"404": {
"description": "Not found"
}
}
}
GET /users/{email}/calendars
List all calendars (user-scoped alias — returns all instance calendars)
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"x-mcp": false,
"summary": "List all calendars (user-scoped alias — returns all instance calendars)",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "email",
"required": true,
"schema": {
"type": "string",
"format": "email"
},
"description": "User email — or the literal \"me\" to act as the current impersonated user (the X-PS-Impersonate-User header, or the instance's configured default MCP user)."
},
{
"$ref": "#/components/parameters/Top"
},
{
"$ref": "#/components/parameters/Skip"
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"default": 50
},
"description": "Alias for $top — max items per page (default 50)"
}
],
"responses": {
"200": {
"description": "Collection of calendars",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Calendar"
}
},
"@odata.nextLink": {
"type": "string",
"nullable": true,
"description": "OData next-page link, absent on the last page"
}
}
}
}
}
}
}
}
POST /users/{email}/calendars
Create calendar (user-scoped path)
User-scoped twin of POST /calendars. Defaults the owner to the resolved user when the body doesn't set one.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"x-mcp": false,
"summary": "Create calendar (user-scoped path)",
"description": "User-scoped twin of POST /calendars. Defaults the owner to the resolved user when the body doesn't set one.",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "email",
"required": true,
"schema": {
"type": "string",
"format": "email"
},
"description": "User email — or the literal \"me\" to act as the current impersonated user (the X-PS-Impersonate-User header, or the instance's configured default MCP user)."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Calendar"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Calendar"
}
}
}
}
}
}
GET /users/{email}/calendars/{id}
Get calendar (user-scoped path)
User-scoped twin of GET /calendars/{id}.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"x-mcp": false,
"summary": "Get calendar (user-scoped path)",
"description": "User-scoped twin of GET /calendars/{id}.",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "email",
"required": true,
"schema": {
"type": "string",
"format": "email"
},
"description": "User email — or the literal \"me\" to act as the current impersonated user (the X-PS-Impersonate-User header, or the instance's configured default MCP user)."
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Calendar"
}
}
}
},
"404": {
"description": "Not found"
}
}
}
PATCH /users/{email}/calendars/{id}
Update calendar (user-scoped path)
User-scoped twin of PATCH /calendars/{id}.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"x-mcp": false,
"summary": "Update calendar (user-scoped path)",
"description": "User-scoped twin of PATCH /calendars/{id}.",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "email",
"required": true,
"schema": {
"type": "string",
"format": "email"
},
"description": "User email — or the literal \"me\" to act as the current impersonated user (the X-PS-Impersonate-User header, or the instance's configured default MCP user)."
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Fields to update (partial)",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Calendar"
}
}
}
},
"responses": {
"200": {
"description": "Updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Calendar"
}
}
}
},
"404": {
"description": "Not found"
}
}
}
DELETE /users/{email}/calendars/{id}
Delete calendar (user-scoped path)
User-scoped twin of DELETE /calendars/{id}.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"x-mcp": false,
"summary": "Delete calendar (user-scoped path)",
"description": "User-scoped twin of DELETE /calendars/{id}.",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "email",
"required": true,
"schema": {
"type": "string",
"format": "email"
},
"description": "User email — or the literal \"me\" to act as the current impersonated user (the X-PS-Impersonate-User header, or the instance's configured default MCP user)."
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No content"
},
"404": {
"description": "Not found"
}
}
}
GET /users/{email}/calendars/{id}/events
List events for a specific calendar (user-scoped path)
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "List events for a specific calendar (user-scoped path)",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "email",
"required": true,
"schema": {
"type": "string",
"format": "email"
},
"description": "User email — or the literal \"me\" to act as the current impersonated user (the X-PS-Impersonate-User header, or the instance's configured default MCP user)."
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
},
"description": "Calendar id"
},
{
"in": "query",
"name": "startDateTime",
"schema": {
"type": "string",
"format": "date-time"
},
"example": "2026-06-02T00:00:00Z"
},
{
"in": "query",
"name": "endDateTime",
"schema": {
"type": "string",
"format": "date-time"
},
"example": "2026-06-06T23:59:59Z"
}
],
"responses": {
"200": {
"description": "Events for the calendar",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Event"
}
}
}
}
}
}
},
"404": {
"description": "Calendar not found"
}
}
}
POST /users/{email}/calendars/{id}/events
Create event in a specific calendar (user-scoped path)
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Create event in a specific calendar (user-scoped path)",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "email",
"required": true,
"schema": {
"type": "string",
"format": "email"
},
"description": "User email — or the literal \"me\" to act as the current impersonated user (the X-PS-Impersonate-User header, or the instance's configured default MCP user)."
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
},
"description": "Calendar id"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Event"
}
}
}
},
"responses": {
"201": {
"description": "Created event",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Event"
}
}
}
},
"404": {
"description": "Calendar not found"
}
}
}
GET /calendars
List Purple Calendar calendars
The calendar containers in this instance — each person's default calendar plus any shared or resource calendars, with owner, colour and sharing flags. These are the buckets events live in, not the events themselves; use it to resolve a calendar id before listing or creating events inside one.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "List Purple Calendar calendars",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"$ref": "#/components/parameters/Top"
},
{
"$ref": "#/components/parameters/Skip"
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"default": 50
},
"description": "Alias for $top — max items per page (default 50)"
}
],
"responses": {
"200": {
"description": "Paginated list of calendars",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Calendar"
}
},
"@odata.nextLink": {
"type": "string",
"nullable": true,
"description": "OData next-page link, absent on the last page"
}
}
}
}
}
}
},
"description": "The calendar containers in this instance — each person's default calendar plus any shared or resource calendars, with owner, colour and sharing flags. These are the buckets events live in, not the events themselves; use it to resolve a calendar id before listing or creating events inside one."
}
POST /calendars
Create calendar
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Create calendar",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Calendar"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Calendar"
}
}
}
}
}
}
GET /calendars/{id}
Get calendar
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Get calendar",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Calendar"
}
}
}
},
"404": {
"description": "Not found"
}
}
}
PATCH /calendars/{id}
Update calendar
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Update calendar",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Fields to update (partial)",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Calendar"
}
}
}
},
"responses": {
"200": {
"description": "Updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Calendar"
}
}
}
},
"404": {
"description": "Not found"
}
}
}
DELETE /calendars/{id}
Delete calendar
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Delete calendar",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No content"
},
"404": {
"description": "Not found"
}
}
}
GET /calendars/{id}/events
List events for a specific calendar
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "List events for a specific calendar",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "startDateTime",
"schema": {
"type": "string",
"format": "date-time"
},
"example": "2026-06-02T00:00:00Z"
},
{
"in": "query",
"name": "endDateTime",
"schema": {
"type": "string",
"format": "date-time"
},
"example": "2026-06-06T23:59:59Z"
}
],
"responses": {
"200": {
"description": "Events for the calendar",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Event"
}
}
}
}
}
}
},
"404": {
"description": "Calendar not found"
}
}
}
POST /calendars/{id}/events
Create event in a specific calendar
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Create event in a specific calendar",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Event"
}
}
}
},
"responses": {
"201": {
"description": "Created event",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Event"
}
}
}
},
"404": {
"description": "Calendar not found"
}
}
}
POST /calendar/getSchedule
Get free/busy schedule for users (bare path alias)
Returns availability view and schedule items for each requested SMTP address. Also available at /users/{email}/calendar/getSchedule.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Get free/busy schedule for users (bare path alias)",
"description": "Returns availability view and schedule items for each requested SMTP address. Also available at /users/{email}/calendar/getSchedule.",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"schedules": {
"type": "array",
"items": {
"type": "string",
"format": "email"
},
"description": "SMTP addresses to query",
"example": [
"alice.chen@acme.com",
"bob.martinez@acme.com"
]
},
"startTime": {
"allOf": [
{
"$ref": "#/components/schemas/DateTimeTimeZone"
}
],
"example": {
"dateTime": "2026-06-02T08:00:00.0000000",
"timeZone": "Pacific Standard Time"
}
},
"endTime": {
"allOf": [
{
"$ref": "#/components/schemas/DateTimeTimeZone"
}
],
"example": {
"dateTime": "2026-06-06T18:00:00.0000000",
"timeZone": "Pacific Standard Time"
}
},
"availabilityViewInterval": {
"type": "integer",
"default": 30,
"description": "Minutes per availability slot",
"example": 30
}
},
"required": [
"schedules",
"startTime",
"endTime"
]
}
}
}
},
"responses": {
"200": {
"description": "Schedule information",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ScheduleInformation"
}
}
}
}
}
}
},
"400": {
"description": "schedules, startTime, and endTime are required"
}
}
}
POST /users/{email}/calendar/getSchedule
Get free/busy schedule for users (user-scoped path)
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Get free/busy schedule for users (user-scoped path)",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "email",
"required": true,
"schema": {
"type": "string",
"format": "email"
},
"description": "User email — or the literal \"me\" to act as the current impersonated user (the X-PS-Impersonate-User header, or the instance's configured default MCP user)."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"schedules": {
"type": "array",
"items": {
"type": "string",
"format": "email"
},
"description": "SMTP addresses to query",
"example": [
"alice.chen@acme.com",
"bob.martinez@acme.com"
]
},
"startTime": {
"allOf": [
{
"$ref": "#/components/schemas/DateTimeTimeZone"
}
],
"example": {
"dateTime": "2026-06-02T08:00:00.0000000",
"timeZone": "Pacific Standard Time"
}
},
"endTime": {
"allOf": [
{
"$ref": "#/components/schemas/DateTimeTimeZone"
}
],
"example": {
"dateTime": "2026-06-06T18:00:00.0000000",
"timeZone": "Pacific Standard Time"
}
},
"availabilityViewInterval": {
"type": "integer",
"default": 30,
"description": "Minutes per availability slot",
"example": 30
}
},
"required": [
"schedules",
"startTime",
"endTime"
]
}
}
}
},
"responses": {
"200": {
"description": "Schedule information",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ScheduleInformation"
}
}
}
}
}
}
}
}
}
GET /places
List bookable meeting rooms
Physical meeting rooms in Purple Calendar — display name, room mailbox address, capacity, building/floor, accessibility and equipment tags (whiteboard, tv, video_conferencing). Use it to pick a room to attach as an event location or resource attendee; it is not an office/site directory and holds no people. Pages with _top/_skip.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "List bookable meeting rooms",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"$ref": "#/components/parameters/Top"
},
{
"$ref": "#/components/parameters/Skip"
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"default": 50
},
"description": "Alias for $top — max items per page (default 50)"
}
],
"responses": {
"200": {
"description": "Paginated list of rooms",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Room"
}
},
"@odata.nextLink": {
"type": "string",
"nullable": true,
"description": "OData next-page link, absent on the last page"
}
}
}
}
}
}
},
"description": "Physical meeting rooms in Purple Calendar — display name, room mailbox address, capacity, building/floor, accessibility and equipment tags (whiteboard, tv, video_conferencing). Use it to pick a room to attach as an event location or resource attendee; it is not an office/site directory and holds no people. Pages with _top/_skip."
}
POST /places
Create room
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Create room",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Room"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Room"
}
}
}
}
}
}
GET /places/{id}
Get room
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Get room",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Room"
}
}
}
},
"404": {
"description": "Not found"
}
}
}
PATCH /places/{id}
Update room
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Update room",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Fields to update (partial)",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Room"
}
}
}
},
"responses": {
"200": {
"description": "Updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Room"
}
}
}
},
"404": {
"description": "Not found"
}
}
}
DELETE /places/{id}
Delete room
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Delete room",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No content"
},
"404": {
"description": "Not found"
}
}
}
GET /users/{email}/mailboxSettings
Get user mailbox settings
Returns a Graph-compatible MailboxSettings projection of the stored UserSettings record. Returns sensible defaults for unknown users.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Get user mailbox settings",
"description": "Returns a Graph-compatible MailboxSettings projection of the stored UserSettings record. Returns sensible defaults for unknown users.",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "email",
"required": true,
"schema": {
"type": "string",
"format": "email"
},
"description": "User email — or the literal \"me\" to act as the current impersonated user (the X-PS-Impersonate-User header, or the instance's configured default MCP user)."
}
],
"responses": {
"200": {
"description": "Mailbox settings",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MailboxSettings"
}
}
}
}
}
}
PATCH /users/{email}/mailboxSettings
Update user mailbox settings
Merges the provided fields into the user's settings. Creates a record if none exists. Validates timeZone and workingHours.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Update user mailbox settings",
"description": "Merges the provided fields into the user's settings. Creates a record if none exists. Validates timeZone and workingHours.",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "email",
"required": true,
"schema": {
"type": "string",
"format": "email"
},
"description": "User email — or the literal \"me\" to act as the current impersonated user (the X-PS-Impersonate-User header, or the instance's configured default MCP user)."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MailboxSettings"
}
}
}
},
"responses": {
"200": {
"description": "Updated mailbox settings",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MailboxSettings"
}
}
}
},
"422": {
"description": "Invalid timeZone or workingHours"
}
}
}
GET /distribution_lists
List email distribution lists
Named email groups in Purple Calendar (e.g. engineering-all@acme.com) with their member addresses and memberCount — used to invite a whole group to a meeting. These are mailing groups, not chat channels (see the chat app) or HR departments (see the hris app). Supports server-side querying with _filter/_search/_orderby/_select/_top/_skip/_count (OData $-params, renamed with a leading underscore for MCP).
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "List email distribution lists",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"default": 50
},
"description": "Max items per page (default 50)"
},
{
"in": "query",
"name": "cursor",
"schema": {
"type": "string"
},
"description": "Pass the previous response's nextCursor to fetch the next page"
},
{
"in": "query",
"name": "$filter",
"schema": {
"type": "string"
},
"description": "OData filter expression. Comparison operators: eq, ne, gt, ge, lt, le. Logical: and, or, not, with parentheses for grouping. String functions: contains(field,'x'), startswith(field,'x'), endswith(field,'x'). Membership: field in ('a','b'). Case-insensitive matching via tolower(field) / toupper(field). Nested fields use a slash, e.g. pto_balance/vacation_days. String literals use single quotes; dates are ISO-8601. Examples: \"status eq 'active'\"; \"salary gt 50000 and department eq 'Engineering'\"; \"contains(tolower(name),'acme')\"; \"closeDate gt 2026-01-01\"."
},
{
"in": "query",
"name": "$select",
"schema": {
"type": "string"
},
"description": "Comma-separated list of fields to return, e.g. \"id,firstName,email\". Nested fields via slash (\"pto_balance/vacation_days\"). The id field is always included."
},
{
"in": "query",
"name": "$orderby",
"schema": {
"type": "string"
},
"description": "Sort clause(s), comma-separated, each \"field [asc|desc]\" (asc is the default). Example: \"createdAt desc, lastName asc\". Null values sort last."
},
{
"in": "query",
"name": "$search",
"schema": {
"type": "string"
},
"description": "Free-text, case-insensitive substring match across the resource's searchable fields."
},
{
"in": "query",
"name": "$top",
"schema": {
"type": "integer"
},
"description": "Maximum number of items to return (page size)."
},
{
"in": "query",
"name": "$skip",
"schema": {
"type": "integer"
},
"description": "Number of matching items to skip before returning results (offset paging). Combine with $top."
},
{
"in": "query",
"name": "$count",
"schema": {
"type": "boolean"
},
"description": "When true, include @odata.count (total matches after $filter/$search, before paging) in the response."
}
],
"responses": {
"200": {
"description": "Paginated list of distribution lists",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DistributionList"
}
},
"nextCursor": {
"type": "string",
"nullable": true,
"description": "Cursor for the next page, or null on the last page"
},
"total": {
"type": "integer",
"description": "Total documents in the collection"
}
}
}
}
}
}
},
"description": "Named email groups in Purple Calendar (e.g. engineering-all@acme.com) with their member addresses and memberCount — used to invite a whole group to a meeting. These are mailing groups, not chat channels (see the chat app) or HR departments (see the hris app). Supports server-side querying with _filter/_search/_orderby/_select/_top/_skip/_count (OData $-params, renamed with a leading underscore for MCP)."
}
POST /distribution_lists
Create distribution list
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Create distribution list",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DistributionList"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DistributionList"
}
}
}
}
}
}
GET /distribution_lists/{id}
Get distribution list
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Get distribution list",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DistributionList"
}
}
}
},
"404": {
"description": "Not found"
}
}
}
PATCH /distribution_lists/{id}
Update distribution list
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Update distribution list",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Fields to update (partial)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DistributionList"
}
}
}
},
"responses": {
"200": {
"description": "Updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DistributionList"
}
}
}
},
"404": {
"description": "Not found"
}
}
}
DELETE /distribution_lists/{id}
Delete distribution list
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Delete distribution list",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Deleted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"404": {
"description": "Not found"
}
}
}
POST /distribution_lists/{id}/members
Add members to a distribution list
Appends new email addresses to the members array (duplicates are silently skipped). Updates memberCount.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Add members to a distribution list",
"description": "Appends new email addresses to the members array (duplicates are silently skipped). Updates memberCount.",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"emails": {
"type": "array",
"items": {
"type": "string",
"format": "email"
},
"example": [
"carol.johnson@acme.com",
"dave.williams@acme.com"
]
}
},
"required": [
"emails"
]
}
}
}
},
"responses": {
"200": {
"description": "Updated distribution list",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DistributionList"
}
}
}
},
"404": {
"description": "Not found"
},
"422": {
"description": "emails array is required and must not be empty"
}
}
}
DELETE /distribution_lists/{id}/members/{email}
Remove a member from a distribution list
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Remove a member from a distribution list",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "path",
"name": "email",
"required": true,
"schema": {
"type": "string",
"format": "email"
},
"description": "Email address of the member to remove"
}
],
"responses": {
"200": {
"description": "Updated distribution list",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DistributionList"
}
}
}
},
"404": {
"description": "Not found (list or member)"
}
}
}
GET /user_settings
List calendar user (mailbox) settings
Raw UserSettings records — one per mailbox in Purple Calendar — holding each person's email, display name, timezone, working hours, date/time format, locale and auto-reply setting. This is the storage-level view and the way to enumerate who has a mailbox; for one known user prefer the Graph-shaped mailboxSettings tool. Supports server-side querying with _filter/_search/_orderby/_select/_top/_skip/_count (OData $-params, renamed with a leading underscore for MCP).
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "List calendar user (mailbox) settings",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"default": 50
},
"description": "Max items per page (default 50)"
},
{
"in": "query",
"name": "cursor",
"schema": {
"type": "string"
},
"description": "Pass the previous response's nextCursor to fetch the next page"
},
{
"in": "query",
"name": "$filter",
"schema": {
"type": "string"
},
"description": "OData filter expression. Comparison operators: eq, ne, gt, ge, lt, le. Logical: and, or, not, with parentheses for grouping. String functions: contains(field,'x'), startswith(field,'x'), endswith(field,'x'). Membership: field in ('a','b'). Case-insensitive matching via tolower(field) / toupper(field). Nested fields use a slash, e.g. pto_balance/vacation_days. String literals use single quotes; dates are ISO-8601. Examples: \"status eq 'active'\"; \"salary gt 50000 and department eq 'Engineering'\"; \"contains(tolower(name),'acme')\"; \"closeDate gt 2026-01-01\"."
},
{
"in": "query",
"name": "$select",
"schema": {
"type": "string"
},
"description": "Comma-separated list of fields to return, e.g. \"id,firstName,email\". Nested fields via slash (\"pto_balance/vacation_days\"). The id field is always included."
},
{
"in": "query",
"name": "$orderby",
"schema": {
"type": "string"
},
"description": "Sort clause(s), comma-separated, each \"field [asc|desc]\" (asc is the default). Example: \"createdAt desc, lastName asc\". Null values sort last."
},
{
"in": "query",
"name": "$search",
"schema": {
"type": "string"
},
"description": "Free-text, case-insensitive substring match across the resource's searchable fields."
},
{
"in": "query",
"name": "$top",
"schema": {
"type": "integer"
},
"description": "Maximum number of items to return (page size)."
},
{
"in": "query",
"name": "$skip",
"schema": {
"type": "integer"
},
"description": "Number of matching items to skip before returning results (offset paging). Combine with $top."
},
{
"in": "query",
"name": "$count",
"schema": {
"type": "boolean"
},
"description": "When true, include @odata.count (total matches after $filter/$search, before paging) in the response."
}
],
"responses": {
"200": {
"description": "Paginated list of user settings",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UserSettings"
}
},
"nextCursor": {
"type": "string",
"nullable": true,
"description": "Cursor for the next page, or null on the last page"
},
"total": {
"type": "integer",
"description": "Total documents in the collection"
}
}
}
}
}
}
},
"description": "Raw UserSettings records — one per mailbox in Purple Calendar — holding each person's email, display name, timezone, working hours, date/time format, locale and auto-reply setting. This is the storage-level view and the way to enumerate who has a mailbox; for one known user prefer the Graph-shaped mailboxSettings tool. Supports server-side querying with _filter/_search/_orderby/_select/_top/_skip/_count (OData $-params, renamed with a leading underscore for MCP)."
}
POST /user_settings
Create user settings record
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Create user settings record",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserSettings"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserSettings"
}
}
}
}
}
}
GET /user_settings/{id}
Get user settings record
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Get user settings record",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserSettings"
}
}
}
},
"404": {
"description": "Not found"
}
}
}
PATCH /user_settings/{id}
Update a calendar user settings record
Partially updates one raw UserSettings record by its document id (timezone, working hours, locale, auto-replies). Use the mailboxSettings update tool instead when you have the person's email address rather than the record id.
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Update a calendar user settings record",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Fields to update (partial)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserSettings"
}
}
}
},
"responses": {
"200": {
"description": "Updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UserSettings"
}
}
}
},
"404": {
"description": "Not found"
}
},
"description": "Partially updates one raw UserSettings record by its document id (timezone, working hours, locale, auto-replies). Use the mailboxSettings update tool instead when you have the person's email address rather than the record id."
}
DELETE /user_settings/{id}
Delete user settings record
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Delete user settings record",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Deleted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
}
}
}
}
}
},
"404": {
"description": "Not found"
}
}
}
POST /me/events/{id}/accept
Accept event invitation (/me alias)
Alias of /users/{email}/events/{id}/accept: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Accept event invitation (/me alias)",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"comment": {
"type": "string",
"example": "Looking forward to it!"
},
"sendResponse": {
"type": "boolean",
"example": true
}
}
}
}
}
},
"responses": {
"202": {
"description": "Accepted"
},
"404": {
"description": "Not found"
}
},
"x-mcp": false,
"description": "Alias of /users/{email}/events/{id}/accept: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user)."
}
POST /me/events/{id}/decline
Decline event invitation (/me alias)
Alias of /users/{email}/events/{id}/decline: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Decline event invitation (/me alias)",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"comment": {
"type": "string",
"example": "Conflict — will catch the recording."
},
"sendResponse": {
"type": "boolean",
"example": true
},
"proposedNewTime": {
"type": "object",
"nullable": true
}
}
}
}
}
},
"responses": {
"202": {
"description": "Accepted"
},
"404": {
"description": "Not found"
}
},
"x-mcp": false,
"description": "Alias of /users/{email}/events/{id}/decline: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user)."
}
POST /me/events/{id}/tentativelyAccept
Tentatively accept event invitation (/me alias)
Alias of /users/{email}/events/{id}/tentativelyAccept: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Tentatively accept event invitation (/me alias)",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"comment": {
"type": "string",
"example": "Will try to join."
},
"sendResponse": {
"type": "boolean",
"example": true
},
"proposedNewTime": {
"type": "object",
"nullable": true
}
}
}
}
}
},
"responses": {
"202": {
"description": "Accepted"
},
"404": {
"description": "Not found"
}
},
"x-mcp": false,
"description": "Alias of /users/{email}/events/{id}/tentativelyAccept: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user)."
}
POST /me/events/{id}/cancel
Cancel event (user-scoped path) (/me alias)
Cancels the event (sets isCancelled: true, showAs: free). Does not delete the event. Cancelling a seriesMaster cancels the whole series; cancelling a generated occurrence (id in the form seriesMasterId_yyyymmdd) cancels just that date by materializing an exception. Alias of /users/{email}/events/{id}/cancel: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Cancel event (user-scoped path) (/me alias)",
"description": "Cancels the event (sets isCancelled: true, showAs: free). Does not delete the event. Cancelling a seriesMaster cancels the whole series; cancelling a generated occurrence (id in the form seriesMasterId_yyyymmdd) cancels just that date by materializing an exception. Alias of /users/{email}/events/{id}/cancel: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"comment": {
"type": "string",
"description": "Cancellation message",
"example": "Meeting is no longer needed."
}
}
}
}
}
},
"responses": {
"202": {
"description": "Accepted"
},
"404": {
"description": "Not found"
}
},
"x-mcp": false
}
GET /me/events/{id}/instances
List occurrences of an event series (user-scoped path) (/me alias)
Expands a seriesMaster into its occurrence instances within the time window (stored exceptions included). For a non-recurring event, returns the event itself when it intersects the window. Alias of /users/{email}/events/{id}/instances: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "List occurrences of an event series (user-scoped path) (/me alias)",
"description": "Expands a seriesMaster into its occurrence instances within the time window (stored exceptions included). For a non-recurring event, returns the event itself when it intersects the window. Alias of /users/{email}/events/{id}/instances: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "startDateTime",
"required": true,
"schema": {
"type": "string",
"format": "date-time"
},
"example": "2026-06-01T00:00:00Z"
},
{
"in": "query",
"name": "endDateTime",
"required": true,
"schema": {
"type": "string",
"format": "date-time"
},
"example": "2026-06-30T23:59:59Z"
}
],
"responses": {
"200": {
"description": "Occurrences in range",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Event"
}
}
}
}
}
}
},
"400": {
"description": "startDateTime and endDateTime are required"
},
"404": {
"description": "Not found"
}
},
"x-mcp": false
}
POST /me/findMeetingTimes
Find meeting time suggestions (user-scoped path) (/me alias)
Organizer-scoped variant. Uses the organizer's timezone from their mailboxSettings for activityDomain filtering. Alias of /users/{email}/findMeetingTimes: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Find meeting time suggestions (user-scoped path) (/me alias)",
"description": "Organizer-scoped variant. Uses the organizer's timezone from their mailboxSettings for activityDomain filtering. Alias of /users/{email}/findMeetingTimes: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "header",
"name": "Prefer",
"schema": {
"type": "string"
},
"description": "Optional response timezone override, e.g. `outlook.timezone=\"Pacific Standard Time\"`",
"example": "outlook.timezone=\"Pacific Standard Time\""
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"attendees": {
"type": "array",
"items": {
"type": "object",
"properties": {
"emailAddress": {
"$ref": "#/components/schemas/EmailAddress"
},
"type": {
"type": "string",
"enum": [
"required",
"optional",
"resource"
]
}
}
},
"example": [
{
"emailAddress": {
"address": "bob.martinez@acme.com",
"name": "Bob Martinez"
},
"type": "required"
}
]
},
"timeConstraint": {
"type": "object",
"properties": {
"activityDomain": {
"type": "string",
"enum": [
"work",
"personal",
"unrestricted"
],
"example": "work"
},
"timeSlots": {
"type": "array",
"items": {
"type": "object",
"properties": {
"start": {
"$ref": "#/components/schemas/DateTimeTimeZone"
},
"end": {
"$ref": "#/components/schemas/DateTimeTimeZone"
}
}
},
"example": [
{
"start": {
"dateTime": "2026-06-02T08:00:00.0000000",
"timeZone": "Pacific Standard Time"
},
"end": {
"dateTime": "2026-06-02T17:00:00.0000000",
"timeZone": "Pacific Standard Time"
}
}
]
}
}
},
"meetingDuration": {
"type": "string",
"description": "ISO 8601 duration, e.g. PT1H, PT30M",
"default": "PT30M",
"example": "PT30M"
},
"maxCandidates": {
"type": "integer",
"default": 5,
"example": 5
},
"minimumAttendeePercentage": {
"type": "number",
"default": 50,
"example": 50
},
"isOrganizerOptional": {
"type": "boolean",
"default": false,
"example": false
},
"returnSuggestionReasons": {
"type": "boolean",
"default": false,
"example": false
}
}
}
}
}
},
"responses": {
"200": {
"description": "Meeting time suggestions",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"emptySuggestionsReason": {
"type": "string",
"example": ""
},
"meetingTimeSuggestions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"confidence": {
"type": "number",
"example": 100
},
"order": {
"type": "integer",
"example": 1
},
"organizerAvailability": {
"type": "string",
"example": "free"
},
"suggestionReason": {
"type": "string"
},
"attendeeAvailability": {
"type": "array",
"items": {
"type": "object",
"properties": {
"attendee": {
"type": "object"
},
"availability": {
"type": "string"
}
}
}
},
"locations": {
"type": "array",
"items": {
"type": "object"
}
},
"meetingTimeSlot": {
"type": "object",
"properties": {
"start": {
"$ref": "#/components/schemas/DateTimeTimeZone"
},
"end": {
"$ref": "#/components/schemas/DateTimeTimeZone"
}
}
}
}
}
}
}
}
}
}
}
},
"x-mcp": false
}
GET /me/calendarView
Get calendar view for a specific user (events in time range) (/me alias)
Alias of /users/{email}/calendarView: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Get calendar view for a specific user (events in time range) (/me alias)",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "query",
"name": "startDateTime",
"required": true,
"schema": {
"type": "string",
"format": "date-time"
},
"example": "2026-06-02T00:00:00Z"
},
{
"in": "query",
"name": "endDateTime",
"required": true,
"schema": {
"type": "string",
"format": "date-time"
},
"example": "2026-06-06T23:59:59Z"
}
],
"responses": {
"200": {
"description": "User events in range",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Event"
}
}
}
}
}
}
},
"400": {
"description": "startDateTime and endDateTime are required"
}
},
"x-mcp": false,
"description": "Alias of /users/{email}/calendarView: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user)."
}
GET /me/events
List all events for a specific user (/me alias)
Alias of /users/{email}/events: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "List all events for a specific user (/me alias)",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"$ref": "#/components/parameters/Top"
},
{
"$ref": "#/components/parameters/Skip"
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"default": 50
},
"description": "Alias for $top — max items per page (default 50)"
}
],
"responses": {
"200": {
"description": "User events",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Event"
}
},
"@odata.nextLink": {
"type": "string",
"nullable": true,
"description": "OData next-page link, absent on the last page"
}
}
}
}
}
}
},
"x-mcp": false,
"description": "Alias of /users/{email}/events: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user)."
}
POST /me/events
Create event (user-scoped path) (/me alias)
User-scoped twin of POST /events. Defaults the organizer to the resolved user when the body doesn't set one. Alias of /users/{email}/events: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"x-mcp": false,
"summary": "Create event (user-scoped path) (/me alias)",
"description": "User-scoped twin of POST /events. Defaults the organizer to the resolved user when the body doesn't set one. Alias of /users/{email}/events: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Event"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Event"
}
}
}
}
}
}
GET /me/events/{id}
Get event (user-scoped path) (/me alias)
User-scoped twin of GET /events/{id}. Alias of /users/{email}/events/{id}: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"x-mcp": false,
"summary": "Get event (user-scoped path) (/me alias)",
"description": "User-scoped twin of GET /events/{id}. Alias of /users/{email}/events/{id}: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Event"
}
}
}
},
"404": {
"description": "Not found"
}
}
}
PATCH /me/events/{id}
Update event (user-scoped path) (/me alias)
User-scoped twin of PATCH /events/{id}. Alias of /users/{email}/events/{id}: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"x-mcp": false,
"summary": "Update event (user-scoped path) (/me alias)",
"description": "User-scoped twin of PATCH /events/{id}. Alias of /users/{email}/events/{id}: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Fields to update (partial)",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Event"
}
}
}
},
"responses": {
"200": {
"description": "Updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Event"
}
}
}
},
"404": {
"description": "Not found"
}
}
}
DELETE /me/events/{id}
Delete event (user-scoped path) (/me alias)
User-scoped twin of DELETE /events/{id}. Alias of /users/{email}/events/{id}: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"x-mcp": false,
"summary": "Delete event (user-scoped path) (/me alias)",
"description": "User-scoped twin of DELETE /events/{id}. Alias of /users/{email}/events/{id}: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No content"
},
"404": {
"description": "Not found"
}
}
}
GET /me/calendars
List all calendars (user-scoped alias — returns all instance calendars) (/me alias)
Alias of /users/{email}/calendars: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"x-mcp": false,
"summary": "List all calendars (user-scoped alias — returns all instance calendars) (/me alias)",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"$ref": "#/components/parameters/Top"
},
{
"$ref": "#/components/parameters/Skip"
},
{
"in": "query",
"name": "limit",
"schema": {
"type": "integer",
"default": 50
},
"description": "Alias for $top — max items per page (default 50)"
}
],
"responses": {
"200": {
"description": "Collection of calendars",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Calendar"
}
},
"@odata.nextLink": {
"type": "string",
"nullable": true,
"description": "OData next-page link, absent on the last page"
}
}
}
}
}
}
},
"description": "Alias of /users/{email}/calendars: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user)."
}
POST /me/calendars
Create calendar (user-scoped path) (/me alias)
User-scoped twin of POST /calendars. Defaults the owner to the resolved user when the body doesn't set one. Alias of /users/{email}/calendars: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"x-mcp": false,
"summary": "Create calendar (user-scoped path) (/me alias)",
"description": "User-scoped twin of POST /calendars. Defaults the owner to the resolved user when the body doesn't set one. Alias of /users/{email}/calendars: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Calendar"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Calendar"
}
}
}
}
}
}
GET /me/calendars/{id}
Get calendar (user-scoped path) (/me alias)
User-scoped twin of GET /calendars/{id}. Alias of /users/{email}/calendars/{id}: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"x-mcp": false,
"summary": "Get calendar (user-scoped path) (/me alias)",
"description": "User-scoped twin of GET /calendars/{id}. Alias of /users/{email}/calendars/{id}: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Calendar"
}
}
}
},
"404": {
"description": "Not found"
}
}
}
PATCH /me/calendars/{id}
Update calendar (user-scoped path) (/me alias)
User-scoped twin of PATCH /calendars/{id}. Alias of /users/{email}/calendars/{id}: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"x-mcp": false,
"summary": "Update calendar (user-scoped path) (/me alias)",
"description": "User-scoped twin of PATCH /calendars/{id}. Alias of /users/{email}/calendars/{id}: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Fields to update (partial)",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Calendar"
}
}
}
},
"responses": {
"200": {
"description": "Updated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Calendar"
}
}
}
},
"404": {
"description": "Not found"
}
}
}
DELETE /me/calendars/{id}
Delete calendar (user-scoped path) (/me alias)
User-scoped twin of DELETE /calendars/{id}. Alias of /users/{email}/calendars/{id}: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"x-mcp": false,
"summary": "Delete calendar (user-scoped path) (/me alias)",
"description": "User-scoped twin of DELETE /calendars/{id}. Alias of /users/{email}/calendars/{id}: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"204": {
"description": "No content"
},
"404": {
"description": "Not found"
}
}
}
GET /me/calendars/{id}/events
List events for a specific calendar (user-scoped path) (/me alias)
Alias of /users/{email}/calendars/{id}/events: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "List events for a specific calendar (user-scoped path) (/me alias)",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
},
"description": "Calendar id"
},
{
"in": "query",
"name": "startDateTime",
"schema": {
"type": "string",
"format": "date-time"
},
"example": "2026-06-02T00:00:00Z"
},
{
"in": "query",
"name": "endDateTime",
"schema": {
"type": "string",
"format": "date-time"
},
"example": "2026-06-06T23:59:59Z"
}
],
"responses": {
"200": {
"description": "Events for the calendar",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Event"
}
}
}
}
}
}
},
"404": {
"description": "Calendar not found"
}
},
"x-mcp": false,
"description": "Alias of /users/{email}/calendars/{id}/events: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user)."
}
POST /me/calendars/{id}/events
Create event in a specific calendar (user-scoped path) (/me alias)
Alias of /users/{email}/calendars/{id}/events: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Create event in a specific calendar (user-scoped path) (/me alias)",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
},
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
},
"description": "Calendar id"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Event"
}
}
}
},
"responses": {
"201": {
"description": "Created event",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Event"
}
}
}
},
"404": {
"description": "Calendar not found"
}
},
"x-mcp": false,
"description": "Alias of /users/{email}/calendars/{id}/events: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user)."
}
POST /me/calendar/getSchedule
Get free/busy schedule for users (user-scoped path) (/me alias)
Alias of /users/{email}/calendar/getSchedule: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Get free/busy schedule for users (user-scoped path) (/me alias)",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"schedules": {
"type": "array",
"items": {
"type": "string",
"format": "email"
},
"description": "SMTP addresses to query",
"example": [
"alice.chen@acme.com",
"bob.martinez@acme.com"
]
},
"startTime": {
"allOf": [
{
"$ref": "#/components/schemas/DateTimeTimeZone"
}
],
"example": {
"dateTime": "2026-06-02T08:00:00.0000000",
"timeZone": "Pacific Standard Time"
}
},
"endTime": {
"allOf": [
{
"$ref": "#/components/schemas/DateTimeTimeZone"
}
],
"example": {
"dateTime": "2026-06-06T18:00:00.0000000",
"timeZone": "Pacific Standard Time"
}
},
"availabilityViewInterval": {
"type": "integer",
"default": 30,
"description": "Minutes per availability slot",
"example": 30
}
},
"required": [
"schedules",
"startTime",
"endTime"
]
}
}
}
},
"responses": {
"200": {
"description": "Schedule information",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"value": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ScheduleInformation"
}
}
}
}
}
}
}
},
"x-mcp": false,
"description": "Alias of /users/{email}/calendar/getSchedule: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user)."
}
GET /me/mailboxSettings
Get user mailbox settings (/me alias)
Returns a Graph-compatible MailboxSettings projection of the stored UserSettings record. Returns sensible defaults for unknown users. Alias of /users/{email}/mailboxSettings: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Get user mailbox settings (/me alias)",
"description": "Returns a Graph-compatible MailboxSettings projection of the stored UserSettings record. Returns sensible defaults for unknown users. Alias of /users/{email}/mailboxSettings: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
}
],
"responses": {
"200": {
"description": "Mailbox settings",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MailboxSettings"
}
}
}
}
},
"x-mcp": false
}
PATCH /me/mailboxSettings
Update user mailbox settings (/me alias)
Merges the provided fields into the user's settings. Creates a record if none exists. Validates timeZone and workingHours. Alias of /users/{email}/mailboxSettings: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).
Authentication
[
{
"patAuth": []
}
]
Request, responses and operation details
{
"summary": "Update user mailbox settings (/me alias)",
"description": "Merges the provided fields into the user's settings. Creates a record if none exists. Validates timeZone and workingHours. Alias of /users/{email}/mailboxSettings: acts as the impersonated user (X-PS-Impersonate-User header, or the instance's default MCP user).",
"parameters": [
{
"$ref": "#/components/parameters/InstanceId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MailboxSettings"
}
}
}
},
"responses": {
"200": {
"description": "Updated mailbox settings",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MailboxSettings"
}
}
}
},
"422": {
"description": "Invalid timeZone or workingHours"
}
},
"x-mcp": false
}