Files
mintlify__docs/discovery-openapi.json
skeptrune f6da1ed7aa Clarify which API key type each endpoint requires (#6557)
* Clarify which API key type each endpoint requires

- Append an auth line to every operation description across all five
  OpenAPI specs stating the required key type and prefix (admin mint_ vs
  assistant mint_dsc_)
- Fix discovery security scheme claiming the assistant key is safe for
  client-side code, contradicting the proxy guidance in api/introduction
- Expand the terse static-export security scheme description to match
  the other admin specs

* Drop key prefix mentions from spec descriptions
2026-07-14 11:55:15 -07:00

929 lines
39 KiB
JSON

{
"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.",
"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 `page` field returned by the [Search documentation](/api/assistant/search) endpoint."
}
}
}
}
}
},
"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.",
"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."
}
}
}
}
}
}
}
},
"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."
}
}
}
}