Home Page | Documentation | Examples | Discord | Blog

This example shows how to create custom API endpoints with VoltAgent's server-hono package. You can extend the VoltAgent API server with your own business logic, data endpoints, or integration points.

npm create voltagent-app@latest -- --example with-custom-endpoints

This example includes 4 simple endpoints:

• GET /api/health - Health check
• GET /api/hello/:name - Personalized greeting with URL parameters
• POST /api/calculate - Simple calculator with JSON body
• DELETE /api/delete-all - Delete all data example

Custom endpoints are registered through the configureApp callback, which gives you full access to the Hono app instance:

import { honoServer } from "@voltagent/server-hono";
import { jwtAuth } from "@voltagent/server-core";

new VoltAgent({
  agents: { agent },
  server: honoServer({
    port: 3141,

    // Optional: Configure CORS
    cors: {
      origin: "https://your-domain.com",
      credentials: true,
    },

    // Optional: Add authentication
    auth: jwtAuth({
      secret: process.env.JWT_SECRET,
      defaultPrivate: true, // Protect all routes by default
      publicRoutes: ["GET /api/health"], // Except these
    }),

    configureApp: (app) => {
      // Add custom routes with full Hono API
      // Note: Routes are automatically protected when auth is configured with defaultPrivate: true
      app.get("/api/health", (c) => c.json({ status: "ok" }));

      // Use route parameters
      app.get("/api/user/:id", (c) => {
        const id = c.req.param("id");
        return c.json({ userId: id });
      });

      // Add middleware
      app.use("/api/admin/*", authMiddleware);

      // Use route groups
      const api = app.basePath("/api/v2");
      api.get("/users", getUsersHandler);
    },
  }),
});

With configureApp, you get:

• Full access to Hono's routing API
• Type-safe route handlers with proper IntelliSense
• Ability to use middleware and route groups
• Support for all Hono features (OpenAPI, validation, etc.)
• Automatic auth protection when auth is configured (routes are registered AFTER auth middleware)

1. Install dependencies:

npm install

2. Create .env file:

echo "OPENAI_API_KEY=your_api_key_here" > .env

npm run dev

# Health check
curl http://localhost:3141/api/health

# Greeting
curl http://localhost:3141/api/hello/john

# Calculator
curl -X POST http://localhost:3141/api/calculate \
  -H "Content-Type: application/json" \
  -d '{"a": 10, "b": 5, "operation": "add"}'

# Delete all data
curl -X DELETE http://localhost:3141/api/delete-all

# Admin stats (middleware logs the access)
curl http://localhost:3141/api/admin/stats

curl -X POST http://localhost:3141/agents/agent/text \
  -H "Content-Type: application/json" \
  -d '{"input": "What endpoints are available?"}'

1. Pass a configureApp callback to the honoServer configuration
2. The callback receives the Hono app instance as a parameter
3. Use Hono's native API to register routes, middleware, and plugins
4. The server calls your configureApp function after registering built-in routes
5. Your custom routes are now part of the API server

That's it! 🎉