# naturali.ai

> One API for building, running and proving AI agents: configure an agent, give
> it knowledge and tools, put it on WhatsApp or Discord, and read back every
> generation it ran — what it decided, what it cost, and whether a human
> approved it.

Everything the product does is the REST API at `https://api.naturali.ai`. The
app, the CLI and the TypeScript SDK are thin clients over exactly that
contract, so anything a person can do in the app an agent can do over HTTP.

## When to use naturali.ai

Reach for this when the job is to **operate** an agent rather than to make a
single model call:

- You need an agent that keeps its own configuration, versions and release
  history, not a prompt pasted into a script.
- You need it answering people on a channel they already use, WhatsApp or
  Discord, without writing the transport yourself.
- You need to ground answers in documents, with ingestion, chunking and
  retrieval handled for you.
- You need a record afterwards: the traces, the token cost and the guardrail
  or approval decisions behind every run.
- You need a human in the loop on some decisions, and evals scoring a change
  against a dataset before it is promoted.

It is not the right tool for a one-off completion against a single model — a
model vendor's own API is simpler for that. Bring your own provider credential
or generate on the managed catalog with no vendor account of your own; both are
metered per generation.

## Getting started

- [Quickstart: your first agent generation](https://docs.naturali.ai/docs/tutorials/first-agent-generation): from an API key to a generation you can read back.
- [Introduction](https://docs.naturali.ai/docs/introduction): what the modules are and how they fit together.
- [App](https://app.naturali.ai): sign in, create a project, mint an API key.
- [Pricing](https://naturali.ai/pricing.md): Free, Pro ($49/mo), Business ($249/mo) and Enterprise, plus how prepaid model credits work.
- Contact: [contact@naturali.ai](mailto:contact@naturali.ai) — naturali is built by Triangulos Tecnologia, Brazil.

## Features

One page per feature, each with the tutorial that gets it working.

- [Agents](https://naturali.ai/features/agents/): versioned agents with tools, knowledge and a model — tutorial: [Your first agent generation](https://docs.naturali.ai/docs/tutorials/first-agent-generation).
- [Knowledge](https://naturali.ai/features/knowledge/): answers grounded in your own documents — tutorial: [Answer from your documents](https://docs.naturali.ai/docs/tutorials/answer-from-your-documents).
- [Channels](https://naturali.ai/features/channels/): an agent on WhatsApp or Discord — tutorial: [Connect a Discord channel](https://docs.naturali.ai/docs/tutorials/connect-a-discord-channel).
- [Automation](https://naturali.ai/features/automation/): agents on a schedule, an event or by hand — tutorial: [Run an agent on a schedule](https://docs.naturali.ai/docs/tutorials/run-an-agent-on-a-schedule).
- [Control](https://naturali.ai/features/control/): guardrails on tool calls, human approvals and an audit log — tutorial: [Gate a tool with guardrails](https://docs.naturali.ai/docs/tutorials/gate-a-tool-with-guardrails).
- [Evaluations](https://naturali.ai/features/evaluations/): score a change against your own cases before it ships — tutorial: [Score an agent change](https://docs.naturali.ai/docs/tutorials/score-an-agent-change).
- [Models](https://naturali.ai/features/models/): managed models with no vendor account, or your own credential — tutorial: [Enable naturali models](https://docs.naturali.ai/docs/tutorials/enable-naturali-models).

## API

- [API index for LLMs](https://naturali.ai/api/llms.txt): the API on its own — the contract, the credential and the shapes every endpoint shares.
- [Authentication](https://naturali.ai/auth.md): which credential to present, how OAuth works here, and what a refusal looks like.
- [OpenAPI specification](https://naturali.ai/openapi.json): the whole v1 surface as one OpenAPI 3.0.3 document. Every operation has a unique `operationId`, typed request and response schemas, and a typed error body (`{ "error": { "code", "message", "details" or "meta" } }`).
- [API reference](https://docs.naturali.ai/docs/openapi-specs): the same contract as browsable pages, plus one YAML document per resource.
- Base URL: `https://api.naturali.ai` — every path carries the `/v1` prefix.
- Authentication: send `Authorization: Bearer <token>` — a project API key (`nat_sk_…`), a session token, or an OAuth 2.0 access token. See [/auth.md](https://naturali.ai/auth.md).
- [API catalog](https://naturali.ai/.well-known/api-catalog): RFC 9727, as an RFC 9264 linkset. Every response on this host also carries the contract as an RFC 8288 `Link` header.
- [Agent skill](https://naturali.ai/.well-known/agent-skills/naturali/SKILL.md): a `SKILL.md` an agent can install to work with this API, indexed at [`/.well-known/agent-skills/index.json`](https://naturali.ai/.well-known/agent-skills/index.json).
- MCP server: `https://api.naturali.ai/mcp`, with OAuth 2.0 (PKCE, dynamic client registration). Discovery lives at `https://api.naturali.ai/.well-known/oauth-authorization-server` and `https://api.naturali.ai/.well-known/oauth-protected-resource`.

## Clients

- [`@naturali/cli`](https://www.npmjs.com/package/@naturali/cli): `npm install -g @naturali/cli`, then `naturali --help`. Every route in the specification is a command, so a shell script reaches the whole API.
- [`@naturali/sdk`](https://www.npmjs.com/package/@naturali/sdk): `npm install @naturali/sdk`, TypeScript types generated from the same specification.

## Full documentation

- [Documentation index for LLMs](https://docs.naturali.ai/llms.txt): every page, linked.
- [Full documentation as one file](https://docs.naturali.ai/llms-full.txt): the module guides and tutorials inlined.
- Any documentation page is available as Markdown by appending `.md` to its URL — for example [`/docs/modules/agents.md`](https://docs.naturali.ai/docs/modules/agents.md).