Copy page

Overview

Neuratel SDK

Create a voice agent and place a call in under 10 lines.

Code
pip install neuratelai         # Python
npm install @neuratelai/sdk    # TypeScript / Node

Code
from neuratelai import NeuratelAI

client = NeuratelAI()  # reads NEURATEL_API_KEY from env

agent = client.agents.create(
    name="Support Bot",
    brain={"provider": "groq", "model": "meta-llama/llama-4-scout-17b-16e-instruct", "instructions": "You are a helpful support agent."},
)

call = client.voice_sessions.outbound(
    agent_id=agent["id"],
    to_number="+14155551234",
    number_id="your-number-uuid",
)
print(call["status"])

Code
import { NeuratelAI } from "@neuratelai/sdk";

const client = new NeuratelAI(); // reads NEURATEL_API_KEY from env

const agent = await client.agents.create({
  name: "Support Bot",
  brain: { provider: "groq", model: "meta-llama/llama-4-scout-17b-16e-instruct", instructions: "You are a helpful support agent." },
});

const call = await client.voiceSessions.outbound({
  agent_id: agent.id,
  to_number: "+14155551234",
  number_id: "your-number-uuid",
});
console.log(call.status);

---

Available SDKs

SDK	Package	Version	Requires
Python	neuratelai on PyPI	v0.2.0	Python 3.10+
TypeScript	@neuratelai/sdk on npm	v0.2.0	Node 18+

Both SDKs cover the same 15 resource groups with full method parity.

SDK comparison

Feature	Python SDK	TypeScript SDK
Sync client	NeuratelAI	—
Async client	AsyncNeuratelAI	NeuratelAI
Runtime deps	httpx, pydantic	None (native fetch)
Pagination	SyncPage / AsyncPage	Page<T>

Authentication

Get an API key from Settings → API Keys. Keys start with nk_live_.

Code
export NEURATEL_API_KEY="nk_live_your_key_here"

Both SDKs read NEURATEL_API_KEY automatically. Pass explicitly if needed:

Code
client = NeuratelAI(api_key="nk_live_...")

Code
const client = new NeuratelAI({ apiKey: "nk_live_..." });

Error handling

Code
from neuratelai import NeuratelAI, AuthenticationError, NotFoundError, RateLimitError, APIError

try:
    agent = client.agents.get("ag_unknown")
except AuthenticationError:
    print("Invalid API key")
except NotFoundError:
    print("Agent not found")
except RateLimitError:
    print("Rate limited — back off and retry")
except APIError as e:
    print(f"Error {e.status_code}: {e}")

Class	HTTP	When
AuthenticationError	401	Invalid or missing API key
PermissionDeniedError	403	Insufficient permissions
NotFoundError	404	Resource doesn't exist
ConflictError	409	Duplicate resource
UnprocessableEntityError	422	Validation failed
RateLimitError	429	Too many requests
InternalServerError	5xx	Server error
APIConnectionError	—	Network failure
APITimeoutError	—	Request timed out

Retries

Both SDKs retry automatically on 429, 408, and 5xx with exponential backoff. Respects Retry-After headers.

Code
client = NeuratelAI(max_retries=3)  # default: 2

Pagination

Code
# Auto-page through all agents
for agent in client.agents.list().auto_paging_iter():
    print(agent["id"])

# Manual page control
page = client.agents.list(limit=20)
print(page.results)    # items on this page
print(page.metadata)   # { total, skip, limit, has_more, count }

Code
// Async auto-paging
for await (const agent of await client.agents.list()) {
  console.log(agent.id);
}

// Manual
const page = await client.agents.list({ limit: 20 });
if (page.hasNextPage()) {
  const next = await page.getNextPage();
}

Resources

agents · voiceSessions · conversations · phoneNumbers · campaigns · callLists · knowledgeBase · webhooks · billing · apiKeys · integrations · dnc · analytics · whatsapp · workflows

Both SDKs ship typed models generated from the canonical OpenAPI spec — import them via from neuratelai.types import VoiceSession, Agent (Python) or import type { Types } from "@neuratelai/sdk" (Node).

→ Python on GitHub  ·  TypeScript on GitHub  ·  REST API