From 64510d24ed2e9c00cf5addbdf0f78ae2a1d8c513 Mon Sep 17 00:00:00 2001 From: Nick K Date: Thu, 10 Jul 2025 20:21:01 -0700 Subject: [PATCH 1/5] Refactor API endpoint to generate assistant messages with updated request and response structures --- discovery-openapi.json | 121 +++++++++++++++++++++++++---------------- 1 file changed, 74 insertions(+), 47 deletions(-) diff --git a/discovery-openapi.json b/discovery-openapi.json index 2afde35cf..53ac1d1e0 100644 --- a/discovery-openapi.json +++ b/discovery-openapi.json @@ -16,55 +16,90 @@ } ], "paths": { - "/chat/topic": { + "/assistant/{domain}/message": { "post": { "x-mcp": { "enabled": true }, - "summary": "Create Assistant Chat Topic", - "description": "Creates a topic to manage message history for a given AI assistant conversation", - "responses": { - "200": { - "description": "Topic created successfully", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "topicId": { - "type": "string", - "description": "The id of the created topic." - } - } - } - } - } + "summary": "Generate Assistant Message", + "description": "Generate a message response for the assistant with the specified domain", + "parameters": [ + { + "name": "domain", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The domain identifier that can be found in the top left corner of the Mintlify dashboard" } - } - } - }, - "/chat/message": { - "post": { - "x-mcp": { - "enabled": true - }, - "summary": "Create Assistant Chat Message", - "description": "Generate a completion in response to a user query", + ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", - "required": ["topicId", "message"], + "required": [ + "fp", + "messages" + ], "properties": { - "topicId": { + "fp": { "type": "string", - "description": "The topic ID to associate this message with" + "description": "Fingerprint identifier" }, - "message": { + "threadId": { "type": "string", - "description": "The user message to generate a completion for" + "description": "Optional thread identifier for conversation continuity" + }, + "messages": { + "type": "array", + "items": { + "type": "object", + "properties": { + "role": { + "type": "string", + "enum": [ + "user", + "assistant", + "system" + ], + "description": "The role of the message sender" + }, + "content": { + "type": "string", + "description": "The content of the message" + }, + "id": { + "type": "string", + "description": "Unique identifier for the message" + } + }, + "required": [ + "role", + "content" + ] + }, + "description": "Array of messages in the conversation" + }, + "retrievalPageSize": { + "type": "number", + "default": 5, + "description": "Number of retrieval results to return" + }, + "filter": { + "type": "object", + "properties": { + "groups": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Optional array of group filters" + } + }, + "description": "Optional filter criteria for the search" } } } @@ -73,20 +108,12 @@ }, "responses": { "200": { - "description": "Topic created successfully", - "headers": { - "X-Mintlify-Base-Url": { - "schema": { - "type": "string" - }, - "description": "The base URL for the Mintlify documentation" - } - }, + "description": "Message generated successfully", "content": { - "text/plain": { + "application/json": { "schema": { - "type": "string", - "description": "A text stream in the form `||[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." + "type": "object", + "description": "A Response object that streams formatted data stream parts with the specified status, headers, and content. This matches what is expected from the AI SDK as documented at https://ai-sdk.dev/docs/ai-sdk-ui/streaming-data ." } } } @@ -103,4 +130,4 @@ } } } -} +} \ No newline at end of file From e9203e34cc0f64478d60fab5de7f99506720424c Mon Sep 17 00:00:00 2001 From: Nick K Date: Fri, 11 Jul 2025 09:43:43 -0700 Subject: [PATCH 2/5] Add Mintlify documentation and update API reference for assistant message generation --- README.md | 13 +++++++++ .../chat/create-assistant-message.mdx | 3 +++ api-reference/chat/create-topic.mdx | 3 --- api-reference/chat/generate-message.mdx | 3 --- discovery-openapi.json | 23 ++++++++-------- docs.json | 27 ++++++++++++++----- 6 files changed, 48 insertions(+), 24 deletions(-) create mode 100644 README.md create mode 100644 api-reference/chat/create-assistant-message.mdx delete mode 100644 api-reference/chat/create-topic.mdx delete mode 100644 api-reference/chat/generate-message.mdx diff --git a/README.md b/README.md new file mode 100644 index 000000000..f68992ccc --- /dev/null +++ b/README.md @@ -0,0 +1,13 @@ +# Mintlify Documentation + +Install the [Mintlify CLI](https://www.npmjs.com/package/mintlify) to preview the documentation changes locally. To install, use the following command + +``` +npm i -g mintlify +``` + +Run the following command at the root of your documentation (where mint.json is) + +``` +mintlify dev +``` diff --git a/api-reference/chat/create-assistant-message.mdx b/api-reference/chat/create-assistant-message.mdx new file mode 100644 index 000000000..0161d03f5 --- /dev/null +++ b/api-reference/chat/create-assistant-message.mdx @@ -0,0 +1,3 @@ +--- +openapi: POST /assistant/{domain}/message +--- diff --git a/api-reference/chat/create-topic.mdx b/api-reference/chat/create-topic.mdx deleted file mode 100644 index 30ad8b74f..000000000 --- a/api-reference/chat/create-topic.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -openapi: POST /chat/topic ---- \ No newline at end of file diff --git a/api-reference/chat/generate-message.mdx b/api-reference/chat/generate-message.mdx deleted file mode 100644 index 30a74c542..000000000 --- a/api-reference/chat/generate-message.mdx +++ /dev/null @@ -1,3 +0,0 @@ ---- -openapi: POST /chat/message ---- \ No newline at end of file diff --git a/discovery-openapi.json b/discovery-openapi.json index 53ac1d1e0..0006d7241 100644 --- a/discovery-openapi.json +++ b/discovery-openapi.json @@ -22,7 +22,7 @@ "enabled": true }, "summary": "Generate Assistant Message", - "description": "Generate a message response for the assistant with the specified domain", + "description": "Generates a response message from the assistant for the specified domain. For best results, use the [useChat hook from ai-sdk](ai-sdk.dev/docs/ai-sdk-ui/streaming-data) to send requests and handle responses. You can set `fp`, `threadId`, and `filter` in the `body` field of the options parameter passed to the hook.", "parameters": [ { "name": "domain", @@ -47,11 +47,11 @@ "properties": { "fp": { "type": "string", - "description": "Fingerprint identifier" + "description": "Browser fingerprint or arbitrary string identifier. There may be future functionality which allows you to get the messages for a given fingerprint" }, "threadId": { "type": "string", - "description": "Optional thread identifier for conversation continuity" + "description": "An optional identifier used to maintain conversation continuity across multiple messages. When provided, it allows the system to associate follow-up messages with the same conversation thread. The threadId is returned in the response as event.threadId when event.type === 'finish'." }, "messages": { "type": "array", @@ -81,7 +81,7 @@ "content" ] }, - "description": "Array of messages in the conversation" + "description": "Array of messages in the conversation. On the frontend, you will likely want to use the handleSubmit function from the @ai-sdk package's useChat hook to append user messages and handle streaming responses, rather than manually setting this array." }, "retrievalPageSize": { "type": "number", @@ -91,12 +91,13 @@ "filter": { "type": "object", "properties": { - "groups": { - "type": "array", - "items": { - "type": "string" - }, - "description": "Optional array of group filters" + "version": { + "type": "string", + "description": "Optional version filter" + }, + "language": { + "type": "string", + "description": "Optional language filter" } }, "description": "Optional filter criteria for the search" @@ -113,7 +114,7 @@ "application/json": { "schema": { "type": "object", - "description": "A Response object that streams formatted data stream parts with the specified status, headers, and content. This matches what is expected from the AI SDK as documented at https://ai-sdk.dev/docs/ai-sdk-ui/streaming-data ." + "description": "Response object that streams formatted data stream parts with the specified status, headers, and content. This matches what is expected from the AI SDK as documented at [ai-sdk.dev/docs/ai-sdk-ui/streaming-data](https://ai-sdk.dev/docs/ai-sdk-ui/streaming-data). Instead of writing your own parser, it is recommended to use the [useChat hook from ai-sdk as documented here](ai-sdk.dev/docs/ai-sdk-ui/streaming-data)." } } } diff --git a/docs.json b/docs.json index 3f5049fad..f80e6f23a 100644 --- a/docs.json +++ b/docs.json @@ -20,7 +20,12 @@ "groups": [ { "group": "Getting started", - "pages": ["index", "quickstart", "installation", "editor"] + "pages": [ + "index", + "quickstart", + "installation", + "editor" + ] }, { "group": "Core configuration", @@ -211,7 +216,9 @@ "groups": [ { "group": "API Reference", - "pages": ["api-reference/introduction"] + "pages": [ + "api-reference/introduction" + ] }, { "group": "Admin", @@ -223,8 +230,7 @@ { "group": "Assistant", "pages": [ - "api-reference/chat/create-topic", - "api-reference/chat/generate-message" + "api-reference/chat/create-assistant-message" ] } ] @@ -236,7 +242,9 @@ "groups": [ { "group": "Changelog", - "pages": ["changelog"] + "pages": [ + "changelog" + ] } ] } @@ -344,7 +352,12 @@ "background": "/images/thumbnail/background.svg" }, "contextual": { - "options": ["copy", "view", "chatgpt", "claude"] + "options": [ + "copy", + "view", + "chatgpt", + "claude" + ] }, "redirects": [ { @@ -484,4 +497,4 @@ "publicApiKey": "pk_76a6caa274e800f3ceff0b2bc6b9b9d82ab8" } } -} +} \ No newline at end of file From ec9474aa4f660b4efd10dc1ea31f8dd6129b658a Mon Sep 17 00:00:00 2001 From: Nick K Date: Fri, 11 Jul 2025 10:06:41 -0700 Subject: [PATCH 3/5] Update OpenAPI specification for assistant message generation with new request structure and additional properties --- discovery-openapi.json | 297 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 289 insertions(+), 8 deletions(-) diff --git a/discovery-openapi.json b/discovery-openapi.json index 0006d7241..ec26510b2 100644 --- a/discovery-openapi.json +++ b/discovery-openapi.json @@ -7,7 +7,7 @@ }, "servers": [ { - "url": "https://api-dsc.mintlify.com/v1" + "url": "https://api-dsc.mintlify.com/api/discovery/v1" } ], "security": [ @@ -58,30 +58,311 @@ "items": { "type": "object", "properties": { + "id": { + "type": "string", + "description": "Unique identifier for the message" + }, "role": { "type": "string", "enum": [ - "user", + "system", "assistant", - "system" + "data", + "user" ], "description": "The role of the message sender" }, + "createdAt": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the message was created" + }, "content": { "type": "string", "description": "The content of the message" }, - "id": { - "type": "string", - "description": "Unique identifier for the message" + "annotations": { + "type": "array", + "items": {}, + "description": "Optional array of annotations for the message" + }, + "parts": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "text" + ] + }, + "text": { + "type": "string" + } + }, + "required": [ + "type", + "text" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "reasoning" + ] + }, + "reasoning": { + "type": "string" + }, + "details": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "text" + ] + }, + "text": { + "type": "string" + }, + "signature": { + "type": "string" + } + }, + "required": [ + "type", + "text" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "redacted" + ] + }, + "data": { + "type": "string" + } + }, + "required": [ + "type", + "data" + ] + } + ] + } + } + }, + "required": [ + "type", + "reasoning", + "details" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "step-start" + ] + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "source" + ] + }, + "source": { + "type": "object", + "properties": { + "sourceType": { + "type": "string", + "enum": [ + "url" + ] + }, + "id": { + "type": "string" + }, + "url": { + "type": "string" + }, + "title": { + "type": "string" + } + }, + "required": [ + "sourceType", + "id", + "url" + ] + } + }, + "required": [ + "type", + "source" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": [ + "tool-invocation" + ] + }, + "toolInvocation": { + "oneOf": [ + { + "type": "object", + "properties": { + "state": { + "type": "string", + "enum": [ + "partial-call" + ] + }, + "step": { + "type": "number" + }, + "toolCallId": { + "type": "string" + }, + "toolName": { + "type": "string" + }, + "args": {} + }, + "required": [ + "state", + "toolCallId", + "toolName", + "args" + ] + }, + { + "type": "object", + "properties": { + "state": { + "type": "string", + "enum": [ + "call" + ] + }, + "step": { + "type": "number" + }, + "toolCallId": { + "type": "string" + }, + "toolName": { + "type": "string" + }, + "args": {} + }, + "required": [ + "state", + "toolCallId", + "toolName", + "args" + ] + }, + { + "type": "object", + "properties": { + "state": { + "type": "string", + "enum": [ + "result" + ] + }, + "step": { + "type": "number" + }, + "toolCallId": { + "type": "string" + }, + "toolName": { + "type": "string" + }, + "args": {}, + "result": {} + }, + "required": [ + "state", + "toolCallId", + "toolName", + "args", + "result" + ] + } + ] + } + }, + "required": [ + "type", + "toolInvocation" + ] + } + ] + }, + "description": "Array of message parts with different types including text, reasoning, sources, and tool invocations" + }, + "experimental_attachments": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "contentType": { + "type": "string" + }, + "url": { + "type": "string" + } + }, + "required": [ + "url" + ] + }, + "description": "Optional array of experimental attachments for the message" } }, "required": [ + "id", "role", - "content" + "content", + "parts" ] }, - "description": "Array of messages in the conversation. On the frontend, you will likely want to use the handleSubmit function from the @ai-sdk package's useChat hook to append user messages and handle streaming responses, rather than manually setting this array." + "description": "Array of messages in the conversation. On the frontend, you will likely want to use the handleSubmit function from the @ai-sdk package's useChat hook to append user messages and handle streaming responses, rather than manually defining the objects in this array as they have so many parameters." }, "retrievalPageSize": { "type": "number", From a0a34c8625391b989e76c324c6f67c6921306e03 Mon Sep 17 00:00:00 2001 From: Nick K Date: Fri, 11 Jul 2025 10:14:27 -0700 Subject: [PATCH 4/5] Add default values for threadId and messages in assistant message generation --- discovery-openapi.json | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/discovery-openapi.json b/discovery-openapi.json index ec26510b2..605f340dc 100644 --- a/discovery-openapi.json +++ b/discovery-openapi.json @@ -22,7 +22,7 @@ "enabled": true }, "summary": "Generate Assistant Message", - "description": "Generates a response message from the assistant for the specified domain. For best results, use the [useChat hook from ai-sdk](ai-sdk.dev/docs/ai-sdk-ui/streaming-data) to send requests and handle responses. You can set `fp`, `threadId`, and `filter` in the `body` field of the options parameter passed to the hook.", + "description": "Generates a response message from the assistant for the specified domain. For best results, use the [useChat hook from ai-sdk](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat) to send requests and handle responses. You can set `fp`, `threadId`, and `filter` in the `body` field of the options parameter passed to the hook.", "parameters": [ { "name": "domain", @@ -50,11 +50,25 @@ "description": "Browser fingerprint or arbitrary string identifier. There may be future functionality which allows you to get the messages for a given fingerprint" }, "threadId": { + "default": null, "type": "string", "description": "An optional identifier used to maintain conversation continuity across multiple messages. When provided, it allows the system to associate follow-up messages with the same conversation thread. The threadId is returned in the response as event.threadId when event.type === 'finish'." }, "messages": { "type": "array", + "default": [ + { + "id": "foobar", + "role": "user", + "content": "how do i get started", + "parts": [ + { + "type": "text", + "text": "How do I get started" + } + ] + } + ], "items": { "type": "object", "properties": { @@ -371,6 +385,7 @@ }, "filter": { "type": "object", + "default": null, "properties": { "version": { "type": "string", @@ -395,7 +410,7 @@ "application/json": { "schema": { "type": "object", - "description": "Response object that streams formatted data stream parts with the specified status, headers, and content. This matches what is expected from the AI SDK as documented at [ai-sdk.dev/docs/ai-sdk-ui/streaming-data](https://ai-sdk.dev/docs/ai-sdk-ui/streaming-data). Instead of writing your own parser, it is recommended to use the [useChat hook from ai-sdk as documented here](ai-sdk.dev/docs/ai-sdk-ui/streaming-data)." + "description": "Response object that streams formatted data stream parts with the specified status, headers, and content. This matches what is expected from the AI SDK as documented at [ai-sdk.dev/docs/ai-sdk-ui/streaming-data](https://ai-sdk.dev/docs/ai-sdk-ui/streaming-data). Instead of writing your own parser, it is recommended to use the [useChat hook from ai-sdk as documented here](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat)." } } } From fdf00ef33b16c09d6a8017ca4fdc1fd15fa1c1fd Mon Sep 17 00:00:00 2001 From: Nick K Date: Fri, 11 Jul 2025 15:38:57 -0700 Subject: [PATCH 5/5] Add back the create topic and generate message pages --- api-reference/chat/create-topic.mdx | 3 + api-reference/chat/generate-message.mdx | 3 + discovery-openapi.json | 81 +++++++++++++++++++++++++ 3 files changed, 87 insertions(+) create mode 100644 api-reference/chat/create-topic.mdx create mode 100644 api-reference/chat/generate-message.mdx diff --git a/api-reference/chat/create-topic.mdx b/api-reference/chat/create-topic.mdx new file mode 100644 index 000000000..dc00663e3 --- /dev/null +++ b/api-reference/chat/create-topic.mdx @@ -0,0 +1,3 @@ +--- +openapi: POST /chat/topic +--- diff --git a/api-reference/chat/generate-message.mdx b/api-reference/chat/generate-message.mdx new file mode 100644 index 000000000..b1cdbbb37 --- /dev/null +++ b/api-reference/chat/generate-message.mdx @@ -0,0 +1,3 @@ +--- +openapi: POST /chat/message +--- diff --git a/discovery-openapi.json b/discovery-openapi.json index 605f340dc..904d9d3f0 100644 --- a/discovery-openapi.json +++ b/discovery-openapi.json @@ -417,6 +417,87 @@ } } } + }, + "/chat/topic": { + "post": { + "x-mcp": { + "enabled": true + }, + "summary": "Create Assistant Chat Topic", + "description": "Creates a topic to manage message history for a given AI assistant 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": { + "x-mcp": { + "enabled": true + }, + "summary": "Create Assistant Chat Message", + "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 `||[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": {