@naturali/sdk

TypeScript SDK for the naturali.ai API, generated from its OpenAPI specs.

pnpm add @naturali/sdk

Usage

import { NaturaliClient } from '@naturali/sdk';

const naturali = new NaturaliClient({
  token: process.env.NATURALI_TOKEN, // nat_sk_… or a session access JWT
});

const { data, error } = await naturali.agents.listAgents({
  path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
  query: { limit: 10 },
});

if (error) {
  // The platform's error envelope, typed: { error: { code, message, details } }
  console.error(error);
} else {
  console.log(data.data);
}

A method never throws on a non-2xx response — it resolves to { data, error }, so the machine-readable code (approval_required, budget_exceeded, access_denied, …) is available as typed data.

Options

The client always talks to https://api.naturali.ai — the only naturali.ai API origin, and not configurable.

| Option | Purpose | | --- | --- | | token | Sent as Authorization: Bearer …. Accepts a nat_sk_… API key or a session access JWT. | | headers | Merged last, so it can override the header above or add your own. |

There is no project option: a project-scoped operation takes project_id in its path, and that is the only thing the API authorizes against.

Call shape

Each resource property mirrors a generated service class, with the configured HTTP client already bound. Arguments follow the spec's own structure and snake_case field names:

await naturali.sessions.addSessionMessage({
  path: { project_id, agent_id, session_id },
  body: { message: 'What is the capital of France?' },
});

await naturali.knowledge.queryKnowledgeCollection({
  path: { project_id, collection_id },
  body: { query: 'refund policy', limit: 5 },
});

Resources: agents, apiKeys, auth, channels, contacts, generations, knowledge, models, projects, providers, sessions, tools, traces.

naturali.http exposes the underlying client for interceptors or a one-off request (naturali.http.get({ url: '/health' })).

Types

Every schema in the specs is exported as a type:

import type { Agent, AgentCreate, ErrorResponse } from '@naturali/sdk';

created_at / updated_at are handed to callers as Date objects; everything else matches the wire shape exactly.

Generation

src/generated/ is build output — never edit it, and never commit it. It is rebuilt from api/openapi/v1/*.yaml by pnpm generate, which typecheck, test and build all run first. See ../README.md for the pipeline.

The only hand-written source is src/naturaliClient.ts.

Versioning

Releases are automatic, and the version is shared with the API and with @naturali/cli — one number, one git tag, three packages. @naturali/[email protected] is the client for API 0.28.0, so the version you installed names the contract you are holding.

Any change to api/openapi/v1/*.yaml regenerates this package and publishes it, because the specs are what it is generated from — so a new version can mean the API gained a resource, not that the hand-written client changed.

fix:/chore: changes release a patch and feat: a minor, inferred from the squashed commit subject. Every case publishes on merge, breaking changes included. See the repository's PIPELINE.md and CHANGELOG.md.