{ "openapi": "3.1.0", "info": { "title": "AgentReady API", "version": "1.1.0", "description": "One API, two questions. The scan endpoints measure the TECHNICAL agent readiness of any domain — free, no key needed. The case endpoints measure what ChatGPT, Claude, Gemini and Perplexity actually answer about a company, and need a key. Everything the dashboard does, this API does too. Every response carries a meta.pricing field — currently {\"model\":\"free\"}, ready for agent payments over HTTP 402.", "contact": { "name": "The Autopilot", "url": "https://the-autopilot.com" } }, "servers": [ { "url": "https://ai-agent-ready.com", "description": "Production" } ], "tags": [ { "name": "scans", "description": "Technical agent-readiness scans. Free, bearer optional." }, { "name": "cases", "description": "AI answer visibility: cases, runs and results. Bearer required." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key from the dashboard. Header: Authorization: Bearer " } }, "schemas": { "Meta": { "type": "object", "required": [ "pricing", "generated_at", "docs" ], "properties": { "pricing": { "type": "object", "properties": { "model": { "type": "string", "enum": [ "free" ] } } }, "generated_at": { "type": "string", "format": "date-time" }, "docs": { "type": "string", "format": "uri" } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/Meta" } } } } }, "security": [ { "bearerAuth": [] } ], "paths": { "/api/v1/cases": { "get": { "operationId": "list_cases", "summary": "All cases visible to the key", "description": "Returns the cases belonging to the account behind the API key, including the current overall score and the time of the last run. A key carrying the monitor:admin scope reads every tenant instead; in that case each entry also carries owner_email and the response is marked scope: all_tenants.", "tags": [ "cases" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Filters over case name and domain.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "cases": [ { "id": "4f1e9b2c-0d8a-4f7b-9d21-1b7c0c9a55e1", "user_id": "6b3d1a70-25c8-4f0e-9a3d-77a1f2b4c8d9", "name": "Example CRM", "domain": "example-crm.com", "category": "CRM software for trade businesses", "competitors": [ "Craftnote", "Meisterwerk", "ToolTime" ], "status": "active", "latest_score": 44, "last_run_at": "2026-08-01T03:12:00.000Z" } ], "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } }, "401": { "description": "Bearer token missing or unknown.", "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "Bearer token missing or unknown." }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } }, "403": { "description": "No Monitor account exists for this key.", "content": { "application/json": { "example": { "error": { "code": "no_account", "message": "No Monitor account exists for this key." }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } } } } }, "/api/v1/cases/{id}": { "get": { "operationId": "get_case", "summary": "Master data and fact sheet of one case", "description": "Everything the monitor knows about the brand itself: fact sheet, ICP, competitors, use cases, region and languages. The fact sheet is the ground truth the accuracy scoring runs against, which makes this the endpoint an agent reads before writing or answering about the customer. Resolves across all tenants for a key with the monitor:admin scope, otherwise only within the key holder's own cases.", "tags": [ "cases" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Case id (UUID).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "case": { "id": "4f1e9b2c-0d8a-4f7b-9d21-1b7c0c9a55e1", "name": "Example CRM", "domain": "example-crm.com", "category": "CRM software for trade businesses", "icp": "Owners of trade businesses with 5 to 50 employees", "competitors": [ "Craftnote", "Meisterwerk", "ToolTime" ], "use_cases": [ "Quoting", "Time tracking", "Invoicing" ], "region": "Germany", "languages": [ "de", "en" ], "fact_sheet": { "Price": "From 29 EUR per user and month", "Trial": "30 days, no credit card" }, "status": "active", "created_at": "2026-07-14T08:02:00.000Z", "updated_at": "2026-08-02T11:20:00.000Z" }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } }, "401": { "description": "Bearer token missing or unknown.", "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "Bearer token missing or unknown." }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } }, "403": { "description": "No Monitor account exists for this key.", "content": { "application/json": { "example": { "error": { "code": "no_account", "message": "No Monitor account exists for this key." }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } }, "404": { "description": "No case with this id belongs to the key holder.", "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "No case with this id belongs to the key holder." }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } } } } }, "/api/v1/cases/{id}/summary": { "get": { "operationId": "get_case_summary", "summary": "Current score and share of answer", "description": "The result of the most recent finished run: overall score, score per model, the three score dimensions, share of answer against every competitor, top gaps, the domains the models cited as sources, and the delta to the previous run.", "tags": [ "cases" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Case id (UUID).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "case": { "id": "4f1e9b2c-0d8a-4f7b-9d21-1b7c0c9a55e1", "name": "Example CRM" }, "run": { "id": "9a0c...", "label": "Aug 26", "kind": "monthly", "finished_at": "2026-08-01T03:41:00.000Z" }, "summary": { "total_score": 44, "per_model": { "openai": 48, "anthropic": 39, "perplexity": 51, "google": 38 }, "dimensions": { "visibility": 1.1, "accuracy": 1.4, "sentiment": 0.2 }, "share_of_answer": [ { "name": "Craftnote", "share": 0.8, "mentions": 7, "judge_mentions": 1, "total": 10, "is_self": false }, { "name": "Example CRM", "share": 0.4, "mentions": 4, "judge_mentions": 0, "total": 10, "is_self": true } ], "top_gaps": [ "No prices are named", "Nothing is said about a trial" ], "delta": { "total_score": -6, "per_model": { "openai": -4 }, "previous_run_id": "7c21..." }, "top_cited_domains": [ { "domain": "craftnote.de", "citations": 9, "answers": 6, "share": 0.75, "is_self": false, "competitor": "Craftnote", "by_model": { "perplexity": 4, "openai": 2 }, "by_block": { "A": 2, "E": 4 } }, { "domain": "example-crm.com", "citations": 3, "answers": 2, "share": 0.25, "is_self": true, "competitor": null, "by_model": { "perplexity": 2 }, "by_block": { "B": 2 } } ], "own_citation_rate": 0.25, "competitor_citation_rate": { "Craftnote": 0.75, "Meisterwerk": 0, "ToolTime": 0 }, "sources_meta": { "answers_total": 10, "answers_with_sources": 8, "training_recall": { "raw_mentions": 1, "raw_total": 6, "online_mentions": 4, "online_total": 6 } } }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } }, "404": { "description": "Case does not exist or belongs to another account.", "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "Case does not exist or belongs to another account." }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } }, "409": { "description": "No run has finished for this case yet.", "content": { "application/json": { "example": { "error": { "code": "no_run", "message": "No run has finished for this case yet." }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } } } } }, "/api/v1/cases/{id}/runs": { "get": { "operationId": "list_runs", "summary": "Runs with score and delta", "description": "All measurement runs of a case, newest first, with status, overall score and the delta to the preceding run.", "tags": [ "cases" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Case id (UUID).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of runs (1–100).", "schema": { "type": "integer", "default": 24 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "runs": [ { "id": "9a0c...", "label": "Aug 26", "kind": "monthly", "status": "done", "scheduled_for": "2026-08-01T03:00:00.000Z", "finished_at": "2026-08-01T03:41:00.000Z", "total_score": 44, "delta": -6 } ], "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } }, "404": { "description": "Case does not exist or belongs to another account.", "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "Case does not exist or belongs to another account." }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } } } }, "post": { "operationId": "create_run", "summary": "Trigger a manual measurement run (Pro)", "description": "Queues a run. The worker picks it up within seconds. Pro plan only; a run that is already queued or in progress for the same case is not duplicated.", "tags": [ "cases" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Case id (UUID).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "description": "Optional label for the run.", "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string" } } }, "example": { "label": "After relaunch" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "run": { "id": "b71f...", "label": "After relaunch", "kind": "manual", "status": "queued" }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } }, "402": { "description": "The plan does not allow manual re-runs.", "content": { "application/json": { "example": { "error": { "code": "plan_required", "message": "The plan does not allow manual re-runs." }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } }, "409": { "description": "A run is already queued or in progress for this case.", "content": { "application/json": { "example": { "error": { "code": "run_pending", "message": "A run is already queued or in progress for this case." }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } } } } }, "/api/v1/scans": { "post": { "operationId": "scan_domain", "summary": "Run a technical agent-readiness scan", "description": "Scans a domain live against nine technical criteria in four pillars (Retrievable, Explainable, Actionable, Distributed) and returns a score from 0 to 100. The score is a percentage of the APPLICABLE points, not a plain sum: areas that do not apply to a domain are removed from numerator and denominator, and signals that cannot be verified from outside count as half. A check may therefore report state \"unknown\" with max 0. Takes 5-30 seconds. Free; without a bearer key you get 3 scans per day per IP.", "tags": [ "scans" ], "security": [ { "bearerAuth": [] }, {} ], "parameters": [], "requestBody": { "required": true, "description": "The domain to scan. With or without scheme, with or without www.", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "Domain or URL to scan." } }, "required": [ "domain" ] }, "example": { "domain": "example.com" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "example": { "scan": { "id": "0e2f8c11-6b4a-4a7e-9f10-2c3d4e5f6a7b", "domain": "example.com", "score": 62, "scoring_version": 2, "created_at": "2026-09-14T08:31:12.000Z", "url": "https://ai-agent-ready.com/check/scan/0e2f8c11-6b4a-4a7e-9f10-2c3d4e5f6a7b", "checks": [ { "id": "crawler", "pillar": "R", "title": "AI crawler access", "state": "good", "score": 18, "max": 18, "findings": [ { "state": "good", "text": "GPTBot, ClaudeBot and PerplexityBot all receive 200." } ] } ] }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } }, "400": { "description": "The domain is missing or cannot be parsed.", "content": { "application/json": { "example": { "error": { "code": "invalid_domain", "message": "The domain is missing or cannot be parsed." }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } }, "401": { "description": "A bearer token was sent but is unknown.", "content": { "application/json": { "example": { "error": { "code": "invalid_key", "message": "A bearer token was sent but is unknown." }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } }, "429": { "description": "Anonymous daily scan limit reached.", "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "Anonymous daily scan limit reached." }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } }, "500": { "description": "The scan could not be completed.", "content": { "application/json": { "example": { "error": { "code": "scan_failed", "message": "The scan could not be completed." }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } }, "503": { "description": "A bearer token was sent but could not be verified right now.", "content": { "application/json": { "example": { "error": { "code": "auth_unavailable", "message": "A bearer token was sent but could not be verified right now." }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } } } } }, "/api/v1/scans/{id}": { "get": { "operationId": "get_scan", "summary": "Fetch a stored scan result", "description": "Returns a previously created scan with all nine checks and their findings. Results are public: the same payload backs the shareable result page.", "tags": [ "scans" ], "security": [ { "bearerAuth": [] }, {} ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Scan id (UUID).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "scan": { "id": "0e2f8c11-6b4a-4a7e-9f10-2c3d4e5f6a7b", "domain": "example.com", "score": 62, "scoring_version": 2, "created_at": "2026-09-14T08:31:12.000Z", "url": "https://ai-agent-ready.com/check/scan/0e2f8c11-6b4a-4a7e-9f10-2c3d4e5f6a7b", "checks": [ { "id": "crawler", "pillar": "R", "title": "AI crawler access", "state": "good", "score": 18, "max": 18, "findings": [ { "state": "good", "text": "GPTBot, ClaudeBot and PerplexityBot all receive 200." } ] } ] }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } }, "401": { "description": "A bearer token was sent but is unknown.", "content": { "application/json": { "example": { "error": { "code": "invalid_key", "message": "A bearer token was sent but is unknown." }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } }, "404": { "description": "There is no result for this id.", "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "There is no result for this id." }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } }, "503": { "description": "A bearer token was sent but could not be verified right now.", "content": { "application/json": { "example": { "error": { "code": "auth_unavailable", "message": "A bearer token was sent but could not be verified right now." }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } } } } }, "/api/v1/stats": { "get": { "operationId": "get_stats", "summary": "Aggregated market data across all scans", "description": "Anonymous aggregates over every scan ever run at the current scoring version: number of domains, score distribution and how often each check fails. No domain names, no personal data. This is the data behind the public report.", "tags": [ "scans" ], "security": [ { "bearerAuth": [] }, {} ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "stats": { "domains": 1284, "scans": 1731, "scoring_version": 2, "median_score": 54, "updated_at": "2026-09-14T08:00:00.000Z" }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } }, "401": { "description": "A bearer token was sent but is unknown.", "content": { "application/json": { "example": { "error": { "code": "invalid_key", "message": "A bearer token was sent but is unknown." }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } }, "503": { "description": "A bearer token was sent but could not be verified right now.", "content": { "application/json": { "example": { "error": { "code": "auth_unavailable", "message": "A bearer token was sent but could not be verified right now." }, "meta": { "pricing": { "model": "free" }, "generated_at": "2026-08-25T09:12:44.000Z", "docs": "https://ai-agent-ready.com/docs/api" } } } } } } } } }, "x-mcp": { "note": "The Monitor MCP server runs inside this application at /api/mcp (Authorization header) and /api/mcp/{api_key} (key in the path, for clients without header support). Each tool maps 1:1 to an endpoint listed here, and both surfaces resolve the same scope: own cases by default, every tenant for a key carrying the monitor:admin scope. Read-only tools only; create_run is not exposed over MCP.", "tools": [ { "tool": "list_cases", "method": "GET", "path": "/api/v1/cases" }, { "tool": "get_case", "method": "GET", "path": "/api/v1/cases/{id}" }, { "tool": "get_case_summary", "method": "GET", "path": "/api/v1/cases/{id}/summary" }, { "tool": "list_runs", "method": "GET", "path": "/api/v1/cases/{id}/runs" }, { "tool": "create_run", "method": "POST", "path": "/api/v1/cases/{id}/runs" }, { "tool": "scan_domain", "method": "POST", "path": "/api/v1/scans" }, { "tool": "get_scan", "method": "GET", "path": "/api/v1/scans/{id}" }, { "tool": "get_stats", "method": "GET", "path": "/api/v1/stats" } ] } }