id	title	sidebar_label	hide_title	description
createApi	createApi	createApi	true	RTK Query > API: createApi reference

`createApi`

createApi is the core of RTK Query's functionality. It allows you to define a set of "endpoints" that describe how to retrieve data from backend APIs and other async sources, including the configuration of how to fetch and transform that data. It generates an "API slice" structure that contains Redux logic (and optionally React hooks) that encapsulate the data fetching and caching process for you.

:::tip

Typically, you should only have one API slice per base URL that your application needs to communicate with. For example, if your site fetches data from both /api/posts and /api/users, you would have a single API slice with /api/ as the base URL, and separate endpoint definitions for posts and users. This allows you to effectively take advantage of automated re-fetching by defining tag relationships across endpoints.

This is because:

Automatic tag invalidation only works within a single API slice. If you have multiple API slices, the automatic invalidation won't work across them.
Every createApi call generates its own middleware, and each middleware added to the store will run checks against every dispatched action. That has a perf cost that adds up. So, if you called createApi 10 times and added 10 separate API middleware to the store, that will be noticeably slower perf-wise.

For maintainability purposes, you may wish to split up endpoint definitions across multiple files, while still maintaining a single API slice which includes all of these endpoints. See code splitting for how you can use the injectEndpoints property to inject API endpoints from other files into a single API slice definition.

:::

// file: src/services/types.ts noEmit
export type Pokemon = {}

// file: src/services/pokemon.ts
// Need to use the React-specific entry point to allow generating React hooks
import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'
import type { Pokemon } from './types'

// highlight-start
// Define a service using a base URL and expected endpoints
export const pokemonApi = createApi({
  reducerPath: 'pokemonApi',
  baseQuery: fetchBaseQuery({ baseUrl: 'https://pokeapi.co/api/v2/' }),
  endpoints: (build) => ({
    getPokemonByName: build.query<Pokemon, string>({
      query: (name) => `pokemon/${name}`,
    }),
  }),
})
//highlight-end

// highlight-start
// Export hooks for usage in function components, which are
// auto-generated based on the defined endpoints
export const { useGetPokemonByNameQuery } = pokemonApi
// highlight-end

`createApi` Parameters

createApi accepts a single configuration object parameter with the following options:

  baseQuery(args: InternalQueryArgs, api: BaseQueryApi, extraOptions?: DefinitionExtraOptions): any;
  endpoints(build: EndpointBuilder<InternalQueryArgs, TagTypes>): Definitions;
  extractRehydrationInfo?: (
    action: UnknownAction,
    {
      reducerPath,
    }: {
      reducerPath: ReducerPath
    }
  ) =>
    | undefined
    | CombinedState<Definitions, TagTypes, ReducerPath>
  tagTypes?: readonly TagTypes[];
  reducerPath?: ReducerPath;
  serializeQueryArgs?: SerializeQueryArgs<InternalQueryArgs>;
  keepUnusedDataFor?: number; // value is in seconds
  refetchOnMountOrArgChange?: boolean | number; // value is in seconds
  refetchOnFocus?: boolean;
  refetchOnReconnect?: boolean;

`baseQuery`

summary

baseQuery function arguments

args - The return value of the query function for a given endpoint
api - The BaseQueryApi object contains:
- signal - An AbortSignal object that may be used to abort DOM requests and/or read whether the request is aborted.
- abort - The abort() method of the AbortController attached to signal.
- dispatch - The store.dispatch method for the corresponding Redux store
- getState - A function that may be called to access the current store state
- extra - Provided as thunk.extraArgument to the configureStore getDefaultMiddleware option.
- endpoint - The name of the endpoint.
- type - Type of request (query or mutation).
- forced - Indicates if a query has been forced.
- queryCacheKey- The computed query cache key.
extraOptions - The value of the optional extraOptions property provided for a given endpoint

baseQuery function signature

export type BaseQueryFn<
  Args = any,
  Result = unknown,
  Error = unknown,
  DefinitionExtraOptions = {},
  Meta = {},
> = (
  args: Args,
  api: BaseQueryApi,
  extraOptions: DefinitionExtraOptions,
) => MaybePromise<QueryReturnValue<Result, Error, Meta>>

export interface BaseQueryApi {
  signal: AbortSignal
  abort: (reason?: string) => void
  dispatch: ThunkDispatch<any, any, any>
  getState: () => unknown
  extra: unknown
  endpoint: string
  type: 'query' | 'mutation'
  forced?: boolean
}

export type QueryReturnValue<T = unknown, E = unknown, M = unknown> =
  | {
      error: E
      data?: undefined
      meta?: M
    }
  | {
      error?: undefined
      data: T
      meta?: M
    }

