API Idempotency

The Levain GraphQL API supports idempotency for mutations only. You can make the same request multiple times while being assured that the request will only be processed once. The API will return the same response for each identical request made with the same Idempotency-Key.

You do not need to use idempotency for queries, as they are already idempotent.

Idempotency key

Using idempotency keys is optional, but recommended for any request that can be safely retried multiple times without causing a different effect than only being performed once.

You can make a request idempotent by providing an Idempotency-Key header in the request. The value of the Idempotency-Key header is a unique identifier for the request.

The Idempotency-Key is used to guarantee that the request is only processed once to your organizational account. If the request has been processed previously, the API will return the same response as the original request.

Usage with the SDK

When using the Levain SDK, you can provide the Idempotency-Key as an option in the request. The SDK will automatically add the Idempotency-Key header to the request.


const levainGraph = new LevainGraphClient({
  baseUrl: config.LEVAIN_API_URL,
  accessToken: config.LEVAIN_API_ACCESS_TOKEN,
  requestConfig: {
    requestMiddleware: async (request: RequestExtendedInit<Variables>) => {
      return {
        headers: {
          'Idempotency-Key': 'uuid for example'

Responses will be cached for a few hours, so if you make the same request with the same Idempotency-Key within this time frame, the API will return the same response as the original request.