REST API

Base URL

https://api.recal.dev/v1

Authentication

Use your API key in the Authorization header:

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

Generate keys at app.recal.dev → API Keys

Endpoints

Scheduling

Find availability across users or organizations.

• GET /v1/users/{userId}/scheduling
• GET /v1/organizations/{orgSlug}/scheduling

Users

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

Organizations

Create workspaces to group users. Optional for B2C, essential for B2B multi-tenancy.

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

Calendar

• GET /v1/users/{userId}/calendar/busy — User busy periods
• GET /v1/organizations/{orgSlug}/calendar/busy — Organization busy periods

OAuth

Supported: Google Calendar, Microsoft Outlook

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

OAuth Scopes

Recal offers two simplified scope options:

• edit - Full calendar read/write access (create, update, delete events)
• free-busy - Read-only access to availability information

When making API calls, Recal automatically validates scopes. If a user lacks required permissions, you'll receive a 403 Forbidden response:

{
  "error": "Insufficient scopes for operation 'calendar.events.insert'. Required scope level: write. You need to request one of these scopes: ...",
  "operation": "calendar.events.insert",
  "validScopes": [
    "https://www.googleapis.com/auth/calendar",
    "https://www.googleapis.com/auth/calendar.events"
  ],
  "data": null
}

See the OAuth Setup Guide for detailed scope configuration.

Example Request

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

Responses

We're responding in the standardized API format:

{
  data: {
    // The actual data payload
  }
}

// or

{
  data: null
  error: string
}

Next Steps