From 8b058cebf500e0d80286d64a7396412cc0528674 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 12 May 2026 22:49:18 +0000 Subject: [PATCH] docs: document public agent score API endpoint --- api/introduction.mdx | 1 + api/score/get-agent-score.mdx | 50 +++++++++++ docs.json | 7 ++ gt.config.json | 13 ++- score.openapi.json | 164 ++++++++++++++++++++++++++++++++++ 5 files changed, 233 insertions(+), 2 deletions(-) create mode 100644 api/score/get-agent-score.mdx create mode 100644 score.openapi.json diff --git a/api/introduction.mdx b/api/introduction.mdx index 2b5c584084..3ca7d3f02f 100644 --- a/api/introduction.mdx +++ b/api/introduction.mdx @@ -25,6 +25,7 @@ The Mintlify REST (Representational State Transfer) API enables you to programma - [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 diff --git a/api/score/get-agent-score.mdx b/api/score/get-agent-score.mdx new file mode 100644 index 0000000000..33efb17c4f --- /dev/null +++ b/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" +} +``` diff --git a/docs.json b/docs.json index 774209b127..67e8435f78 100644 --- a/docs.json +++ b/docs.json @@ -407,6 +407,13 @@ "api/analytics/views", "api/analytics/visitors" ] + }, + { + "group": "Agent score", + "icon": "gauge", + "pages": [ + "api/score/get-agent-score" + ] } ] }, diff --git a/gt.config.json b/gt.config.json index 8bda848b07..8703677a00 100644 --- a/gt.config.json +++ b/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" ] } } diff --git a/score.openapi.json b/score.openapi.json new file mode 100644 index 0000000000..e38de0a72d --- /dev/null +++ b/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" + } + } + } + } + } + } + } + } + } + } +}