Build on Venom Calendar
Work with a member's calendar from code or an agent. Find free times, book and move meetings, manage event types and schedules, send time offers and group polls over REST or MCP, and put booking pages on your own site.
Venom Calendar is each member's own booking calendar: a profile (the /meet/<handle> page), working-hour schedules,
event types and their bookings, plus the calendars and .ics feeds that block busy time. Every console action is an
MCP tool, and each tool has a REST route under /api/v1/calendar. Booking pages also have a public API that needs no
credential.
What you can build
- Booking from your product. Find free times for an event type (
GET /api/v1/calendar/slots) and book one for a customer (POST /api/v1/calendar/bookings), confirmed at once. - Meeting changes from your CRM. Move or cancel a booking (
POST /api/v1/calendar/bookings/{booking_id}/reschedule,…/cancel) and accept or decline requests on event types with manual confirmation (…/confirm). - Links for one person. Make a single-use or one-off booking link (
POST /api/v1/calendar/links) and send it from your own system. - An agent that schedules for you. Connect
venom-calendar: the agent offers a few held times (calendar_offer_create), sends them (calendar_offer_send) and books the one the person picks (calendar_offer_accept). - Group scheduling. Create a poll for several people (
POST /api/v1/calendar/polls) and close it on the winning time (…/polls/{poll_id}/close). - A booking page on your site. Embed
/meet/<handle>/<slug>with one script and listen for the booking (Embedding).
At a glance
Generated from the code on every docs build.
| MCP endpoint | https://cloud.usevenom.dev/workspace/mcp/calendar, server name venom-calendar |
| Connect | claude mcp add --transport http venom-calendar https://cloud.usevenom.dev/workspace/mcp/calendar |
| MCP tools | 41 (16 read, 25 write) |
| OAuth scopes | calendar:read calendar:write |
| REST twin | 43 routes under https://cloud.usevenom.dev/api/v1 |
| Webhook events | calendar.booking.created, calendar.booking.confirmed, calendar.booking.rescheduled, calendar.booking.cancelled, calendar.booking.no_show |
Authentication and scopes
A calendar belongs to one member, so every caller must be a member:
- A personal API key acts as its member. Turn on "This key is mine" when you create it.
- A team key has no member and gets no calendar. Every calendar tool answers that it needs a member's personal key or OAuth.
- An OAuth app acts as the member who connected it. It needs
calendar:readto use the tools at all andcalendar:writeto change anything.
The member's org role then decides:
- Every member, whatever their role, reads and changes their own profile, schedules, bookings, offers, polls, feeds and connected accounts.
- Event types and their team hosts (
calendar_event_type_save,calendar_event_type_delete,calendar_event_type_hosts_set) need a role that writes in Calendar: owner, admin or developer. Billing members and viewers are refused. - A read-only key, or an OAuth grant without
calendar:write, only reads.
An agent's booking goes through the same race-safe path as the public page. Sending an offer
(calendar_offer_send) goes through Comms, so an agent's send waits for a person's approval unless the Comms profile
allows agents (Agents schedule for you).
Worked example
Find free afternoon times for an event type next week, then book one for a customer:
curl "$VENOM_CLOUD/api/v1/calendar/slots?event_type_id=<event-type-id>&from=2026-11-16T00:00:00Z&to=2026-11-21T00:00:00Z&time_zone=Europe/London&prefer=afternoon&limit=5" \
-H "Authorization: Bearer $VENOM_API_KEY"
curl -X POST "$VENOM_CLOUD/api/v1/calendar/bookings" \
-H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
-H 'Idempotency-Key: demo-dana-2026-11-17' \
-d '{"event_type_id": "<event-type-id>", "start": "2026-11-17T14:00:00Z",
"invitee": {"name": "Dana Reyes", "email": "dana@example.com", "time_zone": "Europe/London"}}'The booking answers 201. A time someone else took first answers slot_taken with the next free times; a retry with
the same Idempotency-Key returns the first result. The same over MCP, from a client connected to
/workspace/mcp/calendar:
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": { "name": "calendar_slots_find",
"arguments": { "event_type_id": "<event-type-id>", "from": "2026-11-16T00:00:00Z", "to": "2026-11-21T00:00:00Z", "time_zone": "Europe/London", "prefer": "afternoon", "limit": 5 } } }{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
"params": { "name": "calendar_booking_create",
"arguments": { "event_type_id": "<event-type-id>", "start": "2026-11-17T14:00:00Z",
"invitee": { "name": "Dana Reyes", "email": "dana@example.com", "time_zone": "Europe/London" },
"idempotency_key": "demo-dana-2026-11-17" } } }Over MCP, idempotency_key is required (8 to 200 characters). List event types and their ids with
calendar_event_type_list (GET /api/v1/calendar/event-types).
The public booking API
The booking pages use an API that is open to anyone, under /meet/api: GET /meet/api/<handle>, and for an event type
(/meet/api/<handle>/<slug>) or a link (/meet/api/l/<token>) POST …/open, GET …/slots, POST …/holds and
POST …/book. It is rate limited per visitor and needs the page token and a small proof of work, so build on it
through the embed script rather than calling it from a server. Details and limits:
Booking pages.
Events
5 org webhook events, generated from lib/webhooks/events.ts. Subscribe an endpoint to them in Settings, Webhooks (see Webhooks and events).
| Event | When |
|---|---|
calendar.booking.created |
Someone booked a time on a Venom Calendar booking page (or the owner booked for them): the booking, event type, time, status (confirmed, or pending when it needs your confirmation), and the invitee's name, email and time zone. Never their answers. |
calendar.booking.confirmed |
The owner confirmed a pending booking. |
calendar.booking.rescheduled |
A booking moved to a new time, by the invitee from their link or by the owner: the new time, the previous one and the invite's sequence. |
calendar.booking.cancelled |
A booking was cancelled by the invitee or the owner, or a pending one was declined: the reason given, if any. |
calendar.booking.no_show |
The owner marked a booking as a no-show after its start: the booking, its time and the invitee (Funnel can move the deal back). |
An embedded booking page also fires a venom-meet:booked DOM event on your page when someone books, with the booking id
and start (Embedding). The webhook payload fields are listed on
Booking pages.
REST routes
The REST twin: 43 routes under https://cloud.usevenom.dev/api/v1, each calling the MCP tool named in its row with the same arguments (see the REST twin).
/calendar/profile
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/calendar/profile |
Your booking profile (the /meet/<handle> page) | calendar_profile_get |
| PUT | /api/v1/calendar/profile |
Create or change your booking profile | calendar_profile_save |
/calendar/schedules
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/calendar/schedules |
Your working-hour schedules | calendar_schedule_list |
| POST | /api/v1/calendar/schedules |
Add a working-hour schedule | calendar_schedule_save |
| PUT | /api/v1/calendar/schedules/{schedule_id} |
Change a schedule | calendar_schedule_save |
| DELETE | /api/v1/calendar/schedules/{schedule_id} |
Delete a schedule (its event types fall back to the default) | calendar_schedule_delete |
/calendar/event-types
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/calendar/event-types |
Your bookable kinds of meeting | calendar_event_type_list |
| POST | /api/v1/calendar/event-types |
Add an event type | calendar_event_type_save |
| GET | /api/v1/calendar/event-types/{event_type_id} |
Read an event type with all its rules | calendar_event_type_get |
| PUT | /api/v1/calendar/event-types/{event_type_id} |
Change an event type (fields left out keep their value) | calendar_event_type_save |
| DELETE | /api/v1/calendar/event-types/{event_type_id} |
Delete an event type (its bookings stay) | calendar_event_type_delete |
| GET | /api/v1/calendar/event-types/{event_type_id}/hosts |
An event type's kind, round-robin rules and hosts | calendar_event_type_hosts_get |
| PUT | /api/v1/calendar/event-types/{event_type_id}/hosts |
Make an event type collective or round robin, and set its hosts | calendar_event_type_hosts_set |
/calendar/links
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| POST | /api/v1/calendar/links |
A single-use or one-off booking link (shown once) | calendar_link_create |
/calendar/slots
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/calendar/slots |
Free times for an event type | calendar_slots_find |
/calendar/bookings
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/calendar/bookings |
Bookings, newest first | calendar_booking_list |
| POST | /api/v1/calendar/bookings |
Book a free time for someone (confirmed at once; a taken time answers slot_taken with the next free times) | calendar_booking_create |
| GET | /api/v1/calendar/bookings/{booking_id} |
Read a booking | calendar_booking_get |
| POST | /api/v1/calendar/bookings/{booking_id}/reschedule |
Move a booking to a new start (same invite, sequence + 1) | calendar_booking_reschedule |
| POST | /api/v1/calendar/bookings/{booking_id}/cancel |
Cancel a booking and remove its calendar event | calendar_booking_cancel |
| POST | /api/v1/calendar/bookings/{booking_id}/confirm |
Accept or decline (accept: false) a pending booking | calendar_booking_confirm |
| POST | /api/v1/calendar/bookings/{booking_id}/no-show |
Mark a past booking as a no-show (rebook: true emails a fresh link) | calendar_booking_mark_no_show |
| POST | /api/v1/calendar/bookings/{booking_id}/resend-invite |
Email the invitee the calendar invite again | calendar_booking_resend_invite |
/calendar/reminders
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/calendar/reminders |
Invites, reminders and follow-ups, with why one fell back or wasn't sent | calendar_reminder_list |
/calendar/offers
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/calendar/offers |
Your offers, newest first, with any reply waiting | calendar_offer_list |
| POST | /api/v1/calendar/offers |
Find and hold a few free times for one person, with a single-use link and a ready text | calendar_offer_create |
| GET | /api/v1/calendar/offers/{offer_id} |
Read an offer: the times still held, the link, sends and the reply | calendar_offer_get |
| POST | /api/v1/calendar/offers/{offer_id}/cancel |
Withdraw an offer: release the held times and stop the link | calendar_offer_cancel |
| POST | /api/v1/calendar/offers/{offer_id}/send |
Send the offer through Comms or email (an agent's send waits for approval unless a profile allows agents) | calendar_offer_send |
| POST | /api/v1/calendar/offers/{offer_id}/accept |
Book the offered time the invitee chose; the other holds go | calendar_offer_accept |
| POST | /api/v1/calendar/offers/{offer_id}/dismiss |
Clear an offer's reply suggestion | calendar_offer_dismiss |
/calendar/polls
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/calendar/polls |
Your group polls | calendar_poll_list |
| POST | /api/v1/calendar/polls |
Propose times to a group and get a link to send (the times are held) | calendar_poll_create |
| GET | /api/v1/calendar/polls/{poll_id} |
A group poll with everyone's answers | calendar_poll_get |
| POST | /api/v1/calendar/polls/{poll_id}/close |
Book the chosen time for everyone who can make it, or just close the poll | calendar_poll_close |
/calendar/accounts
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/calendar/accounts |
Your connected calendar accounts (Google, Microsoft, CalDAV) | calendar_account_list |
| DELETE | /api/v1/calendar/accounts/{account_id} |
Disconnect a calendar account (its calendars stop being checked) | calendar_account_remove |
/calendar/calendars
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/calendar/calendars |
The calendars of your connected accounts, with what each is used for | calendar_calendar_list |
| PATCH | /api/v1/calendar/calendars/{calendar_id} |
Change how a calendar is used: conflicts, busy rules, invites, colour, time zone | calendar_calendar_update |
/calendar/feeds
| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | /api/v1/calendar/feeds |
The ICS feeds you subscribed to as busy time | calendar_feed_list |
| POST | /api/v1/calendar/feeds |
Subscribe to an ICS feed as busy time | calendar_feed_add |
| PATCH | /api/v1/calendar/feeds/{feed} |
Rename a feed or change its URL | calendar_feed_update |
| DELETE | /api/v1/calendar/feeds/{feed} |
Stop subscribing to a feed | calendar_feed_remove |
Every calendar tool has a REST route, connected accounts (GET /api/v1/calendar/accounts), their calendars
(GET /api/v1/calendar/calendars, PATCH …/calendars/{calendar_id}), .ics feeds (/api/v1/calendar/feeds) and
reminders (GET /api/v1/calendar/reminders) included.
MCP tools
41 tools: 16 read, 25 write. Generated from the code; "write (destructive)" is the tool's destructiveHint. A tool with a REST route is the same call over HTTP.
| Tool | Title | Access | Scope | REST route |
|---|---|---|---|---|
calendar_account_list |
List calendar accounts | read | calendar:read |
GET /api/v1/calendar/accounts |
calendar_account_remove |
Disconnect a calendar account | write (destructive) | calendar:write |
DELETE /api/v1/calendar/accounts/{account_id} |
calendar_booking_cancel |
Cancel a booking | write (destructive) | calendar:write |
POST /api/v1/calendar/bookings/{booking_id}/cancel |
calendar_booking_confirm |
Confirm or decline a request | write | calendar:write |
POST /api/v1/calendar/bookings/{booking_id}/confirm |
calendar_booking_create |
Book a time | write | calendar:write |
POST /api/v1/calendar/bookings |
calendar_booking_get |
Read a booking | read | calendar:read |
GET /api/v1/calendar/bookings/{booking_id} |
calendar_booking_list |
List bookings | read | calendar:read |
GET /api/v1/calendar/bookings |
calendar_booking_mark_no_show |
Mark a no-show | write | calendar:write |
POST /api/v1/calendar/bookings/{booking_id}/no-show |
calendar_booking_reschedule |
Move a booking | write | calendar:write |
POST /api/v1/calendar/bookings/{booking_id}/reschedule |
calendar_booking_resend_invite |
Resend the invite | write | calendar:write |
POST /api/v1/calendar/bookings/{booking_id}/resend-invite |
calendar_calendar_list |
List calendars | read | calendar:read |
GET /api/v1/calendar/calendars |
calendar_calendar_update |
Change a calendar's rules | write | calendar:write |
PATCH /api/v1/calendar/calendars/{calendar_id} |
calendar_event_type_delete |
Delete an event type | write (destructive) | calendar:write |
DELETE /api/v1/calendar/event-types/{event_type_id} |
calendar_event_type_get |
Read an event type | read | calendar:read |
GET /api/v1/calendar/event-types/{event_type_id} |
calendar_event_type_hosts_get |
Read an event type's hosts | read | calendar:read |
GET /api/v1/calendar/event-types/{event_type_id}/hosts |
calendar_event_type_hosts_set |
Set an event type's hosts | write | calendar:write |
PUT /api/v1/calendar/event-types/{event_type_id}/hosts |
calendar_event_type_list |
List event types | read | calendar:read |
GET /api/v1/calendar/event-types |
calendar_event_type_save |
Save an event type | write | calendar:write |
POST /api/v1/calendar/event-types (+1) |
calendar_feed_add |
Add an .ics feed | write | calendar:write |
POST /api/v1/calendar/feeds |
calendar_feed_list |
List .ics feeds | read | calendar:read |
GET /api/v1/calendar/feeds |
calendar_feed_remove |
Remove an .ics feed | write (destructive) | calendar:write |
DELETE /api/v1/calendar/feeds/{feed} |
calendar_feed_update |
Change an .ics feed | write | calendar:write |
PATCH /api/v1/calendar/feeds/{feed} |
calendar_link_create |
Create a booking link | write | calendar:write |
POST /api/v1/calendar/links |
calendar_offer_accept |
Book an offered time | write | calendar:write |
POST /api/v1/calendar/offers/{offer_id}/accept |
calendar_offer_cancel |
Withdraw an offer | write (destructive) | calendar:write |
POST /api/v1/calendar/offers/{offer_id}/cancel |
calendar_offer_create |
Offer times to someone | write | calendar:write |
POST /api/v1/calendar/offers |
calendar_offer_dismiss |
Dismiss a reply | write | calendar:write |
POST /api/v1/calendar/offers/{offer_id}/dismiss |
calendar_offer_get |
Read an offer | read | calendar:read |
GET /api/v1/calendar/offers/{offer_id} |
calendar_offer_list |
List offers | read | calendar:read |
GET /api/v1/calendar/offers |
calendar_offer_send |
Send an offer | write | calendar:write |
POST /api/v1/calendar/offers/{offer_id}/send |
calendar_poll_close |
Close a group poll | write | calendar:write |
POST /api/v1/calendar/polls/{poll_id}/close |
calendar_poll_create |
Create a group poll | write | calendar:write |
POST /api/v1/calendar/polls |
calendar_poll_get |
Read a group poll | read | calendar:read |
GET /api/v1/calendar/polls/{poll_id} |
calendar_poll_list |
List group polls | read | calendar:read |
GET /api/v1/calendar/polls |
calendar_profile_get |
Read the booking profile | read | calendar:read |
GET /api/v1/calendar/profile |
calendar_profile_save |
Save the booking profile | write | calendar:write |
PUT /api/v1/calendar/profile |
calendar_reminder_list |
List invites and reminders | read | calendar:read |
GET /api/v1/calendar/reminders |
calendar_schedule_delete |
Delete a schedule | write (destructive) | calendar:write |
DELETE /api/v1/calendar/schedules/{schedule_id} |
calendar_schedule_list |
List schedules | read | calendar:read |
GET /api/v1/calendar/schedules |
calendar_schedule_save |
Save a schedule | write | calendar:write |
POST /api/v1/calendar/schedules (+1) |
calendar_slots_find |
Find free times | read | calendar:read |
GET /api/v1/calendar/slots |