Routing

Routing is how a Talos app decides which controller handles which request. You never wire up a route table by hand. You decorate a controller class with a route decorator, and the framework registers the path, method, and validation rules for you. When a request arrives, the router matches it against the registered routes and runs the matched controller’s index(context) method. A route and its controller are two halves of one unit: the decorator describes the contract (path, method, what input is valid, who is allowed in), and the controller supplies the behavior. Because every route is declared on the class that serves it, the definition lives next to the code that runs, and the same configuration object drives parameter parsing, validation, access control, and named URL generation.

What the route decorator buys you

The route lives on the controller it serves, so there’s no central route file drifting out of sync with its handlers. Path params, query strings, and request bodies are validated with @talosjs/validation schemas before your controller runs, so index receives typed, trusted data. Roles, permission classes, and env/ip/host restrictions are part of the same definition, which keeps “who can reach this” visible right where the route is declared. Routes are referenced by name rather than by a hardcoded path: every route has one, and you generate URLs from it with router.generate(...) instead of scattering stringly-typed paths across the codebase. The same decorator family declares HTTP and WebSocket endpoints, so socket routes follow the same naming and validation conventions as HTTP ones.

How it works

The router holds a map of paths to route configurations. Each Route.* decorator builds a route config from the path and your options, marks the HTTP method (or isSocket: true for sockets), attaches the controller class, and registers it with the container as a singleton. At request time the framework matches the path and method, validates the input against the route’s schemas, enforces any access rules, and invokes the matched controller’s index(context).

Stage	What happens
Declaration	A `@Route.get(...)` / `@Route.post(...)` / `@Route.socket(...)` decorator registers the controller class with its path, method, and config.
Matching	An incoming request is matched by path and HTTP method (sockets match by path only).
Validation	`params`, `queries`, and `payload` schemas run; invalid input is rejected before the controller.
Access control	`roles`, `permission`, `env`, `ip`, and `host` are checked; disallowed requests are rejected.
Handling	The matched controller’s `index(context)` runs with `context.params`, `context.queries`, and `context.payload` populated.

The decorator takes the path as its first argument and the config object as its second:

Route.get("/api/users/:id", {
  name: "api.users.show",
  version: 1,
  description: "Get a user by id",
});

Defining a route

Import Route and decorate a controller class. The method decorator name maps to the HTTP method: Route.get, Route.post, Route.put, Route.delete, Route.patch, Route.options, and Route.head. The controller implements IController and exposes an index(context) method that returns a response.

import { Route } from "@talosjs/routing";
import type { ContextType, IController } from "@talosjs/controller";
import type { IResponse } from "@talosjs/http-response";

@Route.get("/api/users", {
  name: "api.users.list",
  version: 1,
  description: "List all users",
})
export class UserListController implements IController {
  public async index(context: ContextType): Promise<IResponse> {
    return context.response.json({
      users: [{ id: 1, name: "John" }],
    });
  }
}

Configuration options

Every option except path and method (which come from the decorator) is passed in the config object.

Field	Type	Description
`name`	`string`	Unique route name in `namespace.resource.action` form. Used for lookup and URL generation. Required.
`version`	`number`	Numeric API version for the route. Required.
`description`	`string`	Human-readable description of the route. Required.
`params`	`Record<string, AssertType>`	Schema per path parameter (the `:id` segments). Validates `context.params`.
`queries`	`AssertType`	Schema for the query string. Validates `context.queries`.
`payload`	`AssertType`	Schema for the request body. Validates `context.payload`.
`response`	`AssertType`	Schema describing the response shape (used for documentation and codegen).
`roles`	`Uppercase<string>[]`	Roles allowed to access the route.
`permission`	`PermissionClassType`	A custom permission class evaluated per request.
`featureFlag`	`FeatureFlagClassType`	A feature-flag class gating the route.
`env`	`EnvironmentNameType[]`	Environments in which the route is available.
`ip`	`string[]`	Allowed IP addresses or CIDR ranges.
`host`	`string[]`	Allowed hostnames.
`cache`	`string`	Cache key prefix that enables response caching for the route.

The decorator supplies path, method, isSocket, and controller automatically — you never set those in the config object.

Route naming

