API Guide

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Get your API key at app.trynia.ai. For autonomous agents, use Agent Onboarding to create accounts and keys via API (/v2/auth/signup, /v2/auth/verify, /v2/auth/login, /v2/auth/login/verify) and then install the skill non-interactively.

Store your API key in an environment variable or secret manager. Rotate it immediately if compromised.

Base URL

All API endpoints are available at:

https://apigcp.trynia.ai/v2

Rate Limits

View your current usage and limits at app.trynia.ai. See the Pricing page for plan details. When you exceed rate limits, the API returns a 429 status code:

{
  "error": "Rate limit exceeded",
  "status": 429
}

Rate limit headers are included in responses:

Header	Description
`X-RateLimit-Limit`	Rate limit ceiling for the endpoint
`X-RateLimit-Remaining`	Remaining requests in current window
`X-RateLimit-Reset`	Time when the rate limit resets
`X-Monthly-Limit`	Monthly request limit

Quick Start Examples

Index a Repository

curl -X POST https://apigcp.trynia.ai/v2/sources \
  -H "Authorization: Bearer $NIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "repository", "repository": "vercel/ai"}'

Index Documentation

curl -X POST https://apigcp.trynia.ai/v2/sources \
  -H "Authorization: Bearer $NIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "documentation", "url": "https://sdk.vercel.ai/docs"}'

Search Across Sources

curl -X POST https://apigcp.trynia.ai/v2/search \
  -H "Authorization: Bearer $NIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "query",
    "messages": [{"role": "user", "content": "How do I stream responses?"}],
    "repositories": ["vercel/ai"],
    "data_sources": ["Vercel AI SDK"]
  }'

Deploy a Document Agent

curl -X POST https://apigcp.trynia.ai/v2/document/agent \
  -H "Authorization: Bearer $NIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "your-pdf-source-id",
    "query": "What are the key findings?"
  }'

Package Search (No Indexing Required)

curl -X POST https://apigcp.trynia.ai/v2/packages/grep \
  -H "Authorization: Bearer $NIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "registry": "npm",
    "package_name": "ai",
    "pattern": "streamText"
  }'

Sandbox search (clone + read-only agent)

Run an ephemeral sandbox that clones a public repo URL and answers with a read-only agent — no indexing step. Use a full URL (not org/repo shorthand). See Sandbox search for SSE, job polling, and response fields.

curl -X POST https://apigcp.trynia.ai/v2/sandbox/search \
  -H "Authorization: Bearer $NIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "https://github.com/vercel/ai",
    "ref": "main",
    "query": "How does streamText relate to the data stream protocol?"
  }'

Best Practices

Use the Unified Search Endpoint

The /search endpoint supports four modes via a discriminator. Use mode: "query" for multi-source search, mode: "universal" for cross-source discovery, mode: "web" for web search, and mode: "deep" for multi-step research:

curl -X POST https://apigcp.trynia.ai/v2/search \
  -H "Authorization: Bearer $NIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "query",
    "messages": [{"role": "user", "content": "authentication middleware implementation"}],
    "search_mode": "unified"
  }'

Sandbox search vs unified search

Sandbox search (POST /sandbox/search) bills as a query like /search, but it clones the repository into an isolated VM for a file-grounded agent run. Prefer /search when your content is already indexed or you need multi-source retrieval; use sandbox search for one-off deep questions against a public Git URL without creating a source.

Leverage Package Search for Dependencies

Search through 3,000+ packages across PyPI, NPM, Crates.io, and Go modules without indexing:

import requests

headers = {"Authorization": f"Bearer {NIA_API_KEY}"}

# Semantic search for understanding patterns
response = requests.post(
    "https://apigcp.trynia.ai/v2/packages/search",
    headers=headers,
    json={
        "registry": "py_pi",
        "package_name": "fastapi",
        "semantic_queries": ["How does dependency injection work?"]
    }
)

Handle Rate Limits with Exponential Backoff

import time
import requests

def fetch_with_retry(url, headers, json_data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=json_data)
        
        if response.status_code == 429:
            wait_time = 2 ** attempt
            print(f"Rate limited. Waiting {wait_time}s...")
            time.sleep(wait_time)
            continue
        
        return response
    
    raise Exception("Max retries exceeded")

Monitor Indexing Progress

Large sources take time to index. Poll the status endpoint:

# Check source status
curl https://apigcp.trynia.ai/v2/sources/{source_id} \
  -H "Authorization: Bearer $NIA_API_KEY"

Response includes status:

