format: zappian-agent-view
version: 1
kind: page
title: Developers
summary: "How software reads this site over HTTP: the addresses, an example call for each, the limits and the version rule."
sections[10]:
  - id: about
    title: What this API is for
    blocks[1]:
      - type: paragraph
        content[1]: "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."
  - id: auth
    title: Authentication
    blocks[1]:
      - type: paragraph
        content[1]: 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.
  - id: calls
    title: Addresses
    blocks[2]:
      - type: table
        head[3]: Method,Address,What it does
        rows[8]{Method,Address,"What it does"}:
          GET,/agent.json,Read the site brief
          GET,"/agent/{path}.json",Read one page
          GET,/agent/search.json,Search the site
          GET,/agent/catalog.json,List every page
          GET,/agent/forms.json,List the forms
          GET,"/agent/forms/{id}.json",Read one form
          GET,/ask,Ask a question
          POST,/ask,Ask a question with a JSON body
      - type: directory
        items[1]{label,href}:
          "API description, OpenAPI 3.1","https://staging.zappian.in/openapi.json"
  - id: examples
    title: Example calls
    blocks[24]:
      - type: heading
        level: 3
        text: "Read the site brief: GET /agent.json"
      - type: paragraph
        content[1]: "Returns the site brief: what this site is, who it is for, and how to read, search and use it. Start here."
      - type: paragraph
        content[1]: "curl https://staging.zappian.in/agent.json"
      - type: heading
        level: 3
        text: "Read one page: GET /agent/{path}.json"
      - type: paragraph
        content[1]: "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."
      - type: paragraph
        content[1]: "curl https://staging.zappian.in/agent/advertiser.json"
      - type: heading
        level: 3
        text: "Search the site: GET /agent/search.json"
      - type: paragraph
        content[1]: "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."
      - type: paragraph
        content[1]: "curl \"https://staging.zappian.in/agent/search.json?q=personal+loans&limit=5\""
      - type: heading
        level: 3
        text: "List every page: GET /agent/catalog.json"
      - type: paragraph
        content[1]: "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."
      - type: paragraph
        content[1]: "curl https://staging.zappian.in/agent/catalog.json"
      - type: heading
        level: 3
        text: "List the forms: GET /agent/forms.json"
      - type: paragraph
        content[1]: Returns the forms on this site and says which ones an agent can send. The whole list comes in one answer.
      - type: paragraph
        content[1]: "curl https://staging.zappian.in/agent/forms.json"
      - type: heading
        level: 3
        text: "Read one form: GET /agent/forms/{id}.json"
      - type: paragraph
        content[1]: "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."
      - type: paragraph
        content[1]: "curl https://staging.zappian.in/agent/forms/enquiry.json"
      - type: heading
        level: 3
        text: "Ask a question: GET /ask"
      - type: paragraph
        content[1]: "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."
      - type: paragraph
        content[1]: "curl \"https://staging.zappian.in/ask?query=personal+loans&limit=5\""
      - type: heading
        level: 3
        text: "Ask a question with a JSON body: POST /ask"
      - type: paragraph
        content[1]: "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."
      - type: paragraph
        content[1]: "curl https://staging.zappian.in/ask -H 'Content-Type: application/json' -d '{\"query\":{\"text\":\"personal loans\"},\"prefer\":{\"limit\":5}}'"
  - id: formats
    title: Other formats
    blocks[2]:
      - type: paragraph
        content[1]: "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."
      - type: paragraph
        content[1]: "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."
  - id: errors
    title: Errors
    blocks[4]:
      - type: paragraph
        content[1]: "The files under /agent answer an error as JSON with two members: error, a short code, and message, a sentence."
      - type: table
        head[3]: Status,Code,When
        rows[3]{Status,Code,When}:
          "400",invalid-input,A search parameter has a value the search cannot take.
          "404",no-agent-view,There is no agent view at this path.
          "500",internal-error,The server could not answer.
      - type: paragraph
        content[1]: "The ask address answers an error in the NLWeb shape: error.code and error.message."
      - type: table
        head[3]: Status,Code,When
        rows[5]{Status,Code,When}:
          "200",NO_RESULTS,No page matched these words.
          "400",INVALID_QUERY,"The question is missing, or a value has the wrong type."
          "413",INVALID_QUERY,The request body is too large.
          "429",RATE_LIMITED,The caller is over the request limit.
          "500",INTERNAL_ERROR,The server could not answer.
  - id: limits
    title: Limits
    blocks[4]:
      - type: paragraph
        content[1]: "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."
      - type: paragraph
        content[1]: "Each counted answer carries the headers RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy."
      - type: paragraph
        content[1]: Reading the files under /agent is not counted today. Keep your request rate modest.
      - type: paragraph
        content[1]: A POST body may be up to 65536 bytes.
  - id: mcp
    title: The MCP server
    blocks[3]:
      - type: paragraph
        content[1]: Agents that speak MCP can use this site through its MCP server. No login or key is needed.
      - type: facts
        items[3]:
          - term: Address
            detail[1]: "https://staging.zappian.in/mcp"
          - term: Transport
            detail[1]: "Streamable HTTP, without sessions"
          - term: Server card
            detail[1]: "https://staging.zappian.in/mcp/server-card"
      - type: directory
        items[1]{label,href}:
          Try each tool in a browser,"https://staging.zappian.in/agent/mcp/"
  - id: versions
    title: Versions
    blocks[2]:
      - type: paragraph
        content[1]: "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."
      - type: facts
        items[1]:
          - term: API-Version
            detail[1]: 1.0.0
  - id: files
    title: Description files
    blocks[1]:
      - type: directory
        items[4]{label,href}:
          "API description, OpenAPI 3.1","https://staging.zappian.in/openapi.json"
          API catalog,"https://staging.zappian.in/.well-known/api-catalog"
          Index for language models,"https://staging.zappian.in/llms.txt"
          Site brief for agents,"https://staging.zappian.in/agent/"
path: /developers/
urls:
  human: "https://staging.zappian.in/developers/"
  agent: "https://staging.zappian.in/agent/developers/"
  markdown: "https://staging.zappian.in/agent/developers.md"
  json: "https://staging.zappian.in/agent/developers.json"
  formats:
    md: "https://staging.zappian.in/agent/developers.md"
    json: "https://staging.zappian.in/agent/developers.json"
    xml: "https://staging.zappian.in/agent/developers.xml"
    toon: "https://staging.zappian.in/agent/developers.toon"
generated: "2026-11-19T10:26:37Z"