REST API

Base URLCopy Anchor Link

https://api.recal.dev/v1

AuthenticationCopy Anchor Link

Use your API key in the Authorization header:

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

Generate keys at dash.recal.dev → API Keys

EndpointsCopy Anchor Link

SchedulingCopy Anchor Link

Find availability across users or organizations.

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

Organization routes report connected members that could not be read; see Troubleshooting.

UsersCopy Anchor Link

• 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

OrganizationsCopy Anchor Link

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

CalendarCopy Anchor Link

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

Organization routes report connected members that could not be read, and the user route reports calendars it could not read; see Troubleshooting.

OAuthCopy Anchor Link

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 ScopesCopy Anchor Link

Recal offers three levels of access:

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

edit is deprecated — still accepted as a synonym for write, but it will be removed in a future version. New integrations should request write.

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 RequestCopy Anchor Link

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

ResponsesCopy Anchor Link

We're responding in the standardized API format:

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

// or

{
  data: null
  error: string
}

// or, on availability endpoints that read several calendars or members

{
  data: { /* everything that could be read */ },
  failedCalendars: [ /* or failedUsers — what could not, each with a reason and message */ ]
}

The third form is a 200. Three things always hold:

• Only endpoints that fan out over calendars or members carry a list.
• data keeps its ordinary shape — the list never moves inside it.
• The list is always present, [] when nothing failed, so failedCalendars.length needs no guard.

Availability routes can answer partially — see Troubleshooting.

Next StepsCopy Anchor Link