Skip to content
Agent view · Company pageSearchOpen the human page

This is the page as an agent reads it: plain Markdown, the same text as the raw file.

curl https://staging.zappian.in/agent/developers.md

200 · text/markdown; charset=utf-8 · 6.5 kB · 141 lines · ≈ 1,600 tokens, estimated

canonical: https://staging.zappian.in/developers/

Raw file.md.json.xml.toon

Developers

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

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

MethodAddressWhat it does
GET/agent.jsonRead the site brief
GET/agent/{path}.jsonRead one page
GET/agent/search.jsonSearch the site
GET/agent/catalog.jsonList every page
GET/agent/forms.jsonList the forms
GET/agent/forms/{id}.jsonRead one form
GET/askAsk a question
POST/askAsk a question with a JSON body

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.

StatusCodeWhen
400invalid-inputA search parameter has a value the search cannot take.
404no-agent-viewThere is no agent view at this path.
500internal-errorThe server could not answer.

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

StatusCodeWhen
200NO_RESULTSNo page matched these words.
400INVALID_QUERYThe question is missing, or a value has the wrong type.
413INVALID_QUERYThe request body is too large.
429RATE_LIMITEDThe caller is over the request limit.
500INTERNAL_ERRORThe 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.

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