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 index 30ad8b74f..dc00663e3 100644 --- a/api-reference/chat/create-topic.mdx +++ b/api-reference/chat/create-topic.mdx @@ -1,3 +1,3 @@ --- 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 index 30a74c542..b1cdbbb37 100644 --- a/api-reference/chat/generate-message.mdx +++ b/api-reference/chat/generate-message.mdx @@ -1,3 +1,3 @@ --- openapi: POST /chat/message ---- \ No newline at end of file +--- diff --git a/discovery-openapi.json b/discovery-openapi.json index 2afde35cf..904d9d3f0 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": [ @@ -16,6 +16,408 @@ } ], "paths": { + "/assistant/{domain}/message": { + "post": { + "x-mcp": { + "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](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", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The domain identifier that can be found in the top left corner of the Mintlify dashboard" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "fp", + "messages" + ], + "properties": { + "fp": { + "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" + }, + "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": { + "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" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Message generated successfully", + "content": { + "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](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat)." + } + } + } + } + } + } + }, "/chat/topic": { "post": { "x-mcp": { @@ -56,7 +458,10 @@ "application/json": { "schema": { "type": "object", - "required": ["topicId", "message"], + "required": [ + "topicId", + "message" + ], "properties": { "topicId": { "type": "string", @@ -103,4 +508,4 @@ } } } -} +} \ No newline at end of file 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