Calendar API
Read and create calendar events.
⚠️ Approval Required: calendar.createEvent() requires user approval.
calendar.listEvents()
Retrieve calendar events within a date range.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
start | string | Yes | ISO date, start of range |
end | string | Yes | ISO date, end of range |
calendar | string | No | Calendar ID (default: primary) |
Example
const events = await tools.calendar.listEvents({
start: "2024-03-01T00:00:00Z",
end: "2024-03-31T23:59:59Z"
});
// Returns:
[
{
id: "evt_abc123",
title: "Team Standup",
start: "2024-03-15T09:00:00Z",
end: "2024-03-15T09:30:00Z",
location: "Conference Room A",
attendees: [
{ email: "alice@company.com", status: "accepted" },
{ email: "bob@company.com", status: "pending" }
],
description: "Daily standup meeting"
},
// ...
]calendar.createEvent()
Create a new calendar event. Requires approval.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
title | string | Yes | Event title |
start | string | Yes | ISO date, event start time |
end | string | Yes | ISO date, event end time |
attendees | string[] | No | Attendee email addresses |
location | string | No | Event location |
description | string | No | Event description/notes |
Example with Approval Flow
export async function handleIntent({ intent, context, tools }) {
if (intent.action === "schedule_meeting") {
// Step 1: Find available time slots
const events = await tools.calendar.listEvents({
start: context.now,
end: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString()
});
// Step 2: Request approval
const approval = await tools.approval.request({
action: "create_calendar_event",
title: "Schedule Team Meeting",
description: "Create meeting for Friday at 2pm",
details: {
title: "Product Roadmap Discussion",
start: "2024-03-22T14:00:00Z",
end: "2024-03-22T15:00:00Z",
attendees: ["team@company.com"]
}
});
if (!approval.approved) {
return {
type: "error",
title: "Meeting not scheduled",
description: "You declined to create the event."
};
}
// Step 3: Create event
try {
const event = await tools.calendar.createEvent({
title: "Product Roadmap Discussion",
start: "2024-03-22T14:00:00Z",
end: "2024-03-22T15:00:00Z",
attendees: ["team@company.com"],
location: "Conference Room B"
});
return {
type: "result",
title: "✅ Meeting scheduled",
description: `Created "${event.title}" for Friday at 2pm`
};
} catch (error) {
return {
type: "error",
title: "Failed to create event",
description: error.message
};
}
}
}Required Capabilities
{
"capabilities": [
"calendar.read", // for calendar.listEvents()
"calendar.write" // for calendar.createEvent()
]
}Error Codes
CAPABILITY_DENIEDUser has not granted calendar.read or calendar.write capability.
APPROVAL_REQUIREDMust call approval.request() before calendar.createEvent().
INVALID_DATE_RANGEStart time must be before end time.