Admin moderation

10 operations.

GET/api/v1/admin/code-proposals

Codes collectors added

ModeratorBeta: may change

UPCs, ISBNs, ISSNs and distributor codes collectors added that the catalog doesn’t have yet.

SDK: collector.listAdminCodeProposals()
Key scopes: admin:moderation:write(API keys are coming soon)
Headers: If-None-MatchX-Request-Id

Parameters

Name	In	Type	About
`status`optional	query	enum	Which items (default pending).One of `pending`, `approved`, `rejected`, `withdrawn`default "pending"

Responses

200A page of codes and counts by status.
AdminCodeProposalPage
- proposalsarray of AdminCodeProposalrequired
- countsmap of numberrequired
304Not modified: your copy (the ETag in If-None-Match) is current.

Errors (400, 404, 500)

400invalid_request
invalid_request: The query or body doesn’t match the schema (see errors[]).
404not_found
not_found: Not an admin (moderator): the same 404 as a missing route.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

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

TypeScript SDK

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

POST/api/v1/admin/code-proposals/{id}

Approve or decline a code

ModeratorBeta: may change

Onto an edition, or the series for an ISSN. A decline needs a note for the collector.

SDK: collector.reviewAdminCodeProposal()
Key scopes: admin:moderation:write(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

decisionenumrequired
One ofapprovereject
editionIdstring (uuid) or nulloptional
overridebooleanoptional
notestringoptionalat most 1000 characters

Responses

200The code, reviewed.
object
- proposalAdminCodeProposalrequired

Errors (400, 404, 409, 500)

400invalid_request invalid_json
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
404not_found
not_found: Not an admin (moderator): the same 404 as a missing route.
409already_reviewed
already_reviewed: Someone already reviewed it.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

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

TypeScript SDK

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

GET/api/v1/admin/cover-contributions

Collectors’ cover photos

ModeratorBeta: may change

By status, with the checks’ findings and look-alike covers.

SDK: collector.listAdminCoverContributions()
Key scopes: admin:moderation:write(API keys are coming soon)
Headers: If-None-MatchX-Request-Id

Parameters

Name	In	Type	About
`status`optional	query	enum	Which items (default pending).One of `pending`, `approved`, `rejected`, `withdrawn`default "pending"

Responses

200A page of covers and counts by status.
AdminCoverContributionPage
- contributionsarray of AdminCoverContributionrequired
- countsmap of numberrequired
304Not modified: your copy (the ETag in If-None-Match) is current.

Errors (400, 404, 500)

400invalid_request
invalid_request: The query or body doesn’t match the schema (see errors[]).
404not_found
not_found: Not an admin (moderator): the same 404 as a missing route.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

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

TypeScript SDK

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

POST/api/v1/admin/cover-contributions/{id}

Approve or decline a cover photo

ModeratorBeta: may change

Approving stores the photo as the catalog cover. A decline needs a note for the collector.

SDK: collector.reviewAdminCoverContribution()
Key scopes: admin:moderation:write(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

decisionenumrequired
One ofapprovereject
notestringoptionalat most 1000 characters

Responses

200The cover, reviewed.
object
- contributionAdminCoverContributionrequired

Errors (400, 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.
404not_found
not_found: Not an admin (moderator): the same 404 as a missing route.
409already_reviewed has_cover photo_missing entity_not_found
already_reviewed: Someone already reviewed it.
has_cover: It has a cover now; decline this one or remove that cover first.
photo_missing: The photo is gone; decline this one.
entity_not_found: The issue is no longer in the catalog.
500internal
internal: Something went wrong on our side (quote the requestId).
503storage_unavailable
storage_unavailable: Cover storage isn’t set up on this server.

curl

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

TypeScript SDK

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

GET/api/v1/admin/moderation

Catalog change requests

ModeratorBeta: may change

Collectors’ corrections and proposals with field diffs, newest pending first. Moderators don’t see emails.

SDK: collector.listAdminChangeRequests()
Key scopes: admin:moderation:write(API keys are coming soon)
Headers: If-None-MatchX-Request-Id

Parameters

Name	In	Type	About
`status`optional	query	enum	Which items (default pending).One of `pending`, `approved`, `rejected`, `withdrawn`default "pending"

Responses

200A page of requests and counts by status.
AdminChangeRequestPage
- requestsarray of AdminChangeRequestrequired
- countsmap of numberrequired
304Not modified: your copy (the ETag in If-None-Match) is current.

Errors (400, 404, 500)

400invalid_request
invalid_request: The query or body doesn’t match the schema (see errors[]).
404not_found
not_found: Not an admin (moderator): the same 404 as a missing route.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

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

TypeScript SDK

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

POST/api/v1/admin/moderation/{id}

Approve or reject a change request

ModeratorBeta: may change

Approving applies it. A rejection needs a note; the collector sees it.

SDK: collector.reviewAdminChangeRequest()
Key scopes: admin:moderation:write(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

decisionenumrequired
One ofapprovereject
notestringoptionalat most 1000 characters

Responses

200The request, reviewed.
object
- requestAdminChangeRequestrequired

Errors (400, 404, 409, 500)

400invalid_request invalid_json
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
404not_found
not_found: Not an admin (moderator): the same 404 as a missing route.
409already_reviewed entity_not_found empty_patch
already_reviewed: Someone already reviewed it.
entity_not_found: The record it’s about no longer exists.
empty_patch: Nothing in it can be applied any more.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

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

TypeScript SDK

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

GET/api/v1/admin/variant-proposals

Variant proposals and import suggestions

ModeratorBeta: may change

Collectors’ variant proposals and the variants imports couldn’t place, collected books first, with candidate editions and what their cover barcodes read.

SDK: collector.listAdminVariantProposals()
Key scopes: admin:moderation:write(API keys are coming soon)
Headers: If-None-MatchX-Request-Id

Parameters

Name	In	Type	About
`status`optional	query	enum	Which items (default pending).One of `pending`, `approved`, `rejected`, `withdrawn`default "pending"

Responses

200A page of proposals and counts by status.
AdminVariantProposalPage
- proposalsarray of AdminVariantProposalrequired
- countsmap of numberrequired
304Not modified: your copy (the ETag in If-None-Match) is current.

Errors (400, 404, 500)

400invalid_request
invalid_request: The query or body doesn’t match the schema (see errors[]).
404not_found
not_found: Not an admin (moderator): the same 404 as a missing route.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

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

TypeScript SDK

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

POST/api/v1/admin/variant-proposals/{id}

Approve or decline a variant proposal

ModeratorBeta: may change

Approve as sent, or as the reviewer edited it (variant and edition), with or without the photo.

SDK: collector.reviewAdminVariantProposal()
Key scopes: admin:moderation:write(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

decisionenumrequired
One ofapprovereject
variantobjectoptional
Fields of variant
- namestring or nulloptionalat most 300 characters
- coverLetterstring or nulloptionalat most 20 characters
- artiststring or nulloptionalat most 120 characters
- printinginteger or nulloptional1–99
- ratiostring or nulloptionalat most 20 characters
- barcodestring or nulloptionalat most 40 characters
- isbnstring or nulloptionalat most 20 characters
- isVirginbooleanoptional
- isExclusivebooleanoptional
- exclusiveRetailerstring or nulloptionalat most 120 characters
- coverPriceCentsinteger or nulloptional0–1000000
- coverPriceCurrencystring or nulloptional
usePhotobooleanoptional
releaseobjectoptional
Fields of release
- publisherIdstring (uuid) or nulloptional
- publisherNamestringoptionalat most 200 characters · default ""
- languagestring or nulloptional
- countrystring or nulloptional
- releaseYearinteger or nulloptional1900–2200
- numberAsPrintedstring or nulloptionalat most 40 characters
- titleAsPrintedstring or nulloptionalat most 300 characters
notestringoptionalat most 1000 characters

Responses

200The proposal, reviewed.
object
- proposalAdminVariantProposalrequired

Errors (400, 404, 409, 500)

400invalid_request invalid_json
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
404not_found
not_found: Not an admin (moderator): the same 404 as a missing route.
409already_reviewed entity_not_found photo_missing import_suggestion
already_reviewed: Someone already reviewed it.
entity_not_found: The issue is no longer in the catalog.
photo_missing: The photo is gone; approve without it or decline.
import_suggestion: An import suggestion: resolve it instead.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

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

TypeScript SDK

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

POST/api/v1/admin/variant-proposals/{id}/resolve

Resolve an import suggestion

ModeratorBeta: may change

The edition it is (optionally giving the edition the provider’s barcode), a new variant, or dismissed.

SDK: collector.resolveAdminVariantSuggestion()
Key scopes: admin:moderation:write(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

decisionenumrequired
One ofassigncreatereject
editionIdstring (uuid)optional
fillBarcodebooleanoptional
variantobjectoptional
Fields of variant
- namestring or nulloptionalat most 300 characters
- coverLetterstring or nulloptionalat most 20 characters
- artiststring or nulloptionalat most 120 characters
- printinginteger or nulloptional1–99
- ratiostring or nulloptionalat most 20 characters
- barcodestring or nulloptionalat most 40 characters
- isbnstring or nulloptionalat most 20 characters
- isVirginbooleanoptional
- isExclusivebooleanoptional
- exclusiveRetailerstring or nulloptionalat most 120 characters
- coverPriceCentsinteger or nulloptional0–1000000
- coverPriceCurrencystring or nulloptional
notestringoptionalat most 1000 characters

Responses

200The suggestion, resolved.
object
- proposalAdminVariantProposalrequired

Errors (400, 404, 409, 500)

400invalid_request invalid_json
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
404not_found
not_found: Not an admin (moderator): the same 404 as a missing route.
409already_reviewed entity_not_found
already_reviewed: Someone already reviewed it.
entity_not_found: The issue is no longer in the catalog.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

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

TypeScript SDK

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

POST/api/v1/admin/variant-proposals/{id}/undo

Undo an assigned import suggestion

ModeratorBeta: may change

Automatic (by its cover barcode) or a moderator’s: it’s pending again and the edition is as it was. An undone automatic placement isn’t repeated.

SDK: collector.undoAdminVariantSuggestion()
Key scopes: admin:moderation:write(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

notestringoptionalat most 1000 characters

Responses

200The suggestion, pending again.
object
- proposalAdminVariantProposalrequired

Errors (400, 404, 409, 500)

400invalid_request invalid_json
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
404not_found
not_found: Not an admin (moderator): the same 404 as a missing route.
409not_assigned
not_assigned: Only a suggestion matched to an edition can be undone.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

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

TypeScript SDK

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