The issues a collector is looking for, and moving one into the collection once found.
/wishlistThe issues you’re looking for, most wanted first by default.
collector.listWishes()wishlist:readIf-None-MatchX-Request-IdcursorstringThe nextCursor of the previous page. Omit for the first page.
at most 1000 characters
limitintegerItems per page, 1–200 (default 50).
1–200 · default 50
sortstringSort by priority, createdAt, updatedAt, title; a leading "-" sorts descending, a comma adds a tiebreak. Default priority.
at most 200 characters
filter[series]string (uuid)Wishes for this series’ issues.
filter[issue]string (uuid)Wishes for this issue.
filter[publisher]string (uuid)Wishes for this publisher’s books.
filter[priority]integerThis priority (1 most wanted).
1–3
filter[tag]string1–100 characters
filter[q]stringWords from the series, title, number or notes; or a barcode, ISBN or distributor code.
1–200 characters
filter[updatedSince]string (date-time)Only rows changed at or after this time: sync what changed since your last run.
at most 64 characters
200OKA page of wishes.
object
nextCursorstring or nullrequiredPass as ?cursor= for the next page; null on the last page.
304Not ModifiedNot modified: your copy (the ETag in If-None-Match) is current.
invalid_requestinvalid_cursorinvalid_filterinvalid_sort
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_cursor: The cursor isn’t one this list (in this order) gave out.
invalid_filter: A filter[field] the list doesn’t have, or a value it refuses.
invalid_sort: A sort field the list doesn’t have.
unauthorized: Not signed in (no session or token, or an expired one).
rate_limitedtemporarily_blocked
rate_limited: Over the caller’s limit: the per-minute burst or the per-day quota (RateLimit headers; wait Retry-After seconds).
temporarily_blocked: Too many refused requests in a row: blocked for a while (Retry-After says how long).
internal: Something went wrong on our side (quote the requestId).
/wishlistAn issue (or one edition of it) you’re looking for, with how much you want it, the lowest grade you’d take and the most you’d pay. Shops’ matching listings show in your notifications.
collector.createWish()wishlist:writeIdempotency-KeyX-Request-IdissueIdstring (uuid)requiredThe catalog issue (GET /catalog/issues, /catalog/search).
editionIdstring (uuid) or nullThe edition (cover, printing) of that issue; null when not known yet.
wishWishInputtagsarray of stringat most 30 items
notesstring or nullat most 32000 characters
isHiddenbooleanHidden from your public profile.
clientKeystringYour id for this copy (8–80 characters), unique in your collection: a second create with the same key finds the first copy instead of adding another.
8–80 characters
200OKAlready there: the wish with that clientKey.
An issue (or edition) on your wishlist.
idstring (uuid)requiredcoverUrlstring (uri) or nullrequiredcurrencystringrequiredwishobjectrequiredpriorityinteger or nullrequired1 (most wanted) to 3.
minGradenumber or nullrequiredtagsarray of stringrequirednotesstring or nullrequiredisHiddenbooleanrequiredcreatedAtstring (date-time)requiredupdatedAtstring (date-time)required201CreatedAdded.
An issue (or edition) on your wishlist.
idstring (uuid)requiredcoverUrlstring (uri) or nullrequiredcurrencystringrequiredwishobjectrequiredpriorityinteger or nullrequired1 (most wanted) to 3.
minGradenumber or nullrequiredtagsarray of stringrequirednotesstring or nullrequiredisHiddenbooleanrequiredcreatedAtstring (date-time)requiredupdatedAtstring (date-time)requiredinvalid_requestinvalid_jsoninvalid_idempotency_key
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
invalid_idempotency_key: The Idempotency-Key isn’t 1–255 visible ASCII characters.
unauthorized: Not signed in (no session or token, or an expired one).
idempotency_in_progresscollection_limitclient_key_in_use
idempotency_in_progress: The first request with this key is still running.
collection_limit: Your collection is at its size limit (250,000 rows unless raised).
client_key_in_use: The clientKey names a row of the other kind (a wish, not a copy, or the reverse).
payload_too_large: The body is over 1,048,576 bytes, this operation’s limit.
idempotency_key_reusedissue_not_foundedition_not_of_issue
idempotency_key_reused: This key was used for a different request.
issue_not_found: No catalog issue with that issueId.
edition_not_of_issue: The editionId isn’t one of that issue’s editions.
rate_limitedtemporarily_blocked
rate_limited: Over the caller’s limit: the per-minute burst or the per-day quota (RateLimit headers; wait Retry-After seconds).
temporarily_blocked: Too many refused requests in a row: blocked for a while (Retry-After says how long).
internal: Something went wrong on our side (quote the requestId).
/wishlist/{id}One wish.
collector.getWish()wishlist:readIf-None-MatchX-Request-Ididstring (uuid)required200OKThe wish.
An issue (or edition) on your wishlist.
idstring (uuid)requiredcoverUrlstring (uri) or nullrequiredcurrencystringrequiredwishobjectrequiredpriorityinteger or nullrequired1 (most wanted) to 3.
minGradenumber or nullrequiredtagsarray of stringrequirednotesstring or nullrequiredisHiddenbooleanrequiredcreatedAtstring (date-time)requiredupdatedAtstring (date-time)required304Not ModifiedNot modified: your copy (the ETag in If-None-Match) is current.
unauthorized: Not signed in (no session or token, or an expired one).
not_found: Nothing at that address.
wish_not_found: No wish of yours with that id.
rate_limitedtemporarily_blocked
rate_limited: Over the caller’s limit: the per-minute burst or the per-day quota (RateLimit headers; wait Retry-After seconds).
temporarily_blocked: Too many refused requests in a row: blocked for a while (Retry-After says how long).
internal: Something went wrong on our side (quote the requestId).
/wishlist/{id}Takes it off your wishlist.
collector.deleteWish()wishlist:writeX-Request-Ididstring (uuid)required200OKRemoved.
object
ok"true"requiredunauthorized: Not signed in (no session or token, or an expired one).
not_found: Nothing at that address.
wish_not_found: No wish of yours with that id.
rate_limitedtemporarily_blocked
rate_limited: Over the caller’s limit: the per-minute burst or the per-day quota (RateLimit headers; wait Retry-After seconds).
temporarily_blocked: Too many refused requests in a row: blocked for a while (Retry-After says how long).
internal: Something went wrong on our side (quote the requestId).
/wishlist/{id}Its priority, lowest grade, target price, edition, tags or notes.
collector.updateWish()wishlist:writeX-Request-Ididstring (uuid)required200OKThe wish as it is now.
An issue (or edition) on your wishlist.
idstring (uuid)requiredcoverUrlstring (uri) or nullrequiredcurrencystringrequiredwishobjectrequiredpriorityinteger or nullrequired1 (most wanted) to 3.
minGradenumber or nullrequiredtagsarray of stringrequirednotesstring or nullrequiredisHiddenbooleanrequiredcreatedAtstring (date-time)requiredupdatedAtstring (date-time)requiredinvalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
unauthorized: Not signed in (no session or token, or an expired one).
not_found: Nothing at that address.
wish_not_found: No wish of yours with that id.
payload_too_large: The body is over 1,048,576 bytes, this operation’s limit.
currency_mismatchedition_not_of_issue
currency_mismatch: An amount isn’t in the copy’s currency (details: field, currency, expected).
edition_not_of_issue: The editionId isn’t one of that issue’s editions.
rate_limitedtemporarily_blocked
rate_limited: Over the caller’s limit: the per-minute burst or the per-day quota (RateLimit headers; wait Retry-After seconds).
temporarily_blocked: Too many refused requests in a row: blocked for a while (Retry-After says how long).
internal: Something went wrong on our side (quote the requestId).
/wishlist/{id}/acquireThe wish becomes a copy you own, with what you know about it (what you paid, its grade, where it is). acquiredOn defaults to today.
collector.acquireWish()wishlist:writecollection:writeIdempotency-KeyX-Request-Ididstring (uuid)requiredgradenumber or null0.5–10
gradingCompanyenum or nullWho slabbed it; null for raw.
cgccbcspsapgxegshgaothercertNumberstring or nullat most 256 characters
pageQualityenum or nullwhiteoff_white_to_whiteoff_whitecream_to_off_whitecreamlight_tantanbrittleisSignedbooleansignaturesarray of stringat most 20 items
signatureAuthenticationenum or nullcgc_signature_seriescbcs_verifiedpsa_dnacoawitnessedunverifiedisRestoredbooleancopyLabelstring or nullYour own name for this copy, e.g. "Signed at NYCC".
at most 320 characters
purchasePriceMoneyInput or nullWhat you paid. Its currency is the copy’s.
acquiredOnstring (date) or nullacquiredFromstring or nullat most 800 characters
forTradebooleanaskingPriceMoneyInput or nullFor trade: what you’d take. In the copy’s currency.
ownValueMoneyInput or nullYour own value for it, used instead of the market estimate.
ownValueNotestring or nullat most 2000 characters
locationstring or nullWhere it is: a storage location’s name ("Long box 12"). A new name makes a new location.
at most 480 characters
readStatusenum or nullunreadreadingreadratinginteger or null1–5
tagsarray of stringat most 30 items
notesstring or nullat most 32000 characters
200OKThe copy it became.
A copy in your collection (owned or sold).
idstring (uuid)requiredstatusenumrequiredownedsoldcoverUrlstring (uri) or nullrequiredcurrencystringrequiredThe copy’s currency: its purchase, asking and own-value amounts are in it.
gradenumber or nullrequiredgradingCompanystring or nullrequiredcertNumberstring or nullrequiredcertStatusstring or nullrequiredpageQualitystring or nullrequiredisSignedbooleanrequiredsignaturesarray of stringrequiredsignatureAuthenticationstring or nullrequiredisRestoredbooleanrequiredcopyLabelstring or nullrequiredisLabeledbooleanrequiredIt has a printed QR label.
acquiredOnstring (date) or nullrequiredacquiredFromstring or nullrequiredsoldOnstring (date) or nullrequiredforTradebooleanrequiredvalueobjectrequiredWhat it’s worth (GET /insights/items/{id} has the history and the sales behind it).
Your own value when you set one, else the market estimate.
ownNotestring or nullrequiredmethodstring or nullrequiredconfidencenumber or nullrequiredupdatedAtstring (date-time) or nullrequiredlocationstring or nullrequiredtagsarray of stringrequirednotesstring or nullrequiredreadStatusstring or nullrequiredratinginteger or nullrequiredisHiddenbooleanrequiredcodesarray of stringrequiredBarcodes and other codes on it and its edition.
sourcestring or nullrequiredcreatedAtstring (date-time)requiredupdatedAtstring (date-time)requiredinvalid_requestinvalid_jsoninvalid_idempotency_key
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
invalid_idempotency_key: The Idempotency-Key isn’t 1–255 visible ASCII characters.
unauthorized: Not signed in (no session or token, or an expired one).
not_found: Nothing at that address.
wish_not_found: No wish of yours with that id.
idempotency_in_progress: The first request with this key is still running.
payload_too_large: The body is over 1,048,576 bytes, this operation’s limit.
idempotency_key_reusedcurrency_mismatchinvalid_copy
idempotency_key_reused: This key was used for a different request.
currency_mismatch: An amount isn’t in the copy’s currency (details: field, currency, expected).
invalid_copy: Values the copy can’t have together (a cert without its grader, a sale on a copy you own…).
rate_limitedtemporarily_blocked
rate_limited: Over the caller’s limit: the per-minute burst or the per-day quota (RateLimit headers; wait Retry-After seconds).
temporarily_blocked: Too many refused requests in a row: blocked for a while (Retry-After says how long).
internal: Something went wrong on our side (quote the requestId).