Scheduling API

The Scheduling API allows you to manage event types, check availability, create bookings, and configure advanced scheduling features.

Authentication

All API requests require authentication:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.girardai.com/v1/scheduling

Event Types

List Event Types

GET /api/v1/scheduling/event-types

Response

{
  "eventTypes": [
    {
      "id": "evt_123",
      "name": "30-Minute Meeting",
      "slug": "30-min",
      "duration": 30,
      "description": "Quick sync call",
      "locations": [
        { "type": "zoom", "autoCreate": true }
      ],
      "isActive": true,
      "createdAt": "2026-02-01T10:00:00Z"
    }
  ]
}

Create Event Type

POST /api/v1/scheduling/event-types

{
  "name": "Strategy Session",
  "slug": "strategy",
  "duration": 60,
  "description": "In-depth strategy discussion",
  "locations": [
    { "type": "zoom", "autoCreate": true },
    { "type": "phone", "number": "+1-555-0123" }
  ],
  "bufferBefore": 15,
  "bufferAfter": 15,
  "minNotice": 24,
  "maxAdvance": 30,
  "questions": [
    {
      "label": "What would you like to discuss?",
      "type": "textarea",
      "required": true
    }
  ]
}

Update Event Type

PATCH /api/v1/scheduling/event-types/{id}

Delete Event Type

DELETE /api/v1/scheduling/event-types/{id}

Availability

Get Availability

Get available time slots for an event type.

GET /api/v1/scheduling/availability

Parameters

Parameter	Type	Required	Description
eventTypeId	string	Yes	Event type ID
start	date	Yes	Start date (YYYY-MM-DD)
end	date	Yes	End date (YYYY-MM-DD)
timezone	string	No	Timezone (default: UTC)

Response

{
  "slots": [
    {
      "start": "2026-02-10T09:00:00-05:00",
      "end": "2026-02-10T09:30:00-05:00",
      "available": true
    },
    {
      "start": "2026-02-10T09:30:00-05:00",
      "end": "2026-02-10T10:00:00-05:00",
      "available": true
    }
  ],
  "timezone": "America/New_York"
}

Set Availability Rules

PUT /api/v1/scheduling/availability/rules

{
  "timezone": "America/New_York",
  "weeklyHours": {
    "monday": ["09:00-12:00", "13:00-17:00"],
    "tuesday": ["09:00-12:00", "13:00-17:00"],
    "wednesday": ["09:00-12:00", "13:00-17:00"],
    "thursday": ["09:00-12:00", "13:00-17:00"],
    "friday": ["09:00-12:00", "13:00-15:00"],
    "saturday": null,
    "sunday": null
  }
}

Bookings

Create Booking

POST /api/v1/scheduling/bookings

{
  "eventTypeId": "evt_123",
  "start": "2026-02-10T09:00:00-05:00",
  "attendee": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1-555-0123",
    "timezone": "America/New_York"
  },
  "responses": {
    "topic": "Product demo"
  },
  "metadata": {
    "source": "website"
  }
}

Response

{
  "id": "booking_456",
  "eventTypeId": "evt_123",
  "status": "confirmed",
  "start": "2026-02-10T09:00:00-05:00",
  "end": "2026-02-10T09:30:00-05:00",
  "attendee": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "location": {
    "type": "zoom",
    "url": "https://zoom.us/j/123456"
  },
  "confirmationUrl": "https://girardai.com/booking/booking_456",
  "rescheduleUrl": "https://girardai.com/booking/booking_456/reschedule",
  "cancelUrl": "https://girardai.com/booking/booking_456/cancel"
}

Get Booking

GET /api/v1/scheduling/bookings/{id}

List Bookings

GET /api/v1/scheduling/bookings

Parameters

Parameter	Type	Description
eventTypeId	string	Filter by event type
status	string	Filter by status
start	date	Start date range
end	date	End date range
limit	number	Results per page
offset	number	Pagination offset

Reschedule Booking

PATCH /api/v1/scheduling/bookings/{id}/reschedule

{
  "newStart": "2026-02-12T14:00:00-05:00",
  "reason": "Conflict with another meeting",
  "notifyAttendee": true
}

