Introduction

naturali.ai is agents that operate for you, with autonomy you can prove. It is one product built on one shared platform — a single runtime everything compiles to and runs on.

The naturali.ai API is the single public contract for the whole platform. Every surface — the console, the operator inbox, the CLI, the TypeScript SDK — is a thin client over exactly this contract; there are no console-private capabilities. Anything the platform can do, you can do through this API and re-embed in your own product.

How these docs are organized

• Docs (this sidebar) — one page per module: what it is, its data model, and the key concepts that aren't obvious from the schema alone. Modules are grouped by product feature: the Foundations every feature consumes (Projects, Models, Providers, Knowledge), then the surfaces built on them (Agents, Channels), then the cross-cutting platform concerns (Access & Observability). New features get a new group here — their module pages never pile up at the top level.
• Tutorials — task-oriented walkthroughs. A module page tells you what something is; a tutorial takes you end to end through doing it, with every call given for the CLI, the SDK and curl. They cut across the feature groups above, which is why they get their own header rather than sitting inside one. Start with Your first agent generation.
• API Reference — the generated REST reference, one page per operation, grouped by the same features, derived directly from the OpenAPI specs that are the binding wire contract. If a docs page and the API reference ever disagree, the API reference wins — it's generated straight from the spec.
• SDK & CLI — the generated clients. They're how you call the product, not part of it, so they live under their own header.

Conventions used throughout

These hold across every module; a module page calls out exceptions.

• Base URL & versioning — https://api.naturali.ai/v1. The API is versioned in the path; within a version, changes are additive.

• Authentication — Authorization: Bearer nat_sk_… (an API key) or a session JWT. Keys are project-scoped by default.

• Wire casing is snake_case (next_cursor, project_id) — see each module's Data Model table for exact field names.

• Public IDs are prefixed per resource (proj_, agent_, tool_, ses_, …) — see each module's Data Model table.

• Pagination — cursor-based on every list endpoint: an opaque cursor plus limit, returning { data, next_cursor } (next_cursor is null at the end).

• Idempotency — mutating POSTs accept an Idempotency-Key header.

• Errors — a machine-readable envelope:

  { "error": { "code": "upstream_unavailable", "message": "...", "details": {} } }

Modules

Foundations

The features every other feature consumes — they exist before any agent does.

Module	What it covers
Projects	The isolation and billing boundary every resource lives in
Models	The model catalog agents resolve against
Providers	Register naturali-managed or BYOK model provider credentials
Knowledge	Versioned documents/playbooks an agent retrieves from

Agents

Create an agent as one versioned manifest and run it from any surface.

Module	What it covers
Agents	Create and run agents bound to a provider and tools
Tools	External capabilities (HTTP or MCP) an agent can call
Sessions	The runtime contract: open a session, exchange messages
Generations	One model loop inside a session, with cost and status

Channels

Bind an agent to a channel; the platform runs the conversation.

Module	What it covers
Channels	Connect an agent to WhatsApp, web, Slack, …

Access & Observability

Cross-cutting platform concerns, consumed by every feature.

Module	What it covers
Auth	Human sign-in by emailed code / session refresh
API Keys	Programmatic tokens (nat_sk_…) scoped to a project
MCP Server	Connect Claude, Cursor or another MCP client to your account
Traces	The audit trail: every tool call, cost, and outcome
Webhooks	Signed, retried event delivery to your own endpoints

Clients

Both clients live under the SDK & CLI header and are generated from the same OpenAPI specs as the API reference, so neither can lag the contract:

Client	Use it for
TypeScript SDK	@naturali/sdk — typed calls from an app, a backend, or a worker
CLI	@naturali/cli — one naturali command per operation, for shells and CI

Every code example in these docs is shown for both, plus raw curl.