Mintlify

View saved version →

---
name: editing-docs-content
description: Use when changing the text or MDX body of documentation pages through the Mintlify Admin MCP — fixing typos, rewriting sections, updating code samples, or making any content edit that should ship as a commit or PR.
---

# Editing Docs Content

## Overview

Content edits happen inside a checked-out editing session on an isolated git branch. Nothing goes live until `save` publishes the branch. Every editor tool fails with "No active session" until you `checkout`.

## Workflow

1. `list_deployments` — find the subdomain (skip if pinned or already known).
2. `checkout { subdomain, slug: "fix-auth-typos" }` — opens the session (~7s). Surface the returned `editorUrl` to the user so they can follow along.
3. Locate content: `search { query }` greps every page on the branch (literal string by default, `regex: true` for regex, results capped at 30KB — refine if `truncated`). `read { path }` returns the full MDX of one page. Both reflect in-session edits immediately.
4. Edit:
   - Targeted change → `edit_page { path, oldString, newString, replaceAll? }` (string-replace, like a code editor Edit tool). `replaceAll` is per-page; a docs-wide sweep is one `edit_page` call per matched path from `search`.
   - Full rewrite → `write_page { path, content }`.
   - If a search hit might sit in frontmatter rather than body, `read` the page first — frontmatter fixes go through `update_node`, not `edit_page`.
5. Verify with `diff` (patch per changed file) or `get_session_state` (branch, edited files, nav diff).
6. `save { title, mode? }` — publishes (~10s).

## Save modes

| mode | Behavior |
|------|----------|
| `auto` (default) | Opens a PR; auto-merges only when the deployment's agent review setting is push-to-main and the deploy branch is unprotected (`merged: true` in the response) |
| `pr` | Opens a PR and always leaves it open for review |
| `commit` | Commits to the **session branch** in git without opening a PR — a snapshot, never a direct write to the deploy branch |

Saving again in the same session commits to the existing PR branch. `discard_session` abandons everything without publishing.

## Critical: frontmatter is not body content

`edit_page` / `write_page` are for the MDX **body only**. Frontmatter fields (`title`, `sidebarTitle`, `description`, `icon`, `canonical`, `og:*`, `keywords`, `noindex`, `hidden`, …) round-trip through structured node metadata — set them with `update_node { nodeId, data: { type: 'page', ... } }`. The site-level description lives in `docs.json` via `update_config`.

## Common mistakes

- Editing frontmatter with `edit_page` — silently wrong; use `update_node`.
- Calling `read`/`edit_page` before `checkout` — "No active session".
- Assuming `save` merged: check `merged` in the response; most deployments leave the PR open.
- Paths are page hrefs (`/quickstart` or `guides/setup`), leading slash and `.mdx` optional.
- Renaming a page path: `move_node`, never a write to a new path plus delete.

View saved version →

---
name: managing-deployment-settings
description: Use when changing live deployment settings through the Mintlify Admin MCP — custom domains, authentication, git sources, AI assistant toggle, noindex, custom scripts, source checks, snippets — or when managing org members and roles.
---

# Managing Deployment Settings

## Overview

Deployment and member operations run through code mode (`execute_code`) with **no checkout and no PR safety net — every write hits the live deployment immediately**. Read current state first, confirm with the user before auth/domain changes, and re-read after writing.

**REQUIRED BACKGROUND:** the `using-code-mode` skill covers return semantics and `{ subdomain }` targeting.

## Namespace `deployment`