Cancel Booking

DELETE /api/v1/scheduling/bookings/{id}

{
  "reason": "Customer requested cancellation",
  "notifyAttendee": true
}

Advanced Scheduling

Recurring Patterns

Create recurring availability blocks.

POST /api/v1/scheduling/recurring-patterns

{
  "name": "Weekly Team Meeting Prep",
  "pattern": "WEEKLY",
  "interval": 1,
  "daysOfWeek": [1],
  "timeStart": "08:00",
  "timeEnd": "09:00",
  "startDate": "2026-02-01",
  "endDate": "2026-12-31",
  "blockType": "preparation"
}

Pattern Types

Pattern	Description
DAILY	Every N days
WEEKLY	Specific days each week
BI_WEEKLY	Every two weeks
MONTHLY	Specific day of month
MONTHLY_NTH	Nth weekday of month
QUARTERLY	Once per quarter
YEARLY	Annual events

Generate Occurrences

POST /api/v1/scheduling/recurring-patterns/{id}/generate

{
  "count": 10,
  "fromDate": "2026-02-01"
}

Response

{
  "occurrences": [
    {
      "date": "2026-02-03",
      "dayOfWeek": 1,
      "start": "2026-02-03T08:00:00",
      "end": "2026-02-03T09:00:00",
      "isException": false
    }
  ]
}

Blackout Periods

Block specific dates/times.

POST /api/v1/scheduling/blackout-periods

{
  "name": "Company Retreat",
  "start": "2026-03-15",
  "end": "2026-03-18",
  "allDay": true,
  "recurring": false,
  "reason": "Annual company retreat"
}

Business Hours

Configure business hours with exceptions.

PUT /api/v1/scheduling/business-hours

{
  "timezone": "America/New_York",
  "default": {
    "monday": ["09:00-17:00"],
    "tuesday": ["09:00-17:00"],
    "wednesday": ["09:00-17:00"],
    "thursday": ["09:00-17:00"],
    "friday": ["09:00-17:00"]
  },
  "exceptions": [
    {
      "date": "2026-07-04",
      "name": "Independence Day",
      "hours": null
    },
    {
      "date": "2026-12-24",
      "name": "Christmas Eve",
      "hours": ["09:00-12:00"]
    }
  ],
  "holidays": ["US_FEDERAL"]
}

Rate Limiting

Configure booking limits.

PUT /api/v1/scheduling/rate-limits

{
  "dailyMax": 8,
  "weeklyMax": 25,
  "monthlyMax": null,
  "consecutiveMax": 3,
  "minGapMinutes": 15
}

Check Rate Limits

GET /api/v1/scheduling/rate-limits/check

{
  "date": "2026-02-10",
  "eventTypeId": "evt_123"
}

Response

{
  "allowed": true,
  "remaining": {
    "daily": 5,
    "weekly": 18,
    "consecutive": 2
  }
}

Calendar Sync

Connect Calendar

POST /api/v1/scheduling/calendars/connect

{
  "provider": "google",
  "redirectUrl": "https://yourapp.com/callback"
}

List Connected Calendars

GET /api/v1/scheduling/calendars

Sync Calendar

Trigger manual calendar sync.

POST /api/v1/scheduling/calendars/{id}/sync

Webhooks

Booking Events

Subscribe to booking events:

POST /api/v1/scheduling/webhooks

{
  "events": [
    "booking.created",
    "booking.rescheduled",
    "booking.cancelled"
  ],
  "url": "https://yourapp.com/webhooks/scheduling"
}

Webhook Payloads

booking.created

{
  "event": "booking.created",
  "data": {
    "id": "booking_456",
    "eventTypeId": "evt_123",
    "start": "2026-02-10T09:00:00-05:00",
    "attendee": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}

Error Codes

Code	Description
slot_unavailable	Time slot is no longer available
outside_availability	Time is outside available hours
buffer_conflict	Conflicts with buffer time
rate_limit_exceeded	Booking limit reached
notice_too_short	Not enough advance notice
too_far_advance	Too far in the future
blackout_period	Date is in blackout period

---

Previous: Integrations API | Next: Error Codes