examples

`endpoints`

summary

See Endpoint Definition Parameters for details on individual properties.

Query endpoint definition

Query endpoints (defined with build.query()) are used to cache data fetched from the server.

You must specify either a query field (which will use the API's baseQuery to make a request), or a queryFn function with your own async logic. All other fields are optional.

export type QueryDefinition<
  QueryArg,
  BaseQuery extends BaseQueryFn,
  TagTypes extends string,
  ResultType,
  ReducerPath extends string = string,
> = {
  query(arg: QueryArg): BaseQueryArg<BaseQuery>

  /* either `query` or `queryFn` can be present, but not both simultaneously */
  queryFn(
    arg: QueryArg,
    api: BaseQueryApi,
    extraOptions: BaseQueryExtraOptions<BaseQuery>,
    baseQuery: (arg: Parameters<BaseQuery>[0]) => ReturnType<BaseQuery>,
  ): MaybePromise<QueryReturnValue<ResultType, BaseQueryError<BaseQuery>>>

  /* transformResponse only available with `query`, not `queryFn` */
  transformResponse?(
    baseQueryReturnValue: BaseQueryResult<BaseQuery>,
    meta: BaseQueryMeta<BaseQuery>,
    arg: QueryArg,
  ): ResultType | Promise<ResultType>

  /* transformErrorResponse only available with `query`, not `queryFn` */
  transformErrorResponse?(
    baseQueryReturnValue: BaseQueryError<BaseQuery>,
    meta: BaseQueryMeta<BaseQuery>,
    arg: QueryArg,
  ): unknown

  extraOptions?: BaseQueryExtraOptions<BaseQuery>

  providesTags?: ResultDescription<
    TagTypes,
    ResultType,
    QueryArg,
    BaseQueryError<BaseQuery>
  >

  keepUnusedDataFor?: number

  onQueryStarted?(
    arg: QueryArg,
    {
      dispatch,
      getState,
      extra,
      requestId,
      queryFulfilled,
      getCacheEntry,
      updateCachedData, // available for query endpoints only
    }: QueryLifecycleApi,
  ): Promise<void>

  onCacheEntryAdded?(
    arg: QueryArg,
    {
      dispatch,
      getState,
      extra,
      requestId,
      cacheEntryRemoved,
      cacheDataLoaded,
      getCacheEntry,
      updateCachedData, // available for query endpoints only
    }: QueryCacheLifecycleApi,
  ): Promise<void>

  argSchema?: StandardSchemaV1<QueryArg>

  /* only available with `query`, not `queryFn` */
  rawResponseSchema?: StandardSchemaV1<BaseQueryResult<BaseQuery>>

  responseSchema?: StandardSchemaV1<ResultType>

  /* only available with `query`, not `queryFn` */
  rawErrorResponseSchema?: StandardSchemaV1<BaseQueryError<BaseQuery>>

  errorResponseSchema?: StandardSchemaV1<BaseQueryError<BaseQuery>>

  metaSchema?: StandardSchemaV1<BaseQueryMeta<BaseQuery>>
}

Infinite Query endpoint definition

Infinite query endpoints (defined with build.infiniteQuery()) are used to cache multi-page data sets from the server. They have all the same callbacks and options as standard query endpoints, but also require an additional infiniteQueryOptions field to specify how to calculate the unique parameters to fetch each page.

For infinite query endpoints, there is a separation between the "query arg" used for the cache key, and the "page param" used to fetch a specific page. For example, a Pokemon API endpoint might have a string query arg like "fire" , but use a page number as the param to determine which page to fetch out of the results. The query and queryFn methods will receive a combined {queryArg, pageParam} object as the argument, rather than just the queryArg by itself.

export type PageParamFunction<DataType, PageParam> = (
  firstPage: DataType,
  allPages: Array<DataType>,
  firstPageParam: PageParam,
  allPageParams: Array<PageParam>,
) => PageParam | undefined | null

type InfiniteQueryCombinedArg<QueryArg, PageParam> = {
  queryArg: QueryArg
  pageParam: PageParam
}

export type InfiniteQueryDefinition<
  QueryArg,
  PageParam,
  BaseQuery extends BaseQueryFn,
  TagTypes extends string,
  ResultType,
  ReducerPath extends string = string,
> =
  // Infinite queries have all the same options as query endpoints,
  // but store the `{pages, pageParams}` structure, and receive an object
  // with both `{queryArg, pageParam}` as the arg for `query` and `queryFn`.
  QueryDefinition<
    InfiniteQueryCombinedArg<QueryArg, PageParam>,
    BaseQuery,
    TagTypes,
    InfiniteData<ResultType>
  > & {
    /**
     * Required options to configure the infinite query behavior.
     * `initialPageParam` and `getNextPageParam` are required, to
     * ensure the infinite query can properly fetch the next page of data.
     * `initialPageparam` may be specified when using the
     * endpoint, to override the default value.
     */
    infiniteQueryOptions: {
      /**
       * The initial page parameter to use for the first page fetch.
       */
      initialPageParam: PageParam
      /**
       * This function is required to automatically get the next cursor for infinite queries.
       * The result will also be used to determine the value of `hasNextPage`.
       */
      getNextPageParam: PageParamFunction<DataType, PageParam>
      /**
       * This function can be set to automatically get the previous cursor for infinite queries.
       * The result will also be used to determine the value of `hasPreviousPage`.
       */
      getPreviousPageParam?: PageParamFunction<DataType, PageParam>
      /**
       * If specified, only keep this many pages in cache at once.
       * If additional pages are fetched, older pages in the other
       * direction will be dropped from the cache.
       */
      maxPages?: number
    }
  }

Mutation endpoint definition

Mutation endpoints (defined with build.mutation()) are used to send updates to the server, and force invalidation and refetching of query endpoints.

As with queries, you must specify either the query option or the queryFn async method.

export type MutationDefinition<
  QueryArg,
  BaseQuery extends BaseQueryFn,
  TagTypes extends string,
  ResultType,
  ReducerPath extends string = string,
  Context = Record<string, any>,
> = {
  query(arg: QueryArg): BaseQueryArg<BaseQuery>

  /* either `query` or `queryFn` can be present, but not both simultaneously */
  queryFn(
    arg: QueryArg,
    api: BaseQueryApi,
    extraOptions: BaseQueryExtraOptions<BaseQuery>,
    baseQuery: (arg: Parameters<BaseQuery>[0]) => ReturnType<BaseQuery>,
  ): MaybePromise<QueryReturnValue<ResultType, BaseQueryError<BaseQuery>>>

  /* transformResponse only available with `query`, not `queryFn` */
  transformResponse?(
    baseQueryReturnValue: BaseQueryResult<BaseQuery>,
    meta: BaseQueryMeta<BaseQuery>,
    arg: QueryArg,
  ): ResultType | Promise<ResultType>

  /* transformErrorResponse only available with `query`, not `queryFn` */
  transformErrorResponse?(
    baseQueryReturnValue: BaseQueryError<BaseQuery>,
    meta: BaseQueryMeta<BaseQuery>,
    arg: QueryArg,
  ): unknown

  extraOptions?: BaseQueryExtraOptions<BaseQuery>

  invalidatesTags?: ResultDescription<TagTypes, ResultType, QueryArg>

  onQueryStarted?(
    arg: QueryArg,
    {
      dispatch,
      getState,
      extra,
      requestId,
      queryFulfilled,
      getCacheEntry,
    }: MutationLifecycleApi,
  ): Promise<void>

  onCacheEntryAdded?(
    arg: QueryArg,
    {
      dispatch,
      getState,
      extra,
      requestId,
      cacheEntryRemoved,
      cacheDataLoaded,
      getCacheEntry,
    }: MutationCacheLifecycleApi,
  ): Promise<void>
}

How endpoints get used

When defining a key like getPosts as shown below, it's important to know that this name will become exportable from api and be able to referenced under api.endpoints.getPosts.useQuery(), api.endpoints.getPosts.initiate() and api.endpoints.getPosts.select(). The same thing applies to mutations but they reference useMutation instead of useQuery.

import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'
interface Post {
  id: number
  name: string
}
type PostsResponse = Post[]

const api = createApi({
  baseQuery: fetchBaseQuery({ baseUrl: '/' }),
  tagTypes: ['Posts'],
  endpoints: (build) => ({
    getPosts: build.query<PostsResponse, void>({
      query: () => 'posts',
      providesTags: (result) =>
        result ? result.map(({ id }) => ({ type: 'Posts', id })) : [],
    }),
    addPost: build.mutation<Post, Partial<Post>>({
      query: (body) => ({
        url: `posts`,
        method: 'POST',
        body,
      }),
      invalidatesTags: ['Posts'],
    }),
  }),
})

// Auto-generated hooks
export const { useGetPostsQuery, useAddPostMutation } = api

// Possible exports
export const { endpoints, reducerPath, reducer, middleware } = api
// reducerPath, reducer, middleware are only used in store configuration
// endpoints will have:
// endpoints.getPosts.initiate(), endpoints.getPosts.select(), endpoints.getPosts.useQuery()
// endpoints.addPost.initiate(), endpoints.addPost.select(), endpoints.addPost.useMutation()
// see `createApi` overview for _all exports_

`extractRehydrationInfo`

summary

examples

`tagTypes`

summary

examples

`reducerPath`

summary

examples

`serializeQueryArgs`

summary

By default, this function will take the query arguments, sort object keys where applicable, stringify the result, and concatenate it with the endpoint name. This creates a cache key based on the combination of arguments + endpoint name (ignoring object key order), such that calling any given endpoint with the same arguments will result in the same cache key.

`invalidationBehavior`

summary

`keepUnusedDataFor`

summary

`refetchOnMountOrArgChange`

summary

:::note You can set this globally in createApi, but you can also override the default value and have more granular control by passing refetchOnMountOrArgChange to each individual hook call or similarly by passing forceRefetch: true when dispatching the initiate action. :::

`refetchOnFocus`

summary

:::note You can set this globally in createApi, but you can also override the default value and have more granular control by passing refetchOnFocus to each individual hook call or when dispatching the initiate action.

If you specify track: false when manually dispatching queries, RTK Query will not be able to automatically refetch for you. :::

`refetchOnReconnect`

summary

:::note You can set this globally in createApi, but you can also override the default value and have more granular control by passing refetchOnReconnect to each individual hook call or when dispatching the initiate action.

If you specify track: false when manually dispatching queries, RTK Query will not be able to automatically refetch for you. :::

`onSchemaFailure`

summary

examples

:::note You can set this globally in createApi, but you can also override the default value and have more granular control by passing onSchemaFailure to each individual endpoint definition. :::

`catchSchemaFailure`

summary

examples

:::note You can set this globally in createApi, but you can also override the default value and have more granular control by passing catchSchemaFailure to each individual endpoint definition. :::

`skipSchemaValidation`

summary

examples

:::note You can set this globally in createApi, but you can also override the default value and have more granular control by passing skipSchemaValidation to each individual endpoint definition. :::

Endpoint Definition Parameters

`query`

(required if no queryFn provided)

export type query = <QueryArg>(
  arg: QueryArg,
) => string | Record<string, unknown>

// with `fetchBaseQuery`
export type query = <QueryArg>(arg: QueryArg) => string | FetchArgs

summary

examples

`queryFn`

(required if no query provided)

summary

Called with the same arguments as baseQuery, as well as the provided baseQuery function itself. It is expected to return an object with either a data or error property, or a promise that resolves to return such an object.

queryFn(
  arg: QueryArg,
  api: BaseQueryApi,
  extraOptions: BaseQueryExtraOptions<BaseQuery>,
  baseQuery: (arg: Parameters<BaseQuery>[0]) => ReturnType<BaseQuery>
): MaybePromise<
| {
    error: BaseQueryError<BaseQuery>
    data?: undefined
  }
| {
    error?: undefined
    data: ResultType
  }
>

export interface BaseQueryApi {
  signal: AbortSignal
  dispatch: ThunkDispatch<any, any, any>
  getState: () => unknown
}

`queryFn` function arguments

args - The argument provided when the query itself is called
api - The BaseQueryApi object, containing signal, dispatch and getState properties
- signal - An AbortSignal object that may be used to abort DOM requests and/or read whether the request is aborted.
- dispatch - The store.dispatch method for the corresponding Redux store
- getState - A function that may be called to access the current store state
extraOptions - The value of the optional extraOptions property provided for the endpoint
baseQuery - The baseQuery function provided to the api itself

examples

`infiniteQueryOptions`

(only for infiniteQuery endpoints)

summary

The infiniteQueryOptions field includes:

initialPageParam: the default page param value used for the first request, if this was not specified at the usage site
getNextPageParam: a required callback you must provide to calculate the next page param, given the existing cached pages and page params
getPreviousPageParam: an optional callback that will be used to calculate the previous page param, if you try to fetch backwards.
maxPages: an optional limit to how many fetched pages will be kept in the cache entry at a time

examples

`transformResponse`

(optional, not applicable with queryFn)

summary

In some cases, you may want to manipulate the data returned from a query before you put it in the cache. In this instance, you can take advantage of transformResponse.

transformResponse: (response, meta, arg) =>
  response.some.deeply.nested.collection

`transformErrorResponse`

(optional, not applicable with queryFn)

summary

In some cases, you may want to manipulate the error returned from a query before you put it in the cache. In this instance, you can take advantage of transformErrorResponse.

transformErrorResponse: (response, meta, arg) =>
  response.data.some.deeply.nested.errorObject