{ "openapi": "3.1.0", "info": { "title": "AX Rush", "version": "1.1.0", "description": "Measure website readiness for AI agents with 26 checks. Public sample scans and reports are anonymous. Paid organization endpoints cover sites, scans, fixes, comparisons, verifications, Answers and private agent runs. The remote engine requires an active paid subscription. Reading stored results does not start scans or model calls.", "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://axrush.com" } ], "security": [], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "An organization API key (axr_...), created on the account page. Part of the paid plan." } } }, "paths": { "/api/v1/me/sites/{id}/compare": { "get": { "operationId": "compareMyScans", "summary": "Compare two finished scans", "description": "Supply both before_scan_id and after_scan_id, or omit both for the latest two. Reports resolved findings, regressions and warnings when the engine, coverage or applicability changed. Check comparisons cover the origin only.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "before_scan_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "after_scan_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Existing results scoped to the API key's organization and the requested site.", "content": { "application/json": { "schema": { "type": "object", "properties": { "siteId": { "type": "string" }, "host": { "type": "string" }, "before": { "type": "object", "properties": { "id": { "type": "string" }, "score": { "type": [ "number", "null" ] }, "originScore": { "type": [ "number", "null" ] }, "pageCount": { "type": "number" }, "engine": { "type": [ "string", "null" ] }, "scannedAt": { "type": "string" }, "trigger": { "type": "string" } }, "required": [ "id", "score", "originScore", "pageCount", "engine", "scannedAt", "trigger" ], "additionalProperties": false }, "after": { "type": "object", "properties": { "id": { "type": "string" }, "score": { "type": [ "number", "null" ] }, "originScore": { "type": [ "number", "null" ] }, "pageCount": { "type": "number" }, "engine": { "type": [ "string", "null" ] }, "scannedAt": { "type": "string" }, "trigger": { "type": "string" } }, "required": [ "id", "score", "originScore", "pageCount", "engine", "scannedAt", "trigger" ], "additionalProperties": false }, "scoreDelta": { "type": "number" }, "comparable": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "string" } }, "checksScope": { "type": "string", "const": "origin" }, "changes": { "type": "array", "items": { "type": "object", "properties": { "checkId": { "type": "string" }, "name": { "type": "string" }, "before": { "anyOf": [ { "type": "object", "properties": { "score": { "type": [ "number", "null" ] }, "applicable": { "type": "boolean" }, "openFindings": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "detail": { "type": [ "string", "null" ] }, "hint": { "type": [ "string", "null" ] } }, "required": [ "status", "message", "detail", "hint" ], "additionalProperties": false } } }, "required": [ "score", "applicable", "openFindings" ], "additionalProperties": false }, { "type": "null" } ] }, "after": { "anyOf": [ { "type": "object", "properties": { "score": { "type": [ "number", "null" ] }, "applicable": { "type": "boolean" }, "openFindings": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "detail": { "type": [ "string", "null" ] }, "hint": { "type": [ "string", "null" ] } }, "required": [ "status", "message", "detail", "hint" ], "additionalProperties": false } } }, "required": [ "score", "applicable", "openFindings" ], "additionalProperties": false }, { "type": "null" } ] }, "scoreDelta": { "type": [ "number", "null" ] }, "change": { "type": "string", "enum": [ "added", "removed", "applicability_changed", "improved", "regressed", "unchanged", "findings_changed" ] }, "resolved": { "type": "boolean" }, "resolvedFindings": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "detail": { "type": [ "string", "null" ] }, "hint": { "type": [ "string", "null" ] } }, "required": [ "status", "message", "detail", "hint" ], "additionalProperties": false } }, "newFindings": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "detail": { "type": [ "string", "null" ] }, "hint": { "type": [ "string", "null" ] } }, "required": [ "status", "message", "detail", "hint" ], "additionalProperties": false } } }, "required": [ "checkId", "name", "before", "after", "scoreDelta", "change", "resolved", "resolvedFindings", "newFindings" ], "additionalProperties": false } }, "resolvedChecks": { "type": "array", "items": { "type": "string" } }, "regressedChecks": { "type": "array", "items": { "type": "string" } }, "nextStep": { "type": "string" } }, "required": [ "siteId", "host", "before", "after", "scoreDelta", "comparable", "warnings", "checksScope", "changes", "resolvedChecks", "regressedChecks", "nextStep" ], "additionalProperties": false } } } }, "400": { "description": "Invalid ids, pagination, query parameters or comparison order.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, unknown or revoked key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A paid plan is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "No owned site or requested results; comparisons require two distinct finished scans.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/api/v1/me/sites/{id}/verifications": { "get": { "operationId": "getMyVerifications", "summary": "Read fix verification records", "description": "Read pending, measuring, verified and expired outcomes. Does not schedule verification or start a scan.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } } ], "responses": { "200": { "description": "Existing results scoped to the API key's organization and the requested site.", "content": { "application/json": { "schema": { "type": "object", "properties": { "siteId": { "type": "string" }, "host": { "type": "string" }, "verifications": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "checkId": { "type": "string" }, "status": { "type": "string" }, "source": { "type": "string" }, "baselineScore": { "type": "number" }, "observedScore": { "type": [ "number", "null" ] }, "gained": { "type": [ "number", "null" ] }, "advisedAt": { "type": "string" }, "lastCheckedAt": { "type": [ "string", "null" ] }, "verifiedAt": { "type": [ "string", "null" ] }, "advisedScanId": { "type": "string" }, "verifiedScanId": { "type": [ "string", "null" ] } }, "required": [ "id", "checkId", "status", "source", "baselineScore", "observedScore", "gained", "advisedAt", "lastCheckedAt", "verifiedAt", "advisedScanId", "verifiedScanId" ], "additionalProperties": false } }, "nextOffset": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "nextStep": { "type": "string" } }, "required": [ "siteId", "host", "verifications", "nextOffset", "nextStep" ], "additionalProperties": false } } } }, "400": { "description": "Invalid ids, pagination, query parameters or comparison order.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, unknown or revoked key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A paid plan is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "No owned site or requested results; comparisons require two distinct finished scans.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/api/v1/me/sites/{id}/answers": { "get": { "operationId": "getMyAnswers", "summary": "Read stored Answers and citations", "description": "Paginate the pass list and select pass_id, or omit it to read the latest finished pass. Selection is independent of pagination. Never starts model calls or spends credits.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } }, { "name": "pass_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Existing results scoped to the API key's organization and the requested site.", "content": { "application/json": { "schema": { "type": "object", "properties": { "siteId": { "type": "string" }, "host": { "type": "string" }, "passes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "engine": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "questionsAsked": { "type": [ "number", "null" ] }, "questionsCited": { "type": [ "number", "null" ] }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "finishedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "engine", "model", "status", "questionsAsked", "questionsCited", "error", "createdAt", "finishedAt" ], "additionalProperties": false } }, "selectedPass": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "engine": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "questionsAsked": { "type": [ "number", "null" ] }, "questionsCited": { "type": [ "number", "null" ] }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "finishedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "engine", "model", "status", "questionsAsked", "questionsCited", "error", "createdAt", "finishedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "answer": { "type": [ "string", "null" ] }, "cited": { "type": [ "boolean", "null" ] }, "mentioned": { "type": [ "boolean", "null" ] }, "rank": { "type": [ "number", "null" ] }, "citations": { "$ref": "#/$defs/__schema0" }, "citedDomains": { "$ref": "#/$defs/__schema1" }, "competitors": { "$ref": "#/$defs/__schema2" }, "error": { "type": [ "string", "null" ] } }, "required": [ "id", "question", "answer", "cited", "mentioned", "rank", "citations", "citedDomains", "competitors", "error" ], "additionalProperties": false } }, "nextOffset": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "nextStep": { "type": "string" } }, "required": [ "siteId", "host", "passes", "selectedPass", "results", "nextOffset", "nextStep" ], "additionalProperties": false, "$defs": { "__schema0": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/__schema0" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/$defs/__schema0" } } ] }, "__schema1": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/__schema1" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/$defs/__schema1" } } ] }, "__schema2": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/__schema2" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/$defs/__schema2" } } ] } } } } } }, "400": { "description": "Invalid ids, pagination, query parameters or comparison order.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, unknown or revoked key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A paid plan is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "No owned site or requested results; comparisons require two distinct finished scans.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/api/v1/me/sites/{id}/agent-runs": { "get": { "operationId": "getMyAgentRuns", "summary": "Read private agent runs and evidence", "description": "Includes unpublished runs. Select run_id for one run; pagination is ignored for that selection. Never starts an agent or spends credits.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 } }, { "name": "run_id", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Existing results scoped to the API key's organization and the requested site.", "content": { "application/json": { "schema": { "type": "object", "properties": { "siteId": { "type": "string" }, "host": { "type": "string" }, "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "taskId": { "type": "string" }, "batchId": { "type": "string" }, "status": { "type": "string" }, "verdict": { "type": [ "string", "null" ] }, "reasons": { "type": "array", "items": { "type": "string" } }, "goal": { "type": [ "string", "null" ] }, "stepCount": { "type": "number" }, "answer": { "type": [ "string", "null" ] }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "quote": { "type": "string" } }, "required": [ "url", "quote" ], "additionalProperties": false } }, "model": { "type": [ "string", "null" ] }, "agentVersion": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "publishedAt": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "replayUrl": { "type": "string" } }, "required": [ "id", "taskId", "batchId", "status", "verdict", "reasons", "goal", "stepCount", "answer", "evidence", "model", "agentVersion", "createdAt", "publishedAt", "error", "replayUrl" ], "additionalProperties": false } }, "nextOffset": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "nextStep": { "type": "string" } }, "required": [ "siteId", "host", "runs", "nextOffset", "nextStep" ], "additionalProperties": false } } } }, "400": { "description": "Invalid ids, pagination, query parameters or comparison order.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, unknown or revoked key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "A paid plan is required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "No owned site or requested results; comparisons require two distinct finished scans.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/api/v1/engine/audit": { "post": { "operationId": "auditWithPrivateEngine", "summary": "Run a remote audit with an active paid AX Rush subscription", "description": "Used by ax-audit 6. Executes on AX Rush servers, never on the caller's machine. Requires a non-revoked organization key and active paid subscription for every audit. Public HTTP(S) targets on ports 80/443 only; no credentials, localhost or private networks. Does not persist the report. Limited to 10 audits per organization per hour and 5 per target per hour, shared with other scan surfaces.", "security": [ { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "checks": { "type": "array", "minItems": 1, "maxItems": 26, "items": { "type": "string" } }, "profile": { "type": "string", "enum": [ "auto", "api", "mcp", "agent", "docs", "commerce", "all" ] }, "timeout": { "type": "integer", "minimum": 100, "maximum": 10000 }, "retries": { "type": "integer", "minimum": 0, "maximum": 2 } } } } } }, "responses": { "200": { "description": "AuditReport returned by the private engine.", "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "timestamp", "engine", "overallScore", "grade", "results", "duration" ], "properties": { "url": { "type": "string", "format": "uri" }, "timestamp": { "type": "string", "format": "date-time" }, "engine": { "type": "string", "example": "axrush-engine@6.0.0" }, "overallScore": { "type": "number", "minimum": 0, "maximum": 100 }, "duration": { "type": "number", "minimum": 0 }, "grade": { "type": "object", "required": [ "min", "label", "color" ], "properties": { "min": { "type": "number" }, "label": { "type": "string" }, "color": { "type": "string" } } }, "results": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "description", "score", "findings", "duration" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "score": { "type": "number", "minimum": 0, "maximum": 100 }, "duration": { "type": "number" }, "applicable": { "type": "boolean" }, "category": { "type": "string" }, "findings": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "warn", "fail" ] }, "message": { "type": "string" }, "detail": { "type": "string", "nullable": true }, "hint": { "type": "string", "nullable": true } }, "required": [ "status", "message" ] } } } } } } } } } }, "400": { "description": "Invalid options or a non-public target." }, "401": { "description": "Missing, invalid or revoked API key." }, "403": { "description": "An active paid subscription is required." }, "413": { "description": "Request exceeds 8 KiB." }, "429": { "description": "Organization or target rate limit exceeded. Retry-After is returned." }, "503": { "description": "Authorization or audit execution is temporarily unavailable." } } } }, "/api/v1/report/{host}": { "get": { "operationId": "getReport", "summary": "Read the stored public report for a host", "description": "Returns the most recent public measurement without scanning again. Sends no traffic to the site and is not rate limited.", "parameters": [ { "name": "host", "in": "path", "required": true, "schema": { "type": "string" }, "example": "example.com" } ], "responses": { "200": { "description": "The most recent public measurement.", "content": { "application/json": { "schema": { "type": "object", "properties": { "host": { "type": "string", "example": "example.com" }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "grade": { "type": "string", "enum": [ "excellent", "good", "fair", "poor" ] }, "engine": { "type": "string", "example": "axrush-engine@6.0.0" }, "originScore": { "type": [ "number", "null" ] }, "pageCount": { "type": "integer", "minimum": 0 }, "scope": { "type": "string", "enum": [ "home_page", "site_blend" ] }, "checksScope": { "type": "string", "const": "origin" }, "discoveredUrls": { "type": [ "integer", "null" ], "description": "Discovered URLs are not measured page coverage." }, "nextStep": { "type": "string" }, "scannedAt": { "type": "string", "format": "date-time" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "llms-txt" }, "name": { "type": "string", "example": "LLMs.txt" }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "weight": { "type": "integer", "description": "0 means it reports without moving the score." }, "informational": { "type": "boolean", "description": "Informational under the current engine; does not affect the score." }, "applicable": { "type": "boolean", "description": "False when the check's subject is absent from the site — no API to describe, no commerce surface, no MCP server. The score is 0 and means nothing; such a check is excluded from the overall score rather than counted as a failure." }, "findings": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "warn", "fail" ] }, "message": { "type": "string" }, "detail": { "type": "string", "nullable": true }, "hint": { "type": "string", "nullable": true } }, "required": [ "status", "message" ] } } }, "required": [ "id", "name", "score", "weight", "applicable", "findings" ] } }, "reportUrl": { "type": "string", "format": "uri" } }, "required": [ "host", "score", "grade", "checks" ] } } } }, "404": { "description": "Nobody has scanned this host publicly yet.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/api/v1/agent-tasks/{host}": { "get": { "operationId": "getAgentTasks", "summary": "Read the agent task replays a host's owner published", "description": "Returns the runs the site's owner chose to publish: what an agent was asked to do on that site, whether it could, and what it reported. Only published runs are visible, because a replay quotes the site's own pages back and publishing one is the owner's decision. Sends no traffic to the site and is not rate limited.", "parameters": [ { "name": "host", "in": "path", "required": true, "schema": { "type": "string" }, "example": "example.com" } ], "responses": { "200": { "description": "The published runs, newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "host": { "type": "string", "example": "example.com" }, "rate": { "type": "number", "nullable": true, "description": "Share of published runs that completed the task, as a percentage. Over the published runs only, so it is checkable from what is returned." }, "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "task": { "type": "string", "example": "ecommerce.find_product_price" }, "verdict": { "type": "string", "enum": [ "success", "partial", "fail", "blocked", "hallucinated", "not_applicable" ] }, "reasons": { "type": "array", "items": { "type": "string" } }, "goal": { "type": "string", "nullable": true }, "steps": { "type": "integer" }, "answer": { "type": "string", "nullable": true }, "publishedAt": { "type": "string", "format": "date-time", "nullable": true }, "replayUrl": { "type": "string", "format": "uri" } }, "required": [ "id", "task", "verdict", "reasons", "steps", "replayUrl" ] } } }, "required": [ "host", "runs" ] } } } }, "404": { "description": "Nothing has been published for this host.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/api/v1/scan": { "post": { "operationId": "scanSite", "summary": "Measure a domain", "description": "Runs the checks against the site's home page and returns the result. Rate limited per caller and per target, because it sends real requests to somebody else's server.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "example": "example.com" } }, "required": [ "domain" ] } } } }, "responses": { "200": { "description": "The measurement.", "content": { "application/json": { "schema": { "type": "object", "properties": { "host": { "type": "string", "example": "example.com" }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "grade": { "type": "string", "enum": [ "excellent", "good", "fair", "poor" ] }, "engine": { "type": "string", "example": "axrush-engine@6.0.0" }, "originScore": { "type": [ "number", "null" ] }, "pageCount": { "type": "integer", "minimum": 0 }, "scope": { "type": "string", "enum": [ "home_page", "site_blend" ] }, "checksScope": { "type": "string", "const": "origin" }, "discoveredUrls": { "type": [ "integer", "null" ], "description": "Discovered URLs are not measured page coverage." }, "nextStep": { "type": "string" }, "scannedAt": { "type": "string", "format": "date-time" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "llms-txt" }, "name": { "type": "string", "example": "LLMs.txt" }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "weight": { "type": "integer", "description": "0 means it reports without moving the score." }, "informational": { "type": "boolean", "description": "Informational under the current engine; does not affect the score." }, "applicable": { "type": "boolean", "description": "False when the check's subject is absent from the site — no API to describe, no commerce surface, no MCP server. The score is 0 and means nothing; such a check is excluded from the overall score rather than counted as a failure." }, "findings": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "warn", "fail" ] }, "message": { "type": "string" }, "detail": { "type": "string", "nullable": true }, "hint": { "type": "string", "nullable": true } }, "required": [ "status", "message" ] } } }, "required": [ "id", "name", "score", "weight", "applicable", "findings" ] } }, "reportUrl": { "type": "string", "format": "uri" } }, "required": [ "host", "score", "grade", "checks" ] } } } }, "400": { "description": "Not a domain that can be measured.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "429": { "description": "Too many scans from this caller, or that target is already being scanned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "502": { "description": "The site could not be measured.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/api/v1/me/sites": { "get": { "operationId": "listMySites", "parameters": [ { "name": "limit", "in": "query", "description": "Enables pagination with a default limit of 20. Omit both parameters for the documented legacy response size.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "offset", "in": "query", "description": "Enables pagination with a default limit of 20. Omit both parameters for the documented legacy response size.", "schema": { "type": "integer", "minimum": 0, "maximum": 10000 } } ], "summary": "List your organization's sites with their latest scores", "description": "The sites your API key's organization watches, each with its most recent score and the one before it. Requires an API key; part of the paid plan.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "The sites, oldest first. With limit or offset, returns a page and nextOffset. Without either parameter, preserves the legacy unpaged response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sites": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "host": { "type": "string", "example": "example.com" }, "url": { "type": "string", "format": "uri" }, "score": { "type": "integer", "nullable": true }, "previousScore": { "type": "integer", "nullable": true, "description": "The scan before the last one, so movement is a field." }, "scannedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "host", "url", "score", "previousScore", "scannedAt", "createdAt" ] } }, "nextOffset": { "type": [ "integer", "null" ], "description": "Pass as offset with the same limit to continue; null means no more rows." } }, "required": [ "sites" ] } } } }, "400": { "description": "Invalid ids or query parameters. An N/A check has nothing to fix.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, unknown or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "The organization is not on the paid plan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/api/v1/me/sites/{id}/report": { "get": { "operationId": "getMyReport", "summary": "Read the latest full report for one of your sites", "description": "The public report's shape plus what only the owner may read: the origin score, the page blend, and per-page scores. Requires an API key.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The latest finished scan, in full.", "content": { "application/json": { "schema": { "type": "object", "properties": { "host": { "type": "string", "example": "example.com" }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "grade": { "type": "string", "enum": [ "excellent", "good", "fair", "poor" ] }, "engine": { "type": "string", "example": "axrush-engine@6.0.0" }, "originScore": { "type": "integer", "nullable": true, "description": "The origin's own score. The top-level score blends the origin with every included page." }, "pageCount": { "type": "integer", "description": "Pages inside the blend." }, "scope": { "type": "string", "enum": [ "home_page", "site_blend" ] }, "checksScope": { "type": "string", "const": "origin" }, "discoveredUrls": { "type": [ "integer", "null" ], "description": "Discovered URLs are not measured page coverage." }, "nextStep": { "type": "string" }, "scannedAt": { "type": "string", "format": "date-time" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "llms-txt" }, "name": { "type": "string", "example": "LLMs.txt" }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "weight": { "type": "integer", "description": "0 means it reports without moving the score." }, "informational": { "type": "boolean", "description": "Informational under the current engine; does not affect the score." }, "applicable": { "type": "boolean", "description": "False when the check's subject is absent from the site — no API to describe, no commerce surface, no MCP server. The score is 0 and means nothing; such a check is excluded from the overall score rather than counted as a failure." }, "findings": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "warn", "fail" ] }, "message": { "type": "string" }, "detail": { "type": "string", "nullable": true }, "hint": { "type": "string", "nullable": true } }, "required": [ "status", "message" ] } } }, "required": [ "id", "name", "score", "weight", "applicable", "findings" ] } }, "reportUrl": { "type": "string", "format": "uri" }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "template": { "type": "string", "example": "/blog/:slug" }, "label": { "type": "string", "nullable": true }, "included": { "type": "boolean", "description": "Whether the owner keeps this page in the blended site score." }, "score": { "type": "integer", "minimum": 0, "maximum": 100 } }, "required": [ "id", "template", "label", "included", "score" ] } } }, "required": [ "host", "score", "grade", "checks", "originScore", "pageCount", "pages" ] } } } }, "400": { "description": "Invalid ids or query parameters. An N/A check has nothing to fix.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, unknown or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "The organization is not on the paid plan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "No such site in your organization, or no finished scan yet.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/api/v1/me/sites/{id}/history": { "get": { "operationId": "getMyHistory", "summary": "Read the score history for one of your sites", "description": "Succeeded scans newest first, with the engine version on every row. Requires an API key.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Enables pagination with a default limit of 20. Omit both parameters for the documented legacy response size.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "offset", "in": "query", "description": "Enables pagination with a default limit of 20. Omit both parameters for the documented legacy response size.", "schema": { "type": "integer", "minimum": 0, "maximum": 10000 } } ], "responses": { "200": { "description": "Newest first. Without pagination parameters, preserves the legacy 100-scan default. With limit or offset, default 20 and maximum 50. nextOffset can continue beyond 100.", "content": { "application/json": { "schema": { "type": "object", "properties": { "siteId": { "type": "string", "format": "uuid" }, "host": { "type": "string" }, "scans": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "trigger": { "type": "string", "enum": [ "manual", "scheduled", "api", "public" ] }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "originScore": { "type": "integer", "nullable": true }, "pageCount": { "type": "integer", "nullable": true }, "engine": { "type": "string", "description": "The engine that measured this scan. A moved score means nothing until you know whether the ruler changed." }, "finishedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "trigger", "score", "originScore", "pageCount", "engine", "finishedAt" ] } }, "nextOffset": { "type": [ "integer", "null" ], "description": "Pass as offset with the same limit to continue; null means no more rows." } }, "required": [ "siteId", "host", "scans" ] } } } }, "400": { "description": "Invalid ids or query parameters. An N/A check has nothing to fix.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, unknown or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "The organization is not on the paid plan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "No such site in your organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/api/v1/me/sites/{id}/scan": { "post": { "operationId": "scanMySite", "summary": "Queue a scan of one of your sites", "description": "Queues the same scan the panel's Scan now runs and returns the scan id at once; poll /api/v1/me/scans/{id} until it settles. One scan per site may be active at a time. Requires an API key.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Queued. Poll /api/v1/me/scans/{id}.", "content": { "application/json": { "schema": { "type": "object", "properties": { "scanId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued" ] }, "pollAfterSeconds": { "type": "integer", "example": 5 } }, "required": [ "scanId", "status" ] } } } }, "400": { "description": "Invalid ids or query parameters. An N/A check has nothing to fix.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, unknown or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "The organization is not on the paid plan, or the site is over its allowance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "No such site in your organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "409": { "description": "A scan of this site is already queued or running.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/api/v1/me/scans/{id}": { "get": { "operationId": "getMyScan", "summary": "Poll one scan until it settles", "description": "Queued and running answer with the status alone; failed carries the error; succeeded carries the full report. Requires an API key.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The scan's current state.", "content": { "application/json": { "schema": { "type": "object", "properties": { "pollAfterSeconds": { "type": "integer", "example": 5 }, "scanId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "running", "failed", "succeeded" ] }, "error": { "type": "string", "nullable": true, "description": "Present when the status is failed." }, "report": { "type": "object", "properties": { "host": { "type": "string", "example": "example.com" }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "grade": { "type": "string", "enum": [ "excellent", "good", "fair", "poor" ] }, "engine": { "type": "string", "example": "axrush-engine@6.0.0" }, "originScore": { "type": "integer", "nullable": true, "description": "The origin's own score. The top-level score blends the origin with every included page." }, "pageCount": { "type": "integer", "description": "Pages inside the blend." }, "scope": { "type": "string", "enum": [ "home_page", "site_blend" ] }, "checksScope": { "type": "string", "const": "origin" }, "discoveredUrls": { "type": [ "integer", "null" ], "description": "Discovered URLs are not measured page coverage." }, "nextStep": { "type": "string" }, "scannedAt": { "type": "string", "format": "date-time" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "llms-txt" }, "name": { "type": "string", "example": "LLMs.txt" }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "weight": { "type": "integer", "description": "0 means it reports without moving the score." }, "informational": { "type": "boolean", "description": "Informational under the current engine; does not affect the score." }, "applicable": { "type": "boolean", "description": "False when the check's subject is absent from the site — no API to describe, no commerce surface, no MCP server. The score is 0 and means nothing; such a check is excluded from the overall score rather than counted as a failure." }, "findings": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "warn", "fail" ] }, "message": { "type": "string" }, "detail": { "type": "string", "nullable": true }, "hint": { "type": "string", "nullable": true } }, "required": [ "status", "message" ] } } }, "required": [ "id", "name", "score", "weight", "applicable", "findings" ] } }, "reportUrl": { "type": "string", "format": "uri" }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "template": { "type": "string", "example": "/blog/:slug" }, "label": { "type": "string", "nullable": true }, "included": { "type": "boolean", "description": "Whether the owner keeps this page in the blended site score." }, "score": { "type": "integer", "minimum": 0, "maximum": 100 } }, "required": [ "id", "template", "label", "included", "score" ] } } }, "required": [ "host", "score", "grade", "checks", "originScore", "pageCount", "pages" ], "nullable": true, "description": "Present when the status is succeeded." } }, "required": [ "scanId", "status" ] } } } }, "400": { "description": "Invalid ids or query parameters. An N/A check has nothing to fix.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, unknown or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "The organization is not on the paid plan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "No scan with that id in your organization.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/api/v1/me/sites/{id}/fixes": { "get": { "operationId": "getMyFixes", "summary": "What to fix first on one of your sites, and what it is worth", "description": "The open work from the latest scan, ordered by the points each fix returns to the score. Items with a gain of zero are findings on checks that already score full marks: worth doing, not worth doing first. Requires an API key.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The work list, most valuable first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "siteId": { "type": "string", "format": "uuid" }, "host": { "type": "string", "example": "example.com" }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "engine": { "type": "string", "example": "ax-audit@4.2.1" }, "scannedAt": { "type": "string", "format": "date-time" }, "fixes": { "type": "array", "items": { "type": "object", "properties": { "checkId": { "type": "string", "example": "llms-txt" }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "weight": { "type": "integer" }, "gain": { "type": "number", "description": "Points the site score returns if this check passes outright. Zero means the check already scores full marks and the finding is advisory." }, "open": { "type": "integer", "description": "Findings that are not passing." }, "artifact": { "type": "string", "nullable": true, "description": "The generated file that fixes this, for /api/v1/me/sites/{id}/artifacts/{kind}." }, "headline": { "type": "string", "description": "The first open finding." } }, "required": [ "checkId", "score", "weight", "gain", "open", "artifact", "headline" ] }, "description": "Most valuable first. Empty when nothing is open." } }, "required": [ "siteId", "host", "score", "engine", "scannedAt", "fixes" ] } } } }, "400": { "description": "Invalid ids or query parameters. An N/A check has nothing to fix.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, unknown or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "The organization is not on the paid plan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "No such site in your organization, or no finished scan yet.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/api/v1/me/sites/{id}/fixes/{checkId}": { "get": { "operationId": "getMyFix", "summary": "How to fix one check on one of your sites", "description": "Every open finding with its measured value and the engine's hint, the guide for that check, the definition of done, and the whole fix as one prose block. Assembled from the measurement rather than written by a model, so the same request returns the same answer. Requires an API key.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "checkId", "in": "path", "required": true, "description": "A check id from /api/v1/me/sites/{id}/fixes.", "schema": { "type": "string", "example": "llms-txt" } } ], "responses": { "200": { "description": "The fix. A check with nothing open answers in the same shape with an empty findings array.", "content": { "application/json": { "schema": { "type": "object", "properties": { "siteId": { "type": "string", "format": "uuid" }, "host": { "type": "string", "example": "example.com" }, "checkId": { "type": "string", "example": "llms-txt" }, "name": { "type": "string", "example": "LLMs.txt" }, "score": { "type": "integer", "minimum": 0, "maximum": 100 }, "weight": { "type": "integer" }, "engine": { "type": "string", "example": "ax-audit@4.2.1" }, "scannedAt": { "type": "string", "format": "date-time" }, "guideUrl": { "type": "string", "format": "uri" }, "artifact": { "type": "string", "nullable": true }, "definitionOfDone": { "type": "string" }, "findings": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "warn", "fail" ] }, "message": { "type": "string" }, "detail": { "type": "string", "nullable": true }, "hint": { "type": "string", "nullable": true }, "learnMore": { "type": "string", "nullable": true, "format": "uri" } }, "required": [ "status", "message", "detail", "hint", "learnMore" ] }, "description": "Empty when the check is already passing." }, "instructions": { "type": "string", "description": "The whole fix as one prose block, assembled from the findings above. No model wrote it, so the same request returns the same text." } }, "required": [ "siteId", "host", "checkId", "name", "score", "weight", "engine", "scannedAt", "guideUrl", "artifact", "definitionOfDone", "findings", "instructions" ] } } } }, "400": { "description": "Invalid ids or query parameters. An N/A check has nothing to fix.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, unknown or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "The organization is not on the paid plan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "No such site in your organization, no finished scan yet, or no check with that id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } }, "/api/v1/me/sites/{id}/artifacts/{kind}": { "get": { "operationId": "getMyArtifact", "summary": "Get a generated file to publish", "description": "The bytes of a file this product wrote for the site, with the path to serve it at, the headers it needs and the checks publishing it would improve. Returns what was generated last and never generates on demand: writing one spends a model call, which is a decision with a cost. Requires an API key.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "llms_txt", "llms_full", "ai_catalog", "agent_card", "mcp_server_card" ] } } ], "responses": { "200": { "description": "The stored file.", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "llms_txt", "llms_full", "ai_catalog", "agent_card", "mcp_server_card" ] }, "path": { "type": "string", "example": "/llms.txt" }, "contentType": { "type": "string", "example": "text/markdown; charset=utf-8" }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Response headers this file needs, beyond Content-Type." }, "readiness": { "type": "string", "enum": [ "ready", "needs_service" ], "description": "needs_service means the file describes something the site may not run. Publish it only if it does." }, "claims": { "type": "array", "items": { "type": "string" }, "description": "What the file asserts about the site, for review before publishing." }, "addresses": { "type": "array", "items": { "type": "string" }, "description": "Check ids publishing this file would improve." }, "generatedAt": { "type": "string", "format": "date-time" }, "body": { "type": "string", "description": "The bytes to serve, verbatim." } }, "required": [ "kind", "path", "contentType", "headers", "readiness", "claims", "addresses", "generatedAt", "body" ] } } } }, "400": { "description": "That is not an artifact kind.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "401": { "description": "Missing, unknown or revoked API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "403": { "description": "The organization is not on the paid plan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "404": { "description": "No such site in your organization, or no file of that kind generated yet.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } }, "503": { "description": "Temporarily unavailable. Retry later.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ] } } } } } } } } }