Developer documentation

API v2

Collected API reference.

Look up books, retrieve descriptions and reading profiles, or process a batch of records. Choose an endpoint below for its parameters, permissions and examples.

Create developer account Download OpenAPI

Get API access

Create an account, request access, then create a server-side key.

Find a book

Look up an ISBN or title and author to get a work ID.

Fetch its details

Use the work ID to retrieve its description, editions, authors and reading profile.

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

Catalog and recommendation endpoints.

Choose an endpoint to see its request and response format. Responses are shortened examples; replace example IDs with IDs returned by the API.

Work and edition objects use id. Relationship fields such as work_id point to the owning work. A book record’s version is returned in data.record_version; its reading profile is in data.reader_intelligence. Descriptions and profiles can be missing.

GET/v2/search

catalog:read

Search works

Find books by title, author, ISBN or a combination of these.

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=East of Eden" \
  --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

Get supported content types, genres, themes and other catalog facets. Reading profile traits are returned separately in each profile.

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

Match an ISBN or a title-and-author record. Uncertain matches return candidates for you to review.

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":{"isbn":"9780142000656"},"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

Match a batch of records and keep each result tied to its original input.

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, or fewer if your plan has a lower limit.

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 IDs from another provider to Collected 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 provider IDs. Full book records can be returned for up to 25 items.

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

Return the book, preferred edition, description and reading profile.

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 a reading profile

Return a reading profile without the rest of the book record. Categorical values appear in traits, complexity values in scores, and derived reading demand in projections.

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

Get books in a batch

Return book records in input order and mark IDs that are not found.

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, or fewer if your plan has a lower limit.

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

Return an author, their bio when available, and the first page of their books.

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

Return works in popularity order. Use the returned cursor for the next page from the same catalog version.

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

Get recommendations

Return books that match a request and reading preferences, excluding the work IDs you supply.

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

An optional request in the reader’s own words.

preferencesobject

Genre, tone, pace, effort and reading-experience filters.

exclude_work_idsarray

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

limitinteger

Return up to 10 matching works. The API may return fewer when fewer books fit.

POST/v2/feedback

feedback:write

Submit catalog feedback

Report a specific book error or a recurring catalog problem. This permission is available 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

A short explanation or source. Do not send secrets or reader data.

Operations

Errors you can act on.

Every API 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.

Catalog and recommendation endpoints.

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 a reading profile

Parameters

Get books in a batch

Parameters

Get an author

Parameters

Page through a bibliography

Parameters

List editions

Parameters

Get an edition

Parameters

Get recommendations

Parameters

Submit catalog feedback

Parameters

Errors you can act on.