---
title: "Developers"
description: "How software reads this site over HTTP: the addresses, an example call for each, the limits and the version rule."
canonical: https://staging.zappian.in/developers/
last-updated: 2026-11-19
---

# Developers

> How software reads this site over HTTP: the addresses, an example call for each, the limits and the version rule.

- **Kind:** Company page
- **Human page:** https://staging.zappian.in/developers/
- **Agent view:** https://staging.zappian.in/agent/developers/
- **Formats:** [Markdown](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

## What this API is for

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.

## Authentication

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.

## Addresses

| 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 |

- [API description, OpenAPI 3.1](https://staging.zappian.in/openapi.json)

## Example calls

### Read the site brief: GET /agent.json

Returns the site brief: what this site is, who it is for, and how to read, search and use it. Start here.

curl https://staging.zappian.in/agent.json

### Read one page: GET /agent/{path}.json

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.

curl https://staging.zappian.in/agent/advertiser.json

### Search the site: GET /agent/search.json

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.

curl "https://staging.zappian.in/agent/search.json?q=personal+loans&limit=5"

### List every page: GET /agent/catalog.json

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.

curl https://staging.zappian.in/agent/catalog.json

### List the forms: GET /agent/forms.json

Returns the forms on this site and says which ones an agent can send. The whole list comes in one answer.

curl https://staging.zappian.in/agent/forms.json

### Read one form: GET /agent/forms/{id}.json

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.

curl https://staging.zappian.in/agent/forms/enquiry.json

### Ask a question: GET /ask

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.

curl "https://staging.zappian.in/ask?query=personal+loans&limit=5"

### Ask a question with a JSON body: POST /ask

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.

curl https://staging.zappian.in/ask -H 'Content-Type: application/json' -d '{"query":{"text":"personal loans"},"prefer":{"limit":5}}'

## Other 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.

## Errors

The files under /agent answer an error as JSON with two members: error, a short code, and message, a sentence.

| 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. |

The ask address answers an error in the NLWeb shape: error.code and error.message.

| 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. |

## Limits

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.

## The 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
- **Transport:** Streamable HTTP, without sessions
- **Server card:** https://staging.zappian.in/mcp/server-card

- [Try each tool in a browser](https://staging.zappian.in/agent/mcp/)

## Versions

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.

- **API-Version:** 1.0.0

## Description files

- [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/)
