Documentation page for Responses API (#872)

* document responses api

* overview on index page

* typo fix

* Copy editz

* Apply suggestions from code review

Co-authored-by: Nick Larew <[email protected]>
Co-authored-by: Andrew Steinheiser <[email protected]>

* NL feedback

---------

Co-authored-by: Ben Perlmutter <[email protected]>
Co-authored-by: Nick Larew <[email protected]>
Co-authored-by: Andrew Steinheiser <[email protected]>

Author: 4 people

docs/docs/index.md

@@ -7,7 +7,11 @@ description: MongoDB Knowledge Service
 
 The MongoDB Knowledge Service lets you learn about MongoDB using generative AI.
 
-## Server
+## Responses API
+
+To build MongoDB-related conversational AI applications, use the [Responses API](./server/responses-api.md). The Responses API is compatible with the OpenAI API and provides MongoDB-specific knowledge through retrieval-augmented generation.
+ 
+## Server OpenAPI Specification
 
 To call the MongoDB Knowledge Service API, refer to the [OpenAPI specification](/server/openapi/).
 

docs/docs/server/openapi.yaml

@@ -304,82 +304,7 @@ paths:
 
         You can rate or comment on a message using the [rateMessage](#operation/rateMessage) and [commentMessage](#operation/commentMessage) endpoints.
 
-        ### Basic Example Usage
-
-        Example usage with OpenAI client `openai`:
-        ```ts
-        import { OpenAI } from "openai";
-
-        const openai = new OpenAI({ baseURL: "https://knowledge.mongodb.com/api/v1" });
-
-        const response = await openai.responses.create({
-          model: "mongodb-chat-latest",
-          stream: true,
-          input: [
-            {
-              role: "user",
-              content: "So what's MongoDB anyways??",
-            },
-          ],
-          instructions: "You are located on the MongoDB Atlas cloud platform. Use that as context to inform your response."
-        });
-
-        for await (const event of response) {
-          console.log(event);
-        }
-        ```
-
-        Example usage with Vercel AI SDK client `@ai-sdk/openai` and `ai`:
-        ```ts
-        import { streamText } from "ai";
-        // NOTE: we are using the AI SDK v5-beta with LanguageModelV2
-        import { createOpenAI } from "@ai-sdk/openai";
-
-        const model = createOpenAI({
-          baseURL: origin + API_PREFIX,
-          apiKey: TEST_OPENAI_API_KEY,
-        }).responses("mongodb-chat-latest");
-
-        const result = await streamText({
-          model,
-          prompt: "What is MongoDB?",
-        });
-
-        for await (const chunk of result.toUIMessageStream()) {
-          console.log(chunk);
-        }
-        ```
-        **NOTE:** We currently only support streaming responses via `streamText`. Methods like `generateText` will not work.
-
-        ### Features
-
-        #### Retrieval-Informed Answers
-
-        By default, the API performs retrieval augmented generation under the hood
-        to generate accurate and up-to-date responses about MongoDB products.
-        If you provide custom tools to the API via the `tools` parameter,
-        the API will choose to use the tool or the retrieval tool based on the `tool_choice` parameter.
-
-        Default behavior is to allow the model to choose the tool to use.
-
-        #### Personality
-
-        The AI API has the personality of a helpful MongoDB assistant. You cannot change this core personality.
-
-        You can augment the personality via the `instructions` parameter. (E.g. "You are a technical services engineer at MongoDB. Use that as context to inform your response.")
-
-        #### Guardrail
-
-        The API features a guardrail that helps ensure the input is appropriate for a MongoDB assistant.
-        This helps ensure the API isn't used for irrelevant or malicious purposes.
-
-        #### Tracing and Storage
-
-        All messages to the chatbot are traced and stored if `store: true`.
-
-        For access to chatbot data, reach out to the Education AI team (`#ask-education-ai` on Slack).
-
-        All data retention is in line with MongoDB data retention policies.
+        For more information on using the Responses API, refer to the [Responses API documentation](./responses-api).
 
       tags:
         - Responses