API reference / Collectors

Price alerts

5 operations.

GET/api/v1/insights/alerts

Your price alerts

Signed in

Price alerts with the estimates they watch, and wishlist targets.

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

Responses

200The alerts.
PriceAlerts
The collector’s price alerts, and their wishlist targets.
- entitlementsInsightsEntitlementsrequired
- currencystringrequired
  The collector’s preferred currency (new alerts use it).
- availablebooleanrequired
  False until price alerts are set up on this deployment.
- alertsarray of PriceAlertrequired
- limitintegerrequired
- targetsarray of objectrequired
  Fields of targets
  itemIdstring (uuid)required
  issueIdstring (uuid)required
  editionIdstring (uuid) or nullrequired
  seriesTitlestring or nullrequired
  issueNumberstring or nullrequired
  coverUrlstring (uri) or nullrequired
  targetCentsintegerrequired
  currencystringrequired
  ISO 4217 code, e.g. USD.
  minGradenumber or nullrequired
304Not modified: your copy (the ETag in If-None-Match) is current.

Errors (401, 500)

401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
500internal
internal: Something went wrong on our side (quote the requestId).

curl

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

TypeScript SDK

await collector.listPriceAlerts();

POST/api/v1/insights/alerts

Create a price alert

Signed inIdempotent

Watch an issue’s estimate for a grade band; tell me when it goes below or above a target.

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

Request body (required, application/json)

object

issueIdstring (uuid)required
editionIdstring (uuid) or nullrequired
gradedbooleanrequired
bandIdenumrequired
One of9.8+9.0-9.67.0-8.54.0-6.5under-4
directionenumrequired
One ofbelowabove
targetCentsintegerrequiredat most 100000000
currencystringoptionaldefault "USD"
notestring or nulloptionalat most 300 characters
cooldownDaysintegeroptional1–90 · default 7
sourceItemIdstring (uuid) or nulloptional

Responses

201The alert.
object
- alertPriceAlertrequired

Errors (400, 401, 403, 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.
401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
403feature_required
feature_required: The plan doesn’t include this (details.feature names it).
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/insights/alerts' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d @body.json

TypeScript SDK

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

DELETE/api/v1/insights/alerts/{id}

Delete a price alert

Signed in

Delete one of your price alerts. Another collector’s alert, or one already gone, is a 404.

SDK: collector.deletePriceAlert()
Key scopes: insights:write(API keys are coming soon)
Headers: X-Request-Id

Parameters

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

Responses

200Deleted.
object
- ok"true"required

Errors (401, 404, 500)

401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404not_found
not_found: Nothing at that address.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl -X DELETE 'https://collection.id/api/v1/insights/alerts/<id>' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

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

PATCH/api/v1/insights/alerts/{id}

Change a price alert

Signed in

The target, direction, note, cool-down, or pause and resume.

SDK: collector.updatePriceAlert()
Key scopes: insights: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

directionenumoptional
One ofbelowabove
targetCentsintegeroptionalat most 100000000
notestring or nulloptionalat most 300 characters
isActivebooleanoptional
cooldownDaysintegeroptional1–90

Responses

200The alert.
object
- alertPriceAlertrequired

Errors (400, 401, 403, 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.
401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
403feature_required
feature_required: The plan doesn’t include this (details.feature names it).
404not_found
not_found: Nothing at that address.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

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

TypeScript SDK

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

GET/api/v1/insights/alerts/preview

Preview a price alert

Signed in

What an alert would watch right now: the current estimate and the issue’s editions.

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

Parameters

Name	In	Type	About
`issue`required	query	string (uuid)	The issue.
`edition`optional	query	"none" or string (uuid)	An edition, or none for the issue’s pool.
`graded`optional	query	enum	1 for slabbed copies, 0 for raw.One of `0`, `1`default "1"
`band`required	query	enum	One of `9.8+`, `9.0-9.6`, `7.0-8.5`, `4.0-6.5`, `under-4`

Responses

200The preview.
PriceAlertPreview
What an alert would watch right now.
- currentobject or nullrequired
  Fields of current
  valueCentsintegerrequired
  lowCentsinteger or nullrequired
  highCentsinteger or nullrequired
  currencystringrequired
  ISO 4217 code, e.g. USD.
  methodstringrequired
  sampleSizeintegerrequired
  confidenceLabelenum or nullrequired
  One oflowfairgoodstrong
  updatedAtstring (date-time) or nullrequired
- editionsarray of objectrequired
  Fields of editions
  idstring (uuid)required
  namestringrequired
- subjectobjectrequired
  Fields of subject
  seriesTitlestring or nullrequired
  seriesSlugstring or nullrequired
  startYearinteger or nullrequired
  issueNumberstring or nullrequired
  issueSlugstring or nullrequired
  coverUrlstring (uri) or nullrequired
  editionNamestring or nullrequired
304Not modified: your copy (the ETag in If-None-Match) is current.

Errors (400, 401, 404, 500)

400invalid_request
invalid_request: The query or body doesn’t match the schema (see errors[]).
401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404not_found
not_found: The issue isn’t in the catalog.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl 'https://collection.id/api/v1/insights/alerts/preview' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

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