Every route has a unique name following the namespace.resource.action convention, for example api.users.list or admin.products.create. Names must be unique across the whole app; registering two routes with the same name throws a RouterException. The name is what you pass to router.generate(...) and what the router uses for lookups. Valid namespaces: api, client, admin, public, auth, webhook, internal, external, system, metrics, docs The middle resource segment names the thing the route acts on (users, products, users.orders), and the final action segment names the operation (list, show, create, update, delete, search, and many more).

Path parameters

Dynamic path segments are written with a leading colon, like :id. Each declared parameter should have a schema in params; after validation the values are available on context.params.

import { Route } from "@talosjs/routing";
import { Assert } from "@talosjs/validation";
import type { ContextType, IController } from "@talosjs/controller";
import type { IResponse } from "@talosjs/http-response";

@Route.get("/api/users/:id", {
  name: "api.users.show",
  version: 1,
  description: "Get a user by id",
  params: {
    id: Assert("string.uuid"),
  },
})
export class UserShowController implements IController {
  public async index(context: ContextType): Promise<IResponse> {
    const { id } = context.params;
    const user = await this.userRepository.findById(id);

    return context.response.json({ user });
  }
}

A path may declare several parameters, like /api/users/:userId/orders/:orderId, and each is matched into context.params by name.

Query validation

Provide a queries schema to validate and coerce the query string. The schema handles defaults and optional keys, so the controller reads ready-to-use values from context.queries.

import { Route } from "@talosjs/routing";
import { Assert } from "@talosjs/validation";
import type { ContextType, IController } from "@talosjs/controller";
import type { IResponse } from "@talosjs/http-response";

@Route.get("/api/products", {
  name: "api.products.search",
  version: 1,
  description: "Search products",
  queries: Assert({
    q: "string",
    page: "number = 1",
    limit: "number = 10",
    "category?": "string",
  }),
})
export class ProductSearchController implements IController {
  public async index(context: ContextType): Promise<IResponse> {
    const { q, page, limit, category } = context.queries;
    const products = await this.search(q, { page, limit, category });

    return context.response.json({ products });
  }
}

Payload validation

For routes that accept a request body, declare a payload schema. The body is validated before index runs, and the parsed value is on context.payload.

import { Route } from "@talosjs/routing";
import { Assert } from "@talosjs/validation";
import type { ContextType, IController } from "@talosjs/controller";
import type { IResponse } from "@talosjs/http-response";

@Route.post("/api/users", {
  name: "api.users.create",
  version: 1,
  description: "Create a new user",
  payload: Assert({
    email: "string.email",
    name: "string >= 2",
    password: "string >= 8",
  }),
})
export class UserCreateController implements IController {
  public async index(context: ContextType): Promise<IResponse> {
    const { email, name, password } = context.payload;
    const user = await this.userService.create({ email, name, password });

    return context.response.json({ user }, 201);
  }
}

See validation for the full schema syntax, and response for the response builder used in these handlers.

Response validation

Declare a response schema to describe the shape index returns. Unlike params, queries, and payload, the response schema is not a runtime gate on the request. It documents the route’s output contract and drives type derivation and codegen, so generated clients and API docs stay in sync with what the controller actually sends back.

import { Route } from "@talosjs/routing";
import { Assert } from "@talosjs/validation";
import type { ContextType, IController } from "@talosjs/controller";
import type { IResponse } from "@talosjs/http-response";

@Route.get("/api/users/:id", {
  name: "api.users.show",
  version: 1,
  description: "Get a user by id",
  params: {
    id: Assert("string.uuid"),
  },
  response: Assert({
    user: {
      id: "string.uuid",
      email: "string.email",
      name: "string",
    },
  }),
})
export class UserShowController implements IController {
  public async index(context: ContextType): Promise<IResponse> {
    const user = await this.userRepository.findById(context.params.id);

    return context.response.json({ user });
  }
}

Because the schema is the same @talosjs/validation construct used for input, the response shape lives in the route contract alongside its inputs. Describe it once on the decorator and the generated types and documentation follow.

WebSocket routes

