Card Clerk Scan API

Quick start

We send your API key separately. Keep it secret, and send it only in the Authorization header, over HTTPS.

curl https://vision.card-clerk.com/v1/scans \
  -H "Authorization: Bearer $CARD_CLERK_KEY" \
  -F "img=@card-0001.jpg" \
  -F "game=mtg" \
  -F "ref=card-0001" \
  -F "batch=box-7"

The same call in Python, with requests:

import os
import requests

try:
    with open("card-0001.jpg", "rb") as image:
        resp = requests.post(
            "https://vision.card-clerk.com/v1/scans",
            headers={"Authorization": f"Bearer {os.environ['CARD_CLERK_KEY']}"},
            files={"img": ("card-0001.jpg", image, "image/jpeg")},
            data={"game": "mtg", "ref": "card-0001", "batch": "box-7"},
            timeout=180,
        )
except requests.ConnectionError:
    resp = None  # refused while the API restarts: retry shortly
if resp is None or not resp.headers.get("content-type", "").startswith("application/json"):
    print("the API is restarting: retry shortly")  # refused, or a 502 from the server in front
elif resp.ok:
    answer = resp.json()
    print(answer["status"], answer["card"], answer["review_reasons"])
else:  # every error has an `error`; a refusal before the scan has no `status`
    answer = resp.json()
    print(resp.status_code, answer.get("status"), answer.get("error"))

The request

POST /v1/scans takes a multipart/form-data form with one image and the text fields below. Other text fields are ignored; a form may hold up to 16 text fields of up to 8 KB each.

Images

• JPEG, PNG, WebP, GIF (still), BMP or TIFF. JPEG works well.
• At most 20 MB and 25 megapixels.
• At least 32 pixels on the short side, and no more than 4 times longer than wide.
• Orientation: we apply the image's EXIF orientation, then turn it by the rotation agreed for your scanner (0°, 90°, 180° or 270°). If it is still landscape, we turn it 90° clockwise. If it finds no match, we try it once more turned 180°. Tell us if your scanner's direction changes.
• For Magic, a card back is recognised and answered card_back.

The answer

Every answer from the API is JSON. A scan the API could read comes back 200 with a status of matched, no_match or card_back. This example shows a Magic promo answered as its standard printing, flagged for review:

{
  "ref": "card-0001",
  "batch": "box-7",
  "scan_id": "6f1c2b9e-…",
  "status": "matched",
  "card": {
    "game": "mtg",
    "print_id": "…",
    "set_code": "stx",
    "set_name": "Strixhaven: School of Mages",
    "collector_number": "119",
    "variant_code": "",
    "name": "Accomplished Alchemist",
    "face": null
  },
  "card_confidence": 0.998,
  "printing_confidence": 0.978,
  "needs_review": true,
  "review_reasons": ["low_printing_confidence"],
  "candidates": [],
  "answered_base": true,
  "rotation_applied": 90,
  "alternatives": [
    {"print_id": "…", "set_code": "pstx", "collector_number": "119p", "variant_code": "",
     "relationship_type": "promo_alternative", "is_base": false, "label": "pstx-119p"},
    {"print_id": "…", "set_code": "pstx", "collector_number": "119s", "variant_code": "",
     "relationship_type": "promo_alternative", "is_base": false, "label": "pstx-119s · Alternate Art s"}
  ]
}

When an answer needs review

An answer with needs_review: true is still our best answer, but a person should confirm it. The reasons:

Statuses and errors

Every error answer from POST /v1/scans is JSON with an error sentence. A wrong path or method gets the web server's own 404 or 405, whose JSON has a detail instead. Once the API has your request, every answer also carries status, your ref (null where the form could not be read) and the scan_id of its record. The refusals before that (401, 411, an early 413, 429, and busy when 64 scans are in hand) are not recorded and carry no scan_id.

Limits and pacing

• Requests per minute: your key allows a set number of requests each clock minute. We give you the number with the key. Past it, you get 429.
• At a time: we identify 4 of your images at once. Send up to 4 together for the fastest answers. More wait their turn for up to 30 seconds, then answer busy.
• In hand: past 64 requests in progress at once, a new request is answered busy straight away, before its image is read. That answer does not count against your requests per minute.
• Timeouts: most answers take a second or two. Under load a scan can wait 30 seconds for its turn, and each of its two tries can take up to a minute, so we suggest a timeout of 3 minutes. That is not a hard limit: a scan you send again after giving up is a new scan, recorded and counted again.

Health check

GET /v1/ping needs no key and answers {"ok": true} while the API is up.

Your data

We keep a record of each request we take in: its time, your ref and batch, its status and the printing we answered. A request refused before we read it (a missing or unknown key, over your requests per minute, a request over 21 MB, or busy with 64 scans in hand) leaves no record. We also keep the image of a scan we read; we do not keep one we refuse as too large or for its fields, and under heavy load an image can be dropped while its record is kept. We use them to bill and to look into problems you report.