Skip to content
Docs menu

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.

View .md

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:read to use the tools at all and calendar:write to 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