mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
skeptrune
cdca393da1
* Refactor API endpoint to generate assistant messages with updated request and response structures * Add Mintlify documentation and update API reference for assistant message generation * Update OpenAPI specification for assistant message generation with new request structure and additional properties * Add default values for threadId and messages in assistant message generation * Add back the create topic and generate message pages * fix: correct the openapi url for assistant
511 lines
22 KiB
JSON
511 lines
22 KiB
JSON
{
|
|
"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": {
|
|
"/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": {
|
|
"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 `<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"
|
|
}
|
|
}
|
|
}
|
|
} |