API reference / Admin

Admin operations

12 operations.

GET/api/v1/admin/announcements

Announcements

AdminBeta: may change

Every announcement, newest first, with its state and how many people dismissed it.

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

Responses

200Announcements.
object
- announcementsarray of AdminAnnouncementrequired
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/announcements' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

await collector.listAdminAnnouncements();

POST/api/v1/admin/announcements

Publish or schedule an announcement

AdminBeta: may changeIdempotent

For everyone, signed-in people, or some plans. Audited.

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

Request body (required, application/json)

object

titlestringrequired1–120 characters
bodystring or nulloptionalat most 600 characters
linkUrlstring or null or ""optional
Fields of linkUrl
1. Option 1: string or null
2. Option 2: ""
linkLabelstring or nulloptionalat most 40 characters
severityenumrequired
One ofinfosuccesswarningcritical
audienceenumrequired
One ofeveryonesigned_inplan
audiencePlansarray of enumoptionalat most 3 items
One offreecollectorpro
startsAtstring (date-time) or nulloptional
endsAtstring (date-time) or nulloptional

Responses

201The announcement.
object
- announcementAnnouncementRowrequired

Errors (400, 404, 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.
404not_found
not_found: Not an admin (moderator): the same 404 as a missing route.
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/admin/announcements' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d @body.json

TypeScript SDK

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

PATCH/api/v1/admin/announcements/{id}

Edit an announcement

AdminBeta: may change

Text, link, audience and window. Audited with before and after.

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

titlestringrequired1–120 characters
bodystring or nulloptionalat most 600 characters
linkUrlstring or null or ""optional
Fields of linkUrl
1. Option 1: string or null
2. Option 2: ""
linkLabelstring or nulloptionalat most 40 characters
severityenumrequired
One ofinfosuccesswarningcritical
audienceenumrequired
One ofeveryonesigned_inplan
audiencePlansarray of enumoptionalat most 3 items
One offreecollectorpro
startsAtstring (date-time) or nulloptional
endsAtstring (date-time) or nulloptional

Responses

200The announcement.
object
- announcementAnnouncementRowrequired

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 PATCH 'https://collection.id/api/v1/admin/announcements/<id>' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d @body.json

TypeScript SDK

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

POST/api/v1/admin/announcements/{id}/end

Take an announcement down now

AdminBeta: may change

Audited.

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

Parameters

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

Responses

200The ended announcement.
object
- announcementAnnouncementRowrequired

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

TypeScript SDK

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

GET/api/v1/admin/audit

Audit log

AdminBeta: may changePaginated (cursor)

Newest first. Filters: action (exact, or a family like "catalog"), entity, actor (an id or an exact email), from/to dates; before pages.

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

Parameters

Name	In	Type	About
`action`optional	query	string	at most 120 characters
`entity`optional	query	string	at most 60 characters
`actor`optional	query	string	at most 200 characters
`from`optional	query	string (date)
`to`optional	query	string (date)
`before`optional	query	integer

Responses

200A page of the log.
AdminAuditPage
- entriesarray of AdminAuditEntryrequired
- nextCursornumber or nullrequired
- actionsarray of stringrequired
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/audit' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

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

GET/api/v1/admin/coverage

Cover coverage

AdminBeta: may change

How collectors’ copies and the catalog’s variants are covered, and the moderation queues. Aggregates only, cached for a few minutes.

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

Responses

200Coverage.
AdminCoverCoverage
- copiesobjectrequired
  Fields of copies
  totalnumberrequired
  coverednumberrequired
  nonenumberrequired
  variantnumberrequired
  linkedFetchednumberrequired
  linkedPendingnumberrequired
  unlinkednumberrequired
  unlinkedUntriednumberrequired
  unlinkedNotFoundnumberrequired
  unlinkedWeaknumberrequired
- variantsobjectrequired
  Fields of variants
  oursnumberrequired
  providernumberrequired
  missingnumberrequired
- variantsTiernumberrequired
- added24hobjectrequired
  Fields of added24h
  issuesnumberrequired
  editionsnumberrequired
- moderationobjectrequired
  Fields of moderation
  variantsnumberrequired
  variantsImportnumberrequired
  variantsCollectednumberrequired
  coversnumberrequired
  coversCollectednumberrequired
  codesnumberrequired
  codesCollectednumberrequired
- generatedAtstringrequired
304Not modified: your copy (the ETag in If-None-Match) is current.

Errors (404, 500, 503)

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).
503not_migrated
not_migrated: The tool needs a database update that hasn’t been applied yet.

curl

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

TypeScript SDK

await collector.getAdminCoverage();

GET/api/v1/admin/health

Incidents, cron jobs and capacity

AdminBeta: may change

Incidents by status, every cron job’s state, recent cron runs and capacity checks.

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

Parameters

Name	In	Type	About
`status`optional	query	enum	Which items (default open).One of `open`, `resolved`, `all`default "open"

Responses

200Health.
AdminHealthView
- generatedAtstringrequired
- incidentsarray of AdminIncidentrequired
- countsobjectrequired
  Fields of counts
  opennumberrequired
  resolvednumberrequired
- jobsarray of AdminCronJobrequired
- runsarray of AdminCronRunrequired
- monitoringSincestring or nullrequired
- capacityAdminCapacity or nullrequired
304Not modified: your copy (the ETag in If-None-Match) is current.

Errors (400, 404, 500, 503)

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).
503not_migrated
not_migrated: The tool needs a database update that hasn’t been applied yet.

