Skip to content

Calendar

Your schedule, booking pages and services.

Open Calendar
Checked against the dashboard on November 19, 2026

Calendar has public methods for the two sides of a booking. Some act for you, the owner, and take your API key: they read your setup and your bookings, set up resources, services and pages, hold and confirm a time, cancel, and change the plan. Others are the ones a booking page makes for a visitor. They need no key, only the page's key.

Sharing calendars with other people, the views, tasks, day events and Calendar settings are done in the dashboard. They have no public method today.

Send a request to a method with your key:

curl -s https://xuda.ai/cpi/get_calendar_setup \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_API_KEY","uid":"YOUR_ACCOUNT_UID"}'
const res = await fetch('https://xuda.ai/cpi/get_calendar_setup', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    api_key: 'YOUR_API_KEY',
    uid: 'YOUR_ACCOUNT_UID',
  }),
});
const { code, data } = await res.json();
import requests

res = requests.post(
    'https://xuda.ai/cpi/get_calendar_setup',
    json={
        'api_key': 'YOUR_API_KEY',
        'uid': 'YOUR_ACCOUNT_UID',
    },
)

A good answer has code 1. A change your plan does not include is refused with code -62 and a sentence in data, for example that group sessions need Growth or that your plan holds a number of booking pages. To act on the calendar of an account that shared it with you at the edit level, pass its share_id to the methods that take one.

Read your setup and bookings

  • get_calendar_setup answers everything the Calendar screens draw in one call: the bookable people and rooms with their hours, the services, and the published booking pages with their public addresses.
  • get_calendar_bookings lists bookings, upcoming by default. Pass past set to true for the ones that already happened, newest first, and limit for how many. Each row carries the time in the resource's zone, the guest's details and anything they said when booking.
  • get_calendar_slots lists the bookable times of one service on one resource between from_ts and to_ts (epoch milliseconds), with everything already taken left out.

Set up what can be booked

  • save_calendar_resource makes or updates something that can be booked: a person, a room, a chair or a device. It needs a timezone, an IANA zone such as Asia/Jerusalem, and its hours are read in that zone. Omit resource_id to make a new one.
  • save_calendar_service makes or updates what people can book: its length, buffers, notice, how far ahead it can be booked, seats, where it meets (meeting_kind), and, with price_cents, currency and checkout, what it costs and whether it is paid at booking. More than one seat needs a plan that includes group sessions, and taking payment needs a plan that includes payments.
  • save_calendar_page makes or updates a booking page: its title, intro, the service_ids it offers, whether it is enabled, its accent colour, its bg_color and text_color (each #rrggbb, or empty to have the page make it from the accent), show_host, whether visitors can change their booking (visitor_changes, change_hours, refund_percent) and the finance account it is paid into (finance_account_id). Making a page past your plan's page limit is refused.
  • delete_calendar_item removes a resource, a service or a page by item_id. Bookings are never deleted this way: they are cancelled.

Book a time yourself

Booking from your own code is two steps, so one time is never sold twice.

Hold the time

hold_calendar_slot reserves a time for a few minutes. Pass resource_id, service_id and start_utc (epoch milliseconds). A good answer has data with occ_id, hold_token and expires_at. Send an idem_key so a repeat of the call returns the same hold instead of taking a second seat.

Confirm it

confirm_calendar_booking turns the hold into a booking. Pass the occ_id and hold_token from the hold, and the guest's name, email, phone and note. A hold that is no longer there has lost the time and is refused.

curl -s https://xuda.ai/cpi/hold_calendar_slot \
  -H 'content-type: application/json' \
  -d '{"api_key":"YOUR_API_KEY","uid":"YOUR_ACCOUNT_UID","resource_id":"RESOURCE_ID","service_id":"SERVICE_ID","start_utc":1793000000000}'
const res = await fetch('https://xuda.ai/cpi/hold_calendar_slot', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    api_key: 'YOUR_API_KEY',
    uid: 'YOUR_ACCOUNT_UID',
    resource_id: 'RESOURCE_ID',
    service_id: 'SERVICE_ID',
    start_utc: 1793000000000,
  }),
});
const { code, data } = await res.json();
import requests

res = requests.post(
    'https://xuda.ai/cpi/hold_calendar_slot',
    json={
        'api_key': 'YOUR_API_KEY',
        'uid': 'YOUR_ACCOUNT_UID',
        'resource_id': 'RESOURCE_ID',
        'service_id': 'SERVICE_ID',
        'start_utc': 1793000000000,
    },
)

Change a booking

  • cancel_calendar_booking cancels by booking_id and puts the time back on the public grid. It is safe to call twice. It only frees the time: it does not email the guest or refund a payment, which the dashboard's Cancel appointment does for a guest who booked through your page.
  • notify_calendar_guests emails everyone invited to one booking, one message each, with the calendar invite attached and an optional message of up to 2000 characters. kind is invite for a new appointment and update for a change, which is the default. The email comes from your own mailbox on a plan that includes it, and from Xuda's booking address otherwise, with your address as the reply-to.
  • create_booking_room makes the Xuda Meet room of a confirmed video booking that has none, and sends each guest the link.

What a booking page calls

A booking page works with its page key, <uid>.<page_id>, and no account.

  • get_booking_bootstrap answers what a page needs to draw itself: its title, its services and a fresh anti-bot token.
  • get_public_booking_slots lists the times a visitor can choose, each with a start, an end and a seat count. It never says who holds the other seats.
  • public_book_slot takes a booking from a visitor. Pass the page_key, service_id, start_utc, the token, and the visitor's name and email. Add an idem_key so a double press does not book twice. company_website is a trap for bots: leave it empty.
  • For a service that is paid when booking, public_start_paid_booking holds the time and starts the payment, start_booking_payment sends a held time to Stripe, and public_confirm_paid_booking and confirm_paid_booking book it once the payment has cleared. The payment is read back from Stripe before anything is booked.
  • A visitor manages a booking from the private link in their email. get_public_booking, public_cancel_booking and public_reschedule_booking take the page key and that link's manage value. They follow the page's rules: whether visitors may change a booking, and up to how many hours before it starts. A paid booking is refunded first, by the page's refund percent.

The plan

get_calendar_plans answers the four tiers with their prices and what each one carries, which plan you are on and whether Calendar is switched on. calendar_set_plan switches it on, changes the tier or switches it off: pass plan_id as calendar_free, calendar_starter, calendar_growth or calendar_business, or set deactivate to true. See Plans and billing.

All the methods

How is this guide?

Last updated on November 18, 2026