{
  "id": "source-uuid",
  "type": "repository",
  "display_name": "vercel/ai",
  "status": "indexing",
  "identifier": "vercel/ai"
}

For a quick inventory of all sources:

curl https://apigcp.trynia.ai/v2/sources-summary \
  -H "Authorization: Bearer $NIA_API_KEY"

Error Handling

The Nia API uses standard HTTP status codes:

Code	Description	Action
200	Success	Process the response normally
400	Bad Request	Check request parameters
401	Unauthorized	Verify your API key
404	Not Found	Resource doesn’t exist
429	Rate Limited	Implement backoff and retry
500	Server Error	Retry with backoff, contact support if persistent

Error Response Format

{
  "error": "Error message describing what went wrong",
  "status": 429
}

SDK & Integration Options

MCP Server (Recommended for AI Agents)

The easiest way to integrate Nia with AI coding agents:

curl -fsSL https://app.trynia.ai/cli | sh

See the Installation guide for detailed setup.

Direct API Integration

For custom applications, use the REST API directly: JavaScript/TypeScript:

const response = await fetch("https://apigcp.trynia.ai/v2/search", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.NIA_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    mode: "query",
    messages: [{ role: "user", content: "How does error handling work?" }],
    repositories: ["fastapi/fastapi"]
  })
});

const results = await response.json();

Python:

import requests

headers = {
    "Authorization": f"Bearer {os.environ['NIA_API_KEY']}",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://apigcp.trynia.ai/v2/search",
    headers=headers,
    json={
        "mode": "query",
        "messages": [{"role": "user", "content": "How does error handling work?"}],
        "repositories": ["fastapi/fastapi"]
    }
)

results = response.json()

Key Endpoints

Endpoint	Description
`POST /sources`	Create/index any source (repository, documentation, paper, dataset, local folder)
`GET /sources`	List all indexed sources
`POST /search`	Unified search with mode: `query`, `web`, `deep`, `universal`
`POST /sandbox/search`	Clone a public Git URL in an ephemeral sandbox and run read-only agent search (guide)
`GET /sandbox/jobs/{jobId}`	Get status and result for a sandbox search job
`POST /document/agent`	Deploy an autonomous AI agent into a document (structured output, citations)
`POST /extract`	Extract structured data from PDFs
`POST /oracle/jobs`	Start an Oracle research job
`POST /github/tracer`	Live GitHub code search agent
`POST /packages/search`	Semantic search in package source code
`POST /packages/grep`	Regex search in package source code
`POST /contexts`	Save cross-agent conversation context
`GET /sources-summary`	Quick inventory of all source types
`GET /usage`	API usage statistics and limits

Check out the API Reference for complete endpoint documentation with request/response schemas.

Getting Started

Capabilities

Source Types

Explore

Examples & Guides

Enterprise

Privacy

Authentication

Base URL

Rate Limits

Quick Start Examples

Index a Repository

Index Documentation

Search Across Sources

Deploy a Document Agent

Package Search (No Indexing Required)

Sandbox search (clone + read-only agent)

Best Practices

Use the Unified Search Endpoint

Sandbox search vs unified search

Leverage Package Search for Dependencies

Handle Rate Limits with Exponential Backoff

Monitor Indexing Progress

Error Handling

Error Response Format

SDK & Integration Options

MCP Server (Recommended for AI Agents)

Direct API Integration

Key Endpoints

​Authentication

​Base URL

​Rate Limits

​Quick Start Examples

​Index a Repository

​Index Documentation

​Search Across Sources

​Deploy a Document Agent

​Package Search (No Indexing Required)

​Sandbox search (clone + read-only agent)

​Best Practices

​Use the Unified Search Endpoint

​Sandbox search vs unified search

​Leverage Package Search for Dependencies

​Handle Rate Limits with Exponential Backoff

​Monitor Indexing Progress

​Error Handling

​Error Response Format

​SDK & Integration Options

​MCP Server (Recommended for AI Agents)

​Direct API Integration

​Key Endpoints

Authentication

Base URL

Rate Limits

Quick Start Examples

Index a Repository

Index Documentation

Search Across Sources

Deploy a Document Agent

Package Search (No Indexing Required)

Sandbox search (clone + read-only agent)

Best Practices

Use the Unified Search Endpoint

Sandbox search vs unified search

Leverage Package Search for Dependencies

Handle Rate Limits with Exponential Backoff

Monitor Indexing Progress

Error Handling

Error Response Format

SDK & Integration Options

MCP Server (Recommended for AI Agents)

Direct API Integration

Key Endpoints