/collection/itemsA copy of a catalog issue (and edition, when you know it). Find the issue with GET /catalog/search or /catalog/barcode, or the edition with GET /catalog/editions. Prices are Money; the copy’s currency is its purchase price’s (else your preferred currency), and its other amounts must be in it. With a clientKey you’ve used before, nothing is added and the answer is that copy (200).
collector.createCopy()collection: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.
statusenumowned (default) or sold. Wishes are added with POST /wishlist.
default "owned"
ownedsoldgradenumber 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
salePriceMoneyInput or nullSold copies: what it sold for.
soldOnstring (date) or nullforTradebooleanaskingPriceMoneyInput 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
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 copy with that clientKey.
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)required201CreatedAdded.
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).
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_issuecurrency_mismatchinvalid_copy
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.
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).