# 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.

## 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.