Developer documentation

Production · v2

Build with book context that holds up.

Resolve the actual work, add reader-facing intelligence, and keep identity confidence, provenance, and revisions attached to the result.

Create developer account Download OpenAPI

01Create a key

Issue a scoped server-side key from your account.

02Resolve identity

Start from ISBN or imperfect title and author data.

03Hydrate the work

Fetch description, editions, authors, and reader intelligence.

Authentication

Keys stay on your server.

Commercial calls use a scoped bearer key. Put it in a server-side secret store and reference it as COLLECTED_API_KEY. Never ship it in browser JavaScript or a mobile binary.

Authorization: Bearer $COLLECTED_API_KEYKeys are shown once. Existing plaintext cannot be recovered.

API reference

Everything in v2.

Every route is below. Scan the full surface, or jump straight to what you need.

GET/v2/search

catalog:read

Search works

Find likely canonical works and return compact work-and-edition cards.

Required scopecatalog:read

Usage1 catalog request

Base URLapi.collectedreads.com

curl --fail-with-body --get "https://api.collectedreads.com/v2/search" \
  -H "Authorization: Bearer ${COLLECTED_API_KEY}" \
  --data-urlencode "q=moby dick" \
  --data-urlencode "language=en" \
  --data-urlencode "market=US" \
  --data-urlencode "limit=5"

catalog:read1 catalog request

Parameters

1 required

qstringrequired

Title, author, ISBN, or a useful combination.

languagestring

Preferred BCP 47 language. Defaults to en.

marketstring

Two-letter market used for edition preference.

limitinteger

Maximum compact results to return.

GET/v2/taxonomy

catalog:read

Get the taxonomy

Load the current typed facet vocabulary before building filters or validating stored preferences.

Required scopecatalog:read

Usage1 catalog request

Base URLapi.collectedreads.com

curl --fail-with-body --get "https://api.collectedreads.com/v2/taxonomy" \
  -H "Authorization: Bearer ${COLLECTED_API_KEY}"

catalog:read1 catalog request

Parameters

0 required

No parameters.

POST/v2/resolve

resolve:read

Resolve one record

Resolve an ISBN or imperfect title-and-author record without hiding ambiguity.

Required scoperesolve:read

Usage1 resolved item

Base URLapi.collectedreads.com

curl --fail-with-body --request POST "https://api.collectedreads.com/v2/resolve" \
  -H "Authorization: Bearer ${COLLECTED_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"query":{"title":"The Left Hand of Darkness","author":"Ursula K. Le Guin"},"preferences":{"languages":["en"],"market":"US"},"limit":5}'

resolve:read1 resolved item

Parameters

1 required

queryobjectrequired

At least one of title, author, or ISBN.

preferencesobject

Language and market preferences for edition selection.

limitinteger

Maximum candidates when the identity is ambiguous.

POST/v2/resolve/batch

bulk:read

Resolve a batch

Resolve an ordered batch and correlate every result by its input position.

Required scopebulk:read

Usage1 bulk item per input

Base URLapi.collectedreads.com

curl --fail-with-body --request POST "https://api.collectedreads.com/v2/resolve/batch" \
  -H "Authorization: Bearer ${COLLECTED_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"items":[{"query":{"isbn":"9780441478125"},"preferences":{"languages":["en"],"market":"US"}},{"query":{"title":"Moby Dick","author":"Herman Melville"},"preferences":{"languages":["en"],"market":"US"}}]}'

bulk:read1 bulk item per input

Parameters

2 required

itemsarrayrequired

Up to 100 inputs, further bounded by the account plan.

queryobjectrequired

Each item contains the same query accepted by single-record resolve.

preferencesobject

Optional language and market preferences for each item.

POST/v2/source-aliases/resolve/batch

bulk:read

Resolve source aliases

Map exact provider aliases to canonical works during a catalog migration.

Required scopebulk:read

Usage1 bulk item per input

Base URLapi.collectedreads.com

curl --fail-with-body --request POST "https://api.collectedreads.com/v2/source-aliases/resolve/batch" \
  -H "Authorization: Bearer ${COLLECTED_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"preferences":{"languages":["en"],"market":"US"},"include_selected":true,"items":[{"client_ref":"legacy-1","aliases":[{"entity_type":"WORK","scheme":"OPEN_LIBRARY","value":"OL45804W"}]}]}'

