API
The API runs the same search the website does and hands back the results as data: JSON by default, or XML, CSV, TSV, NDJSON and plain text. A search only reads; what the API creates, renames and deletes is your own clusters.
https://api.publicwww.com
In one command
Searches and clusters through the API need a paid plan; a free account's token
reads /v1/account only.
export PUBLICWWW_KEY=...
curl -H "Authorization: Bearer $PUBLICWWW_KEY" \
"https://api.publicwww.com/v1/search?query=%22angular.min.js%22&per_page=3"
{
"query": "\"angular.min.js\"",
"page": 1,
"per_page": 3,
"total": 70907,
"total_pages": 23636,
"returned": 3,
"truncated": false,
"index_complete": true,
"took_ms": 2,
"results": [
{ "domain": "imgbox.com", "url": "https://imgbox.com/", "rank": 4187, "ranked": true }
]
}
Endpoints
| Endpoint | Methods | What it does |
|---|---|---|
/v1/search |
GET, POST | Run a search. Parameters, formats. |
/v1/account |
GET | Plan, quota and limits. Spends nothing, does not count against the rate and works on any account. |
/v1/clusters |
GET, POST | Saved lists of websites: create from a search or a list, combine, extract contacts and ids from page source, build signatures. Clusters. |
/mcp |
POST | The MCP server for AI assistants and agents: search and clusters as tools, with the same token. |
/ |
GET | The API describing itself, error codes included. Needs no key. |
/openapi.json |
GET | The same as an OpenAPI 3.1 description, to import into Postman, n8n, Make, Power Automate and other tools. Needs no key. |
There is no separate export endpoint: for bulk, ask /v1/search for a
large per_page, up to max_per_page in
/v1/account; the answer streams as it is produced.
Limit headers: X-Requests-* count requests per minute,
X-RateLimit-* searches per day; which answers carry them is in
limits.
What it promises
-
Results are never silently reduced. When the daily quota runs out,
the website quietly falls back to free-tier limits; the API answers
429 quota_exceededinstead of a short answer that looks complete. -
A short answer is marked as short -
truncatedin the body andX-Truncatedin the headers, in every format. -
Unranked sites say so -
rank: nullandranked: false, never an internal placeholder a client might mistake for a real, very large rank. -
Being told to wait beats being made to wait. Arrive too fast and the
answer comes back at once with a
Retry-After, rather than the connection being held open.
Getting a key
Issue a token on your profile, or let an application get one for you through OAuth 2.1. On the site a free account has searches and clusters within its limits; plans are on pricing.
The API is for your own code - a script, a server, an application. A web page cannot call it from the browser: the browser blocks such calls, and the token would be on show in the page.
In detail
- Authentication - the token in a header, and OAuth 2.1.
- Making requests -
/v1/search: the query and its parameters, by GET or POST. - Response formats - JSON, NDJSON, XML, CSV, TSV and plain text, chosen with
format=. - Quotas and rate limits - searches per day, requests per minute, and the headers that report them.
- Errors - one shape and a stable code for every failure.
- Clusters - saved lists of websites: create, combine, extract values, build signatures.
- Code examples - the same search in several languages, with paging and waiting when told to.
- Google Sheets - a formula and a menu that bring searches into a spreadsheet.
- Clay - PublicWWW through Clay's HTTP API with your token.
- The old export urls -
?export=downloads, unchanged.