# kwery API

Real-time price data across major European and global marketplaces.

New here? Start with the **[Guides](https://docs.kwery.co/)** — getting started,
authentication, webhooks, and per-source field reference.

## Try it — no account needed

A **mock server** is built into this reference: send requests to
`https://docs.kwery.co/_mock/openapi` and get back correctly-shaped example
responses — no signup, no API key (any dummy `Authorization` header passes),
and no credits consumed. Select **Mock server** in the Servers panel and the
code samples switch to it automatically.

```bash
curl -X POST https://docs.kwery.co/_mock/openapi/job \
  -H "Authorization: Bearer test123" \
  -H "Content-Type: application/json" \
  -d '{"source":"idealo","country":"de","key":"gtin","values":["4006381333962"]}'
```

The data returned is static example data from this specification, not a live
crawl — but the response shapes are exactly what production returns, so you can
build and test your integration end-to-end before creating an account.

## Source and key reference

Each source supports a fixed set of `key` types. The `key` field
determines what goes in `values`.

| Source | Key | Values format | Supported countries |
|--------|-----|---------------|---------------------|
| `idealo` | `term` | Free-text search | de at uk (gb) fr it es |
| `idealo` | `id` | Idealo product ID (numeric) | de at uk (gb) fr it es |
| `idealo` | `gtin` | EAN / GTIN-13 | de at uk (gb) fr it es |
| `idealo` | `pzn` | Pharmacy product number | de |
| `amazon` | `term` | Free-text search | us ca mx br uk (gb) de at ch es fr it jp cn in ae au nl se pl be sg tr |
| `amazon` | `asin` | Amazon ASIN (10 chars) | us ca mx br uk (gb) de at ch es fr it jp cn in ae au nl se pl be sg tr |
| `amazon` | `gtin` | EAN / GTIN-13 | us ca mx br uk (gb) de at ch es fr it jp cn in ae au nl se pl be sg tr |
| `google` | `term` | Free-text search | us de uk (gb) au at br ca cz dk fr in ie it jp mx no pl nz nl ru sg za es se fi ch tr ar cl co be gr hu pt ro sk hk id il my ph sa kr tw th ua vn ae |
| `google` | `id` | Google Shopping product ID | us de uk (gb) au at br ca cz dk fr in ie it jp mx no pl nz nl ru sg za es se fi ch tr ar cl co be gr hu pt ro sk hk id il my ph sa kr tw th ua vn ae |
| `google` | `product` | Pipe-separated product record — see `GoogleProductValue` | us de uk (gb) au at br ca cz dk fr in ie it jp mx no pl nz nl ru sg za es se fi ch tr ar cl co be gr hu pt ro sk hk id il my ph sa kr tw th ua vn ae |
| `ebay` | `term` | Free-text search | au at be ca fr de ie it hk my nl pl sg es ch uk (gb) us |
| `ebay` | `id` | eBay item ID (numeric) | au at be ca fr de ie it hk my nl pl sg es ch uk (gb) us |
| `ebay` | `gtin` | EAN / GTIN-13 | au at be ca fr de ie it hk my nl pl sg es ch uk (gb) us |
| `kaufland` | `term` | Free-text search | de cz sk pl at fr it |
| `kaufland` | `id` | Kaufland product ID | de cz sk pl at fr it |
| `kaufland` | `gtin` | EAN / GTIN-13 | de cz sk pl at fr it |
| `otto` | `term` | Free-text search | de |
| `otto` | `id` | Otto product ID | de |
| `billiger` | `term` | Free-text search | de |
| `billiger` | `id` | billiger.de product ID | de |
| `billiger` | `gtin` | EAN / GTIN-13 | de |
| `guenstiger` | `term` | Free-text search | de |
| `guenstiger` | `id` | guenstiger.de product ID (numeric) | de |
| `guenstiger` | `gtin` | EAN / GTIN-13 | de |
| `walmart` | `term` | Free-text search | us |
| `walmart` | `id` | Walmart item ID | us |
| `walmart` | `gtin` | EAN / UPC / GTIN | us |
| `lidl` | `term` | Free-text search | de at fr it nl pl uk … |
| `lidl` | `id` | Lidl product ID | de at fr it nl pl uk … |
| `aliexpress` | `term` | Free-text search | us |
| `aliexpress` | `id` | AliExpress product ID | us |
| `rakuten` | `term` | Free-text search | jp |
| `rakuten` | `id` | Rakuten item ID | jp |

> `uk (gb)` means `uk` and `gb` are two codes for the **same** UK marketplace —
> pass either one, it is not a separate locale. For Amazon, `at` and `ch` are
> served from the amazon.de storefront with Austria/Switzerland localization.

## Authentication

Sign up at [kwery.co](https://kwery.co); the dashboard issues your API key. Send it on
every data-API request as either:
- **Bearer** — `Authorization: Bearer kwy_live_...`
- **API key header** — `x-api-key: kwy_live_...`

Legacy/enterprise accounts provisioned before self-serve may still use HTTP Basic
(username + password) or a Bearer JWT issued directly by us. See
[Authentication](guides/authentication.md) for details.

Access is controlled per `source.country` pair. A `not subscribed to source`
error means your account is not provisioned for the requested combination.

## Response envelope

Validation errors return **HTTP 200** with `"error": true`. Always check the
`error` field before consuming a response:

```json
{ "error": true, "message": "country not supported by source" }
```

Infrastructure errors (auth, 5xx) use standard HTTP status codes.

## Stream API

For large batches (up to **100 000 values**), use the Stream endpoint.
Results are pushed to your `callback_url` as they complete — no polling needed.

1. `POST /stream` — submit values with a `callback_url`
2. Results arrive at `callback_url` in batches as they complete
3. `GET /stream/{id}` — optional progress check

## Batch API

For standard batches (up to **1 000 values**), use the Batch endpoint.
Results are retained for **72 hours**.

1. `POST /job` — submit a list of values, receive a job ID
2. `GET /job/{id}` — poll until `status` is `finished`
3. `GET /job/{id}/download` — retrieve structured results


Version: 4.0
License: Proprietary

## Servers

Production
```
https://api.kwery.co
```

## Security

### BearerAuth

JWT issued by your account. Valid for 24 hours.

Type: http
Scheme: bearer
Bearer Format: JWT

### BasicAuth

HTTP Basic authentication with your account username and password.

Type: http
Scheme: basic

### DashboardAuth

kwery.co dashboard session token (Supabase). Used by the dashboard UI
for account/keys/billing endpoints.


Type: http
Scheme: bearer
Bearer Format: JWT

### ApiKeyAuth

[object Object]

Type: apiKey
In: header
Name: x-api-key

## Download OpenAPI description

 - [kwery API](https://docs.kwery.co/_bundle/openapi.yaml)

## stream

 - [POST /stream](https://docs.kwery.co/openapi/stream/submitstreamjob.md): Submit a large batch for incremental webhook delivery. Results are pushed to `callback_url` in batches as they complete. ## Webhook payload ```json { "job_id": "...", "client_ref": "...", "batc
 - [GET /stream/{id}](https://docs.kwery.co/openapi/stream/getstreamjob.md): Returns progress counters for a stream job. Poll to track completion without consuming webhook deliveries.
 - [GET /stream/{id}/results](https://docs.kwery.co/openapi/stream/getstreamresults.md): Retrieve completed results without relying on webhook delivery. Useful as a fallback or when `callback_url` was not provided. **Offset/limit** — page through results in completion order. **Batch looku
 - [POST /stream/{id}/replay-all](https://docs.kwery.co/openapi/stream/replayalldeliveries.md): Re-enqueues all `dead_lettered` webhook deliveries for this job. Use after fixing a webhook endpoint that was temporarily unreachable.
 - [GET /stream/{id}/deliveries](https://docs.kwery.co/openapi/stream/listdeliveries.md): Returns the last 200 webhook delivery attempts for this job, newest first. Useful for diagnosing delivery failures.
 - [POST /stream/deliveries/{delivery_id}/replay](https://docs.kwery.co/openapi/stream/replaysingledelivery.md): Re-enqueues a single `dead_lettered` delivery. Use when only specific batches need to be retried.
## jobs

 - [POST /job](https://docs.kwery.co/openapi/jobs/submitjob.md): Submit a list of values to crawl. Returns immediately with a job object; results are assembled asynchronously. The request schema is discriminated on `source`. Select the source tab below to see the v
 - [GET /job/{id}](https://docs.kwery.co/openapi/jobs/getjob.md): Returns current status and progress counters. **Status lifecycle:** `new` → `working` → `finished` (or `failed`) When `status` is `finished`, use `GET /job/{id}/download` to retrieve results.
 - [PUT /job/{id}](https://docs.kwery.co/openapi/jobs/updatejob.md): Replaces the value list and parameters of an existing **interval job**. All previous results for this job are cleared. Only the fields listed in `JobUpdateRequest` can be updated. Omitted fields retai
 - [DELETE /job/{id}](https://docs.kwery.co/openapi/jobs/deletejob.md): Permanently deletes a job and all its results. Only interval jobs can be deleted via this endpoint.
 - [GET /job/{id}/download](https://docs.kwery.co/openapi/jobs/downloadjob.md): Returns the complete result set for a finished job. Results are cached after the first download; subsequent requests are served from cache regardless of result size. Append `.csv` to the URL or pass `