---
id: start.server-route
kind: recipe
product: start
framework: react
locale: en
revision: 2
sourceCheckedOn: "2026-08-03"
versionRange: "Start ^1 / Router ^1"
verifiedAgainst: "@tanstack/react-start@1.168.34 + @tanstack/react-router@1.170.18"
contentModel: 2
packages:
  - "@tanstack/react-start"
  - "@tanstack/react-router"
tasks:
  - "create-server-route"
  - "external-api"
  - "return-http-status"
  - "choose-server-route"
sourceRefs:
  - "https://tanstack.com/start/latest/docs/framework/react/guide/server-routes"
  - "https://tanstack.com/start/latest/docs/framework/react/guide/server-functions"
---

# Create an externally callable Server Route

> Build a native HTTP endpoint for third-party callers with explicit status, caching, and safe responses.

## Execution contract

- **Use when:** Use for webhooks, external clients, or integrations requiring a standard HTTP endpoint.
- **Avoid when:** Prefer a Server Function for app-internal calls that need end-to-end types.
- **Preconditions:** Define method, path, input, status codes, response schema, authentication, and idempotency requirements.
- **Verification:** Use an independent HTTP client to test success, unauthorized, invalid-input, and not-found responses.
- **Failure mode:** HTML or 200 error payloads indicate missing explicit Response status and Content-Type handling.
- **Security:** External endpoints must handle identity, authorization, input size, and replay risk without relying on browser same-origin behavior.

## Selection contract

Use a Server Function for in-app, same-origin RPC with end-to-end types. Use a Server Route for webhooks, mobile clients, third-party integrations, or an independent HTTP contract.

## Minimal implementation

Return a Response from file-route server.handlers. Every failure branch chooses an explicit status; page-level notFound() control flow is not a Server Route 404 response.

File: `src/routes/api/health[.]json.ts`

```ts
import { createFileRoute } from '@tanstack/react-router'

export const Route = createFileRoute('/api/health.json')({
  server: {
    handlers: {
      GET: async () => Response.json(
        { ok: true },
        { headers: { 'Cache-Control': 'no-store' } },
      ),
    },
  },
})
```

## Security and validation

Treat params, search, headers, and body as unknown. Validate and enforce authentication, authorization, and rate limits before writes. Return stable error objects without internal exceptions. Identity-dependent responses use no-store or private, never public shared caching.

## Official sources

- https://tanstack.com/start/latest/docs/framework/react/guide/server-routes
- https://tanstack.com/start/latest/docs/framework/react/guide/server-functions