# Welcome to Help Center

**Twig is an API-first RAG platform for building AI agents backed by your data sources.**

## What is Twig?

Twig provides:

* RAG infrastructure with vector search and LLM orchestration
* Data connectors for ingestion and sync from external sources
* Agent configuration APIs and UI for behavior, prompts, and RAG strategy selection
* Validation framework to check for hallucinations, missing citations, and accuracy
* Deployment targets: REST API, embeddable widgets, browser extensions, Slack/Outlook/Zendesk apps

### Core Capabilities

#### 🔌 Data & Integration

* **Data Connectors** - Zendesk, Confluence, Slack, Google Drive, SharePoint, OneDrive, GitBook, Notion, websites, and others. See [full list](https://github.com/thrivapp/twig-help-docs/blob/staging/data-integration/connectors.md).
* **Sync Schedules** - Configure refresh intervals (hourly, daily, weekly, or manual) per data source
* **PII Detection** - Regex-based and NER-based filtering before indexing (configurable per organization)
* **Multi-Tenant Architecture** - Organization-level data isolation with per-tenant embeddings
* **REST API & MCP Server** - Programmatic control over agents, queries, data sources, and evals

#### 🤖 Agent Builder & Intelligence

* **Agent Configuration UI** - Web UI for configuring prompts, temperature, model selection, and data source filters
* **RAG Strategies** - Redwood (single-pass retrieval), Cedar (multi-query expansion), Cypress (agentic multi-hop with tool calling)
* **Session Memory** - Conversation history stored per session (retention: 30 days default)
* **Agentic Workflows** - Multi-step reasoning with function calling (requires Cypress RAG strategy)
* **Agent Personas** - System prompt configuration, response length limits, tone presets, data source scoping

#### ✅ Quality & Validation

* **7-Dimensional Validation** - Checks for: hallucination (claim not in sources), missing data (retrieval gaps), accuracy (factual errors), relevance (off-topic), tone (persona mismatch), completeness (partial answers), citations (source attribution)
* **Source Attribution** - Inline citations with document ID, chunk ID, and URL (when available)
* **Evaluation Framework (Evals)** - Run test queries against agents to measure: answer accuracy, latency (p50/p95), retrieval precision/recall, cost per query
* **Quality Workbench** - Review agent responses, tag incorrect answers, capture feedback for fine-tuning
* **Hybrid Inbox** - Agent drafts responses, human approves/edits before sending (available in Zendesk/HelpScout apps)

#### 🚀 Deployment & Scalability

* **Deployment Channels** - REST API, embeddable widget (iframe), Chrome extension, Slack app, Outlook add-in, Zendesk native app, HelpScout app
* **Infrastructure** - Self-hosted: Docker/Kubernetes manifests available. Cloud: Hosted on AWS with auto-scaling.
* **Observability** - Query logs with retrieval traces (which chunks were retrieved, why), latency breakdowns (embedding, retrieval, LLM), error tracking
* **Caching** - Query result cache (configurable TTL), embedding cache (deduplication at ingestion)

#### 🔐 Enterprise Security

* **SSO Integration** - SAML 2.0 and OAuth 2.0 (Google, Microsoft, Okta, Auth0)
* **Role-Based Access Control** - Roles: Admin, Developer, Viewer. Permissions: manage agents, manage data sources, view analytics, API access.
* **Data Residency** - Embeddings and metadata stored in: US East (default), EU West, AP Southeast (configurable per organization)
* **Compliance** - GDPR: data deletion APIs, export APIs. HIPAA: BAA available on Enterprise plan.
* **Audit Trails** - All queries, data source syncs, user actions logged with timestamps, user IDs, IP addresses

## Quick Start

**Prerequisites**: Twig account with API access

```bash
# Set your API key
export TWIG_API_KEY="your_api_key_here"

# Create an agent
curl -X POST https://api.twig.so/v1/agents \
  -H "Authorization: Bearer $TWIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support Agent", "rag_strategy": "redwood"}'

# Query the agent
curl -X POST https://api.twig.so/v1/query \
  -H "Authorization: Bearer $TWIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agent_123", "query": "What is your refund policy?"}'
```

Full setup instructions: [Quick Start Guide](https://help.twig.so/getting-started/quick-start)

## For Engineers

### 🏗️ Architecture & Concepts

* [Platform Architecture](https://help.twig.so/getting-started/overview) - Ingestion pipeline, vector DB, LLM orchestration, API layer
* [RAG Concepts](https://help.twig.so/getting-started/core-concepts) - Embeddings, vector search, chunking, retrieval scoring
* [RAG Strategy Selection](https://help.twig.so/broken-reference) - Redwood vs Cedar vs Cypress: latency, cost, and accuracy tradeoffs

### 💻 API & Integration

* [REST API Reference](https://help.twig.so/product/developer-api/rest-api) - Endpoints for agents, queries, data sources, evals
* [Authentication](https://help.twig.so/product/developer-api/authentication) - API key generation, bearer token usage, key rotation
* [Webhooks](https://help.twig.so/product/developer-api/webhooks) - Events: data\_sync\_complete, eval\_run\_complete, agent\_query\_complete
* [SDKs](https://help.twig.so/product/developer-api/sdks) - TypeScript, Python clients (npm/pip packages)
* [Rate Limits](https://help.twig.so/product/developer-api/rate-limits) - Current limits: 100 req/min (queries), 10 req/min (data sync)

### 🤖 Building Agents

* [Agent Creation](https://help.twig.so/product/overview/add-an-ai-agent-persona) - API and UI steps, required fields, default values
* [Agent Configuration](https://help.twig.so/product/overview/configuration) - System prompts, temperature (0-2), model selection (GPT-4, Claude)
* [Agentic Workflows](https://help.twig.so/product/advanced/agentic-workflows) - Multi-step planning with Cypress RAG strategy
* [Function Calling](https://help.twig.so/product/advanced/agent-tools) - Custom tools, OpenAPI spec format, authentication

### 📊 Data Pipeline

* [Data Source Setup](https://help.twig.so/broken-reference) - OAuth flows, API credentials, sync schedules, filters
* [Chunking Configuration](https://help.twig.so/rag-scenarios-and-solutions/chunking/optimize-chunks) - Chunk size (default: 512 tokens), overlap (default: 50 tokens), splitting strategies
* [Vector Search Tuning](https://help.twig.so/rag-scenarios-and-solutions/vectors/similarity-calibration) - Similarity thresholds, reranking, hybrid search

### 🔍 Debugging & Monitoring

* [Retrieval Debugging](https://help.twig.so/rag-scenarios-and-solutions/monitoring/retrieval-debugging) - View retrieved chunks, similarity scores, reranking decisions
* [Evaluation Framework](https://help.twig.so/product/monitoring/evals) - Create test sets, run evals, track metrics over time
* [Performance Tuning](https://help.twig.so/product/monitoring/performance-tuning) - Latency analysis: embedding (avg 50ms), retrieval (avg 200ms), LLM (varies)
* [Cost Tracking](https://help.twig.so/product/monitoring/cost-optimization) - Per-query cost breakdown: embedding, LLM tokens, vector search

## Troubleshooting by Symptom

| Symptom                                     | Diagnostic Guide                                                                                                                                                        |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Agent returns wrong or hallucinated answers | [Retrieval Accuracy](https://help.twig.so/rag-scenarios-and-solutions/accuracy/wrong-answers) - Check retrieval scores, increase top\_k, adjust similarity threshold    |
| Semantic search returns irrelevant results  | [Vector Search Tuning](https://help.twig.so/rag-scenarios-and-solutions/vectors/poor-search-results) - Verify embedding model, test query expansion, enable reranking   |
| Context window exceeded error               | [Token Management](https://help.twig.so/rag-scenarios-and-solutions/llm/context-overflow) - Reduce top\_k, decrease chunk size, use truncation                          |
| Query latency >3s                           | [Performance Analysis](https://help.twig.so/product/monitoring/performance-tuning) - Profile embedding/retrieval/LLM steps, check cache hit rate                        |
| Data source sync fails                      | [Data Integration Errors](https://help.twig.so/rag-scenarios-and-solutions/data-integration/confluence-sync) - Verify credentials, check rate limits, review error logs |

[View all solutions](#solutions-by-problem)

## Security & Compliance

* [Authentication & Authorization](https://help.twig.so/product/security/authentication-authorization) - API keys, SSO, role permissions
* [SSO Setup](https://help.twig.so/product/security/sso-integration) - SAML/OAuth configuration steps
* [PII Detection](https://help.twig.so/rag-scenarios-and-solutions/privacy/pii-detection) - Enable PII filters, configure regex patterns
* [Data Privacy](https://help.twig.so/product/security/data-privacy) - Data residency options, deletion APIs, export APIs

## Support

* **Technical Support:** <support@twig.so>
* **Issue Reports:** Include: query ID, agent ID, timestamp, error message, reproduction steps

## Next Steps

**New to RAG?** Start with [RAG Concepts](https://help.twig.so/getting-started/core-concepts) - covers embeddings, vector search, and retrieval.