API

On This Page

How A Request Flows

Product calls hit one router in packages/api. The kit uses oRPC (not tRPC) so the OpenAPI spec falls out of the same router definition.

Browser components send RPC over RPCLink to /rpc. React Server Components skip the network and call the same procedures in-process through a router client on globalThis.$client.

Either way, the request walks the same middleware chain and lands in the same Zod-validated handler.

/api-reference is docs only. It serves the OpenAPI spec and interactive UI to platform admins. It is not a third place to call procedures.

Package Layout

Namespaces

The root router groups procedures under tagged namespaces. Each row is a section in /api-reference and a subtree of orpc.<namespace> on the client.

Anatomy Of A Procedure

A procedure is a chain: pick a base, add middleware, declare the OpenAPI route, declare input/output schemas, then write the handler.

Here is a typical query, getUserSession from packages/api/src/router/user.ts:

export const getUserSession = authorized
  .route({
    path: "/user/session",
    method: "GET",
    summary: "Get user session",
  })
  .output(userSessionOutputSchema)
  .handler(async ({ context }) => {
    const credentialAccount = await prisma.account.findFirst({
      where: { userId: context.user.id, providerId: "credential" },
      select: { id: true },
    });

    return {
      user: { /* ... */ },
      activeOrganizationId: context.session.activeOrganizationId ?? null,
      hasPasswordAuth: !!credentialAccount,
    };
  });

A mutation looks the same with .input(...) added. createOrganization from packages/api/src/router/organization.ts:

export const createOrganization = authorized
  .route({
    path: "/organization/create",
    method: "POST",
    summary: "Create organization",
  })
  .input(organizationCreateSchema)
  .output(z.object({ id: z.string() }))
  .handler(async ({ context, input }) => {
    const org = await auth.api.createOrganization({ /* ... */ });

    if (!org) {
      throw new ORPCError("INTERNAL_SERVER_ERROR", {
        message: "Failed to create organization",
      });
    }

    return { id: org.id };
  });

Context grows as you chain middleware. base provides headers. authorized adds session and user. withActiveOrganization adds organization. Inside the handler, context is typed as everything the chain contributed.

Middleware And Context

Procedures opt into gates by chaining .use(...) after a base.

OpenAPI Reference

Every procedure that declares .route({ path, method, summary }) is published to the OpenAPI spec. The spec and interactive UI live at apps/web/app/api-reference/[[...rest]]/route.ts. That route wraps the same router, allows only a few paths, and checks for an admin session:

const ALLOWED_PATHS = new Set([
  "/api-reference",
  "/api-reference/",
  "/api-reference/spec.json",
]);

async function handleRequest(request: Request): Promise<Response> {
  const url = new URL(request.url);
  if (!ALLOWED_PATHS.has(url.pathname)) return notFound();

  const session = normalizeSession(
    await auth.api.getSession({ headers: request.headers })
  );
  if (!session || !isAdmin(session.user.role)) return notFound();

  // ...delegates to OpenAPIHandler for the docs UI and spec.json
}

Practical notes:

• Visit /api-reference in the running app. It is admin-only in every environment. apps/web/proxy.ts redirects unauthenticated users to login. The handler then decrypts the session and returns 404 for every non-admin (including signed-in non-admins), so the route's existence stays hidden.
• Only GET and HEAD are wired, and only the docs UI and spec.json are served. /api-reference is not a callable REST mount. Procedure paths under that prefix return 404. The single API surface is /rpc.
• Section titles come from base.tag(...) in packages/api/src/router/index.ts. The same tags group the namespaces above.
• Responses set X-Robots-Tag: noindex, nofollow and Cache-Control: private, no-store. /api-reference/ is also disallowed in apps/web/app/robots.ts.

Calling The API From React

Browser hooks

Client components import orpc from apps/web/lib/orpc and use TanStack Query hooks. Query keys, input types, and result types come from the Router type.

import { useSuspenseQuery } from "@tanstack/react-query";
import { orpc } from "@/lib/orpc";

export function DashboardContent() {
  const { data } = useSuspenseQuery(orpc.dashboard.getStats.queryOptions());
  // ...
}

For mutations, use mutationOptions(). For typed error narrowing, use isDefinedError from @orpc/client against the error's code.

Server components

React Server Components do not make HTTP calls. The root layout imports apps/web/lib/orpc.server.ts at boot, which seeds an in-process router client on globalThis.$client:

globalThis.$client = createRouterClient(router, {
  context: async () => ({
    headers: await headers(),
  }),
});

When apps/web/lib/orpc.ts initializes on the server, it picks up that client instead of building an RPCLink. Server components then use the same orpc.<namespace>.<procedure>.queryOptions() API as the browser; calls run in-process. Prefetch and hydration helpers live in apps/web/lib/query/hydration.tsx.

Streaming Procedures

AI chat is the part of the router that does not fit request/response. chat.send and chat.regenerate return event iterators instead of plain values, so they omit .output():

return streamToEventIterator(
  result.toUIMessageStream({ sendReasoning: true, sendSources: true })
);

On the client, the chat UI uses the AI SDK's useChat with a custom transport that calls the procedure and unproxies the stream via eventIteratorToUnproxiedDataStream from @orpc/client. See packages/api/src/router/chat.ts and apps/web/components/dashboard/ai-chat/chat-view.tsx. The full AI surface is on the AI page.

Adding A Procedure

Health And Webhooks

Two surfaces sit next to the app API. Neither is part of the oRPC router itself.

• Health probes. readinessCheck and livenessCheck are available over /rpc. The same checks are also plain Next routes at apps/web/app/api/health/route.ts and apps/web/app/api/healthz/route.ts, so monitoring tools that do not speak RPC can hit them directly.
• Inbound webhooks. Stripe webhooks are Next route handlers at apps/web/app/api/webhooks/stripe/route.ts, not oRPC procedures. They need raw request bodies for signature verification and Stripe-shaped responses. Full pattern: Webhooks And Async Workflows.

Where To Go Next

Also useful: Billing, AI, Webhooks And Async Workflows, and Conventions.