Events API

The Events API allows you to search for available immersion day events with intelligent alternative suggestions.

Endpoint

GET /api/v1/events

Search for events with optional filtering and smart alternatives.

Query Parameters

Response Format

{
  "success": true,
  "data": {
    "primary_results": [...],
    "alternatives": [...]
  }
}

Event Object Structure

{
  "id": 123,
  "location_id": 1,
  "location_name": "Sede Principal",
  "location_address": "Calle 123 #45-67",
  "event_type": "Inmersión",
  "event_date": "2024-12-15",
  "start_time": "09:00:00",
  "end_time": "15:00:00",
  "max_capacity": 30,
  "available_seats": 25,
  "reservation_timeout_minutes": 30,
  "grades": [
    {"id": 2, "grade_name": "2°"},
    {"id": 3, "grade_name": "3°"}
  ]
}

Smart Alternatives Logic

⚠️ Important: Alternatives only appear when:

1. Both location_id AND grade_id are specified
2. AND the preferred location has 0 available seats
3. AND include_alternatives=true

This matches the real family use case: "I want grade 2 at location 1, but if it's full, show me nearby options."

Usage Examples

1. Basic Event Search

Get all upcoming events:

curl -X GET "https://your-org.calendi.me/api/v1/events" \
  -H "X-API-Key: your-api-key"

Response:

{
  "success": true,
  "data": {
    "primary_results": [
      {
        "id": 123,
        "location_name": "Sede Principal",
        "event_date": "2024-12-15",
        "available_seats": 25,
        "grades": [{"id": 2, "grade_name": "2°"}]
      }
    ],
    "alternatives": []
  }
}

2. Location-Specific Search

Get events at specific location (no alternatives):

curl -X GET "https://your-org.calendi.me/api/v1/events?location_id=1" \
  -H "X-API-Key: your-api-key"

Use case: Family wants that specific location only.

3. Grade-Specific Search

Get all locations offering a specific grade (no alternatives):

curl -X GET "https://your-org.calendi.me/api/v1/events?grade_id=2" \
  -H "X-API-Key: your-api-key"

Use case: Family exploring all location options for their child's grade.

4. Preferred Location with Alternatives

The main use case - family prefers specific location and grade:

curl -X GET "https://your-org.calendi.me/api/v1/events?location_id=1&grade_id=2&include_alternatives=true" \
  -H "X-API-Key: your-api-key"

When location has seats:

{
  "success": true,
  "data": {
    "primary_results": [
      {
        "id": 123,
        "location_name": "Sede Principal",
        "available_seats": 10
      }
    ],
    "alternatives": []
  }
}

When location is FULL:

{
  "success": true,
  "data": {
    "primary_results": [
      {
        "id": 123,
        "location_name": "Sede Principal",
        "available_seats": 0
      }
    ],
    "alternatives": [
      {
        "id": 124,
        "location_name": "Sede Norte",
        "available_seats": 15,
        "is_alternative": true
      },
      {
        "id": 125,
        "location_name": "Sede Sur", 
        "available_seats": 8,
        "is_alternative": true
      }
    ]
  }
}

Integration Workflow

1. Discover available options using /locations and /grades
2. Search events with appropriate filters based on user intent
3. Present alternatives only when primary location is full
4. Reserve seats using event IDs from results

Error Responses

Rate Limits

• 100 requests per minute per API key
• Responses include X-RateLimit-* headers
• Contact support for higher limits

Next: Reservations API →