> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/unjs/ofetch/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Headers

> Add custom headers to your requests with the headers option

ofetch makes it easy to add custom headers to your requests using the `headers` option.

## Basic Usage

<CodeGroup>
  ```typescript Object notation theme={null}
  import { ofetch } from 'ofetch'

  await ofetch('/api/users', {
    headers: {
      'Authorization': 'Bearer token123',
      'X-Custom-Header': 'value'
    }
  })
  ```

  ```typescript Headers instance theme={null}
  import { ofetch } from 'ofetch'

  const headers = new Headers()
  headers.set('Authorization', 'Bearer token123')
  headers.set('X-Custom-Header', 'value')

  await ofetch('/api/users', { headers })
  ```

  ```typescript Array notation theme={null}
  import { ofetch } from 'ofetch'

  await ofetch('/api/users', {
    headers: [
      ['Authorization', 'Bearer token123'],
      ['X-Custom-Header', 'value']
    ]
  })
  ```
</CodeGroup>

## Automatic Headers for JSON

When sending JSON bodies, ofetch automatically sets headers for you:

```typescript theme={null}
await ofetch('/api/users', {
  method: 'POST',
  body: { name: 'John' }
})
// Automatically adds:
// content-type: application/json
// accept: application/json
```

You can override these defaults:

```typescript theme={null}
await ofetch('/api/users', {
  method: 'POST',
  body: { name: 'John' },
  headers: {
    'content-type': 'application/vnd.api+json'
  }
})
```

## Merging Headers

Headers are merged when using `$fetch.create()` or when passing a `Request` object:

```typescript theme={null}
const api = ofetch.create({
  headers: {
    'Authorization': 'Bearer token123',
    'X-API-Version': '1.0'
  }
})

// These headers are merged with the defaults
await api('/users', {
  headers: {
    'X-Custom-Header': 'value',
    'X-API-Version': '2.0'  // Overrides default
  }
})
// Final headers:
// Authorization: Bearer token123
// X-API-Version: 2.0
// X-Custom-Header: value
```

## Headers from Request Object

Headers from `Request` objects are preserved and can be overridden:

```typescript theme={null}
const req = new Request('https://api.example.com/users', {
  headers: { 'foo': '1' }
})

await ofetch(req, {
  headers: {
    'foo': '2',  // Overrides Request header
    'bar': '3'   // Added to Request headers
  }
})
// Final headers: foo: 2, bar: 3
```

## Common Patterns

### Authentication

```typescript theme={null}
const api = ofetch.create({
  baseURL: 'https://api.example.com',
  headers: {
    'Authorization': `Bearer ${getToken()}`
  }
})
```

### API Versioning

```typescript theme={null}
await ofetch('/api/users', {
  headers: {
    'Accept': 'application/vnd.myapi.v2+json'
  }
})
```

### Custom User Agent

```typescript theme={null}
await ofetch('https://api.example.com/data', {
  headers: {
    'User-Agent': 'MyApp/1.0'
  }
})
```

### Content Negotiation

```typescript theme={null}
await ofetch('/api/report', {
  headers: {
    'Accept': 'application/pdf'
  },
  responseType: 'blob'
})
```

## Type Definition

Headers inherit from the standard `RequestInit` interface and support all native header formats:

```typescript theme={null}
headers?: HeadersInit
```

Where `HeadersInit` can be:

* `Headers` instance
* `Record<string, string>`
* `[string, string][]`

## Implementation Details

Headers are internally converted to a `Headers` instance and merged using the `mergeHeaders` function from `src/utils.ts:121-138`. Default headers are set at `src/fetch.ts:144-153` for JSON-serializable bodies.