From b3c886a37563dcbdd24107f5a869e73af9d5f01a Mon Sep 17 00:00:00 2001 From: Nick K Date: Thu, 10 Jul 2025 20:21:01 -0700 Subject: [PATCH 1/6] Refactor API endpoint to generate assistant messages with updated request and response structures --- discovery-openapi.json | 112 +++++++++++++++++++++++++---------------- 1 file changed, 68 insertions(+), 44 deletions(-) diff --git a/discovery-openapi.json b/discovery-openapi.json index 904d9d3f0..fdcbcd8d7 100644 --- a/discovery-openapi.json +++ b/discovery-openapi.json @@ -423,35 +423,19 @@ "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": { @@ -463,13 +447,61 @@ "message" ], "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" } } } @@ -478,20 +510,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 ." } } } From 61d093bb7d1a2662337af5a1041c0e841aeaa7ff Mon Sep 17 00:00:00 2001 From: Nick K Date: Fri, 11 Jul 2025 09:43:43 -0700 Subject: [PATCH 2/6] Add Mintlify documentation and update API reference for assistant message generation --- discovery-openapi.json | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/discovery-openapi.json b/discovery-openapi.json index fdcbcd8d7..259b36927 100644 --- a/discovery-openapi.json +++ b/discovery-openapi.json @@ -449,11 +449,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", @@ -483,7 +483,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", @@ -493,12 +493,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" @@ -515,7 +516,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)." } } } From c72c52d30348cb8080e13a134d341f1bd742431a Mon Sep 17 00:00:00 2001 From: Nick K Date: Fri, 11 Jul 2025 10:06:41 -0700 Subject: [PATCH 3/6] Update OpenAPI specification for assistant message generation with new request structure and additional properties --- discovery-openapi.json | 295 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 288 insertions(+), 7 deletions(-) diff --git a/discovery-openapi.json b/discovery-openapi.json index 259b36927..f28cfa25f 100644 --- a/discovery-openapi.json +++ b/discovery-openapi.json @@ -460,30 +460,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 f594832bd70af03c3115a241862942f33e9333fe Mon Sep 17 00:00:00 2001 From: Nick K Date: Fri, 11 Jul 2025 10:14:27 -0700 Subject: [PATCH 4/6] Add default values for threadId and messages in assistant message generation --- discovery-openapi.json | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/discovery-openapi.json b/discovery-openapi.json index f28cfa25f..2ab736083 100644 --- a/discovery-openapi.json +++ b/discovery-openapi.json @@ -457,6 +457,19 @@ }, "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": { @@ -773,6 +786,7 @@ }, "filter": { "type": "object", + "default": null, "properties": { "version": { "type": "string", @@ -797,7 +811,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 7126393d0fc41b28e05888f55cda0337ab9e98ee Mon Sep 17 00:00:00 2001 From: Nick K Date: Fri, 11 Jul 2025 15:38:57 -0700 Subject: [PATCH 5/6] Add back the create topic and generate message pages --- discovery-openapi.json | 408 +++++------------------------------------ 1 file changed, 44 insertions(+), 364 deletions(-) diff --git a/discovery-openapi.json b/discovery-openapi.json index 2ab736083..904d9d3f0 100644 --- a/discovery-openapi.json +++ b/discovery-openapi.json @@ -423,19 +423,35 @@ "x-mcp": { "enabled": true }, - "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" + "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": { @@ -447,357 +463,13 @@ "message" ], "properties": { - "fp": { + "topicId": { "type": "string", - "description": "Browser fingerprint or arbitrary string identifier. There may be future functionality which allows you to get the messages for a given fingerprint" + "description": "The topic ID to associate this message with" }, - "threadId": { + "message": { "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": { - "id": { - "type": "string", - "description": "Unique identifier for the message" - }, - "role": { - "type": "string", - "enum": [ - "system", - "assistant", - "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" - }, - "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", - "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 defining the objects in this array as they have so many parameters." - }, - "retrievalPageSize": { - "type": "number", - "default": 5, - "description": "Number of retrieval results to return" - }, - "filter": { - "type": "object", - "default": null, - "properties": { - "version": { - "type": "string", - "description": "Optional version filter" - }, - "language": { - "type": "string", - "description": "Optional language filter" - } - }, - "description": "Optional filter criteria for the search" + "description": "The user message to generate a completion for" } } } @@ -806,12 +478,20 @@ }, "responses": { "200": { - "description": "Message generated successfully", + "description": "Topic created successfully", + "headers": { + "X-Mintlify-Base-Url": { + "schema": { + "type": "string" + }, + "description": "The base URL for the Mintlify documentation" + } + }, "content": { - "application/json": { + "text/plain": { "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](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat)." + "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." } } } From 5d4e5bba1b7e1fb82f17819d404c8fb2c41f610a Mon Sep 17 00:00:00 2001 From: Nick K Date: Mon, 14 Jul 2025 17:19:26 -0700 Subject: [PATCH 6/6] fix: correct the openapi url for assistant --- discovery-openapi.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/discovery-openapi.json b/discovery-openapi.json index 904d9d3f0..06e26cbcb 100644 --- a/discovery-openapi.json +++ b/discovery-openapi.json @@ -7,7 +7,7 @@ }, "servers": [ { - "url": "https://api-dsc.mintlify.com/api/discovery/v1" + "url": "https://api-dsc.mintlify.com/v1" } ], "security": [