sindresorhus / ky

> Ky is a tiny and elegant HTTP client based on the Fetch API Ky targets modern browsers, Node.js, Bun, and Deno. It's just a tiny package with no dependencies. Benefits over plain • Simpler API • Method shortcuts ( ) • Treats non-2xx status codes as errors (after redirects) • Retries failed requests • JSON option • Timeout support • Base URL option • Instances with custom defaults • Hooks • TypeScript niceties (e.g. supports generics and defaults to , not ) Install > [!NOTE] > This readme is for the next version of Ky. For the current version, click here. CDN • jsdelivr • unpkg • esm.sh Usage With plain , it would be: If you are using Deno, import Ky from a URL. For example, using a CDN: API ky(input, options?) The and are the same as , with additional available (see below). Returns a object with methods added for convenience. So you can, for example, call directly without having to await the first. When called like that, an appropriate header will be set depending on the body method used. Unlike the methods of , these will throw an if the response status is not in the range of . Also, will return if body is empty or the response status is instead of throwing a parse error due to an empty body. Available body shortcuts: , , , , , and . The shortcut is only present when the runtime supports . ⌨️ **TypeScript:** Accepts an optional type parameter, which defaults to , and is passed through to the return type of . You can also get the response body as JSON and validate it with a Standard Schema compatible validator (for example, Zod 3.24+). This throws a when validation fails. ky.get(input, options?) ky.post(input, options?) ky.put(input, options?) ky.patch(input, options?) ky.head(input, options?) ky.delete(input, options?) Sets to the method name and makes a request. ⌨️ **TypeScript:** Accepts an optional type parameter for use with JSON responses (see ). input Type: | | Same as input. When using a instance as , any URL altering options (such as ) will be ignored. options Type: Same as options, plus the following additional options: method Type: \ Default: HTTP method used to make the request. Internally, the standard methods ( , , , , and ) are uppercased in order to avoid server errors due to case sensitivity. json Type: and any other value accepted by Shortcut for sending JSON. Use this instead of the option. Accepts any plain object or value, which will be 'd and sent in the body with the correct header set. searchParams Type: \ Default: Search parameters to include in the request URL. Setting this will override all existing search parameters in the input URL. Accepts any value supported by . When passing an object, values are automatically filtered out, while values are preserved and converted to the string . baseUrl Type: A base URL to resolve the against. When the (after applying the option) is only a relative URL, such as , , or , it will be resolved against the to determine the destination of the request. Otherwise, the is absolute, such as , and it will bypass the . Useful when used with to create niche-specific Ky-instances. If the itself is relative, it will be resolved against the environment's base URL, such as in browsers or in Deno (see the flag). **Tip:** When setting a that has a path, we recommend that it include a trailing slash , as in rather than . This ensures more intuitive behavior for page-relative URLs, such as or , where they will _extend_ from the full path of the rather than _replacing_ its last path segment. prefix Type: A prefix to prepend to the before making the request (and before it is resolved against the ). It can be any valid path or URL, either relative or absolute. A trailing slash is optional and will be added automatically, if needed, when it is joined with . Only takes effect when is a string. Useful when used with to create niche-specific Ky-instances. *In most cases, you should use the option instead, as it is more consistent with web standards. However, is useful if you want origin-relative URLs, such as , to be treated as if they were page-relative. In other words, the leading slash of the will essentially be ignored, because the will become part of the before URL resolution happens.* Notes: • The and are joined with a slash , and slashes are normalized at the join boundary by trimming trailing slashes from and leading slashes from . • After and are joined, the result is resolved against the option, if present. retry Type: \ Default: • : • : • : • : , , • : • : • : • : • : • : An object representing , , , , , , , , , and fields for maximum retry count, allowed methods, allowed status codes, status codes allowed to use the time, maximum time, backoff limit, delay calculation function, retry jitter, timeout retry behavior, and custom retry logic. If is a number, it will be used as and other defaults will remain in place. If the response provides an HTTP status contained in , Ky will wait until the date, timeout, or timestamp given in the header has passed to retry the request. If is missing, the non-standard header is used in its place as a fallback. If the provided status code is not in the list, the header will be ignored. If is set to , it will use . If header is greater than , it will use . The option is the upper limit of the delay per retry in milliseconds. To clamp the delay, set to 1000, for example. By default, the delay is calculated with . The delay increases exponentially. The option can be used to change how the delay between retries is calculated. The function receives one parameter, the attempt count, starting at . The option adds random jitter to retry delays to prevent thundering herd problems. When many clients retry simultaneously (e.g., after hitting a rate limit), they can overwhelm the server again. Jitter adds randomness to break this synchronization. Set to to use full jitter, which randomizes the delay between 0 and the computed delay. Alternatively, pass a fun…