Documentation

API reference & playground

A REST API that identifies trading cards from a photo — and tells you when it isn't sure instead of guessing.

Try it live Error reference Get an API key

Authentication

Bearer token authentication

Every request to /api/v1/* is authenticated with an API key issued from your dashboard, sent as a standard Bearer token.

Create a key on /dashboard/keys after signing up, then attach it to every request as Authorization: Bearer <key>. Keys are scoped to your account and count against your plan's monthly request allotment and rate limit.

Header

Authorization: Bearer cv_live_xxxxxxxxxxxxxxxx

Endpoint

POST /api/v1/identify

Send a card image and get back a structured identity — or an honest needsReview when we can't corroborate a match.

One call. Front image in, structured identity out.

curl -X POST https://aicardvault.io/api/v1/identify \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -F front=@card.jpg \
  -F category=pokemon

Example response

{
  "ok": true,
  "result": {
    "card": {
      "name": "Charizard ex",
      "set": "Obsidian Flames",
      "number": "125/197",
      "year": "2023",
      "rarity": "Double Rare",
      "language": "en"
    },
    "confidence": 0.94,
    "needsReview": false
  }
}

Request body

Accepts either a JSON body with an image URL, or a multipart/form-data upload with front / optional back file fields plus the same category, sport, and language fields as form data. Both shapes hit the same endpoint.

frontImageUrlstring, required*

A public https URL for the card's front image, fetched server-side. *Required for JSON requests; use the front file field instead for multipart uploads.

backImageUrlstring, optional

A public https URL for the card's back image. Improves accuracy on sets where the back disambiguates print runs.

categoryCardCategoryHint, optional

A hint like pokemon, mtg, baseball, etc. Narrows the search space and improves both speed and accuracy — pass it whenever you know the game or category.

sportstring, optional

Free-text sport hint, used alongside a sports category hint.

languageLanguageHint, optional

ISO-ish language hint (en, ja, ko, zh, de, fr, es, it, pt) — most useful for TCGs printed in multiple languages, like Pokémon.

lockSetIdstring, optional

Constrain matching to a specific known set id when you already know it — skips ambiguity across reprints.

Response shape — IdentifySuccess

A 200 response always has this envelope. Errors use a different shape — see the error reference.

oktrue

Always true on success — check this to discriminate from an error body.

requestIdstring

Opaque id for this request, useful when contacting support about a specific call.

result.cardIdentifiedCard | null

The confidently-identified card — name, set, number, year, rarity, category, language. NULL when uncertain; that's the honest miss, not an error.

result.confidencenumber (0–1)

Calibrated P(correct) for the returned card (or for the best rejected candidate on a miss).

result.needsReviewboolean

True whenever card is null — confidence was below our floor or an adjudicator dissented. Treat as 'ask the user to confirm,' not an error; it's still HTTP 200.

result.reviewReasonstring | null

Short human-readable reason a review was needed, present when needsReview is true.

result.sourceIdentitySource | null

Abstracted provenance of the match: catalog, vendor_network, web_corroboration, discovery, or cache. Null on a pure miss.

result.alternatesAlternateMatch[]

Ranked best-guess candidates (name, set, number, confidence, source) — ideal for a 'is this your card?' picker when needsReview is true.

result.pricingCardPricing | null

Plan-gated best-effort market pricing (raw + graded) for the matched card. Null on Free plan or when unavailable.

result.referenceIdstring | null

Opaque token identifying this result — pass it back to POST /api/v1/feedback to correct or confirm the match.

meta{ latencyMs, cached, model, imageHash }

Request metadata: processing latency, whether it was an exact-image cache hit, an abstract model label, and a hash of the input image.

Endpoint

POST /api/v1/feedback

Confirm or correct a result to feed the accuracy flywheel — corrections re-index nightly and improve future matches.

Request body — FeedbackRequest

referenceIdstring, required

The referenceId returned from the identify call you're confirming or correcting.

wasCorrectboolean, required

True if the returned card (or top alternate) was right; false if it was wrong or the call needed review.

correctNamestring, optional

The correct card name, when wasCorrect is false and you know the answer.

correctSetstring, optional

The correct set name, when known.

correctNumberstring, optional

The correct card number within its set, when known.

Example request

curl -X POST https://aicardvault.io/api/v1/feedback \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceId": "ref_9f2a...",
    "wasCorrect": false,
    "correctName": "Charizard ex",
    "correctSet": "Obsidian Flames",
    "correctNumber": "125/197"
  }'

// 200 OK
{
  "ok": true,
  "requestId": "req_3b7c..."
}

A miss is still a 200

needsReview:true with card:null means we couldn't confidently identify the card. It's still an HTTP 200. Best guesses appear in the alternates array with per-candidate confidence, ideal for a 'Is this your card?' picker. Treat it as 'ask the user to confirm,' not as an error.

Try it

Live playground

Call the real gateway with your own API key and image URL. Nothing here is mocked — you're hitting the same endpoint your integration will use.

Fill in an API key and image URL, then send a request to see a live response.

Seeing an error? Check the error reference — new keys and freshly deployed routes can take a moment to warm up.