{"openapi": "3.1.0", "info": {"title": "AgentReady scan API (agentready.market)", "version": "1.0.0", "summary": "Agent-readiness audit for e-commerce stores", "description": "Score /100 of whether an AI shopping agent can find, understand and buy on a store. Reads are free and keyless; an MCP server exposes the same data at /mcp. Canonical identity: agentready.market \u2014 unaffiliated with other products named AgentReady. VERSIONING POLICY: /api/v1/* is the canonical, stable surface (unversioned /api/* aliases remain available); breaking changes only ever ship under a new /vN prefix, announced in llms.txt and the changelog \u2014 never in place. DEPRECATION POLICY: a deprecated endpoint keeps working for at least 6 months and answers with Deprecation and Sunset headers (RFC 8594) carrying the removal date before it goes away; nothing is deprecated today. Errors are structured JSON ({error, code, message, next_action?}); responses carry IETF RateLimit headers, and unknown /api paths return the same JSON error model (code NOT_FOUND).", "contact": {"email": "hello@agentready.market", "url": "https://www.agentready.market/api"}}, "servers": [{"url": "https://www.agentready.market"}], "paths": {"/api/v1": {"get": {"operationId": "apiIndex", "summary": "API discovery document (endpoints, docs, versioning policy)", "responses": {"200": {"description": "Discovery document", "content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string"}, "version": {"type": "string"}, "status": {"type": "string"}, "openapi": {"type": "string", "format": "uri"}, "endpoints": {"type": "array", "items": {"type": "object"}}, "versioning": {"type": "object"}}}}}}}}}, "/api/v1/scan": {"get": {"operationId": "scanStore", "summary": "Run a fresh agent-readiness scan (~30s, merchant's own store)", "description": "Synchronous: the scan completes within the request. The response includes the persisted scan_id, a shareable report_url and your Agent-Ready Index neighbor window.", "parameters": [{"name": "url", "in": "query", "required": true, "schema": {"type": "string", "format": "uri"}}, {"name": "vertical", "in": "query", "required": false, "schema": {"type": "string"}}], "responses": {"200": {"description": "Scan result", "content": {"application/json": {"schema": {"type": "object", "properties": {"score": {"type": "integer", "minimum": 0, "maximum": 100}, "grade": {"type": "string", "enum": ["A", "B", "C", "D", "E"]}, "capped": {"type": "boolean", "description": "True when an access hard-block caps the score"}, "pillars": {"type": "array", "items": {"$ref": "#/components/schemas/Pillar"}}, "top_fixes": {"type": "array", "items": {"$ref": "#/components/schemas/Fix"}}, "scan_id": {"type": "integer"}, "report_url": {"type": "string", "format": "uri"}, "neighbors": {"type": "array", "description": "Your window on the Agent-Ready Index: up to 2 stores above you, yourself (is_self), and 2 below \u2014 the score to beat.", "items": {"type": "object", "properties": {"rank": {"type": "integer"}, "host": {"type": "string"}, "score": {"type": "integer"}, "grade": {"type": "string"}, "is_self": {"type": "boolean"}}}}}}}}}, "400": {"description": "Invalid input (code MISSING_URL)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (code RATE_LIMITED; Retry-After set; RateLimit-* headers on every response)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "504": {"description": "Store too slow (code SCAN_TIMEOUT)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/scan/{scan_id}.json": {"get": {"operationId": "getScanResult", "summary": "Read a stored scan report", "parameters": [{"name": "scan_id", "in": "path", "required": true, "schema": {"type": "integer"}}], "responses": {"200": {"description": "Stored scan result", "content": {"application/json": {"schema": {"type": "object", "properties": {"score": {"type": "integer", "minimum": 0, "maximum": 100}, "grade": {"type": "string", "enum": ["A", "B", "C", "D", "E"]}, "capped": {"type": "boolean", "description": "True when an access hard-block caps the score"}, "pillars": {"type": "array", "items": {"$ref": "#/components/schemas/Pillar"}}, "top_fixes": {"type": "array", "items": {"$ref": "#/components/schemas/Fix"}}, "scan_id": {"type": "integer"}, "report_url": {"type": "string", "format": "uri"}, "neighbors": {"type": "array", "description": "Your window on the Agent-Ready Index: up to 2 stores above you, yourself (is_self), and 2 below \u2014 the score to beat.", "items": {"type": "object", "properties": {"rank": {"type": "integer"}, "host": {"type": "string"}, "score": {"type": "integer"}, "grade": {"type": "string"}, "is_self": {"type": "boolean"}}}}}}}}}, "404": {"description": "Unknown scan_id (code SCAN_NOT_FOUND, next_action points at /api/v1/scan)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/api/v1/reports": {"post": {"operationId": "bulkReports", "summary": "Batch/bulk read: latest stored report for up to 100 hosts in one request (Pro API key)", "security": [{"bearerAuth": []}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"hosts": {"type": "array", "maxItems": 100, "items": {"type": "string"}}}, "required": ["hosts"]}}}}, "responses": {"200": {"description": "Reports per host", "content": {"application/json": {"schema": {"type": "object", "properties": {"reports": {"type": "array", "items": {"$ref": "#/components/schemas/HostReport"}}}}}}}, "400": {"description": "Invalid body (code INVALID_BODY)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Missing/invalid Pro API key (code UNAUTHORIZED)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Rate limited (code RATE_LIMITED)", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}}}, "/badge/{host}.svg": {"get": {"operationId": "scoreBadge", "summary": "Live score badge (SVG, rendered by us \u2014 can't be inflated)", "parameters": [{"name": "host", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "SVG badge", "content": {"image/svg+xml": {}}}}}}, "/verify/{host}": {"get": {"operationId": "verifyHost", "summary": "Redirect to the latest public report for a host", "parameters": [{"name": "host", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": {"302": {"description": "Redirect to report"}}}}}, "components": {"securitySchemes": {"bearerAuth": {"type": "http", "scheme": "bearer", "description": "Pro API key (ar_\u2026) \u2014 create in the console Account page."}}, "schemas": {"Pillar": {"type": "object", "description": "One scored pillar of the audit", "properties": {"id": {"type": "string"}, "label": {"type": "string"}, "score": {"type": "integer"}, "max": {"type": "integer"}, "checks": {"type": "array", "items": {"type": "object"}}}}, "Fix": {"type": "object", "description": "A prioritized remediation", "properties": {"check_id": {"type": "string"}, "title": {"type": "string"}, "points": {"type": "integer", "description": "Score points recovered by this fix"}, "how": {"type": "string"}}}, "HostReport": {"type": "object", "properties": {"host": {"type": "string"}, "scanned": {"type": "boolean"}, "score": {"type": "integer"}, "grade": {"type": "string"}, "capped": {"type": "boolean"}, "agent_ready_verified": {"type": "boolean"}, "scanned_at": {"type": "string", "format": "date-time"}, "report_url": {"type": "string", "format": "uri"}}, "required": ["host", "scanned"]}, "Error": {"type": "object", "description": "Structured error with a machine-readable code and, where applicable, a machine-parseable next_action.", "properties": {"error": {"type": "string", "description": "Legacy human-readable message (kept for backward compatibility)"}, "code": {"type": "string", "enum": ["MISSING_URL", "RATE_LIMITED", "SCAN_TIMEOUT", "SCAN_NOT_FOUND", "UNAUTHORIZED", "INVALID_BODY", "METHOD_NOT_ALLOWED", "NOT_FOUND"]}, "message": {"type": "string"}, "next_action": {"type": "object", "properties": {"method": {"type": "string"}, "endpoint": {"type": "string"}, "params": {"type": "object"}, "description": {"type": "string"}}}}, "required": ["code", "message"]}}}}