bulk:read1 bulk item per input

Parameters

2 required

itemsarrayrequired

Up to 500 exact aliases; rich hydration is capped at 25.

aliasesarrayrequired

Up to four exact work or edition aliases per item.

include_selectedboolean

Include the compact selected work and edition snapshot. Defaults to false.

GET/v2/works/{work_id}

catalog:read

Get a work

Hydrate canonical identity, preferred edition, description, and typed reader intelligence.

Required scopecatalog:read

Usage1 catalog request

Base URLapi.collectedreads.com

curl --fail-with-body --get "https://api.collectedreads.com/v2/works/stw_example" \
  -H "Authorization: Bearer ${COLLECTED_API_KEY}" \
  --data-urlencode "language=en" \
  --data-urlencode "market=US"

catalog:read1 catalog request

Parameters

1 required

work_idpath stringrequired

Canonical Collected work ID.

languagestring

Preferred response and edition language.

marketstring

Market used for preferred-edition selection.

GET/v2/works/{work_id}/reader-intelligence

catalog:read

Get reader intelligence

Fetch the typed reading-experience profile without hydrating the entire work record.

Required scopecatalog:read

Usage1 catalog request

Base URLapi.collectedreads.com

curl --fail-with-body --get "https://api.collectedreads.com/v2/works/stw_example/reader-intelligence" \
  -H "Authorization: Bearer ${COLLECTED_API_KEY}"

catalog:read1 catalog request

Parameters

1 required

work_idpath stringrequired

Canonical Collected work ID.

POST/v2/works/batch

bulk:read

Hydrate works in batch

Hydrate an ordered set of canonical work IDs while preserving missing rows.

Required scopebulk:read

Usage1 bulk item per input

Base URLapi.collectedreads.com

curl --fail-with-body --request POST "https://api.collectedreads.com/v2/works/batch" \
  -H "Authorization: Bearer ${COLLECTED_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"preferences":{"languages":["en"],"market":"US"},"items":[{"work_id":"stw_example","client_ref":"row-1"}]}'

bulk:read1 bulk item per input

Parameters

1 required

itemsarrayrequired

Up to 100 work IDs, further bounded by the account plan.

client_refstring

Optional identifier echoed in the corresponding result.

preferencesobject

Language and market preferences for edition selection.

GET/v2/authors/{author_id}

catalog:read

Get an author

Load exact author identity, an available profile, and the first bibliography page.

Required scopecatalog:read

Usage1 catalog request

Base URLapi.collectedreads.com

curl --fail-with-body --get "https://api.collectedreads.com/v2/authors/sta_example" \
  -H "Authorization: Bearer ${COLLECTED_API_KEY}" \
  --data-urlencode "language=en" \
  --data-urlencode "market=US" \
  --data-urlencode "limit=12"

catalog:read1 catalog request

Parameters

1 required

author_idpath stringrequired

Canonical Collected author ID.

languagestring

Preferred profile, title, and edition language.

marketstring

Market used for preferred-edition selection.

limitinteger

Bibliography items to include on the first page.

GET/v2/authors/{author_id}/works

catalog:read

Page through a bibliography

Read popularity-ranked canonical works using a signed, revision-bound cursor.

Required scopecatalog:read

Usage1 catalog request

Base URLapi.collectedreads.com

curl --fail-with-body --get "https://api.collectedreads.com/v2/authors/sta_example/works" \
  -H "Authorization: Bearer ${COLLECTED_API_KEY}" \
  --data-urlencode "language=en" \
  --data-urlencode "market=US" \
  --data-urlencode "limit=25"

catalog:read1 catalog request

Parameters

1 required

author_idpath stringrequired

Canonical Collected author ID.

languagestring

Preferred title and edition language.

marketstring

Market used for preferred-edition selection.

limitinteger

Works to return on this page.

cursorstring

Opaque next cursor returned by the previous page.

GET/v2/works/{work_id}/editions

catalog:read

List editions

Page through editions and filter by language, market, variant, or family.

Required scopecatalog:read

Usage1 catalog request

Base URLapi.collectedreads.com

