{
 "openapi": "3.1.0",
 "info": {
  "title": "Agent MCP Directory API",
  "version": "1.0.0",
  "summary": "Read-only API, MCP server and NLWeb endpoint over the datasets of agentmcpdirectory.com.",
  "description": "the directory of 1,336 companies checked for a public MCP server, a CLI and an OpenAPI file by a read-only connector on 4 November 2026, and the Act Layer Census of how many of the top 10,000 sites publish MCP, A2A, OpenAPI and OAuth discovery files. A company has an MCP server in this directory only when the connector listed its tools; a sign-in challenge is its own state and is not counted.\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://agentmcpdirectory-preview.vercel.app/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://agentmcpdirectory-preview.vercel.app/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://agentmcpdirectory-preview.vercel.app/developers/"
 },
 "servers": [
  {
   "url": "https://agentmcpdirectory-preview.vercel.app",
   "description": "The host that serves this surface today; page and dataset URLs in the answers stay on https://agentmcpdirectory.com"
  }
 ],
 "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/search_directory": {
   "get": {
    "operationId": "search_directory",
    "tags": [
     "tools"
    ],
    "summary": "Search the directory",
    "description": "Lists directory companies (name, domain, category, MCP status, auth type, transport, tool count, whether a CLI is on record, entry page URL). Filter by words in the company name, registry title or domain, by category, status, auth type, transport or CLI. Call it to find a domain before get_company. 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": "q",
      "in": "query",
      "required": false,
      "description": "Words to look for in the company name, registry title or domain, for example \"stripe\" or \"pay\".",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "category",
      "in": "query",
      "required": false,
      "description": "A category name or its slug, for example \"Payments & Fintech\" or \"developer-tools\". list_categories gives them all.",
      "schema": {
       "type": "string"
      },
      "example": "Payments & Fintech"
     },
     {
      "name": "mcp_status",
      "in": "query",
      "required": false,
      "description": "verified is the only counted state (tools listed); sign-in is a sign-in challenge, tools not seen, not counted; none-found means no endpoint is on record.",
      "schema": {
       "type": "string",
       "enum": [
        "verified",
        "sign-in",
        "credential-wall",
        "no-answer",
        "no-tools",
        "none-found"
       ]
      },
      "example": "verified"
     },
     {
      "name": "auth_type",
      "in": "query",
      "required": false,
      "description": "none, api-key, oauth-dcr (OAuth with client registration), oauth (OAuth without) or unknown. Rows with no endpoint, and rows whose endpoint did not answer, have no auth type, as on the directory page.",
      "schema": {
       "type": "string",
       "enum": [
        "none",
        "api-key",
        "oauth-dcr",
        "oauth",
        "unknown"
       ]
      }
     },
     {
      "name": "transport",
      "in": "query",
      "required": false,
      "description": "The transport the connector observed.",
      "schema": {
       "type": "string",
       "enum": [
        "streamable-http",
        "sse"
       ]
      }
     },
     {
      "name": "has_cli",
      "in": "query",
      "required": false,
      "description": "true for companies with a CLI package on record, false for those without. The CLI column is a floor: a package is checked only where a source names one.",
      "schema": {
       "type": "boolean"
      }
     },
     {
      "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": {
             "company": {
              "type": "string"
             },
             "domain": {
              "type": "string"
             },
             "category": {
              "type": "string"
             },
             "mcp_status": {
              "type": "string",
              "enum": [
               "verified",
               "sign-in",
               "credential-wall",
               "no-answer",
               "no-tools",
               "none-found"
              ]
             },
             "has_mcp": {
              "type": "boolean"
             },
             "auth_type": {
              "type": [
               "string",
               "null"
              ]
             },
             "transport": {
              "type": [
               "string",
               "null"
              ]
             },
             "tool_count": {
              "type": [
               "integer",
               "null"
              ]
             },
             "has_cli": {
              "type": "boolean"
             },
             "url": {
              "type": "string",
              "format": "uri"
             }
            }
           }
          },
          "total": {
           "type": "integer"
          },
          "limit": {
           "type": "integer"
          },
          "next_cursor": {
           "type": [
            "string",
            "null"
           ]
          },
          "edition": {
           "type": "string"
          },
          "dataset": {
           "type": "object",
           "properties": {
            "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_company": {
   "get": {
    "operationId": "get_company",
    "tags": [
     "tools"
    ],
    "summary": "One company in full",
    "description": "Returns the full directory row for one domain (for example stripe.com): status, endpoint and where it was found, transport, protocol revision, auth type, tool count and the recorded tool names, CLI package, OpenAPI, registries, plus how and when the row was observed and the entry page URL to cite. The same tool is callable over MCP at /mcp.",
    "parameters": [
     {
      "name": "domain",
      "in": "query",
      "required": true,
      "description": "The company domain as listed in the directory, for example stripe.com. A leading https:// or www. is ignored.",
      "schema": {
       "type": "string"
      },
      "example": "stripe.com"
     }
    ],
    "responses": {
     "200": {
      "description": "The result, the same object the MCP tool returns as structuredContent.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "company": {
           "type": "string"
          },
          "domain": {
           "type": "string"
          },
          "category": {
           "type": "string"
          },
          "mcp_status": {
           "type": "string",
           "enum": [
            "verified",
            "sign-in",
            "credential-wall",
            "no-answer",
            "no-tools",
            "none-found"
           ]
          },
          "has_mcp": {
           "type": "boolean"
          },
          "auth_type": {
           "type": [
            "string",
            "null"
           ]
          },
          "transport": {
           "type": [
            "string",
            "null"
           ]
          },
          "tool_count": {
           "type": [
            "integer",
            "null"
           ]
          },
          "has_cli": {
           "type": "boolean"
          },
          "url": {
           "type": "string",
           "format": "uri"
          },
          "descriptor": {
           "type": [
            "string",
            "null"
           ]
          },
          "endpoint": {
           "type": [
            "string",
            "null"
           ]
          },
          "endpoint_source": {
           "type": [
            "string",
            "null"
           ]
          },
          "protocol_version": {
           "type": [
            "string",
            "null"
           ]
          },
          "tool_names": {
           "type": "array",
           "items": {
            "type": "string"
           }
          },
          "tool_names_capped": {
           "type": "boolean"
          },
          "resources_count": {
           "type": [
            "integer",
            "null"
           ]
          },
          "prompts_count": {
           "type": [
            "integer",
            "null"
           ]
          },
          "connected_at": {
           "type": [
            "string",
            "null"
           ]
          },
          "cli_package": {
           "type": [
            "string",
            "null"
           ]
          },
          "openapi_url": {
           "type": [
            "string",
            "null"
           ]
          },
          "official_registry": {
           "type": "boolean"
          },
          "github_registry": {
           "type": "boolean"
          },
          "verified_at": {
           "type": "string"
          },
          "entry_url": {
           "type": "string",
           "format": "uri"
          },
          "status_meaning": {
           "type": "string"
          },
          "observation": {
           "type": "object",
           "properties": {
            "method": {
             "type": "string"
            },
            "observed_at": {
             "type": [
              "string",
              "null"
             ]
            },
            "verified_on": {
             "type": "string"
            },
            "endpoint_source": {
             "type": [
              "string",
              "null"
             ]
            },
            "counted_as_mcp_server": {
             "type": "boolean"
            },
            "method_page": {
             "type": "string",
             "format": "uri"
            }
           }
          },
          "category_url": {
           "type": "string",
           "format": "uri"
          },
          "dataset": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "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_categories": {
   "get": {
    "operationId": "list_categories",
    "tags": [
     "tools"
    ],
    "summary": "List categories with counts",
    "description": "Lists the directory categories with how many companies each holds and how many fall in each status: verified (open, tools listed), sign_in (challenge, tools not seen, not counted), credential_wall, no_answer, no_tools and none_found (no endpoint on record). Call it to see where open servers sit before search_directory. 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": {
             "category": {
              "type": "string"
             },
             "slug": {
              "type": "string"
             },
             "companies": {
              "type": "integer"
             },
             "verified": {
              "type": "integer"
             },
             "sign_in": {
              "type": "integer"
             },
             "credential_wall": {
              "type": "integer"
             },
             "no_answer": {
              "type": "integer"
             },
             "no_tools": {
              "type": "integer"
             },
             "none_found": {
              "type": "integer"
             },
             "with_cli": {
              "type": "integer"
             },
             "url": {
              "type": "string",
              "format": "uri"
             }
            }
           }
          },
          "total": {
           "type": "integer"
          },
          "companies": {
           "type": "integer"
          },
          "edition": {
           "type": "string"
          },
          "dataset": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "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_directory_stats": {
   "get": {
    "operationId": "get_directory_stats",
    "tags": [
     "tools"
    ],
    "summary": "Directory totals",
    "description": "Returns the directory totals: companies, how many count as having an MCP server (tools listed), the split by status, auth type (endpoints that answered, as on the directory page) and transport, the distribution of tool counts across the open servers, and how many have a CLI or an OpenAPI file. No parameters. 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": {
          "companies": {
           "type": "integer"
          },
          "counted_as_mcp_server": {
           "type": "integer"
          },
          "not_connected": {
           "type": "integer"
          },
          "by_status": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "status": {
              "type": "string"
             },
             "label": {
              "type": "string"
             },
             "counted": {
              "type": "boolean"
             },
             "companies": {
              "type": "integer"
             },
             "share_percent": {
              "type": "number"
             },
             "meaning": {
              "type": "string"
             },
             "url": {
              "type": "string",
              "format": "uri"
             }
            }
           }
          },
          "by_auth_type": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "auth_type": {
              "type": "string"
             },
             "companies": {
              "type": "integer"
             },
             "meaning": {
              "type": "string"
             },
             "url": {
              "type": "string",
              "format": "uri"
             }
            }
           }
          },
          "by_transport": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "transport": {
              "type": "string"
             },
             "companies": {
              "type": "integer"
             }
            }
           }
          },
          "transport_not_recorded": {
           "type": "integer"
          },
          "tool_counts": {
           "type": "object",
           "properties": {
            "servers": {
             "type": "integer"
            },
            "min": {
             "type": "integer"
            },
            "median": {
             "type": "number"
            },
            "max": {
             "type": "integer"
            },
            "total_tools": {
             "type": "integer"
            },
            "buckets": {
             "type": "array",
             "items": {
              "type": "object",
              "properties": {
               "range": {
                "type": "string"
               },
               "servers": {
                "type": "integer"
               }
              }
             }
            }
           }
          },
          "with_cli": {
           "type": "integer"
          },
          "with_openapi": {
           "type": "integer"
          },
          "in_official_registry": {
           "type": "integer"
          },
          "in_github_registry": {
           "type": "integer"
          },
          "edition": {
           "type": "string"
          },
          "url": {
           "type": "string",
           "format": "uri"
          },
          "method_url": {
           "type": "string",
           "format": "uri"
          },
          "dataset": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "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_census": {
   "get": {
    "operationId": "get_census",
    "tags": [
     "tools"
    ],
    "summary": "Act Layer Census",
    "description": "Returns the Act Layer Census: for the Tranco top 10,000 and for the domains on the Ora leaderboard, how many probed domains publish each discovery file (MCP, A2A agent card, agents.json, OpenAPI, OAuth metadata, AI catalog, agent skills), and the same counts per leaderboard category. Filter by cohort, category or file path. The same tool is callable over MCP at /mcp.",
    "parameters": [
     {
      "name": "cohort",
      "in": "query",
      "required": false,
      "description": "top10k is the Tranco top 10,000; ora-leaderboard is the domains scored on Ora's public leaderboard. Omit for both.",
      "schema": {
       "type": "string",
       "enum": [
        "top10k",
        "ora-leaderboard"
       ]
      },
      "example": "top10k"
     },
     {
      "name": "category",
      "in": "query",
      "required": false,
      "description": "An Ora leaderboard category, for example \"Developer Tools\". Only the leaderboard cohort has categories.",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "file",
      "in": "query",
      "required": false,
      "description": "Words from a file path or label to keep one file, for example \"openapi\" or \".well-known/mcp.json\".",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The result, the same object the MCP tool returns as structuredContent.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "edition": {
           "type": "string"
          },
          "crawl_rows": {
           "type": "integer"
          },
          "crawl_last_request": {
           "type": "string"
          },
          "definitions": {
           "type": "object",
           "properties": {
            "probed": {
             "type": "string"
            },
            "valid_file": {
             "type": "string"
            },
            "share_percent": {
             "type": "string"
            },
            "categories": {
             "type": "string"
            }
           }
          },
          "cohorts": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "id": {
              "type": "string"
             },
             "label": {
              "type": "string"
             },
             "domains": {
              "type": "integer"
             },
             "probed_domains": {
              "type": "integer"
             },
             "domains_with_any_file": {
              "type": "integer"
             },
             "files": {
              "type": "array",
              "items": {
               "type": "object",
               "properties": {
                "path": {
                 "type": "string"
                },
                "label": {
                 "type": "string"
                },
                "probed": {
                 "type": "integer"
                },
                "answered_json_or_yaml": {
                 "type": "integer"
                },
                "valid_file": {
                 "type": "integer"
                },
                "share_percent": {
                 "type": "number"
                }
               }
              }
             }
            }
           }
          },
          "by_category": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "category": {
              "type": "string"
             },
             "domains": {
              "type": "integer"
             },
             "domains_with_any_file": {
              "type": "integer"
             },
             "valid_files": {
              "type": "object",
              "additionalProperties": {
               "type": "integer"
              }
             }
            }
           }
          },
          "url": {
           "type": "string",
           "format": "uri"
          },
          "dataset": {
           "type": "object"
          }
         }
        }
       }
      }
     },
     "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/mcp-directory-2026-11-04.json": {
   "get": {
    "operationId": "download_mcp_directory_2026_11_04_json",
    "tags": [
     "downloads"
    ],
    "summary": "MCP and CLI Directory rows (json)",
    "description": "One row per company: status, endpoint, transport, auth type, tool count and names, CLI package, OpenAPI file, registries, verification date and the entry page. 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/mcp-directory-2026-11-04.csv": {
   "get": {
    "operationId": "download_mcp_directory_2026_11_04_csv",
    "tags": [
     "downloads"
    ],
    "summary": "MCP and CLI Directory rows (csv)",
    "description": "One row per company: status, endpoint, transport, auth type, tool count and names, CLI package, OpenAPI file, registries, verification date and the entry page. Whole-file download; the tools above answer questions over the same rows.",
    "responses": {
     "200": {
      "description": "The file.",
      "content": {
       "text/csv": {
        "schema": {
         "type": "string"
        }
       }
      }
     }
    }
   }
  },
  "/data/act-layer-census-2026-11-04.json": {
   "get": {
    "operationId": "download_act_layer_census_2026_11_04_json",
    "tags": [
     "downloads"
    ],
    "summary": "Act Layer Census (json)",
    "description": "How many probed domains publish each act-layer discovery file, by cohort and by Ora leaderboard category, from the shared crawl of 4 November 2026. 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/act-layer-census-2026-11-04.csv": {
   "get": {
    "operationId": "download_act_layer_census_2026_11_04_csv",
    "tags": [
     "downloads"
    ],
    "summary": "Act Layer Census (csv)",
    "description": "How many probed domains publish each act-layer discovery file, by cohort and by Ora leaderboard category, from the shared crawl of 4 November 2026. Whole-file download; the tools above answer questions over the same rows.",
    "responses": {
     "200": {
      "description": "The file.",
      "content": {
       "text/csv": {
        "schema": {
         "type": "string"
        }
       }
      }
     }
    }
   }
  }
 },
 "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"
       }
      }
     }
    }
   }
  }
 }
}