Calendi

LoginSign Up

Discovery Endpoints

API Discovery Endpoints

These endpoints help developers discover the available resources for an organization. Call these first to get the IDs needed for other API operations.

GET /api/v1/test

Health check and endpoint discovery. Returns organization information and available API endpoints.

Purpose: Verify API connectivity and discover your organization's configuration.

Request

curl -X GET "https://{organization-slug}.calendi.me/api/v1/test" \
  -H "X-API-Key: your-api-key"

Response

{
  "message": "API is working",
  "organization": {
    "id": "org_123",
    "name": "Cosmo Demo School",
    "slug": "cosmo-demo"
  },
  "endpoints": [
    "GET /api/v1/locations",
    "GET /api/v1/grades", 
    "GET /api/v1/events",
    "POST /api/v1/events/{id}/reserve",
    "POST /api/v1/registrations/{id}/confirm"
  ],
  "timestamp": "2024-03-15T10:30:00Z"
}

GET /api/v1/locations

Get all locations available for your organization.

Purpose: Retrieve location IDs and coordinates needed for event filtering and alternative suggestions.

Request

curl -X GET "https://{organization-slug}.calendi.me/api/v1/locations" \
  -H "X-API-Key: your-api-key"

Response

{
  "locations": [
    {
      "id": 1,
      "name": "Main Campus",
      "address": "123 Education Street, Learning City, LC 12345",
      "coordinates": [-74.006, 40.7128]
    },
    {
      "id": 2,
      "name": "North Branch",
      "address": "456 Knowledge Avenue, Study Town, ST 67890",
      "coordinates": [-74.012, 40.7589]
    },
    {
      "id": 3,
      "name": "Community Center",
      "address": "789 Learning Lane, Education Borough, EB 13579",
      "coordinates": [-73.998, 40.6892]
    }
  ]
}

Response Fields

  • id (integer): Unique location identifier for API calls
  • name (string): Display name of the location
  • address (string): Full address for mapping/display
  • coordinates (array): [longitude, latitude] for distance calculations

GET /api/v1/grades

Get all grade levels available for your organization.

Purpose: Retrieve grade IDs needed for event filtering and attendee registration.

Request

curl -X GET "https://{organization-slug}.calendi.me/api/v1/grades" \
  -H "X-API-Key: your-api-key"

Response

{
  "grades": [
    {
      "id": 1,
      "name": "Pre-K"
    },
    {
      "id": 2,
      "name": "Kindergarten"  
    },
    {
      "id": 3,
      "name": "Grade 1"
    },
    {
      "id": 4,
      "name": "Grade 2"
    },
    {
      "id": 5,
      "name": "Grade 3"
    }
  ]
}

Response Fields

  • id (integer): Unique grade identifier for API calls
  • name (string): Display name of the grade level

Usage Flow

  1. Start with /test: Verify API access and get organization info
  2. Get locations: Use /locations to retrieve available venues and their coordinates
  3. Get grades: Use /grades to get available grade levels
  4. Find events: Use the location and grade IDs with /events?location_id=X&grade_id=Y

Example Discovery Sequence

# 1. Test API connectivity
curl -X GET "https://cosmo-demo.calendi.me/api/v1/test" \
  -H "X-API-Key: testapp1a2b.a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"

# 2. Discover locations (get IDs: 1, 2, 3)
curl -X GET "https://cosmo-demo.calendi.me/api/v1/locations" \
  -H "X-API-Key: testapp1a2b.a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"

# 3. Discover grades (get IDs: 1, 2, 3, 4, 5)  
curl -X GET "https://cosmo-demo.calendi.me/api/v1/grades" \
  -H "X-API-Key: testapp1a2b.a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"

# 4. Now use discovered IDs to find events
curl -X GET "https://cosmo-demo.calendi.me/api/v1/events?location_id=1&grade_id=3" \
  -H "X-API-Key: testapp1a2b.a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"

Error Responses

All endpoints return standard error responses:

{
  "error": {
    "code": "UNAUTHORIZED", 
    "message": "Invalid or missing API key"
  }
}

Common error codes:

  • 401: Invalid API key
  • 404: Organization not found
  • 500: Server error

Next Steps

After discovering your organization's resources: