JavaScript SDK

Official ESM package for Node 18+ and other runtimes with fetch, ReadableStream, and AbortController.

The npm package is @latentkit/sdk.

Use this SDK inside server-side JavaScript and TypeScript code: Next.js Route Handlers, Server Actions, Express, Fastify, NestJS, serverless functions, background jobs, and workers.

Install

npm install @latentkit/sdk

1. Set your API key

Create a runtime key in AI Router or API Keys, then set it server-side:

export LATENTKIT_API_KEY="lk_..."

2. Send your first request

import { LatentKit } from '@latentkit/sdk';

// Reads LATENTKIT_API_KEY and LATENTKIT_BASE_URL from the environment.
const client = new LatentKit();

const response = await client.chat.create({
  messages: [{ role: 'user', content: 'Say hello from LatentKit.' }],
  max_tokens: 100,
  response_profile: 'balanced',
});

console.log(response.content);

3. Confirm it in the console or CLI

Open Logs or Request Traces in the console, or run:

npm install -g @latentkit/cli
latentkit login
latentkit logs tail --tenant t_123 --interval 3

Replace t_123 with your workspace id.

Client options

Request cancellation and metadata

Every chat method accepts optional request settings with signal, timeoutMs, and safe extra headers. The SDK sends the effective deadline to LatentKit so the gateway can stop fallback work when the caller disappears.

Use the metadata-aware variants when an adapter needs response headers or the LatentKit request ID:

const controller = new AbortController();

const response = await client.chat.createWithResponse(
  { messages: [{ role: 'user', content: 'hello' }] },
  { signal: controller.signal, timeoutMs: 55_000 },
);

console.log(response.data.content, response.requestId);

Streaming adapters can call client.chat.streamWithResponse(...) and iterate response.events. Abort signals and deadlines remain active until the stream ends or the consumer cancels iteration. Custom headers cannot replace authorization, attribution, timeout, app-selection, or route-control headers.

Route-based requests

Do not pass model, provider, route, or policy. The SDK rejects route-control keys, including inside extra_body. The assigned route selects the provider/model at runtime.

That means application code stays stable:

1. your app sends the task
2. the API key resolves to an assigned published route
3. LatentKit chooses the eligible provider/model
4. response metadata reports what won

Inspect the connection and route

client.me.retrieve() returns the typed MeResponse shared by official integrations. It includes the app and workspace, credits, assigned route, ordered route models, and latest winning request when available:

const context = await client.me.retrieve();

console.log(context.policy?.name, context.policy?.model_count);
for (const model of context.policy?.models ?? []) {
  console.log(model.rank, model.provider, model.model);
}
console.log(context.latest_request?.model);

The latest winner is request activity, not a fixed model. SDK credentials can inspect this runtime context but cannot change the assigned route.

Errors

import { LatentKit, LatentKitApiError } from '@latentkit/sdk';

try {
  await client.chat.create({
    messages: [{ role: 'user', content: 'hello' }],
  });
} catch (error) {
  if (error instanceof LatentKitApiError) {
    console.error({
      status: error.status,
      code: error.code,
      request_id: error.request_id,
    });
  }
}

Return safe errors to your frontend. Do not log or forward raw provider bodies; they may contain prompt content or internal diagnostic detail.

For support and debugging, always log error.request_id.

Streaming

for await (const event of client.chat.stream({
  messages: [{ role: 'user', content: 'Count from one to five.' }],
})) {
  if (event.event === 'error') throw new Error(JSON.stringify(event.data));
  if (event.isDone) break;
  console.log(event.data);
}

Supported resources

client.queue.create supports the complete public enqueue endpoint set and optional idempotencyKey. Queue support is enqueue-only: the API does not currently expose a public per-job result route. Use your host platform's background-job runner and a synchronous SDK resource when the workflow needs the generated result.

Audio transcription

const transcript = await client.transcription.create({
  audio: {
    base64: '<base64-audio>',
    media_type: 'audio/mpeg',
    filename: 'meeting.mp3',
  },
  language: 'en',
  response_format: 'json',
});

console.log(transcript.content);

The API key's route must contain an audio_input model. For OpenAI BYOK routes, a workspace admin can enable transcription models such as gpt-4o-transcribe, gpt-4o-mini-transcribe, gpt-4o-transcribe-diarize, or whisper-1.

See also Python SDK and REST API overview.

For Vercel AI SDK applications, see the dedicated LatentKit provider. Published alpha @latentkit/ai-sdk-provider 0.1.0-alpha.3 adds the AI SDK's Language Model V3 mapping on top of the JavaScript SDK.

SDK vs CLI

Most teams use both: the SDK in the application and the CLI while building, debugging, and operating the route.

Framework notes

• Next.js: keep the client in a server-only module and call it from Route Handlers or Server Actions.
• React/Vite: browser code should call your backend or serverless function; it should not import the SDK with a raw key.
• Express/Fastify/Nest: create one shared client factory, validate incoming request bodies, and centralize LatentKit error logging.