{
 "openapi": "3.1.0",
 "info": {
  "title": "Am I Ready for Agents? API",
  "version": "1.0.0",
  "summary": "Read-only API, MCP server and NLWeb endpoint over the datasets of amireadyforagents.com.",
  "description": "a self-check of 18 questions in five areas with a version for each of eight sectors; sector scorecards from one crawl of top websites (the share that allow the four main AI agents, show readable text, publish an act surface and publish a payment file, each with its counts); and ten decisions for leadership with their options and dated sources.\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://amireadyforagents.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/.",
  "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://amireadyforagents.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://amireadyforagents.com/developers"
 },
 "servers": [
  {
   "url": "https://amireadyforagents.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_sectors": {
   "get": {
    "operationId": "list_sectors",
    "tags": [
     "tools"
    ],
    "summary": "List the eight sectors",
    "description": "Lists the eight sectors the scorecards cover: sample size, the four shares (allow the four main AI agents, readable home page, any act surface, any payment file) as counts and percent, and the page URLs of each sector, with the baseline of every crawled domain. Call it first to find a sector id or slug for the other tools. 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": "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": {
             "id": {
              "type": "string"
             },
             "slug": {
              "type": "string"
             },
             "name": {
              "type": "string"
             },
             "summary": {
              "type": "string"
             },
             "sample": {
              "type": "integer"
             },
             "reachable": {
              "type": "integer"
             },
             "allow_agents": {
              "type": "object",
              "description": "Sites passing the check (n) out of the sites where it could be made (of), and the share in percent.",
              "properties": {
               "n": {
                "type": "integer"
               },
               "of": {
                "type": "integer"
               },
               "pct": {
                "type": [
                 "number",
                 "null"
                ]
               }
              },
              "required": [
               "n",
               "of",
               "pct"
              ]
             },
             "readable_text": {
              "type": "object",
              "description": "Sites passing the check (n) out of the sites where it could be made (of), and the share in percent.",
              "properties": {
               "n": {
                "type": "integer"
               },
               "of": {
                "type": "integer"
               },
               "pct": {
                "type": [
                 "number",
                 "null"
                ]
               }
              },
              "required": [
               "n",
               "of",
               "pct"
              ]
             },
             "act_surface": {
              "type": "object",
              "description": "Sites passing the check (n) out of the sites where it could be made (of), and the share in percent.",
              "properties": {
               "n": {
                "type": "integer"
               },
               "of": {
                "type": "integer"
               },
               "pct": {
                "type": [
                 "number",
                 "null"
                ]
               }
              },
              "required": [
               "n",
               "of",
               "pct"
              ]
             },
             "pay_surface": {
              "type": "object",
              "description": "Sites passing the check (n) out of the sites where it could be made (of), and the share in percent.",
              "properties": {
               "n": {
                "type": "integer"
               },
               "of": {
                "type": "integer"
               },
               "pct": {
                "type": [
                 "number",
                 "null"
                ]
               }
              },
              "required": [
               "n",
               "of",
               "pct"
              ]
             },
             "url": {
              "type": "string",
              "format": "uri"
             },
             "guide_url": {
              "type": "string",
              "format": "uri"
             },
             "self_check_url": {
              "type": "string",
              "format": "uri"
             },
             "brief_url": {
              "type": "string",
              "format": "uri"
             }
            }
           }
          },
          "total": {
           "type": "integer"
          },
          "limit": {
           "type": "integer"
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ]
          },
          "all_crawled": {
           "type": "object",
           "properties": {
            "domains": {
             "type": "integer"
            },
            "reachable": {
             "type": "integer"
            },
            "allow_agents": {
             "type": "object",
             "description": "Sites passing the check (n) out of the sites where it could be made (of), and the share in percent.",
             "properties": {
              "n": {
               "type": "integer"
              },
              "of": {
               "type": "integer"
              },
              "pct": {
               "type": [
                "number",
                "null"
               ]
              }
             },
             "required": [
              "n",
              "of",
              "pct"
             ]
            },
            "readable_text": {
             "type": "object",
             "description": "Sites passing the check (n) out of the sites where it could be made (of), and the share in percent.",
             "properties": {
              "n": {
               "type": "integer"
              },
              "of": {
               "type": "integer"
              },
              "pct": {
               "type": [
                "number",
                "null"
               ]
              }
             },
             "required": [
              "n",
              "of",
              "pct"
             ]
            },
            "act_surface": {
             "type": "object",
             "description": "Sites passing the check (n) out of the sites where it could be made (of), and the share in percent.",
             "properties": {
              "n": {
               "type": "integer"
              },
              "of": {
               "type": "integer"
              },
              "pct": {
               "type": [
                "number",
                "null"
               ]
              }
             },
             "required": [
              "n",
              "of",
              "pct"
             ]
            },
            "pay_surface": {
             "type": "object",
             "description": "Sites passing the check (n) out of the sites where it could be made (of), and the share in percent.",
             "properties": {
              "n": {
               "type": "integer"
              },
              "of": {
               "type": "integer"
              },
              "pct": {
               "type": [
                "number",
                "null"
               ]
              }
             },
             "required": [
              "n",
              "of",
              "pct"
             ]
            }
           }
          },
          "crawl": {
           "type": "object"
          },
          "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_sector_scorecard": {
   "get": {
    "operationId": "get_sector_scorecard",
    "tags": [
     "tools"
    ],
    "summary": "One sector scorecard in full",
    "description": "Returns the scorecard of one sector: sample size, how many domains came in by Ora leaderboard category and by domain keyword, and for each of the four measures its definition, the count (n out of the sites where the check could be made), the percent and the baseline of every crawled domain, with the page URLs to cite. Use it when a person asks how their own sector stands. The same tool is callable over MCP at /mcp.",
    "parameters": [
     {
      "name": "sector",
      "in": "query",
      "required": true,
      "description": "The sector slug (ecommerce, bookings, publishers, saas, services, healthcare, finance or local) or the id used in the data files, for example bookings-travel.",
      "schema": {
       "type": "string"
      },
      "example": "ecommerce"
     }
    ],
    "responses": {
     "200": {
      "description": "The result, the same object the MCP tool returns as structuredContent.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "id": {
           "type": "string"
          },
          "slug": {
           "type": "string"
          },
          "name": {
           "type": "string"
          },
          "summary": {
           "type": "string"
          },
          "sample": {
           "type": "integer"
          },
          "reachable": {
           "type": "integer"
          },
          "assigned_by_category": {
           "type": "integer"
          },
          "assigned_by_keyword": {
           "type": "integer"
          },
          "categories": {
           "type": "object",
           "additionalProperties": {
            "type": "integer"
           }
          },
          "measures": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "metric": {
              "type": "string",
              "enum": [
               "allow_agents",
               "readable_text",
               "act_surface",
               "pay_surface"
              ]
             },
             "label": {
              "type": "string"
             },
             "definition": {
              "type": "string"
             },
             "n": {
              "type": "integer"
             },
             "of": {
              "type": "integer"
             },
             "pct": {
              "type": [
               "number",
               "null"
              ]
             },
             "baseline": {
              "type": "object",
              "description": "Sites passing the check (n) out of the sites where it could be made (of), and the share in percent.",
              "properties": {
               "n": {
                "type": "integer"
               },
               "of": {
                "type": "integer"
               },
               "pct": {
                "type": [
                 "number",
                 "null"
                ]
               }
              },
              "required": [
               "n",
               "of",
               "pct"
              ]
             }
            }
           }
          },
          "crawl": {
           "type": "object"
          },
          "url": {
           "type": "string",
           "format": "uri"
          },
          "guide_url": {
           "type": "string",
           "format": "uri"
          },
          "self_check_url": {
           "type": "string",
           "format": "uri"
          },
          "brief_url": {
           "type": "string",
           "format": "uri"
          },
          "methodology_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/rank_sectors": {
   "get": {
    "operationId": "rank_sectors",
    "tags": [
     "tools"
    ],
    "summary": "Rank the sectors on one measure",
    "description": "Orders the eight sectors by one of the four measures (allow_agents, readable_text, act_surface or pay_surface), highest share first unless order is asc, with each count and the baseline of every crawled domain. Call it for questions such as which sector lets AI agents in most or publishes an act surface least. The same tool is callable over MCP at /mcp.",
    "parameters": [
     {
      "name": "metric",
      "in": "query",
      "required": true,
      "description": "allow_agents (share allowing GPTBot, ClaudeBot, PerplexityBot and Google-Extended), readable_text, act_surface or pay_surface.",
      "schema": {
       "type": "string",
       "enum": [
        "allow_agents",
        "readable_text",
        "act_surface",
        "pay_surface"
       ]
      },
      "example": "allow_agents"
     },
     {
      "name": "order",
      "in": "query",
      "required": false,
      "description": "desc puts the highest share first (default); asc the lowest.",
      "schema": {
       "type": "string",
       "enum": [
        "desc",
        "asc"
       ],
       "default": "desc"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The result, the same object the MCP tool returns as structuredContent.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "metric": {
           "type": "string",
           "enum": [
            "allow_agents",
            "readable_text",
            "act_surface",
            "pay_surface"
           ]
          },
          "label": {
           "type": "string"
          },
          "definition": {
           "type": "string"
          },
          "order": {
           "type": "string"
          },
          "items": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "rank": {
              "type": "integer"
             },
             "id": {
              "type": "string"
             },
             "slug": {
              "type": "string"
             },
             "name": {
              "type": "string"
             },
             "sample": {
              "type": "integer"
             },
             "n": {
              "type": "integer"
             },
             "of": {
              "type": "integer"
             },
             "pct": {
              "type": [
               "number",
               "null"
              ]
             },
             "url": {
              "type": "string",
              "format": "uri"
             }
            }
           }
          },
          "baseline": {
           "type": "object",
           "description": "Sites passing the check (n) out of the sites where it could be made (of), and the share in percent.",
           "properties": {
            "n": {
             "type": "integer"
            },
            "of": {
             "type": "integer"
            },
            "pct": {
             "type": [
              "number",
              "null"
             ]
            }
           },
           "required": [
            "n",
            "of",
            "pct"
           ]
          },
          "url": {
           "type": "string",
           "format": "uri"
          },
          "methodology_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_self_check": {
   "get": {
    "operationId": "get_self_check",
    "tags": [
     "tools"
    ],
    "summary": "The self-check questions",
    "description": "Returns the 18 self-check questions in the order the page shows them (find, read, act, pay, trust), each with the question, the plain reason it matters, and whether the next step is a decision for leadership or a request for the web team. Pass a sector for its examples and two extra questions, an area to keep one area, and include_sources for the dated sources behind each question. The same tool is callable over MCP at /mcp.",
    "parameters": [
     {
      "name": "sector",
      "in": "query",
      "required": false,
      "description": "Sector slug or id, for example healthcare. Adds the sector examples and its two extra questions, so the list has 20 questions.",
      "schema": {
       "type": "string"
      },
      "example": "ecommerce"
     },
     {
      "name": "area",
      "in": "query",
      "required": false,
      "description": "Keep only the questions of one area. Question numbers stay as in the full list.",
      "schema": {
       "type": "string",
       "enum": [
        "find",
        "read",
        "act",
        "pay",
        "trust"
       ]
      },
      "example": "pay"
     },
     {
      "name": "include_sources",
      "in": "query",
      "required": false,
      "description": "true adds each question's dated sources (claim, source URL, read date, kind).",
      "schema": {
       "type": "boolean",
       "default": false
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The result, the same object the MCP tool returns as structuredContent.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "sector": {
           "type": [
            "object",
            "null"
           ],
           "properties": {
            "id": {
             "type": "string"
            },
            "slug": {
             "type": "string"
            },
            "name": {
             "type": "string"
            }
           }
          },
          "total": {
           "type": "integer"
          },
          "scoring": {
           "type": "object",
           "properties": {
            "rule": {
             "type": "string"
            },
            "points": {
             "type": "object"
            },
            "url": {
             "type": "string",
             "format": "uri"
            }
           }
          },
          "areas": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "id": {
              "type": "string"
             },
             "label": {
              "type": "string"
             },
             "question": {
              "type": "string"
             }
            }
           }
          },
          "questions": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "n": {
              "type": "integer"
             },
             "id": {
              "type": "string"
             },
             "area": {
              "type": "string",
              "enum": [
               "find",
               "read",
               "act",
               "pay",
               "trust"
              ]
             },
             "question": {
              "type": "string"
             },
             "example": {
              "type": "string"
             },
             "plain_why": {
              "type": "string"
             },
             "decision_or_fix": {
              "type": "object",
              "properties": {
               "kind": {
                "type": "string",
                "enum": [
                 "decision",
                 "technical"
                ]
               },
               "text": {
                "type": "string"
               }
              }
             },
             "extra": {
              "type": "boolean"
             },
             "source_count": {
              "type": "integer"
             },
             "sources": {
              "type": "array",
              "items": {
               "type": "object",
               "properties": {
                "claim": {
                 "type": "string"
                },
                "source_url": {
                 "type": "string",
                 "format": "uri"
                },
                "read_date": {
                 "type": "string"
                },
                "kind": {
                 "type": "string",
                 "enum": [
                  "primary",
                  "secondary",
                  "vendor_claim"
                 ]
                },
                "fact_date": {
                 "type": "string"
                }
               }
              }
             },
             "url": {
              "type": "string",
              "format": "uri"
             }
            }
           }
          },
          "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_definitions": {
   "get": {
    "operationId": "get_definitions",
    "tags": [
     "tools"
    ],
    "summary": "What each measure counts and the crawl behind it",
    "description": "Returns what each of the four scorecard measures counts, the whole-crawl figure for each, and the crawl behind them: domains crawled and reachable, how many sit in a sector row and how many in none, the status of the edition and the page that gives every rule. Call it before quoting a share, so the denominator is stated correctly. 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": {
          "measures": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "metric": {
              "type": "string",
              "enum": [
               "allow_agents",
               "readable_text",
               "act_surface",
               "pay_surface"
              ]
             },
             "label": {
              "type": "string"
             },
             "definition": {
              "type": "string"
             },
             "n": {
              "type": "integer"
             },
             "of": {
              "type": "integer"
             },
             "pct": {
              "type": [
               "number",
               "null"
              ]
             },
             "baseline": {
              "type": "object",
              "description": "Sites passing the check (n) out of the sites where it could be made (of), and the share in percent.",
              "properties": {
               "n": {
                "type": "integer"
               },
               "of": {
                "type": "integer"
               },
               "pct": {
                "type": [
                 "number",
                 "null"
                ]
               }
              },
              "required": [
               "n",
               "of",
               "pct"
              ]
             }
            }
           }
          },
          "crawl": {
           "type": "object",
           "properties": {
            "domains_in_crawl": {
             "type": "integer"
            },
            "reachable": {
             "type": "integer"
            },
            "status": {
             "type": "string"
            },
            "tranco_list": {
             "type": "string",
             "format": "uri"
            },
            "domains_in_a_sector": {
             "type": "integer"
            },
            "domains_in_no_sector": {
             "type": "integer"
            },
            "assigned_by_category": {
             "type": "integer"
            },
            "assigned_by_keyword": {
             "type": "integer"
            }
           }
          },
          "url": {
           "type": "string",
           "format": "uri"
          },
          "methodology_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/scorecards-2026-11-04.json": {
   "get": {
    "operationId": "download_scorecards_2026_11_04_json",
    "tags": [
     "downloads"
    ],
    "summary": "Sector scorecards (json)",
    "description": "Eight sectors with the sample size and the four shares as counts and percentages, the definitions and the baseline of every crawled domain. 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/scorecards-2026-11-04.csv": {
   "get": {
    "operationId": "download_scorecards_2026_11_04_csv",
    "tags": [
     "downloads"
    ],
    "summary": "Sector scorecards (csv)",
    "description": "Eight sectors with the sample size and the four shares as counts and percentages, the definitions and the baseline of every crawled domain. Whole-file download; the tools above answer questions over the same rows.",
    "responses": {
     "200": {
      "description": "The file.",
      "content": {
       "text/csv": {
        "schema": {
         "type": "string"
        }
       }
      }
     }
    }
   }
  },
  "/data/sectors-2026-11-04.json": {
   "get": {
    "operationId": "download_sectors_2026_11_04_json",
    "tags": [
     "downloads"
    ],
    "summary": "Sector index (json)",
    "description": "The eight sectors with the id used in the scorecard file, the slug used in page paths and the four page URLs of each. 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/self-check-2026-11-04.json": {
   "get": {
    "operationId": "download_self_check_2026_11_04_json",
    "tags": [
     "downloads"
    ],
    "summary": "Self-check questions (json)",
    "description": "The 18 core questions with the plain reason and the decision or fix behind each, the scoring rule, and the examples and two extra questions of each sector version. 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/decisions-2026-11-04.json": {
   "get": {
    "operationId": "download_decisions_2026_11_04_json",
    "tags": [
     "downloads"
    ],
    "summary": "Ten decisions (json)",
    "description": "The ten decisions that sit with leadership, each with its options, their consequences and the dated sources. 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"
       }
      }
     }
    }
   }
  }
 }
}