# FindByWords API

> Answers, suggestions and catalogue for one shop, with the shop's own assistant behind them. Read-only, JSON over HTTPS, one shop per key. Base URL: https://assistant.onesite.agency/api/v1

## Basics

- Authentication: `Authorization: Bearer <key>`. Keys are created in the cabinet (Developers tab), shown once, stored hashed.
- Scopes: `answer` (20/min), `suggest` (120/min), `catalogue:read` (120/min), `similar` (60/min), `analytics:read` (30/min). Optional IP and browser-origin allow-lists.
- Errors share one JSON shape with a `request_id`; branch on `error.code`.
- Lists use cursors (`next_cursor`), GET responses carry an ETag, `POST /answers` accepts `Idempotency-Key`.
- `say` and `why` in answers are AI-generated and flagged in the `ai` object; tell your users.

## Endpoints

- [GET /me](https://findbywords.com/developers#op-getKeyInfo): Check which shop, scopes and limits a key has.
- [POST /answers](https://findbywords.com/developers#op-createAnswer): Ask a question in the shopper's own words and get the best match, alternatives and a reason for each.
- [GET /suggestions](https://findbywords.com/developers#op-listSuggestions): Fast product suggestions under a search box as someone types. No AI model is involved.
- [GET /products](https://findbywords.com/developers#op-listProducts): Read the whole catalogue page by page.
- [GET /products/{product_id}](https://findbywords.com/developers#op-getProduct): Read one product by its id.
- [GET /products/{product_id}/similar](https://findbywords.com/developers#op-listSimilarProducts): Products similar to one product. No AI model is involved.
- [GET /analytics/summary](https://findbywords.com/developers#op-getAnalyticsSummary): Your shop's totals for a window — the same figures as the cabinet's Statistics — with an optional comparison.
- [GET /analytics/series](https://findbywords.com/developers#op-getAnalyticsSeries): Questions, misses and questions that reached a product, for every day of the window.
- [GET /analytics/queries](https://findbywords.com/developers#op-getAnalyticsQueries): The questions people ask most, and the questions most often left without a product.
- [GET /analytics/sales](https://findbywords.com/developers#op-getAnalyticsSales): What the assistant sold, by your own orders — the same figures as the cabinet's Purchases summary.

## Documentation

- [Developer documentation](https://findbywords.com/developers): the human reference, in 7 languages
- [OpenAPI 3.1 document](https://assistant.onesite.agency/api/v1/openapi.json): machine-readable, with examples
- [Complete reference as Markdown](https://findbywords.com/developers/llms-full.txt): every endpoint, schema, error code and example
- [This index](https://findbywords.com/developers/llms.txt)