API Documentation

Interactive API documentation and code examples

Quick Start

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_NATARIS_KEY",
    base_url="https://api.nataris.ai/v1"
)

response = client.chat.completions.create(
    model="nataris-balanced",  # or nataris-fast / nataris-quality
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

cURL

# OpenAI-compatible Chat Completions API
curl -X POST https://api.nataris.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nataris-balanced",
    "messages": [{"role": "user", "content": "Hello, world!"}],
    "stream": true
  }'

# Tip: streaming is the default and recommended — responses start
# arriving immediately, making your app feel fast and responsive.

Available Models

Use capability aliases — we route to the best available device for that tier. Raw model IDs also work for backward compatibility.

nataris-fast

Lowest latency · 0.5B

qwen2.5-0.5b-instruct-q6_k

nataris-balanced

Speed + quality · 1B

llama-3.2-1b-instruct-q4_k_m

nataris-quality

Best quality · 3.8B

phi-3-mini-4k-instruct-q4_k_m

Best-effort — requires a high-RAM device (6GB+). May return MODEL_NOT_WARM if unavailable; use nataris-balanced as fallback.

P2P Inference Network

Nataris routes your requests to community phone providers — real people running AI models on their devices. With smart failover (5 retries in under 15 seconds) and automatic re-routing, your requests are resilient even when individual devices go offline.

P2PCommunity Providers

Runs on real phones in the Nataris network. 85% of revenue goes directly to device providers.

FailoverSmart Retry

If a device fails, the job is instantly re-routed to the next available device. 5 retries, fast linear backoff.

Check response.nataris.inference_type to see if your request was handled by "p2p" or "cloud". Each model's tier field indicates where it can run: P2P, CLOUD, or HYBRID.

API Endpoints

Method	Endpoint	Description
POST	/v1/chat/completions	Chat completionsRecommended
POST	/v1/jobs	Legacy inference job
GET	/v1/jobs/:id	Get job status and result
GET	/v1/models	List available models
GET	/v1/workflows	List workflowsOrchestration
GET	/v1/workflows/:id	Get workflow details + steps
POST	/v1/workflows/estimate	Estimate orchestration cost
POST	/v1/conversations	Create conversationMemory
GET	/v1/conversations	List conversations
GET	/v1/conversations/:id	Get conversation context
POST	/v1/conversations/:id/messages	Add message to conversation

Authentication

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Get your API key from the dashboard after signing up.

Verified Provider Routing

Route requests only to providers with verified device integrity via Google Play Integrity API.

{
  "modelId": "nataris-balanced",
  "prompt": "Your prompt here",
  "privacyLevel": "verified"
}

Multi-Step Workflows (Orchestration)

Research Workflow — auto-chains research → analyze → write

curl -X POST https://api.nataris.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nataris-balanced",
    "messages": [{"role": "user", "content": "Research renewable energy trends"}],
    "stream": true,
    "orchestration": {
      "enabled": true,
      "workflow": "research",
      "max_steps": 10,
      "max_cost_usd": 1.0
    }
  }'

Workflow types: research · code · agent · map_reduce · auto — Billed at 1.5x base rate

Conversation Memory

Pass a conversation_id to automatically persist messages server-side. The API maintains conversation context with auto-generated titles and rolling summarization — no need to send full chat history every time.

{
  "model": "nataris-balanced",
  "messages": [{"role": "user", "content": "Tell me more about that"}],
  "conversation_id": "conv-uuid-from-POST-/v1/conversations"
}

Manage conversations via /v1/conversations — create, list, get context, delete.

Interactive API Reference

Explore the full API with request/response schemas using our interactive Swagger documentation.

Open Swagger UI →

Ready to get started?

Get Your API Key →