Redux Toolkit · Type Alias

MutationDefinition

MutationDefinition is the TypeScript shape of an RTK Query mutation endpoint. It types the request argument, result, base query, tags, reducer path, context, and endpoint behavior.

How it works

MutationDefinition is the type-level shape of an RTK Query mutation endpoint. It captures the argument, base-query, tag, result, reducer-path, and context types, plus endpoint callbacks and lifecycle options used to send updates, manage cache invalidation, and observe mutation state.

Syntax

export type MutationDefinition<QueryArg, BaseQuery extends BaseQueryFn, TagTypes extends string, ResultType, ReducerPath extends string = string, Context = Record<string, any>> = { ... }

Parameters

Name	Type	Description
`QueryArg`	`type`	Type of the mutation argument passed to `query` or `queryFn`.
`BaseQuery`	`BaseQueryFn`	Base query implementation used by the API.
`TagTypes`	`string`	String union of tag names available to the API.
`ResultType`	`type`	Type returned by the mutation.
`ReducerPath`	`string = string`	API reducer path; defaults to `string`.
`Context`	`Record<string, any> = Record<string, any>`	Context type available to endpoint callbacks; defaults to `Record<string, any>`.

Returns

A type describing the configuration and lifecycle behavior of an RTK Query mutation endpoint.

Key points

MutationDefinition applies to the mutation member of RTK Query's endpoint model.
Applications usually create a concrete definition by returning an object from build.mutation() inside createApi.
A usable mutation needs one request strategy: a base-query input via query, or custom asynchronous logic via queryFn.
Mutation definitions can coordinate server updates with cache invalidation and subsequent query refetching.
TypeScript callers should provide result and argument generics so endpoint inputs and outputs are checked.
The generated React hook returns a trigger together with an object describing the latest mutation state.

Common mistakes

Provide exactly one request implementation: query or queryFn; defining both is invalid.
This type describes mutation endpoints, not read-oriented query endpoints.

Example: Mutation endpoint

import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'

type Post = { id: number; title: string }

const api = createApi({
  baseQuery: fetchBaseQuery({ baseUrl: '/api' }),
  endpoints: (build) => ({
    updatePost: build.mutation<Post, { id: number; title: string }>({
      query: ({ id, title }) => ({
        url: `posts/${id}`,
        method: 'PUT',
        body: { title },
      }),
    }),
  }),
})

export const { useUpdatePostMutation } = api

// In a React component:
// const [updatePost] = useUpdatePostMutation()
// await updatePost({ id: 1, title: 'Updated' }).unwrap()

Defines a mutation endpoint that sends a PUT request and exposes a React mutation hook.

When to use it

Server mutations

Sending a server-side create, update, or delete request from an RTK Query API slice.

Cache refresh

Invalidating cached query data after a successful write so related data can be fetched again.

Type-safe React hooks

Typing generated mutation hooks so their trigger arguments and returned data are checked by TypeScript.

Interview questions

QWhat does MutationDefinition represent?

MutationDefinition is the generic type describing an RTK Query mutation endpoint. Its generics include the query argument, base-query type, tag names, result type, reducer path, and endpoint context.

Follow-up: Why would a mutation definition include tag information? Tags let the mutation invalidate or affect cached query data, which can cause related queries to refetch.

QHow does a mutation definition specify its request?

A mutation definition must describe how the request is performed through either query or queryFn. query commonly returns the URL, HTTP method, and body, while queryFn supports arbitrary asynchronous logic.

Follow-up: When is queryFn preferable? Use it when request behavior cannot be expressed by the configured base query, such as combining multiple operations or using custom async handling.

QHow are mutation definitions used from React?

Mutations do not run automatically like queries. The generated mutation hook returns a trigger function plus mutation-result state, and calling the trigger starts the request.

Follow-up: How can a caller obtain the raw result or error? The trigger promise provides unwrap, which exposes the fulfilled value or rejects with the mutation error.

Mutation endpoint definition
build.mutation()
createApi
useMutation
queryFn
invalidatesTags

Source: createApi. Checked 2026-10-15.