curl --fail-with-body --get "https://api.collectedreads.com/v2/works/stw_example/editions" \
  -H "Authorization: Bearer ${COLLECTED_API_KEY}" \
  --data-urlencode "language_preference=en" \
  --data-urlencode "market=US" \
  --data-urlencode "limit=25"

catalog:read1 catalog request

Parameters

1 required

work_idpath stringrequired

Canonical Collected work ID.

language_preferencestring

Preferred language when ranking editions.

marketstring

Market used when ranking editions.

languagestring

Optional exact edition-language filter.

variantstring

Optional edition-variant filter.

family_idstring

Optional edition-family filter.

limitinteger

Editions to return on this page.

cursorstring

Opaque, signed, filter-bound cursor.

GET/v2/editions/{edition_id}

catalog:read

Get an edition

Read identifiers and bibliographic facts for one exact edition.

Required scopecatalog:read

Usage1 catalog request

Base URLapi.collectedreads.com

curl --fail-with-body --get "https://api.collectedreads.com/v2/editions/ste_example" \
  -H "Authorization: Bearer ${COLLECTED_API_KEY}" \
  --data-urlencode "language=en" \
  --data-urlencode "market=US"

catalog:read1 catalog request

Parameters

1 required

edition_idpath stringrequired

Canonical Collected edition ID.

languagestring

Preferred display language.

marketstring

Market used for the edition's work context.

POST/v2/recommendations

recommendations:run

Run a recommendation

Retrieve and rank a bounded candidate set from taste, constraints, and exact exclusions.

Required scoperecommendations:run

Usage1 recommendation request

Base URLapi.collectedreads.com

curl --fail-with-body --request POST "https://api.collectedreads.com/v2/recommendations" \
  -H "Authorization: Bearer ${COLLECTED_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"prompt":"spooky, sharp, and well-written","limit":5,"exclude_work_ids":["stw_already_read"],"preferences":{"tone":["EERIE","WITTY"]}}'

recommendations:run1 recommendation request

Parameters

0 required

promptstring

Optional natural-language intent.

preferencesobject

Structured genre, tone, pace, demand, and experience constraints.

exclude_work_idsarray

Exact work IDs that must not appear. Supports large existing-library exclusion sets.

limitinteger

Return 1 to 10 aligned works; weak padding is not added.

POST/v2/feedback

feedback:write

Submit catalog feedback

Send a bounded field or pattern correction into the review queue. This restricted scope is issued only to approved partners.

Required scopefeedback:write

Usage1 feedback write

Base URLapi.collectedreads.com

curl --fail-with-body --request POST "https://api.collectedreads.com/v2/feedback" \
  -H "Authorization: Bearer ${COLLECTED_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"scope":"FIELD","work_id":"stw_example","field_name":"publication_date","issue_type":"INCORRECT","severity":"HIGH","note":"First publication was 1969.","reporter":"Catalog operations"}'

feedback:write1 feedback write

Parameters

3 required

scopestringrequired

RECORD, FIELD, or PATTERN.

work_idstringrequired

The exact canonical work ID; omitted only for pattern feedback.

field_namestring

Required for FIELD feedback and limited to supported metadata fields.

issue_typestringrequired

A stable category such as INCORRECT, MISSING, or WRONG_EDITION.

notestring

Concise evidence or context; do not send secrets or reader data.

Operations

Errors you can act on.

Every production response includes an X-Request-ID. Errors carry a stable machine code, and rate-limited responses include retry guidance. Request logs retain route and performance metadata—not queries, book IDs, bodies, credentials, IPs, or user agents.

401Invalid or revoked credentials

403Scope, entitlement, or batch limit

409Cursor belongs to an older revision

429Rate or plan quota reached

503Recommendation capacity is full

req_…Use the request ID in logs and support

Keys stay on your server.

Everything in v2.

Search & resolve

Works

Authors & editions

Recommendations

Search works

Parameters

Get the taxonomy

Parameters

Resolve one record

Parameters

Resolve a batch

Parameters

Resolve source aliases

Parameters

Get a work

Parameters

Get reader intelligence

Parameters

Hydrate works in batch

Parameters

Get an author

Parameters

Page through a bibliography

Parameters

List editions

Parameters

Get an edition

Parameters

Run a recommendation

Parameters

Submit catalog feedback

Parameters

Errors you can act on.