Calendar API

Read and create calendar events.

⚠️ Approval Required: calendar.createEvent() requires user approval.

calendar.listEvents()

Retrieve calendar events within a date range.

Parameters

ParameterTypeRequiredDescription
startstringYesISO date, start of range
endstringYesISO date, end of range
calendarstringNoCalendar 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

ParameterTypeRequiredDescription
titlestringYesEvent title
startstringYesISO date, event start time
endstringYesISO date, event end time
attendeesstring[]NoAttendee email addresses
locationstringNoEvent location
descriptionstringNoEvent 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_DENIED

User has not granted calendar.read or calendar.write capability.

APPROVAL_REQUIRED

Must call approval.request() before calendar.createEvent().

INVALID_DATE_RANGE

Start time must be before end time.