Admin catalog

14 operations.

GET/api/v1/admin/catalog

Find catalog records to edit

AdminBeta: may change

A pasted catalog link, an id, "Title #12" or a series title.

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

Parameters

Name	In	Type	About
`q`optional	query	string	What to look for.

Responses

200Matching records.
object
- hitsarray of AdminCatalogSearchHitrequired
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/catalog' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

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

GET/api/v1/admin/catalog/{entity}/{id}

Get a catalog record

AdminBeta: may change

One publisher, series, issue or edition with its editable fields, status, slugs, locks and children.

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

Parameters

Name	In	Type	About
`entity`required	path	enum	publisher, series, issue or edition.One of `publisher`, `series`, `issue`, `edition`
`id`required	path	string (uuid)

Responses

200The record.
object
- recordAdminCatalogRecordrequired
304Not modified: your copy (the ETag in If-None-Match) is current.

Errors (404, 500)

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/catalog/<entity>/<id>' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

await collector.getAdminCatalogRecord({ path: { entity, id } });

PATCH/api/v1/admin/catalog/{entity}/{id}

Edit a catalog record

AdminBeta: may change

Set fields directly, validated like reviewed corrections; only changed fields need to be sent. Locks each changed field against imports. Audited; expires the catalog pages.

SDK: collector.updateAdminCatalogRecord()
Key scopes: admin:catalog:write(API keys are coming soon)
Headers: X-Request-Id

Parameters

Name	In	Type	About
`entity`required	path	enum	publisher, series, issue or edition.One of `publisher`, `series`, `issue`, `edition`
`id`required	path	string (uuid)

Request body (required, application/json)

object

valuesmap of anyrequired
notestringoptionalat most 1000 characters

Responses

200The record as it is now.
object
- recordAdminCatalogRecordrequired

Errors (400, 404, 409, 500)

400invalid_request invalid_json nothing_changed
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
nothing_changed: Every value sent is what the record has.
404not_found
not_found: Not an admin (moderator): the same 404 as a missing route.
409entity_merged
entity_merged: The record was merged into another one; edit the one that was kept.
500internal audit_failed
internal: Something went wrong on our side (quote the requestId).
audit_failed: The change was made, but writing its audit row failed.

curl

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

TypeScript SDK

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

POST/api/v1/admin/catalog/{entity}/{id}/imprints

Add an imprint to a publisher

AdminBeta: may change

Creates a verified imprint under a top-level publisher, or adopts a provisional publisher with that name as it (adopt). Audited.

SDK: collector.createAdminImprint()
Key scopes: admin:catalog:write(API keys are coming soon)
Headers: X-Request-Id

Parameters

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

Request body (required, application/json)

object

namestringrequired1–200 characters
websiteUrlstringoptionalat most 500 characters
foundedYearinteger or nulloptional1800–2200
adoptstring (uuid)optional
notestringoptionalat most 1000 characters

Responses

200The new imprint’s record.
object
- recordAdminCatalogRecordrequired

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.
409provisional_exists name_taken
provisional_exists: A provisional publisher already has the name; adopt it (its id is in the details).
name_taken: A catalog publisher already has the name.
500internal audit_failed
internal: Something went wrong on our side (quote the requestId).
audit_failed: The change was made, but writing its audit row failed.

curl

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

TypeScript SDK

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

POST/api/v1/admin/catalog/{entity}/{id}/locks

Lock or unlock a field

AdminBeta: may change

Lock a field at its current value (imports leave it alone) or remove its lock. Audited.

SDK: collector.setAdminCatalogFieldLock()
Key scopes: admin:catalog:write(API keys are coming soon)
Headers: X-Request-Id

Parameters

Name	In	Type	About
`entity`required	path	enum	publisher, series, issue or edition.One of `publisher`, `series`, `issue`, `edition`
`id`required	path	string (uuid)

Request body (required, application/json)

object

fieldstringrequired
lockedbooleanrequired
reasonstringoptionalat most 1000 characters

Responses

200The record with its locks.
object
- recordAdminCatalogRecordrequired

