API reference / Collectors

Collection

A collector’s copies: what each copy is (issue, edition, variant) and its history, the codes on it, bulk changes, imports and the full export.

GET/api/v1/collection/export

Export the collection

Signed in

The whole collection as a file download, streamed: CSV (with a UTF-8 byte order mark, for spreadsheets) or JSON ({ format, version, exported_at, columns, items }). The columns round-trip through the importer. 20 exports an hour.

SDK: collector.exportCollection()
Key scopes: collection:read(API keys are coming soon)
Headers: X-Request-Id

Parameters

Name	In	Type	About
`format`optional	query	enum	Default csv.One of `csv`, `json`
`status`optional	query	enum	Only copies in this state.One of `owned`, `wishlist`, `sold`

Responses

200The file (Content-Disposition: attachment).
string

Errors (400, 401, 429, 500)

400invalid_request
invalid_request: The query or body doesn’t match the schema (see errors[]).
401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
429rate_limited
rate_limited: More than 20 exports an hour; wait the Retry-After seconds.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl 'https://collection.id/api/v1/collection/export' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

await collector.exportCollection({ query: { … } });

POST/api/v1/collection/imports/{id}/undo

Undo an import

Signed in

Removes the copies an import created that haven’t been edited since, with their photos, on every plan. Copies you added photos to stay unless includePhotographed is true. The body is optional. A very large import may answer done: false: call again to continue.

SDK: collector.undoCollectionImport()
Key scopes: collection:write(API keys are coming soon)
Headers: X-Request-Id

Parameters

Name	In	Type	About
`id`required	path	string (uuid)	The import’s id.

Request body (optional, application/json)

object

includePhotographedbooleanoptionaldefault false

Responses

200What this request removed, and what’s left.
object
- idstring (uuid)required
  The import.
- removedintegerrequired
  Copies removed by this request.
- removedTotalintegerrequired
  Copies removed by the whole undo so far.
- remainingintegerrequired
  Copies still to remove: call again while done is false.
- donebooleanrequired
- keptEditedintegerrequired
  Copies kept because they were edited after the import.
- keptPhotographedintegerrequired
  Copies kept because you added photos to them.
- photosRemovedintegerrequired

Errors (400, 401, 404, 409, 500, 503)

400invalid_request invalid_json
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404not_found import_not_found
not_found: Nothing at that address.
import_not_found: No import of yours with that id.
409import_already_undone undo_window_passed
import_already_undone: The import was already undone.
undo_window_passed: Imports can be undone for a limited time only.
500internal
internal: Something went wrong on our side (quote the requestId).
503not_available
not_available: Undo isn’t available until a database update is applied.

curl

curl -X POST 'https://collection.id/api/v1/collection/imports/<id>/undo' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d @body.json

TypeScript SDK

await collector.undoCollectionImport({ path: { id }, body: { … } });

GET/api/v1/collection/items/{id}/changes

A copy’s history

Signed in

The copy’s issue and variant changes, newest first.

SDK: collector.listCopyChanges()
Key scopes: collection:read(API keys are coming soon)
Headers: If-None-MatchX-Request-Id

Parameters

Name	In	Type	About
`id`required	path	string (uuid)

Responses

200The changes.
object
- changesarray of CopyChangerequired
  Newest first.
304Not modified: your copy (the ETag in If-None-Match) is current.

Errors (401, 404, 500)

401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404not_found
not_found: Nothing at that address.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl 'https://collection.id/api/v1/collection/items/<id>/changes' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

await collector.listCopyChanges({ path: { id } });

POST/api/v1/collection/items/{id}/changes/{changeId}/undo

Undo a change to a copy

Signed inIdempotent

Puts the copy back as it was before the change. Only its latest change can be undone.

SDK: collector.undoCopyChange()
Key scopes: collection:write(API keys are coming soon)
Headers: Idempotency-KeyX-Request-Id

Parameters

Name	In	Type	About
`id`required	path	string (uuid)
`changeId`required	path	string (uuid)

Responses

200The undo, as a change of its own.
object
- changedbooleanrequired
  False when the copy already was that.
- changeCopyChange or nullrequired

Errors (400, 401, 404, 409, 422, 500, 503)

400invalid_idempotency_key
invalid_idempotency_key: The Idempotency-Key isn’t 1–255 visible ASCII characters.
401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404not_found
not_found: Nothing at that address.
409idempotency_in_progress already_undone cannot_undo changed_since
idempotency_in_progress: The first request with this key is still running.
already_undone: That change was already undone.
cannot_undo: Only the copy’s latest change can be undone.
changed_since: The copy changed since; undo the later change first.
422idempotency_key_reused
idempotency_key_reused: This key was used for a different request.
500internal
internal: Something went wrong on our side (quote the requestId).
503not_migrated
not_migrated: The database update this needs isn’t applied yet.

curl

curl -X POST 'https://collection.id/api/v1/collection/items/<id>/changes/<changeId>/undo' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

