REST API Overview

Recal's REST API provides a standardized interface for calendar operations across providers. All endpoints follow RESTful principles with JSON payloads.

Base URL

https://api.recal.dev/v1

Authentication

Authenticate requests using your API key in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.recal.dev/v1/users

Generate API keys in the Recal Dashboard under API Keys. Keys are scoped to organizations for secure access control.

Core Endpoints

Scheduling

Find optimal time slots across users or organizations, accounting for timezones, working hours, and availability.

Typical Workflow

1. Check free/busy periods
2. Query available slots
3. Create events in calendars
4. Verify OAuth connections

• GET /v1/users/{userId}/scheduling - Available slots for a user
• GET /v1/organizations/{orgSlug}/scheduling - Available slots across an organization

Users

Manage users within organizations. Users serve as the primary entities for calendar connections.

• GET /v1/users - List organization users
• POST /v1/users - Create a user
• GET /v1/users/{userId} - Get user details
• PUT /v1/users/{userId} - Update user
• DELETE /v1/users/{userId} - Delete user

After creating users:

• Connect via OAuth
• Manage events
• Check availability

Organizations

Handle multi-tenant structures with organizations for grouping users and managing access.

• GET /v1/organizations - List organizations
• POST /v1/organizations - Create organization
• GET /v1/organizations/{orgSlug} - Get details
• PUT /v1/organizations/{orgSlug} - Update organization
• DELETE /v1/organizations/{orgSlug} - Delete organization

Calendar Operations

Perform event management and availability checks for connected calendars.

• GET /v1/users/{userId}/calendar/free-busy - User's busy periods
• GET /v1/organizations/{orgSlug}/calendar/free-busy - Organization's busy periods

OAuth Connections

Connect users to calendar providers and manage authorizations.

Supported providers:

• Google Calendar
• Microsoft Outlook

Connection Flow

1. Generate authorization URL
2. User grants access
3. Establish connection
4. Access calendar data

• GET /v1/users/{userId}/oauth - List connections
• POST /v1/users/{userId}/oauth/{provider}/authorize - Start OAuth flow
• DELETE /v1/users/{userId}/oauth/{provider} - Remove connection

Interactive Documentation

Test endpoints in real-time:

• Swagger UI - Interactive explorer with schemas and examples

Next Steps

For support:

• Email: team@recal.dev
• Dashboard: recal.dev