Skip to main content

​
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:
HeaderDescription
X-RateLimit-LimitRate limit ceiling for the endpoint
X-RateLimit-RemainingRemaining requests in current window
X-RateLimit-ResetTime when the rate limit resets
X-Monthly-LimitMonthly 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 (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:
CodeDescriptionAction
200SuccessProcess the response normally
400Bad RequestCheck request parameters
401UnauthorizedVerify your API key
404Not FoundResource doesn’t exist
429Rate LimitedImplement backoff and retry
500Server ErrorRetry with backoff, contact support if persistent

​
Error Response Format

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

​
SDK & Integration Options

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

EndpointDescription
POST /sourcesCreate/index any source (repository, documentation, paper, dataset, local folder)
GET /sourcesList all indexed sources
POST /searchUnified search with mode: query, web, deep, universal
POST /sandbox/searchClone 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/agentDeploy an autonomous AI agent into a document (structured output, citations)
POST /extractExtract structured data from PDFs
POST /oracle/jobsStart an Oracle research job
POST /github/tracerLive GitHub code search agent
POST /packages/searchSemantic search in package source code
POST /packages/grepRegex search in package source code
POST /contextsSave cross-agent conversation context
GET /sources-summaryQuick inventory of all source types
GET /usageAPI usage statistics and limits
Check out the API Reference for complete endpoint documentation with request/response schemas.