{
  "openapi": "3.1.0",
  "info": {
    "title": "Zappian Media read API",
    "version": "1.0.0",
    "summary": "How software reads this site over HTTP: the addresses, an example call for each, the limits and the version rule.",
    "description": "This API lets software read the public pages of this site, search them, and read the forms an agent can send. Every call only reads. Sending a form happens only through the submit_form tool of the MCP server. The answers hold the same content as the agent view of each page.\n\nAuthentication: No key and no login are needed. There is nothing to sign up for. A page on another site may call these addresses from a browser.\n\nLimits: Calls to the ask address and to the MCP server are counted together: 60 a minute from one caller. Over the request limit, the server answers HTTP 429 with a Retry-After header, in seconds. Each counted answer carries the headers RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy. Reading the files under /agent is not counted today. Keep your request rate modest. A POST body may be up to 65536 bytes.\n\nVersions: This API has one version. It is in the API-Version response header and in the description file. The addresses carry no version number and stay where they are. Within a version, fields are only added. None is renamed or removed. A change that would break a caller gets a new version number. The old version then answers with Deprecation and Sunset headers until it is switched off.\n\nOther formats: Each agent view is also a raw file in four formats: Markdown, JSON, XML and TOON. Add .md, .json, .xml or .toon to the path. Every page also answers as Markdown at its own address: add .md to the page path, or use /index.md for the home page. A request for a page with the header Accept: text/markdown gets the same Markdown.\n\nThe MCP server: Agents that speak MCP can use this site through its MCP server. No login or key is needed. Address: https://staging.zappian.in/mcp"
  },
  "servers": [
    {
      "url": "https://staging.zappian.in"
    }
  ],
  "externalDocs": {
    "description": "Developer documentation",
    "url": "https://staging.zappian.in/developers/"
  },
  "security": [],
  "tags": [
    {
      "name": "Pages"
    },
    {
      "name": "Search"
    },
    {
      "name": "Forms"
    },
    {
      "name": "Ask"
    }
  ],
  "paths": {
    "/agent.json": {
      "get": {
        "operationId": "getSiteBrief",
        "summary": "Read the site brief",
        "description": "Returns the site brief: what this site is, who it is for, and how to read, search and use it. Start here.",
        "tags": [
          "Pages"
        ],
        "responses": {
          "200": {
            "description": "The document, as JSON.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PageDocument"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/agent/{path}.json": {
      "get": {
        "operationId": "getPage",
        "summary": "Read one page",
        "description": "Returns one page of this site as a document: its title, summary, sections and addresses. Take the path from the catalog or from a search result. Cite urls.human, which is the page for people.",
        "tags": [
          "Pages"
        ],
        "parameters": [
          {
            "name": "path",
            "in": "path",
            "required": true,
            "description": "The page path without the slashes at either end, for example advertiser. For a deeper page, keep the slashes inside the path.",
            "schema": {
              "type": "string",
              "minLength": 1
            },
            "example": "advertiser"
          }
        ],
        "responses": {
          "200": {
            "description": "The document, as JSON.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PageDocument"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NoAgentView"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/agent/search.json": {
      "get": {
        "operationId": "searchPages",
        "summary": "Search the site",
        "description": "Finds pages, articles and news that match a few words, most relevant first. The results are in entries. Without q, the answer explains the search and has no results. There is no paging: limit sets how many results come back.",
        "tags": [
          "Search"
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Words to look for in page titles, summaries and text.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 200
            },
            "example": "personal loans"
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "Limit results to one kind of page. Default 'any'.",
            "schema": {
              "default": "any",
              "type": "string",
              "enum": [
                "any",
                "brief",
                "page",
                "article",
                "legal",
                "index",
                "news"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many results to return, 1 to 20. Default 10.",
            "schema": {
              "default": 10,
              "type": "integer",
              "minimum": 1,
              "maximum": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The document, as JSON.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchDocument"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInput"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/agent/catalog.json": {
      "get": {
        "operationId": "listPages",
        "summary": "List every page",
        "description": "Returns every page that has an agent view, in entries, with its kind, path and summary. The whole list comes in one answer. There is no paging and no cursor.",
        "tags": [
          "Pages"
        ],
        "responses": {
          "200": {
            "description": "The document, as JSON.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogDocument"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/agent/forms.json": {
      "get": {
        "operationId": "listForms",
        "summary": "List the forms",
        "description": "Returns the forms on this site and says which ones an agent can send. The whole list comes in one answer.",
        "tags": [
          "Forms"
        ],
        "responses": {
          "200": {
            "description": "The document, as JSON.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FormsDocument"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/agent/forms/{id}.json": {
      "get": {
        "operationId": "getForm",
        "summary": "Read one form",
        "description": "Returns one form: its fields as a JSON Schema, its consent text and the consent version. This call only reads. To send the form, use the submit_form tool of the MCP server.",
        "tags": [
          "Forms"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "A form id from the forms list, for example enquiry.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z][a-z0-9_]{1,63}$"
            },
            "example": "enquiry"
          }
        ],
        "responses": {
          "200": {
            "description": "The document, as JSON.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FormDocument"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NoAgentView"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/ask": {
      "get": {
        "operationId": "askQuestion",
        "summary": "Ask a question",
        "description": "Answers a question in plain words with the pages that match it, in the NLWeb answer shape. Each result is a page of this site, in its own words. Nothing in the answer is generated. A question that matches no page gets status 200 and the code NO_RESULTS.",
        "tags": [
          "Ask"
        ],
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "The question, in plain words. The parameter q is accepted as another name for it.",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 200
            },
            "example": "personal loans"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "How many results to return, 1 to 20. Default 10.",
            "schema": {
              "default": 10,
              "type": "integer",
              "minimum": 1,
              "maximum": 20
            }
          },
          {
            "name": "site",
            "in": "query",
            "required": false,
            "description": "Optional. When given it must name this site, or the answer is NO_RESULTS.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "streaming",
            "in": "query",
            "required": false,
            "description": "Set to true to get the answer as Server-Sent Events.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "mode",
            "in": "query",
            "required": false,
            "description": "Only list is supported: the answer lists pages and has no written summary.",
            "schema": {
              "type": "string",
              "enum": [
                "list"
              ]
            }
          },
          {
            "name": "response_format",
            "in": "query",
            "required": false,
            "description": "Only conversational_search is supported.",
            "schema": {
              "type": "string",
              "enum": [
                "conversational_search"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The pages that match, or a failure of a well-formed request, such as NO_RESULTS. With streaming, the same content arrives as Server-Sent Events.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/AskAnswer"
                    },
                    {
                      "$ref": "#/components/schemas/AskFailure"
                    }
                  ]
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/AskInvalid"
          },
          "429": {
            "$ref": "#/components/responses/AskLimited"
          },
          "500": {
            "$ref": "#/components/responses/AskFailed"
          }
        }
      },
      "post": {
        "operationId": "askQuestionWithBody",
        "summary": "Ask a question with a JSON body",
        "description": "The same search as the GET form, with the question in a JSON body as NLWeb defines it. It stores nothing, so a call can be repeated safely. Set prefer.streaming to true for Server-Sent Events.",
        "tags": [
          "Ask"
        ],
        "requestBody": {
          "required": true,
          "description": "The question is query.text. Everything under prefer is optional. Other members are accepted and not used.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AskRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The pages that match, or a failure of a well-formed request, such as NO_RESULTS. With streaming, the same content arrives as Server-Sent Events.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/AskAnswer"
                    },
                    {
                      "$ref": "#/components/schemas/AskFailure"
                    }
                  ]
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/AskInvalid"
          },
          "413": {
            "$ref": "#/components/responses/AskTooLarge"
          },
          "429": {
            "$ref": "#/components/responses/AskLimited"
          },
          "500": {
            "$ref": "#/components/responses/AskFailed"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PageDocument": {
        "description": "A page of this site as a document.",
        "type": "object",
        "properties": {
          "format": {
            "type": "string",
            "description": "A marker that names this document format."
          },
          "version": {
            "type": "number",
            "const": 1,
            "description": "The version of the document format."
          },
          "kind": {
            "type": "string",
            "enum": [
              "brief",
              "page",
              "article",
              "legal",
              "index",
              "news"
            ],
            "description": "What kind of document this is."
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "intro": {
            "type": "string"
          },
          "notice": {
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "$ref": "#/components/schemas/Link"
                }
              ]
            }
          },
          "path": {
            "type": "string",
            "description": "The path this document answers to on this site."
          },
          "urls": {
            "$ref": "#/components/schemas/DocumentURLs",
            "description": "The addresses of this document."
          },
          "updated": {
            "type": "string",
            "description": "When the content last changed, when known (ISO 8601)."
          },
          "generated": {
            "type": "string",
            "description": "When this copy was generated (ISO 8601)."
          },
          "sections": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Section"
            },
            "description": "The text of the document, section by section."
          },
          "withheld": {
            "type": "integer",
            "description": "How many passages were left out because they are not verified."
          },
          "forms": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "title"
              ]
            },
            "description": "The forms on this page, by id and title."
          },
          "entries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CatalogEntry"
            },
            "description": "The rows of a list: pages in the catalog, or pages that matched a search."
          },
          "form": {
            "$ref": "#/components/schemas/FormDetail",
            "description": "The form this document describes."
          }
        },
        "required": [
          "format",
          "version",
          "kind",
          "title",
          "path",
          "urls",
          "generated",
          "sections"
        ]
      },
      "SearchDocument": {
        "description": "Search results as a document. Each row of entries is a page that matched.",
        "type": "object",
        "properties": {
          "format": {
            "type": "string",
            "description": "A marker that names this document format."
          },
          "version": {
            "type": "number",
            "const": 1,
            "description": "The version of the document format."
          },
          "kind": {
            "type": "string",
            "const": "search",
            "description": "What kind of document this is."
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "intro": {
            "type": "string"
          },
          "notice": {
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "$ref": "#/components/schemas/Link"
                }
              ]
            }
          },
          "path": {
            "type": "string",
            "description": "The path this document answers to on this site."
          },
          "urls": {
            "$ref": "#/components/schemas/DocumentURLs",
            "description": "The addresses of this document."
          },
          "updated": {
            "type": "string",
            "description": "When the content last changed, when known (ISO 8601)."
          },
          "generated": {
            "type": "string",
            "description": "When this copy was generated (ISO 8601)."
          },
          "sections": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Section"
            },
            "description": "The text of the document, section by section."
          },
          "withheld": {
            "type": "integer",
            "description": "How many passages were left out because they are not verified."
          },
          "forms": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "title"
              ]
            },
            "description": "The forms on this page, by id and title."
          },
          "entries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchHit"
            },
            "description": "The rows of a list: pages in the catalog, or pages that matched a search."
          },
          "form": {
            "$ref": "#/components/schemas/FormDetail",
            "description": "The form this document describes."
          }
        },
        "required": [
          "format",
          "version",
          "kind",
          "title",
          "path",
          "urls",
          "generated",
          "sections",
          "entries"
        ]
      },
      "CatalogDocument": {
        "description": "The page catalog as a document. Each row of entries is a page.",
        "type": "object",
        "properties": {
          "format": {
            "type": "string",
            "description": "A marker that names this document format."
          },
          "version": {
            "type": "number",
            "const": 1,
            "description": "The version of the document format."
          },
          "kind": {
            "type": "string",
            "const": "catalog",
            "description": "What kind of document this is."
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "intro": {
            "type": "string"
          },
          "notice": {
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "$ref": "#/components/schemas/Link"
                }
              ]
            }
          },
          "path": {
            "type": "string",
            "description": "The path this document answers to on this site."
          },
          "urls": {
            "$ref": "#/components/schemas/DocumentURLs",
            "description": "The addresses of this document."
          },
          "updated": {
            "type": "string",
            "description": "When the content last changed, when known (ISO 8601)."
          },
          "generated": {
            "type": "string",
            "description": "When this copy was generated (ISO 8601)."
          },
          "sections": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Section"
            },
            "description": "The text of the document, section by section."
          },
          "withheld": {
            "type": "integer",
            "description": "How many passages were left out because they are not verified."
          },
          "forms": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "title"
              ]
            },
            "description": "The forms on this page, by id and title."
          },
          "entries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CatalogEntry"
            },
            "description": "The rows of a list: pages in the catalog, or pages that matched a search."
          },
          "form": {
            "$ref": "#/components/schemas/FormDetail",
            "description": "The form this document describes."
          }
        },
        "required": [
          "format",
          "version",
          "kind",
          "title",
          "path",
          "urls",
          "generated",
          "sections",
          "entries"
        ]
      },
      "FormsDocument": {
        "description": "The forms directory as a document. The member forms names each form.",
        "type": "object",
        "properties": {
          "format": {
            "type": "string",
            "description": "A marker that names this document format."
          },
          "version": {
            "type": "number",
            "const": 1,
            "description": "The version of the document format."
          },
          "kind": {
            "type": "string",
            "const": "forms",
            "description": "What kind of document this is."
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "intro": {
            "type": "string"
          },
          "notice": {
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "$ref": "#/components/schemas/Link"
                }
              ]
            }
          },
          "path": {
            "type": "string",
            "description": "The path this document answers to on this site."
          },
          "urls": {
            "$ref": "#/components/schemas/DocumentURLs",
            "description": "The addresses of this document."
          },
          "updated": {
            "type": "string",
            "description": "When the content last changed, when known (ISO 8601)."
          },
          "generated": {
            "type": "string",
            "description": "When this copy was generated (ISO 8601)."
          },
          "sections": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Section"
            },
            "description": "The text of the document, section by section."
          },
          "withheld": {
            "type": "integer",
            "description": "How many passages were left out because they are not verified."
          },
          "forms": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "title"
              ]
            },
            "description": "The forms on this page, by id and title."
          },
          "entries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CatalogEntry"
            },
            "description": "The rows of a list: pages in the catalog, or pages that matched a search."
          },
          "form": {
            "$ref": "#/components/schemas/FormDetail",
            "description": "The form this document describes."
          }
        },
        "required": [
          "format",
          "version",
          "kind",
          "title",
          "path",
          "urls",
          "generated",
          "sections",
          "forms"
        ]
      },
      "FormDocument": {
        "description": "One form as a document. The member form holds its fields, consent text and consent version.",
        "type": "object",
        "properties": {
          "format": {
            "type": "string",
            "description": "A marker that names this document format."
          },
          "version": {
            "type": "number",
            "const": 1,
            "description": "The version of the document format."
          },
          "kind": {
            "type": "string",
            "const": "forms",
            "description": "What kind of document this is."
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "intro": {
            "type": "string"
          },
          "notice": {
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "$ref": "#/components/schemas/Link"
                }
              ]
            }
          },
          "path": {
            "type": "string",
            "description": "The path this document answers to on this site."
          },
          "urls": {
            "$ref": "#/components/schemas/DocumentURLs",
            "description": "The addresses of this document."
          },
          "updated": {
            "type": "string",
            "description": "When the content last changed, when known (ISO 8601)."
          },
          "generated": {
            "type": "string",
            "description": "When this copy was generated (ISO 8601)."
          },
          "sections": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Section"
            },
            "description": "The text of the document, section by section."
          },
          "withheld": {
            "type": "integer",
            "description": "How many passages were left out because they are not verified."
          },
          "forms": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "title"
              ]
            },
            "description": "The forms on this page, by id and title."
          },
          "entries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CatalogEntry"
            },
            "description": "The rows of a list: pages in the catalog, or pages that matched a search."
          },
          "form": {
            "$ref": "#/components/schemas/FormDetail",
            "description": "The form this document describes."
          }
        },
        "required": [
          "format",
          "version",
          "kind",
          "title",
          "path",
          "urls",
          "generated",
          "sections",
          "forms",
          "form"
        ]
      },
      "Section": {
        "description": "One section of a document: a title and its blocks of text.",
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "blocks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Block"
            }
          },
          "claims": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "id",
          "title",
          "blocks"
        ]
      },
      "Block": {
        "description": "One block of text. The member type says which kind it is.",
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "heading"
              },
              "level": {
                "type": "integer"
              },
              "text": {
                "type": "string"
              }
            },
            "required": [
              "type",
              "level",
              "text"
            ]
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "paragraph"
              },
              "content": {
                "type": "array",
                "items": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "$ref": "#/components/schemas/Link"
                    }
                  ]
                }
              }
            },
            "required": [
              "type",
              "content"
            ]
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "list"
              },
              "ordered": {
                "type": "boolean"
              },
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ListItem"
                }
              }
            },
            "required": [
              "type",
              "ordered",
              "items"
            ]
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "table"
              },
              "head": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "rows": {
                "type": "array",
                "items": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            },
            "required": [
              "type",
              "head",
              "rows"
            ]
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "quote"
              },
              "content": {
                "type": "array",
                "items": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "$ref": "#/components/schemas/Link"
                    }
                  ]
                }
              }
            },
            "required": [
              "type",
              "content"
            ]
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "facts"
              },
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "term": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "array",
                      "items": {
                        "anyOf": [
                          {
                            "type": "string"
                          },
                          {
                            "$ref": "#/components/schemas/Link"
                          }
                        ]
                      }
                    }
                  },
                  "required": [
                    "term",
                    "detail"
                  ]
                }
              }
            },
            "required": [
              "type",
              "items"
            ]
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "directory"
              },
              "items": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "label": {
                      "type": "string"
                    },
                    "href": {
                      "type": "string"
                    },
                    "agent": {
                      "type": "string"
                    },
                    "note": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "label",
                    "href"
                  ]
                }
              }
            },
            "required": [
              "type",
              "items"
            ]
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "note"
              },
              "content": {
                "type": "array",
                "items": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "$ref": "#/components/schemas/Link"
                    }
                  ]
                }
              }
            },
            "required": [
              "type",
              "content"
            ]
          }
        ]
      },
      "ListItem": {
        "description": "One item of a list. It may hold a list of its own.",
        "type": "object",
        "properties": {
          "content": {
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "$ref": "#/components/schemas/Link"
                }
              ]
            }
          },
          "children": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ListItem"
            }
          }
        },
        "required": [
          "content"
        ]
      },
      "Link": {
        "description": "A link: its words and its address.",
        "type": "object",
        "properties": {
          "text": {
            "type": "string"
          },
          "href": {
            "type": "string"
          }
        },
        "required": [
          "text",
          "href"
        ]
      },
      "DocumentURLs": {
        "description": "The addresses of a document: the page for people, the agent view and the raw files.",
        "type": "object",
        "properties": {
          "human": {
            "type": "string"
          },
          "agent": {
            "type": "string"
          },
          "markdown": {
            "type": "string"
          },
          "json": {
            "type": "string"
          },
          "formats": {
            "type": "object",
            "properties": {
              "md": {
                "type": "string"
              },
              "json": {
                "type": "string"
              },
              "xml": {
                "type": "string"
              },
              "toon": {
                "type": "string"
              }
            },
            "required": [
              "md",
              "json",
              "xml",
              "toon"
            ]
          }
        },
        "required": [
          "human",
          "agent",
          "markdown",
          "json",
          "formats"
        ]
      },
      "CatalogEntry": {
        "description": "One page in the catalog.",
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "brief",
              "page",
              "article",
              "legal",
              "index",
              "news"
            ]
          },
          "path": {
            "type": "string",
            "description": "The page's path on this site, for example '/advertiser/'. Pass it to get_page."
          },
          "url": {
            "type": "string",
            "description": "The page for people."
          },
          "summary": {
            "type": "string"
          },
          "updated": {
            "description": "Date the content last changed, when known (ISO 8601).",
            "type": "string"
          }
        },
        "required": [
          "title",
          "kind",
          "path",
          "url"
        ]
      },
      "SearchHit": {
        "description": "One page that matched a search, with the addresses to open next.",
        "type": "object",
        "properties": {
          "title": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "brief",
              "page",
              "article",
              "legal",
              "index",
              "news"
            ]
          },
          "path": {
            "type": "string",
            "description": "The page's path on this site, for example '/advertiser/'. Pass it to get_page."
          },
          "url": {
            "type": "string",
            "description": "The page for people."
          },
          "summary": {
            "type": "string",
            "maxLength": 300
          },
          "updated": {
            "description": "Date the content last changed, when known (ISO 8601).",
            "type": "string"
          },
          "agent_url": {
            "type": "string",
            "description": "The agent view of the page."
          },
          "formats": {
            "type": "object",
            "properties": {
              "md": {
                "type": "string"
              },
              "json": {
                "type": "string"
              },
              "xml": {
                "type": "string"
              },
              "toon": {
                "type": "string"
              }
            },
            "required": [
              "md",
              "json",
              "xml",
              "toon"
            ],
            "description": "The page as a raw file in each format."
          }
        },
        "required": [
          "title",
          "kind",
          "path",
          "url",
          "agent_url",
          "formats"
        ]
      },
      "FormDetail": {
        "description": "Everything needed to fill one form.",
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9_]{1,63}$",
            "description": "A form id from list_forms."
          },
          "title": {
            "type": "string"
          },
          "purpose": {
            "type": "string",
            "description": "What the form is for and who should use it."
          },
          "pages": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Pages for people that carry this form."
          },
          "human_url": {
            "type": "string",
            "description": "Where a person fills in this form."
          },
          "agent_submission": {
            "type": "string",
            "enum": [
              "available",
              "not_available"
            ],
            "description": "'available' when submit_form accepts this form; 'not_available' when a person must use human_url."
          },
          "input_schema": {
            "description": "JSON Schema (2020-12) of the fields object.",
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {}
          },
          "consent": {
            "type": "object",
            "properties": {
              "text": {
                "type": "string",
                "description": "What the user agrees to by sending this form."
              },
              "version": {
                "type": "string",
                "description": "Send this back as consent.version."
              },
              "privacy_url": {
                "type": "string"
              }
            },
            "required": [
              "text",
              "version",
              "privacy_url"
            ]
          },
          "operator_required": {
            "type": "boolean",
            "description": "True when submit_form needs the operator object."
          }
        },
        "required": [
          "id",
          "title",
          "purpose",
          "pages",
          "human_url",
          "agent_submission",
          "operator_required"
        ]
      },
      "NoAgentViewError": {
        "description": "The error body when a path has no agent view.",
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "const": "no-agent-view",
            "description": "A short code for what went wrong."
          },
          "message": {
            "type": "string",
            "description": "What went wrong, in one sentence."
          },
          "brief": {
            "type": "string",
            "description": "The address of the site brief, to start from."
          }
        },
        "required": [
          "error",
          "message",
          "brief"
        ]
      },
      "InvalidInputError": {
        "description": "The error body when a search parameter cannot be used.",
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "const": "invalid-input",
            "description": "A short code for what went wrong."
          },
          "message": {
            "type": "string",
            "description": "What went wrong, in one sentence."
          },
          "problems": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "field": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              },
              "required": [
                "field",
                "message"
              ]
            },
            "description": "Each value at fault, with the reason."
          }
        },
        "required": [
          "error",
          "message",
          "problems"
        ]
      },
      "InternalError": {
        "description": "The error body when the server could not answer.",
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "const": "internal-error",
            "description": "A short code for what went wrong."
          },
          "message": {
            "type": "string",
            "description": "What went wrong, in one sentence."
          }
        },
        "required": [
          "error",
          "message"
        ]
      },
      "AskAnswer": {
        "description": "The pages that match a question.",
        "type": "object",
        "properties": {
          "_meta": {
            "type": "object",
            "properties": {
              "response_type": {
                "type": "string",
                "const": "answer"
              },
              "response_format": {
                "type": "string",
                "const": "conversational_search"
              },
              "version": {
                "type": "string"
              }
            },
            "required": [
              "response_type",
              "response_format",
              "version"
            ]
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AskItem"
            }
          }
        },
        "required": [
          "_meta",
          "results"
        ]
      },
      "AskFailure": {
        "description": "A question that could not be answered, with the reason.",
        "type": "object",
        "properties": {
          "_meta": {
            "type": "object",
            "properties": {
              "response_type": {
                "type": "string",
                "const": "failure"
              },
              "version": {
                "type": "string"
              }
            },
            "required": [
              "response_type",
              "version"
            ]
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "NO_RESULTS",
                  "INVALID_QUERY",
                  "UNSUPPORTED_FORMAT",
                  "UNSUPPORTED_MODE",
                  "RATE_LIMITED",
                  "INTERNAL_ERROR"
                ]
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "_meta",
          "error"
        ]
      },
      "AskItem": {
        "description": "One page that matches a question, as a schema.org object.",
        "type": "object",
        "properties": {
          "@context": {
            "type": "string",
            "const": "https://schema.org"
          },
          "@type": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "dateModified": {
            "type": "string"
          },
          "grounding": {
            "type": "object",
            "properties": {
              "source_url": {
                "type": "string"
              },
              "agent_url": {
                "type": "string"
              },
              "markdown_url": {
                "type": "string"
              }
            },
            "required": [
              "source_url",
              "agent_url",
              "markdown_url"
            ]
          }
        },
        "required": [
          "@context",
          "@type",
          "name",
          "url",
          "grounding"
        ]
      },
      "AskRequest": {
        "description": "A question in the NLWeb request shape.",
        "type": "object",
        "properties": {
          "query": {
            "type": "object",
            "properties": {
              "text": {
                "type": "string",
                "minLength": 2,
                "maxLength": 200,
                "description": "Words to look for in page titles, summaries and text."
              },
              "site": {
                "type": "string"
              }
            },
            "required": [
              "text"
            ],
            "additionalProperties": {}
          },
          "prefer": {
            "type": "object",
            "properties": {
              "streaming": {
                "type": "boolean"
              },
              "mode": {
                "type": "string",
                "enum": [
                  "list"
                ]
              },
              "response_format": {
                "type": "string",
                "enum": [
                  "conversational_search"
                ]
              },
              "limit": {
                "default": 10,
                "description": "How many results to return, 1 to 20. Default 10.",
                "type": "integer",
                "minimum": 1,
                "maximum": 20
              }
            },
            "additionalProperties": {}
          }
        },
        "required": [
          "query"
        ],
        "additionalProperties": {}
      }
    },
    "headers": {
      "API-Version": {
        "description": "The version of this API.",
        "schema": {
          "type": "string"
        },
        "example": "1.0.0"
      },
      "RateLimit-Limit": {
        "description": "How many counted calls one caller may make in a minute.",
        "schema": {
          "type": "integer",
          "minimum": 0
        },
        "example": 60
      },
      "RateLimit-Remaining": {
        "description": "How many counted calls the caller has left in this minute.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "RateLimit-Reset": {
        "description": "Seconds until the count starts again.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      },
      "RateLimit-Policy": {
        "description": "The limit, then its window in seconds.",
        "schema": {
          "type": "string"
        },
        "example": "60;w=60"
      },
      "Retry-After": {
        "description": "Seconds to wait before the next call.",
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      }
    },
    "responses": {
      "InvalidInput": {
        "description": "A search parameter has a value the search cannot take. The body names each one.",
        "headers": {
          "API-Version": {
            "$ref": "#/components/headers/API-Version"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/InvalidInputError"
            }
          }
        }
      },
      "NoAgentView": {
        "description": "There is no agent view at this path.",
        "headers": {
          "API-Version": {
            "$ref": "#/components/headers/API-Version"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/NoAgentViewError"
            }
          }
        }
      },
      "InternalError": {
        "description": "The server could not answer. Try again later.",
        "headers": {
          "API-Version": {
            "$ref": "#/components/headers/API-Version"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/InternalError"
            }
          }
        }
      },
      "AskInvalid": {
        "description": "The request could not be read: the question is missing, or a value has the wrong type.",
        "headers": {
          "API-Version": {
            "$ref": "#/components/headers/API-Version"
          },
          "RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimit-Limit"
          },
          "RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimit-Remaining"
          },
          "RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimit-Reset"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimit-Policy"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/AskFailure"
            }
          }
        }
      },
      "AskTooLarge": {
        "description": "The request body is larger than 65536 bytes.",
        "headers": {
          "API-Version": {
            "$ref": "#/components/headers/API-Version"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/AskFailure"
            }
          }
        }
      },
      "AskLimited": {
        "description": "The caller is over the request limit. The Retry-After header gives the wait in seconds.",
        "headers": {
          "API-Version": {
            "$ref": "#/components/headers/API-Version"
          },
          "RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimit-Limit"
          },
          "RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimit-Remaining"
          },
          "RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimit-Reset"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimit-Policy"
          },
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/AskFailure"
            }
          }
        }
      },
      "AskFailed": {
        "description": "The server could not answer. Try again later.",
        "headers": {
          "API-Version": {
            "$ref": "#/components/headers/API-Version"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/AskFailure"
            }
          }
        }
      }
    }
  }
}
