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 app, the operator inbox, the CLI, the TypeScript SDK — is a thin client over exactly this contract; there are no app-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 the product's features — Agents, Knowledge, Channels, Automation, Control, Evaluations, Models — then Access for who may call the API and Platform for what every feature stands on. Getting started comes first: authentication, rate limits, errors and the conventions every module shares.
- 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.
- Clients — the SDK, the CLI and the MCP server your assistant connects to. They're how you call the product, not part of it, so they live under their own header.
Before your first call
Four pages hold what every module shares; read them once.
| Page | What it covers |
|---|---|
| Authentication | The three credentials, what each one reaches, and 401 vs 403 vs 404 |
| Rate limits | Request rate limits, 429 and Retry-After, and the quotas and plan limits that are not about rate |
| Errors | The error envelope and the codes common to every module |
| Conventions | Base URL, versioning, IDs, pagination and idempotency |
Modules
Agents
Configure an agent once, version it, and run it from any surface.
| Module | What it covers |
|---|---|
| Agents | Configure, version, release and run agents |
| Tools | HTTP, MCP, client and pipeline capabilities an agent can call |
| Sessions | Durable dialogues: messages, forks, expiry |
| Conversations | The message thread a session records into |
| Actors | Who the agent is talking to, and their persona |
| Generations | One model loop each: status, transcript, cost attribution |
Knowledge
What an agent reads before it answers, and what it remembers.
| Module | What it covers |
|---|---|
| Files | The bytes a project works from |
| Documents | A source split into embedded, retrievable chunks |
| Metadata Schemas | What a resource's metadata must satisfy |
| Ingestion Rules | How a file type becomes readable text |
| Knowledge | One semantic query across a project's documents |
| Embeddings | Text in, vectors out |
| Memories | The individual facts inside a memory store |
| Memory Stores | The named stores an agent remembers into |
| Memory Rules | Which agent runs a memory store ingests |
Channels
Bind an agent to a channel; the platform runs the conversation.
| Module | What it covers |
|---|---|
| Channels | Connect an agent to WhatsApp or Discord |
| Discord channels | The Discord-specific setup and its Gateway worker |
| Channel Routes | Per-identifier and per-surface routing rules |
| Addresses | The identity behind an inbound identifier, and its erasure |
| Channel Kinds | What each channel kind supports |
Automation
Work that runs when no one is calling.
| Module | What it covers |
|---|---|
| Workflows | State machines work moves through |
| Tasks | Units of work moving through a workflow |
| Orchestrations | Multi-step pipelines declared as a graph |
| Triggers | Schedules, webhooks and events that start an automation |
Control
What an agent may do on its own, and the record of what it did.
| Module | What it covers |
|---|---|
| Guardrails | Whether a tool call runs, waits for a person, or is refused |
| Approvals | The human decisions a run is waiting on |
| Deciders | Versioned question sets answered into append-only decisions |
| Exceptions | What went wrong, and what was done about it |
| Audit Log | An append-only record of every request and its answer |
Evaluations
Measure a change before it ships, and read back what ran.
| Module | What it covers |
|---|---|
| Evaluations | Datasets, scorers and runs |
| Traces | The execution record of a run |
| Chains | How far a continuation has run, and whether it is still spending |
| Activity | What the agents in a project did, newest first |
Models
The models a project generates on, and what they may spend.
| Module | What it covers |
|---|---|
| Models | The naturali catalog: what it serves, and what it costs |
| AI Providers | The model vendors a project generates through, their models and prices |
| Model Routes | Ordered provider+model failover an agent can generate through |
| Quotas | The ceilings a project runs under |
Access
Who may call the API, and with what.
| Module | What it covers |
|---|---|
| Auth | Human sign-in by emailed code / session refresh |
| API Keys | Programmatic tokens (nat_sk_…), account- or project-scoped |
| Users | The account a credential resolves to |
Platform
What every feature stands on.
| Module | What it covers |
|---|---|
| Projects | The isolation and billing boundary every resource lives in |
| Formations | A whole agent stack in one template, deployed as one unit |
| Secrets | Encrypted, write-only credentials a provider or tool authenticates with |
| Assistant | Operate your account from a chat channel, once linked |
| Marketplace | Publish a tool or agent for other projects to install |
| Webhooks | Signed, retried event delivery to your own endpoints |
Clients
Every client lives under the Clients header and is generated from the same OpenAPI specs as the API reference, so none of them 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 |
| MCP Server | Connect Claude, Cursor or another MCP client to your account |
Every code example in these docs is shown for the SDK and the CLI, plus raw
curl.