Errors (400, 404, 500)

400invalid_request invalid_json invalid_field
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
invalid_field: That field can’t be locked.
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 -X POST 'https://collection.id/api/v1/admin/catalog/<entity>/<id>/locks' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d @body.json

TypeScript SDK

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

POST/api/v1/admin/catalog/{entity}/{id}/slug

Change a series or issue slug

AdminBeta: may change

The old slug keeps redirecting. Audited.

SDK: collector.changeAdminCatalogSlug()
Key scopes: admin:catalog:write(API keys are coming soon)
Headers: X-Request-Id

Parameters

Name	In	Type	About
`entity`required	path	enum	One of `series`, `issue`
`id`required	path	string (uuid)

Request body (required, application/json)

object

slugstringrequiredat most 120 characters

Responses

200The record with its new slug.
object
- recordAdminCatalogRecordrequired

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_exists
already_exists: Another record has that slug.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

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

TypeScript SDK

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

POST/api/v1/admin/catalog/{entity}/{id}/verify

Verify a provisional record

AdminBeta: may change

Mark a provisional record verified, with the evidence it was checked against. Audited.

SDK: collector.verifyAdminCatalogRecord()
Key scopes: admin:catalog:write(API keys are coming soon)
Headers: X-Request-Id

Parameters

Name	In	Type	About
`entity`required	path	enum	publisher, series, issue or edition.One of `publisher`, `series`, `issue`, `edition`
`id`required	path	string (uuid)

Request body (required, application/json)

object

evidencestringrequired3–1000 characters

Responses

200The verified record.
object
- recordAdminCatalogRecordrequired

