docs: document public agent score API endpoint

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.
@@ -25,6 +25,7 @@
 - [Get search queries](/api/analytics/searches): Export documentation search terms and analytics.
 - [Get page views](/api/analytics/views): Export per-page and site-wide content view counts.
 - [Get unique visitors](/api/analytics/visitors): Export per-page and site-wide unique visitor counts.
+- [Get agent score](/api/score/get-agent-score): Retrieve the [agent readiness score](https://mintlify.com/score) for any public documentation URL. No authentication required.
 
 ### Common use cases
 

api/score/get-agent-score.mdx

@@ -0,0 +1,50 @@
+---
+title: "Get agent score"
+description: "Check how agent-ready a public documentation site is with the unauthenticated Mintlify agent score endpoint."
+openapi: /score.openapi.json GET /agent/score
+keywords: ["agent score", "agent readiness", "AFDocs", "public API"]
+---
+
+Use this endpoint to retrieve the [agent score](https://mintlify.com/score) for any public documentation URL. The endpoint backs the free score tool and is open to anyone — no API key required.
+
+## When to use it
+
+- Build a scorecard or badge into your own site.
+- Monitor a docs site's agent readiness in CI or a scheduled job.
+- Compare scores across competitors or your own subdomains.
+
+For interactive checks from your terminal, use the [`mint score`](/cli/commands#mint-score) command instead.
+
+## How it works
+
+The first request for a URL queues a fresh score computation and returns `202 Accepted` along with a `Retry-After` header. Subsequent requests return `200 OK` with the latest computed score. Mintlify automatically refreshes stale scores in the background, so repeated polling against the same URL stays cheap.
+
+## Rate limits
+
+- 10 requests per minute per IP address.
+
+## Example
+
+```bash
+curl "https://api.mintlify.com/api/agent/score?url=https://mintlify.com/docs"
+```
+
+A queued response while the score is being computed:
+
+```json
+{
+  "canonicalUrl": "https://mintlify.com/docs",
+  "retryAfterSeconds": 10,
+  "status": "queued"
+}
+```
+
+A ready response once the score is available:
+
+```json
+{
+  "canonicalUrl": "https://mintlify.com/docs",
+  "score": 86,
+  "status": "ready"
+}
+```

docs.json

@@ -407,6 +407,13 @@
                   "api/analytics/views",
                   "api/analytics/visitors"
                 ]
+              },
+              {
+                "group": "Agent score",
+                "icon": "gauge",
+                "pages": [
+                  "api/score/get-agent-score"
+                ]
               }
             ]
           },

gt.config.json

@@ -7,7 +7,8 @@
         "./admin-openapi.json",
         "./discovery-openapi.json",
         "./openapi.json",
-        "./analytics.openapi.json"
+        "./analytics.openapi.json",
+        "./score.openapi.json"
       ],
       "transform": [
         {
@@ -25,6 +26,10 @@
         {
           "match": "^openapi.json$",
           "replace": "{locale}/openapi.json"
+        },
+        {
+          "match": "^score.openapi.json$",
+          "replace": "{locale}/score.openapi.json"
         }
       ]
     },
@@ -88,6 +93,9 @@
       },
       "./analytics.openapi.json": {
         "preset": "openapi"
+      },
+      "./score.openapi.json": {
+        "preset": "openapi"
       }
     },
     "docsUrlPattern": "/[locale]",
@@ -105,7 +113,8 @@
           "./admin-openapi.json",
           "./analytics.openapi.json",
           "./discovery-openapi.json",
-          "./openapi.json"
+          "./openapi.json",
+          "./score.openapi.json"
         ]
       }
     }

score.openapi.json

@@ -0,0 +1,164 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Mintlify Agent Score API",
+    "description": "Public, unauthenticated endpoint for checking how agent-ready a documentation site is. Powers the free score tool at https://mintlify.com/score.",
+    "version": "1.0.0"
+  },
+  "servers": [
+    {
+      "url": "https://api.mintlify.com/api",
+      "description": "Production"
+    }
+  ],
+  "security": [],
+  "paths": {
+    "/agent/score": {
+      "get": {
+        "summary": "Get agent score",
+        "description": "Returns the agent readiness score for a public documentation URL. The endpoint is unauthenticated and rate limited to 10 requests per minute per IP address. The first request for a new URL queues a score computation and returns `202 Accepted` with a `Retry-After` header. Poll the endpoint until the response is `200 OK` with the computed score.",
+        "security": [],
+        "parameters": [
+          {
+            "name": "url",
+            "in": "query",
+            "required": true,
+            "description": "The public HTTPS URL of the documentation site to score. The host must be publicly resolvable. Maximum length is 2048 characters.",
+            "schema": {
+              "type": "string",
+              "format": "uri",
+              "maxLength": 2048,
+              "example": "https://mintlify.com/docs"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "A score has been computed for the requested URL.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": ["canonicalUrl", "score", "status"],
+                  "properties": {
+                    "canonicalUrl": {
+                      "type": "string",
+                      "format": "uri",
+                      "description": "The canonical URL of the tracked site that Mintlify scored. This may differ from the requested URL if Mintlify resolved it to a different canonical form."
+                    },
+                    "score": {
+                      "type": "integer",
+                      "minimum": 0,
+                      "maximum": 100,
+                      "description": "Overall agent readiness score between 0 and 100."
+                    },
+                    "status": {
+                      "type": "string",
+                      "enum": ["ready"],
+                      "description": "Indicates that a score is available in the response."
+                    }
+                  }
+                },
+                "example": {
+                  "canonicalUrl": "https://mintlify.com/docs",
+                  "score": 86,
+                  "status": "ready"
+                }
+              }
+            }
+          },
+          "202": {
+            "description": "A score is being computed. Wait `retryAfterSeconds` seconds and request again. The same value is returned in the standard `Retry-After` HTTP header.",
+            "headers": {
+              "Retry-After": {
+                "description": "Number of seconds to wait before polling again.",
+                "schema": {
+                  "type": "integer",
+                  "example": 10
+                }
+              }
+            },
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": ["canonicalUrl", "retryAfterSeconds", "status"],
+                  "properties": {
+                    "canonicalUrl": {
+                      "type": "string",
+                      "format": "uri",
+                      "description": "The canonical URL of the tracked site Mintlify is scoring."
+                    },
+                    "retryAfterSeconds": {
+                      "type": "integer",
+                      "description": "Number of seconds to wait before polling again.",
+                      "example": 10
+                    },
+                    "status": {
+                      "type": "string",
+                      "enum": ["queued"],
+                      "description": "Indicates that a score computation is in progress."
+                    }
+                  }
+                },
+                "example": {
+                  "canonicalUrl": "https://mintlify.com/docs",
+                  "retryAfterSeconds": 10,
+                  "status": "queued"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The `url` query parameter is missing, malformed, or not a public HTTPS address.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string"
+                    }
+                  }
+                },
+                "examples": {
+                  "missingUrl": {
+                    "summary": "Missing or malformed URL",
+                    "value": {
+                      "error": "url query param is required"
+                    }
+                  },
+                  "unsafeUrl": {
+                    "summary": "Non-public or non-HTTPS URL",
+                    "value": {
+                      "error": "url must be a public HTTPS address"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "Rate limit exceeded. Each IP address may make up to 10 requests per minute."
+          },
+          "502": {
+            "description": "Mintlify could not resolve or analyze the provided URL.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "error": {
+                      "type": "string",
+                      "example": "Failed to analyze the provided URL"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}