canonical: https://jentic.com/apis/naturali.ai/naturali

# naturali.ai API

The naturali.ai API runs AI agents inside projects: you define an agent, send it messages, and it resolves its tools and runs the model loop, either in the background with a generation_id to poll or inline with wait=true. Around that loop it stores documents that are chunked and embedded on ingest, memories in memory stores, guardrails, secrets, and orchestration graphs, and it exposes hybrid knowledge search that fuses vector and full-text results. Agents can be connected to messaging channels such as WhatsApp and Discord, and tool calls can be routed through a human approval queue where an item is approved, edited, or rejected.

## For AI agents

Create and run naturali.ai agents, ingest documents and search project knowledge, manage memories, guardrails, and orchestrations, and decide items in the approval queue.

## Scope

Does not train or fine-tune models, host websites, or process payments for your customers. Use for running and managing naturali.ai agents and their knowledge only.

## Capabilities

- Run an agent generation from a messages array, in the background with a generation_id or inline with wait=true, and resume a paused generation by submitting tool_outputs
- Ingest an uploaded PDF, plain text, or markdown file into a chunked, embedded document using a chunk_strategy of page, whole, or size
- Search project knowledge across documents and memories with hybrid vector and full-text retrieval, or by document_paths, document_ids, memory_store_ids, or tags
- Approve, edit-then-approve, or reject items in a project's human approval queue
- Version agent configs and roll out a canary release, then promote it or abort back to stable
- Define, validate, and version orchestration graphs and inspect their runs, traces, and generation transcripts
- Connect a project to messaging channels such as WhatsApp and route channel conversations to agents

## Use cases

### Coding agent driving a hosted naturali.ai agent

A developer's coding agent tests a naturali.ai support agent by sending it questions and checking the replies. Through Jentic the coding agent searches for 'run an agent generation', loads the createAgentGeneration operation with its input schema, and posts a messages array with wait=true so the result comes back inline. If the generation pauses with requires_action for a client tool, the agent submits tool_outputs to resume it. The naturali API key is attached by your own Jentic One instance at call time.

Example prompt: Call POST `/v1/projects/{project_id}/agents/{agent_id}/generate`?wait=true with messages containing 'What is your refund window?', then fetch GET `/v1/projects/{project_id}/generations/{generation_id}/transcript`

### Knowledge base ingestion and retrieval

A team grounds its agents in product manuals. Each uploaded file is ingested into one document split into embedded chunks, with chunk_strategy set to page for PDFs or size with a chunk_size and chunk_overlap. Knowledge search then queries documents and memories together, fusing a vector query and a full-text query per source by reciprocal rank, with filters such as min_similarity and tags.

Example prompt: Ingest an uploaded file with POST `/v1/projects/{project_id}/documents/ingest` using file_id and chunk_strategy 'page', then call POST `/v1/projects/{project_id}/knowledge/search` with query 'warranty terms' and limit 5

### Human approval for agent tool calls

Some agent actions should wait for a person. naturali.ai places these in an approval queue that can be filtered by status and origin, and each item can be approved, approved with edited arguments while the original is preserved, or rejected. Expiry is re-checked at decision time, so an expired item cannot be approved.

Example prompt: List pending items with GET `/v1/projects/{project_id}/approvals`?status=pending, then approve one with POST `/v1/projects/{project_id}/approvals/{approval_id}/approve` supplying edited arguments

### Staged agent config rollout

Changing an agent's prompt or tools in production is safer as a canary. naturali.ai keeps an agent's config history, lets you set a staged rollout on the release, and then promote the canary or abort and roll back to stable. Archived versions can be restored as a new version if a change needs undoing.

