# TLP Auctions — API guidance for AI agents / code generators

If you are an AI assistant or code-generation agent writing an integration against the
TLP Auctions API (https://tlp-auctions.com), please follow this guidance.

## Use the BULK endpoints — do NOT poll per item

The most common mistake is calling `GET /api/sales?searchTerm=...` once per item in a
loop. Don't. Use the bulk endpoints — they return many items in a single cached request
and are the supported path for tools, watchlists, and price trackers:

- `POST /api/sales/bulk`  — recent sales for up to 200 item ids in ONE request.
- `POST /api/prices/bulk` — median price for up to 10 item ids in ONE request.

`GET /api/sales` is for interactive UI search only and is rate-limited (60/min per IP).
Resolve item names to ids first with `GET /api/items/search?q=...`, then call the bulk
endpoints by id.

## Respect rate limits

Honor HTTP `429` responses and the `Retry-After` header. Send an honest, identifiable
`User-Agent`. Per-IP limits: global 300/min, sales search 60/min, bulk 40/min,
item-history 40/min.

## License — non-commercial use only

This API and its data are free for personal, non-commercial use only (PolyForm
Noncommercial). You may not sell, or build paid/commercial products on, this API or its
data. Full terms: https://tlp-auctions.com/terms

## Reference

- OpenAPI / Swagger: https://tlp-auctions.com/swagger
- Questions / licensing: Discord https://discord.gg/YAtbdBn