{ "openapi": "3.0.1", "info": { "title": "Mintlify Assistant API", "description": "An API to integrate Mintlify discovery features into your product.", "version": "1.0.0" }, "servers": [ { "url": "https://api.mintlify.com/discovery" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/assistant/{domain}/message": { "post": { "summary": "Assistant message v1", "description": "Generates a response message from the assistant for the specified domain. Compatible with AI SDK v4.\n\nAuthenticate with an assistant API key.", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The domain identifier from your `domain.mintlify.site` URL. Can be found at the end of your dashboard URL. For example, `app.mintlify.com/organization/domain` has a domain identifier of `domain`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fp", "messages" ], "properties": { "fp": { "type": "string", "description": "Fingerprint identifier for tracking conversation sessions. Use 'anonymous' for anonymous users or provide a unique user identifier." }, "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 documentation search results to use for generating the response. Higher values provide more context but may increase response time. Recommended: 5." }, "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." }, "context": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "code", "textSelection" ], "description": "The type of context being provided." }, "value": { "type": "string", "description": "The code snippet or selected text content." }, "path": { "type": "string", "description": "Optional path to the source file or page." }, "elementId": { "type": "string", "description": "Optional identifier for the UI element containing the context." } }, "required": [ "type", "value" ] }, "description": "Optional array of contextual information to provide to the assistant." }, "currentPath": { "type": "string", "description": "The path of the page the user is currently viewing. When provided, the assistant uses this context to provide more relevant answers. Maximum length: 200 characters." } } } } } }, "responses": { "200": { "description": "Message generated successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Response object with data stream parts formatted with the specified status, headers, and content. For more information, see the AI SDK documentation at [ai-sdk.dev/docs/ai-sdk-ui/streaming-data](https://ai-sdk.dev/docs/ai-sdk-ui/streaming-data). Use the [useChat hook from ai-sdk](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat) to handle the response stream." } } } } } } }, "/v2/assistant/{domain}/message": { "post": { "summary": "Assistant message", "description": "Generates a response message from the assistant for the specified domain. Compatible with AI SDK v5+.\n\nAuthenticate with an assistant API key.", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The domain identifier from your `domain.mintlify.site` URL. Can be found at the end of your dashboard URL. For example, `app.mintlify.com/organization/domain` has a domain identifier of `domain`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fp", "messages" ], "properties": { "fp": { "type": "string", "description": "Fingerprint identifier for tracking conversation sessions. Use `anonymous` for anonymous users or provide a unique user identifier." }, "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", "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", "user" ], "description": "The role of the message sender." }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the message was created." }, "parts": { "type": "array", "items": { "oneOf": [ { "type": "object", "description": "Text content part.", "properties": { "type": { "type": "string", "enum": [ "text" ] }, "text": { "type": "string" } }, "required": [ "type", "text" ] }, { "type": "object", "description": "Reasoning content part with optional provider metadata.", "properties": { "type": { "type": "string", "enum": [ "reasoning" ] }, "text": { "type": "string" }, "providerMetadata": { "type": "object", "description": "Optional provider-specific metadata." } }, "required": [ "type", "text" ] }, { "type": "object", "description": "Source URL reference part.", "properties": { "type": { "type": "string", "enum": [ "source-url" ] }, "sourceId": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" }, "providerMetadata": { "type": "object", "description": "Optional provider-specific metadata." } }, "required": [ "type", "sourceId", "url" ] }, { "type": "object", "description": "File attachment part.", "properties": { "type": { "type": "string", "enum": [ "file" ] }, "mediaType": { "type": "string" }, "url": { "type": "string" }, "filename": { "type": "string" } }, "required": [ "type", "mediaType", "url" ] }, { "type": "object", "description": "Marks the start of a new step.", "properties": { "type": { "type": "string", "enum": [ "step-start" ] } }, "required": [ "type" ] } ] }, "description": "Array of message parts. Each part has a type and type-specific fields." }, "metadata": { "type": "object", "description": "Optional metadata associated with the message." } }, "required": [ "id", "role", "parts" ] }, "description": "Array of messages in the conversation. Use the handleSubmit function from the @ai-sdk/react package's useChat hook to manage messages and streaming responses." }, "retrievalPageSize": { "type": "number", "default": 5, "description": "Number of documentation search results to use for generating the response. Higher values provide more context but may increase response time. Recommended: 5." }, "filter": { "type": "object", "default": null, "properties": { "version": { "type": "string", "description": "Optional version filter." }, "language": { "type": "string", "description": "Optional language filter." }, "groups": { "type": "array", "items": { "type": "string" }, "description": "Optional array of group identifiers to filter results." } }, "description": "Optional filter criteria for the search." }, "context": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "code", "textSelection" ], "description": "The type of context being provided." }, "value": { "type": "string", "description": "The code snippet or selected text content." }, "path": { "type": "string", "description": "Optional path to the source file or page." }, "elementId": { "type": "string", "description": "Optional identifier for the UI element containing the context." } }, "required": [ "type", "value" ] }, "description": "Optional array of contextual information to provide to the assistant." }, "currentPath": { "type": "string", "description": "The path of the page the user is currently viewing. When provided, the assistant uses this context to provide more relevant answers. Maximum length: 200 characters." } } } } } }, "responses": { "200": { "description": "Message generated successfully", "content": { "application/json": { "schema": { "type": "object", "description": "Streaming response compatible with AI SDK v5. Use the [useChat hook from @ai-sdk/react](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat) to handle the response stream." } } } } } } }, "/v1/page/{domain}": { "post": { "summary": "Get page content", "description": "Retrieve the full text content of a specific documentation page by its path. Use this after a search to fetch the complete content of a matching page.\n\nAuthenticate with an assistant API key. Page content requests do not consume credits.", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The domain identifier from your `domain.mintlify.site` URL. Can be found at the end of your dashboard URL. For example, `app.mintlify.com/organization/domain` has a domain identifier of `domain`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string", "description": "The page slug or path to retrieve content for. This corresponds to the `path` field returned by the [Search documentation](/api/assistant/search) endpoint." }, "groups": { "type": "array", "items": { "type": "string" }, "description": "Optional documentation groups the caller is authorized to access. When the deployment uses `auth` or `userAuth`, page content is returned only if the specified groups can view the page. If omitted or empty on a protected deployment, only public pages are returned." } } } } } }, "responses": { "200": { "description": "Page content retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string", "description": "The page path that was requested." }, "content": { "type": "string", "description": "The full text content of the page." } } } } } }, "404": { "description": "Page not found or no search index available", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message describing why the page could not be found." } } } } } } } } }, "/v1/search/{domain}": { "post": { "x-mint": { "mcp": { "enabled": true } }, "summary": "Search documentation", "description": "Perform semantic and keyword searches across your documentation with configurable filtering and pagination.\n\nAuthenticate with an assistant API key. Search requests do not consume credits.", "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The domain identifier from your `domain.mintlify.site` URL. Can be found at the end of your dashboard URL. For example, `app.mintlify.com/organization/domain` has a domain identifier of `domain`." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "The search query to execute against your documentation content." }, "pageSize": { "type": "integer", "default": 10, "minimum": 1, "maximum": 50, "description": "Number of search results to return. Must be between 1 and 50. Defaults to 10 if not specified." }, "scoreThreshold": { "type": "number", "minimum": 0, "maximum": 1, "description": "Minimum relevance score for results. Only results with a score at or above this threshold are returned. Must be between 0 and 1." }, "filter": { "type": "object", "description": "Optional filtering parameters to narrow search results.", "properties": { "version": { "type": "string", "description": "Filter results by documentation version." }, "language": { "type": "string", "description": "Filter results by content language." }, "tag": { "type": "string", "description": "Filter results by tag." }, "groups": { "type": "array", "items": { "type": "string" }, "description": "Optional documentation groups the caller is authorized to access. When the deployment uses `auth` or `userAuth`, results are limited to pages the specified groups can view. If omitted or empty on a protected deployment, results are limited to public pages." } } } } } } } }, "responses": { "200": { "description": "Search results", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string", "description": "The matching content from your documentation." }, "path": { "type": "string", "description": "The path or URL to the source document." }, "metadata": { "type": "object", "description": "Additional metadata about the search result." } } } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "The Authorization header expects a Bearer token. Use an assistant API key. Generate one on the [API keys page](https://app.mintlify.com/settings/organization/api-keys) in your dashboard. In production, proxy requests through your backend rather than embedding the key in client-side code." } } } }