# hacker-news-search API

Public HTTPS endpoint: https://hacker-news-search.api.whox.ai/v1/

Documentation: https://hacker-news-search.api.whox.ai/docs

OpenAPI3.1 schema: https://hacker-news-search.api.whox.ai/openapi.json

JSON schemas: https://hacker-news-search.api.whox.ai/schema.json

No WHOX account, API key or Dot ID is required for these public read operations.

| Operation | Arguments | Result fields |
| --- | --- | --- |
| `search` | `query` (string, required) | title, url |

Call with GET query parameters or POST application/json. POST invokes the same read operation; it does not change the upstream site.

```sh
curl --get https://hacker-news-search.api.whox.ai/v1/search --data-urlencode "query=example"
```

Responses contain `ok`, `service`, `operation`, `data`, and `meta` (source, duration, cache freshness and definition version). Errors contain `ok:false` and `error.code/message`. See openapi.json for full input, response, validation and error schemas.

Limits:60 requests/minute/client,4 concurrent upstream requests,15-second upstream deadline,2MiB upstream response limit,30-second successful-read cache. Source rate limits are preserved and return429; unsupported or changed sources return a structured error. Credentials, account sessions and authenticated writes are not shared.