# Agent Onboarding Source: https://docs.trynia.ai/agent-onboarding API-first account creation and non-interactive skill installation for autonomous agents Use this guide when an AI agent needs to onboard without browser prompts. ## Prerequisites * Base URL: `https://apigcp.trynia.ai/v2` * `nia-wizard` installed or runnable with `npx`. ## Flow Overview ### New Users 1. Create account with `POST /v2/auth/signup` — returns a read-only API key and sends a 6-digit verification code to email. 2. Verify the account with `POST /v2/auth/verify` — upgrades the API key to full access. 3. Install Nia skill in non-interactive mode using `nia-wizard skill add`. ### Returning Users 1. Request a verification code with `POST /v2/auth/login`. 2. Exchange the code for a full-access API key with `POST /v2/auth/login/verify`. ## Create Account (API-First) ```bash theme={null} curl -sS -X POST "https://apigcp.trynia.ai/v2/auth/signup" \ -H "Content-Type: application/json" \ -d '{ "email": "agent@example.com", "organization_name": "Agent Org", "first_name": "Agent", "last_name": "Runner", "idempotency_key": "signup-agent-001" }' ``` Response includes: * `api_key` (read-only until verified) * `api_key_id` * `user_id` * `organization_id` * `verified` (false) ## Verify Account Use the 6-digit code sent to your email: ```bash theme={null} curl -sS -X POST "https://apigcp.trynia.ai/v2/auth/verify" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer " \ -d '{ "code": "123456" }' ``` On success, the API key is upgraded from read-only to full access. ## Returning User Login (Passwordless) ### Step 1: Request verification code ```bash theme={null} curl -sS -X POST "https://apigcp.trynia.ai/v2/auth/login" \ -H "Content-Type: application/json" \ -d '{ "email": "agent@example.com" }' ``` ### Step 2: Exchange code for API key ```bash theme={null} curl -sS -X POST "https://apigcp.trynia.ai/v2/auth/login/verify" \ -H "Content-Type: application/json" \ -d '{ "email": "agent@example.com", "code": "123456" }' ``` Response includes a fresh `api_key` with full access. ## Install Nia Skill Non-Interactively ```bash theme={null} npx nia-wizard skill add \ --api-key "" \ --source nozomio-labs/nia-skill \ --non-interactive \ --ci ``` Optional target pinning: ```bash theme={null} npx nia-wizard skill add \ --api-key "" \ --target codex \ --non-interactive \ --ci ``` ## End-To-End Script (Headless) ```bash theme={null} #!/usr/bin/env bash set -euo pipefail BASE_URL="https://apigcp.trynia.ai/v2" EMAIL="agent@example.com" ORG_NAME="Agent Org" # Step 1: Sign up (returns read-only API key) SIGNUP_JSON=$(curl -sS -X POST "$BASE_URL/auth/signup" \ -H "Content-Type: application/json" \ -d "{\"email\":\"$EMAIL\",\"organization_name\":\"$ORG_NAME\"}") API_KEY=$(echo "$SIGNUP_JSON" | jq -r '.api_key') # Step 2: Verify with email code (upgrades key to full access) read -rp "Enter 6-digit verification code: " CODE curl -sS -X POST "$BASE_URL/auth/verify" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $API_KEY" \ -d "{\"code\":\"$CODE\"}" # Step 3: Install skill npx nia-wizard skill add --api-key "$API_KEY" --non-interactive --ci ``` Handle credentials and generated API keys as secrets. Do not print them to shared logs. ## Reference See API Reference for these endpoints: * `POST /auth/signup` * `POST /auth/verify` * `POST /auth/login` * `POST /auth/login/verify` * `POST /auth/resend-code` # API Guide Source: https://docs.trynia.ai/api-guide Authentication, rate limits, best practices, and integration guides for the Nia API ## Authentication All API requests require authentication using an API key. Include your API key in the `Authorization` header: ```bash theme={null} Authorization: Bearer YOUR_API_KEY ``` Get your API key at [app.trynia.ai](https://app.trynia.ai). For autonomous agents, use [Agent Onboarding](/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](https://app.trynia.ai). See the [Pricing page](/pricing) for plan details. When you exceed rate limits, the API returns a `429` status code: ```json theme={null} { "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 ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} 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) ```bash theme={null} 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](/sandbox-search) for SSE, job polling, and response fields. ```bash theme={null} 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: ```bash theme={null} 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](/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: ```python theme={null} 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 ```python theme={null} 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: ```bash theme={null} # Check source status curl https://apigcp.trynia.ai/v2/sources/{source_id} \ -H "Authorization: Bearer $NIA_API_KEY" ``` Response includes status: ```json theme={null} { "id": "source-uuid", "type": "repository", "display_name": "vercel/ai", "status": "indexing", "identifier": "vercel/ai" } ``` For a quick inventory of all sources: ```bash theme={null} 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 ```json theme={null} { "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: ```bash theme={null} curl -fsSL https://app.trynia.ai/cli | sh ``` See the [Installation guide](/integrations/installation/overview) for detailed setup. ### Direct API Integration For custom applications, use the REST API directly: **JavaScript/TypeScript:** ```javascript theme={null} 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:** ```python theme={null} 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](/sandbox-search)) | | `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](/api-reference) for complete endpoint documentation with request/response schemas. # Context-aware code advisor Source: https://docs.trynia.ai/api-reference/advisor/context-aware-code-advisor /openapi-docs.yaml post /advisor Analyze codebase context against Nia's indexed documentation to get tailored recommendations. # Login Source: https://docs.trynia.ai/api-reference/auth/login /openapi-docs.yaml post /auth/login Request a verification code for passwordless login. A 6-digit code is sent to the provided email. Exchange it via POST /v2/auth/login/verify to receive a new API key. # Login Verify Source: https://docs.trynia.ai/api-reference/auth/login-verify /openapi-docs.yaml post /auth/login/verify Verify login code and receive a new full-access API key. # Resend Code Source: https://docs.trynia.ai/api-reference/auth/resend-code /openapi-docs.yaml post /auth/resend-code Resend the verification code for an unverified API key. Requires the read-only API key in the Authorization header. # Signup Source: https://docs.trynia.ai/api-reference/auth/signup /openapi-docs.yaml post /auth/signup Create a new account and receive a read-only API key. A 6-digit verification code is sent to the provided email. Call POST /v2/auth/verify with the code (and this key in the Authorization header) to upgrade to full access. # Verify Source: https://docs.trynia.ai/api-reference/auth/verify /openapi-docs.yaml post /auth/verify Verify your account using the 6-digit code sent to your email. On success, the API key used in the Authorization header is upgraded from read-only to full access. # Create category Source: https://docs.trynia.ai/api-reference/categories/create-category /openapi-docs.yaml post /categories Create a new category for organizing data sources. # Delete category Source: https://docs.trynia.ai/api-reference/categories/delete-category /openapi-docs.yaml delete /categories/{category_id} Delete a category. Data sources with this category will become uncategorized. # List categories Source: https://docs.trynia.ai/api-reference/categories/list-categories /openapi-docs.yaml get /categories List categories for the authenticated user/organization. # Update category Source: https://docs.trynia.ai/api-reference/categories/update-category /openapi-docs.yaml patch /categories/{category_id} Update an existing category. # Delete context Source: https://docs.trynia.ai/api-reference/context-sharing/delete-context /openapi-docs.yaml delete /contexts/{context_id} Soft delete a context (marks inactive). # Get context Source: https://docs.trynia.ai/api-reference/context-sharing/get-context /openapi-docs.yaml get /contexts/{context_id} Retrieve a specific context by ID. # List contexts Source: https://docs.trynia.ai/api-reference/context-sharing/list-contexts /openapi-docs.yaml get /contexts List conversation contexts with pagination. Filter by tags, agent source, or memory type. # Save context Source: https://docs.trynia.ai/api-reference/context-sharing/save-context /openapi-docs.yaml post /contexts Save conversation context for cross-agent sharing. Indexed in vector store for semantic search. # Semantic search contexts Source: https://docs.trynia.ai/api-reference/context-sharing/semantic-search-contexts /openapi-docs.yaml get /contexts/semantic-search Vector + BM25 hybrid search over contexts. Returns relevance scores and highlights. # Text search contexts Source: https://docs.trynia.ai/api-reference/context-sharing/text-search-contexts /openapi-docs.yaml get /contexts/search Search contexts by content, title, summary, or tags using MongoDB text search. # Update context Source: https://docs.trynia.ai/api-reference/context-sharing/update-context /openapi-docs.yaml put /contexts/{context_id} Update an existing context. Re-indexes in vector store if content changes. # Analyze package manifest Source: https://docs.trynia.ai/api-reference/dependencies/analyze-package-manifest /openapi-docs.yaml post /dependencies/analyze Parse a package manifest and return dependency information with documentation URL mappings. This is a preview - no subscriptions are created. # Subscribe to documentation for manifest dependencies Source: https://docs.trynia.ai/api-reference/dependencies/subscribe-to-documentation-for-manifest-dependencies /openapi-docs.yaml post /dependencies/subscribe Parse a package manifest and automatically subscribe to documentation for all dependencies. # Upload manifest file and subscribe to dependencies Source: https://docs.trynia.ai/api-reference/dependencies/upload-manifest-file-and-subscribe-to-dependencies /openapi-docs.yaml post /dependencies/upload Upload a package manifest file and subscribe to documentation for all dependencies. # Create Tracer Job Source: https://docs.trynia.ai/api-reference/github-search/create-tracer-job /openapi-docs.yaml post /github/tracer Create a Tracer search job. Tracer is an autonomous agent that searches GitHub repositories to answer your question. Returns immediately with a job_id and session_id. Use /github/tracer/{job_id}/stream to receive real-time updates. # Delete Tracer Job Source: https://docs.trynia.ai/api-reference/github-search/delete-tracer-job /openapi-docs.yaml delete /github/tracer/{job_id} Delete a Tracer job by session_id or workflow_run_id. # Get Tracer Job Source: https://docs.trynia.ai/api-reference/github-search/get-tracer-job /openapi-docs.yaml get /github/tracer/{job_id} Get the status and result of a Tracer search job. # Github Code Search Source: https://docs.trynia.ai/api-reference/github-search/github-code-search /openapi-docs.yaml post /github/search Search code in a GitHub repository using GitHub's Code Search API. Rate limited to 10 requests/minute by GitHub. Requires authentication for private repos (via user's GitHub App installation). # Github Glob Source: https://docs.trynia.ai/api-reference/github-search/github-glob /openapi-docs.yaml post /github/glob Find files matching a glob pattern in a GitHub repository. # Github Read Source: https://docs.trynia.ai/api-reference/github-search/github-read /openapi-docs.yaml post /github/read Read a file from a GitHub repository with optional line range. # Github Tree Source: https://docs.trynia.ai/api-reference/github-search/github-tree /openapi-docs.yaml get /github/tree/{owner}/{repo} Get the file tree of a GitHub repository or subdirectory. # List Tracer Jobs Source: https://docs.trynia.ai/api-reference/github-search/list-tracer-jobs /openapi-docs.yaml get /github/tracer List Tracer jobs for the authenticated user. # Stream Tracer Job Source: https://docs.trynia.ai/api-reference/github-search/stream-tracer-job /openapi-docs.yaml get /github/tracer/{job_id}/stream Stream real-time updates from a Tracer search job. Uses Hatchet's native streaming with MongoDB fallback polling. Reconnectable: can reconnect to a running job's stream at any time. # Unified search Source: https://docs.trynia.ai/api-reference/search/unified-search /openapi-docs.yaml post /search Single search endpoint with a mode discriminator. # Create Source Source: https://docs.trynia.ai/api-reference/sources/create-source /openapi-docs.yaml post /sources # Create Source Annotation Source: https://docs.trynia.ai/api-reference/sources/create-source-annotation /openapi-docs.yaml post /sources/{source_id}/annotations # Delete Source Source: https://docs.trynia.ai/api-reference/sources/delete-source /openapi-docs.yaml delete /sources/{source_id} # Delete Source Annotation Source: https://docs.trynia.ai/api-reference/sources/delete-source-annotation /openapi-docs.yaml delete /sources/{source_id}/annotations/{annotation_id} # Explore Global Sources Source: https://docs.trynia.ai/api-reference/sources/explore-global-sources /openapi-docs.yaml get /sources/explore Browse the global catalog of publicly indexed sources. # Get PDF upload URL Source: https://docs.trynia.ai/api-reference/sources/get-pdf-upload-url /openapi-docs.yaml post /sources/upload-url Generate a signed URL for direct PDF upload. Use the returned gcs_path in POST /v2/sources. # Get Source Source: https://docs.trynia.ai/api-reference/sources/get-source /openapi-docs.yaml get /sources/{source_id} # Get Source Classification Source: https://docs.trynia.ai/api-reference/sources/get-source-classification /openapi-docs.yaml get /sources/{source_id}/classification # Get Source Content Source: https://docs.trynia.ai/api-reference/sources/get-source-content /openapi-docs.yaml get /sources/{source_id}/content # Get Source Curation Source: https://docs.trynia.ai/api-reference/sources/get-source-curation /openapi-docs.yaml get /sources/{source_id}/curation # Get Source Tree Source: https://docs.trynia.ai/api-reference/sources/get-source-tree /openapi-docs.yaml get /sources/{source_id}/tree # Grep Source Source: https://docs.trynia.ai/api-reference/sources/grep-source /openapi-docs.yaml post /sources/{source_id}/grep # List Source Annotations Source: https://docs.trynia.ai/api-reference/sources/list-source-annotations /openapi-docs.yaml get /sources/{source_id}/annotations # List Sources Source: https://docs.trynia.ai/api-reference/sources/list-sources /openapi-docs.yaml get /sources # Resolve Source Source: https://docs.trynia.ai/api-reference/sources/resolve-source /openapi-docs.yaml get /sources/resolve # Subscribe to a global source Source: https://docs.trynia.ai/api-reference/sources/subscribe-to-a-global-source /openapi-docs.yaml post /sources/subscribe Subscribe to an existing globally indexed public source. Creates a local reference for instant access without re-indexing. # Sync Source Source: https://docs.trynia.ai/api-reference/sources/sync-source /openapi-docs.yaml post /sources/{source_id}/sync # Update Source Source: https://docs.trynia.ai/api-reference/sources/update-source /openapi-docs.yaml patch /sources/{source_id} # Update Source Annotation Source: https://docs.trynia.ai/api-reference/sources/update-source-annotation /openapi-docs.yaml patch /sources/{source_id}/annotations/{annotation_id} # Update Source Classification Source: https://docs.trynia.ai/api-reference/sources/update-source-classification /openapi-docs.yaml patch /sources/{source_id}/classification # Update Source Curation Source: https://docs.trynia.ai/api-reference/sources/update-source-curation /openapi-docs.yaml put /sources/{source_id}/curation # Add Vault Source Source: https://docs.trynia.ai/api-reference/usage/add-vault-source /openapi-docs.yaml post /vaults/{vault_id}/sources Add a source to the vault's source_ids[]. Idempotent. # Browse Google Drive Items Source: https://docs.trynia.ai/api-reference/usage/browse-google-drive-items /openapi-docs.yaml get /google-drive/installations/{installation_id}/browse # Bulk delete resources Source: https://docs.trynia.ai/api-reference/usage/bulk-delete-resources /openapi-docs.yaml post /bulk-delete Delete multiple resources in a single request. Supports repositories, documentation, research papers, contexts, and local folders. # Cancel a running document agent job Source: https://docs.trynia.ai/api-reference/usage/cancel-a-running-document-agent-job /openapi-docs.yaml delete /document/agent/jobs/{job_id} # Cancel Oracle Job Source: https://docs.trynia.ai/api-reference/usage/cancel-oracle-job /openapi-docs.yaml delete /oracle/jobs/{job_id} Cancel a running or queued Oracle research job. Note: Cancellation is best-effort. The job may complete before cancellation takes effect. # Cancel Vault Workflow Source: https://docs.trynia.ai/api-reference/usage/cancel-vault-workflow /openapi-docs.yaml post /vaults/{vault_id}/cancel Cancel an in-flight vault workflow run, if any. # Check Status Source: https://docs.trynia.ai/api-reference/usage/check-status /openapi-docs.yaml get /shell-docs/status # Configure Slack Channels Source: https://docs.trynia.ai/api-reference/usage/configure-slack-channels /openapi-docs.yaml post /slack/installations/{installation_id}/channels Configure which channels to index. # Create Oracle Job Source: https://docs.trynia.ai/api-reference/usage/create-oracle-job /openapi-docs.yaml post /oracle/jobs Create a new Oracle research job. Returns immediately with job_id and session_id. Use /oracle/jobs/{job_id}/stream to receive real-time updates. Features: - Per-user concurrency limit: max 3 concurrent Oracle jobs - Job queuing: additional jobs wait in queue - 30-minute timeout per job # Create Vault Source: https://docs.trynia.ai/api-reference/usage/create-vault /openapi-docs.yaml post /vaults Create a new vault. Body: {display_name: str, description?: str, source_ids?: [str], schema_md?: str} Bootstraps the vault namespace with schema.md/index.md/log.md/META.md. Does NOT auto-trigger ingest — call POST /v2/vaults/{id}/run with mode=ingest after creation if you want immediate ingestion. # Create X Installation Source: https://docs.trynia.ai/api-reference/usage/create-x-installation /openapi-docs.yaml post /x/installations # Delete Google Drive Installation Source: https://docs.trynia.ai/api-reference/usage/delete-google-drive-installation /openapi-docs.yaml delete /google-drive/installations/{installation_id} # Delete Installation Source: https://docs.trynia.ai/api-reference/usage/delete-installation /openapi-docs.yaml delete /connectors/installations/{installation_id} Disconnect a connector installation. # Delete Oracle Session Source: https://docs.trynia.ai/api-reference/usage/delete-oracle-session /openapi-docs.yaml delete /oracle/sessions/{session_id} Delete an Oracle research session and its associated chat messages. # Delete Slack Installation Source: https://docs.trynia.ai/api-reference/usage/delete-slack-installation /openapi-docs.yaml delete /slack/installations/{installation_id} Disconnect a Slack workspace. # Delete Vault Source: https://docs.trynia.ai/api-reference/usage/delete-vault /openapi-docs.yaml delete /vaults/{vault_id} Delete a vault. Cleans up Postgres files AND TurboPuffer chunks. Order matters: drop TurboPuffer first, then PG, then Mongo. If any step fails before the Mongo delete, the vault row remains so the user can retry without losing accounting state. # Delete X Installation Source: https://docs.trynia.ai/api-reference/usage/delete-x-installation /openapi-docs.yaml delete /x/installations/{installation_id} # Enqueue an async document agent job Source: https://docs.trynia.ai/api-reference/usage/enqueue-an-async-document-agent-job /openapi-docs.yaml post /document/agent/jobs Create a long-running document agent job. Returns immediately with a `job_id` — use GET /document/agent/jobs/{job_id} to poll for the result or GET /document/agent/jobs/{job_id}/stream for live SSE updates. Recommended for production workloads, batch evaluation pipelines, or anything that may run longer than ~10 minutes. The job runs on a background worker pool with 30-minute hard timeout, per-user concurrency caps, and automatic refunds on failure. # Export Account Source: https://docs.trynia.ai/api-reference/usage/export-account /openapi-docs.yaml post /account/export # Fs Create Source: https://docs.trynia.ai/api-reference/usage/fs-create /openapi-docs.yaml post /fs Create a bare filesystem namespace. Returns a source_id you can immediately write to via /v2/fs/{source_id}/files. # Fs Delete Source: https://docs.trynia.ai/api-reference/usage/fs-delete /openapi-docs.yaml delete /fs/{source_id}/files # Fs Delete Namespace Source: https://docs.trynia.ai/api-reference/usage/fs-delete-namespace /openapi-docs.yaml delete /fs/{source_id}/namespace Delete a filesystem namespace and all its files. Only works for source_type=filesystem namespaces. # Fs Exec Source: https://docs.trynia.ai/api-reference/usage/fs-exec /openapi-docs.yaml post /fs/{source_id}/exec # Fs Find Source: https://docs.trynia.ai/api-reference/usage/fs-find /openapi-docs.yaml get /fs/{source_id}/find # Fs Get Metadata Source: https://docs.trynia.ai/api-reference/usage/fs-get-metadata /openapi-docs.yaml get /fs/{source_id}/metadata Get filesystem metadata + stats. # Fs Grep Source: https://docs.trynia.ai/api-reference/usage/fs-grep /openapi-docs.yaml post /fs/{source_id}/grep # Fs Info Source: https://docs.trynia.ai/api-reference/usage/fs-info /openapi-docs.yaml get /fs/{source_id}/info # Fs List Source: https://docs.trynia.ai/api-reference/usage/fs-list /openapi-docs.yaml get /fs List all filesystem namespaces owned by the caller. # Fs Ls Source: https://docs.trynia.ai/api-reference/usage/fs-ls /openapi-docs.yaml get /fs/{source_id}/ls # Fs Mkdir Source: https://docs.trynia.ai/api-reference/usage/fs-mkdir /openapi-docs.yaml post /fs/{source_id}/mkdir # Fs Mv Source: https://docs.trynia.ai/api-reference/usage/fs-mv /openapi-docs.yaml post /fs/{source_id}/mv # Fs Read Source: https://docs.trynia.ai/api-reference/usage/fs-read /openapi-docs.yaml get /fs/{source_id}/read # Fs Tree Source: https://docs.trynia.ai/api-reference/usage/fs-tree /openapi-docs.yaml get /fs/{source_id}/tree # Fs Write Source: https://docs.trynia.ai/api-reference/usage/fs-write /openapi-docs.yaml put /fs/{source_id}/files # Fs Write Batch Source: https://docs.trynia.ai/api-reference/usage/fs-write-batch /openapi-docs.yaml put /fs/{source_id}/files/batch # Generate Install Url Source: https://docs.trynia.ai/api-reference/usage/generate-install-url /openapi-docs.yaml post /google-drive/install # Generate Install Url Source: https://docs.trynia.ai/api-reference/usage/generate-install-url-1 /openapi-docs.yaml post /slack/install Generate a Slack OAuth authorization URL. # Get 1M Usage Source: https://docs.trynia.ai/api-reference/usage/get-1m-usage /openapi-docs.yaml get /oracle/1m-usage Get daily usage for 1M context window models. # Get Detect Extraction Source: https://docs.trynia.ai/api-reference/usage/get-detect-extraction /openapi-docs.yaml get /extract/detect/{extraction_id} # Get Detect Page Image Source: https://docs.trynia.ai/api-reference/usage/get-detect-page-image /openapi-docs.yaml get /extract/detect/{extraction_id}/page/{page_number}/image # Get Engineering Extraction Source: https://docs.trynia.ai/api-reference/usage/get-engineering-extraction /openapi-docs.yaml get /extract/engineering/{extraction_id} # Get Extraction Source: https://docs.trynia.ai/api-reference/usage/get-extraction /openapi-docs.yaml get /extract/{extraction_id} # Get Google Drive Index Status Source: https://docs.trynia.ai/api-reference/usage/get-google-drive-index-status /openapi-docs.yaml get /google-drive/installations/{installation_id}/status # Get Google Drive Installation Source: https://docs.trynia.ai/api-reference/usage/get-google-drive-installation /openapi-docs.yaml get /google-drive/installations/{installation_id} # Get Google Drive Selection Source: https://docs.trynia.ai/api-reference/usage/get-google-drive-selection /openapi-docs.yaml get /google-drive/installations/{installation_id}/selection # Get Installation Status Source: https://docs.trynia.ai/api-reference/usage/get-installation-status /openapi-docs.yaml get /connectors/installations/{installation_id}/status Get sync status and health for a connector installation. # Get Oracle Job Source: https://docs.trynia.ai/api-reference/usage/get-oracle-job /openapi-docs.yaml get /oracle/jobs/{job_id} Get the status and details of an Oracle research job. Returns full job details including result if completed. Includes fallback to check Hatchet state if job appears stuck in running state. # Get Oracle Session Detail Source: https://docs.trynia.ai/api-reference/usage/get-oracle-session-detail /openapi-docs.yaml get /oracle/sessions/{session_id} Retrieve the full details of a single Oracle research session. This is the new primary endpoint. The old /oracle/history/{session_id} endpoint is deprecated but still operational. # Get Oracle Session Messages Source: https://docs.trynia.ai/api-reference/usage/get-oracle-session-messages /openapi-docs.yaml get /oracle/sessions/{session_id}/messages Get chat messages for an Oracle research session. Returns the conversation history including the original query/report and any follow-up messages. # Get Slack Index Status Source: https://docs.trynia.ai/api-reference/usage/get-slack-index-status /openapi-docs.yaml get /slack/installations/{installation_id}/status Get the indexing status for a Slack workspace. # Get Slack Installation Source: https://docs.trynia.ai/api-reference/usage/get-slack-installation /openapi-docs.yaml get /slack/installations/{installation_id} Get details for a specific Slack installation. # Get sources summary Source: https://docs.trynia.ai/api-reference/usage/get-sources-summary /openapi-docs.yaml get /sources-summary Get counts and recent names for all source types. Designed for quick inventory checks. # Get the status / result of a document agent job Source: https://docs.trynia.ai/api-reference/usage/get-the-status-result-of-a-document-agent-job /openapi-docs.yaml get /document/agent/jobs/{job_id} # Get usage summary Source: https://docs.trynia.ai/api-reference/usage/get-usage-summary /openapi-docs.yaml get /usage Get usage counts and limits for current billing period (queries, indexing, oracle, etc.). # Get Vault Source: https://docs.trynia.ai/api-reference/usage/get-vault /openapi-docs.yaml get /vaults/{vault_id} Get vault metadata and current workflow status. # Get X Index Status Source: https://docs.trynia.ai/api-reference/usage/get-x-index-status /openapi-docs.yaml get /x/installations/{installation_id}/status # Get X Installation Source: https://docs.trynia.ai/api-reference/usage/get-x-installation /openapi-docs.yaml get /x/installations/{installation_id} # Grep package source Source: https://docs.trynia.ai/api-reference/usage/grep-package-source /openapi-docs.yaml post /packages/grep Regex search over public package source code (npm, PyPI, crates.io, Go modules). # Grep Slack Messages Source: https://docs.trynia.ai/api-reference/usage/grep-slack-messages /openapi-docs.yaml post /slack/installations/{installation_id}/grep BM25 keyword search over indexed Slack messages in TurboPuffer. # Handle Oauth Callback Source: https://docs.trynia.ai/api-reference/usage/handle-oauth-callback /openapi-docs.yaml post /google-drive/install/callback # Handle Oauth Callback Source: https://docs.trynia.ai/api-reference/usage/handle-oauth-callback-1 /openapi-docs.yaml post /slack/install/callback Exchange an OAuth code for tokens and create the installation. Called by the frontend callback route after the user authorizes the Slack app. # Import Account Source: https://docs.trynia.ai/api-reference/usage/import-account /openapi-docs.yaml post /account/import # Index Docs Source: https://docs.trynia.ai/api-reference/usage/index-docs /openapi-docs.yaml post /shell-docs/index # Index Installation Source: https://docs.trynia.ai/api-reference/usage/index-installation /openapi-docs.yaml post /connectors/installations/{installation_id}/index Trigger indexing for a connector installation. # Ingest Telemetry Source: https://docs.trynia.ai/api-reference/usage/ingest-telemetry /openapi-docs.yaml post /shell-docs/telemetry # Install Connector Source: https://docs.trynia.ai/api-reference/usage/install-connector /openapi-docs.yaml post /connectors/{connector_type}/install Install a connector — either store API key or initiate OAuth flow. # List async document agent jobs for the authenticated user Source: https://docs.trynia.ai/api-reference/usage/list-async-document-agent-jobs-for-the-authenticated-user /openapi-docs.yaml get /document/agent/jobs # List Available Connectors Source: https://docs.trynia.ai/api-reference/usage/list-available-connectors /openapi-docs.yaml get /connectors List all available connector types with their metadata. # List Available Sources Source: https://docs.trynia.ai/api-reference/usage/list-available-sources /openapi-docs.yaml get /vaults/available-sources Return every source the user can add to a vault. Merges data_sources (excluding vaults), local_folders, and projects into a single list with a unified shape so the frontend picker shows everything. # List Extractions Source: https://docs.trynia.ai/api-reference/usage/list-extractions /openapi-docs.yaml get /extractions # List Google Drive Installations Source: https://docs.trynia.ai/api-reference/usage/list-google-drive-installations /openapi-docs.yaml get /google-drive/installations # List Installations Source: https://docs.trynia.ai/api-reference/usage/list-installations /openapi-docs.yaml get /connectors/installations List all connector installations for the current user/org. # List Oracle Jobs Source: https://docs.trynia.ai/api-reference/usage/list-oracle-jobs /openapi-docs.yaml get /oracle/jobs List Oracle research jobs for the authenticated user. Returns jobs ordered by creation time (newest first). # List Oracle Sessions Source: https://docs.trynia.ai/api-reference/usage/list-oracle-sessions /openapi-docs.yaml get /oracle/sessions List Oracle research sessions for the authenticated API key. This is the new primary endpoint. The old /oracle/history endpoint is deprecated but still operational. # List Slack Channels Source: https://docs.trynia.ai/api-reference/usage/list-slack-channels /openapi-docs.yaml get /slack/installations/{installation_id}/channels List available Slack channels from the workspace. # List Slack Installations Source: https://docs.trynia.ai/api-reference/usage/list-slack-installations /openapi-docs.yaml get /slack/installations List all Slack workspace connections for the authenticated user/org. # List Vault Sources Source: https://docs.trynia.ai/api-reference/usage/list-vault-sources /openapi-docs.yaml get /vaults/{vault_id}/sources List the source IDs currently linked to this vault, with metadata. # List Vaults Source: https://docs.trynia.ai/api-reference/usage/list-vaults /openapi-docs.yaml get /vaults List vaults owned by the calling user / org. # List X Installations Source: https://docs.trynia.ai/api-reference/usage/list-x-installations /openapi-docs.yaml get /x/installations # Load Vault Source: https://docs.trynia.ai/api-reference/usage/load-vault /openapi-docs.yaml get /vaults/{vault_id}/load Bootstrap dump for the `nia vault open` bash session. Mirrors the shape of /shell-docs/load. Returns vault metadata and either full file contents or just paths (for vaults > 1000 files). Up to 10000 files are returned (matches DIR_LISTING_LIMIT in fs_service.py). # Oauth Callback Source: https://docs.trynia.ai/api-reference/usage/oauth-callback /openapi-docs.yaml get /connectors/{connector_type}/oauth/callback Handle OAuth callback — exchange code, create installation, redirect to frontend. # Oracle Research Source: https://docs.trynia.ai/api-reference/usage/oracle-research /openapi-docs.yaml post /oracle Run Oracle research and return complete result (non-streaming). # Patch Vault Source: https://docs.trynia.ai/api-reference/usage/patch-vault /openapi-docs.yaml patch /vaults/{vault_id} Update vault metadata (display_name, description, schema_md). When schema_md is updated, the new content is also written into the vault namespace as `/schema.md` so the bash session sees it immediately. # Query document(s) with an AI agent (synchronous) Source: https://docs.trynia.ai/api-reference/usage/query-documents-with-an-ai-agent-synchronous /openapi-docs.yaml post /document/agent Run the full document agent against one or more indexed PDFs or documents. The agent uses tools (search, read sections, read pages) to research the document(s) and produce a comprehensive answer with citations. Supports optional structured output via json_schema. **This endpoint is synchronous and holds the HTTP connection for the entire agent run (typically 1-10 minutes).** For production workloads or anything that may run longer, use POST /document/agent/jobs instead — it returns a job_id immediately and lets you poll or stream results without an HTTP connection limit. # Query Engineering Extraction Source: https://docs.trynia.ai/api-reference/usage/query-engineering-extraction /openapi-docs.yaml post /extract/engineering/{extraction_id}/query # Read package file Source: https://docs.trynia.ai/api-reference/usage/read-package-file /openapi-docs.yaml post /packages/read Read specific lines from a package source file. Max 200 lines per request. # Read Slack Messages Source: https://docs.trynia.ai/api-reference/usage/read-slack-messages /openapi-docs.yaml get /slack/installations/{installation_id}/messages Read recent messages from a Slack channel (live from Slack API). # Register External Token Source: https://docs.trynia.ai/api-reference/usage/register-external-token /openapi-docs.yaml post /slack/install/token Register an external Slack bot token (BYOT). For multi-tenant scenarios: your customers provide their Slack bot token and you manage it through Nia's API. # Remove Vault Source Source: https://docs.trynia.ai/api-reference/usage/remove-vault-source /openapi-docs.yaml delete /vaults/{vault_id}/sources/{source_id} Remove a source from the vault's source_ids[]. Idempotent. # Run Vault Workflow Source: https://docs.trynia.ai/api-reference/usage/run-vault-workflow /openapi-docs.yaml post /vaults/{vault_id}/run Trigger a vault_workflow run. Body: {mode: ingest|sync|lint|refresh, source_ids?: [], model?: str, force?: bool} # Search Vault Source: https://docs.trynia.ai/api-reference/usage/search-vault /openapi-docs.yaml post /vaults/{vault_id}/search Hybrid search scoped to this vault's namespace. Returns embedded vault pages as ranked results with citations. The vault namespace was populated by the existing `fs_sync_workflow` mirroring every write into TurboPuffer (see routes/v2/fs.py:294-313). Telemetry: emits both `store_api_activity` (for the user-facing activity feed) and `store_retrieval_log` (for the training-data pipeline) so vault searches show up alongside every other retrieval call. Two retrieval logs are written for the two-tier strategy: a `vector` log for the TurboPuffer path, and a `regex` log if the PG grep fallback fires. # Semantic package search Source: https://docs.trynia.ai/api-reference/usage/semantic-package-search /openapi-docs.yaml post /packages/search Hybrid semantic + keyword search over package source. 1-5 natural language queries. # Shell Docs Dump Source: https://docs.trynia.ai/api-reference/usage/shell-docs-dump /openapi-docs.yaml get /shell-docs/{namespace}/dump # Shell Docs Find Source: https://docs.trynia.ai/api-reference/usage/shell-docs-find /openapi-docs.yaml get /shell-docs/{namespace}/find # Shell Docs Grep Source: https://docs.trynia.ai/api-reference/usage/shell-docs-grep /openapi-docs.yaml post /shell-docs/{namespace}/grep # Shell Docs Info Source: https://docs.trynia.ai/api-reference/usage/shell-docs-info /openapi-docs.yaml get /shell-docs/{namespace}/info # Shell Docs Load Source: https://docs.trynia.ai/api-reference/usage/shell-docs-load /openapi-docs.yaml get /shell-docs/load Combined status + dump in one request. Returns status info + files if indexed. # Shell Docs Ls Source: https://docs.trynia.ai/api-reference/usage/shell-docs-ls /openapi-docs.yaml get /shell-docs/{namespace}/ls # Shell Docs Read Source: https://docs.trynia.ai/api-reference/usage/shell-docs-read /openapi-docs.yaml get /shell-docs/{namespace}/read # Shell Docs Tree Source: https://docs.trynia.ai/api-reference/usage/shell-docs-tree /openapi-docs.yaml get /shell-docs/{namespace}/tree # Start Detect Extraction Source: https://docs.trynia.ai/api-reference/usage/start-detect-extraction /openapi-docs.yaml post /extract/detect # Start Engineering Extraction Source: https://docs.trynia.ai/api-reference/usage/start-engineering-extraction /openapi-docs.yaml post /extract/engineering # Start Extraction Source: https://docs.trynia.ai/api-reference/usage/start-extraction /openapi-docs.yaml post /extract # Stream live updates from a document agent job (SSE) Source: https://docs.trynia.ai/api-reference/usage/stream-live-updates-from-a-document-agent-job-sse /openapi-docs.yaml get /document/agent/jobs/{job_id}/stream # Stream Oracle Job Source: https://docs.trynia.ai/api-reference/usage/stream-oracle-job /openapi-docs.yaml get /oracle/jobs/{job_id}/stream Stream real-time updates from an Oracle research job. Uses Hatchet's native streaming - no Redis required. Reconnectable: can reconnect to a running job's stream at any time. # Stream Oracle Session Chat Source: https://docs.trynia.ai/api-reference/usage/stream-oracle-session-chat /openapi-docs.yaml post /oracle/sessions/{session_id}/chat/stream Stream a follow-up chat response for an Oracle research session. The response is generated as grounded Q&A based on: - The original research report - Citations and sources discovered during research - Previous chat messages in the session This is a lightweight chat mode (not a full Oracle research run). # Submit Answer Feedback Source: https://docs.trynia.ai/api-reference/usage/submit-answer-feedback /openapi-docs.yaml post /feedback/answer Explicit thumbs up/down on an assistant answer. # Submit Source Feedback Source: https://docs.trynia.ai/api-reference/usage/submit-source-feedback /openapi-docs.yaml post /feedback/source Per-source helpful/irrelevant/partially_relevant feedback. # Submit Source Interaction Source: https://docs.trynia.ai/api-reference/usage/submit-source-interaction /openapi-docs.yaml post /feedback/interaction Implicit interaction events (copy, expand, dwell, click-through). # Trigger Google Drive Index Source: https://docs.trynia.ai/api-reference/usage/trigger-google-drive-index /openapi-docs.yaml post /google-drive/installations/{installation_id}/index # Trigger Google Drive Sync Source: https://docs.trynia.ai/api-reference/usage/trigger-google-drive-sync /openapi-docs.yaml post /google-drive/installations/{installation_id}/sync # Trigger Slack Index Source: https://docs.trynia.ai/api-reference/usage/trigger-slack-index /openapi-docs.yaml post /slack/installations/{installation_id}/index Trigger a full re-index of the Slack workspace. # Trigger X Index Source: https://docs.trynia.ai/api-reference/usage/trigger-x-index /openapi-docs.yaml post /x/installations/{installation_id}/index # Update Google Drive Selection Source: https://docs.trynia.ai/api-reference/usage/update-google-drive-selection /openapi-docs.yaml post /google-drive/installations/{installation_id}/selection # Update Schedule Source: https://docs.trynia.ai/api-reference/usage/update-schedule /openapi-docs.yaml patch /connectors/installations/{installation_id}/schedule Update sync schedule for a connector installation. # Vault Agent Source: https://docs.trynia.ai/api-reference/usage/vault-agent /openapi-docs.yaml post /vaults/{vault_id}/agent Stream an AI agent response that can search/read the vault. Returns an SSE stream of events (same shape as the document agent). Charges one QUERY credit per call; refunds on failure. # Vault Graph Source: https://docs.trynia.ai/api-reference/usage/vault-graph /openapi-docs.yaml get /vaults/{vault_id}/graph Return the wikilink graph as nodes + edges for visualization. Walks all concept/entity/note pages, parses [[wikilinks]], and builds a force-directed-ready JSON structure. No LLM calls — pure file parsing. # Nia Capabilities Source: https://docs.trynia.ai/capabilities The complete reference of every capability Nia provides — indexing, search, research, extraction, sync, context sharing, encryption, integrations, and more. This page is the single, exhaustive reference of **everything Nia can do**. If you are an AI agent or a human evaluating Nia, start here. Each capability links to a deep-dive page with API and CLI usage. **What is Nia?** Nia is an API layer that gives agents up-to-date, continuously monitored context across repositories, documentation, PDFs, datasets, spreadsheets, Slack, Google Drive, X/Twitter, generic connectors, and local knowledge sources. It handles indexing, search, reading, research, extraction, and handoffs so coding agents can work from real source material instead of guesswork. Use it via CLI, MCP, SDKs, agent skills, plugins, or the REST API. ```bash theme={null} npx nia-wizard@latest ``` Creates an account, generates an API key, auto-detects your IDE. Sign up at app.trynia.ai. Free plan included. `https://apigcp.trynia.ai/v2` Auth: `Authorization: Bearer YOUR_API_KEY` Already know your input (code, PDFs, Slack, Drive)? Start with [Source Types](/source-types). *** ## Capability Map Every Nia capability falls into one of these categories: | Category | What it does | | --------------------------------------------------------------- | ------------------------------------------------------------------------------- | | **[Indexing & Subscriptions](#1-indexing--subscriptions)** | Bring any source into Nia and keep it fresh | | **[Search, Read & Explore](#2-search-read--explore)** | Semantic, regex, and structural retrieval across everything indexed | | **[Research Agents](#3-research-agents)** | Autonomous multi-step investigations across code, docs, and the web | | **[Document Agent](#4-document-agent)** | Deploy a tool-using agent into a single PDF or document | | **[Data Extraction](#5-data-extraction)** | Pull structured records, visual elements, and engineering data from PDFs | | **[Vault](#6-vault--agent-maintained-personal-wiki)** | Agent-maintained personal wiki layered on top of your indexed sources | | **[Context Sharing](#7-context-sharing)** | Save plans and conversation state for cross-agent handoffs | | **[Local Sync](#8-local-sync)** | Continuously sync local folders, databases, and chat history | | **[End-to-End Encryption](#9-end-to-end-encryption)** | Zero-knowledge sync for personal data — plaintext never leaves your device | | **[Connectors](#10-connectors)** | Generic framework for OAuth/API-key external sources (Notion, Confluence, Jira) | | **[Scoped MCP Servers](#11-scoped-mcp-servers)** | Specialized MCP servers focused on one source | | **[Sandbox Search](#12-sandbox-search)** | Clone a public Git URL into an ephemeral VM and run a read-only agent | | **[Tracer](#13-tracer-github-search-without-indexing)** | GitHub search agent with parallel sub-agents, no indexing required | | **[Package Search](#14-package-search)** | Search PyPI, npm, Crates.io, Go modules, Ruby Gems without indexing | | **[Source Types](#15-supported-source-types)** | Every input format Nia understands | | **[Explore & Chat](#16-explore--chat)** | Web UI for cross-source Q\&A across pre-indexed knowledge | | **[agentsearch](#17-agentsearch-zero-install-docs-filesystem)** | One-command Unix filesystem over any docs site, zero account | | **[Installation Methods](#18-installation-methods)** | CLI, MCP server, agent skill, plugins, agentsearch | | **[SDKs](#19-sdks-and-language-bindings)** | Python, TypeScript, LangChain | | **[Agent Onboarding](#20-agent-onboarding-api-first)** | Headless signup, verify, and skill install for autonomous agents | | **[Plans, Pricing & Limits](#21-plans-pricing--limits)** | Free → Builder → Team → Business → Enterprise + credit packs | | **[Privacy & Security](#22-privacy--security)** | SOC 2, E2E encryption, opt-out of training, secure storage | *** ## 1. Indexing & Subscriptions Bring knowledge into Nia from any source type. One universal `index` tool auto-detects what you give it. ### `index` (universal entry point) Auto-detects: | Input | Detected as | | ---------------------------------------- | ---------------------- | | GitHub URLs | Repositories | | arXiv URLs / paper IDs / direct PDF URLs | PDFs / research papers | | HuggingFace dataset URLs | Datasets | | `.csv`, `.tsv`, `.xlsx`, `.xls` files | Spreadsheets | | Local paths | Local folders | | Other web URLs | Documentation | Typical prompts: ```text theme={null} "Index https://github.com/vercel/ai" "Index https://docs.anthropic.com" "Index https://arxiv.org/abs/2401.12345" "Index https://huggingface.co/datasets/openai/gsm8k" "Index ./my-local-project" ``` ### `auto_subscribe_dependencies` Parses a manifest — `package.json`, `requirements.txt`, `pyproject.toml`, `Cargo.toml`, `go.mod` — then subscribes to or indexes related documentation sources automatically. Best for spinning up a project knowledge base from an existing repo. ### `manage_resource` Single tool for resource lifecycle: | Action | Description | | ----------- | --------------------------------------------------- | | `list` | List indexed resources, optionally filtered by type | | `status` | Get sync/index status of a resource | | `rename` | Rename a resource | | `delete` | Remove a resource | | `subscribe` | Subscribe to an existing pre-indexed source | ### Pre-indexed (community) sources Skip indexing entirely by subscribing to sources others have already indexed. Browse Global Sources at [app.trynia.ai](https://app.trynia.ai). Popular examples include Chromium, React, Next.js, FastAPI, the Vercel AI SDK, and LangChain. Subscribing is instant and does **not** count against your indexing quota. ### Branch / ref selection Repos accept `branch`, `ref`, `tag`, or commit SHA where applicable. ### Global source deduplication If someone has already indexed an upstream source, you can subscribe instantly. Set `add_as_global_source=False` to keep an indexed source private. → Deep dive: [Pre-indexed Sources](/pre-indexed-sources) *** ## 2. Search, Read & Explore Once content is indexed, query it with semantic, lexical, or structural retrieval. ### `search` — semantic search Hybrid (vector + BM25) semantic search across **all indexed source types**: repositories, docs, papers, datasets, spreadsheets, Google Drive, Slack, X, local folders, connectors, and more. Supports streaming responses, multi-source queries, and source-specific filters (`repositories`, `data_sources`, `slack_workspaces`, `local_folders`, `connector_installations`, `e2e_session_id`). ### `nia_grep` — regex search Regex pattern matching across repositories, documentation, packages, Google Drive sources, local folders, datasets, and Slack. Supports context lines, case sensitivity, path scoping, and result limits. ### `nia_read` Read files, pages, or rows from any indexed source — repositories, documentation, packages, Google Drive sources, local folders, HuggingFace datasets, Slack channels. Supports line ranges and path-based addressing. ### `nia_explore` Browse the structure of any indexed source: file trees, directory listings, dataset schemas, Slack channel listings. ### `get_github_file_tree` Inspect a public GitHub repository structure live — without indexing it first. ### Universal search modes The unified `/search` endpoint supports four modes via a `mode` discriminator: | Mode | Use for | | ----------- | ---------------------------------------------------------- | | `query` | Multi-source AI search with conversation messages | | `universal` | Vector + BM25 across all indexed sources, no LLM synthesis | | `web` | Web search with category and date filtering | | `deep` | Multi-step deep research with citations | → Deep dive: [API Guide](/api-guide) *** ## 3. Research Agents Autonomous agents that plan, call tools, and synthesize answers across many sources. ### `nia_research` — three modes | Mode | Best for | | -------- | ---------------------------------------------------------- | | `quick` | Fast web search and quick source discovery | | `deep` | Comparisons, evaluations, and multi-source analysis | | `oracle` | Complex multi-step investigations with autonomous research | ### `nia_advisor` Analyzes **your** code against indexed documentation to produce grounded recommendations. Pass a code snippet plus the docs you want it checked against. ### Oracle Research Agent Autonomous research assistant for deep technical investigations across codebases, documentation, and the web. Three-phase pattern (DISCOVER → INDEX → SEARCH) with progressive tool usage. **Capabilities:** * Web search (`nia_web_search`), code search, documentation search * Doc filesystem tools: `doc_tree`, `doc_ls`, `doc_read`, `doc_grep` * Package source code analysis (PyPI, npm, Crates.io, Go modules) * Auto-indexes discovered sources during research * Real-time SSE streaming with iteration events, tool events, and final report * Job-based execution with retry and reconnection * Chat with results via `/v2/oracle/sessions/{session_id}/chat` * Session history and message retrieval **Endpoints:** * `POST /v2/oracle` — direct streaming * `POST /v2/oracle/jobs` — job-based (recommended) * `GET /v2/oracle/jobs/{job_id}/stream` — SSE * `GET /v2/oracle/jobs/{job_id}` — status * `GET /v2/oracle/history` — past sessions → Deep dive: [Oracle Research Agent](/oracle-research) ### Tracer (covered separately below) Live GitHub search agent that delegates to parallel sub-agents — see [section 13](#13-tracer-github-search-without-indexing). *** ## 4. Document Agent Deploy an autonomous AI agent **into a specific PDF or document**. Unlike standard search (single-pass retrieval), Document Agent plans its strategy, calls tools (search, read sections, read pages, navigate trees), follows cross-references, and synthesizes a cited answer. ### Key features | Feature | Description | | ------------------- | ------------------------------------------------------------------------- | | Inline citations | Page-, section-, and content-level citations on every claim | | Structured output | Provide a `json_schema` and receive typed extraction matching it | | Extended thinking | Configurable `thinking_budget` (1,000 – 50,000 tokens) for deep reasoning | | Streaming | SSE event stream so you can render progress in real time | | Model selection | Opus 4.7 (1M context), Sonnet, or Haiku | | Autonomous tool use | Plans research strategy itself; calls tools in a loop | ### Models | Model | Context | Best for | | -------------------------- | --------- | ------------------------------------- | | `claude-opus-4-7` | 1M tokens | Complex reasoning over long documents | | `claude-sonnet-4-20250514` | 200K | Balanced performance | | `claude-haiku-35-20241022` | 200K | Quick lookups, high-volume processing | ### Endpoint `POST /v2/document/agent` — query an indexed document with optional schema, thinking budget, and streaming flag. ### Use cases Legal contracts, SEC filings (10-K/10-Q), technical manuals, research papers, audit reports, compliance checklists. → Deep dive: [Document Agent](/document-agent) *** ## 5. Data Extraction Three modes for pulling structured data out of PDFs. ### Table extraction Provide a JSON schema; Nia returns an array of records matching the schema. Ideal for SEC filings, invoices, product catalogs, line items. `POST /v2/extract` — start job `GET /v2/extract/{id}` — poll status ### Detect extraction Detect and locate visual elements — tables, figures, charts, diagrams — in PDF pages. Returns bounding boxes, classifications, and confidence scores. Optional symbol-level detection and pattern filters. Can render annotated page images via `/v2/extract/detect/{id}/page/{n}/image`. `POST /v2/extract/detect` `GET /v2/extract/detect/{id}` ### Engineering extraction Purpose-built for technical documents — engineering drawings, P\&IDs, schematics, datasheets, construction specs. Includes `accuracy_mode` (`fast` or `precise`) and **follow-up queries** that reuse the already-extracted context without re-processing. `POST /v2/extract/engineering` `POST /v2/extract/engineering/{id}/query` — ask follow-ups `GET /v2/extract/engineering/{id}` ### Job lifecycle `queued` → `processing` → `completed` | `failed` ### Listing `GET /v2/extractions?type=table|detect|engineering` lists all your extraction jobs. → Deep dive: [Data Extraction](/data-extraction) *** ## 6. Vault — Agent-Maintained Personal Wiki Vault is an agent-maintained personal wiki layered on top of your indexed Nia sources. Instead of searching raw documents every time, the agent reads sources once and compiles them into a structured, interlinked markdown wiki that gets smarter over time. ### Three layers 1. **Raw sources** — your indexed Nia sources (read-only) 2. **The wiki** — markdown pages the agent generates and owns 3. **The schema** — `schema.md` you and the agent co-evolve ### Page structure Each page has a **Compiled Truth** (above `---`, rewritten when evidence changes) and a **Timeline** (below `---`, append-only evidence trail). Cross-references use `[[wikilinks]]` with optional typed relationships (`uses`, `extends`, `works_at`, `contradicts`, etc.). ### Workflows | Command | What it does | | ------------------------------------------- | --------------------------------------------------------------------------------- | | `nia vault init "Name" --from-source ` | Create a vault and trigger first ingest | | `nia vault ingest ` | Synthesize pages for new sources only | | `nia vault ingest --force` | Re-synthesize all sources | | `nia vault sync ` | Regenerate pages whose sources changed | | `nia vault refresh ` | Combined ingest + sync | | `nia vault lint ` | Find orphan pages, broken wikilinks, contradictions | | `nia vault dream ` | Self-improvement loop: discover entities, find connections, detect contradictions | | `nia vault auto-dream on` | Weekly automatic dream (Sundays 3am UTC) | | `nia vault open ` | Drop into a writable bash shell with the vault mounted | | `nia vault open --c "tree"` | One-shot command (for agent tool loops) | | `nia vault search "query"` | Hybrid semantic + keyword search inside the vault | | `nia vault cancel ` | Cancel a stuck workflow | | `nia vault agents ` | Append agent setup instructions to `CLAUDE.md` / `AGENTS.md` | | `nia vault skill ` | Generate a skill file for the vault | | `nia vault setup ` | Pipe a guided setup prompt into your agent | ### Layout ``` schema.md / index.md / log.md / META.md concepts/ # LLM-generated concept pages entities/ # LLM-generated entity pages (people, products, tools, papers) notes/ # User-curated freeform pages (always protected from sync) lint-report.md dream-report.md ``` ### Web UI at `app.trynia.ai/vaults` * Page tree sidebar * Force-directed graph view (color-coded by relationship type) * TipTap rich editor with wikilink autocomplete * `Cmd+K` search palette with fuzzy + AI-powered Q\&A * Dream/sync controls * Settings: auto-sync, auto-dream, schema editor ### Personal data sources via Local Sync iMessage, WhatsApp, Apple Notes, Contacts, Reminders, Stickies, Screenshots, plus 47+ cloud connectors. ### Provenance protection `provenance.last_human_edit` ensures user-edited files are never overwritten by background workflows. → Deep dive: [Vault](/vault) *** ## 7. Context Sharing Save entire conversation histories — code snippets, plans, decisions, referenced sources, edited files — and re-open them in another agent. Plan with Cursor, continue execution in Claude Code. ### Unified `context` tool | Action | Description | | ---------- | ----------------------------------------------------------------------- | | `save` | Save conversation with title, summary, content, tags, and edited files | | `list` | List saved contexts with filtering (workspace, directory, file overlap) | | `retrieve` | Pull full context by ID | | `search` | Keyword search across title, summary, content, tags | | `update` | Update title, summary, content, tags, or metadata | | `delete` | Remove contexts when done | ### Memory types | Type | Use for | | ------------ | -------------------------- | | `scratchpad` | Short-lived working memory | | `episodic` | Session-level continuity | | `fact` | Persistent facts | | `procedural` | Reusable how-to knowledge | ### What gets captured when you save Conversation history, code snippets and edited files, plans and decisions, referenced sources, every Nia search and query made. ### Endpoints `POST /v2/contexts` (save), plus list/get/update/delete and semantic search. → Deep dive: [Context Sharing](/context-sharing) *** ## 8. Local Sync Standalone CLI daemon (`nia`) that continuously synchronizes local data sources with Nia, enabling agents to search your personal knowledge base. ### Quickstart ```bash theme={null} nia login nia add ~/Documents/notes nia # start daemon nia status ``` ### Core CLI commands | Command | Description | | ---------------------- | ------------------------------------------------------ | | `nia` | Start sync daemon (real-time file watching by default) | | `nia login / logout` | Browser-based OAuth | | `nia status [--json]` | Show all configured sources | | `nia once` | One-time sync then exit | | `nia add ` | Add a new source | | `nia link ` | Link a cloud source to a local path | | `nia remove ` | Remove source | | `nia upgrade` | Check and install updates | ### Search from the terminal ```bash theme={null} nia search "meeting notes from last week" nia search "project updates" --local-folder my-notes --local-folder work-docs nia search "config values" --json --no-stream ``` Flags include `--local-folder`, `--sources`, `--markdown/--no-markdown`, `--stream/--no-stream`, `--json`, `--limit`. ### Monitoring & debugging | Command | Description | | ------------------------------------- | ---------------------------------------------- | | `nia info ` | Detailed info (chunk count, last sync, errors) | | `nia logs [] [--tail] [--errors]` | Sync logs | | `nia diff []` | Dry-run: show what would sync | | `nia doctor` | Diagnostics for auth, API, disk access | | `nia whoami` | Current user | | `nia version [--check]` | CLI version / update check | ### Sync control `nia pause `, `nia resume `, `nia resync `, `nia resync --all`. ### Web integration ```bash theme={null} nia open dashboard | activity | local-sync | api-keys | billing | docs | ``` ### Configuration `nia config list / get / set` for settings. `nia ignore add --dir|--file|--ext|--path` for ignore patterns. `nia watch add ~/Projects` to auto-discover new folders matching unlinked sources. ### Source ID shortcuts ID prefixes (`nia info a3f2`) and display names (`nia pause "My Notes"`) work everywhere. ### Daemon flags `--watch/--poll`, `-f, --fallback ` (default 600), `-r, --refresh ` (default 30). ### Supported data sources | Category | Sources | | --------------- | ---------------------------------------------------------------- | | Chat & messages | iMessage, WhatsApp, Telegram | | Apple ecosystem | Apple Notes, Contacts, Reminders, macOS Stickies | | Browser history | Safari, Chrome, Brave, Edge, Firefox | | Media & files | Screenshots (with optional OCR), generic SQLite, regular folders | ### Virtual file paths Database content extracted into virtual text files for semantic search, e.g.: | Source | Path format | | ----------- | ---------------------------------------------------- | | iMessage | `messages/{contact}/{date}_{row_id}_{direction}.txt` | | WhatsApp | `whatsapp/{contact}/{date}_{msg_id}.txt` | | Browsers | `history/{domain}/{date}_{id}.txt` | | Apple Notes | `notes/{folder}/{title}_{id}.txt` | ### Sync intervals Configurable per source: `5m`, `hourly`, `6h`, `daily`. ### Limits | Limit | Value | | -------------------- | ----------------- | | Files per folder | 5,000 | | Total upload size | 100 MB per folder | | Individual file size | 5 MB | | Database size | 1 GB | | Rows per table | 100,000 | ### Security **350+ exclusion patterns** automatically protect: `.env`, `.pem`, `.key`, SSH keys, `*credentials*`, `*secrets*`, `*token*`, `.git`, `.svn`, `node_modules`, `venv`, `__pycache__`, `dist/`, `build/`, `.next/`. Credentials stored locally with `0600` permissions. → Deep dive: [Local Sync](/local-sync) *** ## 9. End-to-End Encryption **Zero-knowledge sync** for personal data sources. Plaintext never leaves your device — Nia stores only encrypted vectors and ciphertext. ### Pipeline ``` Desktop: Extract → Chunk → Embed (zembed-1-2560) → Encrypt (AES-256-GCM) → Blind Index (HMAC-SHA256) → Upload Cloud: Store ciphertext + vectors; never sees plaintext Agent: Query with e2e_session_id; decrypts via desktop bridge ``` ### Supported sources | Source | Adapter | Backing store | | --------------- | ---------------- | ---------------------------- | | iMessage | `imessage.ts` | SQLite `chat.db` | | WhatsApp | `whatsapp.ts` | SQLite `ChatStorage.sqlite` | | Apple Notes | `notes.ts` | SQLite `NoteStore.sqlite` | | Apple Contacts | `contacts.ts` | AddressBook / vCard | | macOS Stickies | `stickies.ts` | Stickies DB / plist | | Apple Reminders | `reminders.ts` | SQLite | | Screenshots | `screenshots.ts` | Metadata + optional OCR text | All adapters live in `sdk/typescript/src/local-first/`. You can add your own. ### Key concepts * **Encryption key** — passphrase-derived (PBKDF2 → AES-256-GCM), stored in macOS Keychain. Never sent to server. * **Blind index key** — separately derived; produces HMAC-SHA256 tokens for keywords, contact hashes, conversation hashes. Lets the server filter encrypted results without seeing plaintext. * **Embedding profile** — `zembed-1-2560` (2560 dims), client-side, so query and document embeddings match. * **Decrypt sessions** — temporary scoped sessions with TTL, max chunks, and allowed operations. Agent never holds the encryption key. ### Sync modes | Mode | Description | | -------------------- | ---------------------------------------------------------- | | `server_indexed` | Default. Server sees plaintext (used for code, docs, etc.) | | `e2e_client_indexed` | Zero-knowledge. Client encrypts and embeds before upload | ### Endpoints ``` POST /v2/daemon/e2e/sync POST /v2/daemon/e2e/sessions # create scoped decrypt session GET /v2/daemon/e2e/sessions/{id} # session status POST /v2/daemon/e2e/decrypt # retrieve ciphertext for decryption GET /v2/daemon/e2e/sources/{id}/usage DELETE /v2/daemon/e2e/sources/{id}/data # purge encrypted data ``` ### Querying encrypted data Standard `/v2/search/query` endpoint with `e2e_session_id` parameter — desktop bridge handles decryption within session bounds. ### Demo Open-source iMessage demo: [`nia-imessage-app-demo`](https://github.com/nozomio-labs/nia-imessage-app-demo). → Deep dive: [End-to-End Encryption](/e2e-encryption) *** ## 10. Connectors Generic framework for integrating external data sources with OAuth and API key authentication, scheduled syncing, and status monitoring. One API contract for every connector type. ### Lifecycle `Discover → Install → Configure → Index → Search` ### Auth methods | Method | How | | --------- | ---------------------------------------------------------------------- | | `api_key` | Pass the API key directly during installation | | `oauth` | Nia returns an authorization URL; OAuth callback handled automatically | ### Endpoints | Method | Endpoint | Purpose | | -------- | -------------------------------------------- | --------------------------------- | | `GET` | `/v2/connectors` | List available connector types | | `POST` | `/v2/connectors/{type}/install` | Install (API key or OAuth) | | `GET` | `/v2/connectors/{type}/oauth/callback` | OAuth callback | | `GET` | `/v2/connectors/installations` | List installations | | `DELETE` | `/v2/connectors/installations/{id}` | Disconnect (removes indexed data) | | `POST` | `/v2/connectors/installations/{id}/index` | Trigger indexing | | `PATCH` | `/v2/connectors/installations/{id}/schedule` | Update cron schedule | | `GET` | `/v2/connectors/installations/{id}/status` | Sync status | ### Status values `idle | processing | completed | failed` ### Scheduling Standard cron expressions, e.g.: | Cron | Frequency | | ------------- | ------------------- | | `0 */6 * * *` | Every 6 hours | | `0 0 * * *` | Daily at midnight | | `0 9 * * 1` | Weekly Mondays 9 AM | | `0 */1 * * *` | Hourly | Set `schedule: null` to disable; manual sync still available. ### Searching connector data Indexed connector data appears in the unified `/v2/search/query` endpoint. Filter to specific installations via `connector_installations`. ### Multi-instance support Install the same connector type multiple times (e.g. multiple Confluence instances or Notion workspaces) — each installation is independent. → Deep dive: [Connectors](/connectors) *** ## 11. Scoped MCP Servers Don't want a general-purpose MCP with dozens of tools? Generate a scoped MCP server focused on **one specific source** — one framework, one docs site, one paper. Reduces tool clutter and context noise. ### How it works 1. Pick any pre-indexed source from Global Sources at [app.trynia.ai](https://app.trynia.ai) 2. Click "Create Scoped MCP" — Nia generates a dedicated config 3. Add the config to your IDE ### Example config ```json theme={null} { "mcpServers": { "nia-sdk-vercel-ai": { "url": "https://apigcp.trynia.ai/mcp?source=https%3A%2F%2Fsdk.vercel.ai%2Fdocs", "headers": { "Authorization": "Bearer YOUR_API_KEY" } } } } ``` The `source` parameter is URL-encoded. You can run multiple scoped MCPs simultaneously, each operating in its own tool namespace. ### Scoped vs full MCP | Scoped MCP | Full Nia MCP | | -------------------------- | ----------------------------- | | One source per server | All subscribed sources | | Separate tool namespace | Shared tools query everything | | Best for focused workflows | Best for cross-source queries | → Deep dive: [Scoped MCP Servers](/scoped-mcp) *** ## 12. Sandbox Search Provisions an isolated runtime, clones a **public** Git repository (GitHub, GitLab, Bitbucket), and runs a **read-only** agent that answers your question using local files only. When the job finishes, the sandbox is destroyed. ### When to use it | Approach | Best for | | ------------------ | --------------------------------------------------------------------------------------------------------------------- | | **Sandbox search** | One-off questions against a public repo URL or `owner/repo` shorthand; full tree available; supports GitLab/Bitbucket | | **Unified search** | Indexed sources, multiple repositories, hybrid retrieval | | **Tracer** | GitHub-centric agent that uses GitHub APIs (no full clone) | ### Endpoints | Method | Path | Purpose | | ------ | -------------------------- | ----------------------------------------- | | `POST` | `/v2/sandbox/search` | Start a search job (JSON or SSE) | | `GET` | `/v2/sandbox/jobs/{jobId}` | Fetch job record (status, result, errors) | ### Request fields | Field | Description | | ------------ | -------------------------------------------- | | `repository` | HTTPS URL or `owner/repo` shorthand | | `query` | Natural-language question | | `ref` | Branch, tag, or commit (optional) | | `provider` | `github` (default), `gitlab`, or `bitbucket` | | `stream` | Force SSE on/off | ### SSE event types `job | status | opencode | result | error | done` ### CLI ```bash theme={null} nia search sandbox "How does the router work?" -r honojs/hono nia search sandbox "Explain the plugin system" -r vitejs/vite --ref main nia search sandbox job ``` ### Error codes `INVALID_SANDBOX_REPOSITORY | SANDBOX_PROVISIONING_FAILED | SANDBOX_COMMAND_FAILED | SANDBOX_QUERY_JOB_NOT_FOUND` → Deep dive: [Sandbox Search](/sandbox-search) *** ## 13. Tracer (GitHub Search Without Indexing) Autonomous agent that searches code on GitHub without requiring you to index repositories first. Delegates to specialized **parallel sub-agents** — each handling search, reading, or analysis concurrently. ### Modes | Mode | API value | Model | Best for | | ---- | ------------- | ------------------------ | ------------------------------------------ | | Fast | `tracer-fast` | Claude Haiku | Quick lookups, simple questions | | Deep | `tracer-deep` | Claude Opus (1M context) | Thorough investigations, complex codebases | ### Tools Tracer uses | Tool | Purpose | | --------------- | -------------------------------------------------- | | `github_search` | Code search with qualifiers (`language:`, `path:`) | | `github_list` | Browse file tree structure | | `github_read` | Read file contents with optional line ranges | | `github_glob` | Find files matching glob patterns | ### Phases `Plan → Explore → Search & Read → Iterate → Synthesize` ### Endpoints ``` POST /v2/github/tracer GET /v2/github/tracer/{job_id} GET /v2/github/tracer/{job_id}/stream GET /v2/github/tracer ``` ### SSE events `started | tool_start | tool_complete | complete | error` ### Cost 15 credits per job (Free plan with credit packs); included quotas on Builder, Team, Business, Enterprise. → Deep dive: [Tracer](/tracer) *** ## 14. Package Search Search public package source code without indexing. ### Tools | Tool / endpoint | Purpose | | --------------------------- | ----------------------------------------- | | `nia_package_search_hybrid` | Semantic + keyword hybrid search | | `POST /v2/packages/search` | Semantic search with `semantic_queries[]` | | `POST /v2/packages/grep` | Regex search with `pattern` | ### Supported registries `npm`, `py_pi`, `crates_io`, `golang_proxy`, `ruby_gems` ### CLI ```bash theme={null} nia packages grep npm react "useState" --context-after 3 nia packages hybrid npm react "state management hook" ``` ### Free tier 50 package searches per month on Free plan; unlimited on all paid plans. **150M+ pre-indexed documents** across all registries. → Deep dive: [API Guide](/api-guide) *** ## 15. Supported Source Types Every input format Nia understands. | Source type | Bring it in with | Best tools | Notes | | ----------------------------------------------------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | **Code & repositories (GitHub)** | `index`, [Tracer](/tracer), `get_github_file_tree` | `search`, `nia_read`, `nia_grep`, `nia_explore` | Branches/refs supported | | **Documentation sites** | `index` | `search`, `nia_read`, `nia_grep`, `nia_explore` | Honors `llms.txt`; supports include/exclude crawl filters | | **PDFs & research papers** | `index`, [PDF Indexing](/pdf-indexing) | `search`, `nia_read`, [Document Agent](/document-agent), [Data Extraction](/data-extraction) | Tree-guided hybrid search | | **HuggingFace datasets** | `index`, [HF Datasets](/huggingface-datasets) | `search`, `nia_read`, `nia_explore`, `nia_grep` | Intelligent sampling for large datasets | | **Google Drive** | [Google Drive integration](/google-drive) | `search`, `nia_read`, `nia_grep`, `nia_explore` | OAuth, multiple accounts, shared drives, incremental sync | | **Spreadsheets & tables** | `index` (CSV, TSV, XLSX, XLS) | `search`, `nia_read`, `nia_explore` | Row + header aware | | **Slack** | [Slack Search](/slack-search) (OAuth or BYOT) | `search`, `nia_grep`, `nia_read`, `nia_explore` | Real-time event indexing after backfill | | **X (Twitter)** | [X Integration](/x-integration) | `search` | Bearer token; configurable replies/retweets | | **Local folders, databases, chat history** | `index(folder_path=...)` or [Local Sync](/local-sync) | `search`, `nia_read`, `nia_grep`, `nia_explore` | Continuous file watching | | **Connectors (Notion, Confluence, Jira, ...)** | [Connectors](/connectors) | `search`, `nia_read`, `nia_grep` | OAuth + cron scheduling | | **E2E encrypted (iMessage, WhatsApp, Notes, Contacts, Reminders, Stickies, Screenshots)** | [E2E Encryption](/e2e-encryption) | `search` with `e2e_session_id` | Zero-knowledge sync | | **Browser history (Safari, Chrome, Brave, Edge, Firefox)** | [Local Sync](/local-sync) | `search`, `nia_read` | Auto-detected database paths | | **Telegram** | [Local Sync](/local-sync) | `search` | JSON exports / ZIP files | ### Google Drive specifics * Authenticates with Google OAuth (read-only Drive scopes) * Multiple Google accounts per user / org * Browse My Drive and shared drives * Pick specific files or folders; folder selections recurse; shortcuts resolve to targets * File handling: Google Docs → text; Sheets → spreadsheets; Slides/Drawings → PDFs; PDFs/CSVs/Excel → indexed directly; plain text incl. Markdown, JSON, YAML, XML, HTML, code files; binary files skipped * Incremental sync after first full index ### Slack specifics * **Two connection modes**: Direct OAuth (dashboard) and BYOT (bring your own bot token via API) for enterprise multi-tenant scenarios * **Channel selection modes**: `all` (with optional excludes) or `selected` (with explicit includes) * **Real-time event indexing** via Slack's Events API after initial backfill * **Required bot scopes**: `channels:read`, `channels:history`, `channels:join`, `groups:read` (optional), `groups:history` (optional), `users:read`, `reactions:read` * **BYOT** stores bot tokens encrypted at rest (Fernet AES-128-CBC), each workspace in its own vector namespace * **Live message reads** via `/messages` endpoint (not from index) * **Keyword grep** via `/grep` (BM25) ### X / Twitter specifics * Requires X API v2 bearer token from the [X Developer Portal](https://developer.x.com/) * Configurable: `max_results` (1–500), `include_replies`, `include_retweets` * Status lifecycle: `created → processing → indexed | failed` * Public accounts only (X API v2 limitation) ### HuggingFace dataset specifics | Dataset size | Strategy | Rows indexed | | ------------ | -------- | ------------ | | \< 200K rows | Full | All rows | | 200K – 2M | Sampled | Up to 100K | | > 2M | Sampled | Up to 25K | Binary columns (images, audio, arrays) excluded; only text-compatible columns indexed. Supports `HF_TOKEN` for private datasets. Global source dedup — instant subscribe if already indexed by someone else. ### PDF specifics * Tree-guided hybrid search: documents parsed into hierarchical structures (sections, subsections, figures, tables) * Section-level indexing with hierarchy-aware retrieval * Hybrid signals (vector + non-vector: headers, page numbers, cross-references) * Hierarchical traversal — agents traverse documents as trees, not flat chunks * Sources: arXiv URLs / IDs, direct PDF URLs, direct file uploads * LaTeX rendering for equations * Interactive Papers Playground at [app.trynia.ai/playground/papers](https://app.trynia.ai/playground/papers) → Deep dive: [Source Types](/source-types) *** ## 16. Explore & Chat Web UI at [app.trynia.ai/explore](https://app.trynia.ai/explore) for asking questions across thousands of pre-indexed repositories, docs, and research papers — no setup required. ### Features * **Universal knowledge** — search all pre-indexed sources at once * **Session history** — auto-saved, viewable, loadable, deletable * **Cited responses** — every answer includes source links * **Streaming responses** — real-time ### Explore vs MCP | Explore Chat | MCP `search` | | -------------------------------- | -------------------------------------- | | Web interface | Works in your IDE/agent | | Searches all pre-indexed sources | Can target specific subscribed sources | | Visual session management | Programmatic access | → Deep dive: [Explore & Chat](/explore-chat) *** ## 17. agentsearch (Zero-Install Docs Filesystem) Mounts any documentation site as a **filesystem** your agent can navigate with `tree`, `grep`, `cat`, `find`. **No API key, no account, no install** — one `npx` command. ```bash theme={null} npx nia-docs https://docs.trynia.ai ``` Then inside the shell: ```bash theme={null} trynia $ tree -L 1 trynia $ cat welcome.md trynia $ grep -rl "oracle" . ``` ### One-shot mode (for agents) ```bash theme={null} npx nia-docs https://docs.stripe.com -c "grep -rl 'webhook signature' ." npx nia-docs https://docs.stripe.com -c "cat api/charges/create.md" npx nia-docs https://docs.stripe.com -c "find . -name '*.md'" npx nia-docs https://docs.stripe.com -c "tree -L 1" ``` ### Wire into any agent ```bash theme={null} npx nia-docs setup https://docs.stripe.com | claude # Claude Code codex "$(npx nia-docs setup https://docs.stripe.com)" # Codex opencode --prompt "$(npx nia-docs setup https://docs.stripe.com)" gemini "$(npx nia-docs setup https://docs.stripe.com)" copilot -i "$(npx nia-docs setup https://docs.stripe.com)" npx nia-docs agents https://docs.stripe.com >> AGENTS.md ``` ### Performance * \~100ms boot when locally cached * \~2s when site is already backend-indexed * \~30–120s for cold index of a brand-new site * Indexes are namespaced and **shared across all users** — index `docs.stripe.com` once, everyone benefits ### How it works The shell runs **on the client** using `just-bash`, a TypeScript bash reimplementation. Filesystem is an in-memory JS object — `grep -r "webhook" .` over 500 pages completes in milliseconds. Backend respects `llms.txt`, auto-detects OpenAPI specs (`/api-spec/`), and normalizes URL paths. ### Telemetry opt-out ```bash theme={null} NIA_DOCS_TELEMETRY=off npx nia-docs https://docs.example.com ``` → Deep dive: [agentsearch](/integrations/installation/agentsearch) *** ## 18. Installation Methods Five ways to connect Nia to your agent. ### `npx nia-wizard@latest` Single-command install. Creates account, generates API key, auto-detects your IDE, configures everything. ```bash theme={null} npx nia-wizard@latest # npm pnpx nia-wizard@latest # pnpm bunx nia-wizard@latest # bun (fastest) yarn dlx nia-wizard@latest # yarn ``` ### CLI Standalone command-line tool — full Nia platform from the shell. Built for agents (JSON output, async with polling, non-interactive). See [section 8](#8-local-sync) for sync commands. Additional command groups: * `nia auth login [--api-key …]` / `nia auth status` * `nia repos index|list|status|read|grep|tree` * `nia sources index|read|grep|tree` * `nia papers index` * `nia datasets index` * `nia local add|watch` * `nia search query|universal|web|deep|sandbox` * `nia oracle job|stream|status` * `nia tracer run|stream` * `nia contexts save|semantic|get` * `nia packages grep|hybrid` * `nia github tree|read|search|glob` * `nia usage` ### MCP Server Standard Model Context Protocol integration. **Remote server recommended** (zero deps, no local process); local server option uses `pipx run nia-mcp-server`. **Supported clients (30+):** Cursor, VS Code, Claude Code, Claude Desktop, Windsurf, Cline, Continue.dev, Google Antigravity, Trae, Gemini CLI, Mistral Vibe CLI, Zed, OpenAI Codex, Roo Code, Kilo Code, JetBrains AI Assistant, Kiro, LM Studio, Visual Studio 2022, BoltAI, Qodo Gen, Qwen Coder, Perplexity Desktop, Warp, Copilot Coding Agent, Copilot CLI, Amazon Q Developer CLI, Opencode, Crush, Amp, Factory, Augment Code, Rovo Dev CLI, Smithery, Zencoder, Emdash, plus Bun/Deno/Docker/Windows configurations. ### Agent Skill Lightweight alternative to MCP — your agent reads a skill file and calls the Nia API directly. No background process. ```bash theme={null} npx nia-wizard skill add --api-key "nk_..." --source nozomio-labs/nia-skill --non-interactive --ci # Or: bunx skills add nozomio-labs/nia-skill ``` API key configured via `NIA_API_KEY` env var or `~/.config/nia/api_key`. ### Plugins Agent-native marketplace installs: | Plugin | Install | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Claude Code** | `/install nia` (marketplace) or `/plugin marketplace add nozomio-labs/nia-plugin` | | **OpenCode** | `bunx nia-opencode@latest install` (with `--no-tui --api-key …` for CI). Includes keyword triggers (`research…`, `look up…`, `find docs…`, `save this context`, `hand off to Cursor`) | | **OpenClaw** | Install via [ClawHub](https://www.clawhub.ai/arlanrakh/nia) skill | | **21st.dev (`nia-chat`)** | Next.js template combining 21st Agents SDK with Nia knowledge tools — chat with any GitHub repo | → Deep dives: [Installation overview](/integrations/installation/overview), [CLI](/integrations/installation/cli), [MCP](/integrations/installation/mcp), [Skill](/integrations/installation/skill), [agentsearch](/integrations/installation/agentsearch), [Plugins](/plugins/overview) *** ## 19. SDKs and Language Bindings ### Python — `nia-ai-py` ```bash theme={null} pip install nia-ai-py # or: uv add nia-ai-py ``` Requires Python 3.10+. ```python theme={null} from nia_py.sdk import NiaSDK sdk = NiaSDK(api_key="nia_your_api_key") sdk.search.universal(query="How does authentication work?") ``` Three high-level clients: `sdk.search` (universal/query/web/deep), `sdk.sources` (create/list/resolve/delete), `sdk.oracle` (create/wait/stream/list jobs). Each low-level API function has four variants: `.sync()`, `.sync_detailed()`, `.asyncio()`, `.asyncio_detailed()`. ### TypeScript — `nia-ai-ts` ```bash theme={null} npm install nia-ai-ts # also: yarn / pnpm / bun ``` ```typescript theme={null} import { NiaSDK } from "nia-ai-ts"; const sdk = new NiaSDK({ apiKey: "nia_your_api_key" }); await sdk.search.universal({ query: "..." }); ``` Includes E2E encryption helpers under `nia-ai-ts/local-first` — `deriveE2EKeys`, `buildE2ESyncBatch`, adapters (`iMessageAdapter`, etc.), and `sdk.daemon.pushE2ESync` / `createE2ESession` / `purgeE2EData`. ### LangChain — `langchain-nia` ```bash theme={null} pip install langchain-nia # or: uv add langchain-nia ``` Official partner integration. **20 LangChain-compatible tools** via `NiaToolkit` and `NiaAPIWrapper`. Passes all LangChain standard tests. | Group | Tools | Count | | ---------------- | ------------------------------------------------------------------------------------------------------ | ----- | | Search | `NiaSearch`, `NiaWebSearch`, `NiaDeepResearch`, `NiaUniversalSearch`, `NiaAdvisor` | 5 | | Sources | `NiaIndex`, `NiaSourceList`, `NiaSourceSubscribe`, `NiaSourceSync`, `NiaRead`, `NiaGrep`, `NiaExplore` | 7 | | GitHub | `NiaGitHubSearch`, `NiaGitHubRead`, `NiaGitHubGlob`, `NiaGitHubTree` | 4 | | Context & memory | `NiaContextSave`, `NiaContextSearch` | 2 | | Dependencies | `NiaDependencySubscribe`, `NiaDependencyAnalyze` | 2 | Toolkit toggles: `include_search`, `include_sources`, `include_github`, `include_contexts`, `include_dependencies`. Sync and async (`.invoke` / `.ainvoke`). ### Configuration knobs | Option | Description | | ---------------------------------------------- | ------------------------------------- | | `apiKey` / `api_key` | API key | | `baseUrl` / `base_url` | Default `https://apigcp.trynia.ai/v2` | | `timeout_seconds` | Default 60s (Python) | | `maxRetries` / `max_retries` | Default 2 | | `initialBackoffMs` / `initial_backoff_seconds` | Exponential backoff base | ### Auth headers accepted | Header | Format | | --------------- | ------------------------- | | `Authorization` | `Bearer nia_your_api_key` | | `X-API-Key` | `nia_your_api_key` | → Deep dive: [SDK Quickstart](/sdk/quickstart), [Authentication](/sdk/authentication), [Examples](/sdk/examples) *** ## 20. Agent Onboarding (API-First) Headless signup, login, and skill install for autonomous agents — no browser required. ### New users ``` POST /v2/auth/signup → returns read-only API key + emails 6-digit code POST /v2/auth/verify → exchanges code for full-access API key nia-wizard skill add --non-interactive --ci → install skill ``` ### Returning users ``` POST /v2/auth/login → request verification code POST /v2/auth/login/verify → exchange code for full-access API key ``` ### Resend code ``` POST /v2/auth/resend-code ``` ### Non-interactive skill install ```bash theme={null} npx nia-wizard skill add \ --api-key "" \ --source nozomio-labs/nia-skill \ --non-interactive --ci # Optional target pinning: npx nia-wizard skill add --api-key "" --target codex --non-interactive --ci ``` → Deep dive: [Agent Onboarding](/agent-onboarding) *** ## 21. Plans, Pricing & Limits | Feature | Free | Builder (\$15/mo) | Team (\$50/seat/mo) | Business (\$99/seat/mo) | Enterprise | | -------------------------- | ---------- | -------------------- | ---------------------- | ------------------------- | -------------------------- | | Queries | 50/mo | 1,000/mo | 5,000/mo | Unlimited | Unlimited | | Web Searches | 20/mo | 200/mo | 1,000/mo | Unlimited | Unlimited | | Package Search | 50/mo | Unlimited | Unlimited | Unlimited | Unlimited | | Contexts | 5 | 100 | 1,000 | Unlimited | Unlimited | | Deep Research | Credits | 30/mo | 200/mo | Unlimited | Unlimited | | Oracle | Credits | 30/mo | 200/mo | Unlimited | Unlimited | | Tracer | Credits | 30/mo (3 concurrent) | 200/mo (10 concurrent) | Unlimited (50 concurrent) | Unlimited (100 concurrent) | | Indexing | 3 lifetime | 50/mo | 500/mo | Unlimited | Unlimited | | Concurrent Indexes | 1 | 5 | 50 | Unlimited | Unlimited | | SOC 2 / SLA / Custom Infra | – | – | – | (Dedicated support) | ✓ all | ### Credit packs | Pack | Credits | Price | | --------- | ------- | ----- | | Starter | 100 | \$3 | | Plus | 300 | \$7 | | Developer | 1,000 | \$18 | | Growth | 5,000 | \$50 | | Scale | 30,000 | \$149 | | Max | 100,000 | \$499 | ### Credit cost per operation | Operation | Credits | | ------------------------------------------------------------------------------------------------------------------------------ | ------- | | Search & Context (query, search, web search, package search, context save, code grep, doc grep, doc read, read source content) | 1 | | Indexing & Sync | 10 | | Deep Research | 10 | | Oracle | 15 | | Tracer | 15 | ### API request-based pricing For high-volume API users — contact `arlan@nozomio.com` for custom request-based pricing with volume discounts. ### Educational / non-profit discounts Available — contact `arlan@nozomio.com`. ### Rate limit headers `X-RateLimit-Limit | X-RateLimit-Remaining | X-RateLimit-Reset | X-Monthly-Limit` → Deep dive: [Pricing](/pricing) *** ## 22. Privacy & Security * **SOC 2 compliant** (Enterprise) * **Opted out of training** by all AI model providers * **End-to-end encryption** available for personal data sources (iMessage, WhatsApp, Apple Notes, Contacts, Reminders, Stickies, Screenshots) — plaintext never leaves your device * **350+ exclusion patterns** automatically protect credentials (`.env`, `.pem`, `.key`, SSH keys, anything matching `*credentials*`/`*secrets*`/`*token*`), version control (`.git`, `.svn`), dependencies (`node_modules`, `venv`, `__pycache__`), and build outputs (`dist/`, `build/`, `.next/`) * **Local credentials** stored at `~/.nia-sync/config.json` with `0600` permissions; never logged or transmitted in plaintext * **Slack BYOT bot tokens** encrypted at rest with Fernet (AES-128-CBC); each workspace in its own vector namespace * **E2E encryption stack:** AES-256-GCM, PBKDF2 key derivation, macOS Keychain (or platform-equivalent) key storage, HMAC-SHA256 blind index, `zembed-1-2560` client-side embeddings, scoped decrypt sessions with TTL and max-chunks limits * **Local hosting** available for organizations needing data sovereignty → Deep dives: [Privacy](/privacy), [End-to-End Encryption](/e2e-encryption), [Enterprise](/enterprise) *** ## 23. Key API Endpoints Reference | Endpoint | Description | | -------------------------------------------------- | --------------------------------------------------------------- | | `POST /v2/sources` | Create/index any source (auto-detects type) | | `GET /v2/sources` | List indexed sources | | `GET /v2/sources-summary` | Quick inventory across all source types | | `POST /v2/repositories` | Index a GitHub repo | | `POST /v2/data-sources` | Index documentation | | `POST /v2/research-papers` | Index arXiv paper | | `POST /v2/huggingface-datasets` | Index HuggingFace dataset | | `POST /v2/search` | Unified search (`mode`: `query` / `universal` / `web` / `deep`) | | `POST /v2/search/query` | Multi-source query with messages | | `POST /v2/sandbox/search` | Clone + read-only agent in ephemeral VM | | `GET /v2/sandbox/jobs/{jobId}` | Sandbox job status | | `POST /v2/document/agent` | Deploy autonomous agent into a document | | `POST /v2/extract` | Table extraction from PDF | | `POST /v2/extract/detect` | Visual element detection | | `POST /v2/extract/engineering` | Engineering document extraction | | `POST /v2/extract/engineering/{id}/query` | Follow-up query on engineering extraction | | `GET /v2/extractions` | List extraction jobs | | `POST /v2/oracle` / `POST /v2/oracle/jobs` | Oracle Research Agent | | `GET /v2/oracle/jobs/{job_id}/stream` | Oracle SSE | | `POST /v2/github/tracer` | Tracer (GitHub agent without indexing) | | `GET /v2/github/tracer/{job_id}/stream` | Tracer SSE | | `POST /v2/packages/search` | Semantic search in package source | | `POST /v2/packages/grep` | Regex search in package source | | `POST /v2/contexts` | Save cross-agent conversation context | | `POST /v2/slack/install` / `/install/token` | Slack OAuth or BYOT | | `POST /v2/slack/installations/{id}/index` | Index Slack workspace | | `POST /v2/slack/installations/{id}/grep` | BM25 keyword search in Slack | | `POST /v2/x/installations` | Create X (Twitter) installation | | `POST /v2/x/installations/{id}/index` | Index X account | | `POST /v2/google-drive/install` | Google Drive OAuth install | | `POST /v2/google-drive/installations/{id}/index` | Google Drive initial index | | `POST /v2/google-drive/installations/{id}/sync` | Google Drive incremental sync | | `GET /v2/connectors` | List connector types | | `POST /v2/connectors/{type}/install` | Install a connector | | `POST /v2/connectors/installations/{id}/index` | Trigger connector indexing | | `PATCH /v2/connectors/installations/{id}/schedule` | Update cron schedule | | `POST /v2/daemon/e2e/sync` | Push E2E-encrypted chunks | | `POST /v2/daemon/e2e/sessions` | Create scoped decrypt session | | `POST /v2/daemon/e2e/decrypt` | Retrieve ciphertext for desktop bridge | | `POST /v2/auth/signup` / `verify` | Account creation flow | | `POST /v2/auth/login` / `login/verify` | Returning user login | | `GET /v2/usage` | Usage statistics | Auth: `Authorization: Bearer YOUR_API_KEY` (or `X-API-Key: YOUR_API_KEY`). → Full reference: [API Reference](/api-reference) and [API Guide](/api-guide). *** ## 24. Pre-Configured Agent Rules Open-source [`nia-rules-for-agents`](https://github.com/nozomio-labs/nia-rules-for-agents) repository provides ready-to-use rule files for popular agents: * Claude (`.claude/agents/`) * Codex (`.codex/prompts/`) * Cursor (`.cursor/rules/`) * Windsurf (`.windsurf/rules/`) * Roo Code (`.roo/rules/`) * Cline (`.clinerules`) * General agents (`general-agents/`) Drop the appropriate file into your agent's directory to teach it how to leverage Nia effectively. → Deep dive: [Agent Rules](/example-workflows/agent-rules) *** ## 25. Example Workflows End-to-end patterns showing Nia in action: | Workflow | What it demonstrates | | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | **Universal search across all sources** | Single query routed across repos, docs, and web with cross-source ranking | | **Package search + agent building** | grep + hybrid search through package source while building an AI SDK agent | | **One-shot integrations with documentation context** | Index Better Auth docs + codebase, generate complete integration in one shot | | **Deep research for framework discovery** | Use `nia_research deep` / Oracle to discover tools, then index them for development | | **Domain-specific expert agents** | Chromium expert, Paul Graham essays, Naval Ravikant — each built by indexing a corpus and pointing an agent at it | | **Agent handoff** | Plan with Cursor, save context, continue execution in Claude Code | → Deep dive: [Example Workflows](/example-workflows/overview), [Custom Agents](/example-workflows/custom-agents), [Tips & Tricks](/example-workflows/tips) *** ## TL;DR for Agents If you are an AI agent reading this, here is what you should remember: 1. **Indexing is universal** — call `index` on any GitHub URL, arXiv URL, HuggingFace dataset URL, PDF URL, spreadsheet, web URL, or local path. Nia auto-detects the type. 2. **Always check existing sources first** with `manage_resource action=list` or `repos-list` / `sources-list` before indexing or web-fetching. 3. **Search modes**: `search` (semantic), `nia_grep` (regex), `nia_read` (file/section), `nia_explore` (tree). Add `nia_package_search_hybrid` for public package source code without indexing. 4. **Live GitHub** without indexing → use [Tracer](/tracer). Need a deeper read with a full clone → use [Sandbox Search](/sandbox-search). 5. **Long PDFs** → use [Document Agent](/document-agent) for cited multi-section answers and structured output, or [Data Extraction](/data-extraction) for typed records. 6. **Multi-step research** → `nia_research mode=deep|oracle` or [Oracle Research Agent](/oracle-research) directly. 7. **Save state across agents** → `context save` / `context search`. Memory types: `scratchpad`, `episodic`, `fact`, `procedural`. 8. **Personal data** → use [Local Sync](/local-sync) (server-indexed) or [E2E Encryption](/e2e-encryption) (zero-knowledge) for iMessage, WhatsApp, Notes, Contacts, Reminders, Stickies, Screenshots, browser history, and folders. 9. **Cloud sources** → [Google Drive](/google-drive), [Slack](/slack-search), [X](/x-integration), or generic [Connectors](/connectors) (Notion, Confluence, etc.). 10. **Compounding knowledge** → use [Vault](/vault) to let an agent build a self-improving wiki on top of your indexed sources. 11. **Headless onboarding** → use [Agent Onboarding](/agent-onboarding) endpoints (`/v2/auth/signup`, `/v2/auth/verify`, `/v2/auth/login`, `/v2/auth/login/verify`). 12. **Zero-account quick lookup of any docs site** → `npx nia-docs -c "grep -rl 'x' ."` ([agentsearch](/integrations/installation/agentsearch)). *** Auth, base URL, rate limits, examples Full endpoint and schema reference Browse by what knowledge you have Python, TypeScript, LangChain Free plan, no credit card required *** **Need help?** Join our [Discord community](https://discord.gg/BBSwUMrrfn) or email `arlan@nozomio.com`. # Changelog Source: https://docs.trynia.ai/changelog/overview Stay up to date with the latest changes and improvements to Nia ## Release Notes Follow along with updates across Nia's API, MCP server, SDKs, and platform. Stay up to date with the latest changes and improvements to Nia. All changelogs, release notes, and update announcements are posted in our Discord server. Join to stay in the loop on new features, bug fixes, and platform improvements. **Latest:** Join `#changelog` in Discord for the most recent updates. *** ## Where to Find Updates Head over to our Discord community to view the full changelog: [https://dsc.gg/nozomio](https://dsc.gg/nozomio) Our Discord `#changelog` channel includes: * **API & Platform** — New endpoints, performance improvements, and infrastructure changes * **MCP Server** — Updates to the MCP integration and tool capabilities * **SDKs** — New SDK releases, breaking changes, and migration guides * **Plugins** — Updates to OpenCode, OpenClaw, and Claude Code integrations # Connectors Source: https://docs.trynia.ai/connectors A generic framework for integrating external data sources into Nia — discover, install, configure, index, and search. Connectors provide a unified way to bring external data sources into Nia. Instead of building custom integrations for every service, connectors follow a common lifecycle: discover available types, install one with credentials, configure sync settings, trigger indexing, and search the results alongside all your other Nia sources. Connectors are a generalization of Nia's integration model. Each connector type (e.g., Notion, Confluence, Jira) follows the same API contract, so you can manage them all with a single set of endpoints. *** ## How Connectors Work List available connector types to see what external services Nia supports. Each type describes the authentication method it requires (API key or OAuth). Install a connector by providing credentials. For API-key-based connectors, pass the key directly. For OAuth-based connectors, the API returns an authorization URL — redirect the user and handle the callback. Set up a sync schedule and configure what data gets indexed. You can run one-time imports or set up recurring syncs on a cron schedule. Trigger indexing to pull data from the external source, chunk it, embed it, and store it in Nia's vector index. Once indexed, connector data is searchable through the same unified search endpoint used for repositories, docs, Slack, and every other Nia source type. *** ## Available Connector Types List all connector types your organization can use: ```bash theme={null} curl https://apigcp.trynia.ai/v2/connectors \ -H "Authorization: Bearer $NIA_API_KEY" ``` ```json theme={null} { "connectors": [ { "type": "notion", "name": "Notion", "auth_method": "oauth", "description": "Index Notion pages and databases" }, { "type": "confluence", "name": "Confluence", "auth_method": "api_key", "description": "Index Confluence spaces and pages" } ] } ``` Each connector type specifies its `auth_method`: | Auth Method | How It Works | | ----------- | ---------------------------------------------------------------------------------------------------------- | | `api_key` | Pass the API key directly during installation | | `oauth` | Nia returns an authorization URL; the user approves access and Nia handles the token exchange via callback | *** ## Installing a Connector ### API Key Authentication For connectors that use API key auth, provide the credentials directly: ```bash theme={null} curl -X POST https://apigcp.trynia.ai/v2/connectors/confluence/install \ -H "Authorization: Bearer $NIA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "credentials": { "api_key": "your-confluence-api-key", "domain": "yourteam.atlassian.net" }, "display_name": "Engineering Confluence" }' ``` ```json theme={null} { "installation_id": "c3a91f02-...", "connector_type": "confluence", "display_name": "Engineering Confluence", "status": "active", "created_at": "2026-03-29T10:00:00Z" } ``` ### OAuth Authentication For OAuth-based connectors, the install endpoint returns an authorization URL: ```bash theme={null} curl -X POST https://apigcp.trynia.ai/v2/connectors/notion/install \ -H "Authorization: Bearer $NIA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "display_name": "Team Notion" }' ``` ```json theme={null} { "authorization_url": "https://api.notion.com/v1/oauth/authorize?client_id=...&redirect_uri=...", "state": "abc123" } ``` Redirect the user to `authorization_url`. After they approve, Notion redirects to Nia's callback endpoint: ``` GET /v2/connectors/notion/oauth/callback?code=...&state=abc123 ``` Nia exchanges the code for an access token and creates the installation automatically. *** ## Managing Installations ### List All Installations ```bash theme={null} curl https://apigcp.trynia.ai/v2/connectors/installations \ -H "Authorization: Bearer $NIA_API_KEY" ``` ```json theme={null} { "installations": [ { "id": "c3a91f02-...", "connector_type": "confluence", "display_name": "Engineering Confluence", "status": "active", "last_sync_at": "2026-03-28T14:30:00Z", "schedule": "0 */6 * * *", "indexed_document_count": 342 }, { "id": "f7b24e91-...", "connector_type": "notion", "display_name": "Team Notion", "status": "active", "last_sync_at": "2026-03-29T08:00:00Z", "schedule": null, "indexed_document_count": 128 } ] } ``` ### Disconnect a Connector Remove an installation and all its indexed data: ```bash theme={null} curl -X DELETE https://apigcp.trynia.ai/v2/connectors/installations/c3a91f02-... \ -H "Authorization: Bearer $NIA_API_KEY" ``` ```json theme={null} { "message": "Installation disconnected and data removed." } ``` Disconnecting a connector permanently deletes all indexed data from that installation. This action cannot be undone. *** ## Indexing ### Trigger Indexing Start an indexing job that pulls content from the external source: ```bash theme={null} curl -X POST https://apigcp.trynia.ai/v2/connectors/installations/c3a91f02-.../index \ -H "Authorization: Bearer $NIA_API_KEY" ``` ```json theme={null} { "installation_id": "c3a91f02-...", "status": "processing", "workflow_run_id": "d4e56f78-..." } ``` ### Check Sync Status ```bash theme={null} curl https://apigcp.trynia.ai/v2/connectors/installations/c3a91f02-.../status \ -H "Authorization: Bearer $NIA_API_KEY" ``` ```json theme={null} { "installation_id": "c3a91f02-...", "connector_type": "confluence", "status": "processing", "progress": 67, "message": "Indexing pages (230/342)", "indexed_document_count": 230, "chunk_count": 1840, "last_sync_at": "2026-03-28T14:30:00Z" } ``` | Status | Meaning | | ------------ | ------------------------------- | | `idle` | No indexing in progress | | `processing` | Indexing is running | | `completed` | Last sync finished successfully | | `failed` | Last sync encountered an error | *** ## Scheduling and Sync Management ### Set a Sync Schedule Configure automatic recurring syncs using a cron expression: ```bash theme={null} curl -X PATCH https://apigcp.trynia.ai/v2/connectors/installations/c3a91f02-.../schedule \ -H "Authorization: Bearer $NIA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "schedule": "0 */6 * * *" }' ``` ```json theme={null} { "installation_id": "c3a91f02-...", "schedule": "0 */6 * * *", "next_sync_at": "2026-03-29T18:00:00Z" } ``` Common schedule patterns: | Cron Expression | Frequency | | --------------- | ------------------------- | | `0 */6 * * *` | Every 6 hours | | `0 0 * * *` | Daily at midnight | | `0 9 * * 1` | Weekly on Mondays at 9 AM | | `0 */1 * * *` | Every hour | ### Disable Scheduled Sync Set the schedule to `null` to stop automatic syncs: ```bash theme={null} curl -X PATCH https://apigcp.trynia.ai/v2/connectors/installations/c3a91f02-.../schedule \ -H "Authorization: Bearer $NIA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "schedule": null }' ``` Even with a schedule disabled, you can always trigger a manual sync via `POST /v2/connectors/installations/{id}/index`. *** ## Searching Connector Data Once indexed, connector data is available through Nia's unified search endpoint alongside all your other sources: ```bash theme={null} curl -X POST https://apigcp.trynia.ai/v2/search/query \ -H "Authorization: Bearer $NIA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "messages": [{"role": "user", "content": "What is our onboarding process?"}], "include_sources": true, "stream": true }' ``` You can also target specific connector installations: ```bash theme={null} curl -X POST https://apigcp.trynia.ai/v2/search/query \ -H "Authorization: Bearer $NIA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "messages": [{"role": "user", "content": "sprint planning guidelines"}], "connector_installations": ["c3a91f02-...", "f7b24e91-..."], "include_sources": true, "stream": true }' ``` *** ## API Reference | Method | Endpoint | Description | | -------- | ------------------------------------------------ | -------------------------------------- | | `GET` | `/v2/connectors` | List available connector types | | `POST` | `/v2/connectors/{connector_type}/install` | Install a connector (API key or OAuth) | | `GET` | `/v2/connectors/{connector_type}/oauth/callback` | Handle OAuth callback | | `GET` | `/v2/connectors/installations` | List all installations | | `DELETE` | `/v2/connectors/installations/{id}` | Disconnect and remove an installation | | `POST` | `/v2/connectors/installations/{id}/index` | Trigger indexing | | `PATCH` | `/v2/connectors/installations/{id}/schedule` | Update sync schedule | | `GET` | `/v2/connectors/installations/{id}/status` | Get sync status | *** When you disconnect a connector via `DELETE /v2/connectors/installations/{id}`, all indexed data (chunks, embeddings, metadata) is permanently removed from Nia. The external source itself is not modified. Yes. For example, you can connect multiple Confluence instances or multiple Notion workspaces. Each installation operates independently with its own credentials, schedule, and indexed data. Indexing time depends on the volume of content in the external source and any rate limits imposed by the third-party API. Most installations with a few hundred documents complete within a few minutes. Large sources (10k+ documents) may take 30-60 minutes. *** **Need Help?** Join our [Discord community](https://discord.gg/BBSwUMrrfn) or reach out through [app.trynia.ai](https://app.trynia.ai/) for support. # Agent Context Sharing Source: https://docs.trynia.ai/context-sharing Finish planning in one agent, pick up execution in another, without losing the thread. Save entire conversation histories - code snippets, plans, decisions, referenced sources, and edited files. Re-open them in another chat or coding agent. Nia preserves what you searched and every query you made.