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

Every path below is a live /v1 route documented in OpenAPI. Request and response schemas, status codes, and optional query flags live in the Swagger explorer. First-party app plumbing and internal-tier partner routes are omitted on purpose — they are not a public contract (a third party cannot use App Attest against our app id; a higher budget is an API key).

GET/v1/items/{game}/{set}/{item}/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
item: required · path · the grade-less item 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)

GET/v1/graded

Bulk cache-only cert lookups. Pass certs as a comma-separated list (max 50). Never runs on-demand valuation — a cert that is not already stored comes back found: false.

certs: required · query · comma-separated cert numbers, optionally grader-prefixed

GET/v1/graded/{cert}/stream

SSE progress stream for the same cert lookup as GET /v1/graded/{cert}. Use this when you want pipeline stages, not just the terminal GradedLookup.

cert: required · path · the slab cert

GET/v1/indices

Public market-index tiles for Pokémon, One Piece, Sports and Riftbound: value, deltas, sparkline, and top movers. Catalog-only games are not tiles here.

GET/v1/indices/{game}

Full index detail for one indexed game, including its ranked constituents. A game slug that is catalog-only (no public index) 404s.

game: required · path · an indexed game slug (pokemon, one-piece, sports, riftbound)

GET/v1/indices/{game}/series

Daily index value line (base 10000) plus that day's turnover/count and rebalance markers. Drill into a marker with /v1/indices/{game}/rebalance/{date}.

game: required · path · an indexed game slug (pokemon, one-piece, sports, riftbound)

GET/v1/indices/{game}/rebalance/{date}

Basket behind one rotation point: membership for that snapshot day, plus cards that rotated in and out.

game: required · path · an indexed game slug (pokemon, one-piece, sports, riftbound)
date: required · path · snapshot day as YYYY-MM-DD (UTC)

GET/v1/items/featured

Top-mover card tiles across the indexed games (largest 7-day price move).

GET/v1/items/summaries

Batch card summaries for a list of catalog ids in one round-trip. The mobile scan hydrate fallback and watchlist/portfolio reads use this (not the legacy /v1/cards/summaries alias, which is not a partner contract).

ids: query · comma-separated catalog item ids (max 300; omitted returns [])

GET/v1/items/{game}/{set}/{item}

Card detail for one printing at a specific grade (the graded path slug).

game: required · path · one of pokemon, one-piece, sports, lorcana, digimon, riftbound, mtg, yugioh, gundam
set: required · path · the set slug
item: required · path · the card slug, including a grade token when priced at a grade

GET/v1/items/{game}/{set}/{item}/similar

More cards from the same set.

game: required · path
set: required · path
item: required · path

GET/v1/items/{game}/{set}/{item}/trades

Trade history for one card. Optional source / window / scope / limit query flags — see Swagger.

game: required · path
set: required · path
item: required · path

GET/v1/items/{game}/{set}/{item}/series

Daily-average price points (completed sales vs active listings) over a window.

game: required · path
set: required · path
item: required · path

GET/v1/items/{game}/{set}/{item}/fmv-series

Daily fair-market-value line plus per-day sales broken down by source. Powers the card price chart.

game: required · path
set: required · path
item: required · path

GET/v1/items/by-id/{id}

Card detail by catalog id (items.id). Same payload family as the path-slug detail route.

id: required · path · catalog UUID

GET/v1/items/by-id/{id}/overview

All-grades overview by catalog id.

id: required · path · catalog UUID

GET/v1/items/by-id/{id}/trades

Trade history by catalog id.

id: required · path · catalog UUID

GET/v1/items/by-id/{id}/series

Price series by catalog id.

id: required · path · catalog UUID

GET/v1/items/by-id/{id}/fmv-series

Daily FMV series by catalog id.

id: required · path · catalog UUID

GET/v1/items/by-renaiss-id/{rid}

Resolve an upstream Renaiss item id to a site-relative /card/… href (not an API path). For the card payload use /detail or /v1/cards/by-renaiss-id/{rid}.

rid: required · path · items.renaiss_item_id

GET/v1/items/by-renaiss-id/{rid}/detail

Full card detail by upstream Renaiss item id.

rid: required · path · items.renaiss_item_id

GET/v1/items/by-renaiss-id/{rid}/overview

All-grades overview by upstream Renaiss item id.

rid: required · path · items.renaiss_item_id

GET/v1/items/by-renaiss-id/{rid}/trades

Trade history by upstream Renaiss item id.

rid: required · path · items.renaiss_item_id

GET/v1/items/by-renaiss-id/{rid}/series

Price series by upstream Renaiss item id.

rid: required · path · items.renaiss_item_id

GET/v1/items/by-renaiss-id/{rid}/fmv-series

Daily FMV series by upstream Renaiss item id.

rid: required · path · items.renaiss_item_id

GET/v1/cards/by-renaiss-id/{rid}

