API Reference

The BlendedCal REST API lets you build integrations, automate workflows, and manage your calendars programmatically.

Authentication

The BlendedCal API supports two authentication methods:

1. Bearer Token (Recommended for Apps & Scripts)

Bearer tokens are API keys you generate from your profile page. They're perfect for mobile apps, scripts, and third-party integrations.

How to create an API key:

1. Log into BlendedCal
2. Go to Profile → API Keys
3. Click Generate API Key
4. Give it a name (e.g., "iOS App", "Python Script")
5. Select permissions (read-only or read/write for each resource type)
6. Optionally set an expiration date
7. Click Create and copy the token

Using the token:

curl https://blendedcal.com/api/sources \
  -H "Authorization: Bearer YOUR_API_KEY"

2. Session Cookie (For Swagger UI and Web Usage)

When you're logged into the BlendedCal web app, your session cookie automatically authenticates API requests. This is how the Swagger UI works.

Token Permissions

When creating an API key, you can grant specific permissions:

API Endpoints

All endpoints are relative to https://blendedcal.com/api (or your deployment URL).

Sources

Calendars

Events

Other Endpoints

Request and Response Format

Request Body

All POST and PATCH requests should include a JSON body with Content-Type: application/json.

Success Response

{
  "data": { ... },
  "total": 42  // Only for list endpoints
}

Error Response

{
  "error": "Error message",
  "details": "Additional error details (optional)"
}

Error Codes

Example Requests

List All Sources

curl https://blendedcal.com/api/sources \
  -H "Authorization: Bearer YOUR_API_KEY"

Create a Source

curl -X POST https://blendedcal.com/api/sources \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Carter Soccer",
    "url": "https://teamsnap.com/calendar/ics/...",
    "tags": ["carter", "sports", "soccer"],
    "filterText": "game",
    "isActive": true
  }'

Get Filtered Events

curl "https://blendedcal.com/api/events?startAfter=2024-03-01T00:00:00Z&limit=20&search=game" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create a Blended Calendar

curl -X POST https://blendedcal.com/api/calendars \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Carter Schedule",
    "slug": "carter",
    "description": "All of Carter'''s events",
    "meta": {
      "anyTags": ["carter"],
      "filterText": null
    }
  }'

Rate Limiting

Rate limits are enforced per user for authenticated API requests and per IP for unauthenticated requests. Most authenticated API requests allow 100 requests per minute. Higher-impact actions have tighter limits: creating sources or calendars allows 10 requests per minute, fetching events for a calendar allows 30 requests per minute, and manual source syncs allow 5 requests per minute for each source.

Public shared calendar feeds have separate per-IP limits: 100 ICS requests per hour and 300 JSON requests per hour. When a limit is exceeded, BlendedCal returns a 429 response withRetry-After, X-RateLimit-Limit, and X-RateLimit-Remainingheaders so integrations can back off gracefully.