diff --git a/advanced/rest-api/discovery/create-topic.mdx b/advanced/rest-api/discovery/create-topic.mdx new file mode 100644 index 000000000..30ad8b74f --- /dev/null +++ b/advanced/rest-api/discovery/create-topic.mdx @@ -0,0 +1,3 @@ +--- +openapi: POST /chat/topic +--- \ No newline at end of file diff --git a/advanced/rest-api/discovery/generate-message.mdx b/advanced/rest-api/discovery/generate-message.mdx new file mode 100644 index 000000000..30a74c542 --- /dev/null +++ b/advanced/rest-api/discovery/generate-message.mdx @@ -0,0 +1,3 @@ +--- +openapi: POST /chat/message +--- \ No newline at end of file diff --git a/advanced/rest-api/overview.mdx b/advanced/rest-api/overview.mdx index bb3480edb..f9d74b067 100644 --- a/advanced/rest-api/overview.mdx +++ b/advanced/rest-api/overview.mdx @@ -1,12 +1,10 @@ --- -title: Introduction +title: Overview --- - - The Mintlify REST API is only available on the [Pro plan and above](https://mintlify.com/pricing). - +## Trigger Updates -Leverage the external API to programmatically trigger an update when desired. +Leverage the REST API to programmatically trigger an update when desired. The primary use-case will be to trigger updates. We will be adding more and more functionality to the API overtime. Let us know what else you want to see in [our community](https://mintlify.com/community)! @@ -20,3 +18,28 @@ associated with the entire org and can be used across multiple deployments. + +## Discovery API + +The Discovery API allows you to embed an AI chat experience grounded in your docs and continually kept up to date into any application of your choosing. +Responses include citations so you can point your users to the right places they need to get help. + +## Getting Started + +To get started, you'll need to generate a Discovery API key in the [dashboard](https://dashboard.mintlify.com/products/chat/widget): + + + Create a Discovery API key + + + + The Discovery API token is a public token that can be referenced in your + frontend code whereas the API key is a server-side token that should be kept + secret. + + +Now that you have an API key, check out our [example](https://github.com/mintlify/discovery-api-example) for how to use +the API for AI chat. You can also see a deployed version of this example at [chat.mintlify.com](https://chat.mintlify.com). diff --git a/advanced/rest-api/update-status.mdx b/advanced/rest-api/update/status.mdx similarity index 74% rename from advanced/rest-api/update-status.mdx rename to advanced/rest-api/update/status.mdx index c4e806f86..9e2e93b66 100644 --- a/advanced/rest-api/update-status.mdx +++ b/advanced/rest-api/update/status.mdx @@ -1,4 +1,3 @@ --- openapi: "GET /project/update-status/{statusId}" -hideApiMarker: true --- diff --git a/advanced/rest-api/trigger-update.mdx b/advanced/rest-api/update/trigger.mdx similarity index 72% rename from advanced/rest-api/trigger-update.mdx rename to advanced/rest-api/update/trigger.mdx index b9fadca70..26b0968f3 100644 --- a/advanced/rest-api/trigger-update.mdx +++ b/advanced/rest-api/update/trigger.mdx @@ -1,4 +1,3 @@ --- openapi: "POST /project/update/{projectId}" -hideApiMarker: true --- diff --git a/discovery-openapi.json b/discovery-openapi.json new file mode 100644 index 000000000..5021a07ad --- /dev/null +++ b/discovery-openapi.json @@ -0,0 +1,100 @@ +{ + "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": { + "/chat/topic": { + "post": { + "summary": "Create a chat topic", + "description": "Creates a topic to manage message history for a given AI chat 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": { + "summary": "Generate a message completion", + "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 `||[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" + } + } + } +} diff --git a/images/generate-discovery-api-key.png b/images/generate-discovery-api-key.png new file mode 100644 index 000000000..37cf7ac84 Binary files /dev/null and b/images/generate-discovery-api-key.png differ diff --git a/mint.json b/mint.json index 9cb1713b8..033f1b475 100644 --- a/mint.json +++ b/mint.json @@ -182,11 +182,22 @@ "group": "REST API", "pages": [ "advanced/rest-api/overview", - "advanced/rest-api/trigger-update", - "advanced/rest-api/update-status" + { + "group": "Updates", + "pages": [ + "advanced/rest-api/update/trigger", + "advanced/rest-api/update/status" + ] + }, + { + "group": "Discovery API", + "pages": [ + "advanced/rest-api/discovery/create-topic", + "advanced/rest-api/discovery/generate-message" + ] + } ] - }, - "settings/authentication" + } ] }, {