refreshSnapshot

refreshSnapshot updates the content used by a client running in snapshot mode without restarting the application.

When you call this method, the client runs the configured snapshotLoader again. If the loader returns a snapshot that is newer than the currently active one, the client adopts it immediately and uses it for subsequent reads.

This is useful for long-running applications such as SSR servers, background workers, and backend processes that need to reflect newly published content without being restarted.

For example, you can publish a new snapshot to remote storage and then ask the client to reload it:

import { createClient } from '@content-island/api-client';

const client = createClient({
  accessToken: 'YOUR_ACCESS_TOKEN',
  mode: 'snapshot',
  snapshotLoader: async () => {
    const response = await fetch('https://storage.example.com/content-island-snapshot.json');

    return response.text();
  },
});

const result = await client.refreshSnapshot();

console.log(result);

If the remote snapshot is newer, the result looks like this:

{
  status: 'updated',
  meta: {
    schemaVersion: 1,
    exportedAt: '2026-06-22T10:30:00.000Z',
    projectId: '1',
    view: 'published',
  },
}

From that point on, the client uses the new snapshot for subsequent reads.

Tip

See the Snapshot mode guide to learn how to configure the snapshotLoader.

You can also use getSnapshotInfo to inspect the metadata of the currently active snapshot.

Interface

refreshSnapshot does not accept any parameters.

It returns a promise that resolves to a SnapshotRefreshResult:

export interface ApiClient {
  refreshSnapshot: () => Promise<SnapshotRefreshResult>;
}

Result

type SnapshotRefreshResult = {
  status: 'updated' | 'unchanged';
  meta: SnapshotMeta;
};

The status property indicates whether the active snapshot changed:

status	Meaning
'updated'	A newer snapshot was found and is now active
'unchanged'	The loaded snapshot was the same age as, or older than, the active snapshot and was ignored

An 'unchanged' result is not an error. The client continues using the snapshot that was already active.

This prevents a delayed or out-of-order refresh from replacing newer content with older content.

The meta property contains the metadata of the snapshot that remains active after the refresh:

interface SnapshotMeta {
  schemaVersion: number;
  exportedAt: string;
  projectId: string;
  view: 'published' | 'preview';
}

This metadata has the same structure as the value returned by getSnapshotInfo.

When a refresh fails

refreshSnapshot throws an ApiClientError with the SNAPSHOT_MODE code when it cannot load or accept the new snapshot.

In all of these cases, the previously active snapshot is preserved, so existing reads can continue using it.

A refresh fails when:

Situation	Reason
the new snapshot has a different projectId	a refresh cannot switch the client to another project
the new snapshot has a different view	a refresh cannot switch between published and preview
the snapshotLoader fails	the snapshot could not be retrieved
the returned content is not valid JSON	the client cannot parse it
the snapshot has an invalid structure	the content does not match the expected snapshot format
the schema version is not supported	the client cannot use that snapshot version
the client is running in 'api' mode	API clients do not use snapshots
no snapshotLoader was configured	there is no source from which to reload the snapshot

If the loader throws an error, the original error is available through error.cause.

import { createClient, ApiClientError } from '@content-island/api-client';

const client = createClient({
  accessToken: 'YOUR_ACCESS_TOKEN',
  mode: 'snapshot',
  snapshotLoader: async () => fetchSnapshotFromStorage(),
});

try {
  const result = await client.refreshSnapshot();

  if (result.status === 'updated') {
    console.log('The client is now using the new snapshot');
  }
} catch (error) {
  if (error instanceof ApiClientError && error.code === 'SNAPSHOT_MODE') {
    console.error('The snapshot could not be refreshed');

    // The previous snapshot remains active.
  }
}

Safe updates

Refreshing a snapshot never leaves the client in a partially updated state.

A read performed while refreshSnapshot is running uses either:

• the complete previous snapshot; or
• the complete new snapshot.

It never uses a partially loaded snapshot.

Calling refreshSnapshot() multiple times concurrently is also safe. Concurrent calls share the same refresh operation, and the newest valid snapshot remains active.

If the client has not loaded a snapshot yet, the first call to refreshSnapshot() loads the initial snapshot and makes it active.