A collection agents can explore.
Find a discovery, understand its limits, and follow its original source. No API key needed for reading.
OpenAPI contract · Catalog schema · llms.txt
Read the illustrated field notes
Try a real request
These buttons make read-only requests against this site. No account or paid search is used.
Choose an example to see its status and response.
Ask in everyday language
GET /api/catalog?q=tea%20gift%20for%20my%20mum%20under%20%2425 GET /api/catalog?q=nut%20free%20spice%20gift
Read queryContext alongside results. Recipient words are treated as context; budgets remain hard limits. Gift and purchase requests require a source link. Delivery dates, dietary safety, custom fit and lightweight feel need confirmation: results are investigation candidates, not verified suitable products. Empty results may include a separately labeled recovery link; no budget is silently relaxed.
From a question to a shortlist
Agent quickstart and CLI · Curated edits · All pages and Markdown versions
GET /api/edits GET /api/compare?ids=jasmine-silver-tip,aroma-stone
Edits accepts no query parameters. Compare accepts one ids parameter containing 2–4 distinct catalog IDs. It returns recorded prices, source URLs and unresolved details; it does not rank products or invent a winner.
Start small
GET /api/catalog?kind=Tea&maxPrice=25&fields=id,name,price,url,sourceUrl GET /api/catalog?source=maiwa.com&limit=20 GET /api/catalog?q=cinamon&fields=id,name,price GET /api/catalog/jasmine-silver-tip
Use facets to discover accepted categories, tags, kinds, source domains and availability values. Use matchedFacets for counts within your result set. Price filters apply to comparable listed USD estimates only; unknown and admission-only prices are excluded. A jar is not a kilogram.
Pagination you can trust
Follow links.next until it is null. Links carry the catalog revision; HTTP 409 means the catalog changed and you should restart. Limit is 1–100. Conditional reads support ETag and If-None-Match. Use fields to keep responses small.
Readable without a browser
Every item has a /rarities/{id} HTML page, an individual JSON endpoint and an original source link when known. Pages include structured WebPage/Thing data. They do not claim verified offers, stock or measured rarity.
Filter by origin
GET /api/catalog?country=JP&maxPrice=50&fields=id,name,origin,price,url,sourceUrl
Use two-letter codes from facets.countries. Flags and names represent documented origin, not the shop’s location. Unknown origins are excluded.
Sources and freshness
Sources are refreshed manually, with no guaranteed interval. An ETag confirms an unchanged RARA response; it does not confirm current merchant stock or pricing. Preserve the recorded research dates when citing a find.
Imported records disclose publisher, retrieval date and feed endpoint. Price and availability remain unknown unless separately verified. Source photos depict merchant listings, not RARA inventory. The index is not a seller partnership.
Actions require intent
The item interface can record an email and optional fit preferences with explicit consent. This is an expression of interest, not an order, payment or promise of fulfillment. RARA sends no emails. Never submit someone’s email or fit details without their authorization. Private requests and the operator inbox are excluded from the public catalog.
Read every page safely
Run this in a browser on this site, or replace the origin with your deployed RARA domain. Preserve filters by following the returned URL.
let next = '/api/catalog?limit=100&fields=id,name,url';
const items = [];
while (next) {
const response = await fetch(next);
if (response.status === 409) throw new Error('Catalog changed: restart');
if (!response.ok) throw new Error(await response.text());
const page = await response.json();
items.push(...page.items);
next = page.links.next;
}
console.log(items);Response contracts
/catalog.schema.json describes the full downloadable snapshot. The OpenAPI CatalogPage schema describes a search response; Discovery describes a complete item. Field projection returns only requested keys, with null for missing optional values. HEAD uses GET status and headers without a body. Item endpoints reject query parameters; projection is a search-endpoint feature.
Errors
Errors contain error, code, and documentation. They use Cache-Control: no-store. A stale revision returns REVISION_CONFLICT; invalid queries return INVALID_QUERY. Validation always precedes conditional caching. ETags support weak validators and lists. 400: invalid query. 404: unknown item. 405: unsupported method. 409: stale catalog revision. Empty matches are a successful 200 response with zero results. Exact filters never relax silently.