API

Grail Atlas publishes its catalog as JSON. Search it, read a reference, or send in a photo. No authentication required.

Base URL

https://grailatlas.com. Every path below hangs off it, and every response is JSON.

Authentication

The endpoints listed here need none. There are admin endpoints in the specification as well; those require an admin session and are not open to the public.

Endpoints

• GET /api/browse/search Natural-language search over the catalog. Returns reference IDs ranked by semantic similarity.
• GET /api/search Full-text search across references and editorial. Same scoring as the /search page.
• GET /api/reference/{id} One reference in detail: specs, classification, market band, momentum.
• POST /api/photos/submit Send in a photo of a reference. Goes to a review queue, not straight to the site.
• GET /api/photos/credits/leaderboard Photographers ranked by approved submissions.
• GET /api/health Liveness check.

Rate limits

Two endpoints are throttled per IP address. Natural-language search allows 100 requests a minute. Photo submission allows 5 an hour. Go past either and you get a 429 with a Retry-After header saying how long to wait. The rest are not throttled at the handler today, which is not a promise that they never will be: cache the results you can and do not hammer them.

Caching

Reference detail is cached for 10 minutes, full-text search for 2 minutes, and the photographer leaderboard for 5 minutes. Health is never cached. A repeat request inside those windows may be served from cache rather than recomputed.

The specification

The OpenAPI 3.0 document is at /api-docs/openapi.json. Point a client generator at it, or read it in the browser with the interactive explorer, which lists every endpoint with its request and response schemas.

Terms

Use of the API is covered by the terms of use. Questions go to contact.