diff --git a/agent-score.openapi.json b/agent-score.openapi.json new file mode 100644 index 0000000000..0d835c1544 --- /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": { + "/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" + } + } + } + } + } +} diff --git a/api/agent/score.mdx b/api/agent/score.mdx new file mode 100644 index 0000000000..0860b5a851 --- /dev/null +++ b/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" + } + ] +} +``` 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..0d835c1544 --- /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": { + "/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" + } + } + } + } + } +} diff --git a/es/api/agent/score.mdx b/es/api/agent/score.mdx new file mode 100644 index 0000000000..55b157ff9a --- /dev/null +++ b/es/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: /es/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`](/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/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" + } + ] +} +``` 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..0d835c1544 --- /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": { + "/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" + } + } + } + } + } +} diff --git a/fr/api/agent/score.mdx b/fr/api/agent/score.mdx new file mode 100644 index 0000000000..70f9d865ec --- /dev/null +++ b/fr/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: /fr/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`](/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/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" + } + ] +} +``` 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..0d835c1544 --- /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": { + "/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" + } + } + } + } + } +} diff --git a/zh/api/agent/score.mdx b/zh/api/agent/score.mdx new file mode 100644 index 0000000000..fdbfa97aaf --- /dev/null +++ b/zh/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: /zh/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`](/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/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" + } + ] +} +```