API Reference

curl -H "Authorization: Bearer gck_your_api_key_here" \
  https://gudcal.com/api/v1/me

{
  "error": "Description of what went wrong"
}

{
  "id": "clx...",
  "name": "Tim Uzua",
  "email": "tim@gudcal.com",
  "username": "tim",
  "timezone": "America/New_York",
  "bio": "Building GudCal",
  "weekStart": 1
}

{
  "name": "Tim Uzua",
  "username": "tim",
  "timezone": "Africa/Lagos",
  "bio": "Building open-source scheduling",
  "weekStart": 1
}

[
  {
    "id": "clx...",
    "title": "30-Minute Call",
    "slug": "30-min-call",
    "description": "A quick intro call",
    "duration": 30,
    "locationType": "GOOGLE_MEET",
    "isActive": true,
    "requiresConfirmation": false,
    "bufferBefore": 5,
    "bufferAfter": 5,
    "minimumNotice": 120,
    "maxBookingsPerDay": null,
    "slotInterval": null,
    "color": "#0069FF",
    "availability": { "id": "clx...", "name": "Working Hours" },
    "bookingCount": 42
  }
]

{
  "title": "Discovery Call",
  "slug": "discovery-call",
  "description": "Let's explore how we can work together",
  "duration": 45,
  "locationType": "GOOGLE_MEET",
  "requiresConfirmation": false,
  "bufferBefore": 5,
  "bufferAfter": 10,
  "minimumNotice": 240,
  "maxBookingsPerDay": 5
}

{
  "id": "clx...",
  "title": "Discovery Call",
  "slug": "discovery-call",
  "duration": 45,
  "isActive": true,
  "bookingUrl": "https://gudcal.com/tim/discovery-call"
}

{
  "title": "Updated Call",
  "duration": 60,
  "isActive": false
}

[
  {
    "id": "clx...",
    "name": "Working Hours",
    "timezone": "America/New_York",
    "isDefault": true,
    "rules": [
      { "dayOfWeek": 1, "startTime": "09:00", "endTime": "17:00" },
      { "dayOfWeek": 2, "startTime": "09:00", "endTime": "17:00" },
      { "dayOfWeek": 3, "startTime": "09:00", "endTime": "17:00" },
      { "dayOfWeek": 4, "startTime": "09:00", "endTime": "17:00" },
      { "dayOfWeek": 5, "startTime": "09:00", "endTime": "17:00" }
    ],
    "dateOverrides": [
      { "date": "2025-12-25", "isBlocked": true }
    ]
  }
]

{
  "name": "Business Hours",
  "timezone": "America/New_York",
  "isDefault": true,
  "rules": [
    { "dayOfWeek": 1, "startTime": "09:00", "endTime": "12:00" },
    { "dayOfWeek": 1, "startTime": "13:00", "endTime": "17:00" },
    { "dayOfWeek": 2, "startTime": "09:00", "endTime": "17:00" },
    { "dayOfWeek": 3, "startTime": "09:00", "endTime": "17:00" },
    { "dayOfWeek": 4, "startTime": "09:00", "endTime": "17:00" },
    { "dayOfWeek": 5, "startTime": "09:00", "endTime": "15:00" }
  ]
}

[
  {
    "uid": "abc-123-def",
    "eventType": "Discovery Call",
    "eventSlug": "discovery-call",
    "guestName": "Jane Doe",
    "guestEmail": "jane@example.com",
    "guestTimezone": "America/Chicago",
    "startTime": "2025-01-15T14:00:00.000Z",
    "endTime": "2025-01-15T14:45:00.000Z",
    "status": "CONFIRMED",
    "notes": "Looking forward to chatting!"
  }
]

{
  "action": "confirm"
}

{
  "action": "cancel",
  "reason": "Schedule conflict"
}

[
  {
    "id": "clx...",
    "name": "My Agent Key",
    "key": "gck_a1b2...x9y0",
    "expiresAt": "2026-01-15T00:00:00.000Z",
    "lastUsed": "2025-06-10T14:30:00.000Z",
    "createdAt": "2025-01-01T00:00:00.000Z"
  }
]

{
  "name": "Production Agent",
  "expiresInDays": 90
}

{
  "id": "clx...",
  "name": "Production Agent",
  "key": "gck_a1b2c3d4e5f6...",
  "expiresAt": "2025-04-15T00:00:00.000Z"
}

{
  "eventTypeId": "clx...",
  "startTime": "2025-01-15T14:00:00.000Z",
  "guestName": "Jane Doe",
  "guestEmail": "jane@example.com",
  "guestTimezone": "America/New_York",
  "notes": "Looking forward to our call"
}

{
  "event": "BOOKING_CREATED",
  "data": {
    "bookingUid": "abc-123",
    "eventType": "30-min-call",
    "guestName": "Jane Doe",
    "guestEmail": "jane@example.com",
    "startTime": "2025-01-15T14:00:00.000Z",
    "endTime": "2025-01-15T14:30:00.000Z"
  },
  "timestamp": "2025-01-14T10:00:00.000Z"
}

import { createHmac } from "crypto";
 
function verifySignature(payload, signature, secret) {
  const expected = createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return expected === signature;
}

# Step 1: Set up profile
curl -X PUT https://gudcal.com/api/v1/me \
  -H "Authorization: Bearer gck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"username": "tim", "timezone": "Africa/Lagos"}'
 
# Step 2: Create availability schedule
curl -X POST https://gudcal.com/api/v1/availability \
  -H "Authorization: Bearer gck_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Business Hours",
    "timezone": "Africa/Lagos",
    "isDefault": true,
    "rules": [
      {"dayOfWeek": 1, "startTime": "09:00", "endTime": "17:00"},
      {"dayOfWeek": 2, "startTime": "09:00", "endTime": "17:00"},
      {"dayOfWeek": 3, "startTime": "09:00", "endTime": "17:00"},
      {"dayOfWeek": 4, "startTime": "09:00", "endTime": "17:00"},
      {"dayOfWeek": 5, "startTime": "09:00", "endTime": "15:00"}
    ]
  }'
 
# Step 3: Create event types
curl -X POST https://gudcal.com/api/v1/event-types \
  -H "Authorization: Bearer gck_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Quick Chat",
    "slug": "quick-chat",
    "duration": 15,
    "description": "A quick 15-minute chat"
  }'
 
curl -X POST https://gudcal.com/api/v1/event-types \
  -H "Authorization: Bearer gck_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Strategy Session",
    "slug": "strategy-session",
    "duration": 60,
    "requiresConfirmation": true,
    "bufferBefore": 10,
    "bufferAfter": 10
  }'
 
# Booking page is now live at gudcal.com/tim
 
# Step 4: Check pending bookings
curl https://gudcal.com/api/v1/bookings?filter=pending \
  -H "Authorization: Bearer gck_your_key"
 
# Step 5: Confirm a pending booking
curl -X PATCH https://gudcal.com/api/v1/bookings/abc-123 \
  -H "Authorization: Bearer gck_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "confirm"}'