LogoRecal

Recal REST API Reference - Calendar API Endpoints & Authentication

Complete REST API reference for Recal. Authentication, endpoints for users, organizations, calendar events, and OAuth connections.

Complete API Reference

This page provides an overview of key endpoints. For the complete API documentation including all endpoints, request/response schemas, and interactive testing, visit our Swagger UI at api.recal.dev/v1/swagger.

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.

EndpointDescription
GET /v1/users/{userId}/schedulingAvailable slots for a user
GET /v1/organizations/{orgSlug}/schedulingAvailable slots across an organization

👤 Users

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

MethodEndpointDescription
GET/v1/usersList organization users
POST/v1/usersCreate a user
GET/v1/users/{userId}Get user details
PUT/v1/users/{userId}Update user
DELETE/v1/users/{userId}Delete user

🏢 Organizations

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

MethodEndpointDescription
GET/v1/organizationsList organizations
POST/v1/organizationsCreate 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.

EndpointDescription
GET /v1/users/{userId}/calendar/busyUser's busy periods
GET /v1/organizations/{orgSlug}/calendar/busyOrganization's busy periods

🔐 OAuth Connections

Connect users to calendar providers and manage authorizations.

Supported Providers:

  • ✅ Google Calendar
  • ✅ Microsoft Outlook
MethodEndpointDescription
GET/v1/users/{userId}/oauthList connections
POST/v1/users/{userId}/oauth/{provider}/authorizeStart OAuth flow
DELETE/v1/users/{userId}/oauth/{provider}Remove connection

Quick Start Example

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

# 2. Check user availability
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.recal.dev/v1/users/{userId}/calendar/busy

# 3. Find scheduling slots
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.recal.dev/v1/users/{userId}/scheduling

Next Steps

Swagger UI - Complete API Reference

THE primary API documentation with live testing

Quick Start Guide

Set up authentication and make your first call

Important Entities

Understand the data model

Dashboard Overview

Generate API keys and configure OAuth

Recal Core Concepts - Organizations, Users & Calendar Events

Learn how Recal's organizations, users, and events work together. Understand multi-tenant calendar management and API data structures.

Recal Node.js SDK - Calendar API Client Library (Coming Soon)

Official Node.js SDK for Recal's calendar API. Type-safe client, simplified OAuth flows, and webhook handling. Coming soon.