Calendar calendar
Open meeting times. With no provider, a member whose Google or Outlook calendar is connected to Kenso gets times from their own calendar; anyone else names a provider (calendly, cal_com, hubspot). calendar-accounts-list shows the member's connected calendar accounts (up to three) and their calendars. optiverse-connection-get shows whether the member's own Optiverse is connected. granola-connection-get shows whether your own Granola is connected and when it last found a call. The calendar-meeting-type operations edit the member's own list of the types Ken sorts their calendar events into; Scheduler's bookable meeting types are the scheduler tool's.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through calendar_read and changes through calendar_write. Each takes operation plus that operation's parameters, and your workspace role decides which operations you see.
Each operation with a route calls the Kenso API at https://api.ken.so with Authorization: Bearer <Kenso API key>, Ken-Version: 1.1 and X-Ken-Workspace-Id: <workspace id>. You can call that route directly with the same headers.
Operations: create-calendar-meeting-type, delete-calendar-meeting-type, granola-connection-get, optiverse-connection-get, get-availability, get-calendar-preferences, calendar-accounts-list, list-calendar-meeting-types, reorder-calendar-meeting-types, reset-calendar-meeting-types, update-calendar-meeting-type, update-calendar-preferences
create-calendar-meeting-type
Write. POST https://api.ken.so/v1/me/calendar-meeting-types
Body (json): color string, description string, hasBrief boolean, icon string, name string
Add a meeting type at the bottom of the caller's own list. name is required. description is what Ken reads to decide a meeting's type.
POST /api/v1/me/calendar-meeting-types with Ken-Version 1.1. Internal exposure. Needs the meetings and meeting_types features and a member's credential; a Client seat gets 403. client_id is sent as X-Ken-Workspace-Id. name: 1 to 40 characters, unique in the list ignoring case. description: up to 240 characters, one line. color: # and six hex digits (default: the first color of Kenso's palette the list does not use). icon: an icon name in lowercase kebab-case, at most 40 characters. has_brief: default true; an added type gets the general brief. The key is made from the name and never changes. 409 invalid_state (detail too_many) when the list already holds 12 types. data: the new type. Each type: key (lowercase letters, digits and underscores; it never changes and is what a calendar event's meetingType holds), name, description (the text Ken reads to decide a meeting's type), position (1 is the top; when two types fit a meeting the higher one wins), color (#RRGGBB), icon (omitted when not set), hasBrief (Ken writes a brief before meetings of the type), isBuiltIn (one of sales, customer, networking, partnership, investor, education, recruiting, internal), upcomingCount and pastCount (the caller's own events with the type that are not cancelled). After a write that changes a name, a description, the order or which types exist, Ken sorts the caller's events again from the new list: the upcoming ones it types (14 days ahead) and the ones that started in the last 30 days. Older events keep their type, a type the member set by hand is never changed, and a color, icon or hasBrief change sorts nothing again. It runs in the background within minutes.
delete-calendar-meeting-type
Write. DELETE https://api.ken.so/v1/me/calendar-meeting-types/{typeKey}
Path: typeKey
Query: meetings string, moveToKey string
Remove one of the caller's own meeting types, built-in or added. meetings says what the caller's events of that type get: move, clear or resort.
DELETE /api/v1/me/calendar-meeting-types/{typeKey} with Ken-Version 1.1. Internal
exposure. Needs the meetings and meeting_types features and a member's
credential; a Client seat gets 403. client_id is sent as X-Ken-Workspace-Id.
meetings: resort (the default) has Ken sort the events again from the types that
are left, the ones set by hand included: the upcoming ones and those that started
in the last 30 days within minutes, the older ones stay without a type. move gives
them the type move_to_key (required then: another key of the list). clear leaves
them with no type and Ken never sorts them again. The type's color and brief
switch go with it. A removed built-in type comes back only with a reset.
404 when type_key is not in the caller's list. 409 invalid_state (detail
last_type) for the only type left. 400 with detail meetings out_of_range, or
moveToKey required / invalid.
data: key, meetings, moveToKey (with move), and how many of the caller's events
had the type: changedCount = upcomingCount + pastCount.
granola-connection-get
Read. GET https://api.ken.so/v1/integrations/granola/connection
Read the caller's own Granola connection in the workspace. data.status is not_connected, connected or invalid_key. Not for the Client role.
GET /api/v1/integrations/granola/connection. Internal. Sends Ken-Version 1.1. Fields: provider (granola), status, connectedAs, connectedAt, lastCallFoundAt. lastCallFoundAt is when the connection last found a call Kenso attached to a meeting (UTC), omitted until it finds one. invalid_key means Granola refused the stored personal key: the rep connects again. The key is never returned. not_found while the meetings feature is off for the workspace. Connecting and disconnecting happen in the Kenso app under Settings > Integrations; there is no tool for them.
optiverse-connection-get
Read. GET https://api.ken.so/v1/integrations/optiverse/connection
Read the caller's own Optiverse connection in the workspace. data.status is not_connected, connected or invalid_key. Not for the Client role.
GET /api/v1/integrations/optiverse/connection. Internal. Sends Ken-Version 1.1. Fields: provider (optiverse), status, connectedAt, lastCallFoundAt. Optiverse does not name a key's account, so connectedAs is always omitted. lastCallFoundAt is when the connection last found a call Kenso attached to a meeting (UTC), omitted until it finds one. invalid_key means Optiverse refused the stored key: the rep connects again. The key is never returned. not_found while the meetings feature is off for the workspace. Connecting and disconnecting happen in the Kenso app under Settings > Integrations; there is no tool for them.
get-availability
Read. GET https://api.ken.so/v1/calendar/availability
Query: from date-time, meetingLengthMinutes integer, provider string, timeZone string, to date-time
Return open meeting times for the calling member between from_time and to_time. With no provider, a member whose Google or Outlook calendar is connected to Kenso gets times from it.
GET /api/v1/calendar/availability. Public. Sends Ken-Version 1.1. Requires the
Calendar page (view). client_id is sent as X-Ken-Workspace-Id.
from_time and to_time are ISO-8601 instants (to after from, at most 60 days).
meeting_length_minutes is 5 to 720, the longest meeting type (5 to 480 when a named
provider answers; Kenso's default: the member's default meeting length). time_zone
(IANA) labels each slot (default: the member's time zone).
With provider omitted or "ken", a member whose Kenso Workspace calendar is connected,
in a workspace with the meetings feature, gets slots from Kenso: their working hours
in their time zone, minus busy time on their primary calendar and the gap around
each event, starting on the quarter hour, never in the past. Those answers carry
source "ken". A member whose Kenso Workspace calendar needs reconnecting gets status
unavailable with reason calendar_needs_reconnect (source "ken"): they must reconnect
in Settings > Calendar. Anyone else names calendly, cal_com or hubspot; without a provider
the API answers 400 validation_failed.
Returns {status, slots[{startAt, endAt, timeZone, meetingLengthMinutes}],
bookingLink, reason, source}. status is available, no_availability (reason
calendar_empty) or unavailable (Kenso reasons calendar_not_connected,
calendar_needs_reconnect, calendar_provider_error). Slots overlap: each is one
possible start, not a schedule.
get-calendar-preferences
Read. GET https://api.ken.so/v1/me/calendar-preferences
Return the caller's Calendar settings in a workspace. Time zones, working hours, default length, gap, video default and link, reminder.
GET /api/v1/me/calendar-preferences with Ken-Version 1.1. Internal exposure.
Needs the meetings feature (404 while it is off) and a member's credential (an
API key with no member gets 403). client_id is sent as X-Ken-Workspace-Id.
Never writes: a member who never saved reads the defaults.
data: timeZone (IANA, omitted until chosen), effectiveTimeZone (always set),
secondTimeZone, extraTimeZones (up to 3 IANA ids in display order; secondTimeZone
is its first), meetingTypeColors (type key to #RRGGBB, only the caller's
overrides), meetingTypeBriefs (type key to boolean, only the switches that differ
from the default: on for every type except internal), timeFormat (12h or 24h), weekStart (monday or sunday),
showWeekends, workingHoursStart and workingHoursEnd (HH:mm), workingDays
(monday..sunday), defaultLengthMinutes (default 30), gapMinutes (default 10),
videoDefault, videoLink (the fixed https link, omitted when not set),
reminderMinutes (default 10; 0 is none), showTouches, showTasks, offerOpenTimes,
availability (always set: the saved schedule {timeZone, weekly monday..sunday of
[{start, end}], overrides [{date, ranges}]}, else one built from the working hours
with timeZone null), availabilityCustom (true when a schedule is saved) and
updatedAt (omitted until the first save).
videoDefault is the link a new event with guests gets when the request names no
video: calendar (Meet on a Google calendar, Teams on an Outlook calendar),
google_meet, microsoft_teams, zoom, webex, link (videoLink as the location and a
"Join:" line in the description) or none.
calendar-accounts-list
Read. GET https://api.ken.so/v1/calendar-accounts
Read the caller's own calendar accounts in the workspace and their calendars. Up to three accounts, Google and Outlook together, oldest first. Not for the Client role.
GET /api/v1/calendar-accounts. Internal. Sends Ken-Version 1.1. Published as calendar(operation="calendar-accounts-list"), beside the open times these calendars give. Items: id (cacc_), provider (google or microsoft), email, status (connected or needs_reconnect), access (calendar_and_email: Kenso also uses the mailbox for 1:1 email, replies, knowledge and docs; calendar_only: busy time and bookings only, never a mailbox), connectedAt, calendars. Each calendar is the GET /v1/calendars model: id (cal_), accountId, name, isPrimary, isSelected (Kenso reads busy time from it), isWriteTarget (new bookings and events go there; one per member, across accounts), canWrite, syncStatus. Top level: accountCount and accountLimit (3): at the limit the member disconnects one before adding another. An account that needs a reconnect still counts; a disconnected one is gone. Tokens are never returned. not_found while the meetings feature is off for the workspace. Connecting and disconnecting happen in the Kenso app under Settings > Calendar; there is no tool for them.
list-calendar-meeting-types
Read. GET https://api.ken.so/v1/me/calendar-meeting-types
List the caller's own meeting types in a workspace, in their order. The types Ken sorts the caller's calendar events into. At most 12.
GET /api/v1/me/calendar-meeting-types with Ken-Version 1.1. Internal exposure. Needs the meetings and meeting_types features (404 while either is off) and a member's credential (an API key with no member gets 403). client_id is sent as X-Ken-Workspace-Id. Never writes: a member who never edited reads the eight built-in types. Each member has their own list; it is not shared with teammates. data: the list, never paged. Each type: key (lowercase letters, digits and underscores; it never changes and is what a calendar event's meetingType holds), name, description (the text Ken reads to decide a meeting's type), position (1 is the top; when two types fit a meeting the higher one wins), color (#RRGGBB), icon (omitted when not set), hasBrief (Ken writes a brief before meetings of the type), isBuiltIn (one of sales, customer, networking, partnership, investor, education, recruiting, internal), upcomingCount and pastCount (the caller's own events with the type that are not cancelled).
reorder-calendar-meeting-types
Write. PUT https://api.ken.so/v1/me/calendar-meeting-types/order
Body (json): keys array
Put the caller's own meeting types in a new order. keys lists every key of the list exactly once, top first.
PUT /api/v1/me/calendar-meeting-types/order with Ken-Version 1.1. Internal exposure. Needs the meetings and meeting_types features and a member's credential; a Client seat gets 403. client_id is sent as X-Ken-Workspace-Id. The order decides ties: when two types fit a meeting, the higher one wins. 400 (detail keys invalid) unless keys names every type of the list exactly once. data: the list in the new order. Each type: key (lowercase letters, digits and underscores; it never changes and is what a calendar event's meetingType holds), name, description (the text Ken reads to decide a meeting's type), position (1 is the top; when two types fit a meeting the higher one wins), color (#RRGGBB), icon (omitted when not set), hasBrief (Ken writes a brief before meetings of the type), isBuiltIn (one of sales, customer, networking, partnership, investor, education, recruiting, internal), upcomingCount and pastCount (the caller's own events with the type that are not cancelled). After a write that changes a name, a description, the order or which types exist, Ken sorts the caller's events again from the new list: the upcoming ones it types (14 days ahead) and the ones that started in the last 30 days. Older events keep their type, a type the member set by hand is never changed, and a color, icon or hasBrief change sorts nothing again. It runs in the background within minutes.
reset-calendar-meeting-types
Write. POST https://api.ken.so/v1/me/calendar-meeting-types/reset
Put the eight built-in meeting types back as they started, in the caller's own list. The types the caller added stay, after the built-in ones.
POST /api/v1/me/calendar-meeting-types/reset with Ken-Version 1.1. Internal exposure. Needs the meetings and meeting_types features and a member's credential; a Client seat gets 403. client_id is sent as X-Ken-Workspace-Id. Restores each built-in type's name, description, color, icon, brief switch and place at the top, and brings back any the caller removed. No event's type changes by itself. 409 invalid_state (detail too_many) when the eight built-in types plus the caller's own would be more than 12. data: the list. Each type: key (lowercase letters, digits and underscores; it never changes and is what a calendar event's meetingType holds), name, description (the text Ken reads to decide a meeting's type), position (1 is the top; when two types fit a meeting the higher one wins), color (#RRGGBB), icon (omitted when not set), hasBrief (Ken writes a brief before meetings of the type), isBuiltIn (one of sales, customer, networking, partnership, investor, education, recruiting, internal), upcomingCount and pastCount (the caller's own events with the type that are not cancelled). After a write that changes a name, a description, the order or which types exist, Ken sorts the caller's events again from the new list: the upcoming ones it types (14 days ahead) and the ones that started in the last 30 days. Older events keep their type, a type the member set by hand is never changed, and a color, icon or hasBrief change sorts nothing again. It runs in the background within minutes.
update-calendar-meeting-type
Write. PATCH https://api.ken.so/v1/me/calendar-meeting-types/{typeKey}
Path: typeKey
Body (json): color string, description string, hasBrief boolean, icon string, name string
Change one of the caller's own meeting types. Omitted fields stay unchanged. type_key is the type's key, built-in or added. The key itself never changes.
PATCH /api/v1/me/calendar-meeting-types/{typeKey} with Ken-Version 1.1. Internal
exposure. Needs the meetings and meeting_types features and a member's
credential; a Client seat gets 403. client_id is sent as X-Ken-Workspace-Id.
name, description, color, icon and has_brief follow the create's rules. icon ""
clears the icon; description "" clears the description. 404 when type_key is not
in the caller's list. An event keeps its type through a rename.
data: the changed type. Each type: key (lowercase letters, digits and underscores; it never changes and is
what a calendar event's meetingType holds), name, description (the text Ken reads
to decide a meeting's type), position (1 is the top; when two types fit a meeting
the higher one wins), color (#RRGGBB), icon (omitted when not set), hasBrief (Ken
writes a brief before meetings of the type), isBuiltIn (one of sales, customer,
networking, partnership, investor, education, recruiting, internal), upcomingCount
and pastCount (the caller's own events with the type that are not cancelled).
After a write that changes a name, a description, the order or which types exist,
Ken sorts the caller's events again from the new list: the upcoming ones it types
(14 days ahead) and the ones that started in the last 30 days. Older events keep
their type, a type the member set by hand is never changed, and a color, icon or
hasBrief change sorts nothing again. It runs in the background within minutes.
update-calendar-preferences
Write. PATCH https://api.ken.so/v1/me/calendar-preferences
Body (json): availability object, defaultLengthMinutes integer, extraTimeZones array, gapMinutes integer, meetingTypeBriefs object, meetingTypeColors object, offerOpenTimes boolean, reminderMinutes integer, secondTimeZone string, showTasks boolean, showTouches boolean, showWeekends boolean, timeFormat string, timeZone string, videoDefault string, videoLink string, weekStart string, workingDays array, workingHoursEnd string, workingHoursStart string
Change the caller's own Calendar settings in a workspace. Omit a field to leave it unchanged. "" clears time_zone, second_time_zone, video_link or availability.
PATCH /api/v1/me/calendar-preferences with Ken-Version 1.1. Internal exposure.
Changes only the caller's own row, so any member with the Calendar page can save
theirs. Needs the meetings feature. client_id is sent as X-Ken-Workspace-Id. Send
at least one field.
Fields (all optional):
- time_zone, second_time_zone: IANA id with its exact spelling, such as
Europe/Amsterdam. "" clears it (sent as null).
- time_format: 12h or 24h. week_start: monday or sunday.
- working_hours_start, working_hours_end: HH:mm at any whole minute, such as 08:47,
the end later than the start (24:00 is midnight). Scheduler still offers times on
the quarter hour inside them. working_days: day names, monday to sunday, at least
one.
- default_length_minutes 5 to 480, gap_minutes 0 to 240, reminder_minutes 0
(no reminder) to 40320 (4 weeks): any whole number of minutes.
- video_default: calendar, google_meet, microsoft_teams, zoom, webex, link or none.
google_meet on an Outlook calendar and microsoft_teams on a Google calendar give
that calendar's own link. link needs a saved video_link or one in the same call.
- video_link: an absolute https:// URL, at most 2048 characters. "" clears it
(refused while video_default is link). Choosing another video_default keeps it.
- show_weekends, show_touches, show_tasks, offer_open_times: booleans.
- availability (DEV-3935): the caller's default open times, replacing the whole saved
schedule, used for every meeting type without its own. An object
{timeZone, weekly, overrides}: timeZone is an IANA id or null for the caller's zone;
weekly maps monday..sunday to [{start, end}] in HH:mm at any whole minute (start up
to 23:59, end up to 24:00, at most 6 a day; overlapping ranges are refused, touching
ones join);
overrides is [{date: YYYY-MM-DD, ranges}] (at most 100, unique dates; no ranges
blocks the date). It needs at least one weekly range, and saving it sets the
working hours to its earliest start, latest end and the days with times. ""
clears it (sent as null) and goes back to plain working hours. Without it, a
working hours or days change rewrites a saved schedule's weekly ranges.
- extra_time_zones (DEV-9989): up to 3 IANA ids shown beside the caller's own zone,
in display order, none of them the caller's own zone and none twice. It replaces
the whole list; [] clears it. second_time_zone is its first entry: writing either
updates both (a new second_time_zone replaces the first entry and keeps the rest,
"" clears the whole list; extra_time_zones wins when both are sent).
- meeting_type_colors (DEV-9989): the caller's own colors per built-in meeting type,
an object of type key (sales, customer, networking, partnership, investor,
education, recruiting, internal) to # and six hex digits. A type the caller added
is not here: its color and brief switch are update-calendar-meeting-type's. It replaces the whole map and keeps
only what differs from the default color; {} goes back to the defaults.
- meeting_type_briefs (DEV-9989): whether Ken writes a prep brief per meeting type,
an object of type key to true or false. It replaces the whole map and keeps only
what differs from the default (on for every type except internal); {} goes back
to the defaults.
The read returns availability (the saved schedule, else one built from the working
hours with timeZone null) and availabilityCustom (true when one is saved).
A refused field returns 400 validation_failed with every refusal in error.details
(field path such as availability.weekly.monday[1].end, code required, invalid,
too_long, out_of_range with allowed, end_before_start, overlap,
too_many or duplicate), and nothing is saved. Returns the saved preferences, the
same shape as calendar(operation="get-calendar-preferences").