App API Overview

The template ships a versioned App API (/api/app/v1) — a full-featured HTTP backend that Swift, Kotlin, Expo, Electron, and Tauri clients consume directly. Next.js, Nuxt, and TanStack Start implement the same public contract. Web pages and clients share one Better Auth user, one database, and one subscription: sign in on iOS with the account you created on the web, read the same data, and unlock the same entitlement from either channel.

What it provides

• 15 business endpoints under /api/app/v1: profile, todos, device tokens, APNs test push, subscription snapshot + management portal, presigned uploads, and account deletion.
• A service layer (src/server/app/) that route handlers and web pages both call — business logic is written once.
• Bearer-session auth on every endpoint; ownership always comes from the server session, never from a client-supplied user ID.
• A machine-readable OpenAPI 3.1 contract at docs/openapi.yaml.

Important files

Architecture

Every route is a thin wrapper: authedRoute builds a request context, enforces a valid session, and maps thrown AppErrors to uniform error envelopes. The handler delegates to a service that receives the server-verified user ID:

export const GET = authedRoute(async (ctx) => {
  const items = await todosService.list(ctx.userId, filter);
  return ok({ items }, ctx);
});

Services never import NextRequest/NextResponse, so the same functions back the web dashboard and the App API.

API conventions

Error behavior

Endpoints

PUT /api/app/v1/uploads/local also exists as a development-only target for the local storage provider; it is disabled in production and not part of the contract.

The OpenAPI contract

docs/openapi.yaml describes every endpoint, schema, enum, and error response. It is the single source of truth for client implementations — point any OpenAPI viewer or generator at it, and validate hand-written client models against it in contract tests.

Related pages