discovery-openapi.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. The assistant can retrieve protected content unless you pass `groups`. Mintlify doesn't verify group membership, so your backend must choose the groups for each user."
                      }
                    },
                    "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 that narrow results. The assistant API key can read all content, including protected pages. If omitted or empty, includes protected pages in results. Mintlify doesn't verify group membership, so your backend must choose the groups for each user. On password-protected deployments, `groups` doesn't restrict anything."
                  }
                }
              }
            }
          }
        },
        "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 that narrow results. The assistant API key can read all content, including protected pages. If omitted or empty, includes protected pages in results. Mintlify doesn't verify group membership, so your backend must choose the groups for each user. On password-protected deployments, `groups` doesn't restrict anything."
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "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."
      }
    }
  }
}