Skip to content
ZEROPOP

Connector reference

ZeroPop connector
documentation.

The ZeroPop connector is a read-only HTTP API that returns trading card identity and market value. It is built to be called by an AI agent on a user's behalf: four GET operations, JSON responses, no write path of any kind. It is free to use and requires no authentication.

The document

API document URL

OpenAPI document

https://api.zeropop.app/v1/connector/openapi.json

The document is OpenAPI 3.0.3. It is served publicly and requires no key to fetch or to use. Point any agent platform that accepts a custom connector at that URL and it has everything it needs: the four operations, their parameters and their response shapes.

Authentication

None

There is no API key, no account and no OAuth flow. Every operation is public and anonymous.

Because the API is read-only and anonymous, no user data is sent to ZeroPop and nothing about the caller is stored. A request carries a card name or an identifier, and that is all.

Reference

Operations

Four operations, all GET. The usual sequence is search, then fetch the card you matched, then walk out to its set if the question needs it.

GET /v1/public/search

operationId: searchPublicCatalog

Finds cards in the catalog by name. This is the entry point: every other operation takes an identifier that comes out of a search hit.

Important: matching is name-prefix only

Pass the card name and nothing else. The search matches on the start of the card name, so appending a card number, a set name or a year returns an empty list rather than a narrower one.

Searching for "Charizard" returns results. Searching for "Charizard 4/102" returns none.

To narrow to a specific printing, search the name alone and then pick the right hit out of the results by its setName, cardNumber, variant and finish.

Parameters

q
The card name. Minimum 2 characters. Required.
limit
Number of hits to return. Default 24, maximum 48.

Response

hits[]
The matches, best first. Each hit carries a card object plus the fields below.
heroImagePath
Path to a representative image of the card, when one exists.
heroScanId
Identifier of the collector scan that image came from, when one exists.
  • Each hit contains a full card object. The fields of that object are listed under The card object below.

GET /v1/public/cards/{cardKey}

operationId: getPublicCard

Returns one card in full, together with the real collector scans recorded against it.

Parameters

cardKey
Path parameter. Take it from the card object of a search hit. Do not construct one.

Response

card
The card object, described below.
scans[]
Scans collectors have run on this card, each with its grade. These are real results, not predictions.
  • An unknown cardKey returns 404.

GET /v1/public/sets/{setId}

operationId: getPublicSet

Returns one set and the cards it contains.

Parameters

setId
Path parameter. Take it from the setId field of a card whose setId is not null.

Response

name
Set name.
year
Year of the set.
releaseDate
Release date of the set.
cardCount
Number of cards in the set.
cards[]
The cards in the set, as card objects.
  • Many cards have no setId at all, sports cards especially. When setId is null, this operation cannot be called for that card.
  • Never guess or assemble a setId. Only a value read from a card object is valid.
  • An unknown setId returns 404.

GET /v1/public/sets/{setId}/scans

operationId: getPublicSetScans

Returns recent collector scans from across one set.

Parameters

setId
Path parameter, subject to the same rule as above.
limit
Number of scans to return. Default 24, maximum 100.

Response

scans[]
Collector scans from the set, each with its grade.
  • This operation differs from the others: an unknown setId returns 200 with an empty scans array, not a 404.

Schema

The card object

The same object comes back from search hits, from the card operation and from the cards in a set. Any field can be null when we do not hold that detail for the card.

cardKey
Identifier for the card. Pass it to getPublicCard.
cardName
Printed name of the card.
setName
Name of the set the card belongs to.
setId
Identifier of the set, or null. Only a non-null value can be passed to the set operations.
cardNumber
Collector number as printed on the card.
year
Year of the printing.
rarity
Rarity as printed or as catalogued.
variant
Which version of the card this is, when a card has more than one (for example a promo or an alternate art).
finish
Surface finish, for example holofoil or reverse holo.
game
The game or category the card belongs to, for example Pokemon or a sport.
lastSeenPrice
Most recent market value in US dollars. May be null when we have no priced comp for the card.
priceSource
Where that value came from.
priceHistory
Array of points shaped {t, p}, where t is a timestamp and p is a price in US dollars.
slug
URL segment for the card page on zeropop.app.
tcgplayerId
TCGplayer product identifier, when one is known.
justTcgCardId
Legacy catalog identifier, retained for cards that carry one.
setReleaseDate
Release date of the set the card belongs to.
setCardCount
Number of cards in that set.

Results

Empty results and errors

An empty hits array is a definitive answer, not an error. It means the card is not in the ZeroPop catalog. The correct response is to say so. Do not estimate a price for that card from another source and present it as a ZeroPop answer.

Before concluding a card is absent, check the query: a name with a card number or a set appended returns nothing for a card that is in the catalog under its name alone.

200
Success. The body may still contain an empty list.
404
Unknown card or unknown set.
429
Rate limited. Wait and retry shortly.

Error responses carry a JSON body with an error field and a message field.

Limits

Rate limits

Requests are limited per network. Normal conversational use sits far below the limit, so a person asking about cards will not reach it. If a request returns 429, wait a short time and retry.

Scope

Coverage

Covered

  • Pokemon
  • Yu-Gi-Oh
  • Disney Lorcana
  • One Piece
  • Sports cards: baseball, basketball, football and others

Not covered

  • Magic: The Gathering. The catalog does not carry it, and the API will return nothing for it.

The boundary is stated plainly here rather than left implicit, because an agent that does not know where the catalog ends will fill the gap with an invented answer.

Provenance

Where the data comes from

The API is served from ZeroPop's own catalog, built out of the cards ZeroPop users have scanned and graded. Pricing is derived from settled sales ZeroPop observes, meaning what a card actually sold for, rather than from asking prices on open listings.

Accuracy note: prices are estimates drawn from observed sales and recent catalog data, not appraisals. Grades returned with a scan are real collector scan results, not a prediction of what a professional grading company would assign.

Support

Contact and policies

Questions about the connector, or a card the catalog is missing, go through the contact page.

ContactPrivacy policyTerms of service
Back to the Muse setup page