curl

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

TypeScript SDK

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

PATCH/api/v1/admin/health/incidents/{id}

Resolve or reopen an incident

AdminBeta: may change

Set an operations incident to resolved or back to open.

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

statusenumrequired
One ofopenresolved

Responses

200The incident.
object
- incidentobjectrequired
  Fields of incident
  idstringrequired
  statusenumrequired
  One ofopenresolved

Errors (400, 404, 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.
500internal
internal: Something went wrong on our side (quote the requestId).
503not_migrated
not_migrated: The tool needs a database update that hasn’t been applied yet.

curl

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

TypeScript SDK

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

GET/api/v1/admin/overview

Admin overview counts

AdminBeta: may change

Real counts of rows that exist right now; nothing estimated.

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

Responses

200The counts.
AdminOverview
- generatedAtstringrequired
- peopleobjectrequired
  Fields of people
  usersnumberrequired
  newThisWeeknumberrequired
  disablednumberrequired
  adminsnumberrequired
  publicProfilesnumberrequired
- collectionsobjectrequired
  Fields of collections
  ownednumberrequired
  wishlistnumberrequired
  soldnumberrequired
  photosnumberrequired
- catalogobjectrequired
  Fields of catalog
  publishersnumberrequired
  seriesnumberrequired
  issuesnumberrequired
  editionsnumberrequired
  creatorsnumberrequired
  provisionalSeriesnumberrequired
  provisionalIssuesnumberrequired
- moderationobjectrequired
  Fields of moderation
  pendingnumberrequired
  coversPendingnumberrequired
  variantsPendingnumberoptional
  codesPendingnumberoptional
  mergesLast30Daysnumberrequired
  openReportsnumberrequired
- importsobjectrequired
  Fields of imports
  activenumberrequired
  failedLast7Daysnumberrequired
  lastActivityAtstring or nullrequired
  conflictsOpennumberoptional
  conflictsNewLast7Daysnumberoptional
- storesobjectrequired
  Fields of stores
  activenumberrequired
  unverifiednumberrequired
  activeListingsnumberrequired
  openHoldsnumberrequired
- paidSubscriptionsmap of numberrequired
- operationsobjectoptional
  Fields of operations
  openSupportnumberrequired
  openIncidentsnumberrequired
  failedRunsLast24hnumberrequired
- planGrantsmap of numberrequired
- liveAnnouncementsnumberrequired
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/overview' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

await collector.getAdminOverview();

GET/api/v1/admin/settings

Platform settings

AdminBeta: may change

Seller fee and hold defaults.

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

Responses

200The settings.
PlatformSettingsView
- sellerFeeobjectrequired
  Fields of sellerFee
  feeBpsnumberrequired
  minFeeCentsnumberrequired
  maxFeeCentsnumberrequired
  currencystringrequired
- holdsobjectrequired
  Fields of holds
  defaultHoldDaysnumberrequired
  maxOpenHoldsPerBuyernumberrequired
- updatedAtobjectrequired
  Fields of updatedAt
  sellerFeestring or nullrequired
  holdsstring or nullrequired
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/settings' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

await collector.getAdminSettings();

PUT/api/v1/admin/settings

Change platform settings

AdminBeta: may change

Validated, then written with its audit row in one transaction.

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

Request body (required, application/json)

object

sellerFeeobjectoptional
Fields of sellerFee
- feeBpsintegerrequired0–3000
- minFeeCentsintegerrequired0–10000000
- maxFeeCentsintegerrequired0–10000000
- currency"USD"required
holdsobjectoptional
Fields of holds
- defaultHoldDaysintegerrequired1–30
- maxOpenHoldsPerBuyerintegerrequired1–200

Responses

200The settings now.
PlatformSettingsView
- sellerFeeobjectrequired
  Fields of sellerFee
  feeBpsnumberrequired
  minFeeCentsnumberrequired
  maxFeeCentsnumberrequired
  currencystringrequired
- holdsobjectrequired
  Fields of holds
  defaultHoldDaysnumberrequired
  maxOpenHoldsPerBuyernumberrequired
- updatedAtobjectrequired
  Fields of updatedAt
  sellerFeestring or nullrequired
  holdsstring or nullrequired

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 PUT 'https://collection.id/api/v1/admin/settings' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d @body.json

TypeScript SDK

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

GET/api/v1/admin/usage

Product analytics

AdminBeta: may change

The activation funnel over days (30, 90 or 180), and weekly cohorts and feature use over weeks (4–26). Small counts are hidden.

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

Parameters

Name	In	Type	About
`days`optional	query	integer	default 90
`weeks`optional	query	integer	4–26 · default 12

Responses

200Aggregates.
AdminUsage
- generatedAtstringrequired
- todaystringrequired
- daysnumberrequired
- weeksnumberrequired
- funnelarray of objectrequired
  Fields of funnel
  stepstringrequired
  detailstringrequired
  usersnumber or nullrequired
  null: 1-4 people, hidden.
- cohortsarray of objectrequired
  Fields of cohorts
  weekstringrequired
  Monday the cohort’s week starts (YYYY-MM-DD, UTC).
  stepstringrequired
  usersnumber or nullrequired
- featuresarray of objectrequired
  Fields of features
  weekstringrequired
  eventstringrequired
  detailstring or nullrequired
  usersnumber or nullrequired
  userDaysnumber or nullrequired
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/usage' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

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