# List calendar events Returns upcoming events from the calendar connected in the Convo desktop app, Google or Outlook, by start time. Events come in the provider's own format. Declined and cancelled events are left out. Without `timeMax`, Outlook looks 7 days ahead and Google has no end. Source: https://docs.itsconvo.com/api-reference/calendar/list-calendar-events API Base URL: https://www.itsconvo.com/api/v1 ## GET /api/v1/calendar/events ```json { "openapi": "3.0.3", "servers": [ { "url": "https://www.itsconvo.com", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/api/v1/calendar/events": { "get": { "tags": [ "Calendar" ], "summary": "List calendar events", "description": "Returns upcoming events from the calendar connected in the Convo desktop app, Google or Outlook, by start time. Events come in the provider's own format. Declined and cancelled events are left out. Without `timeMax`, Outlook looks 7 days ahead and Google has no end.", "operationId": "listCalendarEvents", "parameters": [ { "name": "maxResults", "in": "query", "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 50 }, "description": "Events to return, 1 to 50" }, { "name": "timeMin", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "Start of the window (ISO 8601). Defaults to now." }, { "name": "timeMax", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "End of the window (ISO 8601)" } ], "responses": { "200": { "description": "Calendar events", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CalendarEvent" } } } }, "example": { "data": [ { "id": "evt_abc123", "summary": "Weekly Standup", "start": { "dateTime": "2026-03-19T09:00:00-04:00", "timeZone": "America/New_York" }, "end": { "dateTime": "2026-03-19T09:30:00-04:00", "timeZone": "America/New_York" }, "attendees": [ { "email": "alice@example.com", "displayName": "Alice Chen", "responseStatus": "accepted" }, { "email": "bob@example.com", "displayName": "Bob Smith", "responseStatus": "accepted" } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Calendar access was revoked. Reconnect the calendar in the desktop app.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "Calendar permissions revoked. Please reconnect your calendar." } } } } }, "404": { "description": "No calendar is connected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Calendar not connected. Connect your calendar in the Convo dashboard." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "A Convo API key: `convo_` followed by 32 hex characters. Create it in the Convo desktop app under Settings → Convo API." } }, "parameters": { "conversationId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Conversation ID from List conversations", "example": "session_1773842400000" } }, "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests allowed per hour on your plan" }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left this hour" }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix time in seconds of the next full hour (UTC), when the count resets" } }, "schemas": { "CalendarEvent": { "type": "object", "properties": { "id": { "type": "string" }, "summary": { "type": "string", "example": "Weekly Standup" }, "start": { "type": "object", "properties": { "dateTime": { "type": "string", "format": "date-time" }, "timeZone": { "type": "string" } } }, "end": { "type": "object", "properties": { "dateTime": { "type": "string", "format": "date-time" }, "timeZone": { "type": "string" } } }, "attendees": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string" }, "displayName": { "type": "string" }, "responseStatus": { "type": "string" } } } } }, "description": "An event in the calendar provider's own format, passed through unchanged. Google Calendar events look like this. Outlook events are Microsoft Graph events, with `subject`, `start`, `end` and `attendees[].emailAddress` instead.", "additionalProperties": true }, "Error": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "unauthorized", "forbidden", "not_found", "rate_limited", "ai_limit_exceeded", "validation_error", "internal_error" ] }, "message": { "type": "string" } } } } } }, "responses": { "Unauthorized": { "description": "The Authorization header is missing, or the key is wrong or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing or invalid Authorization header. Use: Bearer " } } } } }, "Forbidden": { "description": "The plan doesn't allow this request, or the key only works with the MCP server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "forbidden", "message": "API access requires a Starter plan or above. Upgrade at https://www.itsconvo.com/pricing" } } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Conversation not found" } } } } }, "RateLimited": { "description": "Over your hourly request limit", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until the next full hour, when the count resets" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded (100 requests per hour for starter plan)" } } } } }, "AILimitExceeded": { "description": "Your monthly, daily or spending limit for AI credits is reached. The model provider being busy returns `429 rate_limited` instead, without headers.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "ai_limit_exceeded", "message": "Monthly AI generation limit reached. Upgrade your plan for more." } } } } }, "ValidationError": { "description": "A field or parameter is missing or wrong. The message names it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_error", "message": "title is required and must be a non-empty string" } } } } } } } } ```