# Pricelists.org

> Price comparison catalogue with a commerce API built for AI agents. Tracks product
> offers from many merchants, normalises prices to USD, and records a price history
> entry every time a price or stock level changes.

An agent can go from zero to a ranked list of offers in two HTTP calls: register for a
key, then search. No approval step, no OAuth, no human in the loop.

## Start here

- [OpenAPI specification](https://pricelists.org/.well-known/openapi.json): complete machine-readable contract for every endpoint
- [Agent documentation](https://pricelists.org/en/agent-docs): the same contract with worked request/response examples
- [Full reference for LLMs](https://pricelists.org/llms-full.txt): this file expanded with payloads and error semantics

## Getting a key

```
POST https://pricelists.org/api/agent/v1/register
Content-Type: application/json

{"name": "my-agent"}
```

Returns `apiKey` (prefix `plk_`) once and only once — it is stored as a SHA-256 hash and
cannot be recovered. Send it as `Authorization: Bearer plk_...`.

## What you can do

- **Search offers** — `POST /api/agent/v1/search`, no authentication. Match by GTIN/EAN/MPN
  for exact hits or by free text. Two ranking modes: `cheapest` (price only) and `best`
  (merchant credibility, price and delivery speed, weights adjustable per request).
- **Quote and buy** — `POST /quote` produces a 10-minute pricing snapshot; `POST /execute`
  places the order. Merchants without programmatic checkout return a `checkout_url` for a
  human to finish, so an agent always has a path forward.
- **Track orders** — `GET /orders/{orderId}`.
- **Contribute data** — `POST /submit` sends a pricelist for human moderation;
  `GET /submissions/{id}` reports the outcome.

## Rate limits

- Search: 30 requests/minute per IP
- Registration: 5 requests/minute per IP
- Authenticated endpoints: 60 requests/minute per key by default

## Purchase safety

`POST /execute` requires `confirm: true` and an `Idempotency-Key` header. Replaying the
same key returns the original order rather than creating a second one. The API never asks
for card numbers, CVV codes or one-time passwords — payment always happens on the
merchant's side.

## Public read API (no key, added 2026-07)

Base `https://pricelists.org/api/v1` — GET, JSON, ETag-cached, 60 req/min per IP.
**Only merchant-confirmed (real) offers are returned here** — this surface already
excludes the placeholder-price entries described in the data caveat below. Prefer it
over page crawling for price decisions.

- `GET /api/v1/search?q=&limit=&locale=pl|en&compact=1` — full-text (PL+EN)
- `GET /api/v1/products/{id}` — detail + up to 50 offers, cheapest first (`prod_123` or `123`)
- `GET /api/v1/products/by-gtin/{gtin}` (alias `/by-ean/`) — exact barcode lookup,
  checksum-normalized, zero-padded variants match; strongest identifier, 15.4M EANs
- `GET /api/v1/products/by-mpn/{mpn}`
- `GET /api/v1/products/{id}/offers?in_stock_only=1&currency=EUR` — freshness fields
  `last_seen_at` / `last_changed_at` on every offer
- `GET /api/v1/products/{id}/price-history?days=90&granularity=day` + `/statistics`
- `GET /api/v1/compare?ids=prod_1,prod_2` (max 10) — cheapest in-stock offer each
- `GET /api/v1/brands`, `GET /api/v1/categories`, `GET /api/v1/merchants/{slug}`
- `POST /api/v1/assistant/query` `{"query":"cheapest 27\" monitor under 300 usd"}` —
  deterministic natural-language parsing, 15 req/min

Barcode pages for humans: `https://pricelists.org/en/gtin/{gtin}`.
Tool definitions (tool-use JSON) and worked examples: see the repository docs
(`docs/agents/`). An MCP server for Claude Desktop/Code lives at
`integrations/mcp-server` in the repo.

## Optional

- [OpenClaw plugin](https://github.com/price-lists/pricelists.org): ready-made tool
  definitions (`plc_search`, `plc_quote`, `plc_execute`, `plc_order_get`, `plc_submit`,
  `plc_submission_status`) if your runtime supports the OpenClaw plugin format
- [Product pages](https://pricelists.org/en/price): every page carries schema.org
  Product/AggregateOffer JSON-LD, so plain crawling works too

## Data caveat

A large share of catalogue entries originate from a GTIN import that generated placeholder
prices rather than merchant-confirmed ones. Treat a single-offer product page as
indicative and prefer offers where several merchants agree. Real merchant data is being
backfilled.