TypeScript SDK

await collector.undoCopyChange({ path: { id, changeId } });

GET/api/v1/collection/items/{id}/codes

The codes on a copy

Signed in

Barcodes, ISBNs, ISSNs and distributor codes added to the copy, with their review.

SDK: collector.listCopyCodes()
Key scopes: collection:read(API keys are coming soon)
Headers: If-None-MatchX-Request-Id

Parameters

Name	In	Type	About
`id`required	path	string (uuid)

Responses

200The codes.
object
- codesarray of CopyCoderequired
304Not modified: your copy (the ETag in If-None-Match) is current.

Errors (401, 404, 500)

401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404not_found
not_found: Nothing at that address.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl 'https://collection.id/api/v1/collection/items/<id>/codes' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

await collector.listCopyCodes({ path: { id } });

POST/api/v1/collection/items/{id}/codes

Add a code to a copy

Signed inIdempotent

Keeps a code the catalog doesn’t know on the copy (yours to search and scan at once) and sends it for review; once approved, it matches for everyone. Check it first: a code the catalog knows changes what the copy is instead (repoint). 30 codes a day.

SDK: collector.addCopyCode()
Key scopes: collection:write(API keys are coming soon)
Headers: Idempotency-KeyX-Request-Id

Parameters

Name	In	Type	About
`id`required	path	string (uuid)

Request body (required, application/json)

object

textstringrequired1–60 characters
addOnstring or nulloptionalat most 5 characters
formatstring or nulloptionalat most 20 characters
kindenum or nulloptional
One ofupcisbnissndistributor
notestring or nulloptionalat most 1000 characters

Responses

201The code, on the copy.
object
- codeCopyCoderequired

Errors (400, 401, 404, 409, 422, 429, 500)

400invalid_request invalid_json invalid_idempotency_key invalid_code
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.
invalid_code: Not a valid barcode, ISBN, ISSN or code (check digits).
401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404not_found
not_found: Nothing at that address.
409idempotency_in_progress already_added already_known known_elsewhere already_proposed
idempotency_in_progress: The first request with this key is still running.
already_added: The copy already has this code.
already_known: The catalog knows this code: change the copy to it instead.
known_elsewhere: Another edition has this code.
already_proposed: This code is already waiting for review.
422idempotency_key_reused
idempotency_key_reused: This key was used for a different request.
429rate_limited
rate_limited: More than 30 codes today; wait the Retry-After seconds.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl -X POST 'https://collection.id/api/v1/collection/items/<id>/codes' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d @body.json

TypeScript SDK

await collector.addCopyCode({ path: { id }, body: { … } });

DELETE/api/v1/collection/items/{id}/codes/{codeId}

Remove a code from a copy

Signed in

Takes the code off the copy, and withdraws it from review if it’s still waiting.

SDK: collector.removeCopyCode()
Key scopes: collection:write(API keys are coming soon)
Headers: X-Request-Id

Parameters

Name	In	Type	About
`id`required	path	string (uuid)
`codeId`required	path	string (uuid)

Responses

200Removed.
object
- ok"true"required

Errors (401, 404, 500)

401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404not_found
not_found: Nothing at that address.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl -X DELETE 'https://collection.id/api/v1/collection/items/<id>/codes/<codeId>' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

await collector.removeCopyCode({ path: { id, codeId } });

POST/api/v1/collection/items/{id}/codes/check

Check a code against a copy

Signed in

What a code names, compared with this copy: the copy itself, another issue or edition to change the copy to, or nothing the catalog knows yet. Changes nothing. 120 checks an hour.

SDK: collector.checkCopyCode()
Key scopes: collection:read(API keys are coming soon)
Headers: X-Request-Id

Parameters

Name	In	Type	About
`id`required	path	string (uuid)

Request body (required, application/json)

object

textstringrequired1–60 characters
addOnstring or nulloptionalat most 5 characters
formatstring or nulloptionalat most 20 characters
kindenum or nulloptional
One ofupcisbnissndistributor
notestring or nulloptionalat most 1000 characters

Responses

200What the code names.
object
- codeobjectrequired
  Fields of code
  kindenumrequired
  One ofupcisbnissndistributor
  codestringrequired
  addonstringrequired
  displaystringrequired
  hintsarray of stringrequired
  What the code itself says (the add-on’s cover and printing...).
- currentbooleanrequired
  The copy already is what the code names, or already has the code.
- matchesarray of CopyTargetOptionrequired
  What the code names.
- relatedarray of CopyTargetOptionrequired
  Weaker: the code’s series at the copy’s number.
- savedCopyCode or nullrequired
  The code, when it’s already on this copy.

Errors (400, 401, 404, 429, 500)

400invalid_request invalid_json invalid_code
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
invalid_code: Not a valid barcode, ISBN, ISSN or code (check digits).
401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404not_found
not_found: Nothing at that address.
429rate_limited
rate_limited: More than 120 checks an hour; wait the Retry-After seconds.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl -X POST 'https://collection.id/api/v1/collection/items/<id>/codes/check' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d @body.json

