Send and read JSON

Use ky when you want to send a JSON request body and read the response as a typed value. The json option serializes the request body, and .json<T>() parses the response body and gives the result the TypeScript type T.

Send a request and read its response

1. Pass the value to send in the json option; see Add request headers for how Ky serializes it and sets Content-Type.
2. Call .json<T>() on the request to get a promise for the parsed response body, typed to the response shape your endpoint returns.

ts
Copy
import ky from 'ky';

const main = async (): Promise<void> => {
	const createdUser = await ky.post('https://api.example.com/users', {
		json: {name: 'Ada'},
	}).json<{id: number; name: string}>();

	console.log(`Created ${createdUser.name} (${createdUser.id})`);
};

void main();

When the endpoint returns JSON with an id and name, createdUser has those typed fields and the log displays them. The type argument guides TypeScript; it does not validate the response at runtime. Keep it aligned with the endpoint's response contract.

Options that matter

The body method also sets an appropriate Accept header. It throws an HTTPError for a non-2xx response when HTTP errors are enabled, and .json() throws if the body is empty because it cannot be parsed.

Pitfalls

• ky.stop makes the request resolve with undefined, so there is no response to inspect and body shortcuts such as .json() are incompatible with it. Throw from beforeRetry instead when the caller needs an error rather than a missing response.
• The type argument on .json<T>() is not runtime validation. If the response needs validation, use the approach in Validate JSON responses.

Related

• Ky quick start
• Add request headers
• Ky errors and validation