# Headers

**Kind:** Constant

**Source:** [`packages/common/decorators/http/route-params.decorator.ts`](https://github.com/nestjs/nest/blob/master/packages/common/decorators/http/route-params.decorator.ts#L325)

**Part of:** [Common](subsystem-packages-common)

Route handler parameter decorator. Extracts the `headers`
property from the `req` object and populates the decorated
parameter with the value of `headers`.

For example: `async update(@Headers('Cache-Control') cacheControl: string)`

`Headers` is a route-handler parameter decorator that extracts the `headers` object from the incoming request. It can return all request headers or a specific header value when a header name is provided, allowing handlers to access HTTP metadata without manually reading from `req`.

## Definition

```ts
(property?: string) => ParameterDecorator
```

## Value

```ts
createRouteParamDecorator(RouteParamtypes.HEADERS)
```

## Diagram

```mermaid
graph LR
  A[Incoming HTTP Request] --> B[req.headers]
  B --> C[@Headers decorator]
  C --> D[Decorated route handler parameter]
  D --> E[Handler logic]
```

## Usage

```ts
import { Controller, Get, Headers } from '@nestjs/common';

@Controller('documents')
export class DocumentsController {
  @Get()
  findAll(@Headers('cache-control') cacheControl: string) {
    return {
      cacheControl,
    };
  }

  @Get('request-headers')
  getHeaders(@Headers() headers: Record<string, string | string[]>) {
    return headers;
  }
}
```

## AI Coding Instructions

- Use `@Headers()` when the handler needs the complete request headers object.
- Pass a header name, such as `@Headers('authorization')`, to inject only one header value.
- Prefer lowercase header names because Node.js normalizes incoming request header keys to lowercase.
- Treat extracted header values as potentially missing or as `string | string[] | undefined` when applicable.
- Keep request-specific parsing and validation in the route handler or a dedicated pipe/guard rather than modifying the decorator.