Update from code changes: document mint deslop command

admin-openapi.json

@@ -358,6 +358,202 @@
         }
       }
     },
+    "/v1/deslop/{projectId}": {
+      "post": {
+        "summary": "Check page for AI-sounding prose",
+        "description": "Scan an MDX page for AI-sounding prose and return line-mapped flagged passages with optional human-style rewrite suggestions. Pages under 50 words are skipped for free. Each checked page charges 1 AI credit from the shared AI credits pool used by the assistant.\n\nAuthenticate with an admin API key.",
+        "parameters": [
+          {
+            "name": "projectId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Your project ID. Can be copied from the [API keys](https://app.mintlify.com/settings/organization/api-keys) page in your dashboard."
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["path", "content"],
+                "properties": {
+                  "path": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Identifier for the page being checked. Echoed back in the response and used to key results when checking multiple pages."
+                  },
+                  "content": {
+                    "type": "string",
+                    "maxLength": 1000000,
+                    "description": "Raw MDX or Markdown content of the page. Frontmatter, code blocks, and inline code are stripped before scoring so only prose is analyzed."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Page checked successfully. `skipped` is `null` for scored pages, or a reason string (for example, `too_short`) when the page was not scored. Scored pages include the AI-written fractions, per-window flagged passages with line ranges, and any rewrite suggestions.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "oneOf": [
+                    {
+                      "type": "object",
+                      "properties": {
+                        "path": {
+                          "type": "string",
+                          "description": "Echo of the `path` from the request."
+                        },
+                        "skipped": {
+                          "type": "string",
+                          "nullable": true,
+                          "description": "Reason the page was skipped without scoring, such as `too_short` when the page is under 50 words. `null` when the page was scored."
+                        },
+                        "predictionShort": {
+                          "type": "string",
+                          "description": "Short label for the overall verdict. One of `Human`, `AI-Assisted`, `Mixed`, or `AI`.",
+                          "enum": ["Human", "AI-Assisted", "Mixed", "AI"]
+                        },
+                        "fractionAi": {
+                          "type": "number",
+                          "description": "Fraction of prose (0-1) that reads as fully AI-written."
+                        },
+                        "fractionAiAssisted": {
+                          "type": "number",
+                          "description": "Fraction of prose (0-1) that reads as AI-assisted."
+                        },
+                        "fractionHuman": {
+                          "type": "number",
+                          "description": "Fraction of prose (0-1) that reads as human-written."
+                        },
+                        "windows": {
+                          "type": "array",
+                          "description": "Flagged passages with line ranges from the original page and optional rewrite suggestions.",
+                          "items": {
+                            "type": "object",
+                            "properties": {
+                              "text": {
+                                "type": "string",
+                                "description": "The flagged passage as it appears in the page."
+                              },
+                              "label": {
+                                "type": "string",
+                                "description": "Passage-level verdict (for example, `AI` or `AI-Assisted`)."
+                              },
+                              "aiAssistanceScore": {
+                                "type": "number",
+                                "description": "Score (0-1) indicating how AI-written the passage is."
+                              },
+                              "confidence": {
+                                "oneOf": [
+                                  { "type": "string" },
+                                  { "type": "number" }
+                                ],
+                                "description": "Detector confidence for this passage."
+                              },
+                              "startLine": {
+                                "type": "integer",
+                                "description": "1-indexed start line of the passage in the original page."
+                              },
+                              "endLine": {
+                                "type": "integer",
+                                "description": "1-indexed end line of the passage in the original page."
+                              },
+                              "rewrites": {
+                                "type": "array",
+                                "description": "Optional human-style rewrite candidates.",
+                                "items": {
+                                  "type": "object",
+                                  "properties": {
+                                    "text": {
+                                      "type": "string",
+                                      "description": "Suggested replacement prose."
+                                    },
+                                    "rationale": {
+                                      "type": "string",
+                                      "description": "Short explanation of why the rewrite reads as more human."
+                                    }
+                                  }
+                                }
+                              }
+                            }
+                          }
+                        },
+                        "creditsCharged": {
+                          "type": "integer",
+                          "description": "AI credits charged for this request. `1` for scored pages, `0` for skipped pages."
+                        }
+                      }
+                    },
+                    {
+                      "type": "object",
+                      "description": "Response shape when the page was skipped without scoring.",
+                      "properties": {
+                        "path": { "type": "string" },
+                        "skipped": {
+                          "type": "string",
+                          "description": "Reason the page was skipped (for example, `too_short`)."
+                        },
+                        "creditsCharged": {
+                          "type": "integer",
+                          "description": "Always `0` for skipped pages."
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid request body. The `path` and `content` fields are required.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "402": {
+            "description": "Your organization is out of AI credits. Top up credits or upgrade your plan and retry.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "Rate limit exceeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "The AI-prose detection service or quota service is temporarily unavailable. No credits are charged. Retry with backoff.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/v2/agent/{projectId}/job": {
       "post": {
         "summary": "Create agent job",

api/deslop/check.mdx

@@ -0,0 +1,26 @@
+---
+title: "Check page for AI-sounding prose"
+openapi: /admin-openapi.json POST /v1/deslop/{projectId}
+keywords: ["deslop", "ai detection", "humanization", "prose quality"]
+
+---
+
+This endpoint scans an MDX or Markdown page for AI-sounding prose and returns line-mapped flagged passages with optional human-style rewrite suggestions. Use it to catch AI-drafted content before it reaches production, or to run the same checks the [`mint deslop`](/cli/commands#mint-deslop) CLI runs from a CI pipeline or internal tool.
+
+Frontmatter, fenced code blocks, and inline code are stripped before scoring, so only prose is analyzed.
+
+## Credits
+
+Each scored page charges 1 AI credit from the shared AI credits pool used by the assistant. Pages under 50 words are settled as a free skip (`skipped: "too_short"`) before the credit check runs.
+
+## Usage
+
+```bash
+curl -X POST https://api.mintlify.com/v1/deslop/{projectId} \
+  -H "Authorization: Bearer mint_xxxxx" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "path": "docs/guide.mdx",
+    "content": "# Getting started\n\nWelcome to our platform..."
+  }'
+```

cli/commands.mdx

@@ -324,6 +324,66 @@
 
 ---
 
+## `mint deslop`
+
+Detect AI-sounding prose in documentation pages and get humanization suggestions. Requires authentication with `mint login`.
+
+```bash
+mint deslop [files..] [flags]
+```
+
+With no arguments, the command checks git-changed `.md` and `.mdx` pages (staged, unstaged, and untracked). In a docs repo with a `docs.json`, changed files are automatically filtered to the pages referenced in your navigation, so `.mintignore`d and unpublished pages are skipped. You can also pass explicit file paths or globs.
+
+Each page is scored on the fraction of prose that reads as AI-written. Pages that meet or exceed `--threshold` fail, and the command exits with status `1` if any page is flagged or errors. Fully-human pages never fail, even at `--threshold 0`.
+
+| Argument | Description |
+| --- | --- |
+| `files` | Optional. One or more file paths or globs to check. Defaults to git-changed pages. |
+
+| Flag | Description |
+| --- | --- |
+| `--subdomain` | Documentation subdomain. Defaults to the value set with `mint config set subdomain`. |
+| `--format` | Output format: `table` (default, colored), `plain` (pipeable), or `json` (agent-friendly). |
+| `--threshold` | Fail a page when its AI-written fraction meets this value. Number between `0` and `1`. Defaults to `0.5`. |
+| `--fix-whitespace` | Normalize prose whitespace in the checked files before scoring. Rewrites files locally with no server call. |
+
+For each flagged page, the output shows the AI-written percentage, the flagged line ranges, the offending prose, and suggested rewrites you can apply.
+
+<Note>
+  Checking pages consumes AI credits. `--fix-whitespace` runs locally and does not charge credits. If the batch hits a credits or availability error, the remaining pages are skipped instead of retried.
+</Note>
+
+### Examples
+
+```bash
+# Check git-changed pages
+mint deslop
+
+# Check a specific page
+mint deslop docs/guide.mdx
+
+# Check pages by glob with agent-friendly output
+mint deslop "docs/**/*.mdx" --format json
+
+# Fail only on the most confidently AI-written pages
+mint deslop --threshold 0.8
+
+# Normalize prose whitespace and re-check in one pass
+mint deslop --fix-whitespace
+```
+
+### Fixing whitespace
+
+`--fix-whitespace` deterministically cleans prose whitespace in each checked file: trailing spaces, runs of blank lines, unicode and zero-width spaces, and internal double-spaces. Fenced code blocks, inline code, and frontmatter are left untouched. Because it runs locally, it is safe to include in pre-commit hooks or CI.
+
+### JSON output
+
+`--format json` writes a single JSON object to stdout with a `results` array (one entry per file, keyed by `path`) and a `summary` block. Errors are reported per file and counted in `summary.errors`. This shape is designed for agents that loop: check, rewrite flagged passages, then re-run until the command exits `0`.
+
+The CLI calls the same detection service exposed by the Admin API. Use the [check page for AI-sounding prose](/api/deslop/check) endpoint if you need to run these checks from a CI pipeline or internal tool without shelling out to the CLI.
+
+---
+
 ## `mint new`
 
 Create a new documentation project by picking a theme or cloning a pre-defined template from the [mintlify/templates](https://github.com/mintlify/templates) repository.

docs.json

@@ -410,6 +410,13 @@
                   "api/assistant/get-page-content"
                 ]
               },
+              {
+                "group": "Deslop",
+                "icon": "sparkles",
+                "pages": [
+                  "api/deslop/check"
+                ]
+              },
               {
                 "group": "Analytics",
                 "icon": "chart-line",

es.json

@@ -389,6 +389,13 @@
             "es/api/assistant/get-page-content"
           ]
         },
+        {
+          "group": "Deslop",
+          "icon": "sparkles",
+          "pages": [
+            "es/api/deslop/check"
+          ]
+        },
         {
           "group": "Analytics",
           "icon": "chart-line",