Node.js Installation

Get an API key

Visit Noukai Console to create an API key starting with nk_.

Configure authentication and defaults

Set the API key as an environment variable:

export NOUKAI_API_KEY=nk_yourkey_...

Optionally set your default org and project to simplify flow references:

export NOUKAI_ORG=acme
export NOUKAI_PROJECT=spelling

Or pass them directly to the client:

import { Noukai } from "@noukai/sdk";
 
const noukai = new Noukai({ apiKey: "nk_yourkey_...", org: "acme", project: "spelling" });

Verify installation

Run a quick test:

import { Noukai } from "@noukai/sdk";
 
const noukai = new Noukai({ org: "acme", project: "spelling" });
const result = await noukai
  .flow("grade-3")
  .execute({ message: "The cat sat on the mat." });
console.log(result.output);

If you see output, you're ready to go! (Or use the fully-qualified form noukai.flow("acme/spelling/grade-3") if you prefer.)

Advanced configuration

Local development

For local development, use env: "dev" to connect to http://localhost:8080/api/v1:

import { Noukai } from "@noukai/sdk";
 
const noukai = new Noukai({
  apiKey: "nk_...",
  env: "dev",
  org: "acme",
  project: "spelling"
});

Or set the environment variable:

export NOUKAI_ENV=dev

The env parameter accepts:

"dev" or "development" → http://localhost:8080/api/v1
"production" (default) → https://api.noukai.xyz/api/v1
Other values use the production default

The SDK targets Noukai's hosted endpoints (api.noukai.xyz for production, localhost:8080 for env="dev"). There is no way to point the SDK at a custom URL — this is a deliberate constraint to prevent accidental misrouting.

The only user-facing way to switch URL targets is the env option (or NOUKAI_ENV env var).

Timeouts and retries

Customize request timeouts and retry behavior:

import { Noukai } from "@noukai/sdk";
 
const noukai = new Noukai({
  timeout: 300_000,    // 5 minutes (default: 300 seconds)
  maxRetries: 1        // Retry once on 5xx (default: 1)
});

Logging

Enable structured logging:

import { Noukai } from "@noukai/sdk";
 
const noukai = new Noukai({
  onLog: (event) => {
    console.log(`[${event.phase}] ${event.method} ${event.path}`);
    if (event.statusCode) {
      console.log(`  Status: ${event.statusCode}`);
    }
  },
  logPayloads: true  // Include request/response bodies
});

TypeScript support

The SDK is written in TypeScript and provides full type definitions:

import { Noukai, ExecuteResult } from "@noukai/sdk";
 
const noukai = new Noukai();
const result: ExecuteResult = await noukai
  .flow("acme/spelling/grade-3")
  .execute({ message: "hello" });

Next steps

Quickstart — Run your first flow
Guides — Learn key patterns
API Reference — Class and method signatures

Install the package