Authentication - Nia AI Documentation

Getting Your API Key

If you need fully headless onboarding for agents, follow Agent Onboarding for API-first signup/login and non-interactive skill installation.

Create an account

Go to app.trynia.ai and sign in or create a new account.

Navigate to API Keys

Open Settings → API Keys from the sidebar.

Generate a key

Click Create new API key, give it a name, and copy the key. You won’t be able to see it again.

Keep your API key secure. Never commit it to version control or expose it in client-side code.

Client Setup

High-Level SDK (Recommended)

Python
TypeScript

from nia_py.sdk import NiaSDK

sdk = NiaSDK(api_key="nia_your_api_key")

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

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

Low-Level Client

For full control over individual API calls, use the underlying authenticated client directly.

Python
TypeScript

from nia_py import AuthenticatedClient

client = AuthenticatedClient(
    base_url="https://apigcp.trynia.ai/v2",
    token="nia_your_api_key",
)

import { OpenAPI, V2ApiRepositoriesService } from "nia-ai-ts";

OpenAPI.BASE = "https://apigcp.trynia.ai/v2";
OpenAPI.TOKEN = "nia_your_api_key";

const repos = await V2ApiRepositoriesService.listRepositoriesV2V2RepositoriesGet();

Environment Variables

Store your API key in an environment variable instead of hardcoding it:

export NIA_API_KEY="nia_your_api_key"

Python
TypeScript

import os
from nia_py.sdk import NiaSDK

sdk = NiaSDK(api_key=os.environ["NIA_API_KEY"])

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

const sdk = new NiaSDK({ apiKey: process.env.NIA_API_KEY! });

Advanced Configuration

Request Timeout

Python
TypeScript

sdk = NiaSDK(
    api_key=os.environ["NIA_API_KEY"],
    timeout_seconds=120.0,  # default: 60s
)

For the low-level client, pass an httpx.Timeout:

import httpx
from nia_py import AuthenticatedClient

client = AuthenticatedClient(
    base_url="https://apigcp.trynia.ai/v2",
    token="nia_your_api_key",
    timeout=httpx.Timeout(120.0),
)

// Timeout is controlled at the fetch level.
// The SDK defaults to the platform's fetch timeout.
const sdk = new NiaSDK({
  apiKey: process.env.NIA_API_KEY!,
});

Retry Configuration

Both SDKs include automatic retries with exponential backoff for server errors (5xx) and network failures.

Python
TypeScript

sdk = NiaSDK(
    api_key="nia_your_api_key",
    max_retries=3,                   # default: 2
    initial_backoff_seconds=1.0,     # default: 0.5
)
# Backoff: 1s → 2s → 4s

const sdk = new NiaSDK({
  apiKey: "nia_your_api_key",
  maxRetries: 3,            // default: 2
  initialBackoffMs: 1000,   // default: 500
});
// Backoff: 1000ms → 2000ms → 4000ms

Context Manager (Python)

The Python low-level client supports context managers for automatic resource cleanup:

from nia_py import AuthenticatedClient
from nia_py.api.v2_api import list_repositories_v2_v2_repositories_get

with AuthenticatedClient(
    base_url="https://apigcp.trynia.ai/v2",
    token="nia_your_api_key",
) as client:
    repos = list_repositories_v2_v2_repositories_get.sync(client=client)

Or async:

async with AuthenticatedClient(
    base_url="https://apigcp.trynia.ai/v2",
    token="nia_your_api_key",
) as client:
    repos = await list_repositories_v2_v2_repositories_get.asyncio(client=client)

Rate Limits

API rate limits depend on your plan:

Plan	Requests/min	Indexed Sources
Free	10	3
Pro	60	Unlimited
Enterprise	Custom	Unlimited

Rate limit headers are included in every response:

X-RateLimit-Limit — maximum requests allowed
X-RateLimit-Remaining — requests remaining in window
X-RateLimit-Reset — seconds until window resets

Error Handling

Python
TypeScript

High-level SDK raises typed exceptions:

from nia_py.sdk import NiaSDK
from nia_py.sdk.errors import NiaAPIError, NiaTimeoutError

sdk = NiaSDK(api_key="nia_your_api_key")

try:
    result = sdk.search.universal(query="test")
except NiaAPIError as e:
    print(f"API error {e.status_code}: {e}")
except NiaTimeoutError as e:
    print(f"Operation timed out: {e}")

Low-level client returns Response objects with status codes:

from nia_py.api.v2_api import list_repositories_v2_v2_repositories_get

response = list_repositories_v2_v2_repositories_get.sync_detailed(client=client)

if response.status_code == 200:
    print(response.parsed)
elif response.status_code == 401:
    print("Invalid API key")
elif response.status_code == 429:
    print("Rate limited — retry after:", response.headers.get("Retry-After"))

High-level SDK throws typed errors:

import { NiaSDK, NiaTimeoutError, NiaSDKError } from "nia-ai-ts";

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

try {
  const result = await sdk.search.universal({ query: "test" });
} catch (error) {
  if (error instanceof NiaTimeoutError) {
    console.error("Operation timed out:", error.message);
  } else if (error instanceof NiaSDKError) {
    console.error("SDK error:", error.message);
  }
}

Low-level services throw ApiError with status info:

import { ApiError, V2ApiRepositoriesService } from "nia-ai-ts";

try {
  const repos = await V2ApiRepositoriesService.listRepositoriesV2V2RepositoriesGet();
} catch (error) {
  if (error instanceof ApiError) {
    console.error(`API error ${error.status}: ${error.body}`);
  }
}

Authentication Methods

The API accepts your key via either header:

Header	Format
`Authorization`	`Bearer nia_your_api_key`
`X-API-Key`	`nia_your_api_key`

Both SDKs use the Authorization: Bearer format by default. The Python low-level client allows customizing the header:

client = AuthenticatedClient(
    base_url="https://apigcp.trynia.ai/v2",
    token="nia_your_api_key",
    prefix="Bearer",                  # default
    auth_header_name="Authorization", # default
)

​Getting Your API Key

​Client Setup

​High-Level SDK (Recommended)

​Low-Level Client

​Environment Variables

​Advanced Configuration

​Request Timeout

​Retry Configuration

​Context Manager (Python)

​Rate Limits

​Error Handling

​Authentication Methods

Getting Your API Key

Client Setup

High-Level SDK (Recommended)

Low-Level Client

Environment Variables

Advanced Configuration

Request Timeout

Retry Configuration

Context Manager (Python)

Rate Limits

Error Handling

Authentication Methods