API

Cal.diy exposes two distinct API surfaces. Knowing which one fits your use case matters because they have different authentication, versioning, and audience.

At a glance

Surface	Path	Used by	Auth	Page
tRPC	packages/trpc mounted at apps/web/pages/api/trpc/[trpc].ts	The Next.js front end + embeds	NextAuth session cookie	tRPC
REST v2	apps/api/v2 (NestJS)	Platform SDK consumers, third-party integrators, atoms	API keys, OAuth, JWT	REST v2
REST v1 (legacy)	apps/web/pages/api/v1/	Legacy customers	API keys	(covered in REST v2)

Choose by audience

• Building UI inside Cal.diy itself → tRPC. You get end-to-end TypeScript types and don't need to think about versioning.
• Building a third-party product that talks to Cal.diy → REST v2. Documented in apps/docs/content/api-reference/v2/openapi.json. Versioned by date (2024-06-14, 2024-08-13, ...).
• Building a Platform SaaS on top of Cal.com → REST v2 + the Platform atoms in packages/platform/atoms. The atoms wrap the REST endpoints.

Pages

• tRPC
• REST v2

Why two surfaces?

The two surfaces evolved at different points in the project's history:

• tRPC came in with the 2022 monorepo refactor. It is excellent for an internal API where you control both ends.
• REST v2 was added in 2023–2024 to give external customers a stable, versioned, documented API. It is a separate NestJS service so the public contract is decoupled from the web app's release cadence.

Both share a single Postgres database (packages/prisma). They diverge in how they read and write — tRPC routers call services directly; REST v2 controllers go through packages/platform/libraries.