API reference

Every export from @relayhttp/relay. Types are shown in TypeScript syntax.

On this page

relay()
Method helpers
RelayRequest
relay.create()
instance.extend()
Interceptors
RelayError
Options

#relay()

Signature

relay(input: string | URL | Request, options?: RelayOptions): RelayRequest

Sends a request. The method defaults to GET unless you pass options.method. The method helpers below are usually more readable.

Parameter	Type	Description
`input`	`string \| URL \| Request`	The URL to request. Relative URLs use `baseUrl`.
`options`	`RelayOptions`	Optional. See Options.

Returns RelayRequest: a promise for a Response with body helpers.

Example

const res = await relay('https://api.example.com/health', { method: 'HEAD' });

#Method helpers

Signature

relay.get(input, options?)
relay.post(input, options?)
relay.put(input, options?)
relay.patch(input, options?)
relay.delete(input, options?)
relay.head(input, options?)

Shorthands that set options.method for you. They accept the same arguments as relay().

Returns RelayRequest

Example

await relay.patch('todos/7', { json: { done: true } });

#RelayRequest

The value returned by every request. Await it for the raw Response, or call a body helper:

Method	Returns	Description
`.json<T>()`	`Promise<T>`	Parses JSON. Returns `undefined` for empty 204 responses.
`.text()`	`Promise<string>`	Reads the body as text.
`.blob()`	`Promise<Blob>`	Reads the body as a Blob, e.g. for downloads.
`.arrayBuffer()`	`Promise<ArrayBuffer>`	Reads raw bytes.
`.formData()`	`Promise<FormData>`	Parses multipart or URL-encoded form bodies.

#relay.create()

Signature

relay.create(defaults: RelayOptions): RelayInstance

Creates a new instance with its own defaults and interceptors. Instances have every method the default export has.

Parameter	Type	Description
`defaults`	`RelayOptions`	Options applied to every request made with the instance.

Returns RelayInstance

Example

export const github = relay.create({
  baseUrl: 'https://api.github.com',
  headers: { accept: 'application/vnd.github+json' },
});

#instance.extend()

Signature

instance.extend(defaults: RelayOptions): RelayInstance

Creates a child instance that inherits the parent's defaults and interceptors, then layers new defaults on top. Headers are merged; other options are replaced.

Parameter	Type	Description
`defaults`	`RelayOptions`	Options to add or override.

Returns RelayInstance

Example

const admin = api.extend({ headers: { 'x-role': 'admin' } });

#Interceptors

Signature

instance.interceptors.request.use(fn: (request: Request) => void | Request | Promise<void | Request>): () => void
instance.interceptors.response.use(fn: (response: Response, request: Request) => Response | Promise<Response>): () => void

Registers a function that runs before each request or after each response. Return a new Request or Response to replace the original.

Returns A function that removes the interceptor.

Example

const stop = api.interceptors.request.use((req) => {
  console.time(req.url);
});

stop(); // remove it again

#RelayError

Thrown (as a rejected promise) for every failure. It extends Error.

Property	Type	Description
`code`	`'HTTP_ERROR' \| 'TIMEOUT' \| 'NETWORK_ERROR' \| 'ABORTED' \| 'PARSE_ERROR'`	What went wrong.
`status`	`number \| undefined`	HTTP status, when there was a response.
`request`	`Request`	The request that failed.
`response`	`Response \| undefined`	The response, for `HTTP_ERROR`.
`attempts`	`number`	How many attempts were made, including retries.

#Options

Option	Type	Description
`baseUrl`	`string`	Prepended to relative URLs.
`headers`	`HeadersInit`	Headers merged into every request.
`searchParams`	`Record \| string \| URLSearchParams`	Query string to append.
`json`	`unknown`	Serialised as the JSON body. Sets `Content-Type`.
`body`	`BodyInit`	Raw request body, e.g. `FormData`.
`timeout`	`number \| false`	Per-attempt timeout in ms. Default `10000`.
`totalTimeout`	`number \| false`	Timeout across all attempts. Default `false`.
`retry`	`RetryOptions \| number`	See Retries. Default limit `2`.
`dedupe`	`boolean`	Share one in-flight request between identical GETs. Default `true`.
`fetch`	`typeof fetch`	Custom fetch implementation, useful for tests.

Was this page helpful?

Edit this page on GitHub

Last updated September 18, 2026