Quickstart

Get started with the Nia AI SDKs for Python and TypeScript

Nia provides official SDKs for Python and TypeScript with a high-level client that wraps the REST API into an ergonomic interface with built-in retries, streaming, and type safety.

Installation

Python

pip install nia-ai-py

Or with uv:

uv add nia-ai-py

Requires Python 3.10+.

TypeScript

npm install nia-ai-ts

Or with other package managers:

yarn add nia-ai-ts
# or
pnpm add nia-ai-ts
# or
bun add nia-ai-ts

Quick Start

Python

from nia_py.sdk import NiaSDK

sdk = NiaSDK(api_key="nia_your_api_key")

# Semantic search across your indexed sources
results = sdk.search.universal(query="How does authentication work?")
print(results)

TypeScript

import { NiaSDK } from "nia-ai-ts";

const sdk = new NiaSDK({ apiKey: "nia_your_api_key" });

// Semantic search across your indexed sources
const results = await sdk.search.universal({ query: "How does authentication work?" });
console.log(results);

Get your API key at app.trynia.ai under Settings → API Keys. Never commit API keys to version control.

Core Concepts

The SDK is organized into three clients accessible from the main NiaSDK instance:

Client	Description
sdk.search	Semantic search, web search, deep research, and query-based code search
sdk.sources	Create, list, resolve, and delete indexed sources (repos, docs, papers)
sdk.oracle	Launch autonomous research jobs with streaming and polling

Search

Python

from nia_py.sdk import NiaSDK

sdk = NiaSDK(api_key="nia_your_api_key")

# Universal search across all indexed sources
results = sdk.search.universal(query="implement retry logic", top_k=10)

# Query search with specific repos and conversation context
results = sdk.search.query(
    messages=[{"role": "user", "content": "How does streaming work?"}],
    repositories=["vercel/ai"],
)

# Web search
results = sdk.search.web(query="latest LLM developments")

# Deep research (multi-step with citations)
results = sdk.search.deep(query="Compare RSC vs traditional SSR")

TypeScript

import { NiaSDK } from "nia-ai-ts";

const sdk = new NiaSDK({ apiKey: "nia_your_api_key" });

// Universal search across all indexed sources
const results = await sdk.search.universal({ query: "implement retry logic", top_k: 10 });

// Query search with specific repos and conversation context
const queryResults = await sdk.search.query({
  messages: [{ role: "user", content: "How does streaming work?" }],
  repositories: ["vercel/ai"],
});

// Web search
const webResults = await sdk.search.web({ query: "latest LLM developments" });

// Deep research (multi-step with citations)
const deepResults = await sdk.search.deep({ query: "Compare RSC vs traditional SSR" });

Source Management

Python

# Create a source (auto-detects type from URL)
sdk.sources.create({"url": "https://github.com/vercel/ai"})
sdk.sources.create({"url": "https://docs.anthropic.com"})

# List sources with filters
repos = sdk.sources.list(type="repository", limit=20)

# Resolve a source by name
source = sdk.sources.resolve(identifier="vercel/ai")

# Delete a source
sdk.sources.delete(source_id="source-uuid")

TypeScript

// Create a source (auto-detects type from URL)
await sdk.sources.create({ url: "https://github.com/vercel/ai" });
await sdk.sources.create({ url: "https://docs.anthropic.com" });

// List sources with filters
const repos = await sdk.sources.list({ type: "repository", limit: 20 });

// Resolve a source by name
const source = await sdk.sources.resolve({ identifier: "vercel/ai" });

// Delete a source
await sdk.sources.delete({ sourceId: "source-uuid" });

Oracle Research

Oracle is Nia’s autonomous research agent. It runs multi-step research jobs that can take minutes to complete.

Python

# Start a research job
job = sdk.oracle.create_job(
    query="How does Next.js handle caching in the App Router?",
    repositories=["vercel/next.js"],
)
print(f"Job started: {job['id']}")

# Wait for completion (polls every 2s, 10min timeout)
result = sdk.oracle.wait_for_job(job_id=job["id"])
print(result)

# Or stream events in real-time
for event in sdk.oracle.stream_job_events(job_id=job["id"]):
    print(event)

TypeScript

// Start a research job
const job = await sdk.oracle.createJob({
  query: "How does Next.js handle caching in the App Router?",
  repositories: ["vercel/next.js"],
});
console.log(`Job started: ${job.id}`);

// Wait for completion (polls every 2s, 10min timeout)
const result = await sdk.oracle.waitForJob(job.id);
console.log(result);

// Or stream events in real-time
for await (const event of sdk.oracle.streamJob(job.id)) {
  console.log(event);
}

Configuration

Both SDKs accept the same configuration options:

Python

sdk = NiaSDK(
    api_key="nia_your_api_key",
    base_url="https://apigcp.trynia.ai/v2",  # default
    timeout_seconds=60.0,                      # request timeout
    max_retries=2,                             # retry on 5xx / transport errors
    initial_backoff_seconds=0.5,               # exponential backoff base
)

TypeScript

const sdk = new NiaSDK({
  apiKey: "nia_your_api_key",
  baseUrl: "https://apigcp.trynia.ai/v2",  // default
  maxRetries: 2,                             // retry on failures
  initialBackoffMs: 500,                     // exponential backoff base
});

Next Steps

Authentication

API key setup, environment variables, and advanced client configuration

Examples

Complete code examples for all SDK operations

REST API Reference

Full REST API documentation with all endpoints

Get API Key

Create your free Nia account and generate an API key