| Area | Methods |
|------|---------|
| Read state | `get({})` — subdomain, name, basePath, customDomains, noindex, plan, … |
| Identity | `updateName`, `updateBasePath` ('' or '/docs'), `updateNoindex` |
| Custom domains | `addCustomDomainV2` (returns DNS records to configure), `removeCustomDomain`, `createCustomHostname`, `getCustomHostnameStatus`, `retriggerCustomHostnameValidation`, `deleteCustomHostname` |
| Docs auth | `updateAuth` (jwt / oauth-with-client-secret / password / mintlify), `updateUserAuth` (shared-session / jwt / oauth), `toggleAuth`, `deleteAuth`, `deleteUserAuth`, `addAuthPassword`, `deleteAuthPassword`, `deleteAuthJwtKeyPair` |
| Git sources | `getGitSources`, `addGitSource`, `updateGitSourceItem`, `removeGitSource` (by index), `reorderGitSources`, `setBaseGitSource` |
| AI assistant | `updateDisableAiChat({ disableAiChat })` — `true` turns the assistant **off**; `updateChatConfig` tunes assistant behavior when it is on |
| Add-ons | `updateAddOnFeedback`, `updateAddOnRelatedPages`, `updateSearchSettings`, `updatePrivacyConfig`, `updateCustomScripts` |
| Quality checks | `getSourceChecks`, `updateSourceChecks` (link-rot, spellcheck) |
| Editor publishing | `updateEditorPublishingSettings` (PR instructions, draft default, merge method) |
| Snippets | `getSnippets` |

Several auth/domain methods require a user-authorized token; `unauthorized` errors mean the token lacks the scope or user grant, not that the method is wrong.

## Namespace `members` (org-scoped)

