From 74388a6466803f93a5e919b0415638b4b2362a39 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 22 Sep 2025 11:39:49 -0700 Subject: [PATCH 01/28] update Slack app naming --- ai/slack-app.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/ai/slack-app.mdx b/ai/slack-app.mdx index ca2705b90..b63a860e9 100644 --- a/ai/slack-app.mdx +++ b/ai/slack-app.mdx @@ -5,14 +5,14 @@ icon: "slack" --- - The Slack app is available for [Pro and Enterprise plans](https://mintlify.com/pricing?ref=slack-app). + The Slack app is available for [Pro and Custom plans](https://mintlify.com/pricing?ref=slack-app). -The Slack app adds a bot named `@mintlify` to your Slack workspace that can search your documentation and answer users' questions. The bot responds to direct messages, @mentions, and to any questions in a channel specifically named `#ask-ai`. +The Slack app adds a bot to your Slack workspace that can search your documentation and answer users' questions. The bot responds to direct messages, @mentions, and to any questions in a channel specifically named `#ask-ai`. The bot's name is `@yourprojectname-assistant`. So if your project name is Mintlify, the bot's name is `@mintlify-assistant`. The Slack app can incur costs: either using your AI assistant credits or incurring overages. -## Setting up the Slack app +## Set up the Slack app If your Slack Workspace Owner requires admin approval to install apps, ask them to approve the Mintlify Slack app before you add it. @@ -22,6 +22,6 @@ The Slack app can incur costs: either using your AI assistant credits or incurri 2. Select **Connect** in the Slack Integration card. 3. Follow the Slack prompts to add the app to your workspace. 4. Test that the bot is working and responds when you: - - Send a direct message to the Mintlify app. - - Mention the bot with `@mintlify` in a channel. + - Send a direct message to the bot. + - Mention the bot in a channel. - Create an `#ask-ai` channel, add the bot, and ask a question. From a8bae3f4d46eebd59df5298b11e2ef4ef882a770 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 22 Sep 2025 11:39:59 -0700 Subject: [PATCH 02/28] add agent page to nav --- docs.json | 1 + 1 file changed, 1 insertion(+) diff --git a/docs.json b/docs.json index 89c231597..c0bac893c 100644 --- a/docs.json +++ b/docs.json @@ -51,6 +51,7 @@ "group": "AI optimization", "pages": [ "guides/assistant", + "ai/agent", "ai/llmstxt", "ai/contextual-menu", "ai/model-context-protocol", From ca565ad18b9034949702dc515bdbf815ee77c27a Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 22 Sep 2025 15:34:07 -0700 Subject: [PATCH 03/28] create agent page --- ai/agent.mdx | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 ai/agent.mdx diff --git a/ai/agent.mdx b/ai/agent.mdx new file mode 100644 index 000000000..73dd0687e --- /dev/null +++ b/ai/agent.mdx @@ -0,0 +1,97 @@ +--- +title: "Agent" +description: "The agent helps you write and maintain documentation" +icon: "pen-line" +--- +TODO: finalize naming + + Agent is available to anyone with access to your dashboard. + + +Agent can help you write and maintain documentation. It integrates with your Slack workspace and can reference your documentation, the Mintlify schema, and technical writing best practices to help with writing tasks. The agent can also be accessed through the API. + +Use the agent to: + +- Write new content based on your prompts, links to pull requests, or Slack threads +- Update outdated code examples and API references +- Search and update existing content +- Answer questions about your docs and technical writing topics + +To get started, add the agent to your Slack workspace and mention it with `@mintlify` in a channel. + +## Add Agent to your Slack workspace + + + If your Slack Workspace Owner requires admin approval to install apps, ask them to approve the TODO: (confirm app name) MintlifyWriter app before you add it. + +TODO: confirm steps +1. Navigate to the [agent](https://dashboard.mintlify.com/products/agent) page of your dashboard. +2. Select **Connect** in the Slack card. +3. Follow the Slack prompts to add the app to your workspace. +4. Test that the agent is working and responds when you: + - Send a direct message to it. + - Mention it with `@mintlify` in a channel. + +## Embed the agent via API +TODO: this whole section once the API is finalized +See the API reference for more info. + +## Tips for working with Agent + +Think of the agent as a helpful assistant that needs your guidance to complete tasks. Give it clear instructions and context. More focused tasks are easier to complete, so break down complex projects into smaller steps. + +### Write effective prompts + +Make your prompts specific and outcome-focused. + +A prompt like `@mintlify Improve the onboarding page` will get general technical writing best practices applied to the page, but it doesn't have success criteria and it won't address a specific user need. + +Try prompts based on outcomes you want your users to achieve or problems that you know they encounter. For example: `@mintlify A lot of users have trouble installing the CLI. Review the onboarding page and update the docs so that users can easily install the CLI.` + +Use broad prompts for general content maintenance like fixing typos, updating redirects, or renaming a feature throughout your docs. + +### Common workflows + +Three common workflows to successfully use the agent are: +- Iterate on a prompt in a Slack thread +- Begin with the agent then take over in your local environment or the web editor +- Update docs when merging feature changes + +You can prompt the agent, then continue to mention it with `@mintlify` in the same thread to refine and iterate on the pull request that it creates. + +You can also query the agent to begin a project, then check out the branch it creates and finish the task in your local environment or the web editor. The agent can help you get started, then +you can take over to complete the task. + +When you merge a feature PR, mention the agent with the PR link to automatically update relevant documentation. For example: `@mintlify This PR adds a new authentication method. Update the API + docs to include the new auth flow: [PR link]` + +This adds the PR-triggered pattern while keeping the existing workflows intact. + + + +- Write new content based on your prompts, links to pull requests, or Slack threads +- Add missing sections to existing documentation pages +- Generate code examples for new features or endpoints +- Create documentation from GitHub pull requests +- Generate release notes from commit history +- Create troubleshooting sections based on common issues + + + + +- Fix typos and formatting issues +- Search and update existing content +- Update outdated code examples and API references +- Suggest improvements to unclear explanations +- Add missing prerequisites or setup steps + + + +- Standardize formatting and style across multiple pages +- Reorganize content structure for better user flow +- Update docs when reviewing code changes + + + +- Answer questions about your docs and technical writing topics + From d350e42ecef29ac39a9bc004ce63aacc691db917 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 22 Sep 2025 15:55:53 -0700 Subject: [PATCH 04/28] add to common workflows --- ai/agent.mdx | 49 ++++++++++--------------------------------------- 1 file changed, 10 insertions(+), 39 deletions(-) diff --git a/ai/agent.mdx b/ai/agent.mdx index 73dd0687e..5be0e34d1 100644 --- a/ai/agent.mdx +++ b/ai/agent.mdx @@ -52,46 +52,17 @@ Use broad prompts for general content maintenance like fixing typos, updating re ### Common workflows -Three common workflows to successfully use the agent are: -- Iterate on a prompt in a Slack thread -- Begin with the agent then take over in your local environment or the web editor -- Update docs when merging feature changes +**Iterate on a prompt in a Slack thread** +You can prompt the agent, then continue to mention it with `@mintlify` in the same thread to refine and iterate on the pull request that it creates. For example: `@mintlify Our quickstart page needs a new section on inviting collaborators` then `@mintlify The new section should be called "Inviting collaborators"` and any other iterations. -You can prompt the agent, then continue to mention it with `@mintlify` in the same thread to refine and iterate on the pull request that it creates. +**Begin with the agent then take over in your local environment or the web editor** +You can also query the agent to begin a project, then check out the branch it creates and finish the task in your local environment or the web editor. The agent can help you get started, then you can take over to complete the task. For example: `@mintlify Update the quickstart page to include information about inviting collaborators` and then checkout the branch to make any additional changes using your preferred method. -You can also query the agent to begin a project, then check out the branch it creates and finish the task in your local environment or the web editor. The agent can help you get started, then -you can take over to complete the task. +**Update docs when merging feature changes** +When you merge a feature PR, mention the agent with the PR link to automatically update relevant documentation. For example: `@mintlify This PR adds a new authentication method. Update the API docs to include the new auth flow: [PR link]`. -When you merge a feature PR, mention the agent with the PR link to automatically update relevant documentation. For example: `@mintlify This PR adds a new authentication method. Update the API - docs to include the new auth flow: [PR link]` +**Generate release notes from commit history** +Mention the agent with a specific PR or a time period to generate release notes or changelog updates based on the commit history. For example: `@mintlify Generate release notes for this PR: [PR link]`. -This adds the PR-triggered pattern while keeping the existing workflows intact. - - - -- Write new content based on your prompts, links to pull requests, or Slack threads -- Add missing sections to existing documentation pages -- Generate code examples for new features or endpoints -- Create documentation from GitHub pull requests -- Generate release notes from commit history -- Create troubleshooting sections based on common issues - - - - -- Fix typos and formatting issues -- Search and update existing content -- Update outdated code examples and API references -- Suggest improvements to unclear explanations -- Add missing prerequisites or setup steps - - - -- Standardize formatting and style across multiple pages -- Reorganize content structure for better user flow -- Update docs when reviewing code changes - - - -- Answer questions about your docs and technical writing topics - +**Generate code examples** +Generate code examples for features or endpoints. For example: `@mintlify Generate a code example to make the authentication method easier to understand`. From 37bbbd04aae517dd342e5fc7ff2a673facfd08c9 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Mon, 22 Sep 2025 15:57:24 -0700 Subject: [PATCH 05/28] remove passive voice --- ai/agent.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ai/agent.mdx b/ai/agent.mdx index 5be0e34d1..51a02c9e1 100644 --- a/ai/agent.mdx +++ b/ai/agent.mdx @@ -8,7 +8,7 @@ TODO: finalize naming Agent is available to anyone with access to your dashboard. -Agent can help you write and maintain documentation. It integrates with your Slack workspace and can reference your documentation, the Mintlify schema, and technical writing best practices to help with writing tasks. The agent can also be accessed through the API. +Agent helps you write and maintain documentation. It integrates with your Slack workspace and can reference your documentation, the Mintlify schema, and technical writing best practices to help with writing tasks. You can embed the agent in your application using the API. Use the agent to: From 9cc8904c050853936f60eaca00509f4e208e115c Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 23 Sep 2025 11:42:27 -0700 Subject: [PATCH 06/28] add API workflow example --- ai/agent.mdx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/ai/agent.mdx b/ai/agent.mdx index 51a02c9e1..775b68547 100644 --- a/ai/agent.mdx +++ b/ai/agent.mdx @@ -66,3 +66,6 @@ Mention the agent with a specific PR or a time period to generate release notes **Generate code examples** Generate code examples for features or endpoints. For example: `@mintlify Generate a code example to make the authentication method easier to understand`. + +** Automate with the API** +Integrate the agent into your existing automation tools to automatically update documentation when code changes occur, trigger content reviews, or sync documentation updates across multiple repositories. From 6e1220daaf0d33df7129edb774223409003d7e8d Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 23 Sep 2025 11:46:10 -0700 Subject: [PATCH 07/28] add Slack to header exceptions --- .vale/styles/Google/Headings.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.vale/styles/Google/Headings.yml b/.vale/styles/Google/Headings.yml index 6e2645923..a527dab29 100644 --- a/.vale/styles/Google/Headings.yml +++ b/.vale/styles/Google/Headings.yml @@ -30,6 +30,7 @@ exceptions: - PDF - SAML - SDK + - Slack - SSL - SSO - TLS From 8b2616b2177f1cfebcf127d665ce91026e7c4d74 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 23 Sep 2025 14:09:33 -0700 Subject: [PATCH 08/28] revise intro --- ai/agent.mdx | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/ai/agent.mdx b/ai/agent.mdx index 775b68547..390d9cecb 100644 --- a/ai/agent.mdx +++ b/ai/agent.mdx @@ -8,12 +8,12 @@ TODO: finalize naming Agent is available to anyone with access to your dashboard. -Agent helps you write and maintain documentation. It integrates with your Slack workspace and can reference your documentation, the Mintlify schema, and technical writing best practices to help with writing tasks. You can embed the agent in your application using the API. +Agent helps you write and maintain documentation. It can reference your documentation, GitHub repositories that you give it access to, pull requests, Slack messages, the Mintlify schema, and technical writing best practices. The agent integrates with your Slack workspace and can be embedded in custom applications with the API. Use the agent to: - Write new content based on your prompts, links to pull requests, or Slack threads -- Update outdated code examples and API references +- Revise outdated code examples and API references - Search and update existing content - Answer questions about your docs and technical writing topics @@ -50,6 +50,9 @@ Try prompts based on outcomes you want your users to achieve or problems that yo Use broad prompts for general content maintenance like fixing typos, updating redirects, or renaming a feature throughout your docs. + +From Claude: Consider adding one more example of a outcome-focused prompt for a different scenario (maybe API documentation or troubleshooting content) + ### Common workflows **Iterate on a prompt in a Slack thread** @@ -67,5 +70,11 @@ Mention the agent with a specific PR or a time period to generate release notes **Generate code examples** Generate code examples for features or endpoints. For example: `@mintlify Generate a code example to make the authentication method easier to understand`. -** Automate with the API** +TODO: could be more specific about when/why this helps users + +1. Add a workflow about reviewing existing content for accuracy: @mintlify Review the API rate limiting section - we changed limits last month + +2. Consider adding troubleshooting prompts: @mintlify Users are getting confused by step 3 in the setup guide. Make it clearer + +**Automate with the API** Integrate the agent into your existing automation tools to automatically update documentation when code changes occur, trigger content reviews, or sync documentation updates across multiple repositories. From bff83494c287b1d0b7c5b37c3b1b910e22f463e4 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 23 Sep 2025 14:13:30 -0700 Subject: [PATCH 09/28] adjust header depth for ToC --- ai/agent.mdx | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/ai/agent.mdx b/ai/agent.mdx index 390d9cecb..a1a7b211b 100644 --- a/ai/agent.mdx +++ b/ai/agent.mdx @@ -36,12 +36,10 @@ TODO: confirm steps TODO: this whole section once the API is finalized See the API reference for more info. -## Tips for working with Agent +## Write effective prompts Think of the agent as a helpful assistant that needs your guidance to complete tasks. Give it clear instructions and context. More focused tasks are easier to complete, so break down complex projects into smaller steps. -### Write effective prompts - Make your prompts specific and outcome-focused. A prompt like `@mintlify Improve the onboarding page` will get general technical writing best practices applied to the page, but it doesn't have success criteria and it won't address a specific user need. @@ -53,21 +51,21 @@ Use broad prompts for general content maintenance like fixing typos, updating re From Claude: Consider adding one more example of a outcome-focused prompt for a different scenario (maybe API documentation or troubleshooting content) -### Common workflows +## Agent workflows -**Iterate on a prompt in a Slack thread** +### Iterate on a prompt in a Slack thread You can prompt the agent, then continue to mention it with `@mintlify` in the same thread to refine and iterate on the pull request that it creates. For example: `@mintlify Our quickstart page needs a new section on inviting collaborators` then `@mintlify The new section should be called "Inviting collaborators"` and any other iterations. -**Begin with the agent then take over in your local environment or the web editor** +### Begin with the agent then take over in your local environment or the web editor You can also query the agent to begin a project, then check out the branch it creates and finish the task in your local environment or the web editor. The agent can help you get started, then you can take over to complete the task. For example: `@mintlify Update the quickstart page to include information about inviting collaborators` and then checkout the branch to make any additional changes using your preferred method. -**Update docs when merging feature changes** +### Update docs when merging feature changes When you merge a feature PR, mention the agent with the PR link to automatically update relevant documentation. For example: `@mintlify This PR adds a new authentication method. Update the API docs to include the new auth flow: [PR link]`. -**Generate release notes from commit history** +### Generate release notes from commit history Mention the agent with a specific PR or a time period to generate release notes or changelog updates based on the commit history. For example: `@mintlify Generate release notes for this PR: [PR link]`. -**Generate code examples** +### Generate code examples Generate code examples for features or endpoints. For example: `@mintlify Generate a code example to make the authentication method easier to understand`. TODO: could be more specific about when/why this helps users @@ -76,5 +74,5 @@ TODO: could be more specific about when/why this helps users 2. Consider adding troubleshooting prompts: @mintlify Users are getting confused by step 3 in the setup guide. Make it clearer -**Automate with the API** +### Automate with the API Integrate the agent into your existing automation tools to automatically update documentation when code changes occur, trigger content reviews, or sync documentation updates across multiple repositories. From 4d749509f597d367c79aa13a3a0688f50cef8f0e Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 23 Sep 2025 16:14:21 -0700 Subject: [PATCH 10/28] clean up the prompts section --- ai/agent.mdx | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/ai/agent.mdx b/ai/agent.mdx index a1a7b211b..87a1a4048 100644 --- a/ai/agent.mdx +++ b/ai/agent.mdx @@ -38,19 +38,14 @@ See the API reference for more info. ## Write effective prompts -Think of the agent as a helpful assistant that needs your guidance to complete tasks. Give it clear instructions and context. More focused tasks are easier to complete, so break down complex projects into smaller steps. +Think of the agent as a helpful assistant that needs your guidance to complete tasks. If you give it clear instructions and context, it is more likely to complete the task successfully. More focused tasks are easier to complete, so break down complex projects into smaller steps. -Make your prompts specific and outcome-focused. +Make your prompts specific and outcome-focused. A prompt like `@mintlify Improve the onboarding page` will have the agent apply general technical writing best practices to the page, but it may not improve the page in a way that truly helps your users. -A prompt like `@mintlify Improve the onboarding page` will get general technical writing best practices applied to the page, but it doesn't have success criteria and it won't address a specific user need. - -Try prompts based on outcomes you want your users to achieve or problems that you know they encounter. For example: `@mintlify A lot of users have trouble installing the CLI. Review the onboarding page and update the docs so that users can easily install the CLI.` +Try prompts based on outcomes you want your users to achieve or problems that you know they encounter. For example: `@mintlify A lot of users have trouble installing the CLI. Review the onboarding page and update the docs so that users can easily install the CLI` or `@mintlify Developers keep getting 401 errors when following our authentication guide. Review the auth docs and add clearer examples showing how to properly format the API key`. Use broad prompts for general content maintenance like fixing typos, updating redirects, or renaming a feature throughout your docs. - -From Claude: Consider adding one more example of a outcome-focused prompt for a different scenario (maybe API documentation or troubleshooting content) - ## Agent workflows ### Iterate on a prompt in a Slack thread From e1cc77f514aa49e0f73c6b815313041dc31d5dee Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 23 Sep 2025 16:34:38 -0700 Subject: [PATCH 11/28] add into to workflows section --- ai/agent.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/ai/agent.mdx b/ai/agent.mdx index 87a1a4048..cf1fcfc4a 100644 --- a/ai/agent.mdx +++ b/ai/agent.mdx @@ -48,6 +48,8 @@ Use broad prompts for general content maintenance like fixing typos, updating re ## Agent workflows +There are many ways to use the agent to help maintain and improve your documentation. These examples show ways to get started using the agent. Try out different prompts and find what works best for you. + ### Iterate on a prompt in a Slack thread You can prompt the agent, then continue to mention it with `@mintlify` in the same thread to refine and iterate on the pull request that it creates. For example: `@mintlify Our quickstart page needs a new section on inviting collaborators` then `@mintlify The new section should be called "Inviting collaborators"` and any other iterations. From 32b5ac63eb440300d74069c319bb3ec77d8c5029 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 23 Sep 2025 16:54:17 -0700 Subject: [PATCH 12/28] add broad examples --- ai/agent.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ai/agent.mdx b/ai/agent.mdx index cf1fcfc4a..0b23918a6 100644 --- a/ai/agent.mdx +++ b/ai/agent.mdx @@ -44,11 +44,11 @@ Make your prompts specific and outcome-focused. A prompt like `@mintlify Improve Try prompts based on outcomes you want your users to achieve or problems that you know they encounter. For example: `@mintlify A lot of users have trouble installing the CLI. Review the onboarding page and update the docs so that users can easily install the CLI` or `@mintlify Developers keep getting 401 errors when following our authentication guide. Review the auth docs and add clearer examples showing how to properly format the API key`. -Use broad prompts for general content maintenance like fixing typos, updating redirects, or renaming a feature throughout your docs. +Use broad prompts for general content maintenance like fixing typos, updating redirects, or renaming a feature throughout your docs. For example: `@mintlify Find and fix all typos in the docs` or `@mintlify change all unordered lists to use * instead of -`. ## Agent workflows -There are many ways to use the agent to help maintain and improve your documentation. These examples show ways to get started using the agent. Try out different prompts and find what works best for you. +The agent assists with many different documentation tasks. These workflows show some of the ways you can integrate the agent into your documentation process. Try an approach that fits how your team currently works and adapt it to your specific needs. ### Iterate on a prompt in a Slack thread You can prompt the agent, then continue to mention it with `@mintlify` in the same thread to refine and iterate on the pull request that it creates. For example: `@mintlify Our quickstart page needs a new section on inviting collaborators` then `@mintlify The new section should be called "Inviting collaborators"` and any other iterations. From b0052b3cd086c1f2c63c37a35bb2e47058f45386 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 23 Sep 2025 17:02:55 -0700 Subject: [PATCH 13/28] update example workflows --- ai/agent.mdx | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/ai/agent.mdx b/ai/agent.mdx index 0b23918a6..33c7eece1 100644 --- a/ai/agent.mdx +++ b/ai/agent.mdx @@ -19,7 +19,9 @@ Use the agent to: To get started, add the agent to your Slack workspace and mention it with `@mintlify` in a channel. -## Add Agent to your Slack workspace +## Configure the agent + +### Add Agent to your Slack workspace If your Slack Workspace Owner requires admin approval to install apps, ask them to approve the TODO: (confirm app name) MintlifyWriter app before you add it. @@ -32,6 +34,10 @@ TODO: confirm steps - Send a direct message to it. - Mention it with `@mintlify` in a channel. +### Give the agent access to your repositories + +TODO: once workflow is finalized + ## Embed the agent via API TODO: this whole section once the API is finalized See the API reference for more info. @@ -51,25 +57,25 @@ Use broad prompts for general content maintenance like fixing typos, updating re The agent assists with many different documentation tasks. These workflows show some of the ways you can integrate the agent into your documentation process. Try an approach that fits how your team currently works and adapt it to your specific needs. ### Iterate on a prompt in a Slack thread -You can prompt the agent, then continue to mention it with `@mintlify` in the same thread to refine and iterate on the pull request that it creates. For example: `@mintlify Our quickstart page needs a new section on inviting collaborators` then `@mintlify The new section should be called "Inviting collaborators"` and any other iterations. +Prompt the agent, then continue to mention it with `@mintlify` in the same thread to refine and iterate on the pull request that it creates. For example: `@mintlify Our quickstart page needs a new section on inviting collaborators` then `@mintlify The new section should be called "Inviting collaborators"` and any other iterations. -### Begin with the agent then take over in your local environment or the web editor -You can also query the agent to begin a project, then check out the branch it creates and finish the task in your local environment or the web editor. The agent can help you get started, then you can take over to complete the task. For example: `@mintlify Update the quickstart page to include information about inviting collaborators` and then checkout the branch to make any additional changes using your preferred method. +### Begin with the agent then take over +Prompt the agent to begin a project, then check out the branch it creates and finish the task in your local environment or the web editor. The agent can help you get started, then you can take over to complete the task. For example: `@mintlify Update the quickstart page to include information about inviting collaborators` and then checkout the branch to make any additional changes using your preferred method. ### Update docs when merging feature changes -When you merge a feature PR, mention the agent with the PR link to automatically update relevant documentation. For example: `@mintlify This PR adds a new authentication method. Update the API docs to include the new auth flow: [PR link]`. +When you merge a feature pull request, prompt the agent with a link to the pull request to automatically update relevant documentation. For example: `@mintlify This PR adds a new authentication method. Update the docs to include the new auth flow: [PR link]`. ### Generate release notes from commit history -Mention the agent with a specific PR or a time period to generate release notes or changelog updates based on the commit history. For example: `@mintlify Generate release notes for this PR: [PR link]`. +Prompt the agent with a specific pull request or a time period to generate release notes or changelog updates based on the commit history. For example: `@mintlify Generate release notes for this PR: [PR link]` or `@mintlify Generate release notes for the last month`. ### Generate code examples -Generate code examples for features or endpoints. For example: `@mintlify Generate a code example to make the authentication method easier to understand`. - -TODO: could be more specific about when/why this helps users +Prompt the agent to generate code examples for features throughout your docs or on specific pages. For example: `@mintlify Generate a code example to make the authentication method easier to understand`. -1. Add a workflow about reviewing existing content for accuracy: @mintlify Review the API rate limiting section - we changed limits last month +### Review existing content +Prompt the agent to review existing content for technical accuracy, style, grammar, or other issues. For example: `@mintlify Review the API rate limiting section. We changed limits last month`. -2. Consider adding troubleshooting prompts: @mintlify Users are getting confused by step 3 in the setup guide. Make it clearer +### Respond to user feedback +Prompt the agent with feedback from your users to make focused updates to your docs. For example: `@mintlify Users are getting confused by step 3 in the setup guide. Make it more clear`. ### Automate with the API Integrate the agent into your existing automation tools to automatically update documentation when code changes occur, trigger content reviews, or sync documentation updates across multiple repositories. From 1d92a4656eca6d574980f436eaca4029ef6b53b1 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 23 Sep 2025 17:06:11 -0700 Subject: [PATCH 14/28] =?UTF-8?q?=F0=9F=92=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ai/agent.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ai/agent.mdx b/ai/agent.mdx index 33c7eece1..45fc57954 100644 --- a/ai/agent.mdx +++ b/ai/agent.mdx @@ -59,7 +59,7 @@ The agent assists with many different documentation tasks. These workflows show ### Iterate on a prompt in a Slack thread Prompt the agent, then continue to mention it with `@mintlify` in the same thread to refine and iterate on the pull request that it creates. For example: `@mintlify Our quickstart page needs a new section on inviting collaborators` then `@mintlify The new section should be called "Inviting collaborators"` and any other iterations. -### Begin with the agent then take over +### Start with the agent, finish manually Prompt the agent to begin a project, then check out the branch it creates and finish the task in your local environment or the web editor. The agent can help you get started, then you can take over to complete the task. For example: `@mintlify Update the quickstart page to include information about inviting collaborators` and then checkout the branch to make any additional changes using your preferred method. ### Update docs when merging feature changes @@ -75,7 +75,7 @@ Prompt the agent to generate code examples for features throughout your docs or Prompt the agent to review existing content for technical accuracy, style, grammar, or other issues. For example: `@mintlify Review the API rate limiting section. We changed limits last month`. ### Respond to user feedback -Prompt the agent with feedback from your users to make focused updates to your docs. For example: `@mintlify Users are getting confused by step 3 in the setup guide. Make it more clear`. +Prompt the agent with feedback from your users to make focused updates to your docs. For example: `@mintlify Users are getting confused by step 3 in the setup guide. What might be making it unclear?`. ### Automate with the API Integrate the agent into your existing automation tools to automatically update documentation when code changes occur, trigger content reviews, or sync documentation updates across multiple repositories. From 2759113a09f8738c4ce7d28afc7b5e90a8575031 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Tue, 23 Sep 2025 17:17:55 -0700 Subject: [PATCH 15/28] add steps for connecting repos --- ai/agent.mdx | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/ai/agent.mdx b/ai/agent.mdx index 45fc57954..b5734211d 100644 --- a/ai/agent.mdx +++ b/ai/agent.mdx @@ -19,9 +19,7 @@ Use the agent to: To get started, add the agent to your Slack workspace and mention it with `@mintlify` in a channel. -## Configure the agent - -### Add Agent to your Slack workspace +## Add Agent to your Slack workspace If your Slack Workspace Owner requires admin approval to install apps, ask them to approve the TODO: (confirm app name) MintlifyWriter app before you add it. @@ -34,9 +32,9 @@ TODO: confirm steps - Send a direct message to it. - Mention it with `@mintlify` in a channel. -### Give the agent access to your repositories - -TODO: once workflow is finalized +## Connect repositories as context +TODO: revisit when UI is finalized +The agent can only access GitHub repositories that you grant it access to. You can modify which repositories the agent can access in the [GitHub App settings](https://github.com/apps/mintlify/installations/new). ## Embed the agent via API TODO: this whole section once the API is finalized From ab0adc10a3a50207d2e521e1e9eb08694e2d3709 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Wed, 24 Sep 2025 16:08:43 -0700 Subject: [PATCH 16/28] clean up some TODOs --- ai/agent.mdx | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/ai/agent.mdx b/ai/agent.mdx index b5734211d..1a0d1c141 100644 --- a/ai/agent.mdx +++ b/ai/agent.mdx @@ -3,12 +3,12 @@ title: "Agent" description: "The agent helps you write and maintain documentation" icon: "pen-line" --- -TODO: finalize naming + - Agent is available to anyone with access to your dashboard. + The agent is available to anyone with access to your dashboard. -Agent helps you write and maintain documentation. It can reference your documentation, GitHub repositories that you give it access to, pull requests, Slack messages, the Mintlify schema, and technical writing best practices. The agent integrates with your Slack workspace and can be embedded in custom applications with the API. +The agent helps write and maintain your documentation. It references your documentation, connected repositories, and Slack messages to create content that follows technical writing best practices and adheres to the Mintlify schema. Access the agent in your Slack workspace or embed it in custom applications with the API. Use the agent to: @@ -19,22 +19,22 @@ Use the agent to: To get started, add the agent to your Slack workspace and mention it with `@mintlify` in a channel. -## Add Agent to your Slack workspace +## Add the agent to your Slack workspace - If your Slack Workspace Owner requires admin approval to install apps, ask them to approve the TODO: (confirm app name) MintlifyWriter app before you add it. + If your Slack Workspace Owner requires admin approval to install apps, ask them to approve the mintlify app before you connect it. -TODO: confirm steps + 1. Navigate to the [agent](https://dashboard.mintlify.com/products/agent) page of your dashboard. -2. Select **Connect** in the Slack card. -3. Follow the Slack prompts to add the app to your workspace. +2. Select the **Connect** button. +3. Follow the Slack prompts to add the `mintlify` app to your workspace. 4. Test that the agent is working and responds when you: - Send a direct message to it. - Mention it with `@mintlify` in a channel. ## Connect repositories as context -TODO: revisit when UI is finalized -The agent can only access GitHub repositories that you grant it access to. You can modify which repositories the agent can access in the [GitHub App settings](https://github.com/apps/mintlify/installations/new). + +The agent can only access repositories that you connect through the Mintlify GitHub App. Modify which repositories the agent can access in the [GitHub App settings](https://github.com/apps/mintlify/installations/new). ## Embed the agent via API TODO: this whole section once the API is finalized From 89efe28c7b80a6ca94ea278d85b4e4efafd35689 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 26 Sep 2025 14:58:55 -0700 Subject: [PATCH 17/28] edit intro --- ai/agent.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ai/agent.mdx b/ai/agent.mdx index 1a0d1c141..56a0e7fa0 100644 --- a/ai/agent.mdx +++ b/ai/agent.mdx @@ -8,7 +8,7 @@ icon: "pen-line" The agent is available to anyone with access to your dashboard. -The agent helps write and maintain your documentation. It references your documentation, connected repositories, and Slack messages to create content that follows technical writing best practices and adheres to the Mintlify schema. Access the agent in your Slack workspace or embed it in custom applications with the API. +The agent creates pull requests with proposed changes to your documentation based on your prompts. When you send a request to the agent, it references your documentation, connected repositories, and Slack messages to create content that follows technical writing best practices and adheres to the Mintlify schema. Access the agent in your Slack workspace or embed it in custom applications with the API. Use the agent to: From 5c0eb5fd97e68889da5976312a90d4da18c33eea Mon Sep 17 00:00:00 2001 From: cdxker Date: Sat, 27 Sep 2025 19:44:16 -0700 Subject: [PATCH 18/28] feature: rough draft of discovery agent routes. Copy is prone to change just copy / pasted --- api-reference/agent/create-agent-job.mdx | 23 ++ api-reference/agent/get-agent-job.mdx | 16 ++ api-reference/agent/get-all-jobs.mdx | 17 ++ discovery-openapi.json | 333 ++++++++++++++++++++++- docs.json | 8 + 5 files changed, 396 insertions(+), 1 deletion(-) create mode 100644 api-reference/agent/create-agent-job.mdx create mode 100644 api-reference/agent/get-agent-job.mdx create mode 100644 api-reference/agent/get-all-jobs.mdx diff --git a/api-reference/agent/create-agent-job.mdx b/api-reference/agent/create-agent-job.mdx new file mode 100644 index 000000000..ba88103a1 --- /dev/null +++ b/api-reference/agent/create-agent-job.mdx @@ -0,0 +1,23 @@ +--- +openapi: POST /agent/{domain} +--- + +## Rate limits + +The agent API has the following limits: + +- 10,000 uses per key per month +- 10,000 requests per Mintlify organization per hour +- 10,000 requests per IP per day + +## Usage + +This endpoint creates an AI writer job that can generate and edit documentation based on provided messages and branch information. The job executes asynchronously and returns a streaming response with the execution details and results. + +## Branch Management + +The agent requires branch information to know where to make changes: +- `branchName`: The target git branch for documentation changes +- `branchExists`: Whether the branch already exists in your repository + +If the branch doesn't exist, the agent will create it. If files are edited successfully, a draft pull request will be automatically created. \ No newline at end of file diff --git a/api-reference/agent/get-agent-job.mdx b/api-reference/agent/get-agent-job.mdx new file mode 100644 index 000000000..84ce4f4c2 --- /dev/null +++ b/api-reference/agent/get-agent-job.mdx @@ -0,0 +1,16 @@ +--- +openapi: GET /agent/{domain}/job/{id} +--- + +## Usage + +This endpoint retrieves the details and status of a specific writer job by its unique identifier. Use this to check the progress, status, and results of a previously created agent job. + +## Job Details + +The response includes information such as: +- Job execution status and completion state +- Branch information and pull request details +- Any error messages or completion messages +- Files that were edited during the job +- Session metadata and timestamps \ No newline at end of file diff --git a/api-reference/agent/get-all-jobs.mdx b/api-reference/agent/get-all-jobs.mdx new file mode 100644 index 000000000..a6f4bf5a2 --- /dev/null +++ b/api-reference/agent/get-all-jobs.mdx @@ -0,0 +1,17 @@ +--- +openapi: GET /agent/{domain}/jobs +--- + +## Usage + +This endpoint retrieves all writer jobs for the specified domain, providing an overview of all agent activities and their current status. This is useful for monitoring and managing multiple concurrent or historical agent jobs. + +## Response + +The response contains an `allSessions` array with details about each writer job including: +- Job execution status and completion state +- Branch information and pull request links +- Session identifiers and creation timestamps +- Files that were edited and completion messages + +Use this endpoint to get a comprehensive view of all agent activity for your domain. \ No newline at end of file diff --git a/discovery-openapi.json b/discovery-openapi.json index 30278d030..6dd51338d 100644 --- a/discovery-openapi.json +++ b/discovery-openapi.json @@ -576,6 +576,337 @@ } } } + }, + "/agent/{domain}": { + "post": { + "summary": "Create writer job", + "description": "Creates a new AI writer job that can generate and edit documentation based on provided messages and branch information.", + "parameters": [ + { + "name": "domain", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The domain identifier from your `domain.mintlify.app` URL. Can be found in the top left of your dashboard." + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "branchName", + "branchExists", + "messages" + ], + "properties": { + "branchName": { + "type": "string", + "description": "The name of the git branch where changes should be made." + }, + "branchExists": { + "type": "boolean", + "description": "Whether the specified branch already exists in the repository." + }, + "messages": { + "type": "array", + "description": "Array of messages for the AI writer to process.", + "items": { + "type": "object", + "required": [ + "role", + "content" + ], + "properties": { + "role": { + "type": "string", + "enum": ["system", "user"], + "description": "The role of the message sender." + }, + "content": { + "type": "string", + "description": "The content of the message." + } + } + } + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Writer job created successfully", + "headers": { + "X-Message-Id": { + "schema": { + "type": "string" + }, + "description": "Message identifier for the created job" + } + }, + "content": { + "text/plain": { + "schema": { + "type": "string", + "description": "Streaming response containing the writer job execution details and results." + } + } + } + } + } + } + }, + "/agent/{domain}/job/{id}": { + "get": { + "summary": "Get writer job by ID", + "description": "Retrieves the details and status of a specific writer job by its ID.", + "parameters": [ + { + "name": "domain", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The domain identifier from your `domain.mintlify.app` URL. Can be found in the top left of your dashboard." + }, + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the writer job to retrieve." + } + ], + "responses": { + "200": { + "description": "Writer job details retrieved successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "_id": { + "type": "string", + "description": "Unique MongoDB ObjectId of the writer session." + }, + "subdomain": { + "type": "string", + "description": "The subdomain this session belongs to." + }, + "source": { + "type": "string", + "enum": ["slack", "api"], + "description": "Source of the writer session." + }, + "sessionId": { + "type": "string", + "description": "Unique session identifier." + }, + "branchName": { + "type": "string", + "description": "Git branch name where changes were made.", + "nullable": true + }, + "haulted": { + "type": "boolean", + "description": "Whether the session execution was halted." + }, + "haultReason": { + "type": "string", + "enum": ["completed", "github_missconfigured", "error"], + "description": "Reason for session halt." + }, + "createdPullRequest": { + "type": "boolean", + "description": "Whether a pull request was created." + }, + "pullRequestLink": { + "type": "string", + "description": "Link to the created pull request." + }, + "messageToUser": { + "type": "string", + "description": "Message for the user about the session outcome." + }, + "editedFiles": { + "type": "boolean", + "description": "Whether any files were edited during the session." + }, + "lastTextStream": { + "type": "string", + "description": "Last text stream from the agent execution." + }, + "todos": { + "type": "array", + "description": "List of todo items from the session.", + "items": { + "type": "object", + "properties": { + "content": { + "type": "string", + "description": "Brief description of the task." + }, + "status": { + "type": "string", + "enum": ["pending", "in_progress", "completed", "cancelled"], + "description": "Current status of the task." + }, + "priority": { + "type": "string", + "enum": ["high", "medium", "low"], + "description": "Priority level of the task." + }, + "id": { + "type": "string", + "description": "Unique identifier for the todo item." + } + } + } + }, + "createdAt": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the session was created." + } + } + } + } + } + } + } + } + }, + "/agent/{domain}/jobs": { + "get": { + "summary": "Get all writer jobs", + "description": "Retrieves all writer jobs for the specified domain, including their status and details.", + "parameters": [ + { + "name": "domain", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The domain identifier from your `domain.mintlify.app` URL. Can be found in the top left of your dashboard." + } + ], + "responses": { + "200": { + "description": "All writer jobs retrieved successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "allSessions": { + "type": "array", + "description": "Array of all writer sessions for the domain.", + "items": { + "type": "object", + "properties": { + "_id": { + "type": "string", + "description": "Unique MongoDB ObjectId of the writer session." + }, + "subdomain": { + "type": "string", + "description": "The subdomain this session belongs to." + }, + "source": { + "type": "string", + "enum": ["slack", "api"], + "description": "Source of the writer session." + }, + "sessionId": { + "type": "string", + "description": "Unique session identifier." + }, + "branchName": { + "type": "string", + "description": "Git branch name where changes were made.", + "nullable": true + }, + "haulted": { + "type": "boolean", + "description": "Whether the session execution was halted." + }, + "haultReason": { + "type": "string", + "enum": ["completed", "github_missconfigured", "error"], + "description": "Reason for session halt." + }, + "createdPullRequest": { + "type": "boolean", + "description": "Whether a pull request was created." + }, + "pullRequestLink": { + "type": "string", + "description": "Link to the created pull request." + }, + "messageToUser": { + "type": "string", + "description": "Message for the user about the session outcome." + }, + "editedFiles": { + "type": "boolean", + "description": "Whether any files were edited during the session." + }, + "lastTextStream": { + "type": "string", + "description": "Last text stream from the agent execution." + }, + "todos": { + "type": "array", + "description": "List of todo items from the session.", + "items": { + "type": "object", + "properties": { + "content": { + "type": "string", + "description": "Brief description of the task." + }, + "status": { + "type": "string", + "enum": ["pending", "in_progress", "completed", "cancelled"], + "description": "Current status of the task." + }, + "priority": { + "type": "string", + "enum": ["high", "medium", "low"], + "description": "Priority level of the task." + }, + "id": { + "type": "string", + "description": "Unique identifier for the todo item." + } + } + } + }, + "createdAt": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the session was created." + } + } + } + } + } + } + } + } + } + } + } } }, "components": { @@ -587,4 +918,4 @@ } } } -} \ No newline at end of file +} diff --git a/docs.json b/docs.json index 57651279d..19483c462 100644 --- a/docs.json +++ b/docs.json @@ -264,6 +264,14 @@ "api-reference/assistant/create-assistant-message", "api-reference/assistant/search" ] + }, + { + "group": "Agent", + "pages": [ + "api-reference/agent/create-agent-job", + "api-reference/agent/get-agent-job", + "api-reference/agent/get-all-jobs" + ] } ] }, From bb8b4396e893be768c9c6eee141e70611a947d90 Mon Sep 17 00:00:00 2001 From: cdxker Date: Sun, 28 Sep 2025 11:03:12 -0700 Subject: [PATCH 19/28] feature: finalized rough draft of api spec. Cleaned up copy on the api reference page --- api-reference/agent/create-agent-job.mdx | 20 ++----- api-reference/agent/get-agent-job.mdx | 4 +- api-reference/agent/get-all-jobs.mdx | 8 +-- discovery-openapi.json | 73 +++++------------------- 4 files changed, 19 insertions(+), 86 deletions(-) diff --git a/api-reference/agent/create-agent-job.mdx b/api-reference/agent/create-agent-job.mdx index ba88103a1..d788087fa 100644 --- a/api-reference/agent/create-agent-job.mdx +++ b/api-reference/agent/create-agent-job.mdx @@ -1,23 +1,11 @@ --- -openapi: POST /agent/{domain} +openapi: POST /agent/job/{domain} --- -## Rate limits - -The agent API has the following limits: - -- 10,000 uses per key per month -- 10,000 requests per Mintlify organization per hour -- 10,000 requests per IP per day - -## Usage - This endpoint creates an AI writer job that can generate and edit documentation based on provided messages and branch information. The job executes asynchronously and returns a streaming response with the execution details and results. +If the branch doesn't exist, the agent will create it. If files are edited successfully, a draft pull request will be automatically created at the end of the job -## Branch Management +## Suggested usage -The agent requires branch information to know where to make changes: -- `branchName`: The target git branch for documentation changes -- `branchExists`: Whether the branch already exists in your repository +For best results, use the useChat hook from ai-sdk to send requests and handle responses. -If the branch doesn't exist, the agent will create it. If files are edited successfully, a draft pull request will be automatically created. \ No newline at end of file diff --git a/api-reference/agent/get-agent-job.mdx b/api-reference/agent/get-agent-job.mdx index 84ce4f4c2..6eef948f8 100644 --- a/api-reference/agent/get-agent-job.mdx +++ b/api-reference/agent/get-agent-job.mdx @@ -11,6 +11,4 @@ This endpoint retrieves the details and status of a specific writer job by its u The response includes information such as: - Job execution status and completion state - Branch information and pull request details -- Any error messages or completion messages -- Files that were edited during the job -- Session metadata and timestamps \ No newline at end of file +- Session metadata and timestamps diff --git a/api-reference/agent/get-all-jobs.mdx b/api-reference/agent/get-all-jobs.mdx index a6f4bf5a2..a45eda5a5 100644 --- a/api-reference/agent/get-all-jobs.mdx +++ b/api-reference/agent/get-all-jobs.mdx @@ -8,10 +8,4 @@ This endpoint retrieves all writer jobs for the specified domain, providing an o ## Response -The response contains an `allSessions` array with details about each writer job including: -- Job execution status and completion state -- Branch information and pull request links -- Session identifiers and creation timestamps -- Files that were edited and completion messages - -Use this endpoint to get a comprehensive view of all agent activity for your domain. \ No newline at end of file +Use this endpoint to get a comprehensive view of all previous agent sessions. diff --git a/discovery-openapi.json b/discovery-openapi.json index 6dd51338d..c911e8368 100644 --- a/discovery-openapi.json +++ b/discovery-openapi.json @@ -577,7 +577,7 @@ } } }, - "/agent/{domain}": { + "/agent/job/{domain}": { "post": { "summary": "Create writer job", "description": "Creates a new AI writer job that can generate and edit documentation based on provided messages and branch information.", @@ -599,22 +599,17 @@ "schema": { "type": "object", "required": [ - "branchName", - "branchExists", - "messages" + "branch", + "messages", ], "properties": { - "branchName": { + "branch": { "type": "string", - "description": "The name of the git branch where changes should be made." - }, - "branchExists": { - "type": "boolean", - "description": "Whether the specified branch already exists in the repository." + "description": "The name of the git branch where the agent should work on, will be automatically created if it doesn't exist" }, "messages": { "type": "array", - "description": "Array of messages for the AI writer to process.", + "description": "A list of previous messages to provide to the assistant.", "items": { "type": "object", "required": [ @@ -641,7 +636,7 @@ }, "responses": { "200": { - "description": "Writer job created successfully", + "description": "Writer job created successfully (streaming response). X-Session-Id Header is sent back in the response", "headers": { "X-Message-Id": { "schema": { @@ -694,24 +689,15 @@ "schema": { "type": "object", "properties": { - "_id": { + "sessionId": { "type": "string", - "description": "Unique MongoDB ObjectId of the writer session." + "description": "The subdomain this session belongs to." }, "subdomain": { "type": "string", "description": "The subdomain this session belongs to." }, - "source": { - "type": "string", - "enum": ["slack", "api"], - "description": "Source of the writer session." - }, - "sessionId": { - "type": "string", - "description": "Unique session identifier." - }, - "branchName": { + "branch": { "type": "string", "description": "Git branch name where changes were made.", "nullable": true @@ -725,10 +711,6 @@ "enum": ["completed", "github_missconfigured", "error"], "description": "Reason for session halt." }, - "createdPullRequest": { - "type": "boolean", - "description": "Whether a pull request was created." - }, "pullRequestLink": { "type": "string", "description": "Link to the created pull request." @@ -737,14 +719,6 @@ "type": "string", "description": "Message for the user about the session outcome." }, - "editedFiles": { - "type": "boolean", - "description": "Whether any files were edited during the session." - }, - "lastTextStream": { - "type": "string", - "description": "Last text stream from the agent execution." - }, "todos": { "type": "array", "description": "List of todo items from the session.", @@ -814,24 +788,15 @@ "items": { "type": "object", "properties": { - "_id": { + "sessionId": { "type": "string", - "description": "Unique MongoDB ObjectId of the writer session." + "description": "The subdomain this session belongs to." }, "subdomain": { "type": "string", "description": "The subdomain this session belongs to." }, - "source": { - "type": "string", - "enum": ["slack", "api"], - "description": "Source of the writer session." - }, - "sessionId": { - "type": "string", - "description": "Unique session identifier." - }, - "branchName": { + "branch": { "type": "string", "description": "Git branch name where changes were made.", "nullable": true @@ -845,10 +810,6 @@ "enum": ["completed", "github_missconfigured", "error"], "description": "Reason for session halt." }, - "createdPullRequest": { - "type": "boolean", - "description": "Whether a pull request was created." - }, "pullRequestLink": { "type": "string", "description": "Link to the created pull request." @@ -857,14 +818,6 @@ "type": "string", "description": "Message for the user about the session outcome." }, - "editedFiles": { - "type": "boolean", - "description": "Whether any files were edited during the session." - }, - "lastTextStream": { - "type": "string", - "description": "Last text stream from the agent execution." - }, "todos": { "type": "array", "description": "List of todo items from the session.", From 44a4de793bd48d44af75dadc074497f670933a3c Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Sun, 28 Sep 2025 12:14:57 -0700 Subject: [PATCH 20/28] alphabetize endpoint groups --- docs.json | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs.json b/docs.json index 19483c462..56bd74f51 100644 --- a/docs.json +++ b/docs.json @@ -258,13 +258,6 @@ "api-reference/update/status" ] }, - { - "group": "Assistant", - "pages": [ - "api-reference/assistant/create-assistant-message", - "api-reference/assistant/search" - ] - }, { "group": "Agent", "pages": [ @@ -272,6 +265,13 @@ "api-reference/agent/get-agent-job", "api-reference/agent/get-all-jobs" ] + }, + { + "group": "Assistant", + "pages": [ + "api-reference/assistant/create-assistant-message", + "api-reference/assistant/search" + ] } ] }, From 1b29f2c2856395bf639ce0dc35920cc02ee7571a Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Sun, 28 Sep 2025 12:39:57 -0700 Subject: [PATCH 21/28] writer -> agent --- api-reference/agent/create-agent-job.mdx | 5 +++-- api-reference/agent/get-agent-job.mdx | 4 ++-- api-reference/agent/get-all-jobs.mdx | 2 +- discovery-openapi.json | 28 ++++++++++++------------ 4 files changed, 20 insertions(+), 19 deletions(-) diff --git a/api-reference/agent/create-agent-job.mdx b/api-reference/agent/create-agent-job.mdx index d788087fa..2d606312a 100644 --- a/api-reference/agent/create-agent-job.mdx +++ b/api-reference/agent/create-agent-job.mdx @@ -2,8 +2,9 @@ openapi: POST /agent/job/{domain} --- -This endpoint creates an AI writer job that can generate and edit documentation based on provided messages and branch information. The job executes asynchronously and returns a streaming response with the execution details and results. -If the branch doesn't exist, the agent will create it. If files are edited successfully, a draft pull request will be automatically created at the end of the job +This endpoint creates an agent job based on provided messages and branch information. The job executes asynchronously and returns a streaming response with the execution details and results. + +If a branch doesn't exist, the agent creates one. If files are edited successfully, a draft pull request is automatically created at the end of the job. ## Suggested usage diff --git a/api-reference/agent/get-agent-job.mdx b/api-reference/agent/get-agent-job.mdx index 6eef948f8..e24430aae 100644 --- a/api-reference/agent/get-agent-job.mdx +++ b/api-reference/agent/get-agent-job.mdx @@ -4,9 +4,9 @@ openapi: GET /agent/{domain}/job/{id} ## Usage -This endpoint retrieves the details and status of a specific writer job by its unique identifier. Use this to check the progress, status, and results of a previously created agent job. +This endpoint retrieves the details and status of a specific agent job by its unique identifier. Use this to check the progress, status, and results of a previously created agent job. -## Job Details +## Job details The response includes information such as: - Job execution status and completion state diff --git a/api-reference/agent/get-all-jobs.mdx b/api-reference/agent/get-all-jobs.mdx index a45eda5a5..51a586573 100644 --- a/api-reference/agent/get-all-jobs.mdx +++ b/api-reference/agent/get-all-jobs.mdx @@ -4,7 +4,7 @@ openapi: GET /agent/{domain}/jobs ## Usage -This endpoint retrieves all writer jobs for the specified domain, providing an overview of all agent activities and their current status. This is useful for monitoring and managing multiple concurrent or historical agent jobs. +This endpoint retrieves all agent jobs for the specified domain, providing an overview of all agent activities and their current status. This is useful for monitoring and managing multiple concurrent or historical agent jobs. ## Response diff --git a/discovery-openapi.json b/discovery-openapi.json index c911e8368..0cbb4ddde 100644 --- a/discovery-openapi.json +++ b/discovery-openapi.json @@ -579,8 +579,8 @@ }, "/agent/job/{domain}": { "post": { - "summary": "Create writer job", - "description": "Creates a new AI writer job that can generate and edit documentation based on provided messages and branch information.", + "summary": "Create agent job", + "description": "Creates a new agent job that can generate and edit documentation based on provided messages and branch information.", "parameters": [ { "name": "domain", @@ -605,11 +605,11 @@ "properties": { "branch": { "type": "string", - "description": "The name of the git branch where the agent should work on, will be automatically created if it doesn't exist" + "description": "The name of the Git branch that the agent should work on, will be automatically created if it doesn't exist" }, "messages": { "type": "array", - "description": "A list of previous messages to provide to the assistant.", + "description": "A list of previous messages to provide to the agent.", "items": { "type": "object", "required": [ @@ -636,7 +636,7 @@ }, "responses": { "200": { - "description": "Writer job created successfully (streaming response). X-Session-Id Header is sent back in the response", + "description": "Agent job created successfully (streaming response). X-Session-Id Header is sent back in the response", "headers": { "X-Message-Id": { "schema": { @@ -649,7 +649,7 @@ "text/plain": { "schema": { "type": "string", - "description": "Streaming response containing the writer job execution details and results." + "description": "Streaming response containing the agent job execution details and results." } } } @@ -659,8 +659,8 @@ }, "/agent/{domain}/job/{id}": { "get": { - "summary": "Get writer job by ID", - "description": "Retrieves the details and status of a specific writer job by its ID.", + "summary": "Get agent job by ID", + "description": "Retrieves the details and status of a specific agent job by its ID.", "parameters": [ { "name": "domain", @@ -678,12 +678,12 @@ "schema": { "type": "string" }, - "description": "The unique identifier of the writer job to retrieve." + "description": "The unique identifier of the agent job to retrieve." } ], "responses": { "200": { - "description": "Writer job details retrieved successfully", + "description": "Agent job details retrieved successfully", "content": { "application/json": { "schema": { @@ -761,8 +761,8 @@ }, "/agent/{domain}/jobs": { "get": { - "summary": "Get all writer jobs", - "description": "Retrieves all writer jobs for the specified domain, including their status and details.", + "summary": "Get all agent jobs", + "description": "Retrieves all agent jobs for the specified domain, including their status and details.", "parameters": [ { "name": "domain", @@ -776,7 +776,7 @@ ], "responses": { "200": { - "description": "All writer jobs retrieved successfully", + "description": "All agent jobs retrieved successfully", "content": { "application/json": { "schema": { @@ -784,7 +784,7 @@ "properties": { "allSessions": { "type": "array", - "description": "Array of all writer sessions for the domain.", + "description": "Array of all agent sessions for the domain.", "items": { "type": "object", "properties": { From 4159fb34d6481353eee8fc3206580c38ec6ca17e Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Sun, 28 Sep 2025 12:42:52 -0700 Subject: [PATCH 22/28] add links to endpoint pages --- ai/agent.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ai/agent.mdx b/ai/agent.mdx index 56a0e7fa0..231ff6eac 100644 --- a/ai/agent.mdx +++ b/ai/agent.mdx @@ -37,8 +37,8 @@ To get started, add the agent to your Slack workspace and mention it with `@mint The agent can only access repositories that you connect through the Mintlify GitHub App. Modify which repositories the agent can access in the [GitHub App settings](https://github.com/apps/mintlify/installations/new). ## Embed the agent via API -TODO: this whole section once the API is finalized -See the API reference for more info. + +The agent endpoints can be used to [create jobs](/api-reference/agent/create-agent-job), [get a specific job](/api-reference/agent/get-agent-job), and [get all jobs](/api-reference/agent/get-all-jobs). ## Write effective prompts From 9184563320bf41bee0ea1cd34fc7c3f00c8aacd4 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Sun, 28 Sep 2025 12:45:40 -0700 Subject: [PATCH 23/28] =?UTF-8?q?=F0=9F=92=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ai/agent.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ai/agent.mdx b/ai/agent.mdx index 231ff6eac..784eaaeb2 100644 --- a/ai/agent.mdx +++ b/ai/agent.mdx @@ -44,7 +44,7 @@ The agent endpoints can be used to [create jobs](/api-reference/agent/create-age Think of the agent as a helpful assistant that needs your guidance to complete tasks. If you give it clear instructions and context, it is more likely to complete the task successfully. More focused tasks are easier to complete, so break down complex projects into smaller steps. -Make your prompts specific and outcome-focused. A prompt like `@mintlify Improve the onboarding page` will have the agent apply general technical writing best practices to the page, but it may not improve the page in a way that truly helps your users. +Make your prompts specific and outcome-focused. A prompt like `@mintlify Improve the onboarding page` will have the agent apply general technical writing best practices to the page and patterns from your documentation, but it may not improve the page in the way that you were picturing. Try prompts based on outcomes you want your users to achieve or problems that you know they encounter. For example: `@mintlify A lot of users have trouble installing the CLI. Review the onboarding page and update the docs so that users can easily install the CLI` or `@mintlify Developers keep getting 401 errors when following our authentication guide. Review the auth docs and add clearer examples showing how to properly format the API key`. From ef4807f5e6a91ab0dcdd9374eb245cfa0dce483b Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Sun, 28 Sep 2025 12:47:40 -0700 Subject: [PATCH 24/28] add rate limit info --- api-reference/agent/create-agent-job.mdx | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/api-reference/agent/create-agent-job.mdx b/api-reference/agent/create-agent-job.mdx index 2d606312a..b21502eb3 100644 --- a/api-reference/agent/create-agent-job.mdx +++ b/api-reference/agent/create-agent-job.mdx @@ -6,7 +6,14 @@ This endpoint creates an agent job based on provided messages and branch informa If a branch doesn't exist, the agent creates one. If files are edited successfully, a draft pull request is automatically created at the end of the job. -## Suggested usage +## Rate limits + +The agent API has the following limits: -For best results, use the useChat hook from ai-sdk to send requests and handle responses. +- 10,000 uses per key per month +- 10,000 requests per Mintlify organization per hour +- 10,000 requests per IP per day + +## Suggested usage +For best results, use the [useChat hook from ai-sdk](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat) to send requests and handle responses. From 97aef0f747785a97fe227764c9497193be880c24 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Sun, 28 Sep 2025 12:52:31 -0700 Subject: [PATCH 25/28] spacing --- ai/agent.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ai/agent.mdx b/ai/agent.mdx index 784eaaeb2..2afe03038 100644 --- a/ai/agent.mdx +++ b/ai/agent.mdx @@ -29,8 +29,8 @@ To get started, add the agent to your Slack workspace and mention it with `@mint 2. Select the **Connect** button. 3. Follow the Slack prompts to add the `mintlify` app to your workspace. 4. Test that the agent is working and responds when you: - - Send a direct message to it. - - Mention it with `@mintlify` in a channel. + - Send a direct message to it. + - Mention it with `@mintlify` in a channel. ## Connect repositories as context From b7d24df2061578fe19ccbcd635e0c8d6a5a4e909 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Sun, 28 Sep 2025 12:58:52 -0700 Subject: [PATCH 26/28] update availability --- ai/agent.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ai/agent.mdx b/ai/agent.mdx index 2afe03038..ae91ddd85 100644 --- a/ai/agent.mdx +++ b/ai/agent.mdx @@ -5,7 +5,7 @@ icon: "pen-line" --- - The agent is available to anyone with access to your dashboard. + The agent is available on [Pro and Custom plans](https://mintlify.com/pricing?ref=agent). The agent creates pull requests with proposed changes to your documentation based on your prompts. When you send a request to the agent, it references your documentation, connected repositories, and Slack messages to create content that follows technical writing best practices and adheres to the Mintlify schema. Access the agent in your Slack workspace or embed it in custom applications with the API. From db3b55707d724ee410a6e1f237fd3680e6762850 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Sun, 28 Sep 2025 13:06:51 -0700 Subject: [PATCH 27/28] concision --- ai/agent.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/ai/agent.mdx b/ai/agent.mdx index ae91ddd85..ce57347dc 100644 --- a/ai/agent.mdx +++ b/ai/agent.mdx @@ -42,11 +42,11 @@ The agent endpoints can be used to [create jobs](/api-reference/agent/create-age ## Write effective prompts -Think of the agent as a helpful assistant that needs your guidance to complete tasks. If you give it clear instructions and context, it is more likely to complete the task successfully. More focused tasks are easier to complete, so break down complex projects into smaller steps. +Think of the agent as a helpful assistant that needs your guidance to complete tasks. Give it clear instructions and context. More focused tasks are easier to complete, so break down complex projects into smaller steps. -Make your prompts specific and outcome-focused. A prompt like `@mintlify Improve the onboarding page` will have the agent apply general technical writing best practices to the page and patterns from your documentation, but it may not improve the page in the way that you were picturing. +Make your prompts specific and outcome-focused. Generic prompts like `@mintlify Improve the onboarding page` apply general best practices, but may not improve content in the specific way that you were picturing. -Try prompts based on outcomes you want your users to achieve or problems that you know they encounter. For example: `@mintlify A lot of users have trouble installing the CLI. Review the onboarding page and update the docs so that users can easily install the CLI` or `@mintlify Developers keep getting 401 errors when following our authentication guide. Review the auth docs and add clearer examples showing how to properly format the API key`. +Try prompts based on outcomes you want your users to achieve or problems that they encounter. For example: `@mintlify A lot of users have trouble installing the CLI. Review the onboarding page and update the docs so that users can easily install the CLI` or `@mintlify Developers keep getting 401 errors when following our authentication guide. Review the auth docs and add clearer examples showing how to properly format the API key`. Use broad prompts for general content maintenance like fixing typos, updating redirects, or renaming a feature throughout your docs. For example: `@mintlify Find and fix all typos in the docs` or `@mintlify change all unordered lists to use * instead of -`. @@ -55,13 +55,13 @@ Use broad prompts for general content maintenance like fixing typos, updating re The agent assists with many different documentation tasks. These workflows show some of the ways you can integrate the agent into your documentation process. Try an approach that fits how your team currently works and adapt it to your specific needs. ### Iterate on a prompt in a Slack thread -Prompt the agent, then continue to mention it with `@mintlify` in the same thread to refine and iterate on the pull request that it creates. For example: `@mintlify Our quickstart page needs a new section on inviting collaborators` then `@mintlify The new section should be called "Inviting collaborators"` and any other iterations. +Prompt the agent, then continue to mention it with `@mintlify` in the same thread to refine and iterate on the pull request that it creates. For example: `@mintlify Our quickstart page needs a new section on inviting collaborators`. Then `@mintlify The new section should be called "Inviting collaborators"`. Followed by any other iterations. ### Start with the agent, finish manually Prompt the agent to begin a project, then check out the branch it creates and finish the task in your local environment or the web editor. The agent can help you get started, then you can take over to complete the task. For example: `@mintlify Update the quickstart page to include information about inviting collaborators` and then checkout the branch to make any additional changes using your preferred method. ### Update docs when merging feature changes -When you merge a feature pull request, prompt the agent with a link to the pull request to automatically update relevant documentation. For example: `@mintlify This PR adds a new authentication method. Update the docs to include the new auth flow: [PR link]`. +When you merge a feature pull request, share the PR link with the agent to update relevant docs. For example: `@mintlify This PR adds a new authentication method. Update the docs to include the new auth flow: [PR link]`. ### Generate release notes from commit history Prompt the agent with a specific pull request or a time period to generate release notes or changelog updates based on the commit history. For example: `@mintlify Generate release notes for this PR: [PR link]` or `@mintlify Generate release notes for the last month`. From c6a2c0ee7534f41b700b293157619083309ef3ab Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Sun, 28 Sep 2025 13:13:11 -0700 Subject: [PATCH 28/28] update access requirements --- ai/agent.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/ai/agent.mdx b/ai/agent.mdx index ce57347dc..24d9a073d 100644 --- a/ai/agent.mdx +++ b/ai/agent.mdx @@ -5,7 +5,7 @@ icon: "pen-line" --- - The agent is available on [Pro and Custom plans](https://mintlify.com/pricing?ref=agent). + The agent is available on [Pro and Custom plans](https://mintlify.com/pricing?ref=agent) for anyone with access to your dashboard. The agent creates pull requests with proposed changes to your documentation based on your prompts. When you send a request to the agent, it references your documentation, connected repositories, and Slack messages to create content that follows technical writing best practices and adheres to the Mintlify schema. Access the agent in your Slack workspace or embed it in custom applications with the API. @@ -28,7 +28,8 @@ To get started, add the agent to your Slack workspace and mention it with `@mint 1. Navigate to the [agent](https://dashboard.mintlify.com/products/agent) page of your dashboard. 2. Select the **Connect** button. 3. Follow the Slack prompts to add the `mintlify` app to your workspace. -4. Test that the agent is working and responds when you: +4. Follow the Slack prompts to link your Mintlify account to your Slack workspace. +5. Test that the agent is working and responds when you: - Send a direct message to it. - Mention it with `@mintlify` in a channel.