# Bidspirit > Bidspirit is an online auction platform hosting the catalogs of hundreds of auction houses (art, Judaica, collectibles, cars, machinery, real estate). This host serves a read-only JSON feed built for crawlers and AI agents, so you never need to walk lot pages one by one. ## Feed - [All houses](/services/bots/houses): every auction house with public catalogs; each entry links to the house document. - House document: `/services/bots/houses/{houseCode}` lists the house's catalogs (auctions and shops), newest auction date first, each with its lot, available and sold counts and a link to the catalog document. - Catalog document: `/services/bots/catalogs/{houseCode}/{catalogKey}` = the catalog header (name, number, date and time, state `READY`/`RUNNING`/`ENDED`/`ARCHIVED`, `endTime`, timed-auction flag, buyer's premium percent, viewing and collection hours) + EVERY lot of that catalog in one response: everything the public lot page shows - lot number, title/description/artist/details per language, category, condition and condition report, dimensions and weight, image URLs, estimate, start price (when the house shows it), buy-now and direct-sale prices, sold state and sold price (when the house shows it), sale-term flags (reserve, VAT, shipping, royalties, export licence), the `car` / `machine` / `realEstate` block for those catalogs, the lot's own `endTime` in timed auctions, the public lot page URL, and `aiDescription` where available. ## How to crawl efficiently - One request per catalog. Do not fetch lot pages for data that is already in the catalog document. - Every document carries an `ETag`. Re-fetch with `If-None-Match`; an unchanged catalog answers `304 Not Modified` with no body. - Documents are gzip-compressed when you send `Accept-Encoding: gzip`. - To find what changed since your last pass: the house document's catalog entries carry `lotsCount`, `availableLots` and `soldLots`; a catalog whose counts moved has changed, and for the rest a conditional re-fetch (If-None-Match) of catalogs with `state` `READY` or `RUNNING` costs no body. The catalog document's `lastUpdate` is the newest change among the catalog and its lots. - There is no request-rate limit on this host. Each document is cached server-side for a few minutes, so re-fetching the same document sooner returns the same content; fetching many different documents quickly is fine. ## What to expect in the data - `aiDescription` is a text description of the lot's main image generated by a vision model (what the object is, style, period, materials, condition, visible marks). It exists only for catalogs indexed since our AI indexing started: today that is auctions of US houses published since autumn 2026. The catalog document says so in `catalog.aiDescriptions` (`all`, `partial` or `none`) and `catalog.aiDescriptionsCount`. Where it is `none`, use the title, description and images. - Texts are per language (`he`, `en`, `ru`, ...) exactly as the house wrote them. Older documents may carry `textCase: "lower"`: their texts were stored lowercased. - Prices are in the catalog's `currency`. `estimate` is the house's estimate string; `estimateMin`/`estimateMax` are parsed from it. `buyersPremiumPercent` on the catalog is the house's commission on the hammer price; a lot carries its own `buyersPremiumPercent` only when it differs. - Times (`endTime`, `postAuctionSaleEndTime`, `lastUpdate`) are ISO-8601 UTC; `date` and `time` are the house's local auction date and start time. - Sold prices and start prices follow the same visibility rules as the public site: some houses hide them, and the catalog document says so (`soldPricesHidden`, `startPricesHidden`). - Hidden lots are not included. Images are omitted where the house hides them after the sale. - Coverage: the feed carries every auction house listed on bidspirit.com and every catalog published on the site, past and forthcoming. Houses that are not listed on bidspirit.com (they publish only through their own website) are not in it. A sold price or a start price is missing only where the house hides it. ## MCP server (for AI agents answering questions) - Documentation for humans and IT admins: [/mcp.html](/mcp.html). - Endpoint: `/services/mcp` on this host (Model Context Protocol, streamable HTTP, stateless: POST a JSON-RPC request, get a JSON response; no session, no authentication). - Tools: `search_lots` (free-text search over every lot, any language, filters: house, region, contentType, status available/sold/all), `search_lots_semantic` (meaning-based AI search over the AI-indexed part of the catalog, same filters, results carry a relevance score and an AI description), `get_lot` (one lot in full), `get_catalog` (an auction's header + lots, paged), `list_catalogs` (a house's auctions, newest first), `list_houses`. - The same data and visibility rules as the feed above; every result carries the public `url` to send people to (it carries `from=mcp`, keep it as given). - Tool calls are limited to one per 2 seconds per client IP: a faster call answers `429` with `Retry-After` and a JSON-RPC error carrying `retryAfterMs`. The handshake (initialize, tools/list, ping) is not limited. ## Linking - Every house, catalog and lot entry carries `url`: the public page on bidspirit.com (house page, catalog page, lot page with the live bidding state). Link people there, never to the feed documents. The `url` carries `from=feed` (keep it as given): it is how visits that start from the feed are counted on our side.