> ## Documentation Index
> Fetch the complete documentation index at: https://clair.im/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication, credits, and errors

> Authenticate Clair APIs with a Bearer key against api.clair.im. One wallet and rate limit cover Google Search, news, jobs, contacts, reviews, and Product Hunt.

Every Clair API shares one origin, one key, and one credit wallet.

|        |                                                             |
| ------ | ----------------------------------------------------------- |
| Origin | `https://api.clair.im`                                      |
| Header | `Authorization: Bearer YOUR_KEY`                            |
| Keys   | [Dashboard → API keys](https://clair.im/dashboard/api-keys) |

```sh theme={null}
curl -G https://api.clair.im/v1/news \
  -H "Authorization: Bearer YOUR_KEY" \
  --data-urlencode "q=inflation" \
  --data-urlencode "limit=5"
```

New accounts receive **250 free credits** and a **10 requests/minute** cap. Create a key once and copy it; Clair cannot show the secret again.

<Note>
  Indexed News and Jobs remain available on RapidAPI listings. First-party
  docs, the playground, and live scrapes (Google Search, publisher pages,
  Glassdoor, Trustpilot, Product Hunt, website contacts) use
  `api.clair.im` and a Clair Bearer key.
</Note>

## Credits

Requests debit the wallet before the handler runs. An empty wallet returns
`429` with `quota_exceeded`. Subscription credits spend first; purchased
credits do not expire with the plan.

| Family                 | Credits | Examples                                                        |
| ---------------------- | ------- | --------------------------------------------------------------- |
| Indexed                | 1       | `GET /v1/news`, `GET /v1/jobs`, taxonomies, market intelligence |
| Live search            | 5       | `engine=google_search`, `engine=google_news`                    |
| Live listing / article | 8       | Reuters, Bloomberg, AP, Glassdoor, Trustpilot, Product Hunt     |
| Website contacts       | 10      | `GET /v1/contacts`                                              |

Each `page` on a live scraper is a new billed request. Indexed News and Jobs
paginate with `limit` and `cursor` inside one credit per call.

## Errors

Mounted endpoints return a stable `error` code and human `detail`. Branch on
the code; do not parse `detail`.

```json theme={null}
{ "error": "bad_request", "detail": "q is required" }
```

| Status | `error`               | Meaning                                                                                                  |
| ------ | --------------------- | -------------------------------------------------------------------------------------------------------- |
| `400`  | `bad_request`         | A parameter failed validation.                                                                           |
| `400`  | `bad_cursor`          | The cursor is malformed, bound to different inputs, or this engine does not paginate.                    |
| `400`  | `locked_parameter`    | A pin-locked filter was sent (for example `limit` on a live scrape, or `sources` on a publisher engine). |
| `400`  | `empty_query`         | News keyword search normalized to nothing searchable.                                                    |
| `400`  | `unknown_source`      | A News source name is not in `GET /v1/sources`.                                                          |
| `400`  | `unknown_skill`       | A Jobs skill is outside the reviewed vocabulary.                                                         |
| `401`  | `unauthorized`        | Missing or invalid Bearer key.                                                                           |
| `403`  | `forbidden`           | This listing cannot query that engine.                                                                   |
| `404`  | `not_found`           | No Trustpilot profile, Product Hunt product, or canonical resource.                                      |
| `429`  | `quota_exceeded`      | Wallet is empty or the plan rate cap was hit.                                                            |
| `500`  | `internal`            | Unexpected origin error.                                                                                 |
| `502`  | `scrape_failed`       | The live page could not be fetched or parsed. Indexed APIs never return this.                            |
| `503`  | `product_unavailable` | The product is not ready, or credits could not be reached.                                               |
| `503`  | `overloaded`          | This endpoint hit its per-machine concurrency limit.                                                     |
| `504`  | `timeout`             | The live scrape exceeded its deadline.                                                                   |

Origin responses include `X-Request-ID`. Include it when reporting a problem.
Honor `Retry-After` on `503`.

## Pagination

**Indexed News and Jobs** use `limit` (default 25, max 100) and an opaque
`cursor`. Pass `next_cursor` unchanged. Changing filters while reusing a
cursor returns `bad_cursor`.

**Live scrapes** use 1-based `page`. They return `next_cursor: null`. Do not
send `limit` or `cursor`. Google Search pages are 10 organic hits (`page` max
10\). Reuters pages are 20 articles. Google News, Bloomberg, AP, and Product
Hunt listings are a single page (`page` must be 1). Trustpilot and Glassdoor
forward `page` to the public listing.