Request

assertMethod(event, expected, allowHead?)

Asserts that the incoming request method is of the expected type using isMethod.

If the method is not allowed, it will throw a 405 error with the message "HTTP method is not allowed".

getHeader(event, name)

Get a request header by name.

getHeaders(event)

Get the request headers object.

Array headers are joined with a comma.

getQuery(event)

Get query the params object from the request URL parsed with unjs/ufo.

getRequestHeader(event, name)

Get a request header by name.

getRequestHeaders(event)

Get the request headers object.

Array headers are joined with a comma.

getRequestHost(event, opts: { xForwardedHost? })

Get the request hostname.

If xForwardedHost is true, it will use the x-forwarded-host header if it exists.

If no host header is found, it will default to "localhost".

getRequestIP(event)

Try to get the client IP address from the incoming request.

If xForwardedFor is true, it will use the x-forwarded-for header if it exists.

getRequestProtocol(event, opts: { xForwardedProto? })

Get the request protocol.

If x-forwarded-proto header is set to "https", it will return "https". You can disable this behavior by setting xForwardedProto to false.

If protocol cannot be determined, it will default to "http".

getRequestURL(event, opts: { xForwardedHost?, xForwardedProto? })

Generated the full incoming request URL using getRequestProtocol, getRequestHost and event.path.

If xForwardedHost is true, it will use the x-forwarded-host header if it exists.

If xForwardedProto is false, it will not use the x-forwarded-proto header.

getRouterParam(event, name, opts: { decode? })

Get a matched route param by name.

getRouterParams(event, opts: { decode? })

Get matched route params.

If decode option is true, it will decode the matched route params using decodeURI.

getValidatedQuery(event, validate)

Get the query param from the request URL parsed with unjs/ufo and validated with validate function.

getValidatedRouterParams(event, validate, opts: { decode? })

Get matched route params and validate with validate function.

isMethod(event, expected, allowHead?)

Checks if the incoming request method is of the expected type.

If allowHead is true, it will allow HEAD requests to pass if the expected method is GET.

toWebRequest(event)

Convert the H3Event to a WebRequest object.

NOTE: This function is not stable and might have edge cases that are not handled properly.

getRequestFingerprint(event, opts)

Get a unique fingerprint for the incoming request.

Body utils

getRequestWebStream(event)

Captures a stream from a request.

readBody(event, options: { strict? })

Reads request body and tries to safely parse using destr.

Example:

export default defineEventHandler(async (event) => {
  const body = await readBody(event);
});

readFormData(event)

Constructs a FormData object from an event, after converting it to a a web request.

Example:

export default defineEventHandler(async (event) => {
  const formData = await readFormData(event);
  const email = formData.get("email");
  const password = formData.get("password");
});

readMultipartFormData(event)

Tries to read and parse the body of a an H3Event as multipart form.

Example:

export default defineEventHandler(async (event) => {
  const formData = await readMultipartFormData(event);
  // The result could look like:
  // [
  //   {
  //     "data": "other",
  //     "name": "baz",
  //   },
  //   {
  //     "data": "something",
  //     "name": "some-other-data",
  //   },
  // ];
});

readRawBody(event, encoding)

Reads body of the request and returns encoded raw string (default), or Buffer if encoding is falsy.

Example:

export default defineEventHandler(async (event) => {
  const body = await readRawBody(event, "utf-8");
});

readValidatedBody(event, validate)

Tries to read the request body via readBody, then uses the provided validation function and either throws a validation error or returns the result.

You can use a simple function to validate the body or use a library like zod to define a schema.

Example:

export default defineEventHandler(async (event) => {
  const body = await readValidatedBody(event, (body) => {
    return typeof body === "object" && body !== null;
  });
});

Example:

import { z } from "zod";
export default defineEventHandler(async (event) => {
  const objectSchema = z.object();
  const body = await readValidatedBody(event, objectSchema.safeParse);
});