TypeScript SDK

The official Gumnut TypeScript SDK provides typed requests and responses for server-side TypeScript and JavaScript. It supports TypeScript 4.9 and later and Node.js 20 LTS or later. The generated SDK also supports current web browsers, Deno 1.28+, Bun 1+, Cloudflare Workers, Vercel Edge Runtime, and Nitro 2.6+. React Native and Jest’s jsdom environment are not supported.

Installation

npm install gumnut-sdk

Or with Bun:

bun add gumnut-sdk

Create a client

In Node.js, Bun, and Deno, set GUMNUT_API_KEY in the environment and the client reads it automatically. Do not embed an API key in browser code. For a browser integration, use OAuth or call the SDK through a backend proxy that keeps the API key server-side.

import Gumnut from 'gumnut-sdk';

const client = new Gumnut();

Keep API keys in environment variables or a secrets manager. Never expose an API key in browser code. See API keys for creation and scoping.

Upload and organize a photo

Generated request fields use snake_case, while resource methods use camelCase.

import fs from 'node:fs';
import Gumnut from 'gumnut-sdk';

const client = new Gumnut();

const now = new Date().toISOString();
const libraryId = 'lib_your_library_id';
const asset = await client.assets.create({
  asset_data: fs.createReadStream('photo.jpg'),
  device_asset_id: 'photo-001',
  device_id: 'batch-importer',
  file_created_at: now,
  file_modified_at: now,
  library_id: libraryId,
});

const album = await client.albums.create({ name: 'Vacation', library_id: libraryId });
await client.albums.assetsAssociations.add(album.id, {
  asset_ids: [asset.id],
});

library_id is optional for accounts with one library and required when an account has multiple libraries. Uploads accept an fs.ReadStream, a web File, a fetch Response, or the result of the exported toFile helper. See the generated API reference for the complete parameter types.

Search

const results = await client.search.search({
  query: 'sunset at the beach',
});

for (const item of results.data) {
  console.log(item.asset.id);
}

Search supports natural-language content queries and structured filters. See Pagination and filtering for the API’s search and filtering behavior.

Pagination

List methods return async-iterable cursor pages. A for await loop fetches subsequent pages as needed.

for await (const asset of client.assets.list()) {
  console.log(asset.id);
}

For explicit page control, use hasNextPage() and getNextPage():

let page = await client.assets.list();

while (true) {
  for (const asset of page.data) {
    console.log(asset.id);
  }

  if (!page.hasNextPage()) break;
  page = await page.getNextPage();
}

Retries and timeouts

The SDK retries connection errors, HTTP 408, 409, 429, and 5xx responses twice by default. Configure retries and the timeout on the client:

const client = new Gumnut({
  maxRetries: 4,
  timeout: 30_000,
});

Error handling

All SDK errors extend Gumnut.APIError. HTTP failures expose a status code; connection failures use APIConnectionError subclasses.

try {
  await client.assets.retrieve('asset_missing');
} catch (error) {
  if (error instanceof Gumnut.APIError) {
    console.error(error.status, error.message);
  } else {
    throw error;
  }
}

Getting started

Authentication

APIs

SDKs

MCP

Immich

More

Installation

Create a client

Upload and organize a photo

Search

Retries and timeouts

Error handling

Reference

​Installation

​Create a client

​Upload and organize a photo

​Search

​Pagination

​Retries and timeouts

​Error handling

​Reference

Installation

Create a client

Upload and organize a photo

Search

Pagination

Retries and timeouts

Error handling

Reference