Improve chat API documentation clarity based on customer feedback #3280
Conversation
Based on customer support feedback, this commit enhances the chat completions documentation with:
- Added link to index conversation settings for better content optimization
- Clarified that PATCH /chats/{workspace}/settings automatically creates workspaces
- Added explicit privacy section stating no conversation data is stored
- Improved workspace explanation in getting started guide
- Added conversation management example showing stateless nature
- Made documentation more welcoming and easier to understand
These changes address common customer questions and make the complex chat feature more approachable.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <[email protected]>
WalkthroughDocumentation was updated to enhance guidance on AI chat workspaces, conversation management, and privacy. New sections explain workspace concepts, provide code examples for handling conversation history in JavaScript and Python, and clarify that conversation context is not stored server-side. A Python code sample was added for typo tolerance settings. Changes
Poem
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
guides/ai/getting_started_with_chat.mdx (1)
282-344: Minor: consider tightening JS sample to avoid unhandled promise at top levelThe snippet uses
awaitat the top level; some bundlers still require it to be wrapped in an async function or top-levelawaitsupport. Not critical, but you may want to wrap the snippet in an IIFE for portability.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
guides/ai/getting_started_with_chat.mdx(3 hunks)reference/api/chats.mdx(7 hunks)snippets/samples/code_samples_typo_tolerance_guide_5.mdx(1 hunks)
🧰 Additional context used
🪛 LanguageTool
reference/api/chats.mdx
[uncategorized] ~574-~574: Loose punctuation mark.
Context: ...the scenes. Arguments: - call_id: Unique identifier to track the search o...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~597-~597: Loose punctuation mark.
Context: ...s and results. Arguments: - role: Message author role ("user" or "assista...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~621-~621: Loose punctuation mark.
Context: ...rification. Arguments: - call_id: Matches the call_id from `_meiliSearc...
(UNLIKELY_OPENING_PUNCTUATION)
🔇 Additional comments (2)
snippets/samples/code_samples_typo_tolerance_guide_5.mdx (1)
18-22: Python snippet looks correct – no action neededThe call signature, dict syntax, and key casing (
disableOnNumbers) match the REST payload and the Python SDK expectations.reference/api/chats.mdx (1)
11-13: Verify target anchor of the “conversation settings” linkThe link points to
/reference/api/settings#conversation.
Double-check that the actual heading ID on the settings page is indeedconversation; otherwise users will land at the top of the page instead of the intended section.
- Removed duplicate "Understanding workspaces" section in getting_started_with_chat.mdx - Replaced non-standard Capsule component with built-in Note component in chats.mdx These changes address PR feedback to prevent duplicate anchors and ensure compatibility with the documentation build system. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (4)
reference/api/chats.mdx (2)
402-414: Great addition, but consider tightening the wordingThe bullets already state that no data is stored. The opening sentence repeats the same idea nearly verbatim.
A single concise sentence followed by the bullet list would read better and reduce redundancy.
573-577: Minor formatting glitch after “Arguments” headingThere is a double space before the line break, triggering the LanguageTool UNLIKELY_OPENING_PUNCTUATION warning.
Removing the extra space silences the linter without affecting rendering.guides/ai/getting_started_with_chat.mdx (2)
275-299: Provide full-context snippet or add a note
clientis referenced but never declared in this code block, andawaitis used at top level.
Either:
- Prepend the snippet with the two-line client instantiation (as shown earlier), or
- Add a short sentence like “Assume
clientis defined as in the previous section and that your environment supports top-levelawait.”This prevents cut-and-paste frustrations.
301-325: Python snippet: showclientcreation for completenessSame context issue as the JS example. A one-liner creating
client(or a brief comment referring back) will make the example self-contained.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
guides/ai/getting_started_with_chat.mdx(2 hunks)reference/api/chats.mdx(7 hunks)
🧰 Additional context used
🪛 LanguageTool
reference/api/chats.mdx
[uncategorized] ~574-~574: Loose punctuation mark.
Context: ...the scenes. Arguments: - call_id: Unique identifier to track the search o...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~597-~597: Loose punctuation mark.
Context: ...s and results. Arguments: - role: Message author role ("user" or "assista...
(UNLIKELY_OPENING_PUNCTUATION)
[uncategorized] ~621-~621: Loose punctuation mark.
Context: ...rification. Arguments: - call_id: Matches the call_id from `_meiliSearc...
(UNLIKELY_OPENING_PUNCTUATION)
⏰ Context from checks skipped due to timeout of 90000ms (1)
- GitHub Check: Mintlify Deployment
🔇 Additional comments (3)
reference/api/chats.mdx (2)
11-13: Verify anchor correctness for new “conversation settings” link
/reference/api/settings#conversationlooks plausible, but the settings page usually namespaces subsections as#conversation-settings.
Please double-check the generated anchor in the target file to avoid a broken link.
47-49: Nice UX clarificationCalling out the auto-creation of workspaces removes a common stumbling block.
No further action required.guides/ai/getting_started_with_chat.mdx (1)
24-33: Duplicate section issue resolved – nice cleanup
| - `role`: Message author role ("user" or "assistant") | ||
| - `content`: Message content (for tool results) |
There was a problem hiding this comment.
Incorrect value in role description
The description says either role or assistant – the first option should be user.
- "description": "The role of the messages author, either `role` or `assistant`"
+ "description": "The role of the message author, either `user` or `assistant`"Committable suggestion skipped: line range outside the PR's diff.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~597-~597: Loose punctuation mark.
Context: ...s and results. Arguments: - role: Message author role ("user" or "assista...
(UNLIKELY_OPENING_PUNCTUATION)
🤖 Prompt for AI Agents
In reference/api/chats.mdx at lines 597 to 598, the description of the `role`
field incorrectly states the possible values as "role" or "assistant". Update
the description to correctly specify that `role` can be either "user" or
"assistant" to accurately reflect the message author roles.
Summary
This PR improves the chat completions documentation based on feedback from customer support interactions. The changes make the documentation more welcoming and easier to understand for users setting up conversational search.
Changes
API Reference Updates (
/reference/api/chats.mdx)PATCH /chats/{workspace}/settingsautomatically creates workspaces if they don't existGetting Started Guide Updates (
/guides/ai/getting_started_with_chat.mdx)Related Issue
Based on customer support feedback about chat completions feature documentation.
Test plan
npm run marklint)npm run proselint)🤖 Generated with Claude Code
Summary by CodeRabbit
/chatsAPI documentation with tips on conversation settings, clarification on workspace creation, and a new section on privacy and data storage.