Nia Capabilities - Nia AI Documentation

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.

Quick Install

npx nia-wizard@latest

Creates an account, generates an API key, auto-detects your IDE.

Get an API Key

API Base URL

https://apigcp.trynia.ai/v2Auth: Authorization: Bearer YOUR_API_KEY

Browse by Source Type

Already know your input (code, PDFs, Slack, Drive)? Start with Source Types.

Capability Map

Every Nia capability falls into one of these categories:

Category	What it does
Indexing & Subscriptions	Bring any source into Nia and keep it fresh
Search, Read & Explore	Semantic, regex, and structural retrieval across everything indexed
Research Agents	Autonomous multi-step investigations across code, docs, and the web
Document Agent	Deploy a tool-using agent into a single PDF or document
Data Extraction	Pull structured records, visual elements, and engineering data from PDFs
Vault	Agent-maintained personal wiki layered on top of your indexed sources
Context Sharing	Save plans and conversation state for cross-agent handoffs
Local Sync	Continuously sync local folders, databases, and chat history
End-to-End Encryption	Zero-knowledge sync for personal data — plaintext never leaves your device
Connectors	Generic framework for OAuth/API-key external sources (Notion, Confluence, Jira)
Scoped MCP Servers	Specialized MCP servers focused on one source
Sandbox Search	Clone a public Git URL into an ephemeral VM and run a read-only agent
Tracer	GitHub search agent with parallel sub-agents, no indexing required
Package Search	Search PyPI, npm, Crates.io, Go modules, Ruby Gems without indexing
Source Types	Every input format Nia understands
Explore & Chat	Web UI for cross-source Q&A across pre-indexed knowledge
agentsearch	One-command Unix filesystem over any docs site, zero account
Installation Methods	CLI, MCP server, agent skill, plugins, agentsearch
SDKs	Python, TypeScript, LangChain
Agent Onboarding	Headless signup, verify, and skill install for autonomous agents
Plans, Pricing & Limits	Free → Builder → Team → Business → Enterprise + credit packs
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:

"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. 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

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

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

Tracer (covered separately below)

Live GitHub search agent that delegates to parallel sub-agents — see section 13.

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

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

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

Raw sources — your indexed Nia sources (read-only)
The wiki — markdown pages the agent generates and owns
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 <ids>`	Create a vault and trigger first ingest
`nia vault ingest <id>`	Synthesize pages for new sources only
`nia vault ingest <id> --force`	Re-synthesize all sources
`nia vault sync <id>`	Regenerate pages whose sources changed
`nia vault refresh <id>`	Combined ingest + sync
`nia vault lint <id>`	Find orphan pages, broken wikilinks, contradictions
`nia vault dream <id>`	Self-improvement loop: discover entities, find connections, detect contradictions
`nia vault auto-dream <id> on`	Weekly automatic dream (Sundays 3am UTC)
`nia vault open <id>`	Drop into a writable bash shell with the vault mounted
`nia vault open <id> --c "tree"`	One-shot command (for agent tool loops)
`nia vault search <id> "query"`	Hybrid semantic + keyword search inside the vault
`nia vault cancel <id>`	Cancel a stuck workflow
`nia vault agents <id>`	Append agent setup instructions to `CLAUDE.md` / `AGENTS.md`
`nia vault skill <id>`	Generate a skill file for the vault
`nia vault setup <id>`	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

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

8. Local Sync

Standalone CLI daemon (nia) that continuously synchronizes local data sources with Nia, enabling agents to search your personal knowledge base.

Quickstart

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 <path>`	Add a new source
`nia link <id> <path>`	Link a cloud source to a local path
`nia remove <id>`	Remove source
`nia upgrade`	Check and install updates

