> ## Documentation Index
> Fetch the complete documentation index at: https://docs.virtuous.org/llms.txt
> Use this file to discover all available pages before exploring further.
# AI Assistant
> The in-docs AI chat — ask questions, get cited answers from the Virtuous docs, attach files and images, and skip the hunt-and-peck. How to use it well and when to reach for it instead of search
The Virtuous API Docs include a **built-in AI Assistant** — a chat panel that answers your questions using the actual content of the docs. Ask anything about the Virtuous APIs, and the assistant searches the documentation in real time, returns answers grounded in the docs, and cites specific pages so you can dive deeper.
This isn't the same as your external AI tools (Cursor, Claude Code, etc.) — those connect to the [MCP server](/virtuous/mcp/overview) and pull docs into their workflows. The AI Assistant is built into [docs.virtuous.org](https://docs.virtuous.org) itself and works in your browser.
## What the AI Assistant does
When you ask a question, the assistant:
* **Searches the docs** for relevant content across all four tabs (CRM+, Raise, Volunteer, Virtuous)
* **Reads the relevant pages** to construct an answer
* **Cites its sources** — every answer includes links to the pages it pulled from
* **Builds context from your current page** — questions are interpreted with the page you're reading as background
* **Returns API details** — including methods, parameters, request bodies, and response schemas from the OpenAPI specs
* **Generates copyable code** — answers often include code examples you can copy directly into your project
* **Handles multiple modalities** — you can attach text, images, and other files for context
The result is conversational documentation: instead of hunting through pages, you ask the question and get an answer.
## When to use the AI Assistant
Different tools fit different needs. Here's how to choose:
| Need | Best tool |
| ------------------------------------------------------------ | ------------------------------------------------------------ |
| "I know the exact page I want to read" | [Search](/virtuous/docs-guide/search-and-navigation) (Cmd+K) |
| "I have a specific question and want a synthesized answer" | **AI Assistant** (Cmd+I) |
| "I want to use the docs in my external AI tool while I code" | [MCP server](/virtuous/mcp/overview) |
| "I want to copy a docs page into ChatGPT or Claude manually" | [Contextual Menu](/virtuous/docs-guide/contextual-menu) |
| "I want to test an endpoint and see the response" | [API Playground](/virtuous/docs-guide/api-playground) |
The AI Assistant is most valuable when you want to **ask** rather than **search** — when phrasing the question is faster than guessing the right keywords.
## Opening the assistant
There are several ways to start a conversation:
| Method | Where |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Keyboard shortcut** | Cmd + I (macOS) or Ctrl + I (Windows/Linux) — from anywhere in the docs |
| **Assistant button** | Next to the search bar at the top of the page |
| **Assistant bar** | At the bottom of the page on most screens |
| **URL parameter** | Add `?assistant` to any docs URL to open the assistant when the page loads |
| **URL parameter with question** | Add `?assistant=` (URL-encoded) to open the assistant pre-loaded with a question |
The chat panel opens on the right side of the page. The page you were reading stays open behind it — useful when you want to read along with the conversation.
## What kinds of questions work well
The assistant is grounded in the docs, so it answers best when your question maps to content the docs actually cover.
### Strong questions
| Question | Why it works |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| "What's the right pattern for detecting deleted users in the Volunteer API?" | Maps to specific Volunteer content; clear and specific |
| "Show me the request body shape for the CRM+ Contact create endpoint" | Maps to the OpenAPI spec for CRM+ |
| "How does the Raise webhook signature verification work? Show me the code." | Maps to a documented workflow with code |
| "What are the trade-offs between webhooks and polling for the three Virtuous APIs?" | Cross-product question that pulls from multiple pages |
| "What's the documented retry pattern for 429 responses?" | Maps to Error Recovery Patterns content |
| "Walk me through the steps to certify an integration through the Integration Pathway." | Maps to Partner Program content |
### Less effective questions
| Question | Why it doesn't work as well |
| -------------------------------------------------- | ----------------------------------------------- |
| "Is Virtuous a good CRM?" | The docs don't cover product positioning |
| "How much does CRM+ cost?" | Pricing isn't in the docs |
| "Should I integrate with Virtuous or Salesforce?" | The docs don't make comparative recommendations |
| "Explain the history of donor management" | Out of scope |
| "Write me a complete production-ready integration" | Too broad — break into smaller questions |
If the assistant can't find relevant content, it'll say so rather than fabricating an answer.
## Building on the current page's context
When you ask a question, the assistant uses the page you're reading as context. This means follow-up questions often work better than full-context restatements:
| Less effective | More effective (with page context) |
| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| "What does the CRM+ Contact create endpoint return?" (asked from a random page) | Same question asked from the Contact Create workflow page |
| "What's the difference between Concepts and Workflows?" (general) | "How is this concept used in actual workflows?" (asked from a Concepts page) |
| "Show me the audit findings" (general) | "Which audit findings are referenced here?" (asked from a specific page) |
For best results, navigate to the most relevant page first, then ask. The assistant will combine the page content with the question to produce a contextually-aware answer.
## Highlighting text to ask about it
Sometimes the question you want to ask is about a specific piece of text on the page. The assistant supports this directly:
1. **Highlight** the text or code block you want to ask about
2. Click the **Add to assistant** button that appears
3. The assistant chat panel opens with that text included as context
4. Type your question (or use one of the assistant's suggested follow-ups)
This works for prose text and for code blocks. The "Ask AI" button is also available within code blocks specifically — useful when you're looking at a complex code sample and want to understand it.
You can add **multiple highlights** to a single conversation. The assistant uses them all as context.
## Attaching files for context
For questions where the answer depends on something the docs don't know about — your existing code, a screenshot of an error, your data structure — you can attach files to the assistant chat.
### What you can attach
| Type | Supported formats |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Images** | JPEG, PNG, GIF, WebP, SVG |
| **Documents** | PDF |
| **Code and text files** | JavaScript (`.js`, `.jsx`, `.mjs`, `.cjs`), TypeScript (`.ts`, `.tsx`), Python, HTML, CSS, Markdown, MDX, JSON, YAML, XML, SQL, CSV, plain text, shell scripts (`.sh`, `.bash`, `.env`), GraphQL, TOML, Go, Rust, Ruby, Java, Kotlin, Swift, C (`.c`, `.h`), C++ (`.cpp`, `.hpp`), C#, PHP, Lua, R, Scala |
### Limits
* **Maximum file size:** 5 MB per attachment
* **Maximum attachments per message:** 10
### When attachments help
| Scenario | What to attach |
| --------------------------------------------------------------- | ------------------------------------------ |
| "Why is this code not working?" | The relevant source file |
| "Why am I seeing this error?" | A screenshot of the error |
| "How do I integrate this OpenAPI schema with the Virtuous API?" | The OpenAPI JSON/YAML |
| "Does this data match the expected shape for /users?" | A sample of your data (sanitized) as JSON |
| "How should I model this in my Postgres schema?" | A screenshot or SQL of your current schema |
The assistant treats attached files as context for its answer. It doesn't store them after the conversation — they're used to generate the response, not retained.
**Don't attach files containing sensitive data.** Customer data, API tokens, production secrets, internal credentials — none of this should be pasted into the assistant. The assistant is for documentation help, not for processing sensitive material.
## How the assistant handles questions it can't answer
If the assistant searches the docs and doesn't find content that answers your question, it'll say so directly rather than fabricating an answer. You'll typically see something like:
> "I don't have information about that in the Virtuous documentation. You may want to contact the Virtuous support team for this question."
When this happens, your options are:
| Option | When to use it |
| ------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **Rephrase the question** | Sometimes the docs do cover the topic but the assistant needs a different angle |
| **Browse manually** | Use [Search and Navigation](/virtuous/docs-guide/search-and-navigation) to look directly |
| **Check the OpenAPI spec** | For specific endpoint behavior — use the [API Playground](/virtuous/docs-guide/api-playground) |
| **Reach out to your Partner Manager** | For program or business questions |
| **Contact support** | For account-specific or production-issue questions |
The assistant being honest about limits is intentional — it's better than confidently wrong answers.
## What gets indexed (and what doesn't)
The assistant searches the **published** Virtuous API Docs — everything you can see at `docs.virtuous.org`. A few specifics:
| Content | Indexed |
| ------------------------------------------------------------ | ----------------------- |
| All published pages in CRM+, Raise, Volunteer, Virtuous tabs | ✓ |
| OpenAPI specifications | ✓ |
| Code examples and snippets in docs | ✓ |
| Embedded diagrams and tables | ✓ (the textual content) |
| Draft branches or preview deployments | ✗ Not indexed |
| Hidden pages (unless explicitly opted in) | ✗ Not by default |
This means the assistant answers from the **current published state** of the docs. As content is updated, the assistant's answers reflect the updates immediately.
## What the assistant won't do
A few things to be clear about:
| Won't do | Why |
| ------------------------------------------------- | -------------------------------------------------------------------- |
| Make Virtuous API calls on your behalf | The assistant is for documentation help; it doesn't call APIs |
| Access your Virtuous account data | The assistant doesn't have credentials to your account |
| Save your conversation across sessions by default | Conversations are session-scoped unless you take action to save them |
| Modify the docs | Read-only — same as any reader |
| Provide pricing or account-specific information | Not in the docs |
| Make commercial commitments on Virtuous's behalf | The assistant is informational, not transactional |
The assistant is a **documentation companion**, not a runtime tool or sales interface.
## Practical workflows
A few patterns that emerge naturally:
### "I'm stuck on a specific concept"
1. Navigate to the most relevant Concepts page
2. Open the assistant (Cmd + I)
3. Ask the specific question — the assistant uses the page as context
4. Follow the citations to read more
### "I need to write code that does X"
1. Open the assistant from anywhere
2. Ask: "Write me a JavaScript function that does X. Use the Virtuous API patterns from the docs."
3. The assistant generates code grounded in documented patterns
4. Copy the code; follow the citations to verify the underlying patterns
### "I'm debugging an error response"
1. Open the assistant
2. Paste the error response (or attach a screenshot)
3. Ask what the error means and what the documented recovery is
4. Apply the suggested approach
### "I'm comparing options across products"
1. Open the assistant
2. Ask: "Compare how CRM+ and Raise handle webhook signature verification."
3. The assistant pulls from both products and synthesizes a comparison
4. Follow citations to dive deeper on either product
### "I want to share a question with a teammate"
1. Construct the question
2. Build a deep-link URL: `https://docs.virtuous.org/some-relevant-page?assistant=`
3. Send the URL to your teammate; clicking it opens the assistant pre-loaded with your question
## Tips for getting the most out of the assistant
A handful of practices that consistently improve results:
| Tip | Why |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Be specific about the product** | "Volunteer API users" vs. "users" — disambiguates between CRM+, Raise, and Volunteer |
| **Ask for citations** | "Cite the specific docs pages" surfaces the underlying content so you can dive deeper |
| **Use follow-up questions** | Conversations build context; the second question often gets a better answer than the first |
| **Verify code samples** | Generated code is grounded in docs but still benefits from review — especially for error handling and edge cases |
| **Combine with the Playground** | Ask the assistant to explain an endpoint, then test it in the [Playground](/virtuous/docs-guide/api-playground) |
| **Iterate on prompts** | If the first answer isn't right, refine the question — the assistant doesn't see your intent, just your text |
## Privacy and trust
A few things to know about how the assistant handles your conversations:
| Topic | Detail |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **What's in the conversation** | Your questions, the docs content the assistant searched, attached files, and the assistant's answers |
| **Where the conversation runs** | In the browser; the assistant queries the docs index and language model providers on the backend |
| **Conversation retention** | Session-scoped by default; conversations don't persist across sessions unless you take action |
| **Sensitive data** | Don't paste customer data, API tokens, or production secrets into the assistant — treat it like any AI chat interface |
| **Account-level data** | The assistant doesn't have access to your Virtuous account — it only sees the public documentation |
## Where to go next
Send docs pages to your external AI tools (ChatGPT, Claude, Cursor, VS Code).
Connect your external AI development tools (Cursor, Claude Code) directly to the docs while you build.
The keyboard shortcuts and structured browsing patterns that complement the assistant.
Test API endpoints directly in the docs and copy the resulting code.