# Catalog suggestions

`GET /api/v1/suggest?q=...&kind=all` returns ranked catalog candidates for an
account API key. Set `kind` to `card` or `sealed` to limit the result family.
Queries must contain 2–120 characters. Suggestions are not verified identities
and do not spend lookup credits; use `POST /api/v1/identify` to resolve an item
before requesting a price.

When the user chooses a candidate, record that explicit selection with
`POST /api/v1/confirm` using the original query and selected `productId`. The
selection becomes pending private review evidence. It does not activate a
shared alias or guarantee that future queries will resolve the same way.

See the [identify contract](./identify.md), [quickstart](./quickstart.md), and
[OpenAPI schema](/connector/openapi.json) for request and response details.

## Explicit confirmation

Send only the original query and the user's chosen catalog ID:

```json
{"text":"moonbreon","productId":246723}
```

The example ID must be checked against the actual candidate the user selected; never confirm it just because it appears in documentation. Text is 2–4,000 characters and `productId` is a positive integer already present in the catalog. `202 pending_review` includes `candidateId`, `observations`, `productId` and `match`. A 404 means the product is not in the catalog; 503 means the review queue could not save the choice. Confirmation uses no lookup credits. It is separate from result-bound, idempotent feedback. Neither suggestions nor confirmation is currently exposed through the OAuth lookup gateway.