---
title: Booking pages
description: "Your /meet page: event types, times that are really free, holds while someone fills the form, single-use and one-off links, manual confirmation, the invitee's reschedule and cancel link, and the API and MCP tools behind it."
section: calendar
order: 30
audience: [user, operator, builder, agent]
sources: [services/nodejs-cloud/lib/calendar/booking.ts, services/nodejs-cloud/lib/calendar/public.ts, services/nodejs-cloud/lib/calendar/booking-form.ts, services/nodejs-cloud/lib/calendar/mcp.ts, services/nodejs-cloud/lib/calendar/http.ts, services/nodejs-cloud/app/meet, services/nodejs-cloud/migrations/0203_calendar_booking.sql, docs/adr/0072-venom-calendar.md]
features: [cloud.meet, cloud.page-meet]
---

A booking page lets someone pick a time with you. It offers only the times you are free across every calendar you
connected ([.ics feeds](/docs/calendar/ics-feeds.md) today, Google next), inside your working hours, with your buffers, notice and
limits applied ([how slots are computed](/docs/calendar/overview.md#how-bookable-times-are-computed)).

## Your pages

| Address | What it is |
|---|---|
| `/meet/<handle>` | Your profile: your name, a welcome line and your public event types. |
| `/meet/<handle>/<slug>` | One event type: a month of free days, the times on the day picked, then the form. |
| `/meet/l/<token>` | A single-use or one-off link (below). |
| `/meet/manage/<token>` | The invitee's own booking: the confirmation, "add to calendar", reschedule and cancel. |

Your **handle** is unique across Venom Cloud: 3 to 40 lowercase letters, digits or `-`. Words the cloud uses itself
(`api`, `manage`, `embed`, `admin`, `calendar` and a few more) are reserved.

An **event type** is a kind of meeting: a slug, a title, one or more lengths, a schedule (your working hours in one time
zone, with date overrides for days off), where it happens, buffers before and after, minimum notice, how far ahead
people may book, limits per day or week, and questions. Questions use the same blocks as Venom Forms (short and long
text, choices, phone and so on; file uploads and hidden fields are not offered). A **secret** event type is bookable
but not listed on your profile. An event type that is **off** is gone from its page at once.

When you save a profile, schedule or event type, every problem is listed at once, so you fix them in one go.

## What the invitee sees

The page is drawn on the server and works without JavaScript up to the list of times: the month, the days with free
times and the times themselves are plain links. The invitee's time zone is detected in the browser and can be changed;
an event type set to **lock the time zone** (an in-person meeting) shows your zone only. Several lengths show as a
choice at the top.

After the booking the invitee lands on their manage page: what, when, where, a **Download .ics** button and a
**Google Calendar** link (both made on the page; nothing is sent to Google). If the event type has a **redirect URL**
(https only), the invitee goes there instead, with `booking_id`, `start`, `end`, `status`, `name`, `email` and `event`
added to its query string.

Nothing on these pages loads from outside your cloud: no fonts, scripts or images from elsewhere. They carry the same
strict content security policy as Venom Forms' public pages, are never indexed, and send no referrer.

## Two people, one time

Venom never books the same time twice:

1. **Hold.** Picking a time places a 5-minute hold, so other visitors stop seeing it while the form is filled. One hold
   per browser: picking another time moves it.
2. **Recheck.** On submit, every connected calendar is refreshed (for at most 3 seconds) and the time is checked again
   against fresh busy time, your other bookings and other people's holds. If the refresh runs over, the cached busy
   time is used and the booking is flagged so you can see it was checked against older data.
3. **Book.** The booking is written in one transaction, and the database itself refuses two bookings of yours that
   overlap (buffers included).

If someone else got there first, the invitee sees "That time was just taken" with the next five free times to pick
from. Sending the same form twice (a double click, a retry on a bad connection) returns the first booking, not a
second one.

## Links for one person

From the API or an agent you can make a link to send someone:

- **Single use**: books an event type once, then says it was used.
- **One-off**: a meeting of its own. It books once, can change the lengths, the title and the window of dates offered,
  and works even when the event type is switched off.

A link can expire, and can carry a person and a deal from People and Funnel, which the booking keeps. The link is shown
once; only a hash of it is stored.

## Confirming by hand

An event type set to **manual confirm** makes bookings that wait for you (`pending`). A pending booking holds its time.
Accept it and it is confirmed and written to your calendar; decline it and it is cancelled with the reason `declined`.
Bookings you make yourself (in the app, the API or through an agent) are confirmed at once.

## Reschedule and cancel

The manage link (`/meet/manage/<token>`) is the only way in for the invitee: 32 random bytes, of which only a hash is
stored. A wrong link and a deleted booking look the same.

- **Reschedule** offers the event type's free times. The booking keeps its calendar UID and its sequence number goes up,
  so calendars update the existing event instead of adding a new one.
- **Cancel** marks the booking cancelled and removes the calendar event. Cancelling twice is refused.
- Neither works once the meeting has started.

You can do both from the API and MCP too.

## Limits against abuse

| Check | Limit |
|---|---|
| Page opens per visitor (by a salted hash of the IP) | 60 a minute |
| Time lists per visitor | 120 a minute |
| Holds per visitor | 30 a minute |
| Bookings per visitor | 10 a minute |
| Bookings per invitee email | 5 a minute |
| Live bookings per email per event type | 3 a week |

A booking also needs the page's token (valid for a day), a small proof of work the page solves while the form is filled
(about a second in a browser), and an empty spam trap field. There is no third-party CAPTCHA.

## Events

Each booking change raises an org webhook event (Settings, Webhooks) and an in-process event other Venom products
listen to:

| Event | When |
|---|---|
| `calendar.booking.created` | a booking is made (confirmed, or pending for manual confirm) |
| `calendar.booking.confirmed` | you accept a pending booking |
| `calendar.booking.rescheduled` | the booking moves (with the previous start and end) |
| `calendar.booking.cancelled` | the invitee or you cancel it, or you decline it (`reason: declined`) |
| `calendar.booking.no_show` | you mark the invitee a no-show after the start ([No-shows](/docs/calendar/reminders.md#no-shows)) |

The webhook payload has the booking id, the event type's id and slug, the title, start, end, status, sequence, the
invitee's name, email and time zone, the person and deal, and who made the change. Answers to the questions are not in
it.

## For builders and agents {#agents}

The console API under `/api/workspace/calendar` (the signed-in member) and the workspace REST API under
`/api/v1/calendar` (a member's personal key or an OAuth token) have the same operations as the MCP tools on
`/workspace/mcp/calendar` ([Workspace MCP](/docs/cloud/workspace-mcp)):

| Tool | Does |
|---|---|
| `calendar_profile_get`, `calendar_profile_save` | read or save your profile (handle, name, time zone, welcome) |
| `calendar_schedule_list`, `calendar_schedule_save`, `calendar_schedule_delete` | your working-hour schedules; deleting one moves its event types to the default |
| `calendar_event_type_list`, `calendar_event_type_get`, `calendar_event_type_save`, `calendar_event_type_delete` | event types; a save with an id changes only the fields given |
| `calendar_slots_find` | free times for an event type, shown in a time zone, morning, afternoon or evening first |
| `calendar_link_create` | a single-use or one-off link |
| `calendar_booking_list`, `calendar_booking_get` | your bookings, newest first, with a cursor |
| `calendar_booking_create` | book a time for someone (confirmed at once; `idempotency_key` required) |
| `calendar_booking_reschedule`, `calendar_booking_cancel`, `calendar_booking_confirm` | move, cancel, or accept or decline a pending booking |

Reading needs `calendar:read`, changing `calendar:write`. A team key has no calendar: use a member's personal key.
A time that was taken answers with an error that lists the next free times.

The public API the pages use is open to anyone and lives 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` (the page token), `GET
…/slots?month=YYYY-MM&time_zone=`, `POST …/holds` and `POST …/book`. The manage link has `GET /meet/api/manage/<token>`,
`…/slots`, `POST …/reschedule`, `POST …/cancel` and `GET …/ics`. To put a page on your own site, see
[Embedding](/docs/calendar/embed.md).
