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

Currently, there is no rate limiting implemented. Please be respectful and avoid excessive requests. Rate limiting may be added in future versions.