Calendi API Documentation

Overview

The Calendi API is a REST API that enables educational institutions to integrate event management capabilities into their existing systems. Built for multi-tenant SaaS architecture, Calendi helps schools manage immersion day events while providing seamless booking experiences for families.

Who Uses the Calendi API

Chat Interfaces: Build conversational booking experiences where families can discover and book events through natural language
Mobile Applications: Create native mobile apps for school communities with event browsing and booking capabilities
Booking Systems: Integrate event management into existing school management systems or parent portals
External Platforms: Connect third-party educational tools and platforms with Calendi's event infrastructure

Key Features

Multi-tenant Architecture: Each organization gets their own subdomain and isolated data
Smart Seat Management: Automatic seat reservations with configurable timeouts
Alternative Suggestions: When preferred locations are full, get nearby alternatives based on distance
Real-time Availability: Live seat counts and booking status updates
Flexible Integration: RESTful design with comprehensive error handling and status codes

API Capabilities

The Calendi API supports the complete event booking lifecycle:

Discovery: Browse available locations, grades, and event types
Search: Find events matching specific criteria with alternative suggestions
Reservation: Secure seats with automatic timeout protection
Confirmation: Complete bookings with payment processing integration

Getting Started

1. Obtain API Access

To use the Calendi API, you'll need:

An active organization account with Calendi
API key credentials for your application

Getting Your API Key

Log into your organization's dashboard at https://{your-organization}.calendi.me
Navigate to Settings > API Keys
Click Create New API Key
Provide an application name and description
Copy your API key (format: appname123.a1b2c3d4e5f6...)

Important: Store your API key securely. It provides full access to your organization's event data and booking capabilities.

2. Base URL Structure

All API requests use your organization's subdomain:

https://{organization-slug}.calendi.me/api/v1/

Examples:

https://cosmo-demo.calendi.me/api/v1/ - Cosmo Demo School
https://riverside-academy.calendi.me/api/v1/ - Riverside Academy
https://tech-high.calendi.me/api/v1/ - Tech High School

3. Authentication

Include your API key in the X-API-Key header with every request:

X-API-Key: your-api-key-here
Content-Type: application/json

4. Quick Start Example

Here's a complete example showing how to discover available events and make a reservation:

# 1. Get available locations and grades
curl -X GET "https://cosmo-demo.calendi.me/api/v1/locations" \
  -H "X-API-Key: testapp1a2b.a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"

# Response
{
  "locations": [
    {
      "id": 1,
      "name": "Main Campus",
      "address": "123 Education St, Learning City",
      "coordinates": [-74.006, 40.7128]
    }
  ]
}

# 2. Find available events
curl -X GET "https://cosmo-demo.calendi.me/api/v1/events?location_id=1&grade_id=2&include_alternatives=true" \
  -H "X-API-Key: testapp1a2b.a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"

# Response
{
  "events": [
    {
      "id": "evt_123",
      "title": "Science Discovery Day",
      "date": "2024-03-15",
      "time_slots": [
        {
          "id": "slot_456",
          "start_time": "09:00",
          "end_time": "12:00",
          "available_seats": 15,
          "max_capacity": 20
        }
      ],
      "location": {
        "id": 1,
        "name": "Main Campus"
      },
      "grade": {
        "id": 2,
        "name": "Grade 2"
      }
    }
  ],
  "alternatives": []
}

# 3. Reserve seats
curl -X POST "https://cosmo-demo.calendi.me/api/v1/events/evt_123/reserve" \
  -H "X-API-Key: testapp1a2b.a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6" \
  -H "Content-Type: application/json" \
  -d '{
    "time_slot_id": "slot_456",
    "attendees": [
      {
        "name": "Emma Johnson",
        "grade_id": 2
      }
    ],
    "contact": {
      "parent_name": "Sarah Johnson",
      "email": "sarah@example.com",
      "phone": "+1-555-0123"
    }
  }'

# Response
{
  "registration": {
    "id": "reg_789",
    "status": "pending",
    "reserved_until": "2024-03-01T15:30:00Z",
    "event": {
      "id": "evt_123",
      "title": "Science Discovery Day"
    },
    "attendees": [
      {
        "name": "Emma Johnson",
        "grade": "Grade 2"
      }
    ]
  },
  "timeout_minutes": 30
}

# 4. Confirm reservation (after payment processing)
curl -X POST "https://cosmo-demo.calendi.me/api/v1/registrations/reg_789/confirm" \
  -H "X-API-Key: testapp1a2b.a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6" \
  -H "Content-Type: application/json" \
  -d '{
    "payment": {
      "transaction_id": "txn_abc123",
      "amount": 25.00,
      "currency": "USD",
      "method": "card"
    }
  }'

# Response
{
  "registration": {
    "id": "reg_789",
    "status": "confirmed",
    "confirmation_code": "CONF-2024-789",
    "event": {
      "id": "evt_123",
      "title": "Science Discovery Day",
      "date": "2024-03-15",
      "time_slot": {
        "start_time": "09:00",
        "end_time": "12:00"
      }
    },
    "attendees": [
      {
        "name": "Emma Johnson",
        "grade": "Grade 2"
      }
    ]
  }
}

5. Next Steps

Now that you've made your first API calls, explore these key areas:

Event Management: Comprehensive event search and filtering
Reservation System: Advanced booking flows and timeout handling
Alternative Locations: Smart suggestions when preferred venues are full
Error Handling: Complete error codes and troubleshooting guide
Webhooks: Real-time notifications for booking updates

Rate Limits

The Calendi API implements rate limiting to ensure fair usage:

Standard tier: 1000 requests per hour
Premium tier: 5000 requests per hour
Enterprise tier: Custom limits available

Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Support

Need help getting started?

Documentation: Complete API reference at /docs
Support Portal: Contact support through your organization dashboard
Status Page: Monitor API availability at status.calendi.me

Ready to build? Check out our complete API reference for detailed endpoint documentation.

Developer Documentation