Task/api external user #32
Conversation
WalkthroughThis update introduces new and enhanced API documentation for session management and semantic search features. It adds documentation for listing, retrieving, and deleting conversation sessions, updates the "Ask Question" and semantic search endpoints with new optional parameters, and adjusts the navigation configuration to include the new endpoints. Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant API
%% List Sessions
Client->>API: POST /{guru_slug}/sessions/ (with page_num, search_query, external_user_id)
API-->>Client: Sessions grouped by time period, has_more flag
%% Get Session
Client->>API: POST /sessions/{session_id}/conversation/
API-->>Client: Full conversation history for session_id
%% Delete Session
Client->>API: DELETE /sessions/{session_id}/delete/
API-->>Client: Success or error message
%% Ask Question (with external_user_id)
Client->>API: POST /{guru_slug}/answer/ (with optional external_user_id)
alt external_user_id matches session
API-->>Client: Answer response
else external_user_id mismatch
API-->>Client: 400 error (S-902)
end
%% Semantic Search (with labels)
Client->>API: POST /{guru_slug}/semantic-search/ (with optional labels)
API-->>Client: Sources filtered by labels, each with labels array
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~15 minutes Possibly related PRs
Note ⚡️ Unit Test Generation is now available in beta!Learn more here, or try it out under "Finishing Touches" below. 🪧 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 (8)
api-reference/endpoints/ask-question.mdx (2)
34-36: Clarify optionality & expected format ofexternal_user_idConsider adding either
required={false}or an explicit note that the value must be a string ≤ 256 chars (or whatever your limit is). This keeps the docs self-contained and helps client teams validate inputs.
132-137: Add an example request demonstrating the mismatch errorYou’ve documented the 400 response but not the request shape that triggers it.
Including a minimal JSON request with a conflictingexternal_user_idwill make the scenario crystal-clear.api-reference/endpoints/semantic-search.mdx (2)
21-24: State element type forlabelsarrayReaders will wonder whether labels are free-form strings, UUIDs, or IDs. Add something like
items="string"or a short sentence: “Each entry must be a non-empty string label name”.
34-38: Movelabelsfield description next to the existing ones for consistencyThe bullet list is now slightly out of order (
icon_urlis shown beforelabels). Swapping them keeps the response schema tidy and predictable.api-reference/endpoints/list-sessions.mdx (2)
17-19: Document maximum page size or expose apage_sizeparameter
page_numis documented, but without a way to control page size clients cannot anticipate result volume or optimise pagination.
31-66: Provide schema details forlast_weekandolderarrays as wellOnly the
todaygroup contains an expandable schema. Re-using the same expandable (or factoring it into a reusable component) for the other two keeps the docs symmetric and avoids reader confusion.api-reference/endpoints/delete-session.mdx (1)
25-43: Consider using HTTP 204 for successful deletionREST conventions typically return 204 No Content for a DELETE when nothing is returned beyond a confirmation. If you intentionally return a JSON payload, note the rationale so integrators know to expect a body.
api-reference/endpoints/get-session.mdx (1)
88-224: Group success & error examples with<CodeGroup>for cleaner UX.Presenting six standalone code blocks clutters the page. Mintlify supports:
<CodeGroup> <CodeGroup.Item title="200 – OK"> ```json { ... }</CodeGroup.Item>
<CodeGroup.Item title="400 – Bad Request">
{ "msg": "Binge ID is required" }</CodeGroup.Item>
…
This keeps the examples collapsible and aligned with the rest of the API docs. </blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used: CodeRabbit UI** **Review profile: CHILL** **Plan: Pro** <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between ba7bbea40eafd0599e60a3c68f777539590d62ae and cd56f8b8d000d22d637356c9f16f875132bcbd06. </details> <details> <summary>📒 Files selected for processing (6)</summary> * `api-reference/endpoints/ask-question.mdx` (2 hunks) * `api-reference/endpoints/delete-session.mdx` (1 hunks) * `api-reference/endpoints/get-session.mdx` (1 hunks) * `api-reference/endpoints/list-sessions.mdx` (1 hunks) * `api-reference/endpoints/semantic-search.mdx` (3 hunks) * `mint.json` (1 hunks) </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>📓 Path-based instructions (3)</summary> <details> <summary>**/*.mdx</summary> **📄 CodeRabbit Inference Engine (CLAUDE.md)** > `**/*.mdx`: Use MDX format for all documentation files > Use Mintlify components like <Card>, <CardGroup>, <CodeGroup> for rich content > Include practical examples and code snippets in documentation > Use images from /images/ directory for visual guides Files: - `api-reference/endpoints/delete-session.mdx` - `api-reference/endpoints/list-sessions.mdx` - `api-reference/endpoints/ask-question.mdx` - `api-reference/endpoints/get-session.mdx` - `api-reference/endpoints/semantic-search.mdx` </details> <details> <summary>api-reference/endpoints/**/*.mdx</summary> **📄 CodeRabbit Inference Engine (CLAUDE.md)** > API endpoint docs follow the structure in /api-reference/endpoints/ Files: - `api-reference/endpoints/delete-session.mdx` - `api-reference/endpoints/list-sessions.mdx` - `api-reference/endpoints/ask-question.mdx` - `api-reference/endpoints/get-session.mdx` - `api-reference/endpoints/semantic-search.mdx` </details> <details> <summary>mint.json</summary> **📄 CodeRabbit Inference Engine (CLAUDE.md)** > `mint.json`: Navigation structure is defined in mint.json under the navigation key > mint.json contains all site configuration, navigation, and settings Files: - `mint.json` </details> </details><details> <summary>🧠 Learnings (4)</summary> <details> <summary>api-reference/endpoints/delete-session.mdx (1)</summary> Learnt from: CR PR: Gurubase/gurubase-docs#0 File: CLAUDE.md:0-0 Timestamp: 2025-07-19T21:27:14.098Z Learning: Applies to api-reference/endpoints/**/*.mdx : API endpoint docs follow the structure in /api-reference/endpoints/ </details> <details> <summary>mint.json (3)</summary> Learnt from: CR PR: Gurubase/gurubase-docs#0 File: CLAUDE.md:0-0 Timestamp: 2025-07-19T21:27:14.098Z Learning: Applies to mint.json : mint.json contains all site configuration, navigation, and settings Learnt from: CR PR: Gurubase/gurubase-docs#0 File: CLAUDE.md:0-0 Timestamp: 2025-07-19T21:27:14.098Z Learning: Applies to mint.json : Navigation structure is defined in mint.json under the navigation key Learnt from: CR PR: Gurubase/gurubase-docs#0 File: CLAUDE.md:0-0 Timestamp: 2025-07-19T21:27:14.098Z Learning: Applies to api-reference/endpoints/**/*.mdx : API endpoint docs follow the structure in /api-reference/endpoints/ </details> <details> <summary>api-reference/endpoints/get-session.mdx (1)</summary> Learnt from: CR PR: Gurubase/gurubase-docs#0 File: CLAUDE.md:0-0 Timestamp: 2025-07-19T21:27:14.098Z Learning: Applies to api-reference/endpoints/**/*.mdx : API endpoint docs follow the structure in /api-reference/endpoints/ </details> <details> <summary>api-reference/endpoints/semantic-search.mdx (1)</summary> Learnt from: CR PR: Gurubase/gurubase-docs#0 File: CLAUDE.md:0-0 Timestamp: 2025-07-19T21:27:14.098Z Learning: Applies to api-reference/endpoints/**/*.mdx : API endpoint docs follow the structure in /api-reference/endpoints/ </details> </details> </details> <details> <summary>🔇 Additional comments (2)</summary><blockquote> <details> <summary>mint.json (1)</summary> `118-121`: **Verified: `get-session.mdx` Exists** The file `api-reference/endpoints/get-session.mdx` is present, so the navigation link won’t break. </details> <details> <summary>api-reference/endpoints/get-session.mdx (1)</summary> `1-5`: **Confirm HTTP verb for session conversation endpoint** - File: api-reference/endpoints/get-session.mdx - Front-matter currently reads: ```yaml title: 'Get Session' api: 'POST /sessions/{session_id}/conversation/'
- Since this operation “retrieves” a session, it likely should be a
GETrequest. If the backend really expectsGET, update to:-api: 'POST /sessions/{session_id}/conversation/' +api: 'GET /sessions/{session_id}/conversation/'Please verify the actual route/controller implementation (and any tests or nav entries) to confirm which HTTP verb is required, then adjust the docs accordingly.
Summary by CodeRabbit
New Features
Improvements
Documentation