TypeScript SDK

await collector.checkCopyCode({ path: { id }, body: { … } });

GET/api/v1/collection/items/{id}/repoint

Suggest what a copy could be

Signed in

Ranked issues to change the copy to before searching: what its barcodes name, the issues next to it, the same number in other volumes.

SDK: collector.listCopyRepointOptions()
Key scopes: collection:read(API keys are coming soon)
Headers: If-None-MatchX-Request-Id

Parameters

Name	In	Type	About
`id`required	path	string (uuid)

Responses

200Suggestions, best first.
object
- suggestionsarray of CopyTargetOptionrequired
  Best first.
304Not modified: your copy (the ETag in If-None-Match) is current.

Errors (401, 404, 500)

401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404not_found
not_found: Nothing at that address.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl 'https://collection.id/api/v1/collection/items/<id>/repoint' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

await collector.listCopyRepointOptions({ path: { id } });

POST/api/v1/collection/items/{id}/repoint

Change what a copy is

Signed inIdempotent

Changes the copy’s issue, edition or variant. Only what the copy is changes: its purchase, grade, notes, your own value and its QR labels stay as they were. The change goes in the copy’s history, where it can be undone.

SDK: collector.repointCopy()
Key scopes: collection:write(API keys are coming soon)
Headers: Idempotency-KeyX-Request-Id

Parameters

Name	In	Type	About
`id`required	path	string (uuid)

Request body (required, application/json)

object

issueIdstring (uuid)required
editionIdstring (uuid) or nulloptional
pendingVariantIdstring (uuid) or nulloptional
codeobject or nulloptional
Fields of code
- kindenumrequired
  One ofupcisbnissndistributor
- codestringrequired1–40 characters
- addonstringoptionaldefault ""

Responses

200Whether it changed, and the change.
object
- changedbooleanrequired
  False when the copy already was that.
- changeCopyChange or nullrequired

Errors (400, 401, 403, 404, 409, 422, 500, 503)

400invalid_request invalid_json invalid_idempotency_key invalid_code
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.
invalid_code: The code that led here isn’t a valid code.
401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
403forbidden
forbidden: That isn’t yours to change.
404not_found
not_found: Nothing at that address.
409idempotency_in_progress invalid_target edition_mismatch invalid_pending_variant repoint_rate_limited
idempotency_in_progress: The first request with this key is still running.
invalid_target: The issue or edition can’t take a copy.
edition_mismatch: The edition isn’t one of that issue’s.
invalid_pending_variant: That pending variant isn’t yours, or isn’t of that issue.
repoint_rate_limited: Too many changes today; try again tomorrow.
422idempotency_key_reused
idempotency_key_reused: This key was used for a different request.
500internal
internal: Something went wrong on our side (quote the requestId).
503not_migrated
not_migrated: The database update this needs isn’t applied yet.

curl

curl -X POST 'https://collection.id/api/v1/collection/items/<id>/repoint' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d @body.json

TypeScript SDK

await collector.repointCopy({ path: { id }, body: { … } });

POST/api/v1/collection/items/bulk

Change many copies at once

Signed inIdempotent

The library’s bulk tools, for up to 500 copies a request: update (status, sold date and price, for trade, asking price, location), retag (add and remove tags) or delete (also removes their photos). More than one copy needs Pro. A write that fails after earlier batches went through reports them in error.details.saved.

SDK: collector.bulkCopies()
Key scopes: collection:write(API keys are coming soon)
Headers: Idempotency-KeyX-Request-Id

Request body (required, application/json)

object or object or object

Option 1: object
- action"update"required
- idsarray of string (uuid)required1–500 items
- patchobjectrequired
  Fields of patch
  statusenumoptional
  One ofownedwishlistsold
  sold_onstring (date) or nulloptional
  sale_price_centsinteger or nulloptional0–2000000000
  for_tradebooleanoptional
  asking_price_centsinteger or nulloptional0–2000000000
  locationstring or nulloptionalat most 480 characters
Option 2: object
- action"retag"required
- idsarray of string (uuid)required1–500 items
- addarray of stringoptionalat most 30 items · default []
- removearray of stringoptionalat most 30 items · default []
Option 3: object
- action"delete"required
- idsarray of string (uuid)required1–500 items

Responses

200How many copies changed.
object
- changedintegerrequired
  Copies changed (or deleted).

Errors (400, 401, 403, 409, 422, 500)

400invalid_request invalid_json invalid_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.
401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
403feature_required
feature_required: Changing more than one copy needs Pro.
409idempotency_in_progress
idempotency_in_progress: The first request with this key is still running.
422idempotency_key_reused
idempotency_key_reused: This key was used for a different request.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl -X POST 'https://collection.id/api/v1/collection/items/bulk' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d @body.json

TypeScript SDK

await collector.bulkCopies({ body: { … } });