# 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. Everything is a read - nothing here creates or changes anything.

Base URL `https://api.publicwww.com`

## In one command

```
curl -H "Authorization: Bearer $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": 278,
"total_pages": 93,
"returned": 3,
"truncated": false,
"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](https://publicwww.com/docs/api/requests/), [formats](https://publicwww.com/docs/api/formats/). |
| `/v1/account` | GET | Plan, quota and limits. Spends nothing. |
| `/v1/clusters` | GET, POST | Saved lists of websites: create from a search or a list, combine, extract contacts and ids from page source. [Clusters](https://publicwww.com/docs/api/clusters/). |
| `/mcp` | POST | The [MCP server](https://publicwww.com/docs/mcp/) 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](https://api.publicwww.com/openapi.json), to import into Postman, n8n, Make, Power Automate and other tools. Needs no key. |

There is no separate export endpoint. Bulk is `/v1/search` with a large `per_page`, which on a paid plan goes up to a million rows; the answer streams as it is produced.

## What it promises

- **Results are never silently reduced.** When a browser's daily quota runs out the website quietly falls back to free-tier limits and shows less. A script cannot see that happen, so here it is an error instead - `429 quota_exceeded`, not a short answer that looks complete.
- **A short answer is marked as short** - `truncated` in the body and `X-Truncated` in the headers, in every format.
- **Unranked sites say so** - `rank: null` and `ranked: 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](https://publicwww.com/profile/api), or let an application get one for you through [OAuth 2.1](https://publicwww.com/docs/api/authentication/#oauth). A paid plan is required; see [pricing](https://publicwww.com/prices.html). Existing scripts that call the old `?export=` urls keep working unchanged - see [the old export urls](https://publicwww.com/docs/api/legacy/).

Source: https://publicwww.com/docs/api/