Content
read: Fetch the full MDX of any page onbranch, or on your deploy branch when you omit it. Pass a page path, such asguides/setup, or the last segment of an editor URL, which is the page ID with an optional title in front of it. When you use a page ID from an editor URL, pass the branch from that URL asbranch. The response includes afilePaththat you can pass aspathtoedit_pageandwrite_page, and aversionof the content it returned. PassforEdit: trueto read the live page instead of its saved copy. UseforEdit: truebefore you overwrite the page withwrite_page. To read a private page, pass itsprivate-page-<uuid>node ID fromlist_nodeswithvisibility: "private". Private reads don’t need abranchand require an OAuth session. The admin MCP rejects client and machine-to-machine tokens for private-page access.search: Search the pages onbranchby meaning and exact wording, or your deploy branch when you omit it. Pass a question, topic, name, or exact phrase asquery. By default,searchreturns the most relevant pages first asresults. Each result has the page’spathandtitle, andsnippetswith the matching lines. Whensearchis confident in the top result, that result also includes the page’s fullcontent, up to 16 KB. The next results include thesectionaround their best match. Passlimitto return up to 20 pages (default 6). To list every page that contains a phrase, such as before a rename, passmode: "all"(defaultlimit100, maximum 500). Passingregex: truetreatsqueryas a regular expression and always usesmode: "all".edit_page: Apply a targeted edit to a page. Passpathin the same forms asread. PassoldStringandnewStringfor one replacement, or pass aneditslist of up to 100 replacements to change several parts of a page in one call. Mintlify applies the edits in order, each to the result of the previous one. If any edit fails, none of them apply. Likewrite_page,edit_pagereturnsnotRenderedfor markup the edit adds that the editor drops. It doesn’t report markup that was already on the page. To edit a private page, pass itsprivate-page-<uuid>node ID aspath. Private edits require an OAuth session with an editor role or higher on the page and don’t need abranch.write_page: Overwrite a page’s full MDX content. Passpathin the same forms asread. Before you overwrite a page, callreadwithforEdit: trueand pass the returnedversiontowrite_pageasbaseVersion. If the page changed since that read, Mintlify refuses the write, changes nothing, and returnspage_changed. Read the page again and reapply your change. If you omitbaseVersionon a page that has content,write_pagereturnsbase_version_required. A page with only frontmatter doesn’t need abaseVersion. Also accepts aprivate-page-<uuid>node ID to overwrite a private page under the same OAuth and role requirements asedit_page. Usecreate_nodeto create a new private page. If the content includes markup the Mintlify editor drops, such as<script>tags,<style>blocks, event handlers likeonClick, or JavaScript expressions, the response includes anotRenderedfield. Each entry lists the droppedelement, itsline,whythe editor drops it, and what to useinstead, such as Tailwind classes, inlinestyle={{}}objects with literal values, or Mintlify components like accordions and tabs.read_page_history: List a page’s saved version history onbranch, or on your deploy branch when you omit it. Passpathin the same forms asread, including aprivate-page-<uuid>node ID. Returnsversions, newest first, and anextCursor. Each version has aversionId,createdAt, andauthors, each with anameand atypeofuser,git, orsystem. Passlimitto return 1 to 50 versions per call (default 20), and passnextCursorback ascursorto list older versions. Pass aversionIdto get that version’s full MDX ascontent. The tool is read-only. To restore an earlier version, callreadon the page withforEdit: true, then pass the earlier version’scontenttowrite_pagewith that read’sversionasbaseVersion. If that version contains inline data that’s no longer on the page,write_pagecan’t restore it. Restore that version from version history in the editor instead. Errors includepage_not_found,version_not_found, andinvalid_cursor.
Inline data
Pages can embed images and other files as base64 data URLs. To keep responses small,read, search, diff, read_page_history, and read_comments replace each base64 payload of 1,000 characters or more with a placeholder such as [elided 48210 chars #1234567890].
Keep these placeholders unchanged when you pass content back. edit_page, write_page, create_node, and suggest_edit replace each placeholder with the original data from the current content of the target page.
If a placeholder doesn’t match data on the target page, Mintlify refuses the write, changes nothing, and returns inline_data_unresolved. Copy placeholders only from a read of the same page. If Mintlify can’t read the page to restore placeholders, it returns inline_data_source_unreadable and changes nothing. Try the call again.
Uploads
upload_file: Start uploading a local file. Pass the destinationpath, the file’scontentType, and its exactsizein bytes. Returns anuploadId, a presigneduploadUrl, and theheadersto send with the upload.finalize_file_upload: Save an uploaded image tobranch. Pass theuploadIdand the samepath. Returns thesrcto reference in MDX withedit_pageorwrite_page, or in thelogoorfaviconfields ofdocs.jsonwithupdate_config.
upload_file, the AI tool uploads the file bytes to uploadUrl with a PUT request and the returned headers. For example:
path, such as images/dashboard.png, and the branch to upload_file. After the upload, call finalize_file_upload. Mintlify checks that the uploaded file’s contents match its extension before saving it. An upload to an existing path replaces that image. Only logo and favicon uploads can be SVG files: pass purpose: "logo" to both tools when you upload one. Page images can’t be SVG. Saved images appear in status and publish with your other edits when you call publish.
To write a page from a local Markdown file, pass a .md or .mdx path with contentType set to text/markdown or text/plain. Page uploads don’t need a branch or finalize_file_upload. After the upload, pass the uploadId in place of content to write_page, or as data.uploadId to create_node. This avoids resending a large page’s full content in the tool call.
Use the uploadId within 10 minutes. Each uploadId works once, on the same project and for the same user or client that created it. Mintlify deletes the uploaded file after the write. A reused or expired uploadId returns upload_not_found.
Comments
Work with the comments and suggestions that your team leaves in the dashboard editor.read_comments: List the open comment and suggestion threads on a page, oldest first. Passpathin the same forms asread. Each thread includes athreadId, itstype(commentorsuggestion), thequotedTextit’s anchored to, thesuggestedTextfor suggestions, and itscommentswith eachauthor,content, andcreatedAt. If the anchored text no longer exists on the page, the thread includesanchorRemoved: trueandquotedTextshows the original quote. Reads threads onbranch, or on your deploy branch when you omit it.add_comment: Start a new comment thread on a page without changing its content. Use it to leave feedback for your team instead of editing. Passpathin the same forms asread, thecontentof the comment, andquotedText: the smallest unique span of visible text to anchor to, within one paragraph or heading. Use rendered words, not Markdown or MDX syntax. For example, quotecustom domain, not[custom domain](/path). Returns the newthreadId. If the text isn’t on the page, the error isno_match. If it matches more than once, the error isnot_unique, so quote a longer span.suggest_edit: Propose a tracked-changes suggestion on a page instead of editing it. The original text stays on the page with a strikethrough and the replacement appears alongside it. Nothing changes until someone accepts or rejects the suggestion in the dashboard editor. Passpathin the same forms asread,oldString, andnewString.oldStringis the smallest unique span of visible text to replace, within one paragraph or heading. Use rendered words, not Markdown or MDX syntax. Pass an emptynewStringto suggest a deletion. Pass an optionalcommentto explain why the change helps. Mintlify posts it as the agent’s reply in the suggestion thread. The oldernoteparameter still works as a deprecated alias forcomment. Returns the newthreadIdwith theoriginalTextandsuggestedText, trimmed to the span that changes. If the same suggestion is already open, the response includesalreadyExists: trueand the existingthreadId. Theno_matchandnot_uniqueerrors work as they do foradd_comment. The error isno_changewhen both strings are the same, andconflicting_annotationwhen the text overlaps another open suggestion.reply_to_comment: Reply to a thread bythreadIdwithcontent. Passresolve: trueto also resolve the thread. Mintlify posts the reply as the agent on behalf of the authorizing user, and it appears live in the dashboard editor.resolve_comment: Resolve a thread without replying.read_inbox: List your dashboard inbox on a project, newest activity first. The inbox includes comments and mentions, suggested edits, review requests, and private pages and folders shared with you. By default,read_inboxreturns open items. Passstateasopen,done, orall, andsectionascomment,suggestion,invitation,request, orall(default). Therequestsection includes review requests and invitations. Passfilterto narrow comments tomentionsoron-my-page(pages you own), or suggestions to those frompeopleor theagent, or therequestsection torequestsorinvites. The filter must matchsectionunlesssectionisall. PassdateFromanddateToas ISO 8601 date-times to limit items by their latest activity. Passlimitfor 1 to 50 items per call (default 20), and passnextCursorback ascursorto list older items. Each item includes itscategory,state,latestActivity, andtarget. Whentarget.threadis present, unresolved, and not on a private page, callread_commentswith itsfilePathand reply withreply_to_comment, both on itsbranch.restricteditems don’t include thread details.read_inboxis read-only and never marks items as read or done. Errors includeinvalid_filter,invalid_date_range, andinvalid_cursor.
add_comment, suggest_edit, reply_to_comment, and resolve_comment require an OAuth session and a branch. They act on the threads left on that branch, and work on your deploy branch even when edits to it require a pull request. You can reply to suggestion threads, but you must accept or reject suggestions in the editor. Comments on private pages aren’t available through the admin MCP. read_inbox also requires an OAuth session, and only returns the inbox of an active member of the project’s organization.
Navigation
list_nodes: Walk the navigation tree ofbranch, or of your deploy branch when you omit it, with optional filters. Filter byparentId(userecursive: trueto include all descendants), one or more node types, or any division scope:language,version,tab,dropdown,anchor,product, oritem. Uploaded files and folders (fileandfile_directorynodes) appear only when you include them in the type filter. Each node returns itsid,type,text, andparent, pluspath,pageId, andhiddenwhen they apply. Pass a page’spathtoreadto get its content and frontmatter. Results paginate through an opaquecursor. Passvisibility: "private"to list the private pages and folders the OAuth user can access instead of the branch navigation tree. Private listing ignoresbranchand the other filters, and returns each node’srole.create_node: Add a new page, group, tab, anchor, version, language, product, or dropdown. Passvisibility: "private"withdata.type: "page"ordata.type: "group"to create a private page or private folder in the caller’s private tree. The caller becomes the node’s manager. Private creation requires an OAuth session, doesn’t need abranch, and places the node at the private root or under an existingprivate-folder-<uuid>parent. For new pages, the response includes aneditorUrlthat opens the page in your dashboard. If a page already exists at thepathonbranch,create_nodewrites the new content into that page instead of failing. The page keeps its place in the navigation, even if you pass a different parent, and the response includesupdated: true. If Mintlify adds a new page to the navigation but can’t save its content,create_nodereturnsPAGE_SEED_FAILED. Callcreate_nodeagain with the samepathto write the content.update_node: Update a node’s properties in place (rename a group, change an icon, set a default version). Accepts aprivate-page-<uuid>orprivate-folder-<uuid>node ID to rename a private page or folder or change its icon or tag. Private updates require an OAuth session with an editor role or higher and don’t need abranch.move_node: Move a node, including renaming a page’s path.delete_node: Remove a node from the navigation. Accepts aprivate-page-<uuid>orprivate-folder-<uuid>node ID to delete a private page or folder from the caller’s private tree. Private deletions require an OAuth session with a manager role on the node and don’t need abranch.
create_node, update_node, move_node, or delete_node call leaves the navigation in an invalid state, the response includes a navigationErrors field that describes the problem. For example, a page placed at the root next to tabs returns navigationErrors. Mintlify can drop invalid nodes from the published navigation, so fix these errors before you call publish.
Configuration
update_config: Change top-leveldocs.jsonsettings, such as theme, colors, logo, navbar, footer, redirects, integrations, and SEO. It can’t changenavigation; use the navigation tools instead. Mintlify rejects an invalid configuration as a whole.
Mintlify skill
read_skill: Read Mintlify’s guide to writing docs, which covers pages, components, widgets, navigation, anddocs.json. It’s the same Mintlify skill that the agent uses. Call it withoutpathto getSKILL.md, the skill’s index, and afileslist of its reference files. Pass a file from that list aspath, such asreference/widgets.md, to read it. The tool is read-only and doesn’t need asubdomainorbranch. If the file doesn’t exist, it returnsskill_file_not_foundwith thefileslist.
skills list of your organization’s and your own agent skills that are turned on, each with a name, description, and path. Pass a skill’s path, such as org/release-notes/SKILL.md, to read its instructions. The response lists the skill’s reference files in files, and you can pass any of them as path. Personal skill paths start with me/ and appear only for OAuth sessions.
The admin MCP tells AI tools to call read_skill before they write, restructure, or style pages, and to follow any organization or personal skill whose description fits the task.
Project management
Project management tools handle project-level operations, such as managing automations, project settings, custom domains, Git sources, authentication, members, analytics, and private page sharing. They act on the live project, not on a branch. Each tool takes asubdomain for the project to act on. Organization-wide connections must pass subdomain. Call list_deployments to find it. Read tools also accept subdomains, a list of up to 25 projects, and return a result or error for each one. Most tools take a request object whose action field selects the operation. For example:
get_deployment_settings: Read a project’s dashboard settings, including editor publishing and Reviewing settings, Git sources, custom hostname status, and source checks in one call. Slack configuration and snippets are opt-in.get_analytics_report: Read a prebuilt analytics report, such as page views, popular pages, referrals, feedback, assistant chats, or search quality. Select the report withrequest.report. Large results paginate withmaxRowsandrowOffset. For custom queries, usequery_analytics.get_analytics_schema: Read the tables, events, and SQL rules thatquery_analyticsaccepts. The AI tool calls it once before writing a query.query_analytics: Run one read-onlySELECTquery on your site’s analytics, such as page views, search, assistant, feedback, and traffic. Results are already scoped to the project. If analytics queries aren’t enabled for the project, both analytics query tools return anot_enablederror.get_workflows: List automations, get one automation, or page through its runs.list_repos_and_prs: List connected repositories, a repository’s pull requests, or available integrations to use in an automation.
update_deployment_settings: Change one dashboard setting, such asnoindex,base_path,name,disable_ai_chat,search_settings,privacy,custom_scripts, or an add-on. Useeditor_publishingto change Reviewing settings. Only org admins can change them, with the same rules as the dashboard. Useupdate_configfordocs.jsonsettings.manage_custom_domain: Add or remove a custom domain, provision its hostname, or retrigger hostname validation.manage_git_source: Add, update, remove, or reorder the Git repositories a project builds from, or set the base source.manage_access_auth: Configure or remove site authentication, add or delete passwords, configure end-user authentication, or switch which one is active. Switching carries over only a JWT configuration. If the active configuration uses any other type, the switch fails with a409error and leaves your site unchanged. To change to a different type, configure the new authentication directly. When an action turns on site authentication, including a switch from end-user authentication, Mintlify deletes existing previews that don’t have organization login or password protection. SetpreviewDeploymentstodelete_unauthenticated(default),delete_all, orkeepto choose what happens to existing previews.manage_workflow: Create, update, enable or disable, delete, or trigger an automation. In a multi-repository project, pass an optionalrepo_name(for example,mintlify/docs) when you create or update an automation to set its target repository. The repository must be connected to the project. If you omit it, new automations use the base source and updates keep the current target.manage_workflow_prs: Merge or close a pull request that an automation run opened. To merge a pull request for a branch the AI tool edited, usepublishwithmerge: trueinstead.manage_members_sharing: List, invite, or remove organization members, update their roles, or manage private page grants and moves in bases. One call invites up to 250 people and skips anyone who is already a member or has a pending invite.
state, so the AI tool can confirm the change without a second call. Each action checks the connection’s granted scopes and your dashboard role. An action you aren’t authorized for returns an error such as insufficient_scope. To fix it, see Tool calls return insufficient_scope.
Review requests
These tools appear only when your project requires review before publishing.list_review_requests and request_review take an optional branch, which defaults to your deploy branch. On another branch, a review request covers the branch’s changes against your deploy branch. If your deploy branch has GitHub branch protection, request reviews on a feature branch.
list_review_requests: List the open review requests on a branch. Each request includes itsrequester, itsreviewersand theirstate, and itspages. Each page has apath,title, andapprovalofapproved,pending, orstaleif the page changed after approval and needs another review. Changes that don’t belong to a page, such as navigation and site settings, appear as one item titledSite changes.request_review: Ask reviewers to approve your pending changes. Pass up to 100pagesin the same forms asread, and thereviewers, each as anemailor arole.role: "admin"asks every admin.role: "editor"asks every publisher, or every editor if your organization doesn’t have the publisher role. If you have pending changes that don’t belong to a page and no other open request includes them, Mintlify adds theSite changesitem to the request. Mintlify only asks active members, other than you, who can approve. Each reviewer gets an email and an inbox item. Errors includeno_pending_changeswhen a page has nothing to review,no_reviewerswhen no one who can approve matchesreviewers, andreview_unavailablewhen the branch can’t take review requests, such as a protected deploy branch.add_reviewers: Add reviewers to an open review request byrequestId, without withdrawing it, like adding reviewers in the editor. Passreviewersin the same forms asrequest_review. Existing approvals stay. Mintlify skips the requester, people already on the request, and members who can’t approve, and only new reviewers get an email and an inbox item. Returns the updatedrequestand theaddedemails. Errors includerequest_not_foundandno_reviewers.withdraw_review_request: Withdraw a review request you made byrequestId. Pass arevieweremail to remove only that reviewer. Removing the last reviewer withdraws the request. The pages keep their pending changes.approve_review_request: Approve someone else’s review request byrequestId, like clicking Approve in the editor. The admin MCP tells the AI tool to approve only when you ask it to approve that specific request, and to confirm the requester and pages with you first. Returnsown_requestfor your own request,own_branchfor a branch you created,not_reviewerif your role can’t approve,changedif the changes were edited since the AI tool read them, andgithub_rejectedif GitHub refused the approval, for example because you haven’t connected your GitHub account. On a protected GitHub branch, approving also approves the pull request in GitHub as your connected account.publish_review_request: Publish an approved review request byrequestId, with atitlefor the commit message, like publishing a teammate’s approved changes in the editor. Admins and publishers can publish. The admin MCP tells the AI tool to publish only when you ask it to publish that specific request. Returnsnot_approveduntil every page has the approvals it needs,navigation_heldwhile another open request holds navigation changes that this request needs, andnot_allowedif your role can’t publish. On a feature branch, it merges the branch’s pull request into your deploy branch and returnsmerged. It returnsno_pull_requestif the branch has no pull request yet, so callpublishon the branch first, andmerge_not_allowedif you must merge in the editor. Follow the returneddeploymentwithdeployment_status.
Branches and publishing
list_deployments: List the projects your connection can access, returning each{subdomain, name, projectType}.projectTypeissitefor a site orworkspacefor a knowledge base. Call this to discover whichsubdomainto pass.create_branch: Start a new branch off your deploy branch, or off the existing branch you pass asfrom, with atitlethat also names its pull request. Returns thebranchNameto pass asbranch. See Work on a branch. You don’t need it to edit the deploy branch directly.list_branches: List Git branches available for a project’s repository, with optionalqueryfiltering. Returns the branch names, total count, and the deploy branch. Pass any of them asbranch.status: List the edited files, changeddocs.jsonkeys, and pending navigation diff onbranch, or on your deploy branch when you omit it. On the deploy branch, lists only your changes.diff: List all changes betweenbranchand your deploy branch. Each changed file anddocs.jsonentry includesauthorsandbyYou.authorslists the members whose unpublished edits the entry contains.byYouistruewhen the entry includes your own edits. UsebyYouto tell your changes apart from a colleague’s on a shared branch.publish: On the deploy branch, commit only your pending changes directly. If your project requires review and you aren’t an admin, returnsreview_requiredon the deploy branch or when you passmerge: true. See Projects that require review. On a branch, commit pending changes and return the branch’s pull request, opening one if needed. Passmerge: trueto also merge the pull request when edits to the deploy branch are allowed. When the changes reach the deploy branch, also returns adeploymentstatus to follow withdeployment_status.deployment_status: Check whether published changes are live on your docs site. Pass thecommitShafrompublish, or omit it to check the latest deploy. Returns astateofpending,queued,building,live,not_live,failed, orskipped, along withliveand amessageto share with you.not_livemeans the site still serves an earlier version, for example because the deploy was rolled back or your deployment is pinned to an earlier version.discard: Abandon the edits onbranch. On the deploy branch, reverts only your pending changes. On another branch you created, deletes the branch and closes its pull request.