Search from the terminal

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 <id>`	Detailed info (chunk count, last sync, errors)
`nia logs [<id>] [--tail] [--errors]`	Sync logs
`nia diff [<id>]`	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 <id>, nia resume <id>, nia resync <id>, nia resync --all.

Web integration

nia open dashboard | activity | local-sync | api-keys | billing | docs | <source-id>

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 <sec> (default 600), -r, --refresh <sec> (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

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. → Deep dive: End-to-End 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

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

Pick any pre-indexed source from Global Sources at app.trynia.ai
Click “Create Scoped MCP” — Nia generates a dedicated config
Add the config to your IDE

Example config

{
  "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

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

CLI

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 <job-id>

Error codes

INVALID_SANDBOX_REPOSITORY | SANDBOX_PROVISIONING_FAILED | SANDBOX_COMMAND_FAILED | SANDBOX_QUERY_JOB_NOT_FOUND → Deep dive: 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

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

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

15. Supported Source Types

Every input format Nia understands.

Source type	Bring it in with	Best tools	Notes
Code & repositories (GitHub)	`index`, 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	`search`, `nia_read`, Document Agent, Data Extraction	Tree-guided hybrid search
HuggingFace datasets	`index`, HF Datasets	`search`, `nia_read`, `nia_explore`, `nia_grep`	Intelligent sampling for large datasets
Google Drive	Google Drive integration	`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 (OAuth or BYOT)	`search`, `nia_grep`, `nia_read`, `nia_explore`	Real-time event indexing after backfill
X (Twitter)	X Integration	`search`	Bearer token; configurable replies/retweets
Local folders, databases, chat history	`index(folder_path=...)` or Local Sync	`search`, `nia_read`, `nia_grep`, `nia_explore`	Continuous file watching
Connectors (Notion, Confluence, Jira, …)	Connectors	`search`, `nia_read`, `nia_grep`	OAuth + cron scheduling
E2E encrypted (iMessage, WhatsApp, Notes, Contacts, Reminders, Stickies, Screenshots)	E2E Encryption	`search` with `e2e_session_id`	Zero-knowledge sync
Browser history (Safari, Chrome, Brave, Edge, Firefox)	Local Sync	`search`, `nia_read`	Auto-detected database paths
Telegram	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
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

→ Deep dive: Source Types

16. Explore & Chat

Web UI at 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

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.

npx nia-docs https://docs.trynia.ai

Then inside the shell:

trynia $ tree -L 1
trynia $ cat welcome.md
trynia $ grep -rl "oracle" .

One-shot mode (for agents)

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

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

NIA_DOCS_TELEMETRY=off npx nia-docs https://docs.example.com

→ Deep dive: 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.

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 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.

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 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, CLI, MCP, Skill, agentsearch, Plugins

19. SDKs and Language Bindings

Python — `nia-ai-py`

pip install nia-ai-py    # or: uv add nia-ai-py

Requires Python 3.10+.

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`

npm install nia-ai-ts     # also: yarn / pnpm / bun

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`

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, Authentication, 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

npx nia-wizard skill add \
  --api-key "<api-key>" \
  --source nozomio-labs/nia-skill \
  --non-interactive --ci

# Optional target pinning:
npx nia-wizard skill add --api-key "<key>" --target codex --non-interactive --ci

→ Deep dive: 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

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, End-to-End Encryption, 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 and API Guide.

24. Pre-Configured Agent Rules

Open-source 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

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, Custom Agents, Tips & Tricks

TL;DR for Agents

If you are an AI agent reading this, here is what you should remember:

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.
Always check existing sources first with manage_resource action=list or repos-list / sources-list before indexing or web-fetching.
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.
Live GitHub without indexing → use Tracer. Need a deeper read with a full clone → use Sandbox Search.
Long PDFs → use Document Agent for cited multi-section answers and structured output, or Data Extraction for typed records.
Multi-step research → nia_research mode=deep|oracle or Oracle Research Agent directly.
Save state across agents → context save / context search. Memory types: scratchpad, episodic, fact, procedural.
Personal data → use Local Sync (server-indexed) or E2E Encryption (zero-knowledge) for iMessage, WhatsApp, Notes, Contacts, Reminders, Stickies, Screenshots, browser history, and folders.
Cloud sources → Google Drive, Slack, X, or generic Connectors (Notion, Confluence, etc.).
Compounding knowledge → use Vault to let an agent build a self-improving wiki on top of your indexed sources.
Headless onboarding → use Agent Onboarding endpoints (/v2/auth/signup, /v2/auth/verify, /v2/auth/login, /v2/auth/login/verify).
Zero-account quick lookup of any docs site → npx nia-docs <url> -c "grep -rl 'x' ." (agentsearch).