These operate on the organization, not a single deployment: `listMembers({ includeRoles? })` (pass `includeRoles: true` to get each member's roles — omitted by default), `updateMemberRoles({ userId, roles })` (SSO-managed roles cannot be changed), `removeMember({ userId })`.

## Example: audit before touching auth

```
const current = await deployment.get({});
const sources = await deployment.getGitSources({});
({ current, sources });
```

## Common mistakes

- Writing without reading — always `deployment.get({})` first and echo the plan to the user for auth, domain, or member removals.
- Guessing payload shapes — `updateAuth`/`updateUserAuth` are discriminated unions; pull the schema via `search_code_operations` first.
- Removing git sources by guessed index — list first, indices shift after removal.
- Renaming preview deployments — `updateName` rejects them.
- Expecting a rollback path — there is no session/branch here; capture the pre-change state in the same script's logs.

View saved version →

---
name: managing-navigation
description: Use when adding, renaming, moving, or deleting docs pages, groups, tabs, anchors, versions, languages, or products in the navigation tree through the Mintlify Admin MCP, or when restructuring the sidebar.
---

# Managing Navigation

## Overview

Navigation is a tree of typed nodes edited with dedicated node tools inside a checked-out session — never through `update_config` (which rejects the `navigation` key). Node types: `page`, `group`, `tab`, `anchor`, `version`, `language`, `product`. Parent/child compatibility is enforced (groups cannot contain tabs; pages have no children).

## Explore first

`list_nodes` filters the tree: `parentId: null` = root nodes, `recursive: true` = all descendants (pair with omitted/null `parentId` to dump the whole tree), `type` = single type or array, plus `language`/`version`/`tab` scope filters. Paginates via `cursor`/`nextCursor` (limit max 500). You need real `nodeId`s from here before any mutation.

**Finding a page's nodeId by path**: `list_nodes { type: 'page', recursive: true }` and match each node's `data.href` against the page path (the same path `search` results and `read` use). There is no direct path-lookup parameter.

## Quick reference

| Task | Tool |
|------|------|
| New page | `create_node { parentId, data: { type: 'page', path, content } }` (MDX validated) |
| New group/tab/version/… | `create_node` with that type's name-shaped `data` |
| Rename group, set page frontmatter, change icon | `update_node { nodeId, data }` — partial merge, `data.type` must match stored type |
| Reorder or reparent | `move_node { nodeId, parentId?, order? }` — at least one required; `order` is 0-based; `parentId: null` = root |
| Rename a page's URL path | `move_node` (path/`href` is immutable in `update_node`) |
| Remove node + subtree | `delete_node { nodeId }` — returns `deletedNodeIds` |
| Redirect after deletion | `update_config { op: 'add_redirect', redirect: { source, destination, permanent? } }` — point `destination` at the closest surviving replacement page |

## Page frontmatter lives here

`update_node` with `data.type: 'page'` is the correct tool for `title`, `sidebarTitle`, `description`, `icon`, `tag`, `canonical`, `og:*`, `keywords`, `noindex`, `hidden`, `deprecated` — the merged fields serialize back into the MDX `---` block on save. `edit_page` must not touch frontmatter.

## Common mistakes

- Deleting a published page without adding a redirect — breaks inbound links; pair `delete_node` with `add_redirect`.
- Trying to set `href`/`pageId` via `update_node` — rejected as immutable; use `move_node`.
- Moving nodes across version/tab/language/product boundaries unintentionally — allowed, but the response flags `crossedBoundary: true`; check it.
- Guessing `nodeId`s — always fetch them from `list_nodes` first.
- Forgetting `save` — nav edits stay on the session branch until published.

View saved version →

---
name: managing-workflows
description: Use when creating, updating, enabling, disabling, triggering, or debugging Mintlify Workflows (scheduled or push-triggered docs automations) through the Admin MCP, or when checking why a workflow run failed.
---

# Managing Workflows

## Overview

Workflows are deployment-level automations managed through code mode (`execute_code`) — no checkout needed, and changes apply to the live deployment immediately.

**REQUIRED BACKGROUND:** read the `using-code-mode` skill first for script return semantics and `{ subdomain }` targeting.

## Methods (namespace `workflows`)

| Method | Notes |
|--------|-------|
| `listWorkflows({})` | All workflows on the deployment |
| `getWorkflow({ workflowSchemaId })` | One workflow |
| `createWorkflow({ name, on, ... })` | Enforces plan limits and trigger validation |
| `updateWorkflow({ workflowSchemaId, ... })` | Dashboard validation path |
| `setWorkflowEnabled({ workflowSchemaId, enabled })` | Enabling re-checks plan limits |
| `triggerWorkflow({ workflowSchemaId })` | Manual run; enforces monthly run limits |
| `deleteWorkflow({ workflowSchemaId })` | Soft delete |
| `listWorkflowRuns({ workflowSchemaId?, status? })` | Run history, filterable |

Triggers (`on`) are either push-based (`{ push: [{ repo, branch?, isDeploymentGitSource? }] }`, max 10 repos) or cron (`{ cron: '0 9 * * 1' }`). Fetch the exact current schema with `search_code_operations { query: 'create workflow', namespace: 'workflows' }` before creating — the full `inputSchema` comes back in the hit.

## Example: find why runs are failing

```
const wfs = await workflows.listWorkflows({});
const runs = await workflows.listWorkflowRuns({ status: 'failed' });
({ workflows: wfs, failedRuns: runs });
```

## Common mistakes

- Guessing the `createWorkflow` payload — it is a large validated union; pull the schema via `search_code_operations` first.
- Forgetting these writes are live — disabling or deleting a workflow takes effect immediately.
- Triggering repeatedly to "retry" — manual triggers count against monthly run limits.
- Checking out an editor session first — workflows are code-mode, not session-scoped.

View saved version →

---
name: mintlify
description: Set up, write, and publish documentation sites with Mintlify, and work on existing Mintlify projects. Use when the user wants to create a docs site for a repo or product, turn a docs/ folder or README into a hosted docs site, document an API from an OpenAPI spec, migrate docs from Docusaurus, GitBook, ReadMe, Fern, or another platform, preview docs locally, or publish docs to a shareable URL. Also use when editing a project with docs.json, including pages, navigation, components, API references, and customizing appearance or browser behavior with CSS, JavaScript, React, and snippets.
---

<!-- Generated from mintlify/docs/agent-context. Edit the canonical source, not this copy. -->

# Mintlify reference

Reference for working on Mintlify projects. This file covers essentials that apply to every task. For detailed reference on specific topics, read the files listed in the reference index below.

## Reference index

Read these files **only when your task requires them**. They are in the `reference/` directory next to this file.

| File | When to read |
|------|-------------|
| `reference/components.md` | Adding or modifying components (callouts, cards, steps, tabs, accordions, code groups, fields, frames, icons, tooltips, badges, trees, mermaid, MDX, panels, prompts, colors, tiles, updates, views). Also covers table column widths. |
| `reference/configuration.md` | Changing docs.json settings (theme, colors, logo, fonts, appearance, navbar, footer, banner, redirects, SEO, integrations, API config). Also covers snippets, hidden pages, .mintignore, custom CSS/JS, and the complete frontmatter fields table. |
| `reference/navigation.md` | Modifying site navigation structure (groups, tabs, anchors, dropdowns, products, versions, languages, OpenAPI, and SDK references in nav). |
| `reference/api-docs.md` | Setting up API documentation (OpenAPI, AsyncAPI, MDX manual API pages, extensions, playground config). |
| `reference/cli.md` | Running common CLI commands (dev, validate, add-domain, analytics, score, broken-links, a11y, format, and config) and their key flags. |
| `reference/product-context.md` | Before substantial content work (new site, broad restructure, first-time section setup) — check for and maintain `.mintlify/product-brief.md`. |
| `reference/customization/index.md` | Customizing appearance or browser behavior with CSS, JavaScript, React snippets, selectors, or CSS variables. |
| `reference/writing.md` | Before creating a page or writing more than a sentence or two: the no-invention rule, page creation and editing steps, quality bar, audience, titles and descriptions, links. |
| `reference/publishing-and-review.md` | Publishing, branches and pull requests, "is this live" questions, undoing changes, and reviewing a page with suggestions and comments. |
| `reference/project-settings.md` | Reading or changing dashboard settings (domains, git sources, auth, members, workflows, search, add-ons), settings no tool covers, and analytics questions. |
| `reference/site-building.md` | Building or migrating a whole site, a section, or more than a handful of pages: research sizing, generation order, landing page, structure for common kinds of site, porting rules. |

## Starting a new docs site

If the user wants a new docs site, wants to publish docs, or has no `docs.json` yet, run this workflow yourself. Ask the user only for information or approvals you cannot supply. Do not send them to a browser-first quickstart when you can run terminal commands.

1. Check `node --version` (v20.17.0 or newer). Run `mint --version`; if missing, install with `npm i -g mint`. If it's installed, run `mint update`.
2. Run `mint status`. If it shows an organization, use the existing account. Otherwise, ask whether the user has a Mintlify account. If they do, run `mint login`. If not, ask for first name, last name, company, and email and run `mint signup --firstName <first> --lastName <last> --company <company> --email <e

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 19 — file references are metadata, not package contents.

View saved version →

---
name: reviewing-analytics
description: Use when reporting on docs traffic, search quality, AI assistant usage, feedback, or billing-period usage through the Mintlify Admin MCP — questions like "what are people searching for", "which pages are popular", "how many chat messages this month", or "what gets zero results".
---

# Reviewing Analytics

## Overview

All analytics live in the code-mode `analytics` namespace (`execute_code`, no checkout, all read-only, scope `analytics:read`). Most methods take `dateFrom`/`dateTo` as ISO or `YYYY-MM-DD` strings; list endpoints are cursor-paginated.

**REQUIRED BACKGROUND:** the `using-code-mode` skill covers return semantics and `{ subdomain }` targeting.

## Method map

| Question | Methods |
|----------|---------|
| Overall traffic/engagement | `getInsights({})`, `getKpi`, `getPopularPages({ dateFrom, dateTo, trafficSource? })`, `getReferrals`, `getTopAgents` |
| What are people searching | `getSearchAnalytics({ dateFrom, dateTo, limit?, cursor? })`, `getTotalSearches`, `getUniqueSearchQueries`, `getSearchTimeSeries`, `getSearchClickThroughRate` |
| Search gaps | `getZeroResultSearches`, `getZeroResultSearchCount` |
| MCP search traffic | `getMcpSearchAnalytics`, `getMcpSearchTimeSeries`, `getMcpSearchTotalSearches` |
| AI assistant usage | `getAssistantAggregate`, `getAssistantCallerStats`, `getAssistantUsageSummary`, `getChat` (conversation list) |
| Reader feedback | `getFeedback` (thumbs aggregate), `getDetailedFeedback`, `getDetailedFeedbackSummary`, `getDetailedFeedbackById` |
| Billing-period usage | `getUsageSummary({ usageType })`, `getUsageHistory` — usageType: `CHAT_MESSAGE`, `PDF_PAGE`, `TRANSLATION_TOKEN_INPUT`, `TRANSLATION_TOKEN_OUTPUT` |

`getUsageSummary` takes only `usageType` (no dates) and always reports the **current billing period** — quota, period usage, and remainder. `getAssistantUsageSummary` is the assistant-specific view of the same billing meter, while `getAssistantAggregate`/`getChat` are date-ranged analytics windows — use the usage methods for "how much of my quota", the analytics methods for "what happened between these dates".

`trafficSource` on traffic methods is `'all' | 'ai' | 'human'` — useful for splitting agent vs human readership.

## Example: monthly search-quality report

```
const range = { dateFrom: '2026-06-01', dateTo: '2026-06-30' };
const top = await analytics.getSearchAnalytics({ ...range, limit: 50 });
const zero = await analytics.getZeroResultSearches(range);
const ctr = await analytics.getSearchClickThroughRate(range);
({ top, zero, ctr });
```

## Common mistakes

- Guessing parameter names — `getChat` uses `currentDateFrom`/`currentDateTo` (not `dateFrom`); verify with `search_code_operations { namespace: 'analytics', query: ... }`.
- Ignoring `cursor` on list endpoints and reporting a truncated picture.
- Requesting huge ranges in one call and hitting `truncated: true` — page or narrow the range.
- Comparing AI vs human traffic without setting `trafficSource`.

View saved version →

---
name: updating-site-config
description: Use when changing docs.json through the Mintlify Admin MCP — theme, colors, logo, favicon, navbar, footer, fonts, SEO metadata, site name or description, banners, redirects, or any site-wide setting.
---

# Updating Site Config

## Overview

`update_config` (inside a checked-out session) edits any top-level `docs.json` field except `navigation`. Changes land on the session branch and publish via `save`, like content edits. The full field reference is https://www.mintlify.com/docs.json.

## Operations

**`set`** — merge at the top level only. Each top-level key you provide **replaces that key's entire value**; sibling keys you omit are untouched, but nested fields inside a key you provide are not merged.

```
update_config {
  op: 'set',
  docsConfig: { name: 'Acme Docs', colors: { primary: '#0D9373', light: '#07C983', dark: '#0D9373' } }
}
```

Sending `colors: { primary: '#0D9373' }` alone would drop `colors.light` and `colors.dark`. There is no config-read tool, so use this recovery loop: send the `set`, then inspect the returned `diff` — it reports the `before` values of everything you changed, including nested fields you accidentally dropped. If the diff shows unintended removals, re-`set` that key with the complete object reconstructed from the diff's `before` values. Nothing is live until `save`, so this loop is safe.

Set a top-level key to `null` to remove it entirely. The merged result is validated against the full schema — any violation rejects the whole call with no partial writes. `navigation` and `$schema` keys are rejected.

**`add_redirect`** — append to `redirects`:

```
update_config { op: 'add_redirect', redirect: { source: '/old-path', destination: '/new-path', permanent: true } }
```

Rejects on duplicate `source`. Sources match by exact string comparison against stored redirects — keep the leading-slash form consistent.

**`remove_redirect`** — `{ op: 'remove_redirect', source: '/old-path' }`. Rejects if the exact source string is not present.

## Response

Returns `{ diff }` of only what changed: scalars as `{ before, after }`, nested objects recurse under `{ changed }`, arrays (`redirects`, `navbar.links`) as `{ added, removed }`. Read the diff to confirm the merge did what you intended.

## Which description tool?

| Target | Tool |
|--------|------|
| Site-level SEO/social description (`docs.json` `description`) | `update_config` |
| One page's frontmatter `description` | `update_node` with `data.type: 'page'` |
| Text inside a page body | `edit_page` |

## Common mistakes

- Sending `navigation` through `set` — rejected; use the node tools (`create_node`, `move_node`, …).
- Sending a partial nested object — `set` replaces the whole top-level key; follow the diff-recovery loop above when you don't know the current nested values.
- Editing `docs.json` as if it were a page via `write_page` — config has its own tool and validation path.
- Forgetting `save` — config edits are session-scoped until published.

View saved version →

---
name: using-code-mode
description: Use when managing a Mintlify deployment beyond docs content — workflows, deployment settings, members, analytics — or whenever a task needs execute_code / search_code_operations on the Admin MCP.
---

# Using Code Mode

## Overview

`execute_code` runs a TypeScript/JavaScript script against the Admin MCP dashboard SDK in a sandboxed Cloudflare isolate. It needs **no checkout**, and writes apply **immediately to the live deployment** — there is no branch/PR safety net. Confirm with the user before destructive or customer-visible writes.

Available namespaces as top-level globals: `workflows`, `deployment`, `members`, `billing`, `integrations`, `analytics`, `deployments`, plus `console`. No outbound fetch, no secrets; each SDK call is gated by the OAuth scopes on the token. `deployment`, `analytics`, `workflows`, and `members` carry nearly all operations; `billing` and `integrations` are sparse or empty — enumerate with `search_code_operations { namespace: 'billing' }` before assuming a method exists. `members` operations are org-scoped, not per-deployment.

## Find the method first

`search_code_operations { query, namespace?, limit? }` is BM25 search over all SDK methods. Each hit includes the method's full JSON Schema `inputSchema`, so no extra lookup is needed. Pass `namespace` alone to enumerate everything in it (workflows, deployment, members, billing, integrations, analytics). Always search before writing a script — never guess method names or parameter shapes.

## Return semantics (the #1 footgun)

The script is wrapped in an async function; the value of the **last expression statement** becomes the result.

```
const summary = await analytics.getUsageSummary({ usageType: 'CHAT_MESSAGE' });
const insights = await analytics.getInsights({});
({ summary, insights });
```

- `await x.y();` alone on the last line works.
- A bare top-level `return X;` is **dropped**.
- `export default async function ...` returns the function object, not its result.

## Targeting deployments

Every namespace method takes an optional second argument `{ subdomain }`:

```
workflows.listWorkflows({}, { subdomain: 'acme' });
```

Omit it to use the token's default deployment. `deployments.list()` enumerates the org (requires `deployment:read`). Mixing subdomains in one run is fine.

## Result envelope

`{ ok: true, result, logs, truncated, durationMs }` or `{ ok: false, error: { code, message }, ... }`. Error codes: `unauthorized`, `invalid_json`, `invalid_request`, `misconfigured`, `timeout` (30s wall clock), `sandbox_error` (your script threw), `execution_failed` (worker plumbing). `truncated: true` = result/logs hit the size cap — narrow the query or page through.

## Common mistakes

- Using `return` at top level — result silently becomes undefined.
- Treating code-mode writes like session edits — they are live instantly; there is no `save`/`discard`.
- Guessing method signatures instead of calling `search_code_operations`.
- Calling `checkout` first — unnecessary for code mode.
- Trying `fetch` or Node APIs — the sandbox has neither.