Add request headers

Use a per-request headers option for one-off values, or add a beforeRequest hook to a ky instance to attach shared headers to its requests.

When to use each approach

Set headers on the request when a value applies only to that call. Put a header in an instance's request hook when the same value belongs on every request made through that instance, such as an application identifier.

Set headers for one request

Pass a plain object as headers in the request options. The header is sent with this request; other calls made through ky do not inherit it.

ts
Copy
import ky from 'ky';

async function loadProfile(): Promise<void> {
	const response = await ky.get('https://api.example.com/v1/profile', {
		headers: {
			'x-request-id': 'profile-view-42',
		},
	});

	const body = await response.text();
	console.log(body);
}

void loadProfile();

The request carries x-request-id: profile-view-42. In a browser, inspect the request's Headers in the Network panel to see the header that was sent. The call returns a response promise; here, .text() reads its response body.

Add a shared header with a request hook

Create an instance with extend() and use its beforeRequest hook to modify the outgoing request. The hook receives the request, so set the header on request.headers.

ts
Copy
import ky from 'ky';

const api = ky.extend({
	hooks: {
		beforeRequest: [
			({request}) => {
				request.headers.set('x-client-id', 'web-dashboard');
			},
		],
	},
});

async function loadProfile(): Promise<void> {
	const response = await api.get('https://api.example.com/v1/profile');

	const body = await response.text();
	console.log(body);
}

void loadProfile();

Requests made through api carry x-client-id: web-dashboard; calls through the default ky instance do not use this hook. The hook runs once before retry handling begins, and the response promise still gives you the response to read.

Options that matter

Pitfalls

• A beforeRequest hook runs once with retryCount equal to 0; it does not run again for a retry. Use the retry lifecycle when a header needs to change before a retry.
• An error thrown by a beforeRequest hook is fatal and does not trigger Ky's retry logic.
• The json option sets Content-Type to application/json unless your request headers option sets Content-Type itself.

Related

• Instances and defaults
• The request lifecycle
• Send and read JSON
• Ky options