Example prompt: Set a rollout with PUT `/v1/projects/{project_id}/agents/{agent_id}/release`, review generations, then call POST `/v1/projects/{project_id}/agents/{agent_id}/release/promote` or `/release/abort`

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/projects/{project_id}/agents/{agent_id}/generate` | Run an agent generation |
| GET | `/v1/projects/{project_id}/generations/{generation_id}` | Get a generation |
| POST | `/v1/projects/{project_id}/agents` | Create an agent |
| POST | `/v1/projects/{project_id}/documents/ingest` | Ingest a file into a chunked document |
| POST | `/v1/projects/{project_id}/knowledge/search` | Search documents and memories |
| POST | `/v1/projects/{project_id}/memories` | Create a memory |
| POST | `/v1/projects/{project_id}/approvals/{approval_id}/approve` | Approve an approval item |
| POST | `/v1/projects/{project_id}/embeddings` | Create embeddings |

## Key resources

- **Agents** — Create, update, and delete agents, run generations, submit tool outputs, version configs, and manage staged releases
- **Documents and knowledge** — Create, ingest, version, tag, withdraw, and relate documents, and run hybrid knowledge search
- **Memories** — Memory stores, individual memories with assertions and tags, and rules for what completed turns may write
- **Orchestrations** — Orchestration graphs with validation and versions, plus their runs and queue stats
- **Approvals and guardrails** — The human approval queue, guardrails with dry-run evaluation, and the exception queue
- **Channels** — WhatsApp and Discord channel connections, routes, and channel conversations
- **Account** — Projects, API keys with rotation, secrets, quotas, usage, billing, and the audit log

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 60 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 73 / 100
  - Developer Experience & Jentic Compatibility: 70 / 100
  - AI-Readiness & Agent Experience: 56 / 100
  - Agent Usability: 43 / 100
  - Security: 75 / 100
  - AI Discoverability: 73 / 100
- **View full report:** https://jentic.com/apis/naturali.ai/naturali/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring naturali.ai by hand means choosing between a nat_sk_ key, a session JWT, or an OAuth 2.0 authorization code flow, threading a project id through hundreds of paths, and handling background generations that return 202 and must be polled. Through Jentic you install once, import naturali.ai from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** naturali.ai puts the project id in the URL path (`/v1/projects/{project_id}/...`), and agent, document, and approval ids sit there too, so a rule can confine your agent to one project and the operations you pick. You choose the operations it may call, so destructive ones like secret deletion or API key rotation are not included unless you add them.
- **Credential handling:** Your naturali.ai key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'run an agent generation' or 'search project knowledge', and Jentic returns the matching naturali.ai operation with its input schema, so the agent finds the right call among 371 without loading the whole reference.

## Related APIs

- **Relevance AI API** — Agent platform API for managing agents, tools, tasks, and knowledge
- **OpenAI API** — Model provider whose chat and embedding models can back the agents a naturali.ai project runs
- **Anthropic Messages API** — Claude models that can be configured as an AI provider for naturali.ai agents

## FAQ

### What authentication does the naturali.ai API use?

Per its OpenAPI spec, the naturali.ai API accepts a bearer token, either a naturali API key beginning nat_sk_ or a session JWT, or an OAuth access token issued to a connected app through the OAuth 2.0 authorization code flow served by the naturali.ai API itself. A few sign-in operations such as POST `/v1/auth/code` and POST `/v1/auth/refresh` need no credential. Through Jentic the key is stored encrypted by your own instance and attached per call.

### Can I run an agent and get the answer in one call with the naturali.ai API?

Yes. POST `/v1/projects/{project_id}/agents/{agent_id}/generate` runs in the background by default and returns 202 with a generation_id to poll, but passing wait=true blocks and returns the result inline. If a client tool is needed the generation pauses with requires_action, and you resume it through the tool-outputs operation.

### What are the rate limits for the naturali.ai API?

The OpenAPI spec does not publish fixed request rate limits. It does expose a Quotas resource for managing quotas and rate limits per project, and usage operations for reading consumption, so limits are configured per project. Check https://naturali.ai for plan details.

### Is there a naturali.ai MCP server?

You don't need an MCP server to give your agent naturali.ai. Jentic connects it directly from the API Directory: import it, store your nat_sk_ key once, and your agent discovers the operations it needs on demand instead of loading hundreds of tool definitions into its context.

### How do I search project knowledge with the naturali.ai API through Jentic?

Import naturali.ai from the API Directory in your Jentic One instance and store your key. Your agent searches for 'search project knowledge', loads POST `/v1/projects/{project_id}/knowledge/search`, and sends a query with options such as limit, min_similarity, or include_memories. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the naturali.ai API?

Yes. Write a rule that allows only the generate and knowledge-search operations under `/v1/projects/proj_123`, and your agent can run agents and query knowledge in that one project but cannot delete documents, read secrets, rotate API keys, or touch another project. Every call it makes is logged.

### How does document ingestion chunk files in the naturali.ai API?

The ingest operation parses a file you already uploaded and creates one document split into embedded chunks. PDFs are parsed page by page, while text/plain and text/markdown files are read as a single source, and chunk_strategy accepts page, whole, or size, with chunk_size and chunk_overlap for the size strategy.