Scheduling Integration

When to use

Use this skill whenever a task requires checking booking availability, creating or managing appointments (events), or looking up/creating contacts in the Scheduling app. Typical triggers: a lead wants to book a meeting, a booking needs to be confirmed, canceled, completed, or rescheduled, or you need to list a resource's upcoming events. Do not use this skill for anything unrelated to scheduling, such as CRM (customer relationship management) records outside of contacts tied to bookings, or email delivery.

Tools

• http-get — read event types, availability, events, and contacts
• http-post — create bookings, events, contacts, and event types
• http-request — update events (PATCH) and trigger status transitions
• write-file — stage large result sets (for example, a full event list) instead of dumping them into the conversation
• send-message — escalate to a human when authentication fails or an Integration is missing

Playbook

1. Discover available booking types before offering times: http-get /api/v1/event_types to list active event types for the current resource.
2. Find open slots for the requested window: http-get /api/v1/availabilities?start_date=&end_date=&event_type_id= to get computed open time slots.
3. If you need slots formatted for a single day (for example, to read out loud or paste into a message), http-get /api/v1/availabilities/formatted?date=&event_type_id=.
4. Before finalizing a specific date/time with a contact, confirm it is still open: http-get /api/v1/availabilities/check_slot?date=&time=&event_type_id=&duration=.
5. Look up the contact by email to avoid duplicates: http-get /api/v1/contacts?email=. If none exists, create one with http-post /api/v1/contacts.
6. Create the booking using the safe, validated path — never the raw event endpoint — with http-post /api/v1/bookings. This endpoint re-validates slot availability and auto-creates or matches the contact.
7. To create an event directly without a slot-availability check (only when explicitly instructed to bypass validation), use http-post /api/v1/events.
8. To update an existing event's time, notes, or other fields, use http-request (PATCH) against /api/v1/events/:id.
9. Advance an event's status as needed: http-request (POST) /api/v1/events/:id/confirm, /api/v1/events/:id/cancel, or /api/v1/events/:id/complete.
10. To review a single event's details, http-get /api/v1/events/:id. To list events with filters (status, event_type_id, contact_id, start_date, end_date), http-get /api/v1/events.
11. If a listing or lookup returns a large result set, write it to disk with write-file rather than including it inline, then summarize the key rows in your response.
12. Never request, echo, or hardcode API keys, tokens, or the X-Organization header — authentication is injected automatically by the org's Integration row for this app.

Failure modes

• A 401 Unauthorized response means the Integration row is missing or its credentials are invalid. Stop immediately and use send-message to notify a human, naming "Scheduling" as the app and stating that its Integration needs to be configured or repaired.
• A 403 Forbidden response means the caller lacks write permission for a mutating call. Stop and use send-message to name "Scheduling" and specify that write access (can_write?) is needed for the calling identity.
• If no Integration row exists for the org at all, do not attempt any call — use send-message right away to request that a Scheduling Integration be added, naming the required scopes (read event types/availability/events/contacts, write bookings/events/contacts).
• If check_slot or availabilities shows a slot as unavailable, do not force a booking through /api/v1/events — report the conflict instead of bypassing validation.

Done when

The requested booking, event update, status transition, or contact record has been created or modified via the appropriate endpoint and confirmed by a follow-up http-get, or a human has been notified via send-message because authentication or an Integration was missing.