docs: document public agent score API endpoint

agent-score.openapi.json

@@ -0,0 +1,185 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Mintlify Agent Score API",
+    "version": "1.0.0",
+    "description": "Public API for checking how well a documentation site is structured for AI agents."
+  },
+  "servers": [
+    {
+      "url": "https://api.mintlify.com",
+      "description": "Production"
+    }
+  ],
+  "security": [],
+  "paths": {
+    "/v1/score": {
+      "get": {
+        "summary": "Get agent score",
+        "description": "Returns the agent readiness score for a public documentation URL. The endpoint is unauthenticated. If the URL has not been analyzed before and no cached score exists, the response is `queued` and you should poll again after `retryAfterSeconds`. Cached scores, including stale scores queued for a background refresh, return the `ready` score with the full list of checks.",
+        "operationId": "getAgentScore",
+        "parameters": [
+          {
+            "name": "url",
+            "in": "query",
+            "required": true,
+            "description": "Public HTTPS URL of the documentation site to score. URLs without a scheme are upgraded to `https://`. Maximum length is 2048 characters.",
+            "schema": {
+              "type": "string",
+              "format": "uri",
+              "maxLength": 2048,
+              "example": "https://mintlify.com/docs"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The score is ready.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": ["canonicalUrl", "checks", "score", "status"],
+                  "properties": {
+                    "status": {
+                      "type": "string",
+                      "enum": ["ready"],
+                      "description": "Indicates that the score is available."
+                    },
+                    "canonicalUrl": {
+                      "type": "string",
+                      "format": "uri",
+                      "description": "The canonical URL Mintlify resolved from the requested URL."
+                    },
+                    "score": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "maximum": 100,
+                      "description": "Overall agent readiness score for the site, from 0 to 100."
+                    },
+                    "checks": {
+                      "type": "array",
+                      "description": "Individual check results from the AgentRank (AFDocs) framework and Mintlify-specific checks.",
+                      "items": {
+                        "$ref": "#/components/schemas/Check"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "202": {
+            "description": "The score is being computed. Retry after the number of seconds in `retryAfterSeconds` (also returned as the `Retry-After` response header).",
+            "headers": {
+              "Retry-After": {
+                "description": "Number of seconds to wait before retrying the request.",
+                "schema": {
+                  "type": "integer"
+                }
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": ["canonicalUrl", "retryAfterSeconds", "status"],
+                  "properties": {
+                    "status": {
+                      "type": "string",
+                      "enum": ["queued"]
+                    },
+                    "canonicalUrl": {
+                      "type": "string",
+                      "format": "uri"
+                    },
+                    "retryAfterSeconds": {
+                      "type": "integer",
+                      "description": "Suggested number of seconds to wait before polling again."
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The `url` query parameter is missing, malformed, or not a public HTTPS address.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "Rate limit exceeded. The endpoint allows up to 10 requests per minute per IP.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "502": {
+            "description": "Mintlify could not analyze the provided URL.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Check": {
+        "type": "object",
+        "required": ["id", "name", "status"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Stable identifier for the check."
+          },
+          "name": {
+            "type": "string",
+            "description": "Human-readable name of the check."
+          },
+          "status": {
+            "type": "string",
+            "enum": ["pass", "fail", "warn", "skip"],
+            "description": "Result of the check."
+          },
+          "message": {
+            "type": "string",
+            "description": "Optional explanation of the result."
+          },
+          "category": {
+            "type": "string",
+            "description": "Optional category the check belongs to."
+          },
+          "children": {
+            "type": "array",
+            "description": "Nested checks for grouped extensions.",
+            "items": {
+              "$ref": "#/components/schemas/Check"
+            }
+          }
+        }
+      },
+      "Error": {
+        "type": "object",
+        "properties": {
+          "error": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

api/agent/score.mdx

@@ -0,0 +1,68 @@
+---
+title: "Get agent score"
+description: "Check how well any public documentation site is structured for AI agents with a single unauthenticated request."
+openapi: /agent-score.openapi.json GET /v1/score
+keywords: ["agent score", "agent readiness", "AgentRank", "AFDocs", "public API"]
+---
+
+Use this endpoint to fetch the agent readiness score for any public documentation URL. It powers the `mint score` CLI command and the public AgentRank leaderboard, and you can call it directly from your own tools, CI checks, or dashboards.
+
+The endpoint is unauthenticated — no API key is required.
+
+Call it at `GET https://api.mintlify.com/v1/score` with the public documentation URL in the `url` query parameter.
+
+## When to use it
+
+- Show an agent readiness badge or score on a status page.
+- Add a quality gate to CI that fails when a docs site falls below a target score.
+- Build a custom report or comparison across multiple documentation sites.
+
+If you only need to check your own site interactively, run [`mint score`](/cli/commands#mint-score) instead.
+
+## How it works
+
+The first request for a URL Mintlify has not analyzed before returns `202 Accepted` with `status: "queued"` and a `Retry-After` header. Mintlify analyzes the site in the background, then subsequent requests return `200 OK` with `status: "ready"` and the full list of checks.
+
+Cached scores are returned immediately. If a cached score is older than one hour, Mintlify queues a background refresh but still returns the cached result so your application is not blocked.
+
+## Rate limits
+
+- 10 requests per minute, per IP address.
+
+Requests beyond the limit receive `429 Too Many Requests`.
+
+## Example
+
+Poll until the score is ready:
+
+```bash
+curl "https://api.mintlify.com/v1/score?url=https://mintlify.com/docs"
+```
+
+A queued response looks like:
+
+```json
+{
+  "status": "queued",
+  "canonicalUrl": "https://mintlify.com/docs",
+  "retryAfterSeconds": 10
+}
+```
+
+A ready response looks like:
+
+```json
+{
+  "status": "ready",
+  "canonicalUrl": "https://mintlify.com/docs",
+  "score": 92,
+  "checks": [
+    {
+      "id": "llms-txt",
+      "name": "llms-txt",
+      "status": "pass",
+      "category": "discovery"
+    }
+  ]
+}
+```

api/introduction.mdx

@@ -7,7 +7,7 @@
 
 The Mintlify REST (Representational State Transfer) API enables you to programmatically interact with your documentation, trigger updates, embed AI-powered chat experiences, and export analytics data.
 
 ## Endpoints
 
 - [Trigger update](/api/update/trigger): Trigger an update of your site when desired.
 - [Get update status](/api/update/status): Get the status of an update and other details about your docs.
@@ -15,6 +15,7 @@
 - [Create agent job](/api/agent/v2/create-agent-job): Create an agent job to automatically edit your documentation.
 - [Get agent job](/api/agent/v2/get-agent-job): Retrieve the details and status of a specific agent job.
 - [Send follow-up message](/api/agent/v2/send-message): Send a follow-up message to an existing agent job.
+- [Get agent score](/api/agent/score): Check the agent readiness score for any public documentation URL. No authentication required.
 - [Create assistant message](/api/assistant/create-assistant-message-v2): Embed the assistant, trained on your docs, into any application of your choosing.
 - [Search documentation](/api/assistant/search): Search through your documentation.
 - [Get page content](/api/assistant/get-page-content): Retrieve the full text content of a documentation page.

docs.json

@@ -383,7 +383,8 @@
                 "pages": [
                   "api/agent/v2/create-agent-job",
                   "api/agent/v2/get-agent-job",
-                  "api/agent/v2/send-message"
+                  "api/agent/v2/send-message",
+                  "api/agent/score"
                 ]
               },
               {

es.json

@@ -350,7 +350,8 @@
           "pages": [
             "es/api/agent/v2/create-agent-job",
             "es/api/agent/v2/get-agent-job",
-            "es/api/agent/v2/send-message"
+            "es/api/agent/v2/send-message",
+            "es/api/agent/score"
           ]
         },
         {