diff --git a/api-reference/endpoints/ask-question.mdx b/api-reference/endpoints/ask-question.mdx
index d546b42..8ab2a72 100644
--- a/api-reference/endpoints/ask-question.mdx
+++ b/api-reference/endpoints/ask-question.mdx
@@ -31,6 +31,10 @@ To ask follow-up questions, include the `session_id` from a previous response in
Maintain conversation context for follow-up questions. When a question is asked, the response includes a session_id that can be used in subsequent requests. On the Gurubase platform, these conversation sessions are called "Binges".
+
+ External user identifier for tracking user-specific conversation sessions. When provided, this ID is stored in the session. If a session already exists with a different external_user_id, the request will be rejected.
+
+
Fetch an existing answer. Do not ask a new question (generally used after streaming to fetch the answer fields like references etc.).
@@ -125,6 +129,12 @@ When `stream=true`, the response will be a text stream containing only the answe
"msg": "Request was throttled. Expected available in 56 seconds."
}
```
+
+```json 400
+{
+ "msg": "External user ID mismatch for this session. Code: S-902"
+}
+```
## Code Examples
diff --git a/api-reference/endpoints/delete-session.mdx b/api-reference/endpoints/delete-session.mdx
new file mode 100644
index 0000000..36abb71
--- /dev/null
+++ b/api-reference/endpoints/delete-session.mdx
@@ -0,0 +1,74 @@
+---
+title: 'Delete Session'
+api: 'DELETE /sessions/{session_id}/delete/'
+description: 'Delete a conversation session'
+---
+
+Delete a conversation session (binge).
+
+## Path Parameters
+
+
+ The unique identifier of the session to delete
+
+
+### Response
+
+
+ Success message indicating the session was deleted
+
+
+
+ The ID of the deleted session
+
+
+
+```json 200
+{
+ "msg": "Session deleted successfully",
+ "session_id": "1b9e86c9-87a8-472a-a6bf-6522e89b2de8"
+}
+```
+
+```json 400
+{
+ "msg": "Binge ID is required"
+}
+```
+
+```json 400
+{
+ "msg": "Session is already deleted"
+}
+```
+
+```json 401
+{
+ "msg": "Invalid API key"
+}
+```
+
+```json 403
+{
+ "msg": "Forbidden"
+}
+```
+
+```json 404
+{
+ "msg": "Session not found"
+}
+```
+
+```json 404
+{
+ "msg": "Guru type not found"
+}
+```
+
+```json 429
+{
+ "msg": "Request was throttled. Expected available in 56 seconds."
+}
+```
+
diff --git a/api-reference/endpoints/get-session.mdx b/api-reference/endpoints/get-session.mdx
new file mode 100644
index 0000000..b88c63d
--- /dev/null
+++ b/api-reference/endpoints/get-session.mdx
@@ -0,0 +1,224 @@
+---
+title: 'Get Session'
+api: 'POST /sessions/{session_id}/conversation/'
+description: 'Retrieve a complete conversation session'
+---
+
+Retrieve a complete conversation session (binge) including all questions and answers in the conversation chain, ordered chronologically.
+
+## Path Parameters
+
+
+ The unique identifier of the session to retrieve
+
+
+### Response
+
+
+ Unique identifier for the session. This has the same meaning as `session_id`.
+
+
+
+ Slug of the initial question that started this conversation session
+
+
+
+ Timestamp when the session was created (ISO format)
+
+
+
+ Timestamp when the session was last used (ISO format)
+
+
+
+ Array of messages in the conversation, ordered chronologically
+
+
+
+ Unique identifier for the message
+
+
+ Human-readable slug for the message
+
+
+ The original question asked by the user
+
+
+ The enhanced/processed question used by the AI
+
+
+ The AI's response in Markdown format
+
+
+ Timestamp when the message was created (ISO format)
+
+
+ Timestamp when the message was last updated (ISO format)
+
+
+ Array of reference sources used to generate the answer
+
+
+
+ URL of the reference
+
+
+ Icon URL for the reference source
+
+
+ Title of the reference
+
+
+
+
+ Confidence score of the answer (0-100)
+
+
+ Slug of the parent message (for follow-up questions)
+
+
+ Source of the question (e.g., "USER", "api", "web", "slack")
+
+
+ User's vote on the answer (if any). Can be "upvote", "downvote", or null
+
+
+
+
+
+```json 200
+{
+ "binge_id": "1b9e86c9-87a8-472a-a6bf-6522e89b2de8",
+ "root_question_slug": "what-is-gurubase-e2dd49bd-45da-4915-8ee0-3a1c09ee97a1",
+ "date_created": "2025-07-30T14:11:45.421172+00:00",
+ "last_used": "2025-07-30T14:13:09.459496+00:00",
+ "conversation": [
+ {
+ "id": "2183",
+ "slug": "what-is-gurubase-e2dd49bd-45da-4915-8ee0-3a1c09ee97a1",
+ "user_question": "what is gurubase",
+ "question": "What is Gurubase?",
+ "answer": "# What is Gurubase?\n\nGurubase is a platform that transforms your existing content into intelligent, topic-specific AI assistants known as \"Gurus.\" These AI-powered assistants are designed to answer questions, provide support, and guide users through your documentation, code, and knowledge base. Gurubase supports a wide range of data sources, including websites, PDF documents, Excel files, GitHub repositories, Confluence documents, Zendesk tickets, Jira issues, and YouTube videos, among others. \n\nThe platform allows for seamless integration into existing workflows through website widgets, chatbots, and APIs. It offers flexible deployment options, including a hosted platform at Gurubase.io and an enterprise self-hosted solution. Key features of Gurubase include advanced AI Q&A capabilities, multi-source integration, real-time synchronization, and codebase intelligence. These features ensure that the knowledge base remains current and accurate, providing reliable responses to user queries. For more detailed information, you can visit the [Gurubase Introduction](https://docs.gurubase.ai/introduction) page.",
+ "date_created": "2025-07-30T14:11:45.426114+00:00",
+ "date_updated": "2025-07-30T14:14:37.789405+00:00",
+ "references": [
+ {
+ "link": "https://docs.gurubase.ai/introduction",
+ "icon": "https://mintlify.s3-us-west-1.amazonaws.com/gurubase/_generated/favicon/favicon-32x32.png?v=3",
+ "title": "Welcome to Gurubase - Gurubase"
+ },
+ {
+ "link": "https://docs.gurubase.ai/guides/create-guru",
+ "icon": "https://mintlify.s3-us-west-1.amazonaws.com/gurubase/_generated/favicon/favicon-32x32.png?v=3",
+ "title": "Create Your First Guru - Gurubase"
+ }
+ ],
+ "trust_score": 90,
+ "parent_slug": null,
+ "source": "USER",
+ "user_vote": "downvote"
+ },
+ {
+ "id": "2184",
+ "slug": "add-website-to-guru-knowledge-base-0ad07b24-1c30-4245-a1d9-9ea26d7c039e",
+ "user_question": "How can I add a website to my Guru's knowledge base?",
+ "question": "How to add a website to my Guru's knowledge base?",
+ "answer": "# How to add a website to my Guru's knowledge base?\n\nTo add a website to your Guru's knowledge base in Gurubase, follow these steps:\n\n1. **Access the Dashboard**: Navigate to your Gurubase dashboard. If you are using a self-hosted version, you can access it at your local instance URL.\n\n2. **Create or Select a Guru**: If you haven't created a Guru yet, you will need to do so. Click on the \"Create New Guru\" button to start the setup process. If you already have a Guru, select it from your list.\n\n3. **Configure Basic Settings**: During the creation process, you will need to configure basic settings such as the Guru's name, logo, and topics. These settings help define the scope and expertise of your Guru.\n\n4. **Add Knowledge Sources**: \n - Go to the section where you can add knowledge sources.\n - **Websites**: Enter the URLs of the websites you want to include. Gurubase allows you to index website content by importing sitemaps or crawling the website. This feature enables the Guru to answer questions based on the indexed content of the website.\n\n5. **Publish Your Guru**: Once you have added the website URLs and any other knowledge sources, click \"Publish Guru.\" This action will initiate the indexing process, where Gurubase will process and embed the content from the provided sources into your Guru's knowledge base.\n\n6. **Manage and Update**: After publishing, you can manage your website sources by editing, deleting, or reindexing them to ensure the information remains current and accurate.\n\nFor more detailed guidance, you can refer to the [Create Your First Guru](https://docs.gurubase.ai/guides/create-guru) page on the Gurubase documentation site.",
+ "date_created": "2025-07-30T14:12:29.647988+00:00",
+ "date_updated": "2025-07-30T14:12:33.309291+00:00",
+ "references": [
+ {
+ "link": "https://docs.gurubase.ai/integrations/website-widget",
+ "icon": "https://mintlify.s3-us-west-1.amazonaws.com/gurubase/_generated/favicon/favicon-32x32.png?v=3",
+ "title": "Website Widget Integration - Gurubase"
+ },
+ {
+ "link": "https://docs.gurubase.ai/guides/create-guru",
+ "icon": "https://mintlify.s3-us-west-1.amazonaws.com/gurubase/_generated/favicon/favicon-32x32.png?v=3",
+ "title": "Create Your First Guru - Gurubase"
+ },
+ {
+ "link": "https://github.com/gurubase/gurubase-widget/tree/master/README.md",
+ "icon": "https://github.com/favicon.ico",
+ "title": "README.md"
+ },
+ {
+ "link": "https://github.com/gurubase/gurubase-widget/tree/master/examples/pure_js/README.md",
+ "icon": "https://github.com/favicon.ico",
+ "title": "README.md"
+ },
+ {
+ "link": "https://github.com/gurubase/gurubase-widget/tree/master/examples/remix/README.md",
+ "icon": "https://github.com/favicon.ico",
+ "title": "README.md"
+ },
+ {
+ "link": "https://github.com/gurubase/gurubase-widget/tree/master/examples/mintlify/README.md",
+ "icon": "https://github.com/favicon.ico",
+ "title": "README.md"
+ },
+ {
+ "link": "https://github.com/gurubase/gurubase-widget/tree/master/examples/mintlify/gurubase.js",
+ "icon": "https://github.com/favicon.ico",
+ "title": "gurubase.js"
+ }
+ ],
+ "trust_score": 90,
+ "parent_slug": "what-is-gurubase-e2dd49bd-45da-4915-8ee0-3a1c09ee97a1",
+ "source": "USER",
+ "user_vote": null
+ },
+ {
+ "id": "2185",
+ "slug": "control-pdf-visibility-guru-knowledge-base-1b3689ca-5445-409b-81e7-8bcfdaf00df9",
+ "user_question": "How can I control the visibility of my PDF documents within my Guru's knowledge base?",
+ "question": "How to control PDF visibility in my Guru's knowledge base?",
+ "answer": "# How to control PDF visibility in my Guru's knowledge base?\n\nTo control the visibility of PDF documents within your Guru's knowledge base in Gurubase, follow these steps:\n\n1. **Access the Dashboard**: Navigate to your Gurubase dashboard where you manage your Guru.\n\n2. **Locate the PDF Source**: Find the PDF document you wish to manage. This can be done by accessing the list of knowledge sources associated with your Guru.\n\n3. **Open the PDF Management Interface**: Click the menu icon (⋮) next to the PDF source you want to manage. This will open the management options for that specific document.\n\n4. **Toggle Visibility Settings**: \n - You will see options to toggle between \"Public\" and \"Private\" visibility settings.\n - **Private PDFs**: These are accessible only to you and your team members. They will not be visible in answer references or citations provided by the Guru.\n - **Public PDFs**: These are visible in answer references and citations, allowing users to access the content when the Guru provides answers.\n\n5. **Save Changes**: Ensure that you save any changes you make to the visibility settings to apply them effectively.\n\nBy managing the visibility settings, you can control who has access to the content of your PDF documents, ensuring that sensitive information remains protected while still allowing public access to non-sensitive documents. For more detailed guidance, you can refer to the [Create Your First Guru](https://docs.gurubase.ai/guides/create-guru) page on the Gurubase documentation site.",
+ "date_created": "2025-07-30T14:13:09.444277+00:00",
+ "date_updated": "2025-07-30T14:14:17.257488+00:00",
+ "references": [
+ {
+ "link": "https://docs.gurubase.ai/guides/create-guru",
+ "icon": "https://mintlify.s3-us-west-1.amazonaws.com/gurubase/_generated/favicon/favicon-32x32.png?v=3",
+ "title": "Create Your First Guru - Gurubase"
+ }
+ ],
+ "trust_score": 100,
+ "parent_slug": "add-website-to-guru-knowledge-base-0ad07b24-1c30-4245-a1d9-9ea26d7c039e",
+ "source": "USER",
+ "user_vote": "upvote"
+ }
+ ]
+}
+```
+
+```json 400
+{
+ "msg": "Binge ID is required"
+}
+```
+
+```json 401
+{
+ "msg": "Invalid API key"
+}
+```
+
+```json 403
+{
+ "msg": "You don't have access to this binge"
+}
+```
+
+```json 404
+{
+ "msg": "Binge not found"
+}
+```
+
+```json 429
+{
+ "msg": "Request was throttled. Expected available in 56 seconds."
+}
+```
+
diff --git a/api-reference/endpoints/list-sessions.mdx b/api-reference/endpoints/list-sessions.mdx
new file mode 100644
index 0000000..f2c1568
--- /dev/null
+++ b/api-reference/endpoints/list-sessions.mdx
@@ -0,0 +1,130 @@
+---
+title: 'List Sessions'
+api: 'POST /{guru_slug}/sessions/'
+description: 'Retrieve conversation sessions for a Guru'
+---
+
+Retrieve conversation sessions for a specific Guru. This endpoint supports pagination and search functionality, returning sessions grouped by time periods.
+
+## Path Parameters
+
+
+ The slug of the Guru to retrieve sessions for
+
+
+### Body Parameters
+
+
+ The page number for pagination. Must be a positive integer.
+
+
+
+ Search query to filter sessions. Searches across question text, user questions, and session slugs.
+
+
+
+ Filter sessions by external user ID. When provided, only returns sessions associated with this external user ID.
+
+
+### Response
+
+
+ Sessions from today
+
+
+
+ Unique identifier for the session
+
+
+ Timestamp when the session was last used
+
+
+ The slug of the guru type
+
+
+ The name of the guru type
+
+
+ The name/title of the root question that started this session
+
+
+ The slug of the root question
+
+
+ Link to the root question
+
+
+
+
+
+ Sessions from the last 7 days (excluding today)
+
+
+
+ Sessions older than 7 days
+
+
+
+ Whether there are more sessions available beyond the current page
+
+
+
+```json 200
+{
+ "today": [
+ {
+ "last_used": "2025-07-29T10:23:27.535170Z",
+ "id": "0389210e-720d-442c-8fd4-2c6ecda89627",
+ "guru_type_slug": "gurubase",
+ "guru_type_name": "Gurubase",
+ "root_question_name": "What is Gurubase?",
+ "root_question_slug": "what-is-gurubase-73d46ea7-12b5-49c7-ab5e-1dffdb8b71de-69e06b42-d549-4624-8400-768f7388361a",
+ "root_question_link": ""
+ }
+ ],
+ "last_week": [
+ {
+ "last_used": "2025-07-28T16:05:10.579616Z",
+ "id": "25dffa55-b947-41af-9bca-a2361afca8be",
+ "guru_type_slug": "gurubase",
+ "guru_type_name": "Gurubase",
+ "root_question_name": "Does Gurubase support Slack ?",
+ "root_question_slug": "does-gurubase-support-slack-64911f4a-03c7-4105-a477-80d68f030dfe",
+ "root_question_link": ""
+ }
+ ],
+ "older": [],
+ "has_more": false
+}
+```
+
+```json 400
+{
+ "msg": "Page number must be an integer"
+}
+```
+
+```json 401
+{
+ "msg": "Invalid API key"
+}
+```
+
+```json 403
+{
+ "msg": "Forbidden"
+}
+```
+
+```json 404
+{
+ "msg": "Guru type {guru_slug} not found"
+}
+```
+
+```json 429
+{
+ "msg": "Request was throttled. Expected available in 56 seconds."
+}
+```
+
diff --git a/api-reference/endpoints/semantic-search.mdx b/api-reference/endpoints/semantic-search.mdx
index dd93964..1e30ddd 100644
--- a/api-reference/endpoints/semantic-search.mdx
+++ b/api-reference/endpoints/semantic-search.mdx
@@ -18,6 +18,10 @@ Retrieve sources that are most relevant to a given question. This endpoint fetch
The question to find related sources for
+
+ Array of labels to filter sources by. If provided, only sources with matching labels will be returned. If multiple labels are provided, they are OR'ed. Meaning data sources belonging to any of those labels are returned.
+
+
### Response
The response contains an array of source objects and total count.
@@ -27,9 +31,10 @@ The response contains an array of source objects and total count.
Each source object contains:
- `title` (string): The title of the source document or page
- - `link` (string): The URL link to the source
+ - `link` (string): The URL link to the source (can be null for internal sources)
- `display_link` (boolean): Whether to display the link in the UI
- `icon_url` (string): URL of the icon representing the source
+ - `labels` (array): Array of labels associated with this source
@@ -44,60 +49,111 @@ The response contains an array of source objects and total count.
"title": "Slack Bot Integration - Gurubase",
"link": "https://docs.gurubase.ai/integrations/slack-bot",
"display_link": true,
+ "labels": [
+ "integrations",
+ "slack",
+ "bots"
+ ],
"icon_url": "https://mintlify.s3-us-west-1.amazonaws.com/gurubase/_generated/favicon/favicon-32x32.png?v=3"
},
{
"title": "GitHub Bot Integration - Gurubase",
"link": "https://docs.gurubase.ai/integrations/github-bot",
"display_link": true,
+ "labels": [
+ "integrations",
+ "github",
+ "bots"
+ ],
"icon_url": "https://mintlify.s3-us-west-1.amazonaws.com/gurubase/_generated/favicon/favicon-32x32.png?v=3"
},
{
"title": "Welcome to Gurubase - Gurubase",
"link": "https://docs.gurubase.ai/introduction",
"display_link": true,
+ "labels": [
+ "documentation",
+ "getting-started"
+ ],
"icon_url": "https://mintlify.s3-us-west-1.amazonaws.com/gurubase/_generated/favicon/favicon-32x32.png?v=3"
},
{
"title": "Quickstart - Gurubase",
"link": "https://docs.gurubase.ai/quickstart",
"display_link": true,
+ "labels": [
+ "documentation",
+ "getting-started",
+ "tutorial"
+ ],
"icon_url": "https://mintlify.s3-us-west-1.amazonaws.com/gurubase/_generated/favicon/favicon-32x32.png?v=3"
},
{
"title": "Create Your First Guru - Gurubase",
"link": "https://docs.gurubase.ai/guides/create-guru",
"display_link": true,
+ "labels": [
+ "documentation",
+ "guides",
+ "tutorial"
+ ],
"icon_url": "https://mintlify.s3-us-west-1.amazonaws.com/gurubase/_generated/favicon/favicon-32x32.png?v=3"
},
{
"title": "head.html",
"link": "https://github.com/gurubase/gurubase-widget/tree/master/examples/retype/_includes/head.html",
"display_link": true,
+ "labels": [
+ "code",
+ "github",
+ "widget",
+ "examples"
+ ],
"icon_url": "https://github.com/favicon.ico"
},
{
"title": "widget.js",
"link": "https://github.com/gurubase/gurubase-widget/tree/master/src/widget.js",
"display_link": true,
+ "labels": [
+ "code",
+ "github",
+ "widget",
+ "javascript"
+ ],
"icon_url": "https://github.com/favicon.ico"
},
{
"title": "Website Widget Integration - Gurubase",
"link": "https://docs.gurubase.ai/integrations/website-widget",
"display_link": true,
+ "labels": [
+ "integrations",
+ "widget",
+ "website"
+ ],
"icon_url": "https://mintlify.s3-us-west-1.amazonaws.com/gurubase/_generated/favicon/favicon-32x32.png?v=3"
},
{
"title": "Jira Integration - Gurubase",
"link": "https://docs.gurubase.ai/integrations/jira-bot",
"display_link": true,
+ "labels": [
+ "integrations",
+ "jira",
+ "bots"
+ ],
"icon_url": "https://mintlify.s3-us-west-1.amazonaws.com/gurubase/_generated/favicon/favicon-32x32.png?v=3"
},
{
"title": "API Reference - Gurubase",
"link": "https://docs.gurubase.ai/api-reference/introduction",
"display_link": true,
+ "labels": [
+ "documentation",
+ "api",
+ "reference"
+ ],
"icon_url": "https://mintlify.s3-us-west-1.amazonaws.com/gurubase/_generated/favicon/favicon-32x32.png?v=3"
}
],
diff --git a/mint.json b/mint.json
index 6fc044b..15d17c6 100644
--- a/mint.json
+++ b/mint.json
@@ -115,7 +115,10 @@
"api-reference/endpoints/analytics-export",
"api-reference/endpoints/record-vote",
"api-reference/endpoints/semantic-search",
- "api-reference/endpoints/transcribe-audio"
+ "api-reference/endpoints/transcribe-audio",
+ "api-reference/endpoints/list-sessions",
+ "api-reference/endpoints/get-session",
+ "api-reference/endpoints/delete-session"
]
}
],