API reference / Collectors
Find books: search, barcodes, identification from evidence, and full issue records.
/api/v1/catalog/barcodeA UPC with its 2- or 5-digit add-on, an EAN-13 or an ISBN. The exact edition first, then what the series and the add-on suggest; signed-in callers also get Metron results. Signed out: 60 lookups a minute per network.
collector.lookupBarcode()If-None-MatchX-Request-Id| Name | In | Type | About |
|---|---|---|---|
coderequired | query | string | The digits under the bars.6–40 characters |
addonoptional | query | string | |
limitoptional | query | integer | 1–25 |
object
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_barcode: Not a UPC, EAN or ISBN.
checksum_failed: The digits fail the barcode’s check digit.
rate_limited: Signed out: too many requests from your network.
internal: Something went wrong on our side (quote the requestId).
curl 'https://collection.id/api/v1/catalog/barcode'await collector.lookupBarcode({ query: { … } });/api/v1/catalog/identifyFuses a barcode, what the cover says and a perceptual hash of the cover photo, and answers ranked candidates with the reasons for each.
collector.identifyIssue()X-Request-Idobject
barcodeobject or nulloptionaltextstringrequired6–40 charactersaddOnstring or nulloptionalformatstring or nulloptional1–20 characterscoverobject or nulloptionaltitlestring or nulloptional1–300 charactersissueNumberstring or nulloptional1–40 characterspublisherstring or nulloptional1–200 characterscoverDatestring (date) or nulloptionalyearinteger or nulloptional1800–2200coverPriceCentsinteger or nulloptional0–10000000coverPriceCurrencystring or nulloptionalvariantHintsarray of string or nulloptionalat most 10 itemscreatorsarray of string or nulloptionalat most 20 itemscoverHashstring or nulloptionallimitinteger or nulloptional1–25object
invalid_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).
internal: Something went wrong on our side (quote the requestId).
curl -X POST 'https://collection.id/api/v1/catalog/identify' \
-H "Authorization: Bearer $COLLECTOR_TOKEN" \
-H 'Content-Type: application/json' \
-d @body.jsonawait collector.identifyIssue({ body: { … } });/api/v1/catalog/issues/{id}The issue’s full record with its series, editions and credits. A merged issue answers its winner, naming the id asked for in mergedFrom.
collector.getCatalogIssue()If-None-MatchX-Request-Id| Name | In | Type | About |
|---|---|---|---|
idrequired | path | string (uuid) |
object
mergedFromstring (uuid) or nullrequiredsourcesarray of objectrequiredWhere the record came from (GCD, Metron...), with links.
providerstringrequiredurlstring (uri) or nullrequirednot_found: Nothing at that address.
issue_not_found: No issue with that id.
internal: Something went wrong on our side (quote the requestId).
curl 'https://collection.id/api/v1/catalog/issues/<id>'await collector.getCatalogIssue({ path: { id } });/api/v1/catalog/materializeFor a candidate that exists only at a provider: imports its records and answers our ids. For one we have, answers its ids. Counts towards the per-collector import limit.
collector.materializeIssue()Idempotency-KeyX-Request-Idobject
issueIdstring (uuid) or nulloptionaleditionIdstring (uuid) or nulloptionalproviderobject or nulloptionalproviderenumrequiredOne ofmetrongcdcataloggd
issueIdstringrequired1–262 charactersvariantIdstring or nulloptionalat most 200 charactersThe catalog records a book now has (created from a provider, or new and provisional).
issueIdstring (uuid)requirededitionIdstring (uuid) or nullrequiredseriesIdstring (uuid)requiredinvalid_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_progress: The first request with this key is still running.
idempotency_key_reused: This key was used for a different request.
rate_limited: Too many requests; wait the Retry-After seconds.
internal: Something went wrong on our side (quote the requestId).
curl -X POST 'https://collection.id/api/v1/catalog/materialize' \
-H "Authorization: Bearer $COLLECTOR_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d @body.jsonawait collector.materializeIssue({ body: { … } });/api/v1/catalog/provisionalReuses catalog records that match and never edits them; new records are provisional and attributed to the caller until confirmed (30 a day).
collector.createProvisionalIssue()Idempotency-KeyX-Request-Idobject
seriesTitlestringrequired1–300 characterspublisherstring or nulloptional1–200 charactersstartYearinteger or nulloptional1800–2200volumeinteger or nulloptional0–999numberstringrequired1–40 characterscoverDatestring (date) or nulloptionalcoverUrlstring (uri) or nulloptionalat most 2000 charactersA photo already uploaded to our covers bucket.
editionNamestring or nulloptional1–300 characterscoverVariantstring or nulloptional1–120 charactersprintinginteger or nulloptional1–99upcstring or nulloptionalupcAddonstring or nulloptionalisbnstring or nulloptionalThe catalog records a book now has (created from a provider, or new and provisional).
issueIdstring (uuid)requirededitionIdstring (uuid) or nullrequiredseriesIdstring (uuid)requiredinvalid_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_cover_url: The cover isn’t in our covers bucket.
unauthorized: Not signed in (no session or token, or an expired one).
idempotency_in_progress: The first request with this key is still running.
idempotency_key_reused: This key was used for a different request.
rate_limited: Too many requests; wait the Retry-After seconds.
internal: Something went wrong on our side (quote the requestId).
curl -X POST 'https://collection.id/api/v1/catalog/provisional' \
-H "Authorization: Bearer $COLLECTOR_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d @body.jsonawait collector.createProvisionalIssue({ body: { … } });/api/v1/catalog/searchFree text, the way a collector types it: "Amazing Spider-Man 300", "saga 1", "X-Men (1991) 1". The local catalog first; signed-in callers also get Metron results when local ones are thin. Signed out: 60 lookups a minute per network.
collector.searchCatalog()If-None-MatchX-Request-Id| Name | In | Type | About |
|---|---|---|---|
qrequired | query | string | 1–200 characters |
publisheroptional | query | string | 1–120 characters |
limitoptional | query | integer | 1–50 |
object
invalid_request: The query or body doesn’t match the schema (see errors[]).
rate_limited: Signed out: too many requests from your network.
internal: Something went wrong on our side (quote the requestId).
curl 'https://collection.id/api/v1/catalog/search'await collector.searchCatalog({ query: { … } });/api/v1/catalog/series/{slug}/go"Go to issue" on a series page: redirects to the issue, or to the block of the run where that number would be (with ?missing=).
collector.goToIssue()X-Request-Id| Name | In | Type | About |
|---|---|---|---|
slugrequired | path | string | 1–200 characters |
noptional | query | string | The issue number typed. |
curl 'https://collection.id/api/v1/catalog/series/<slug>/go'await collector.goToIssue({ path: { slug }, query: { … } });