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