> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trynia.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Nia 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`.