Class: HttpRouter

For AI agents: see llms.txt for the complete documentation index. Markdown versions are available by adding .md to a page URL or requesting Accept: text/markdown.

server.HttpRouter

HTTP router for specifying the paths and methods of httpActionGenerics

An example convex/http.js file might look like this.

import { httpRouter } from "convex/server";
import { getMessagesByAuthor } from "./getMessagesByAuthor";
import { httpAction } from "./_generated/server";

const http = httpRouter();

// HTTP actions can be defined inline...
http.route({
  path: "/message",
  method: "POST",
  handler: httpAction(async ({ runMutation }, request) => {
    const { author, body } = await request.json();

    await runMutation(api.sendMessage.default, { body, author });
    return new Response(null, {
      status: 200,
    });
  })
});

// ...or they can be imported from other files.
http.route({
  path: "/getMessagesByAuthor",
  method: "GET",
  handler: getMessagesByAuthor,
});

// Convex expects the router to be the default export of `convex/http.js`.
export default http;

Constructors

constructor

• new HttpRouter()

Properties

exactRoutes

• exactRoutes: Map<string, Map<"GET" | "POST" | "PUT" | "DELETE" | "OPTIONS" | "PATCH", PublicHttpAction>>

Defined in

server/router.ts:143

---

prefixRoutes

• prefixRoutes: Map<"GET" | "POST" | "PUT" | "DELETE" | "OPTIONS" | "PATCH", Map<string, PublicHttpAction>>

Defined in

server/router.ts:144

---

isRouter

• isRouter: true

Defined in

server/router.ts:145

Methods

route

▸ route(spec): void

Specify an HttpAction to be used to respond to requests for an HTTP method (e.g. "GET") and a path or pathPrefix.

Paths must begin with a slash. Path prefixes must also end in a slash.

// matches `/profile` (but not `/profile/`)
http.route({ path: "/profile", method: "GET", handler: getProfile})

// matches `/profiles/`, `/profiles/abc`, and `/profiles/a/c/b` (but not `/profile`)
http.route({ pathPrefix: "/profile/", method: "GET", handler: getProfile})

Parameters

Name	Type
spec	RouteSpec

Returns

void

Defined in

server/router.ts:161

---

getRoutes

▸ getRoutes(): readonly [string, "GET" | "POST" | "PUT" | "DELETE" | "OPTIONS" | "PATCH", PublicHttpAction][]

Returns a list of routed HTTP actions.

These are used to populate the list of routes shown in the Functions page of the Convex dashboard.

Returns

readonly [string, "GET" | "POST" | "PUT" | "DELETE" | "OPTIONS" | "PATCH", PublicHttpAction][]

• an array of [path, method, endpoint] tuples.

Defined in

server/router.ts:229

---

lookup

▸ lookup(path, method): null | readonly [PublicHttpAction, "GET" | "POST" | "PUT" | "DELETE" | "OPTIONS" | "PATCH", string]

Returns the appropriate HTTP action and its routed request path and method.

The path and method returned are used for logging and metrics, and should match up with one of the routes returned by getRoutes.

For example,

http.route({ pathPrefix: "/profile/", method: "GET", handler: getProfile});

http.lookup("/profile/abc", "GET") // returns [getProfile, "GET", "/profile/*"]

Parameters

Name	Type
path	string
method	"GET" | "POST" | "PUT" | "DELETE" | "OPTIONS" | "PATCH" | "HEAD"

Returns

null | readonly [PublicHttpAction, "GET" | "POST" | "PUT" | "DELETE" | "OPTIONS" | "PATCH", string]

• a tuple [PublicHttpAction, method, path] or null.

Defined in

server/router.ts:275

---

runRequest

▸ runRequest(argsStr, requestRoute): Promise<string>

Given a JSON string representation of a Request object, return a Response by routing the request and running the appropriate endpoint or returning a 404 Response.

Parameters

Name	Type	Description
argsStr	string	a JSON string representing a Request object.
requestRoute	string	-

Returns

Promise<string>

• a Response object.

Defined in

server/router.ts:304