API

Trace TanStack routes through the Worker entry, authentication, validation, and API responses.

Follow the request through the source

Flare uses TanStack Start and native Worker bindings. There are no Next.js route handlers or OpenNext adapters in this path.

apps/web/src/server.ts receives requests and handles Paraglide, public robots/sitemap responses, queues, and scheduled work.
apps/web/src/server/api.ts dispatches /api/* requests, validates input, checks sessions, and invokes services.
apps/web/src/routes/$.tsx implements public, authentication, workbench, and admin page paths. Protected pages check access before loading data.
packages/* owns authentication, database, billing, storage, AI, and task implementations.

Hiding a button is presentation behavior. Each API still enforces its own authorization.

Common API contracts

Path	Method and input	Access / response
`/api/health`	GET	Health and environment, without secrets
`/api/public/auth`	GET	Public provider configuration and Turnstile site key
`/api/auth/*`	Better Auth endpoints	Authentication, sessions, two-factor, API keys
`/api/files`	GET / POST multipart `file`	Owned files; restricted file API keys are supported
`/api/chat`	POST `{prompt, requestId?}`	Session and credits; event-stream response
`/api/summary`	POST `{fileId}`	Owned text file; asynchronous task
`/api/checkout`	POST `{planId,gateway,requestId}`	Session and enabled offer; UUID requestId
`/api/billing/manage`	POST `{orderId,action}`	Owned order; action is portal or cancel
`/api/admin/*`	GET / POST	Per-endpoint administrator authorization

The summary endpoint takes only fileId. Do not copy requestId from the chat or checkout contract. Read current api.ts for response types and error handling, and update callers and contract checks together when extending an endpoint.

Make a same-origin JSON request

const response = await fetch('/api/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    prompt: 'Summarize the release notes',
    requestId: crypto.randomUUID(),
  }),
});
if (!response.ok) {
  // Read the server error and show an actionable message.
  throw new Error('Chat request failed');
}
// Consume text/event-stream progressively instead of calling response.json().

Same-origin browser calls use the current session. Mutation requests validate Origin against APP_URL. A cross-origin proxy, a test client without the expected origin, or a misconfigured production URL can therefore be rejected. File API keys do not grant access to admin, chat, or checkout endpoints.

Extend a business module

Define service behavior in packages, add method and schema validation in api.ts, then connect the UI. Filter collections by the authenticated user and verify ownership again when accessing a single record. Reuse the ledger, outbox, and idempotency mechanisms for financial or credit operations instead of deducting credits in a component.

Keep the durable production rate limits: authentication defaults to 30 requests per minute and mutations to 120. Subjects are hashed in D1. Extend the same enforcement points for sensitive endpoints; client-side debouncing is insufficient.

Page and locale paths

Existing paths include /app, files, AI, billing, usage, settings, onboarding, and /app/admin. Chinese page URLs use a /zh prefix. API paths remain /api; never request /zh/api.

Verify the boundary

A signed-out workbench visit redirects, and direct protected API calls still fail.
User A cannot access user B's file or order by guessing its ID.
An empty prompt, malformed UUID, or unknown plan fails without creating work.
Verify progressive stream delivery, cancellation, and failure feedback.
For a 403, check role, ownership, and Origin before changing server logic.

Run pnpm check:contracts and pnpm type-check, then the relevant API tests.