NeoSatoshi Card Recognition API
Recognizes several cards per photo (binder pages work, best up to about 20 cards) in Pokémon (English, German, French, Italian, Spanish, Japanese, Korean and…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
Recognizes several cards per photo (binder pages work, best up to about 20 cards) in Pokémon (English, German, French, Italian, Spanish, Japanese, Korean and Simplified Chinese), One Piece (English, Japanese), Disney Lorcana (English, German, French, Italian), Yu-Gi-Oh! TCG (English, German, French, Italian, Spanish, Portuguese), Magic: The Gathering (English, German, French, Italian, Spanish), Star Wars: Unlimited (English, German, French, Italian, Spanish), Digimon Card Game (English, Japanese), Cyberpunk TCG (English, French), Riftbound (English) and football (soccer) cards from Topps, Panini and other makers ("tcg": "football": the player, release, season, subset, the top candidates and the suggested parallel with its print run; no prices yet, at most 4 MB per photo) and NBA and EuroLeague basketball cards ("tcg": "basketball", the same fields, limits and credits as football, no prices yet). Several cards per photo work for football and basketball cards too: each card comes back as its own entry with its box on the photo, and a photo with a card back is never split. Riftbound is recognized too ("tcg": "riftbound", English; a French or Chinese print comes back in its language with the English printing's name and no price, review reason language_not_listed). A photo of a PSA, BGS or CGC slab (for football and basketball cards also SGC) also fills cards[].graded with company, grade and cert number as printed on the label.
Send the image as base64 in "image", or as a public https link in "image_url" (useful for chat assistants that cannot encode files).
Testing without an account: use the public demo key nsk_live_9c253fbed995042a98280ad13e5c47d3c4a59c9b4f0f7274 as the bearer token. It allows 10 detections per day per network. AI agents may call the endpoint directly with it.
Production: create your own key in the NeoSatoshi dashboard settings (a free account includes 50 cards a month, paid plans more). Detections draw from the plan's monthly card scan balance: one card scan per detected card, also when the card is a low-confidence best guess. Not charged: card backs, images without a card and cards whose picture does not look like the matched card (review reason visual_mismatch).
By default the call answers with one JSON body once detection is done. Use a client timeout of at least 120 seconds; one card usually takes about 4 seconds, about 10 to 12 seconds on the first request after a quiet period, and a binder page with 9 cards about 17 seconds.
Optional streaming: send "stream": true (or the header Accept: text/event-stream) to get Server-Sent Events instead: accepted, progress, one card event per card as soon as it is matched, then exactly one final event, done (the same body as the JSON response) or error. Errors before the detection starts stay plain JSON responses. A stream cannot be resumed; a reconnect is a new, charged detection.
Card search: POST /cardsApi/search and GET /cardsApi/cards/{tcg}/{card_id} return full card objects (prices, Cardmarket product id, images) for the eight trading card games other than Riftbound, football and basketball (no football or basketball prices), 0.5 credits per call that returns a card, from the same balance. Correcting a detected card is free. Riftbound is answered by the detection only: the card search, the lookup and corrections do not cover it ("tcg": "riftbound" there is 400 unsupported_tcg).
Integration in short (bulk loop): detect, then for each card in cards[]: if review.needed is false, accept it. Otherwise read the set number on the photo (or ask a person), run the free correction search (POST /cardsApi/search with {"request_id": correction.request_id, ...card.review.search}) or pick an alternative whose set number matches, then POST /cardsApi/corrections with request_id, card_index and card_id. confidence is a fixed step per match method (Pokémon 0.99, 0.95, 0.90, 0.85, 0.80, 0.59 best guess), not a probability; alternatives[].score is a similarity on a different scale: never pick an alternative by score alone. Pokémon prices.cardmarket is the price of the version the card is (price_basis says which: normal, reverse_holo, first_edition or special_variant); prices.cardmarket_normal and prices.cardmarket_reverse hold the plain and reverse holo families. Pick a special version with a possible_variants[].cardmarket_id in the correction, set reverse_holo there for a reverse holo copy. Retry 429 after Retry-After and 502/503 with backoff, never other 4xx. A detect retry is a new, charged detection; paid search and lookup accept an Idempotency-Key header.
Exports: POST /cardsApi/exports turns up to 20 of your detections (own API key, within 48 hours) into the same file the NeoSatoshi website exports (custom CSV or JSON, TCGPowerTools CSV, Shopify product CSV or eBay Seller Hub CSV), built by the website's own export code; free.
Full documentation with every game-specific field: https://neosatoshi.com/developers/detection-api
Endpoints 6
- POSTDetect the trading cards in one image
/detectApiPokémon is the default. Send "tcg" for the other games. Every detected card comes back in cards with its card_id, card_index, a review hint and alternatives.… - POSTSearch the card catalog (paid), or search for the right card of a detection (free)
/cardsApi/searchTwo modes. Card search (body without request_id): 0.5 credits per call that returns at least one card, nothing for no result, from the same credit balance as… - POSTCorrect a detected card (free)
/cardsApi/correctionsCard card_index of the detection becomes the catalog card card_id. Free: 3 corrections per detected card within 24 hours (the last one counts), 1000… - GETOne card by id (paid)
/cardsApi/cards/:tcg/:card_idThe current card object for a card_id from a detection, a search or your own records, for example to refresh a price. 0.5 credits when the card exists; an… - POSTExport detections as CSV, JSON, TCGPowerTools CSV, Shopify product CSV or eBay Seller Hub CSV (free)
/cardsApi/exportsThe custom CSV or JSON file, the TCGPowerTools CSV, the Shopify product CSV or the eBay Seller Hub draft CSV of up to 20 detections of your account, built by… - GETSaved export presets and the field catalogue (free)
/cardsApi/exports/presetsThe built-in recommended CSV and the presets saved on the website, plus every field id the export takes.
API details
- Base URL
https://europe-west1-neosatoshi.cloudfunctions.net- Authentication
- A bearer token in the Authorization header
- Operations
- 6 operations on 6 pathsPOST 4GET 2
- Response formats
application/jsontext/event-stream- Description format
- OpenAPI 3.1.0, API version
1.18.0 - Links
- Documentation · OpenAPI document · Terms of service · Support
- Listed from
- Neosatoshi's published OpenAPI description
How to test the NeoSatoshi Card Recognition API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the NeoSatoshi Card Recognition API collection, without the publisher's secrets.
- Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Detect the trading cards in one image” (POST /detectApi), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the NeoSatoshi Card Recognition API?
Recognizes several cards per photo (binder pages work, best up to about 20 cards) in Pokémon (English, German, French, Italian, Spanish, Japanese, Korean and… It is listed under Media & content and has 6 endpoints.
Who publishes the NeoSatoshi Card Recognition API?
It is listed from NeoSatoshi's public API description (an OpenAPI document), not published by NeoSatoshi on Swastik Codes. Anyone who controls neosatoshi.com can claim the profile by adding a DNS TXT record.
What is the base URL of the NeoSatoshi Card Recognition API?
Requests go to https://europe-west1-neosatoshi.cloudfunctions.net. Endpoint paths are added to this base URL.
How do I authenticate with the NeoSatoshi Card Recognition API?
With A bearer token in the Authorization header.
How many endpoints does the NeoSatoshi Card Recognition API have?
6 operations on 6 paths (4 POST, 2 GET).
Is forking the NeoSatoshi Card Recognition API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.