HTTP routes overview

Understand HTTP Routes as the transport layer around domain services, then choose the guide for your endpoint.

An HTTP route connects a method and URL to an operation exposed by a service. A domain owns the business behavior; its service exposes public functions; a route connects a URL and method to one of those functions. Adding a public function alone does not publish an endpoint.

Keep these responsibilities separate so the same operation can serve an HTTP request, a scheduled job, or an AI tool without copying its validation and business rules into each entry point.

Pre-setup

Start from the minimal app. Core HTTP needs no optional integration or external service. Merge listener settings in relkit.config.ts when changing the defaults:

/** HTTP needs listener settings but no external provider or custom PORT field. */
import { defineApp, defineEnv } from "@relkit/app/config";

export default defineApp({
  env: defineEnv({}),
  server: { port: 3000, maxBodyBytes: 1_048_576 },
});

Keep your app’s existing ID, env contract, and other settings. PORT is a framework-owned runtime override; do not add it to defineEnv. Put application-specific values in src/platform/env.ts and keep that descriptor in defineApp({ env }).

Configure a route’s dependencies before serving it: database, uploads, cache/rate-limit storage, and authentication. These use local Docker where a service is needed. Then run bun run check, bun run typecheck, and bun run dev; the first route guide verifies the actual HTTP response. Scalar and MCP require their own opt-in setup.

Follow a request through the application

For a function-backed route, the normal request flow is:

HTTP request
  ↓ URL + method
Route (src/routes/)
  ↓ policy + input mapping
Public function (src/services/<domain>/)
  ↓ validated output
HTTP response

The route does not contain another business handler. It selects a public function and describes how HTTP values become that function’s input. RELKIT checks the descriptors, generates transport artifacts, and registers the checked routes with the runtime.

Core HTTP, RPC and JSON OpenAPI are available in the minimal app without optional protocol/UI SDKs. MCP, AG-UI and Scalar each have an independent installation and explicit selection.

The Orders extension to the minimal app uses the same layers:

/** Maps the HTTP endpoint to its owning service's public member. */
import { defineServiceRoutes } from "@relkit/app/routes";
import orders from "@app/services/orders/service.js";

export const { POST } = defineServiceRoutes(orders, {
  POST: { member: "createOrder", successStatus: 201 },
});

The directory supplies /orders, the named export supplies POST, and the service member selects the public createOrder function. Its object input comes from JSON; its validated output becomes a JSON 201 response. Follow your first HTTP route to trace and verify it.

Know where each change belongs

Business rules that must apply to every caller belong in the function, not only in HTTP middleware. For agents, tools, jobs, events, caching, and storage, use the domain organization guide to choose an owner and continue into that capability’s getting-started guide.

Choose a starting point

These guides describe function-backed HTTP endpoints first. Raw handlers opt out of that typed pipeline; generated clients use a separate RPC transport. Their dedicated guides explain those boundaries.