Skip to main content
POST
Scan a card
POST /v1/scan identifies a trading card from a photo of it. Send a roughly straight-on photo of a single card. You get back the closest catalog matches, each with a confidence score. The card does not have to fill the frame, since the service locates it and reads it up close, but the more of the frame it fills the better: the collector number is the smallest print on the card, and it is what pins the match.

Send a file

Send multipart/form-data with the photo in an image field (max 10 MB):

Send a URL

Send application/json with a publicly reachable https URL (max 10 MB, no redirects):

The printed identity

The image is the entire request. There are no fields for the card’s name, number or set code, and that is deliberate: reading those off the card is the work you are calling this endpoint to do. The scan identifies the card two ways at once: the printed identity (name, collector number, set code) read from the photo, and visual similarity against the catalog. A legible print pins the match to the cards that agree with it, which keeps lookalikes out of matches; the similarity ranks what is left. An unreadable print costs nothing: similarity decides alone, less sharply. The collector line is small print, so a sharper photo turns a close visual race into a single answer. Anything read that matches no card is discarded rather than trusted, and any extra keys you send are ignored.

The response

  • score is a similarity from 0 to 1, higher is better. Matches are best-first.
  • A confident scan returns a single match. A close race returns up to five, so show them and let the user pick.
  • An empty matches (with "game": null) is a valid 200, not an error, and unidentified then says which kind of “don’t know” it was.
  • Photos are not stored.

When nothing matched

The scan returns nothing rather than a guess. A card it cannot read and cannot recognise scores about the same against thousands of unrelated cards, so a list built from that is noise wearing a confidence score, which is worse than an empty answer because an app cannot tell the two apart.
unidentified is null whenever matches is non-empty.

Errors

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

image
file
required

Response

Identification result. Empty matches with a null game is a valid outcome: nothing cleared the confidence floor.

data
object
required
error
object | null
required