API Guide

Auth, base URL, rate limits, examples

API Reference

Full endpoint and schema reference

Source Types

Browse by what knowledge you have

SDKs

Python, TypeScript, LangChain

Get an API Key

Free plan, no credit card required

Need help? Join our Discord community or email arlan@nozomio.com.

Troubleshooting Document Agent

⌘I

Quick Install

Get an API Key

API Base URL

Browse by Source Type

​Capability Map

​1. Indexing & Subscriptions

​index (universal entry point)

​auto_subscribe_dependencies

​manage_resource

​Pre-indexed (community) sources

​Branch / ref selection

​Global source deduplication

​2. Search, Read & Explore

​search — semantic search

​nia_grep — regex search

​nia_read

​nia_explore

​get_github_file_tree

​Universal search modes

​3. Research Agents

​nia_research — three modes

​nia_advisor

​Oracle Research Agent

​Tracer (covered separately below)

​4. Document Agent

​Key features

​Models

​Endpoint

​Use cases

​5. Data Extraction

​Table extraction

​Detect extraction

​Engineering extraction

​Job lifecycle

​Listing

​6. Vault — Agent-Maintained Personal Wiki

​Three layers

​Page structure

​Workflows

​Layout

​Web UI at app.trynia.ai/vaults

​Personal data sources via Local Sync

​Provenance protection

​7. Context Sharing

​Unified context tool

​Memory types

​What gets captured when you save

​Endpoints

​8. Local Sync

​Quickstart

​Core CLI commands

​Search from the terminal

​Monitoring & debugging

​Sync control

​Web integration

​Configuration

​Source ID shortcuts

​Daemon flags

​Supported data sources

​Virtual file paths

​Sync intervals

​Limits

​Security

​9. End-to-End Encryption

​Pipeline

​Supported sources

​Key concepts

​Sync modes

​Endpoints

​Querying encrypted data

​Demo

​10. Connectors

​Lifecycle

​Auth methods

​Endpoints

​Status values

​Scheduling

​Searching connector data

​Multi-instance support

​11. Scoped MCP Servers

Capability Map

1. Indexing & Subscriptions

`index` (universal entry point)

`auto_subscribe_dependencies`

`manage_resource`

Pre-indexed (community) sources

Branch / ref selection

Global source deduplication

2. Search, Read & Explore

`search` — semantic search

`nia_grep` — regex search

`nia_read`

`nia_explore`

`get_github_file_tree`

Universal search modes

3. Research Agents

`nia_research` — three modes

`nia_advisor`

Oracle Research Agent

Tracer (covered separately below)

4. Document Agent

Key features

Models

Endpoint

Use cases

5. Data Extraction

Table extraction

Detect extraction

Engineering extraction

Job lifecycle

Listing

6. Vault — Agent-Maintained Personal Wiki

Three layers

Page structure

Workflows

Layout

Web UI at `app.trynia.ai/vaults`

Personal data sources via Local Sync

Provenance protection

7. Context Sharing

Unified `context` tool

Memory types

What gets captured when you save

Endpoints

8. Local Sync

Quickstart

Core CLI commands

Search from the terminal

Monitoring & debugging

Sync control

Web integration

Configuration

Source ID shortcuts

Daemon flags

Supported data sources

Virtual file paths

Sync intervals

Limits

Security

9. End-to-End Encryption

Pipeline

Supported sources

Key concepts

Sync modes

Endpoints

Querying encrypted data

Demo

10. Connectors

Lifecycle

Auth methods

Endpoints

Status values

Scheduling

Searching connector data

Multi-instance support

11. Scoped MCP Servers

How it works

Example config

Scoped vs full MCP

12. Sandbox Search