Route.socket(path, config) declares a WebSocket endpoint. It takes the same config as the HTTP decorators (the method is ignored and isSocket is set to true), but the controller’s context comes from @talosjs/socket and exposes a channel for subscribing and publishing.

import { Route } from "@talosjs/routing";
import { Assert } from "@talosjs/validation";
import type { ContextType, IController } from "@talosjs/socket";
import type { IResponse } from "@talosjs/http-response";

@Route.socket("/ws/chat/:roomId", {
  name: "api.chat.connect",
  version: 1,
  description: "Connect to a chat room",
  params: {
    roomId: Assert("string"),
  },
})
export class ChatController implements IController {
  public async index(context: ContextType): Promise<IResponse> {
    const { roomId } = context.params;
    await context.channel.subscribe();

    return context.response.json({ connected: true, room: roomId });
  }
}

Generating URLs

Look routes up by name and build their URL with router.generate(name, params). Path parameters are interpolated from the params object; missing required parameters throw a RouterException.

import { router } from "@talosjs/routing";

const userUrl = router.generate("api.users.show", { id: "123" });
// "/api/users/123"

const orderUrl = router.generate("api.users.orders.show", {
  userId: "123",
  orderId: "456",
});
// "/api/users/123/orders/456"

Generating from names keeps URLs in one place. Rename a path in its decorator and every call site that uses the route name keeps working.

Access control

Routes can declare who is allowed to reach them. These checks run before the controller, so an unauthorized request never reaches index. For role-based access, list the roles permitted to call the route:

@Route.delete("/admin/users/:id", {
  name: "admin.users.delete",
  version: 1,
  description: "Delete a user (admin only)",
  roles: ["ROLE_ADMIN", "ROLE_SUPER_ADMIN"],
})
export class UserDeleteController implements IController {
  public async index(context: ContextType): Promise<IResponse> {
    await this.userService.delete(context.params.id);
    return context.response.json({ deleted: true });
  }
}

When the rule is more than a fixed role list, point permission at a permission class that decides per request:

@Route.put("/api/users/:id", {
  name: "api.users.update",
  version: 1,
  description: "Update a user profile",
  permission: CanEditOwnProfile,
})
export class UserUpdateController implements IController {
  // only the owner may update; the permission class enforces it
}

To limit a route to certain environments or network origins, use the env, ip, and host lists:

@Route.get("/internal/metrics", {
  name: "internal.metrics.show",
  version: 1,
  description: "Internal metrics endpoint",
  env: ["local", "development"],
  ip: ["127.0.0.1", "10.0.0.0/8"],
  host: ["metrics.internal"],
})
export class MetricsController implements IController {
  // reachable only from the listed envs, IP ranges, and hosts
}

Access checks compose with the request middleware pipeline. Middleware runs first and may short-circuit, then the route’s own access rules apply, then the controller runs.

Conventions worth following

Name every route as namespace.resource.action so names stay predictable and router.generate calls read clearly. Declare params, queries, and payload schemas at the boundary, so index works with trusted, typed data instead of re-checking input by hand, and use router.generate(name, params) wherever you need a route URL rather than hardcoding one. Keep one route per controller: a controller’s index serves a single route, so split distinct operations into distinct controllers. Put roles, permission, and env/ip/host rules on the route itself so the contract states who may reach it. Set version deliberately so clients and generated docs can track route revisions.

Scaffolding

Generate a controller and its route together with the CLI rather than wiring one by hand:

talos controller:create

See controller:create for the full command reference, and the controller page for how the generated index(context) method consumes the validated request.

Getting Started

AI

Framework

Command Line

What the route decorator buys you

How it works

Defining a route

Configuration options

Route naming

Path parameters

Query validation

Payload validation

Response validation

WebSocket routes

Generating URLs

Access control

Conventions worth following

Scaffolding

​What the route decorator buys you

​How it works

​Defining a route

​Configuration options

​Route naming

​Path parameters

​Query validation

​Payload validation

​Response validation

​WebSocket routes

​Generating URLs

​Access control

​Conventions worth following

​Scaffolding

What the route decorator buys you

How it works

Defining a route

Configuration options

Route naming

Path parameters

Query validation

Payload validation

Response validation

WebSocket routes

Generating URLs

Access control

Conventions worth following

Scaffolding