Card detail by upstream Renaiss item id (documented sibling of /v1/items/by-renaiss-id/{rid}/detail). Other /v1/cards/* path aliases exist for shipped clients but are not a second partner contract.

rid: required · path · items.renaiss_item_id

GET/v1/sets/{game}/{set}

Every card tracked in a set, keyed by the set slug (the second path segment of a card href).

game: required · path · one of pokemon, one-piece, sports, lorcana, digimon, riftbound, mtg, yugioh, gundam
set: required · path · the set slug

GET/v1/trades/recent

Cross-card live trade feed, newest first.

GET/v1/search

Search by text, legacy character, or canonical tags. Repeat tag=mood:sleeping&tag=color:blue for an AND intersection, including same-kind tags. Omitted tag preserves ordinary search; tag=, empty/whitespace-only or unknown/inactive slugs return an empty results array. Slugs are exact and case-sensitive; the first colon separates kind and slug. Global/same-game duplicate links count once. Only active tags on live imaged public items appear. Short text can browse by tag or character; no item pagination or total.

q: optional · query · up to 80 characters; minimum 2 without a tag or character
tag: optional · repeatable kind:slug · at most 8 raw occurrences, 160-character tokens and 120-character slugs; malformed kinds/controls/bounds return 400
character: optional · legacy roster slug/alias; unknown falls back to q within any required tags. tag=character uses the separate tag vocabulary
game: optional · scopes tags and legacy character; AND with a game in q. No effect without either filter; unknown game is 400
limit: optional · result limit, default 12, maximum 30

GET/v1/tags

Discover linked public choices, for example /v1/tags?kind=mood&q=sleep. Returns only tags (kind, slug, name) and hasMore from one extra eligible distinct choice. Eligible global names win over scoped duplicates; exact canonical slugs rank first. Refine the prefix when more choices exist. No private provenance, full count or vocabulary export; at most 100 choices, under 160 KiB. Empty coverage is an empty success; an unavailable scan is an error.

kind: required · existing facet, such as mood, color or character
q: optional · literal case-insensitive name/slug prefix, at most 120 characters; %, _ and backslash are literal
game: optional · public catalog game; global and same-game tags apply
limit: optional · decimal integer 1..100, default 50. Invalid input, controls and repeated scalar parameters return 400

POST/v1/search/by-image

Upload a card photo; the server runs image-index /prepare-embed (crop + OCR + DINOv3) and returns ranked catalog ids plus a confidence band. Pass ?hydrate=1 for inline summaries (items), otherwise follow up with /v1/items/summaries. Rate-limited even for the index website.

file: required · multipart/form-data · the card photo, ≤ 15 MB

POST/v1/search/by-embedding

Vector sibling of by-image: POST a MobileCLIP-S2 embedding (512 floats, model mobileclip-s2) instead of a photo. The photo never leaves the device. This is the mobile Local Embed path. Same hydrate contract as by-image.

embedding: required · JSON body · 512-float L2-normalized MobileCLIP-S2 vector

POST/v1/search/by-image/bulk

Upload up to 12 card crops as repeated items parts; each part is searched in one request. Rate-limited as one request however many parts it carries.

items: required · multipart/form-data · repeated image parts (legacy alias: cards), max 12

POST/v1/search/detect-items

Locate the cards in a photo (bounding boxes) without ranking the catalog. The mobile scan crop path uses this family; a legacy /v1/search/detect-cards alias exists but is not a partner contract.

file: required · multipart/form-data · the photo

POST/v1/partners/apply

Public partner-application form. Separate intake quota (not the anonymous 10/day data-read budget).

POST/v1/report

Public data-issue report. Separate intake quota.

GET/v1/health

Liveness probe. Never cached. Also served at GET /health.

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/items/…/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), year (the card’s publication year — check it against the one printed on the slab label; null when the catalog holds no year) and href. Every card also carries its two identities: id — the catalog id you feed straight into /v1/items/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 a reason says why. When the cert resolved to a card we track but cannot price — reason: no_grade_price (a grade outside the scale we price, e.g. CGC 7.5) or reason: deactivated (voided by the grader) — the card is still there with its identity and href, grade null and every price field null. Card presence does not follow from the reason: a reason: deactivated cert whose game we do not track carries no card, while a cert that DID resolve to one keeps it under a later reason: needs_photo, reason: compute_incomplete or reason: company_unsupported too. Branch on the card itself, not on the reason.
/v1/graded/by-image — the same object, delivered as the terminal result SSE event.

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

The field walkthrough above is for overview and graded lookup. Every other listed route uses its own schema — read it in Swagger / OpenAPI rather than inferring from these three.

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 (offers is an AggregateOffer over live public 30-day listings, omitted whenever none exist)
Grade-less overview	/card/{game}/{set}/{card} · slug has no grade token	+ BreadcrumbList · Product · ItemList (ItemList omitted when no grades are tracked)
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
About	/about	+ AboutPage

Offers come from live listings only — never the reference price

The reference price is never an offer. It is a modeled fair-market value derived from recorded sales, and the sale counts are past completed trades — nothing is purchasable from us at that URL, so publishing either as an Offer or AggregateOffer would assert a live price we do not have.

What a graded card page does carry, only while at least one live listing exists, is an honest AggregateOffer under Product.offers: an aggregate of live marketplace listings observed in the last 30 days — the same public slice any signed-out visitor can read on the page. It publishes lowPrice, highPrice and offerCount in USD and nothing else: no per-listing Offer nodes, no seller, no listing URL. With no live listing the offers key is absent entirely, and deeper trade history (90-day / all-time, which requires approved access) never appears in structured data.

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.

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.