# Webiny Http Route

Adding custom HTTP routes to the API with <Api.Route> and HttpRouteHandler.

- Repository: https://github.com/webiny/webiny-js (8051 stars)
- Category: Engineering
- License: see repository
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add webiny/webiny-js --skill webiny-http-route -g -a claude-code -y`
Codex: `npx skills add webiny/webiny-js --skill webiny-http-route -g -a codex -y`
Cursor: `npx skills add webiny/webiny-js --skill webiny-http-route -g -a cursor -y`
Gemini CLI: `npx skills add webiny/webiny-js --skill webiny-http-route -g -a gemini-cli -y`

## Description

Adding custom HTTP routes to the API with <Api.Route> and HttpRouteHandler. Use this skill when the developer wants to expose a custom HTTP endpoint (GET, POST, PUT, etc.) on the API alongside the GraphQL handler, implement a route handler with full DI support, or register a custom HTTP route in webiny.config.tsx.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Custom HTTP Routes

## TL;DR

Write a handler that implements `HttpRouteHandler.Interface`, then point `<Api.Route>` at it in
`webiny.config.tsx`. The `method` and `path` props configure both the API Gateway route and the
router, so the handler file never restates them. Handlers get full DI.

**YOU MUST include the full file path with the `.ts` extension in the `src` prop.** Use
`src={"/extensions/MyRoute.ts"}`, not `src={"/extensions/MyRoute"}`. Omitting it fails the build.

**YOU MUST use `export default`** for the `createImplementation()` call. Named exports fail here.

## The route pattern

```typescript
// extensions/MyRoute.ts
import { HttpRouteHandler, Logger } from "webiny/api";

class MyRouteImpl implements HttpRouteHandler.Interface {
  constructor(private logger: Logger.Interface) {}

  async handle(request: HttpRouteHandler.Request, response: HttpRouteHandler.Response) {
    this.logger.info({ path: request.path }, "Handling request");

    return response.status(200).json({ status: "ok" });
  }
}

export default HttpRouteHandler.createImplementation({
  implementation: MyRouteImpl,
  dependencies: [Logger]
});
```

Register it:

```tsx
<Api.Route method={"POST"} path={"/my-route"} src={"/extensions/MyRoute.ts"} />
```

## Props reference

The rest: https://github.com/webiny/webiny-js/blob/HEAD/skills/user-skills/api/http-route/SKILL.md