Client

The client is the object createClient() returns: a NodaroClient that holds your base URL, your auth provider and your settings, and exposes every part of the Nodaro API as a resource, such as client.workflows or client.nodes. You create it once and reuse it for every call.

Create a client

import { createClient, StaticTokenAuth } from "@nodaro/sdk"

const client = createClient({
  baseUrl: "https://app.nodaro.ai",
  auth: new StaticTokenAuth(process.env.NODARO_TOKEN!),
  timeoutMs: 120_000,
})

createClient(options: ClientOptions): NodaroClient

NodaroClient is also exported as a class, so you can type a function that receives a client:

import type { NodaroClient } from "@nodaro/sdk"

async function countWorkflows(client: NodaroClient, projectId: string) {
  const { data } = await client.workflows.list({ projectId })
  return data.length
}

Resources on the client

Every resource is created by createClient and reached as client.<resource>.

The client itself has three more methods: me(), withWorkspace() and request().

What methods return

• Envelopes are kept. When an endpoint answers { "data": ... }, the method resolves to that envelope, so you write const { data } = await client.workflows.get(id). Paginated lists add a cursor next to data, such as nextCursor.
• Some resources return the payload. A few methods unwrap their response, for example client.characters.list() resolves to { characters, nextCursor } and client.credits.balance() to the balance itself. Each reference page shows the exact return type.
• Deletes and cancels usually resolve to { success: true }.
• Field names follow the wire format. A Job uses snake_case fields, such as output_data and created_at, because the API sends them that way. A Workflow and a WorkflowExecution use camelCase.

Every response and input type is exported, so you can import it with import type. See Types.

me()

me(): Promise<UserIdentity & MeOrganizations>

Returns the identity behind the current token (GET /v1/me). Any valid token resolves to its owner, whether it is an API token, an OAuth access token or a browser session. A missing or invalid token throws UnauthorizedError.

const me = await client.me()
console.log(me.email, me.tier)

On a Nodaro Cloud instance with organizations, the result also carries organizations, workspaces, lastWorkspaceId and organizationsUnavailable. Treat their three states differently:

withWorkspace(workspaceId)

withWorkspace(workspaceId: string | null): NodaroClient

Returns a new client that acts in workspaceId. The new client shares the auth, base URL, timeout and fetch of the original. Pass null for your personal space.

const classroom = client.withWorkspace(workspaceId)

await classroom.workflows.run(workflowId) // runs in the workspace
await client.workflows.run(workflowId)    // runs in the personal space

The method returns a new client instead of changing the current one. Two operations that run at the same time on one client can therefore never mix up their workspaces.

The workspace decides scope, never access. It chooses which workspace a list reads from and where a new item is created. Reading, changing, deleting or running an item you name by id depends on that item's own workspace. A forgotten workspace cannot hide your work, and a wrong one cannot reach anyone else's.

Workspaces belong to organizations on Nodaro Cloud. See Organizations and workspaces and Workspaces.

request(method, path, options)

request<T>(method: string, path: string, options?: {
  body?: unknown
  query?: Record<string, string | number | boolean | undefined>
  headers?: Record<string, string>
  signal?: AbortSignal
}): Promise<T>

Sends a request to any endpoint, for the few that have no resource method yet. It adds your auth header and your workspace, sends body as JSON, applies timeoutMs, and throws the same typed errors as the resource methods.

// The same request that client.jobs.list() sends
const page = await client.request<{ data: unknown[]; next: string | null }>("GET", "/v1/jobs", {
  query: { type: "llm-structured", limit: 20 },
})

A FormData body is sent as a multipart upload. Query values that are undefined are left out. The REST API reference lists every endpoint and its fields.

Timeouts and a custom fetch

timeoutMs aborts a request that takes longer than the limit, 60 seconds by default. Most generation takes longer than any sensible HTTP timeout, so start it and poll the job instead: client.nodes.runAndWait() does both for you. The streaming methods, client.copilot.stream() and client.media.downloadVideoProgress(), do not apply the timeout, because they are meant to stay open for minutes.

Pass your own fetch to change how requests travel:

• Tests. Return canned Response objects from a mock.
• Retries. Wrap the global fetch in a helper that retries on a 5xx answer.
• Tracing. Wrap it with your tracing or monitoring library.

const client = createClient({
  baseUrl: "https://app.nodaro.ai",
  auth: new StaticTokenAuth(process.env.NODARO_TOKEN!),
  fetch: (input, init) => tracedFetch(input, init),
})

Runtimes and browsers

The SDK uses only fetch and URL, which are global in Node.js 20 and newer, in modern browsers, in React Native, on Cloudflare Workers, on Deno and on Bun. No polyfill is needed.

• CORS with OAuth tokens. A browser app that calls Nodaro with an OAuth access token must run on an origin listed in the developer app's allowedOrigins. See OAuth and developer apps.
• CORS with a session. A browser app that uses supabaseAuth is not checked against that list.
• The client label. On a server, the SDK sends X-Nodaro-Client: sdk/<version>, and Nodaro records it as the origin of each job. In a browser the default label is not sent, because the browser's Origin header already names your app. A clientLabel you set yourself is always sent.