API reference / Collectors
Collectors improve the catalog: corrections, cover photos and variant proposals, reviewed by moderators.
/api/v1/catalog/correctionsYour five most recent correction suggestions for one series, issue or edition, newest first, with their review status.
collector.listMyCorrections()If-None-MatchX-Request-Id| Name | In | Type | About |
|---|---|---|---|
entityrequired | query | enum | One of series, issue, edition |
idrequired | query | string (uuid) |
object
invalid_request: The query or body doesn’t match the schema (see errors[]).
unauthorized: Not signed in (no session or token, or an expired one).
internal: Something went wrong on our side (quote the requestId).
curl 'https://collection.id/api/v1/catalog/corrections' \
-H "Authorization: Bearer $COLLECTOR_TOKEN"await collector.listMyCorrections({ query: { … } });/api/v1/catalog/correctionsSuggest new values for a series, issue or edition (database column names). A moderator reviews it; one pending suggestion per record per collector.
collector.submitCorrection()Idempotency-KeyX-Request-Idobject
entityenumrequiredOne ofseriesissueedition
idstring (uuid)requiredchangesmap of anyoptionaldefault {}notesobjectoptionalcreditsstringoptionalat most 1000 characterscoverProblemenumoptionalOne ofwrongnot_a_coverlow_quality
reasonstringoptionalat most 2000 characterssourceenumoptionaldefault "catalog"One ofcatalogcollectionscan
object
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_progress: The first request with this key is still running.
duplicate: You already have a suggestion waiting for this record.
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/corrections' \
-H "Authorization: Bearer $COLLECTOR_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d @body.jsonawait collector.submitCorrection({ body: { … } });/api/v1/catalog/corrections/{id}/withdrawTake back one of your own suggestions still waiting for review.
collector.withdrawCorrection()X-Request-Id| Name | In | Type | About |
|---|---|---|---|
idrequired | path | string (uuid) |
object
withdrawn"true"requiredunauthorized: Not signed in (no session or token, or an expired one).
not_found: Nothing at that address.
internal: Something went wrong on our side (quote the requestId).
curl -X POST 'https://collection.id/api/v1/catalog/corrections/<id>/withdraw' \
-H "Authorization: Bearer $COLLECTOR_TOKEN"await collector.withdrawCorrection({ path: { id } });/api/v1/catalog/cover-contributionsThe cover photos you’ve sent and where their review stands, newest first; optionally one issue’s.
collector.listMyCoverContributions()If-None-MatchX-Request-Id| Name | In | Type | About |
|---|---|---|---|
issueoptional | query | string (uuid) | Only this issue’s. |
object
invalid_request: The query or body doesn’t match the schema (see errors[]).
unauthorized: Not signed in (no session or token, or an expired one).
internal: Something went wrong on our side (quote the requestId).
curl 'https://collection.id/api/v1/catalog/cover-contributions' \
-H "Authorization: Bearer $COLLECTOR_TOKEN"await collector.listMyCoverContributions({ query: { … } });/api/v1/catalog/cover-contributionsA straightened cover photo, already uploaded to your folder of the cover-contributions bucket, for an issue or edition with no cover. Checked (sharpness, resolution, an existing similar cover) and reviewed by a moderator.
collector.submitCoverContribution()Idempotency-KeyX-Request-Idobject
entityenumrequiredOne ofissueedition
entityIdstring (uuid)requireditemIdstring (uuid) or nulloptionalimagePathstringrequiredcreditbooleanrequiredacceptTerms"true"requiredobject
contributionobjectrequiredidstring (uuid)requiredentityenumrequiredOne ofissueedition
entityIdstring (uuid)requiredissueIdstring (uuid)requiredstatusenumrequiredOne ofpendingapprovedrejectedwithdrawn
creditbooleanrequiredCredit the contributor by name when approved.
reviewNotestring or nullrequiredcreatedAtstring (date-time)requiredreviewedAtstring (date-time) or nullrequiredflagsarray of enumrequiredWhat the photo checks noticed, for the reviewer.
One ofblurrysimilar_coverlow_resolution
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).
forbidden: The upload isn’t yours.
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/cover-contributions' \
-H "Authorization: Bearer $COLLECTOR_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d @body.jsonawait collector.submitCoverContribution({ body: { … } });/api/v1/catalog/cover-contributions/{id}Take back a cover still waiting for review; its photo is removed.
collector.withdrawCoverContribution()X-Request-Id| Name | In | Type | About |
|---|---|---|---|
idrequired | path | string (uuid) |
object
withdrawn"true"requiredunauthorized: Not signed in (no session or token, or an expired one).
not_found: Nothing at that address.
internal: Something went wrong on our side (quote the requestId).
curl -X DELETE 'https://collection.id/api/v1/catalog/cover-contributions/<id>' \
-H "Authorization: Bearer $COLLECTOR_TOKEN"await collector.withdrawCoverContribution({ path: { id } });/api/v1/catalog/covers-wanted"Help the catalog": most-owned first.
collector.listCoversWanted()If-None-MatchX-Request-Idobject
unauthorized: Not signed in (no session or token, or an expired one).
internal: Something went wrong on our side (quote the requestId).
curl 'https://collection.id/api/v1/catalog/covers-wanted' \
-H "Authorization: Bearer $COLLECTOR_TOKEN"await collector.listCoversWanted();/api/v1/catalog/variant-covers-wanted"Help the catalog", variants: copies whose variant borrows the main cover. Most-owned first.
collector.listVariantCoversWanted()If-None-MatchX-Request-Idobject
unauthorized: Not signed in (no session or token, or an expired one).
internal: Something went wrong on our side (quote the requestId).
curl 'https://collection.id/api/v1/catalog/variant-covers-wanted' \
-H "Authorization: Bearer $COLLECTOR_TOKEN"await collector.listVariantCoversWanted();/api/v1/catalog/variant-proposalsThe variants you’ve proposed and where their review stands, newest first; optionally one issue’s.
collector.listMyVariantProposals()If-None-MatchX-Request-Id| Name | In | Type | About |
|---|---|---|---|
issueoptional | query | string (uuid) | Only this issue’s. |
object
invalid_request: The query or body doesn’t match the schema (see errors[]).
unauthorized: Not signed in (no session or token, or an expired one).
internal: Something went wrong on our side (quote the requestId).
curl 'https://collection.id/api/v1/catalog/variant-proposals' \
-H "Authorization: Bearer $COLLECTOR_TOKEN"await collector.listMyVariantProposals({ query: { … } });/api/v1/catalog/variant-proposalsA variant the catalog doesn’t list (kind "new"), possibly in another edition of the issue (a listed release, or one described), or a correction to a listed one ("change"), with an optional cover photo. Private to you until a moderator approves it; your copy can point at it straight away.
collector.proposeVariant()Idempotency-KeyX-Request-Idobject
kindenumrequiredOne ofnewchange
issueIdstring (uuid)requirededitionIdstring (uuid) or nulloptionalitemIdstring (uuid) or nulloptionalreleaseIdstring (uuid) or nulloptionalreleaseobject or nulloptionalpublisherIdstring (uuid) or nulloptionalpublisherNamestringoptionalat most 200 characters · default ""languagestring or nulloptionalcountrystring or nulloptionalreleaseYearinteger or nulloptional1900–2200numberAsPrintedstring or nulloptionalat most 40 characterstitleAsPrintedstring or nulloptionalat most 300 charactersvariantobjectrequirednamestring or nulloptionalat most 300 characterscoverLetterstring or nulloptionalat most 20 charactersartiststring or nulloptionalat most 120 charactersprintinginteger or nulloptional1–99ratiostring or nulloptionalat most 20 charactersbarcodestring or nulloptionalat most 40 charactersisbnstring or nulloptionalat most 20 charactersisVirginbooleanoptionalisExclusivebooleanoptionalexclusiveRetailerstring or nulloptionalat most 120 characterscoverPriceCentsinteger or nulloptional0–1000000coverPriceCurrencystring or nulloptionalchangedarray of stringoptionalat most 20 itemsnotestring or nulloptionalat most 1000 charactersphotoobject or nulloptionalimagePathstringrequiredcreditbooleanrequiredacceptTerms"true"requiredobject
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_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/variant-proposals' \
-H "Authorization: Bearer $COLLECTOR_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d @body.jsonawait collector.proposeVariant({ body: { … } });/api/v1/catalog/variant-proposals/{id}Withdraw one of your proposals while it’s still pending; its photo is discarded.
collector.withdrawVariantProposal()X-Request-Id| Name | In | Type | About |
|---|---|---|---|
idrequired | path | string (uuid) |
object
ok"true"requiredunauthorized: Not signed in (no session or token, or an expired one).
not_found: Nothing at that address.
already_reviewed: A moderator has already reviewed it.
internal: Something went wrong on our side (quote the requestId).
curl -X DELETE 'https://collection.id/api/v1/catalog/variant-proposals/<id>' \
-H "Authorization: Bearer $COLLECTOR_TOKEN"await collector.withdrawVariantProposal({ path: { id } });