document discovery api

advanced/rest-api/discovery/create-topic.mdx

@@ -0,0 +1,3 @@
+---
+openapi: POST /chat/topic
+---

advanced/rest-api/discovery/generate-message.mdx

@@ -0,0 +1,3 @@
+---
+openapi: POST /chat/message
+---

advanced/rest-api/overview.mdx

@@ -1,12 +1,10 @@
 ---
-title: Introduction
+title: Overview
 ---
 
-<Check>
-  The Mintlify REST API is only available on the [Pro plan and above](https://mintlify.com/pricing).
-</Check>
+## Trigger Updates
 
-Leverage the external API to programmatically trigger an update when desired.
+Leverage the REST API to programmatically trigger an update when desired.
 The primary use-case will be to trigger updates. We will be adding more and more
 functionality to the API overtime. Let us know what else you want to see in
 [our community](https://mintlify.com/community)!
@@ -20,3 +18,28 @@ associated with the entire org and can be used across multiple deployments.
 <Frame>
   <img src="/images/external-api-key.png" />
 </Frame>
+
+## Discovery API
+
+The Discovery API allows you to embed an AI chat experience grounded in your docs and continually kept up to date into any application of your choosing.
+Responses include citations so you can point your users to the right places they need to get help.
+
+## Getting Started
+
+To get started, you'll need to generate a Discovery API key in the [dashboard](https://dashboard.mintlify.com/products/chat/widget):
+
+<Frame>
+  <img
+    alt="Create a Discovery API key"
+    src="/images/generate-discovery-api-key.png"
+  />
+</Frame>
+
+<Note>
+  The Discovery API token is a public token that can be referenced in your
+  frontend code whereas the API key is a server-side token that should be kept
+  secret.
+</Note>
+
+Now that you have an API key, check out our [example](https://github.com/mintlify/discovery-api-example) for how to use
+the API for AI chat. You can also see a deployed version of this example at [chat.mintlify.com](https://chat.mintlify.com).

advanced/rest-api/update-status.mdx → advanced/rest-api/update/status.mdx

@@ -1,4 +1,3 @@
 ---
 openapi: "GET /project/update-status/{statusId}"
-hideApiMarker: true
 ---

advanced/rest-api/trigger-update.mdx → advanced/rest-api/update/trigger.mdx

@@ -1,4 +1,3 @@
 ---
 openapi: "POST /project/update/{projectId}"
-hideApiMarker: true
 ---

discovery-openapi.json

@@ -0,0 +1,100 @@
+{
+  "openapi": "3.0.1",
+  "info": {
+    "title": "Mintlify Discovery API",
+    "description": "An API to integrate Mintlify discovery features into your product.",
+    "version": "1.0.0"
+  },
+  "servers": [
+    {
+      "url": "https://api-dsc.mintlify.com/v1"
+    }
+  ],
+  "security": [
+    {
+      "bearerAuth": []
+    }
+  ],
+  "paths": {
+    "/chat/topic": {
+      "post": {
+        "summary": "Create a chat topic",
+        "description": "Creates a topic to manage message history for a given AI chat conversation.",
+        "responses": {
+          "200": {
+            "description": "Topic created successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "topicId": {
+                      "type": "string",
+                      "description": "The id of the created topic."
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/chat/message": {
+      "post": {
+        "summary": "Generate a message completion",
+        "description": "Generate a completion in response to a user query",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["topicId", "message"],
+                "properties": {
+                  "topicId": {
+                    "type": "string",
+                    "description": "The topic ID to associate this message with"
+                  },
+                  "message": {
+                    "type": "string",
+                    "description": "The user message to generate a completion for"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Topic created successfully",
+            "headers": {
+              "X-Mintlify-Base-Url": {
+                "schema": {
+                  "type": "string"
+                },
+                "description": "The base URL for the Mintlify documentation"
+              }
+            },
+            "content": {
+              "text/plain": {
+                "schema": {
+                  "type": "string",
+                  "description": "A text stream in the form `<response>||[chunks]`. The chunks are parts of your docs that most closely matched the user query. Each has the following format: \n ```\n { \n \tid: string;\n \tlink: string;\n \tchunk_html: string;\n \tmetadata: {\n \t\ttitle?: string\n \t}\n} \n``` \n The links are relative links with your docs URL intended as the host. To get an absolute link to your docs, you can use the `X-Mintlify-Base-Url` header as the host and construct a fully-qualified URL."
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "bearerAuth": {
+        "type": "http",
+        "scheme": "bearer"
+      }
+    }
+  }
+}

mint.json

@@ -182,11 +182,22 @@
           "group": "REST API",
           "pages": [
             "advanced/rest-api/overview",
-            "advanced/rest-api/trigger-update",
-            "advanced/rest-api/update-status"
+            {
+              "group": "Updates",
+              "pages": [
+                "advanced/rest-api/update/trigger",
+                "advanced/rest-api/update/status"
+              ]
+            },
+            {
+              "group": "Discovery API",
+              "pages": [
+                "advanced/rest-api/discovery/create-topic",
+                "advanced/rest-api/discovery/generate-message"
+              ]
+            }
           ]
-        },
-        "settings/authentication"
+        }
       ]
     },
     {