Type Alias: KyInstance()

type KyInstance = ResponsePromise<T>;

type KyInstance<T>(url: Input, options?: KyRequestOptions): ResponsePromise<T>;

Fetch the given url.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
url	Input	Request object, URL object, or URL string.
options?	KyRequestOptions	-

Returns

ResponsePromise<T>

A promise with Body method added.

Example

import ky from 'ky';

const json = await ky('https://example.com', {json: {foo: true}}).json();

console.log(json);
//=> `{data: '🦄'}`

Properties

Property	Modifier	Type	Description
create	public	(defaultOptions?: KyRequestOptions) => KyInstance	Create a new Ky instance with complete new defaults.
delete	public	<T>(url: Input, options?: KyRequestOptions) => ResponsePromise<T>	Fetch the given url using the option {method: 'delete'}.
extend	public	(defaultOptions: | KyRequestOptions | (parentOptions: KyRequestOptions) => KyRequestOptions) => KyInstance	Create a new Ky instance with some defaults overridden with your own. In contrast to ky.create(), ky.extend() inherits defaults from its parent. You can also refer to parent defaults by providing a function to .extend(). Example import ky from 'ky'; const api = ky.create({prefixUrl: 'https://example.com/api'}); const usersApi = api.extend((options) => ({prefixUrl: ${options.prefixUrl}/users})); const response = await usersApi.get('123'); //=> 'https://example.com/api/users/123' const response = await api.get('version'); //=> 'https://example.com/api/version'
get	public	<T>(url: Input, options?: KyRequestOptions) => ResponsePromise<T>	Fetch the given url using the option {method: 'get'}.
head	public	(url: Input, options?: KyRequestOptions) => ResponsePromise	Fetch the given url using the option {method: 'head'}.
patch	public	<T>(url: Input, options?: KyRequestOptions) => ResponsePromise<T>	Fetch the given url using the option {method: 'patch'}.
post	public	<T>(url: Input, options?: KyRequestOptions) => ResponsePromise<T>	Fetch the given url using the option {method: 'post'}.
put	public	<T>(url: Input, options?: KyRequestOptions) => ResponsePromise<T>	Fetch the given url using the option {method: 'put'}.
retry	readonly	typeof retry	Force a retry from an afterResponse hook. This allows you to retry a request based on the response content, even if the response has a successful status code. The retry will respect the retry.limit option and skip the shouldRetry check. The forced retry is observable in beforeRetry hooks, where the error will be a ForceRetryError. Example import ky, {isForceRetryError} from 'ky'; const api = ky.extend({ hooks: { afterResponse: [ async (request, options, response) => { // Retry based on response body content if (response.status === 200) { const data = await response.clone().json(); // Simple retry with default delay if (data.error?.code === 'TEMPORARY_ERROR') { return ky.retry(); } // Retry with custom delay from API response if (data.error?.code === 'RATE_LIMIT') { return ky.retry({ delay: data.error.retryAfter * 1000, code: 'RATE_LIMIT' }); } } } ], beforeRetry: [ ({error, retryCount}) => { // Observable in beforeRetry hooks if (isForceRetryError(error)) { console.log(Forced retry #${retryCount}: ${error.message}); // Example output: "Forced retry #1: Forced retry: RATE_LIMIT" } } ] } }); const response = await api.get('https://example.com/api');
stop	readonly	typeof stop	A Symbol that can be returned by a beforeRetry hook to stop the retry. This will also short circuit the remaining beforeRetry hooks. Note: Returning this symbol makes Ky abort and return with an undefined response. Be sure to check for a response before accessing any properties on it or use optional chaining. It is also incompatible with body methods, such as .json() or .text(), because there is no response to parse. In general, we recommend throwing an error instead of returning this symbol, as that will cause Ky to abort and then throw, which avoids these limitations. A valid use-case for ky.stop is to prevent retries when making requests for side effects, where the returned data is not important. For example, logging client activity to the server. Example import ky from 'ky'; const options = { hooks: { beforeRetry: [ async ({request, options, error, retryCount}) => { const shouldStopRetry = await ky('https://example.com/api'); if (shouldStopRetry) { return ky.stop; } } ] } }; // Note that response will be undefinedin caseky.stopis returned. const response = await ky.post('https://example.com', options); // Using.text() or other body methods is not supported. const text = await ky('https://example.com', options).text();