API Routes

Overview

Hono is the canonical API router inside the Next.js application. The single src/app/api/[[...route]]/route.ts adapter mounts src/api/app.ts; domain handlers under src/api/routes/ call server-only services for business logic.

Base URL

• Development: http://localhost:3000/api
• Production: https://yourdomain.com/api

Authentication Routes

Billing Routes

User Routes

Utility Routes

Result errors

Auth actions and several customer-facing service failures return an ok flag and a redirect path that carries the visible status or error:

{
  "ok": false,
  "redirectPath": "/path?error=message&error_description=details"
}

Validation, search, webhook, and test-only routes keep their route-specific HTTP status and response body instead of being forced into this shape.

Adding New Routes

Add the endpoint to the Hono module that owns its domain. Keep business logic in a service and leave the Next.js catch-all unchanged.

import { Hono } from "hono";

import { processData } from "@/services/example/service";

export const exampleRoutes = new Hono();

exampleRoutes.post("/", async (c) => {
  const body = await c.req.json();
  const result = await processData(body);
  return c.json(result);
});

Mount a new domain module in src/api/app.ts with apiApp.route('/example', exampleRoutes). Existing domains should add their endpoint to the current route module instead.

Related

• Authentication - Auth flow details
• Payments - Billing flow details
• Project Structure - File organization