Install Jentic One Beta

Connect the naturali.ai API to your agent

Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the naturali.ai API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.

Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.

Step 1: Jentic One Host machine

# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fnaturali.ai%2Fnaturali" | sh

Step 2: Agent machine

# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fnaturali.ai%2Fnaturali" | sh
jentic register       # connects your agent to your Jentic One instance

Jentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.

Capabilities

What an agent can do with naturali.ai API.

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

GET STARTED

Start building with naturali.ai API

Explore with Jentic One

View OpenAPI Document

Use Cases

Patterns agents use naturali.ai API for, with concrete tasks.

★ 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.

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.

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.

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.

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

371 endpoints — the naturali.

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

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

Why Jentic?

What agents get from Jentic-routed access to this vendor.

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 isolation

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.

Intent-based discovery

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.

FAQs

Specific to using naturali.ai API through Jentic.

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.

naturali.ai API

AI ReadinessFoundational (C+)60/100

See full scorecard

Official vendor OpenAPI document · agent-readyAI/MLLanguage Modelsbearer, oauth2371 EndpointsREST

For 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.

Use for: I need to run a naturali.ai agent on a customer question and wait for the answer, Search the project's documents and memories for the refund policy, Ingest this PDF into the project knowledge base, List all approval items waiting for a decision

Not supported: 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.

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.

Jentic One on Github View OpenAPI Document

Show dimension breakdown

Foundational Compliance

Base layer of spec validity and structural soundness.

Grade: A-Signals: 4

91%

Lint Results

Aggregated quality score from linter diagnostics, weighted by severity.

100%

Resolution Completeness

Percentage of `$ref` references that resolve successfully.

100%

Specification Validity

Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).

Structural Integrity

Structural correctness score based on schema issues using logarithmic dampening.

Developer Experience & Jentic Compatibility

Clarity, completeness, and ingestion readiness for developers and tooling.

Grade: B+Signals: 4

23%

Example Density

How richly the API is illustrated with examples.

100%

Example Validity

Percentage of examples that conform to their schemas.

55%

Response Coverage

Percentage of operations with complete response definitions (success, client error, server error).

100%

Tooling Readiness

Health of API ingestion, bundling, and resolution within Jentic pipelines.

AI-Readiness & Agent Experience

Semantic breadth, depth, and agent comprehension for AI systems.

Grade: CSignals: 4

62%

Description Coverage

Coverage of descriptions across API elements.

Error Standardization

Coverage of RFC 9457 Problem Details for error responses.

100%

OperationId Quality

Coverage, uniqueness, and casing consistency of operationIds for AI inference.

62%

Summary Coverage

Coverage of summaries across operations/tags/info.

Agent Usability

Functional utility, complexity comfort, and AI orchestration readiness.

Grade: D-Signals: 1

43%

Complexity Comfort

Agent comfort level based on API operational and structural complexity.

Security

Trust, risk posture, and security compliance.

Grade: A-Signals: 1

75%

Authentication Strength

Average quality of security schemes based on authentication method strength (weakest link for OAuth2).

AI Discoverability

Findability, semantic richness, and reasoning readiness.

Grade: A-Signals: 1

73%

Descriptive Richness

Clarity and depth of descriptions across API elements.

Connect the naturali.ai API to your agent

Capabilities

Start building with naturali.ai API

Use Cases

Key Endpoints

Why Jentic?

Related APIs

FAQs

naturali.ai API

Jentic AI Readiness Score

naturali.ai API

Foundational Compliance

Lint Results

Resolution Completeness

Specification Validity

Structural Integrity

Developer Experience & Jentic Compatibility

Example Density

Example Validity

Response Coverage

Tooling Readiness

AI-Readiness & Agent Experience

Description Coverage

Error Standardization

OperationId Quality

Summary Coverage

Agent Usability

Complexity Comfort

Security

Authentication Strength

AI Discoverability

Descriptive Richness