Errors (400, 404, 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.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

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

TypeScript SDK

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

GET/api/v1/admin/catalog/edition-overrides/{id}

An edition’s overridden fields

AdminBeta: may change

Fields an admin overrode on an edition, the known versions of each (previous, Metron, GCD) and recent reverts.

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

Parameters

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

Responses

200The overrides.
CatalogOverridesResponse
- entity"edition"required
- idstringrequired
- overridesarray of CatalogOverriderequired
- lookupsobjectrequired
  Fields of lookups
  metronExternalLookuprequired
  gcdExternalLookuprequired
- revertsarray of CatalogOverrideRevertrequired
304Not modified: your copy (the ETag in If-None-Match) is current.

Errors (404, 409, 500)

404not_found
not_found: Not an admin (moderator): the same 404 as a missing route.
409entity_merged
entity_merged: The record was merged into another one; edit the one that was kept.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl 'https://collection.id/api/v1/admin/catalog/edition-overrides/<id>' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

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

POST/api/v1/admin/catalog/edition-overrides/{id}/revert

Revert an overridden field

AdminBeta: may change

Put one overridden field back to a known version (its lock goes too). Audited; can be undone.

SDK: collector.revertAdminEditionOverride()
Key scopes: admin:catalog: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

fieldstringrequired
versionenumrequired
One ofpreviousmetrongcd
notestringoptionalat most 1000 characters

Responses

200The overrides as they are now.
CatalogOverridesResponse
- entity"edition"required
- idstringrequired
- overridesarray of CatalogOverriderequired
- lookupsobjectrequired
  Fields of lookups
  metronExternalLookuprequired
  gcdExternalLookuprequired
- revertsarray of CatalogOverrideRevertrequired

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.
409entity_merged not_overridden version_unavailable
entity_merged: The record was merged into another one; edit the one that was kept.
not_overridden: That field isn’t overridden (any more).
version_unavailable: That version can’t be read right now.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

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

TypeScript SDK

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

GET/api/v1/admin/catalog/issue-overrides/{id}

Overridden fields per edition of an issue

AdminBeta: may change

For each edition of the issue, how many of its fields an admin has overridden (the marks in the catalog editor), keyed by edition id.

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

Parameters

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

Responses

200Counts by edition id.
object
- countsmap of numberrequired
  Overridden fields per edition id.
304Not modified: your copy (the ETag in If-None-Match) is current.

Errors (404, 500)

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/catalog/issue-overrides/<id>' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

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

POST/api/v1/admin/catalog/moves

Move issues to another series

AdminBeta: may changeIdempotent

Checked again from current data (numbers the target has are refused). The database journals the move, so it can be undone for 7 days. Audited.

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

Request body (required, application/json)

object

issueIdsarray of string (uuid)required1–500 items
targetSeriesIdstring (uuid)required
notestringoptionalat most 1000 characters

Responses

200The move.
object
- idstringrequired
  The move’s journal id (undo within 7 days).
- movednumberrequired
- renamedarray of objectrequired
  Fields of renamed
  idstringrequired
  fromstringrequired
  tostringrequired

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

400invalid_request invalid_json invalid_idempotency_key mixed_series
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.
mixed_series: Move issues of one series at a time.
404not_found
not_found: Not an admin (moderator): the same 404 as a missing route.
409idempotency_in_progress move_blocked
idempotency_in_progress: The first request with this key is still running.
move_blocked: The move can’t run as asked (the details say why).
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/admin/catalog/moves' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d @body.json

TypeScript SDK

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

POST/api/v1/admin/catalog/moves/{id}/undo

Undo an issue move

AdminBeta: may change

Put a move back from its journal (within 7 days).

SDK: collector.undoAdminIssueMove()
Key scopes: admin:catalog:write(API keys are coming soon)
Headers: X-Request-Id

Parameters

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

Responses

200What was put back.
UndoResult
Journal entries put back, and ones skipped because the data changed since.
- appliednumberrequired
- skippednumberrequired

Errors (404, 500)

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 -X POST 'https://collection.id/api/v1/admin/catalog/moves/<id>/undo' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

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

POST/api/v1/admin/catalog/moves/preview

Preview moving issues to another series

AdminBeta: may change

Slugs, what follows the issues, collisions and warnings. Writes nothing.

SDK: collector.previewAdminIssueMove()
Key scopes: admin:catalog:read(API keys are coming soon)
Headers: X-Request-Id

Request body (required, application/json)

object

issueIdsarray of string (uuid)required1–500 items
targetSeriesIdstring (uuid)required
notestringoptionalat most 1000 characters

Responses

200What the move would do.
object
- previewobjectrequired
  Fields of preview
  fromobjectrequired
  Fields of from
  idstringrequired
  labelstringrequired
  publisherstring or nullrequired
  toobjectrequired
  Fields of to
  idstringrequired
  labelstringrequired
  publisherstring or nullrequired
  issuesarray of objectrequired
  Fields of issues
  idstringrequired
  labelstringrequired
  slugstringrequired
  newSlugstringrequired
  collisionsarray of stringrequired
  warningsarray of stringrequired
  carriedobjectrequired
  Fields of carried
  editionsnumberrequired
  copiesnumberrequired
  listingsnumberrequired
  barcodeMatchesnumberrequired
  problemsarray of stringrequired
  Why the move can’t run as asked, if anything.

Errors (400, 404, 500)

400invalid_request invalid_json mixed_series
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
mixed_series: Move issues of one series at a time.
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 -X POST 'https://collection.id/api/v1/admin/catalog/moves/preview' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d @body.json

TypeScript SDK

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

POST/api/v1/admin/catalog/override-reverts/{id}/undo

Undo a revert

AdminBeta: may change

The override and its lock come back.

SDK: collector.undoAdminOverrideRevert()
Key scopes: admin:catalog:write(API keys are coming soon)
Headers: X-Request-Id

Parameters

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

Responses

200The overrides as they are now.
CatalogOverridesResponse
- entity"edition"required
- idstringrequired
- overridesarray of CatalogOverriderequired
- lookupsobjectrequired
  Fields of lookups
  metronExternalLookuprequired
  gcdExternalLookuprequired
- revertsarray of CatalogOverrideRevertrequired

Errors (404, 500)

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 -X POST 'https://collection.id/api/v1/admin/catalog/override-reverts/<id>/undo' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

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