{
 "openapi": "3.1.0",
 "info": {
  "title": "Agent Readiness Compare API",
  "version": "1.1.0",
  "summary": "Read-only API, MCP server and NLWeb endpoint over the datasets of agentreadinesscompare.com.",
  "description": "the Scanner Concordance (the same 60 domains looked up in six public agent readiness scanners on 2026-11-04, with the reason for every empty cell), the scanner rubric (the ten-criterion rubric of 2026-11-05 that ranks ten scanners out of 100, with a basis and a source URL for every point; the seven-criterion reading of 2026-11-04 is kept as a superseded edition) and the Standards Map (16 standards and the scanners that check each).\n\nAccess: every endpoint is public and read-only; there is no API key, no OAuth and no scope, because nothing here can be written or belongs to a user. Rate limit: 120 requests a minute per client address, announced in RateLimit and RateLimit-Policy headers; a 429 carries Retry-After. Errors are JSON ({\"error\":{\"code\",\"message\",\"hint\",\"status\",\"docs\"}}), never HTML. Versioning: the path prefix /api/v1 is the contract; a breaking change ships under /api/v2 with the old prefix kept for at least 180 days and announced on https://agentreadinesscompare.com/developers/ and in this document's info.version. Additive changes (new fields, new tools) do not change the prefix. Idempotency: every operation is a read, so retries are safe and no idempotency key exists. Long-running operations: none; every call answers in one response. Data edition: 2026-11-04; the same rows are downloadable whole from /data/.",
  "license": {
   "name": "CC BY 4.0",
   "url": "https://creativecommons.org/licenses/by/4.0/"
  },
  "x-authentication": "none",
  "x-rate-limit": {
   "requests": 120,
   "window_seconds": 60,
   "headers": [
    "RateLimit",
    "RateLimit-Policy",
    "Retry-After"
   ]
  },
  "x-versioning-policy": {
   "current": "v1",
   "breaking_changes": "new path prefix, old prefix kept for 180 days",
   "announcements": "https://agentreadinesscompare.com/developers/"
  },
  "x-idempotency": "all operations are reads; retries are safe",
  "x-dataset-edition": "2026-11-04"
 },
 "externalDocs": {
  "description": "API and MCP server documentation",
  "url": "https://agentreadinesscompare.com/developers/"
 },
 "servers": [
  {
   "url": "https://agentreadinesscompare.com",
   "description": "The site"
  }
 ],
 "tags": [
  {
   "name": "tools",
   "description": "One GET endpoint per MCP tool."
  },
  {
   "name": "nlweb",
   "description": "NLWeb 0.55 ask endpoint."
  },
  {
   "name": "downloads",
   "description": "Whole-dataset files."
  },
  {
   "name": "index"
  }
 ],
 "security": [],
 "paths": {
  "/api": {
   "get": {
    "operationId": "getApiIndex",
    "tags": [
     "index"
    ],
    "summary": "API index",
    "description": "Links to every endpoint, dataset download, the OpenAPI document, the MCP server and the NLWeb endpoint, plus the rate limit and the versioning policy.",
    "responses": {
     "200": {
      "description": "The index.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/ApiIndex"
        }
       }
      }
     },
     "429": {
      "description": "More than the published rate limit; Retry-After says when to try again.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/list_scanners": {
   "get": {
    "operationId": "list_scanners",
    "tags": [
     "tools"
    ],
    "summary": "List the six scanners",
    "description": "Lists the six agent readiness scanners in the Concordance with their ids: how many of the 60 domains each scored, score range and median, why cells are empty, the total of 100 and rank on the ten-criterion rubric that ranks the scanners, access notes, the standards each checks and the profile URL. Call it first to get scanner ids for the other tools. The same tool is callable over MCP at /mcp.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "The result, the same object the MCP tool returns as structuredContent.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "items": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "id": {
              "type": "string"
             },
             "name": {
              "type": "string"
             },
             "scored": {
              "type": "integer"
             },
             "of": {
              "type": "integer"
             },
             "score_range": {
              "type": [
               "object",
               "null"
              ],
              "properties": {
               "min": {
                "type": "number"
               },
               "median": {
                "type": "number"
               },
               "max": {
                "type": "number"
               }
              }
             },
             "empty_cells": {
              "type": "array",
              "items": {
               "type": "object",
               "properties": {
                "reason": {
                 "type": "string"
                },
                "count": {
                 "type": "integer"
                }
               }
              }
             },
             "rubric": {
              "type": "object",
              "properties": {
               "total": {
                "type": "integer"
               },
               "of": {
                "type": "integer"
               },
               "rank": {
                "type": "integer"
               },
               "tied": {
                "type": "boolean"
               },
               "edition": {
                "type": "string"
               }
              }
             },
             "access": {
              "type": "object",
              "properties": {
               "value": {
                "type": [
                 "integer",
                 "string"
                ]
               },
               "evidence": {
                "type": "string"
               },
               "source_url": {
                "type": "string",
                "format": "uri"
               },
               "read_date": {
                "type": "string"
               }
              }
             },
             "standards_checked": {
              "type": "array",
              "items": {
               "type": "object",
               "properties": {
                "id": {
                 "type": "string"
                },
                "name": {
                 "type": "string"
                },
                "url": {
                 "type": "string",
                 "format": "uri"
                }
               }
              }
             },
             "url": {
              "type": "string",
              "format": "uri"
             }
            }
           }
          },
          "total": {
           "type": "integer"
          },
          "scale": {
           "type": "string"
          },
          "url": {
           "type": "string",
           "format": "uri"
          },
          "dataset_url": {
           "type": "string",
           "format": "uri"
          },
          "edition": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "A parameter is missing or has the wrong type; error.hint lists the parameters.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "No such endpoint or record.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "More than the published rate limit; Retry-After says when to try again.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "500": {
      "description": "Internal error; the datasets could not be read.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/get_domain_scores": {
   "get": {
    "operationId": "get_domain_scores",
    "tags": [
     "tools"
    ],
    "summary": "One domain across the six scanners",
    "description": "Returns one domain's cell from each of the six scanners: score, the scanner's own band, the reason when it gave none, the time it was read, the source URL, and which scanners differ by 25 points or more. Use it to answer how scanners rated one site. Only the 60 Concordance domains exist. The same tool is callable over MCP at /mcp.",
    "parameters": [
     {
      "name": "domain",
      "in": "query",
      "required": true,
      "description": "A domain from the Concordance, for example netlify.com. A leading https:// or www. is ignored.",
      "schema": {
       "type": "string"
      },
      "example": "netlify.com"
     }
    ],
    "responses": {
     "200": {
      "description": "The result, the same object the MCP tool returns as structuredContent.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "domain": {
           "type": "string"
          },
          "category": {
           "type": "string"
          },
          "stratum": {
           "type": "string",
           "enum": [
            "ora-leaderboard",
            "tranco-business"
           ]
          },
          "spread": {
           "type": [
            "integer",
            "null"
           ]
          },
          "disagreeing_scanners": {
           "type": "array",
           "items": {
            "type": "string"
           }
          },
          "scores": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "scanner": {
              "type": "string"
             },
             "name": {
              "type": "string"
             },
             "score": {
              "type": [
               "integer",
               "null"
              ]
             },
             "band": {
              "type": [
               "string",
               "null"
              ]
             },
             "reason": {
              "type": [
               "string",
               "null"
              ]
             },
             "fetched_at": {
              "type": "string"
             },
             "source_url": {
              "type": "string",
              "format": "uri"
             },
             "read_date": {
              "type": "string"
             }
            }
           }
          },
          "url": {
           "type": "string",
           "format": "uri"
          },
          "dataset_url": {
           "type": "string",
           "format": "uri"
          },
          "edition": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "A parameter is missing or has the wrong type; error.hint lists the parameters.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "No such endpoint or record.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "More than the published rate limit; Retry-After says when to try again.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "500": {
      "description": "Internal error; the datasets could not be read.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/list_concordance": {
   "get": {
    "operationId": "list_concordance",
    "tags": [
     "tools"
    ],
    "summary": "List and filter the Concordance",
    "description": "Lists Concordance rows, one per domain, with category, stratum, spread and each scanner's score. Filter by category, stratum, words in the domain, or one scanner and a score range; with a scanner the rows are sorted by its score, highest first. Call it to find domains before get_domain_scores. Paginated: pass limit (1 to 100) and the next_cursor of the previous page as cursor. The same tool is callable over MCP at /mcp.",
    "parameters": [
     {
      "name": "category",
      "in": "query",
      "required": false,
      "description": "Part of a category name, case-insensitive: Infrastructure, Agent Tools, Developer Tools, E-commerce, Consumer, Travel, or Tranco business.",
      "schema": {
       "type": "string"
      },
      "example": "Developer Tools"
     },
     {
      "name": "stratum",
      "in": "query",
      "required": false,
      "description": "ora-leaderboard (50 domains) or tranco-business (10 domains).",
      "schema": {
       "type": "string",
       "enum": [
        "ora-leaderboard",
        "tranco-business"
       ]
      }
     },
     {
      "name": "scanner",
      "in": "query",
      "required": false,
      "description": "A scanner id such as ora or isitagentready; keeps only the domains this scanner scored and sorts them by its score.",
      "schema": {
       "type": "string"
      },
      "example": "ora"
     },
     {
      "name": "min_score",
      "in": "query",
      "required": false,
      "description": "Lowest score to keep, on the named scanner's own 0 to 100 scale. Needs scanner.",
      "schema": {
       "type": "integer",
       "minimum": 0,
       "maximum": 100
      }
     },
     {
      "name": "max_score",
      "in": "query",
      "required": false,
      "description": "Highest score to keep. Needs scanner.",
      "schema": {
       "type": "integer",
       "minimum": 0,
       "maximum": 100
      }
     },
     {
      "name": "q",
      "in": "query",
      "required": false,
      "description": "Words to look for in the domain, for example ai or shop.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "required": false,
      "description": "Page size, 1 to 100 (default 20).",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 100,
       "default": 20
      }
     },
     {
      "name": "cursor",
      "in": "query",
      "required": false,
      "description": "Opaque cursor from next_cursor of the previous page.",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The result, the same object the MCP tool returns as structuredContent.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "items": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "domain": {
              "type": "string"
             },
             "category": {
              "type": "string"
             },
             "stratum": {
              "type": "string"
             },
             "spread": {
              "type": [
               "integer",
               "null"
              ]
             },
             "scores": {
              "type": "object",
              "additionalProperties": {
               "type": [
                "integer",
                "null"
               ]
              }
             },
             "url": {
              "type": "string",
              "format": "uri"
             }
            }
           }
          },
          "total": {
           "type": "integer"
          },
          "limit": {
           "type": "integer"
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ]
          },
          "scanners": {
           "type": "array",
           "items": {
            "type": "string"
           }
          },
          "edition": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "A parameter is missing or has the wrong type; error.hint lists the parameters.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "No such endpoint or record.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "More than the published rate limit; Retry-After says when to try again.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "500": {
      "description": "Internal error; the datasets could not be read.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/compare_scanners": {
   "get": {
    "operationId": "compare_scanners",
    "tags": [
     "tools"
    ],
    "summary": "Compare two scanners",
    "description": "Compares two scanners on the domains both scored: how many, the Spearman rank correlation computed from the rows (only from 15 shared domains), the mean gap, and the widest score gaps by domain. Use it to ask whether two scanners rank sites alike and where they split. Get ids from list_scanners. The same tool is callable over MCP at /mcp.",
    "parameters": [
     {
      "name": "a",
      "in": "query",
      "required": true,
      "description": "First scanner id, for example ora.",
      "schema": {
       "type": "string"
      },
      "example": "ora"
     },
     {
      "name": "b",
      "in": "query",
      "required": true,
      "description": "Second scanner id, for example isitagentready.",
      "schema": {
       "type": "string"
      },
      "example": "isitagentready"
     }
    ],
    "responses": {
     "200": {
      "description": "The result, the same object the MCP tool returns as structuredContent.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "a": {
           "type": "object",
           "properties": {
            "id": {
             "type": "string"
            },
            "name": {
             "type": "string"
            },
            "scored": {
             "type": "integer"
            }
           }
          },
          "b": {
           "type": "object",
           "properties": {
            "id": {
             "type": "string"
            },
            "name": {
             "type": "string"
            },
            "scored": {
             "type": "integer"
            }
           }
          },
          "shared_domains": {
           "type": "integer"
          },
          "rank_correlation": {
           "type": "object",
           "properties": {
            "method": {
             "type": "string"
            },
            "rho": {
             "type": [
              "number",
              "null"
             ]
            },
            "n": {
             "type": "integer"
            },
            "minimum_shared_domains": {
             "type": "integer"
            }
           }
          },
          "mean_gap": {
           "type": [
            "number",
            "null"
           ],
           "description": "Mean of a minus b over the shared domains."
          },
          "gaps_of_25_points_or_more": {
           "type": "integer"
          },
          "widest_gaps": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "domain": {
              "type": "string"
             },
             "a_score": {
              "type": "integer"
             },
             "b_score": {
              "type": "integer"
             },
             "gap": {
              "type": "integer"
             },
             "url": {
              "type": "string",
              "format": "uri"
             }
            }
           }
          },
          "independent": {
           "type": "boolean"
          },
          "note": {
           "type": [
            "string",
            "null"
           ]
          },
          "url": {
           "type": "string",
           "format": "uri"
          },
          "dataset_url": {
           "type": "string",
           "format": "uri"
          },
          "edition": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "A parameter is missing or has the wrong type; error.hint lists the parameters.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "No such endpoint or record.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "More than the published rate limit; Retry-After says when to try again.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "500": {
      "description": "Internal error; the datasets could not be read.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/get_rubric": {
   "get": {
    "operationId": "get_rubric",
    "tags": [
     "tools"
    ],
    "summary": "The scanner rubric with evidence",
    "description": "Returns the rubric that ranks the scanners: ten criteria worth 100 points, and for each of the ten scanners the points on every part with its basis and source URL, the total and rank, plus the rule that scores the citation part of the standards criterion (version 1.2). Filter to one scanner or one criterion. Set rubric_edition to 2026-11-04 for the earlier seven-criterion reading, which is superseded and labelled so. Use it to explain why a scanner ranks where it does. The same tool is callable over MCP at /mcp.",
    "parameters": [
     {
      "name": "scanner",
      "in": "query",
      "required": false,
      "description": "Optional scanner id, for example mintlify or startuphub-agent-readiness (the current rubric ranks ten scanners, six of them in the Concordance).",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "criterion",
      "in": "query",
      "required": false,
      "description": "Optional criterion id, for example standards. The current ids are journey, depth, agents, transparency, standards, integration, benchmark, fixes, repeatability and access.",
      "schema": {
       "type": "string",
       "enum": [
        "journey",
        "depth",
        "agents",
        "transparency",
        "standards",
        "integration",
        "benchmark",
        "fixes",
        "repeatability",
        "access",
        "coverage",
        "reproducibility",
        "remediation",
        "independence",
        "freshness"
       ]
      },
      "example": "standards"
     },
     {
      "name": "rubric_edition",
      "in": "query",
      "required": false,
      "description": "Optional. 2026-11-05 (the default) is the ten-criterion rubric that ranks the scanners; 2026-11-04 is the superseded seven-criterion reading.",
      "schema": {
       "type": "string",
       "enum": [
        "2026-11-05",
        "2026-11-04"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The result, the same object the MCP tool returns as structuredContent.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string",
           "enum": [
            "current",
            "superseded"
           ]
          },
          "rubric_edition": {
           "type": "string"
          },
          "version": {
           "type": "string"
          },
          "note": {
           "type": [
            "string",
            "null"
           ]
          },
          "max_total": {
           "type": "integer"
          },
          "rule": {
           "type": "string"
          },
          "citation_rule": {
           "type": [
            "string",
            "null"
           ]
          },
          "criteria": {
           "type": "array",
           "items": {
            "type": "object"
           }
          },
          "scanners": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "id": {
              "type": "string"
             },
             "name": {
              "type": "string"
             },
             "rank": {
              "type": "integer"
             },
             "tied": {
              "type": "boolean"
             },
             "total": {
              "type": "integer"
             },
             "of": {
              "type": "integer"
             },
             "url": {
              "type": "string",
              "format": "uri"
             },
             "by_criterion": {
              "type": "object",
              "additionalProperties": {
               "type": "integer"
              }
             },
             "cells": {
              "type": "array",
              "items": {
               "type": "object",
               "properties": {
                "criterion": {
                 "type": "string"
                },
                "part": {
                 "type": "string"
                },
                "points": {
                 "type": "integer"
                },
                "cap": {
                 "type": "integer"
                },
                "basis": {
                 "type": "string"
                },
                "source_url": {
                 "type": [
                  "string",
                  "null"
                 ]
                },
                "source_urls": {
                 "type": "array",
                 "items": {
                  "type": "string",
                  "format": "uri"
                 }
                }
               }
              }
             },
             "criteria": {
              "type": "object",
              "additionalProperties": {
               "type": "object",
               "properties": {
                "value": {
                 "type": [
                  "integer",
                  "string"
                 ]
                },
                "evidence": {
                 "type": "string"
                },
                "source_url": {
                 "type": "string",
                 "format": "uri"
                },
                "read_date": {
                 "type": "string"
                }
               }
              }
             }
            }
           }
          },
          "scale": {
           "type": [
            "string",
            "null"
           ]
          },
          "cite": {
           "type": "string"
          },
          "url": {
           "type": "string",
           "format": "uri"
          },
          "dataset_url": {
           "type": "string",
           "format": "uri"
          },
          "edition": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "A parameter is missing or has the wrong type; error.hint lists the parameters.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "No such endpoint or record.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "More than the published rate limit; Retry-After says when to try again.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "500": {
      "description": "Internal error; the datasets could not be read.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/ask": {
   "get": {
    "operationId": "askGet",
    "tags": [
     "nlweb"
    ],
    "summary": "Ask (NLWeb, GET)",
    "description": "NLWeb 0.55. Searches the site's records and pages for the question and returns schema.org objects, each with a source URL. Add streaming=true (or Accept: text/event-stream) for server-sent events start, result, error and complete.",
    "parameters": [
     {
      "name": "query",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "maxLength": 500
      },
      "description": "The question or search text."
     },
     {
      "name": "site",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Ignored unless it names this site; present for NLWeb compatibility."
     },
     {
      "name": "mode",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "list",
        "summarize"
       ]
      },
      "description": "list (default) or summarize, which adds a SearchSummary item."
     },
     {
      "name": "streaming",
      "in": "query",
      "required": false,
      "schema": {
       "type": "boolean"
      },
      "description": "true for text/event-stream."
     },
     {
      "name": "response_format",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "conversational_search",
        "chatgpt_app"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "An NLWeb answer, or a failure with code NO_RESULTS.",
      "content": {
       "application/json": {
        "schema": {
         "oneOf": [
          {
           "$ref": "#/components/schemas/AskAnswer"
          },
          {
           "$ref": "#/components/schemas/AskFailure"
          }
         ]
        }
       },
       "text/event-stream": {
        "schema": {
         "type": "string",
         "description": "Events start, result (one per item), error, complete; each data line is JSON."
        }
       }
      }
     },
     "400": {
      "description": "INVALID_QUERY, UNSUPPORTED_MODE or UNSUPPORTED_FORMAT.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/AskFailure"
        }
       }
      }
     },
     "429": {
      "description": "More than the published rate limit; Retry-After says when to try again.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   },
   "post": {
    "operationId": "askPost",
    "tags": [
     "nlweb"
    ],
    "summary": "Ask (NLWeb, POST)",
    "description": "NLWeb 0.55 request object: query.text (required), query.site, prefer.streaming, prefer.mode, prefer.response_format, meta.version. The context object is accepted and ignored: answers come from the site's data, not from a model.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/AskRequest"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "An NLWeb answer, or a failure with code NO_RESULTS.",
      "content": {
       "application/json": {
        "schema": {
         "oneOf": [
          {
           "$ref": "#/components/schemas/AskAnswer"
          },
          {
           "$ref": "#/components/schemas/AskFailure"
          }
         ]
        }
       },
       "text/event-stream": {
        "schema": {
         "type": "string"
        }
       }
      }
     },
     "400": {
      "description": "INVALID_QUERY, UNSUPPORTED_MODE or UNSUPPORTED_FORMAT.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/AskFailure"
        }
       }
      }
     },
     "429": {
      "description": "More than the published rate limit; Retry-After says when to try again.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/data/concordance-2026-11-04.json": {
   "get": {
    "operationId": "download_concordance_2026_11_04_json",
    "tags": [
     "downloads"
    ],
    "summary": "Scanner Concordance (json)",
    "description": "Sixty domains by six scanners: score, band, reason for an empty cell, fetch time, source URL and read date per cell, plus the spread per row. Whole-file download; the tools above answer questions over the same rows.",
    "responses": {
     "200": {
      "description": "The file.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "additionalProperties": true
        }
       }
      }
     }
    }
   }
  },
  "/data/concordance-2026-11-04.csv": {
   "get": {
    "operationId": "download_concordance_2026_11_04_csv",
    "tags": [
     "downloads"
    ],
    "summary": "Scanner Concordance (csv)",
    "description": "Sixty domains by six scanners: score, band, reason for an empty cell, fetch time, source URL and read date per cell, plus the spread per row. Whole-file download; the tools above answer questions over the same rows.",
    "responses": {
     "200": {
      "description": "The file.",
      "content": {
       "text/csv": {
        "schema": {
         "type": "string"
        }
       }
      }
     }
    }
   }
  },
  "/data/scanner-rubric-2026-11-05.json": {
   "get": {
    "operationId": "download_scanner_rubric_2026_11_05_json",
    "tags": [
     "downloads"
    ],
    "summary": "Scanner rubric, ten criteria (the rubric that ranks the scanners) (json)",
    "description": "The ten criteria worth 100 points and, per scanner, the points on each part with its basis and source URL, the total and rank, the 5 November re-read log and the version 1.2 citation rule. Whole-file download; the tools above answer questions over the same rows.",
    "responses": {
     "200": {
      "description": "The file.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "additionalProperties": true
        }
       }
      }
     }
    }
   }
  },
  "/data/scanner-ranking-2026-11-05.csv": {
   "get": {
    "operationId": "download_scanner_ranking_2026_11_05_csv",
    "tags": [
     "downloads"
    ],
    "summary": "Scanner rubric, ten criteria (the rubric that ranks the scanners) (csv)",
    "description": "The ten criteria worth 100 points and, per scanner, the points on each part with its basis and source URL, the total and rank, the 5 November re-read log and the version 1.2 citation rule. Whole-file download; the tools above answer questions over the same rows.",
    "responses": {
     "200": {
      "description": "The file.",
      "content": {
       "text/csv": {
        "schema": {
         "type": "string"
        }
       }
      }
     }
    }
   }
  },
  "/data/scanner-rubric-cells-2026-11-05.csv": {
   "get": {
    "operationId": "download_scanner_rubric_cells_2026_11_05_csv",
    "tags": [
     "downloads"
    ],
    "summary": "Scanner rubric, ten criteria (the rubric that ranks the scanners) (csv)",
    "description": "The ten criteria worth 100 points and, per scanner, the points on each part with its basis and source URL, the total and rank, the 5 November re-read log and the version 1.2 citation rule. Whole-file download; the tools above answer questions over the same rows.",
    "responses": {
     "200": {
      "description": "The file.",
      "content": {
       "text/csv": {
        "schema": {
         "type": "string"
        }
       }
      }
     }
    }
   }
  },
  "/data/rubric-2026-11-04.json": {
   "get": {
    "operationId": "download_rubric_2026_11_04_json",
    "tags": [
     "downloads"
    ],
    "summary": "Scanner rubric, seven criteria of 4 November (superseded) (json)",
    "description": "Superseded for the ranking by the ten-criterion rubric. The seven criteria and, per scanner, the score or result, the evidence, the source URL and the read date, with a total of 25 and rank. Whole-file download; the tools above answer questions over the same rows.",
    "responses": {
     "200": {
      "description": "The file.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "additionalProperties": true
        }
       }
      }
     }
    }
   }
  },
  "/data/rubric-2026-11-04.csv": {
   "get": {
    "operationId": "download_rubric_2026_11_04_csv",
    "tags": [
     "downloads"
    ],
    "summary": "Scanner rubric, seven criteria of 4 November (superseded) (csv)",
    "description": "Superseded for the ranking by the ten-criterion rubric. The seven criteria and, per scanner, the score or result, the evidence, the source URL and the read date, with a total of 25 and rank. Whole-file download; the tools above answer questions over the same rows.",
    "responses": {
     "200": {
      "description": "The file.",
      "content": {
       "text/csv": {
        "schema": {
         "type": "string"
        }
       }
      }
     }
    }
   }
  },
  "/data/standards-2026-11-04.json": {
   "get": {
    "operationId": "download_standards_2026_11_04_json",
    "tags": [
     "downloads"
    ],
    "summary": "Standards Map (json)",
    "description": "The 16 standards: maintainer, layer, what each is and does not do, the scanners that check it, the AgentReady identifiers and the source. Whole-file download; the tools above answer questions over the same rows.",
    "responses": {
     "200": {
      "description": "The file.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "additionalProperties": true
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "securitySchemes": {},
  "schemas": {
   "Error": {
    "type": "object",
    "required": [
     "error"
    ],
    "properties": {
     "error": {
      "type": "object",
      "required": [
       "code",
       "message",
       "status"
      ],
      "properties": {
       "code": {
        "type": "string",
        "enum": [
         "invalid_params",
         "not_found",
         "method_not_allowed",
         "unsupported_media_type",
         "rate_limited",
         "internal"
        ]
       },
       "message": {
        "type": "string"
       },
       "hint": {
        "type": "string"
       },
       "status": {
        "type": "integer"
       },
       "docs": {
        "type": "string",
        "format": "uri"
       },
       "openapi": {
        "type": "string",
        "format": "uri"
       }
      }
     }
    }
   },
   "ApiIndex": {
    "type": "object",
    "properties": {
     "name": {
      "type": "string"
     },
     "version": {
      "type": "string"
     },
     "edition": {
      "type": "string"
     },
     "documentation": {
      "type": "string",
      "format": "uri"
     },
     "openapi": {
      "type": "string",
      "format": "uri"
     },
     "endpoints": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "path": {
         "type": "string"
        },
        "method": {
         "type": "string"
        },
        "summary": {
         "type": "string"
        }
       }
      }
     },
     "datasets": {
      "type": "array",
      "items": {
       "type": "object"
      }
     },
     "mcp": {
      "type": "object"
     },
     "ask": {
      "type": "object"
     },
     "rate_limit": {
      "type": "object"
     },
     "versioning": {
      "type": "object"
     }
    }
   },
   "AskRequest": {
    "type": "object",
    "required": [
     "query"
    ],
    "properties": {
     "query": {
      "type": "object",
      "required": [
       "text"
      ],
      "properties": {
       "text": {
        "type": "string",
        "maxLength": 500
       },
       "site": {
        "type": "string"
       }
      }
     },
     "context": {
      "type": "object",
      "additionalProperties": true
     },
     "prefer": {
      "type": "object",
      "properties": {
       "streaming": {
        "type": "boolean"
       },
       "mode": {
        "type": "string",
        "description": "list, summarize, or both comma-separated"
       },
       "response_format": {
        "type": "string",
        "enum": [
         "conversational_search",
         "chatgpt_app"
        ]
       }
      }
     },
     "meta": {
      "type": "object",
      "properties": {
       "version": {
        "type": "string"
       },
       "query_id": {
        "type": "string"
       }
      }
     }
    }
   },
   "AskMeta": {
    "type": "object",
    "required": [
     "response_type",
     "version"
    ],
    "properties": {
     "response_type": {
      "type": "string",
      "enum": [
       "answer",
       "failure"
      ]
     },
     "response_format": {
      "type": "string"
     },
     "version": {
      "type": "string"
     },
     "site": {
      "type": "string"
     },
     "edition": {
      "type": "string"
     },
     "query_id": {
      "type": "string"
     }
    }
   },
   "AskResult": {
    "type": "object",
    "required": [
     "@type",
     "name",
     "url"
    ],
    "properties": {
     "@type": {
      "type": "string"
     },
     "name": {
      "type": "string"
     },
     "url": {
      "type": "string",
      "format": "uri"
     },
     "description": {
      "type": "string"
     },
     "score": {
      "type": "number"
     },
     "grounding": {
      "type": "object",
      "properties": {
       "source": {
        "type": "string",
        "format": "uri"
       },
       "dataset": {
        "type": "string"
       },
       "edition": {
        "type": "string"
       },
       "publisher": {
        "type": "string"
       }
      }
     }
    },
    "additionalProperties": true
   },
   "AskAnswer": {
    "type": "object",
    "required": [
     "_meta"
    ],
    "properties": {
     "_meta": {
      "$ref": "#/components/schemas/AskMeta"
     },
     "results": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/AskResult"
      }
     },
     "content": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "type": {
         "type": "string"
        },
        "text": {
         "type": "string"
        }
       }
      }
     },
     "structuredData": {
      "type": "array",
      "items": {
       "$ref": "#/components/schemas/AskResult"
      }
     }
    }
   },
   "AskFailure": {
    "type": "object",
    "required": [
     "_meta",
     "failure"
    ],
    "properties": {
     "_meta": {
      "$ref": "#/components/schemas/AskMeta"
     },
     "failure": {
      "type": "object",
      "required": [
       "code"
      ],
      "properties": {
       "code": {
        "type": "string",
        "enum": [
         "NO_RESULTS",
         "INVALID_QUERY",
         "UNSUPPORTED_FORMAT",
         "UNSUPPORTED_MODE",
         "RATE_LIMITED",
         "INTERNAL_ERROR"
        ]
       },
       "message": {
        "type": "string"
       }
      }
     }
    }
   }
  }
 }
}
