Developers · Public API

Every reference price, programmatically.

Key-authenticated JSON endpoints for partners and the public, covering the Pokémon, One Piece, Sports, Disney Lorcana, Digimon, Riftbound, Magic: The Gathering, Yu-Gi-Oh! and Gundam catalogs. Identify a card by its game / set / card path slug or by graded-slab cert — the upstream Renaiss inventory id is returned for correlation but never accepted as an input.

Apply for API access ✦ Open Swagger explorer OpenAPI spec (JSON)

At a glance

Base URL

https://api.renaissos.com

Auth

X-Api-Key + X-Api-Secret headers (partner), or none (public · per-IP).

Supported games

pokemon · one-piece · sports · lorcana · digimon · riftbound · mtg · yugioh · gundamAny other game slug returns 404.

Card identity

Path slug (game, set, card) — card is the grade-less {number}-{name}[-{language}][-{idtoken}] — or a graded-slab cert.

Authentication

Partner endpoints authenticate with an API key — a public key_id paired with a secret. Send both as headers on every request:

X-Api-Key — your key id (public)
X-Api-Secret — your secret

The secret is shown once when the key is issued and is stored only as a hash on our side — keep it server-side and never ship it in a browser bundle. The public read endpoints need no key (they’re rate-limited per IP). A wrong key or secret returns 401.

Need a key? Apply for API access →

Example request

curl https://api.renaissos.com/v1/graded/PSA151238633 \
  -H "X-Api-Key: $RENAISS_KEY_ID" \
  -H "X-Api-Secret: $RENAISS_SECRET"

Tiers

Tier	Auth	Quota
Partner	X-Api-Key + X-Api-Secret	10,000 / day per key
Public	none (per-IP)	10 / day per IP

Endpoints

GET/v1/cards/{game}/{set}/{card}/overview

Grade-agnostic card lookup by path slug. Returns the card's identity plus a grades[] entry for every (company, grade) we track for that one card.

game: required · path · the game slug — one of pokemon, one-piece, sports, lorcana, digimon, riftbound, mtg, yugioh, gundam
set: required · path · the set slug
card: required · path · the grade-less card slug {number}-{name}[-{language}][-{idtoken}]. The optional language token disambiguates a non-English printing and the trailing 8-hex id token pins one exact printing; copy the canonical segments from a card response’s href rather than hand-building the bare form, which can resolve to the wrong printing or miss.

GET/v1/graded/{cert}

Graded-cert (PSA / CGC / BGS) lookup with on-demand valuation. Cached-first: a tracked cert returns its reference price + scan images instantly; a new one runs the live FMV pipeline to identify, crawl and price it on the spot. Always 200 for a parseable cert — inspect `found`. A live-progress (SSE) variant is at /v1/graded/{cert}/stream.

cert: required · path · the slab cert, e.g. PSA151238633 (bare digits default to PSA; CGC / BGS prefixes accepted)

POST/v1/graded/by-image

Value a graded card from a photo — no cert number needed. Upload the slab/card image and the AI reads the card identity and grade off the photo, then prices it. Streams pipeline progress over SSE, then a terminal `result` event carrying the same payload as the cert lookup — or a `failed` event when the photo isn't a readable card. A malformed upload returns 400 before the stream opens.

file: required · multipart/form-data · the card or slab photo (JPEG / PNG / WebP / AVIF, ≤ 15 MB)

There is no shared response envelope — each endpoint has its own shape, and no field is tier-dependent: a partner key raises the quota, it does not change the body. Prices are integer USD cents — priceUsdCents.

/v1/cards/…/overview — the card’s identity (name, setName, cardNumber, language, imageUrl, gradeCount, href) plus grades[], one entry per tracked grade carrying company, grade, gradeLabel, priceUsdCents, deltaPct, confidence, sourceCount, observationCount, updatedAt, lastSaleAt and href.
/v1/graded/{cert} — cert, certNumber, company, found, grade, gradeLabel, certImages, and a card summary holding priceUsdCents, deltaPct, confidence, updatedAt (when the price was last computed), lastSaleAt (the newest sale behind it) and href. Every card also carries its two identities: id — the catalog id you feed straight into /v1/cards/by-id/{id} — and renaissItemId, the upstream Renaiss inventory id, for correlating a card with your own records. renaissItemId is null while an item is in the Index but not yet mapped to the inventory. On found: false there is no card, so a reason says why instead.
/v1/graded/by-image — the same object, delivered as the terminal result SSE event.

Attribution (“Renaiss OS Index” + a link to the source page) is required when displaying a number publicly.

Structured data (JSON-LD)

Beyond the JSON API, public pages carry schema.org markup in <script type="application/ld+json"> blocks. Every block is server-rendered, so a crawler that executes no JavaScript still receives it. A condensed version of this — the graded-card block and the no-offer rule — is restated for machine readers in /llms.txt.

Page	Route	schema.org @type
Every page	root layout	Organization · WebSite
Graded card	/card/{game}/{set}/{card} · slug carries a grade token	+ BreadcrumbList · Product
Grade-less overview	/card/{game}/{set}/{card} · slug has no grade token	nothing beyond the site-wide pair
Set	/card/{game}/{set}	+ BreadcrumbList · ItemList (ItemList omitted when the set tracks no cards)
Index	/indices/{game}	+ BreadcrumbList · ItemList · Dataset (all three absent while the index is still computing; ItemList also omitted when the basket is empty)
Research hub	/research	+ BreadcrumbList · ItemList
Research article	/research/{slug}	+ BreadcrumbList · Article

No Offer · no AggregateOffer

The Product block on a graded card page deliberately carries no offers property, no Offer and no AggregateOffer. Nothing is purchasable from us at that URL: the reference price is a modeled fair-market value derived from recorded sales, and the sale counts are past completed trades — publishing either as an offer would assert a live price we do not have.

What the price does ship as, when there is one, is an additionalProperty entry. That array holds up to three PropertyValue entries and every one of them is optional — treat them as fields that may be absent from a perfectly valid graded card page, not as a guaranteed contract:

Reference price — value is the amount in dollars, unitText the string USD. Present only when the card has a modeled price.
Recorded sales — the completed-sale count. Present only when a count is known for the card.
Reference price updated — when that price was last recomputed. Present only when the card carries a last-updated timestamp.

A graded card that has none of the three carries no additionalProperty at all; the Product block is still emitted either way. Treat whatever you do receive as a data point, never as a quote.

Known gap: the grade-less overview page emits only the site-wide Organization + WebSite pair — it carries neither BreadcrumbList nor Product today. Every row above was verified against a live production response and against the conditions the emitter applies — a live page can only ever show you the blocks it does emit. Where a row carries a parenthesised note, that block is dropped for a page that still returns 200: treat it as optional, not as a guaranteed contract.

Full reference

The complete endpoint list, request/response schemas, and status codes live in the interactive Swagger explorer — try any call there, or pull the OpenAPI spec.