{
  "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": [
    {
      "id": "about",
      "title": "What this API is for",
      "blocks": [
        {
          "type": "paragraph",
          "content": [
            "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": [
        {
          "type": "paragraph",
          "content": [
            "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": [
        {
          "type": "table",
          "head": [
            "Method",
            "Address",
            "What it does"
          ],
          "rows": [
            [
              "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": [
            {
              "label": "API description, OpenAPI 3.1",
              "href": "https://staging.zappian.in/openapi.json"
            }
          ]
        }
      ]
    },
    {
      "id": "examples",
      "title": "Example calls",
      "blocks": [
        {
          "type": "heading",
          "level": 3,
          "text": "Read the site brief: GET /agent.json"
        },
        {
          "type": "paragraph",
          "content": [
            "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": [
            "curl https://staging.zappian.in/agent.json"
          ]
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Read one page: GET /agent/{path}.json"
        },
        {
          "type": "paragraph",
          "content": [
            "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": [
            "curl https://staging.zappian.in/agent/advertiser.json"
          ]
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Search the site: GET /agent/search.json"
        },
        {
          "type": "paragraph",
          "content": [
            "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": [
            "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": [
            "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": [
            "curl https://staging.zappian.in/agent/catalog.json"
          ]
        },
        {
          "type": "heading",
          "level": 3,
          "text": "List the forms: GET /agent/forms.json"
        },
        {
          "type": "paragraph",
          "content": [
            "Returns the forms on this site and says which ones an agent can send. The whole list comes in one answer."
          ]
        },
        {
          "type": "paragraph",
          "content": [
            "curl https://staging.zappian.in/agent/forms.json"
          ]
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Read one form: GET /agent/forms/{id}.json"
        },
        {
          "type": "paragraph",
          "content": [
            "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": [
            "curl https://staging.zappian.in/agent/forms/enquiry.json"
          ]
        },
        {
          "type": "heading",
          "level": 3,
          "text": "Ask a question: GET /ask"
        },
        {
          "type": "paragraph",
          "content": [
            "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": [
            "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": [
            "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": [
            "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": [
        {
          "type": "paragraph",
          "content": [
            "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": [
            "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": [
        {
          "type": "paragraph",
          "content": [
            "The files under /agent answer an error as JSON with two members: error, a short code, and message, a sentence."
          ]
        },
        {
          "type": "table",
          "head": [
            "Status",
            "Code",
            "When"
          ],
          "rows": [
            [
              "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": [
            "The ask address answers an error in the NLWeb shape: error.code and error.message."
          ]
        },
        {
          "type": "table",
          "head": [
            "Status",
            "Code",
            "When"
          ],
          "rows": [
            [
              "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": [
        {
          "type": "paragraph",
          "content": [
            "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": [
            "Each counted answer carries the headers RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Policy."
          ]
        },
        {
          "type": "paragraph",
          "content": [
            "Reading the files under /agent is not counted today. Keep your request rate modest."
          ]
        },
        {
          "type": "paragraph",
          "content": [
            "A POST body may be up to 65536 bytes."
          ]
        }
      ]
    },
    {
      "id": "mcp",
      "title": "The MCP server",
      "blocks": [
        {
          "type": "paragraph",
          "content": [
            "Agents that speak MCP can use this site through its MCP server. No login or key is needed."
          ]
        },
        {
          "type": "facts",
          "items": [
            {
              "term": "Address",
              "detail": [
                "https://staging.zappian.in/mcp"
              ]
            },
            {
              "term": "Transport",
              "detail": [
                "Streamable HTTP, without sessions"
              ]
            },
            {
              "term": "Server card",
              "detail": [
                "https://staging.zappian.in/mcp/server-card"
              ]
            }
          ]
        },
        {
          "type": "directory",
          "items": [
            {
              "label": "Try each tool in a browser",
              "href": "https://staging.zappian.in/agent/mcp/"
            }
          ]
        }
      ]
    },
    {
      "id": "versions",
      "title": "Versions",
      "blocks": [
        {
          "type": "paragraph",
          "content": [
            "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": [
            {
              "term": "API-Version",
              "detail": [
                "1.0.0"
              ]
            }
          ]
        }
      ]
    },
    {
      "id": "files",
      "title": "Description files",
      "blocks": [
        {
          "type": "directory",
          "items": [
            {
              "label": "API description, OpenAPI 3.1",
              "href": "https://staging.zappian.in/openapi.json"
            },
            {
              "label": "API catalog",
              "href": "https://staging.zappian.in/.well-known/api-catalog"
            },
            {
              "label": "Index for language models",
              "href": "https://staging.zappian.in/llms.txt"
            },
            {
              "label": "Site brief for agents",
              "href": "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:36Z"
}
