skills/mintlify__docs
1
0
Fork 0
mirror of https://github.com/mintlify/docs.git synced 2026-09-14 13:35:46 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
add-currentpath-param-1772056843
mintlify__docs/discovery-openapi.json
T
mintlify-development[bot] e909eccb1f Add currentPath parameter to assistant API docs 
Generated-By: mintlify-agent
2026-02-25 22:00:47 +00:00

810 lines
35 KiB
JSON
Raw Permalink Blame History

{
"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.",
"parameters": [
{
"name": "domain",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The domain identifier from your `domain.mintlify.app` URL. Can be found at the end of your dashboard URL. For example, `dashboard.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."
},
"currentPath": {
"type": "string",
"description": "The path of the page the user is currently viewing. When provided, the assistant includes this context in its system prompt, allowing it to provide more relevant answers based on the user's location in the documentation. Maximum 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+.",
"parameters": [
{
"name": "domain",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The domain identifier from your `domain.mintlify.app` URL. Can be found at the end of your dashboard URL. For example, `dashboard.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 includes this context in its system prompt, allowing it to provide more relevant answers based on the user's location in the documentation. Maximum 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/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.",
"parameters": [
{
"name": "domain",
"in": "path",
"required": true,
"schema": {
"type": "string"
},
"description": "The domain identifier from your `domain.mintlify.app` URL. Can be found at the end of your dashboard URL. For example, `dashboard.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": "number",
"default": 10,
"description": "Number of search results to return. Defaults to 10 if not specified."
},
"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."
}
}
}
}
}
}
}
},
"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 (prefixed with `mint_dsc_`). This is a public key safe for use in client-side code. Generate one on the [API keys page](https://dashboard.mintlify.com/settings/organization/api-keys) in your dashboard."
}
}
}
}
Reference in New Issue View Git Blame Copy Permalink