From c7b2e1c61e98eb618dadf417ac682b09825b27e3 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 13 May 2026 00:17:34 +0000 Subject: [PATCH 1/2] docs: add public agent score API endpoint reference --- agent-score.openapi.json | 185 ++++++++++++++++++++++++++++++++++++ api/agent/score.mdx | 66 +++++++++++++ api/introduction.mdx | 1 + docs.json | 3 +- es.json | 3 +- es/agent-score.openapi.json | 185 ++++++++++++++++++++++++++++++++++++ es/api/agent/score.mdx | 66 +++++++++++++ fr.json | 3 +- fr/agent-score.openapi.json | 185 ++++++++++++++++++++++++++++++++++++ fr/api/agent/score.mdx | 66 +++++++++++++ gt.config.json | 13 ++- zh.json | 3 +- zh/agent-score.openapi.json | 185 ++++++++++++++++++++++++++++++++++++ zh/api/agent/score.mdx | 66 +++++++++++++ 14 files changed, 1024 insertions(+), 6 deletions(-) create mode 100644 agent-score.openapi.json create mode 100644 api/agent/score.mdx create mode 100644 es/agent-score.openapi.json create mode 100644 es/api/agent/score.mdx create mode 100644 fr/agent-score.openapi.json create mode 100644 fr/api/agent/score.mdx create mode 100644 zh/agent-score.openapi.json create mode 100644 zh/api/agent/score.mdx diff --git a/agent-score.openapi.json b/agent-score.openapi.json new file mode 100644 index 0000000000..1b9c82d541 --- /dev/null +++ b/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": { + "/agent/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 (or its cached score is being refreshed), the response is `queued` and you should poll again after `retryAfterSeconds`. Once the analysis finishes, subsequent calls 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" + } + } + } + } + } +} diff --git a/api/agent/score.mdx b/api/agent/score.mdx new file mode 100644 index 0000000000..63675627e2 --- /dev/null +++ b/api/agent/score.mdx @@ -0,0 +1,66 @@ +--- +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 /agent/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. + +## 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/agent/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" + } + ] +} +``` diff --git a/api/introduction.mdx b/api/introduction.mdx index 2b5c584084..01db1ba92c 100644 --- a/api/introduction.mdx +++ b/api/introduction.mdx @@ -15,6 +15,7 @@ The Mintlify REST (Representational State Transfer) API enables you to programma - [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. diff --git a/docs.json b/docs.json index 774209b127..895325e894 100644 --- a/docs.json +++ b/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" ] }, { diff --git a/es.json b/es.json index 00a899d887..1cc78507be 100644 --- a/es.json +++ b/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" ] }, { diff --git a/es/agent-score.openapi.json b/es/agent-score.openapi.json new file mode 100644 index 0000000000..1b9c82d541 --- /dev/null +++ b/es/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": { + "/agent/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 (or its cached score is being refreshed), the response is `queued` and you should poll again after `retryAfterSeconds`. Once the analysis finishes, subsequent calls 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" + } + } + } + } + } +} diff --git a/es/api/agent/score.mdx b/es/api/agent/score.mdx new file mode 100644 index 0000000000..87080d7537 --- /dev/null +++ b/es/api/agent/score.mdx @@ -0,0 +1,66 @@ +--- +title: "Get agent score" +description: "Check how well any public documentation site is structured for AI agents with a single unauthenticated request." +openapi: /es/agent-score.openapi.json GET /agent/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. + +## 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`](/es/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/agent/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" + } + ] +} +``` diff --git a/fr.json b/fr.json index 7d1a174b98..4e855390c8 100644 --- a/fr.json +++ b/fr.json @@ -350,7 +350,8 @@ "pages": [ "fr/api/agent/v2/create-agent-job", "fr/api/agent/v2/get-agent-job", - "fr/api/agent/v2/send-message" + "fr/api/agent/v2/send-message", + "fr/api/agent/score" ] }, { diff --git a/fr/agent-score.openapi.json b/fr/agent-score.openapi.json new file mode 100644 index 0000000000..1b9c82d541 --- /dev/null +++ b/fr/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": { + "/agent/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 (or its cached score is being refreshed), the response is `queued` and you should poll again after `retryAfterSeconds`. Once the analysis finishes, subsequent calls 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" + } + } + } + } + } +} diff --git a/fr/api/agent/score.mdx b/fr/api/agent/score.mdx new file mode 100644 index 0000000000..77d445f4a2 --- /dev/null +++ b/fr/api/agent/score.mdx @@ -0,0 +1,66 @@ +--- +title: "Get agent score" +description: "Check how well any public documentation site is structured for AI agents with a single unauthenticated request." +openapi: /fr/agent-score.openapi.json GET /agent/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. + +## 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`](/fr/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/agent/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" + } + ] +} +``` diff --git a/gt.config.json b/gt.config.json index 8bda848b07..41bfa2ee2c 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", + "./agent-score.openapi.json" ], "transform": [ { @@ -25,6 +26,10 @@ { "match": "^openapi.json$", "replace": "{locale}/openapi.json" + }, + { + "match": "^agent-score.openapi.json$", + "replace": "{locale}/agent-score.openapi.json" } ] }, @@ -88,6 +93,9 @@ }, "./analytics.openapi.json": { "preset": "openapi" + }, + "./agent-score.openapi.json": { + "preset": "openapi" } }, "docsUrlPattern": "/[locale]", @@ -105,7 +113,8 @@ "./admin-openapi.json", "./analytics.openapi.json", "./discovery-openapi.json", - "./openapi.json" + "./openapi.json", + "./agent-score.openapi.json" ] } } diff --git a/zh.json b/zh.json index 0c3a366f90..edbe17cd2e 100644 --- a/zh.json +++ b/zh.json @@ -350,7 +350,8 @@ "pages": [ "zh/api/agent/v2/create-agent-job", "zh/api/agent/v2/get-agent-job", - "zh/api/agent/v2/send-message" + "zh/api/agent/v2/send-message", + "zh/api/agent/score" ] }, { diff --git a/zh/agent-score.openapi.json b/zh/agent-score.openapi.json new file mode 100644 index 0000000000..1b9c82d541 --- /dev/null +++ b/zh/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": { + "/agent/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 (or its cached score is being refreshed), the response is `queued` and you should poll again after `retryAfterSeconds`. Once the analysis finishes, subsequent calls 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" + } + } + } + } + } +} diff --git a/zh/api/agent/score.mdx b/zh/api/agent/score.mdx new file mode 100644 index 0000000000..e16392d59f --- /dev/null +++ b/zh/api/agent/score.mdx @@ -0,0 +1,66 @@ +--- +title: "Get agent score" +description: "Check how well any public documentation site is structured for AI agents with a single unauthenticated request." +openapi: /zh/agent-score.openapi.json GET /agent/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. + +## 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`](/zh/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/agent/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" + } + ] +} +``` From 6621c9ce7db5271c5865df5285e08ade5f4b2354 Mon Sep 17 00:00:00 2001 From: rtbarnes Date: Fri, 15 May 2026 13:27:13 -0700 Subject: [PATCH 2/2] docs: correct public agent score endpoint path --- agent-score.openapi.json | 4 ++-- api/agent/score.mdx | 6 ++++-- es/agent-score.openapi.json | 4 ++-- es/api/agent/score.mdx | 6 ++++-- fr/agent-score.openapi.json | 4 ++-- fr/api/agent/score.mdx | 6 ++++-- zh/agent-score.openapi.json | 4 ++-- zh/api/agent/score.mdx | 6 ++++-- 8 files changed, 24 insertions(+), 16 deletions(-) diff --git a/agent-score.openapi.json b/agent-score.openapi.json index 1b9c82d541..0d835c1544 100644 --- a/agent-score.openapi.json +++ b/agent-score.openapi.json @@ -13,10 +13,10 @@ ], "security": [], "paths": { - "/agent/score": { + "/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 (or its cached score is being refreshed), the response is `queued` and you should poll again after `retryAfterSeconds`. Once the analysis finishes, subsequent calls return the `ready` score with the full list of checks.", + "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": [ { diff --git a/api/agent/score.mdx b/api/agent/score.mdx index 63675627e2..0860b5a851 100644 --- a/api/agent/score.mdx +++ b/api/agent/score.mdx @@ -1,7 +1,7 @@ --- 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 /agent/score +openapi: /agent-score.openapi.json GET /v1/score keywords: ["agent score", "agent readiness", "AgentRank", "AFDocs", "public API"] --- @@ -9,6 +9,8 @@ Use this endpoint to fetch the agent readiness score for any public documentatio 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. @@ -34,7 +36,7 @@ Requests beyond the limit receive `429 Too Many Requests`. Poll until the score is ready: ```bash -curl "https://api.mintlify.com/agent/score?url=https://mintlify.com/docs" +curl "https://api.mintlify.com/v1/score?url=https://mintlify.com/docs" ``` A queued response looks like: diff --git a/es/agent-score.openapi.json b/es/agent-score.openapi.json index 1b9c82d541..0d835c1544 100644 --- a/es/agent-score.openapi.json +++ b/es/agent-score.openapi.json @@ -13,10 +13,10 @@ ], "security": [], "paths": { - "/agent/score": { + "/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 (or its cached score is being refreshed), the response is `queued` and you should poll again after `retryAfterSeconds`. Once the analysis finishes, subsequent calls return the `ready` score with the full list of checks.", + "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": [ { diff --git a/es/api/agent/score.mdx b/es/api/agent/score.mdx index 87080d7537..55b157ff9a 100644 --- a/es/api/agent/score.mdx +++ b/es/api/agent/score.mdx @@ -1,7 +1,7 @@ --- title: "Get agent score" description: "Check how well any public documentation site is structured for AI agents with a single unauthenticated request." -openapi: /es/agent-score.openapi.json GET /agent/score +openapi: /es/agent-score.openapi.json GET /v1/score keywords: ["agent score", "agent readiness", "AgentRank", "AFDocs", "public API"] --- @@ -9,6 +9,8 @@ Use this endpoint to fetch the agent readiness score for any public documentatio 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. @@ -34,7 +36,7 @@ Requests beyond the limit receive `429 Too Many Requests`. Poll until the score is ready: ```bash -curl "https://api.mintlify.com/agent/score?url=https://mintlify.com/docs" +curl "https://api.mintlify.com/v1/score?url=https://mintlify.com/docs" ``` A queued response looks like: diff --git a/fr/agent-score.openapi.json b/fr/agent-score.openapi.json index 1b9c82d541..0d835c1544 100644 --- a/fr/agent-score.openapi.json +++ b/fr/agent-score.openapi.json @@ -13,10 +13,10 @@ ], "security": [], "paths": { - "/agent/score": { + "/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 (or its cached score is being refreshed), the response is `queued` and you should poll again after `retryAfterSeconds`. Once the analysis finishes, subsequent calls return the `ready` score with the full list of checks.", + "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": [ { diff --git a/fr/api/agent/score.mdx b/fr/api/agent/score.mdx index 77d445f4a2..70f9d865ec 100644 --- a/fr/api/agent/score.mdx +++ b/fr/api/agent/score.mdx @@ -1,7 +1,7 @@ --- title: "Get agent score" description: "Check how well any public documentation site is structured for AI agents with a single unauthenticated request." -openapi: /fr/agent-score.openapi.json GET /agent/score +openapi: /fr/agent-score.openapi.json GET /v1/score keywords: ["agent score", "agent readiness", "AgentRank", "AFDocs", "public API"] --- @@ -9,6 +9,8 @@ Use this endpoint to fetch the agent readiness score for any public documentatio 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. @@ -34,7 +36,7 @@ Requests beyond the limit receive `429 Too Many Requests`. Poll until the score is ready: ```bash -curl "https://api.mintlify.com/agent/score?url=https://mintlify.com/docs" +curl "https://api.mintlify.com/v1/score?url=https://mintlify.com/docs" ``` A queued response looks like: diff --git a/zh/agent-score.openapi.json b/zh/agent-score.openapi.json index 1b9c82d541..0d835c1544 100644 --- a/zh/agent-score.openapi.json +++ b/zh/agent-score.openapi.json @@ -13,10 +13,10 @@ ], "security": [], "paths": { - "/agent/score": { + "/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 (or its cached score is being refreshed), the response is `queued` and you should poll again after `retryAfterSeconds`. Once the analysis finishes, subsequent calls return the `ready` score with the full list of checks.", + "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": [ { diff --git a/zh/api/agent/score.mdx b/zh/api/agent/score.mdx index e16392d59f..fdbfa97aaf 100644 --- a/zh/api/agent/score.mdx +++ b/zh/api/agent/score.mdx @@ -1,7 +1,7 @@ --- title: "Get agent score" description: "Check how well any public documentation site is structured for AI agents with a single unauthenticated request." -openapi: /zh/agent-score.openapi.json GET /agent/score +openapi: /zh/agent-score.openapi.json GET /v1/score keywords: ["agent score", "agent readiness", "AgentRank", "AFDocs", "public API"] --- @@ -9,6 +9,8 @@ Use this endpoint to fetch the agent readiness score for any public documentatio 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. @@ -34,7 +36,7 @@ Requests beyond the limit receive `429 Too Many Requests`. Poll until the score is ready: ```bash -curl "https://api.mintlify.com/agent/score?url=https://mintlify.com/docs" +curl "https://api.mintlify.com/v1/score?url=https://mintlify.com/docs" ``` A queued response looks like: