{ "openapi": "3.1.0", "info": { "title": "Book Report API", "version": "1.0.0", "summary": "Read reports, account-aware field choices, and catalog metadata from Book Report.", "description": "Use the Book Report API to run read-only reports and retrieve the authenticated account's report vocabulary, settings, and catalog metadata.\n\nA report has four parts: a date range, attributes that group rows, metrics that measure each row, and optional filters that narrow the underlying data.\n\nFor a common report, call POST /api/v1/report directly. The built-in field keys are defined in this document. Use /api/v1/report-fields when software needs to discover custom or account-dependent fields, /api/v1/report-filter-values when it needs authoritative filter values, /api/v1/account-context when account defaults matter, and /api/v1/catalog for descriptive book and edition metadata.\n\nMultiple values for one filter are combined with OR. Different filter keys are combined with AND.\n\nRelative ranges are resolved using the Book Report server calendar in UTC. Explicit start and end dates are inclusive; use them when a local-calendar boundary matters.\n\nThese endpoints read data already imported into Book Report. They do not start or refresh distributor imports.\n\nThe public API allows 3,600 requests per account per clock hour across all of that account's API keys. A 429 response includes Retry-After.\n\nAll /api/v1/* endpoints support public browser CORS, including Authorization headers and OPTIONS preflight requests. Allow, Retry-After, WWW-Authenticate, and X-Api-Version response headers are exposed to browser code. A browser app can call the API directly when the user intentionally supplies a Book Report API key; avoid embedding a reusable key in publicly served source code." }, "servers": [ { "url": "https://app.getbookreport.com", "description": "Production" } ], "security": [ { "ApiKeyBearerAuth": [] } ], "tags": [ { "name": "Reports", "description": "Numeric sales, earnings, units, borrows, pages read, advertising, and royalties." }, { "name": "Discovery", "description": "Optional runtime discovery for custom fields, feature-dependent fields, and account filter values." }, { "name": "Account", "description": "Safe account report defaults and connected-source context." }, { "name": "Catalog", "description": "Resolved Book and Edition metadata. Catalog responses use camelCase in REST v1." } ], "paths": { "/api/v1/report-fields": { "get": { "operationId": "listReportFields", "tags": [ "Discovery" ], "summary": "Discover account-available report fields", "description": "Optional for fixed integrations because common built-in keys are defined in this OpenAPI document. Use this endpoint for a dynamic report builder or to discover custom catalog attributes and feature-dependent fields available to this account. This response is authoritative for the authenticated account: every returned attribute and metric may be combined in one report. A field that is absent is unavailable to the account, and requesting an unavailable or unknown field returns 400 invalid_request.", "responses": { "200": { "description": "The report vocabulary available to the authenticated account.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportFieldsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "504": { "$ref": "#/components/responses/RequestTimeout" } } } }, "/api/v1/report-filter-values": { "get": { "operationId": "listReportFilterValues", "tags": [ "Discovery" ], "summary": "Discover authoritative report filter values", "description": "Call without filter to list available filters. Call with filter to page and search its account-specific values. Pass values[].value—not the display label—to ReportRequest.filters.", "parameters": [ { "name": "filter", "in": "query", "required": false, "description": "Report filter key to inspect. Omit to list available filters.", "schema": { "$ref": "#/components/schemas/ReportFilterKey" } }, { "name": "query", "in": "query", "required": false, "description": "Optional case-insensitive search across labels and values for the selected filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of values to return. Defaults to 50; maximum 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Zero-based cursor returned as nextCursor by a previous call. Defaults to 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Available filters or values for one filter.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterValuesResponse" }, "examples": { "filters": { "summary": "List available filters", "value": { "filterValueUsage": { "reportFilterField": "value", "displayField": "label", "note": "Pass values[].value to report filters. values[].label is display text and may not be accepted as a report filter input." }, "filters": [ { "key": "country", "label": "Country", "type": "String", "optionCount": 2 }, { "key": "format", "label": "Format", "type": "String", "optionCount": 3 } ], "totalFilters": 2 } }, "values": { "summary": "Values for the country filter", "value": { "filterValueUsage": { "reportFilterField": "value", "displayField": "label", "note": "Pass values[].value to report filters. values[].label is display text and may not be accepted as a report filter input." }, "filter": { "key": "country", "label": "Country", "type": "String", "optionCount": 2 }, "values": [ { "label": "Canada", "value": "CA" }, { "label": "United States", "value": "US" } ], "totalValues": 2, "matchedValues": 2, "returnedValues": 2, "cursor": 0, "nextCursor": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "504": { "$ref": "#/components/responses/RequestTimeout" } }, "x-bookreport-supported-filters": [ { "key": "book", "label": "Book", "type": "Book", "description": "The book title. Multiple editions of the same book, such as ebook, paperback, hardcover, audiobook, and wide-store editions, are grouped together under one title." }, { "key": "product", "label": "Product", "type": "Book", "description": "The distributor-specific product or edition row. Unlike Book, this does not collapse reviewed non-book items into one shared row." }, { "key": "series_number", "label": "Series #", "type": "Book", "description": "The book, displayed as Series Title #Position when series metadata is available; otherwise it falls back to the book title." }, { "key": "author", "label": "Author", "type": "Book", "description": "The primary author of the book involved in the transaction. When a book has multiple authors, this uses the first or primary author." }, { "key": "series", "label": "Series", "type": "Book", "description": "The series that the book is part of, when series metadata is available." }, { "key": "publication_year", "label": "Publication Year", "type": "Book", "description": "The year the book was published. For pre-orders, this is the year the pre-order period completed and the book became available." }, { "key": "language", "label": "Language", "type": "Book", "description": "The language associated with the book, when available." }, { "key": "book_id", "label": "Book ID", "type": "Book", "description": "The unique identifier for each book product or edition. Each edition and each distributor version can have a different ID." }, { "key": "co_author", "label": "Co-author", "type": "Book", "description": "Contributor names listed as co-authors in distributor metadata. Multiple names may be combined in one value." }, { "key": "translator", "label": "Translator", "type": "Book", "description": "Contributor names listed as translators in distributor metadata. Multiple names may be combined in one value." }, { "key": "illustrator", "label": "Illustrator", "type": "Book", "description": "Contributor names listed as illustrators in distributor metadata. Multiple names may be combined in one value." }, { "key": "editor", "label": "Editor", "type": "Book", "description": "Contributor names listed as editors in distributor metadata. Multiple names may be combined in one value." }, { "key": "marketplace", "label": "Marketplace", "type": "Transaction", "description": "The marketplace where the transaction took place, such as Amazon.com, Amazon.co.uk, Google Play Books, Apple Books, Smashwords, Barnes and Noble, or Kobo." }, { "key": "transaction_type", "label": "Transaction Type", "type": "Transaction", "description": "The transaction type as reported by the distributor. Each distributor defines its own transaction types." }, { "key": "format", "label": "Format", "type": "Transaction", "description": "The format of the book involved in the transaction, such as eBook, paperback, hardcover, or audiobook." }, { "key": "distributor", "label": "Distributor", "type": "Transaction", "description": "The distributor or publishing platform that put the book on sale, such as Kindle Direct Publishing, Draft2Digital, Google Play Books, Kobo Writing Life, or Barnes & Noble Press." }, { "key": "country", "label": "Country", "type": "Transaction", "description": "The country where the transaction took place. For KDP sales, countries are inferred from the Amazon marketplace; most other distributors provide the country directly." }, { "key": "data_owner", "label": "Data Owner", "type": "Transaction", "description": "The Book Report data-sharing owner associated with the transaction, when shared data is present." }, { "key": "royalty_percentage", "label": "Royalty Percentage", "type": "Transaction", "description": "The percentage of the sale price counted as royalties, where applicable." }, { "key": "offer_price", "label": "Offer Price", "type": "Transaction", "description": "The price at which the book was offered at the time of sale, converted into the selected currency and grouped into price ranges." } ] } }, "/api/v1/account-context": { "get": { "operationId": "getAccountContext", "tags": [ "Account" ], "summary": "Get safe account context", "description": "Optional context for software that needs to explain or reproduce the account defaults automatically applied to reports. pageReadRoyaltyRateMode controls which rate Book Report uses to estimate Kindle Unlimited page-read royalties while official marketplace rates are unavailable. kenpcFractionPerEstimatedBorrow is the decimal fraction of a book's KENPC treated as one estimated Kindle Unlimited borrow. These borrow-estimation settings are unrelated to series read-through. No email address, account ID, API key, OAuth ID, cookie, token, or raw third-party account identifier is returned.", "responses": { "200": { "description": "Safe context for the authenticated account.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountContextResponse" }, "example": { "reportSettings": { "currency": "USD", "pageReadRoyaltyRateMode": "previous_month", "customPageReadRoyaltyRateUsd": null, "kenpcFractionPerEstimatedBorrow": 0.75, "linkDomain": "www.amazon.com" }, "connectedSources": [ { "name": "Amazon KDP", "domain": "kdp.amazon.com", "connectionMode": "browser", "category": "publishing", "connected": true, "reconnectWarning": null } ], "capabilities": { "readOnly": true, "reportDefaultsAppliedToMcpReports": true, "reportDefaultsAppliedToApiReports": true, "explicitReportCurrencyOverride": true, "includesPii": false } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "504": { "$ref": "#/components/responses/RequestTimeout" } } } }, "/api/v1/catalog": { "get": { "operationId": "getCatalog", "tags": [ "Catalog" ], "summary": "Get resolved catalog metadata", "description": "Returns the same resolved Book and Edition model that future catalog editing will use, without exposing write operations. Book-wide metadata lives on each book; source-specific format, distributor, language, KENPC, and contributor metadata lives on editions. Each resolved catalog attribute contains value and inferred. inferred is true when Book Report supplied the value from catalog defaults.\n\nquery, author, series, format, and distributor are combined with AND at the logical-book level. Edition filters match a book when any edition has the requested value. When includeEditions=true, every edition belonging to each matching book is returned, not only the editions that matched an edition filter.\n\nmeta.totalBooks is the number of matching visible books before pagination. meta.truncated is true exactly when offset + returnedBooks is less than totalBooks. Exclusion counts include matching catalog objects hidden by the archived or non-book visibility defaults; they do not count unrelated hidden objects outside the current search.\n\nbookKey and editionKey identify catalog objects; do not assume they are accepted report filters. Use /api/v1/report-filter-values for authoritative report inputs. Likewise, reporting *_key columns are reporting identifiers and are not guaranteed to equal catalog keys. Archived books and reviewed non-book products are hidden by default.", "parameters": [ { "name": "query", "in": "query", "required": false, "description": "Case-insensitive search across book and edition identifiers and metadata.", "schema": { "type": "string" } }, { "name": "author", "in": "query", "required": false, "description": "Case-insensitive author or contributor search.", "schema": { "type": "string" } }, { "name": "series", "in": "query", "required": false, "description": "Case-insensitive series search.", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "Case-insensitive edition format search, such as ebook, paperback, hardcover, or audiobook.", "schema": { "type": "string" } }, { "name": "distributor", "in": "query", "required": false, "description": "Case-insensitive edition distributor search, such as Amazon, BookFunnel, IngramSpark, Draft2Digital, Google Play, or Kobo.", "schema": { "type": "string" } }, { "name": "includeEditions", "in": "query", "required": false, "description": "Include edition-level metadata under each logical book. Defaults to false.", "schema": { "type": "boolean", "default": false } }, { "name": "includeArchived", "in": "query", "required": false, "description": "Include archived books that are hidden from the catalog by default. Reports still include their sales. Defaults to false.", "schema": { "type": "boolean", "default": false } }, { "name": "includeNonBookProducts", "in": "query", "required": false, "description": "Include reviewed non-book products that are hidden by default. Defaults to false.", "schema": { "type": "boolean", "default": false } }, { "name": "sortBy", "in": "query", "required": false, "description": "Catalog sort key. Defaults to title.", "schema": { "type": "string", "enum": [ "title", "publicationDate", "series" ], "default": "title" } }, { "name": "sortDirection", "in": "query", "required": false, "description": "Catalog sort direction. Defaults to asc.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } }, { "name": "limit", "in": "query", "required": false, "description": "Books per page. Defaults to 100; maximum 500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset. Defaults to 0.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Resolved catalog metadata.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogResponse" }, "examples": { "books": { "summary": "Books without editions", "value": { "meta": { "totalBooks": 1, "returnedBooks": 1, "offset": 0, "limit": 100, "truncated": false, "generatedAt": "2026-07-30T21:48:21.000Z", "includedEditions": false, "excludedArchivedBooks": 0, "excludedNonBookProducts": 0, "catalogVisibility": { "archivedBooks": { "mode": "hidden_by_default", "includeParameter": "includeArchived", "hiddenMatchingBooks": 0, "note": "Archived books are hidden from catalog by default." }, "nonBookProducts": { "mode": "hidden_by_default", "includeParameter": "includeNonBookProducts", "hiddenMatchingProducts": 0, "note": "Reviewed non-book products are hidden from catalog by default." } } }, "customAttributeDefinitions": [], "books": [ { "bookKey": "book:the-long-road", "title": { "value": "The Long Road", "inferred": false }, "author": { "value": "A. Writer", "inferred": false }, "series": { "value": "Road Stories", "inferred": false }, "seriesPosition": { "value": 1, "inferred": false }, "publicationDate": { "value": "2026-02-03", "inferred": false }, "publicationYear": { "value": "2026", "inferred": false }, "color": { "value": "#496A81", "inferred": false }, "coauthor": { "value": null, "inferred": false }, "url": { "value": "https://example.com/the-long-road", "inferred": false }, "image": { "value": "https://example.com/the-long-road.jpg", "inferred": false }, "archived": false, "nonBook": false, "memberCount": 1 } ] } }, "booksAndEditions": { "summary": "Books with editions", "value": { "meta": { "totalBooks": 1, "returnedBooks": 1, "offset": 0, "limit": 100, "truncated": false, "generatedAt": "2026-07-30T21:48:21.000Z", "includedEditions": true, "excludedArchivedBooks": 0, "excludedNonBookProducts": 0, "catalogVisibility": { "archivedBooks": { "mode": "hidden_by_default", "includeParameter": "includeArchived", "hiddenMatchingBooks": 0, "note": "Archived books are hidden from catalog by default." }, "nonBookProducts": { "mode": "hidden_by_default", "includeParameter": "includeNonBookProducts", "hiddenMatchingProducts": 0, "note": "Reviewed non-book products are hidden from catalog by default." } } }, "customAttributeDefinitions": [], "books": [ { "bookKey": "book:the-long-road", "title": { "value": "The Long Road", "inferred": false }, "author": { "value": "A. Writer", "inferred": false }, "series": { "value": "Road Stories", "inferred": false }, "seriesPosition": { "value": 1, "inferred": false }, "publicationDate": { "value": "2026-02-03", "inferred": false }, "publicationYear": { "value": "2026", "inferred": false }, "color": { "value": "#496A81", "inferred": false }, "coauthor": { "value": null, "inferred": false }, "url": { "value": "https://example.com/the-long-road", "inferred": false }, "image": { "value": "https://example.com/the-long-road.jpg", "inferred": false }, "archived": false, "nonBook": false, "memberCount": 1, "editions": [ { "editionKey": "asin:B0EXAMPLE", "sourceTitle": "The Long Road", "format": { "value": "ebook", "inferred": false }, "distributor": { "value": "Amazon", "inferred": false }, "kenpc": { "value": 318, "inferred": false }, "language": { "value": "English", "inferred": false }, "translator": { "value": null, "inferred": false }, "editor": { "value": null, "inferred": false }, "illustrator": { "value": null, "inferred": false }, "url": { "value": "https://www.amazon.com/dp/B0EXAMPLE", "inferred": false }, "image": { "value": "https://example.com/the-long-road.jpg", "inferred": false }, "nonBook": false, "classification": null } ] } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "504": { "$ref": "#/components/responses/RequestTimeout" } } } }, "/api/v1/report": { "post": { "operationId": "runReport", "tags": [ "Reports" ], "summary": "Run a report", "description": "A report has four parts: a date range, attributes that group rows, metrics that measure each row, and optional filters that narrow the underlying data.\n\nMultiple values for one filter are combined with OR. Different filter keys are combined with AND.\n\nRelative ranges are resolved using the Book Report server calendar in UTC. Explicit start and end dates are inclusive; use them when a local-calendar boundary matters.\n\nRows are sorted descending by the first requested metric. When limit is omitted, REST returns every row. When supplied, limit is any positive integer and selects the top rows after sorting; there is no documented maximum.\n\nMoney metrics use the account currency unless currency overrides it. The account page-read royalty rate mode, KENPC fraction per estimated borrow, and Amazon link domain are also applied automatically.\n\nCatalog endpoints return descriptive metadata. Report endpoints return numeric facts aggregated by the requested attributes.", "requestBody": { "required": true, "description": "A JSON report request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportRequest" }, "examples": { "recentEarningsByBook": { "summary": "Recent earnings grouped by book", "value": { "range": "last_30_days", "attributes": [ "book" ], "metrics": [ "earnings", "units" ] } }, "explicitFilteredMonthlyReport": { "summary": "Explicit UTC dates, nested grouping, and filters", "value": { "start": "2026-01-01", "end": "2026-06-30", "attributes": [ "total", "book", "month" ], "metrics": [ "earnings", "sales", "pages_read" ], "filters": { "country": [ "US", "CA" ], "format": [ "ebook" ] }, "currency": "USD", "includeFilterKey": true, "limit": 1 } } } } } }, "responses": { "200": { "description": "Report result.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportResponse" }, "examples": { "earningsByBook": { "summary": "Simple book report", "value": { "meta": { "generatedAt": "2026-07-30T21:48:21.000Z", "start": "2026-07-01", "end": "2026-07-30", "currency": "USD", "pageReadRoyaltyRateMode": "previous_month", "customPageReadRoyaltyRateUsd": null, "kenpcFractionPerEstimatedBorrow": 0.75, "linkDomain": "www.amazon.com", "rowCount": 2, "sort": { "key": "earnings", "direction": "desc", "type": "metric" }, "generationMs": 42 }, "columns": [ { "key": "book", "kind": "attribute", "type": "string" }, { "key": "earnings", "kind": "metric", "type": "number", "currency": "USD" }, { "key": "units", "kind": "metric", "type": "number" } ], "rows": [ { "book": "The Long Road", "earnings": 421.52, "units": 103 }, { "book": "Another Book", "earnings": 209.14, "units": 52 } ] } }, "filteredMonthlyTopRows": { "summary": "Flat multi-attribute rows with stable keys and a row limit", "value": { "meta": { "generatedAt": "2026-07-30T21:48:21.000Z", "start": "2026-01-01", "end": "2026-06-30", "currency": "USD", "pageReadRoyaltyRateMode": "previous_month", "customPageReadRoyaltyRateUsd": null, "kenpcFractionPerEstimatedBorrow": 0.75, "linkDomain": "www.amazon.com", "rowCount": 18, "sort": { "key": "earnings", "direction": "desc", "type": "metric" }, "generationMs": 57 }, "columns": [ { "key": "total", "kind": "attribute", "type": "string" }, { "key": "total_key", "kind": "attribute", "type": "string" }, { "key": "book", "kind": "attribute", "type": "string" }, { "key": "book_key", "kind": "attribute", "type": "string" }, { "key": "month", "kind": "attribute", "type": "string" }, { "key": "month_key", "kind": "attribute", "type": "string" }, { "key": "earnings", "kind": "metric", "type": "number", "currency": "USD" }, { "key": "sales", "kind": "metric", "type": "number" }, { "key": "pages_read", "kind": "metric", "type": "number" } ], "rows": [ { "total": "Total", "total_key": "total", "book": "The Long Road", "book_key": "book:the-long-road", "month": "2026-06", "month_key": "2026-06", "earnings": 421.52, "sales": 103, "pages_read": 18420 } ], "rowWindow": { "totalRows": 18, "returnedRows": 1, "limit": 1, "truncated": true, "note": "Returned rows are the top rows after sorting by the first requested metric; additional rows were capped by the report limit." } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "504": { "$ref": "#/components/responses/RequestTimeout" } }, "x-bookreport-supported-filters": [ { "key": "book", "label": "Book", "type": "Book", "description": "The book title. Multiple editions of the same book, such as ebook, paperback, hardcover, audiobook, and wide-store editions, are grouped together under one title." }, { "key": "product", "label": "Product", "type": "Book", "description": "The distributor-specific product or edition row. Unlike Book, this does not collapse reviewed non-book items into one shared row." }, { "key": "series_number", "label": "Series #", "type": "Book", "description": "The book, displayed as Series Title #Position when series metadata is available; otherwise it falls back to the book title." }, { "key": "author", "label": "Author", "type": "Book", "description": "The primary author of the book involved in the transaction. When a book has multiple authors, this uses the first or primary author." }, { "key": "series", "label": "Series", "type": "Book", "description": "The series that the book is part of, when series metadata is available." }, { "key": "publication_year", "label": "Publication Year", "type": "Book", "description": "The year the book was published. For pre-orders, this is the year the pre-order period completed and the book became available." }, { "key": "language", "label": "Language", "type": "Book", "description": "The language associated with the book, when available." }, { "key": "book_id", "label": "Book ID", "type": "Book", "description": "The unique identifier for each book product or edition. Each edition and each distributor version can have a different ID." }, { "key": "co_author", "label": "Co-author", "type": "Book", "description": "Contributor names listed as co-authors in distributor metadata. Multiple names may be combined in one value." }, { "key": "translator", "label": "Translator", "type": "Book", "description": "Contributor names listed as translators in distributor metadata. Multiple names may be combined in one value." }, { "key": "illustrator", "label": "Illustrator", "type": "Book", "description": "Contributor names listed as illustrators in distributor metadata. Multiple names may be combined in one value." }, { "key": "editor", "label": "Editor", "type": "Book", "description": "Contributor names listed as editors in distributor metadata. Multiple names may be combined in one value." }, { "key": "marketplace", "label": "Marketplace", "type": "Transaction", "description": "The marketplace where the transaction took place, such as Amazon.com, Amazon.co.uk, Google Play Books, Apple Books, Smashwords, Barnes and Noble, or Kobo." }, { "key": "transaction_type", "label": "Transaction Type", "type": "Transaction", "description": "The transaction type as reported by the distributor. Each distributor defines its own transaction types." }, { "key": "format", "label": "Format", "type": "Transaction", "description": "The format of the book involved in the transaction, such as eBook, paperback, hardcover, or audiobook." }, { "key": "distributor", "label": "Distributor", "type": "Transaction", "description": "The distributor or publishing platform that put the book on sale, such as Kindle Direct Publishing, Draft2Digital, Google Play Books, Kobo Writing Life, or Barnes & Noble Press." }, { "key": "country", "label": "Country", "type": "Transaction", "description": "The country where the transaction took place. For KDP sales, countries are inferred from the Amazon marketplace; most other distributors provide the country directly." }, { "key": "data_owner", "label": "Data Owner", "type": "Transaction", "description": "The Book Report data-sharing owner associated with the transaction, when shared data is present." }, { "key": "royalty_percentage", "label": "Royalty Percentage", "type": "Transaction", "description": "The percentage of the sale price counted as royalties, where applicable." }, { "key": "offer_price", "label": "Offer Price", "type": "Transaction", "description": "The price at which the book was offered at the time of sale, converted into the selected currency and grouped into price ranges." } ] } } }, "components": { "securitySchemes": { "ApiKeyBearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Book Report API key", "description": "Send a Book Report API key as Authorization: Bearer YOUR_API_KEY." } }, "headers": { "ApiVersion": { "description": "Public API major version. Always 1 for /api/v1/*.", "schema": { "type": "string", "const": "1" } }, "BearerChallenge": { "description": "Bearer authentication challenge.", "schema": { "type": "string" } }, "AllowedMethods": { "description": "Comma-separated methods accepted by this endpoint.", "schema": { "type": "string" } }, "RetryAfter": { "description": "Seconds until the next account request is allowed.", "schema": { "type": "integer", "minimum": 1 } } }, "responses": { "BadRequest": { "description": "The request failed validation.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "The API key is missing or invalid.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" }, "WWW-Authenticate": { "$ref": "#/components/headers/BearerChallenge" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "The authenticated account cannot access the requested feature.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "MethodNotAllowed": { "description": "The HTTP method is not allowed for this endpoint.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" }, "Allow": { "$ref": "#/components/headers/AllowedMethods" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "The account exceeded 3,600 requests in the current clock hour.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InternalServerError": { "description": "An unexpected server error occurred.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RequestTimeout": { "description": "The request exceeded the server execution timeout.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "ReportRange": { "type": "string", "enum": [ "all_time", "current_day", "current_month", "current_year", "last_24_months", "last_30_days", "last_7_days", "last_90_days", "previous_day", "previous_month", "previous_year" ], "description": "Relative range resolved against the current Book Report server calendar in UTC." }, "ReportAttributeKey": { "description": "Built-in row-grouping key or an account custom:* key returned by /api/v1/report-fields.", "oneOf": [ { "type": "string", "enum": [ "total", "book", "product", "series_number", "author", "series", "publication_year", "language", "book_id", "co_author", "translator", "illustrator", "editor", "marketplace", "transaction_type", "format", "distributor", "country", "data_owner", "royalty_percentage", "offer_price", "campaign", "ad_group", "ad_profile", "attribution", "date", "month", "year" ], "title": "Built-in key" }, { "type": "string", "title": "Account custom attribute key", "pattern": "^custom:.+$" } ] }, "ReportOutputAttributeColumnKey": { "type": "string", "description": "Requested attribute key, or its *_key companion when includeFilterKey=true." }, "ReportFilterKey": { "description": "Built-in filter key or an account custom:* key returned by /api/v1/report-fields.", "oneOf": [ { "type": "string", "enum": [ "book", "product", "series_number", "author", "series", "publication_year", "language", "book_id", "co_author", "translator", "illustrator", "editor", "marketplace", "transaction_type", "format", "distributor", "country", "data_owner", "royalty_percentage", "offer_price" ], "title": "Built-in key" }, { "type": "string", "title": "Account custom attribute key", "pattern": "^custom:.+$" } ] }, "ReportMetricKey": { "type": "string", "enum": [ "earnings", "sales_royalties", "print_royalties", "ebook_royalties", "audio_royalties", "kdp_select_royalties", "pre_order_royalties", "sales", "print_sales", "ebook_sales", "audio_units", "borrows", "pages_read", "free_units", "paid_units", "units", "refunds", "pre_orders", "ad_spend", "net_earnings", "impressions", "clicks", "cpc", "cpm", "ctr" ], "description": "Numeric metric key. Money metrics identify their currency in the response column metadata. Ratio metrics use decimal ratios: 1 is 100%." }, "ReportRequest": { "type": "object", "description": "Choose exactly one date form: provide range, or provide both start and end. Do not combine range with start or end.", "required": [ "attributes", "metrics" ], "additionalProperties": false, "properties": { "range": { "$ref": "#/components/schemas/ReportRange" }, "start": { "type": "string", "format": "date", "description": "Inclusive UTC-calendar start date. Required with end when range is omitted." }, "end": { "type": "string", "format": "date", "description": "Inclusive UTC-calendar end date. Required with start when range is omitted." }, "attributes": { "type": "array", "minItems": 1, "uniqueItems": true, "description": "Ordered grouping hierarchy. The first attribute is the root column. Common values include total, book, series, format, distributor, marketplace, date, month, and year. Use /api/v1/report-fields for the complete account-available list, including custom:* values.", "items": { "type": "string" }, "x-bookreport-built-in-values": [ "total", "book", "product", "series_number", "author", "series", "publication_year", "language", "book_id", "co_author", "translator", "illustrator", "editor", "marketplace", "transaction_type", "format", "distributor", "country", "data_owner", "royalty_percentage", "offer_price", "campaign", "ad_group", "ad_profile", "attribution", "date", "month", "year" ] }, "metrics": { "type": "array", "minItems": 1, "uniqueItems": true, "description": "Numeric measures. Common values include earnings, sales, units, borrows, pages_read, and refunds. The first metric determines descending row order. Use /api/v1/report-fields for the complete account-available list.", "items": { "type": "string", "enum": [ "earnings", "sales_royalties", "print_royalties", "ebook_royalties", "audio_royalties", "kdp_select_royalties", "pre_order_royalties", "sales", "print_sales", "ebook_sales", "audio_units", "borrows", "pages_read", "free_units", "paid_units", "units", "refunds", "pre_orders", "ad_spend", "net_earnings", "impressions", "clicks", "cpc", "cpm", "ctr" ] }, "x-bookreport-built-in-values": [ "earnings", "sales_royalties", "print_royalties", "ebook_royalties", "audio_royalties", "kdp_select_royalties", "pre_order_royalties", "sales", "print_sales", "ebook_sales", "audio_units", "borrows", "pages_read", "free_units", "paid_units", "units", "refunds", "pre_orders", "ad_spend", "net_earnings", "impressions", "clicks", "cpc", "cpm", "ctr" ] }, "filters": { "type": "object", "description": "Map from a report filter key to one or more authoritative values. Values within a key are OR; keys are AND.", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string" } } }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Optional ISO-style three-letter uppercase currency override for money metrics." }, "includeFilterKey": { "type": "boolean", "default": false, "description": "When true, include stable *_key attribute columns where available. Useful when display labels are not stable identifiers." }, "limit": { "type": "integer", "minimum": 1, "description": "Optional top-row limit applied after sorting. Omit to return every REST report row. There is no documented maximum." } }, "x-bookreport-date-selection": { "exactlyOne": [ "range", "start+end" ] } }, "ReportFieldsResponse": { "type": "object", "required": [ "ranges", "attributes", "filters", "metrics" ], "additionalProperties": false, "properties": { "ranges": { "type": "array", "items": { "$ref": "#/components/schemas/ReportRange" } }, "attributes": { "type": "array", "items": { "$ref": "#/components/schemas/ReportField" } }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/ReportField" } }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/ReportMetricField" } } }, "example": { "ranges": [ "all_time", "current_day", "current_month", "current_year", "last_24_months", "last_30_days", "last_7_days", "last_90_days", "previous_day", "previous_month", "previous_year" ], "attributes": [ { "key": "total", "label": "Total", "type": "Report", "description": "One aggregate row across the requested date range and filters. It may be used alone or with other attributes; when combined, its output value is the literal root label \"Total\"." }, { "key": "book", "label": "Book", "type": "Book", "description": "The book title. Multiple editions of the same book, such as ebook, paperback, hardcover, audiobook, and wide-store editions, are grouped together under one title." }, { "key": "product", "label": "Product", "type": "Book", "description": "The distributor-specific product or edition row. Unlike Book, this does not collapse reviewed non-book items into one shared row." }, { "key": "series_number", "label": "Series #", "type": "Book", "description": "The book, displayed as Series Title #Position when series metadata is available; otherwise it falls back to the book title." }, { "key": "author", "label": "Author", "type": "Book", "description": "The primary author of the book involved in the transaction. When a book has multiple authors, this uses the first or primary author." }, { "key": "series", "label": "Series", "type": "Book", "description": "The series that the book is part of, when series metadata is available." }, { "key": "publication_year", "label": "Publication Year", "type": "Book", "description": "The year the book was published. For pre-orders, this is the year the pre-order period completed and the book became available." }, { "key": "language", "label": "Language", "type": "Book", "description": "The language associated with the book, when available." }, { "key": "book_id", "label": "Book ID", "type": "Book", "description": "The unique identifier for each book product or edition. Each edition and each distributor version can have a different ID." }, { "key": "co_author", "label": "Co-author", "type": "Book", "description": "Contributor names listed as co-authors in distributor metadata. Multiple names may be combined in one value." }, { "key": "translator", "label": "Translator", "type": "Book", "description": "Contributor names listed as translators in distributor metadata. Multiple names may be combined in one value." }, { "key": "illustrator", "label": "Illustrator", "type": "Book", "description": "Contributor names listed as illustrators in distributor metadata. Multiple names may be combined in one value." }, { "key": "editor", "label": "Editor", "type": "Book", "description": "Contributor names listed as editors in distributor metadata. Multiple names may be combined in one value." }, { "key": "marketplace", "label": "Marketplace", "type": "Transaction", "description": "The marketplace where the transaction took place, such as Amazon.com, Amazon.co.uk, Google Play Books, Apple Books, Smashwords, Barnes and Noble, or Kobo." }, { "key": "transaction_type", "label": "Transaction Type", "type": "Transaction", "description": "The transaction type as reported by the distributor. Each distributor defines its own transaction types." }, { "key": "format", "label": "Format", "type": "Transaction", "description": "The format of the book involved in the transaction, such as eBook, paperback, hardcover, or audiobook." }, { "key": "distributor", "label": "Distributor", "type": "Transaction", "description": "The distributor or publishing platform that put the book on sale, such as Kindle Direct Publishing, Draft2Digital, Google Play Books, Kobo Writing Life, or Barnes & Noble Press." }, { "key": "country", "label": "Country", "type": "Transaction", "description": "The country where the transaction took place. For KDP sales, countries are inferred from the Amazon marketplace; most other distributors provide the country directly." }, { "key": "data_owner", "label": "Data Owner", "type": "Transaction", "description": "The Book Report data-sharing owner associated with the transaction, when shared data is present." }, { "key": "royalty_percentage", "label": "Royalty Percentage", "type": "Transaction", "description": "The percentage of the sale price counted as royalties, where applicable." }, { "key": "offer_price", "label": "Offer Price", "type": "Transaction", "description": "The price at which the book was offered at the time of sale, converted into the selected currency and grouped into price ranges." }, { "key": "campaign", "label": "Campaign", "type": "Advertising", "description": "The campaign reported by the advertising provider." }, { "key": "ad_group", "label": "Ad Group", "type": "Advertising", "description": "The ad group or ad set reported by the advertising provider." }, { "key": "ad_profile", "label": "Ad Profile", "type": "Advertising", "description": "The account or profile reported by the advertising provider." }, { "key": "attribution", "label": "Attribution", "type": "Advertising", "description": "Breaks compatible metrics into attributed and organic parts." }, { "key": "date", "label": "Date", "type": "Date", "description": "The date the transaction took place." }, { "key": "month", "label": "Month", "type": "Date", "description": "The month the transaction took place." }, { "key": "year", "label": "Year", "type": "Date", "description": "The year the transaction took place." } ], "filters": [ { "key": "book", "label": "Book", "type": "Book", "description": "The book title. Multiple editions of the same book, such as ebook, paperback, hardcover, audiobook, and wide-store editions, are grouped together under one title." }, { "key": "product", "label": "Product", "type": "Book", "description": "The distributor-specific product or edition row. Unlike Book, this does not collapse reviewed non-book items into one shared row." }, { "key": "series_number", "label": "Series #", "type": "Book", "description": "The book, displayed as Series Title #Position when series metadata is available; otherwise it falls back to the book title." }, { "key": "author", "label": "Author", "type": "Book", "description": "The primary author of the book involved in the transaction. When a book has multiple authors, this uses the first or primary author." }, { "key": "series", "label": "Series", "type": "Book", "description": "The series that the book is part of, when series metadata is available." }, { "key": "publication_year", "label": "Publication Year", "type": "Book", "description": "The year the book was published. For pre-orders, this is the year the pre-order period completed and the book became available." }, { "key": "language", "label": "Language", "type": "Book", "description": "The language associated with the book, when available." }, { "key": "book_id", "label": "Book ID", "type": "Book", "description": "The unique identifier for each book product or edition. Each edition and each distributor version can have a different ID." }, { "key": "co_author", "label": "Co-author", "type": "Book", "description": "Contributor names listed as co-authors in distributor metadata. Multiple names may be combined in one value." }, { "key": "translator", "label": "Translator", "type": "Book", "description": "Contributor names listed as translators in distributor metadata. Multiple names may be combined in one value." }, { "key": "illustrator", "label": "Illustrator", "type": "Book", "description": "Contributor names listed as illustrators in distributor metadata. Multiple names may be combined in one value." }, { "key": "editor", "label": "Editor", "type": "Book", "description": "Contributor names listed as editors in distributor metadata. Multiple names may be combined in one value." }, { "key": "marketplace", "label": "Marketplace", "type": "Transaction", "description": "The marketplace where the transaction took place, such as Amazon.com, Amazon.co.uk, Google Play Books, Apple Books, Smashwords, Barnes and Noble, or Kobo." }, { "key": "transaction_type", "label": "Transaction Type", "type": "Transaction", "description": "The transaction type as reported by the distributor. Each distributor defines its own transaction types." }, { "key": "format", "label": "Format", "type": "Transaction", "description": "The format of the book involved in the transaction, such as eBook, paperback, hardcover, or audiobook." }, { "key": "distributor", "label": "Distributor", "type": "Transaction", "description": "The distributor or publishing platform that put the book on sale, such as Kindle Direct Publishing, Draft2Digital, Google Play Books, Kobo Writing Life, or Barnes & Noble Press." }, { "key": "country", "label": "Country", "type": "Transaction", "description": "The country where the transaction took place. For KDP sales, countries are inferred from the Amazon marketplace; most other distributors provide the country directly." }, { "key": "data_owner", "label": "Data Owner", "type": "Transaction", "description": "The Book Report data-sharing owner associated with the transaction, when shared data is present." }, { "key": "royalty_percentage", "label": "Royalty Percentage", "type": "Transaction", "description": "The percentage of the sale price counted as royalties, where applicable." }, { "key": "offer_price", "label": "Offer Price", "type": "Transaction", "description": "The price at which the book was offered at the time of sale, converted into the selected currency and grouped into price ranges." } ], "metrics": [ { "key": "earnings", "label": "Earnings", "isMoney": true, "type": "Revenue Metrics", "description": "Total earnings over the selected time period." }, { "key": "sales_royalties", "label": "Sales Royalties", "isMoney": true, "type": "Revenue Metrics", "description": "Earnings from paid sales across all formats, excluding pre-orders." }, { "key": "print_royalties", "label": "Print Royalties", "isMoney": true, "type": "Revenue Metrics", "description": "Earnings from books sold in print format, including paperback and hardcover books." }, { "key": "ebook_royalties", "label": "eBook Royalties", "isMoney": true, "type": "Revenue Metrics", "description": "Earnings from books sold in eBook format." }, { "key": "audio_royalties", "label": "Audio Royalties", "isMoney": true, "type": "Revenue Metrics", "description": "Earnings from audiobooks." }, { "key": "kdp_select_royalties", "label": "KDP Select Royalties", "isMoney": true, "type": "Revenue Metrics", "description": "Earnings from books borrowed or read through KDP Select programs such as Kindle Unlimited or the Kindle Owners Lending Library." }, { "key": "pre_order_royalties", "label": "Pre Order Royalties", "isMoney": true, "type": "Revenue Metrics", "description": "Earnings from pre-orders." }, { "key": "sales", "label": "Sales", "isMoney": false, "type": "Quantity Metrics", "description": "The number of paid sales in all formats. This is gross units sold, not net of refunds, and does not include pre-orders." }, { "key": "print_sales", "label": "Print Sales", "isMoney": false, "type": "Quantity Metrics", "description": "The number of paid sales of print books, including paperback and hardcover books." }, { "key": "ebook_sales", "label": "eBook Sales", "isMoney": false, "type": "Quantity Metrics", "description": "The number of paid sales of eBooks." }, { "key": "audio_units", "label": "Audio Units", "isMoney": false, "type": "Quantity Metrics", "description": "The number of audiobooks sold or borrowed." }, { "key": "borrows", "label": "Borrows", "isMoney": false, "type": "Quantity Metrics", "description": "The number of borrows of eBooks. KDP borrows after July 2015 are estimated from pages read, KENPC, and the account read-through setting." }, { "key": "pages_read", "label": "Pages Read", "isMoney": false, "type": "Quantity Metrics", "description": "The number of pages read through Kindle Unlimited." }, { "key": "free_units", "label": "Free Units", "isMoney": false, "type": "Quantity Metrics", "description": "The number of units given away for free, including free promotions, giveaways, and zero-price transactions." }, { "key": "paid_units", "label": "Paid Units", "isMoney": false, "type": "Quantity Metrics", "description": "The number of paid units plus borrows, combining print sales, eBook sales, pre-orders, and borrows." }, { "key": "units", "label": "Units", "isMoney": false, "type": "Quantity Metrics", "description": "The total number of units distributed, including paid sales, borrows, free units, and pre-orders." }, { "key": "refunds", "label": "Refunds", "isMoney": false, "type": "Quantity Metrics", "description": "The number of units refunded or returned." }, { "key": "pre_orders", "label": "Pre Orders", "isMoney": false, "type": "Quantity Metrics", "description": "The number of pre-orders placed. Pre-orders appear on the day they are placed, not the delivery date." }, { "key": "ad_spend", "label": "Ad Spend", "isMoney": true, "type": "Advertising Metrics", "description": "The amount spent on advertising." }, { "key": "net_earnings", "label": "Net Earnings", "isMoney": true, "type": "Advertising Metrics", "description": "Total earnings minus ad spend." }, { "key": "impressions", "label": "Impressions", "isMoney": false, "type": "Advertising Metrics", "description": "The number of advertising impressions." }, { "key": "clicks", "label": "Clicks", "isMoney": false, "type": "Advertising Metrics", "description": "The number of advertising clicks." }, { "key": "cpc", "label": "CPC", "isMoney": true, "type": "Advertising Metrics", "description": "The average ad spend per click." }, { "key": "cpm", "label": "CPM", "isMoney": true, "type": "Advertising Metrics", "description": "The average ad spend per thousand impressions." }, { "key": "ctr", "label": "CTR", "isMoney": false, "type": "Advertising Metrics", "description": "The share of ad impressions that became clicks, expressed as a decimal ratio where 1 is 100%." } ] } }, "ReportField": { "type": "object", "required": [ "key", "label", "type", "description" ], "additionalProperties": false, "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "description": { "type": "string" } } }, "ReportMetricField": { "type": "object", "required": [ "key", "label", "type", "description", "isMoney" ], "additionalProperties": false, "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string" }, "description": { "type": "string" }, "isMoney": { "type": "boolean" } } }, "FilterValuesResponse": { "oneOf": [ { "type": "object", "required": [ "filterValueUsage", "filters", "totalFilters" ], "additionalProperties": false, "properties": { "filterValueUsage": { "type": "object", "required": [ "reportFilterField", "displayField", "note" ], "additionalProperties": false, "properties": { "reportFilterField": { "const": "value" }, "displayField": { "const": "label" }, "note": { "type": "string" } } }, "filters": { "type": "array", "items": { "type": "object", "required": [ "key", "label", "type", "optionCount" ], "additionalProperties": false, "properties": { "key": { "$ref": "#/components/schemas/ReportFilterKey" }, "label": { "type": "string" }, "type": { "type": "string" }, "optionCount": { "type": "integer", "minimum": 0 } } } }, "totalFilters": { "type": "integer", "minimum": 0 } } }, { "type": "object", "required": [ "filterValueUsage", "filter", "values", "totalValues", "matchedValues", "returnedValues", "cursor", "nextCursor" ], "additionalProperties": false, "properties": { "filterValueUsage": { "type": "object", "required": [ "reportFilterField", "displayField", "note" ], "additionalProperties": false, "properties": { "reportFilterField": { "const": "value" }, "displayField": { "const": "label" }, "note": { "type": "string" } } }, "filter": { "type": "object", "required": [ "key", "label", "type", "optionCount" ], "additionalProperties": false, "properties": { "key": { "$ref": "#/components/schemas/ReportFilterKey" }, "label": { "type": "string" }, "type": { "type": "string" }, "optionCount": { "type": "integer", "minimum": 0 } } }, "values": { "type": "array", "items": { "type": "object", "required": [ "label", "value" ], "additionalProperties": false, "properties": { "label": { "type": "string" }, "value": { "type": "string" } } } }, "totalValues": { "type": "integer", "minimum": 0 }, "matchedValues": { "type": "integer", "minimum": 0 }, "returnedValues": { "type": "integer", "minimum": 0 }, "cursor": { "type": "integer", "minimum": 0 }, "nextCursor": { "type": [ "integer", "null" ], "minimum": 0 } } } ] }, "AccountContextResponse": { "type": "object", "required": [ "reportSettings", "connectedSources", "capabilities" ], "additionalProperties": false, "properties": { "reportSettings": { "type": "object", "required": [ "currency", "pageReadRoyaltyRateMode", "customPageReadRoyaltyRateUsd", "kenpcFractionPerEstimatedBorrow", "linkDomain" ], "additionalProperties": false, "properties": { "currency": { "type": "string", "description": "Default account currency used for money metrics unless overridden." }, "pageReadRoyaltyRateMode": { "type": "string", "enum": [ "previous_month", "pessimistic", "custom" ], "description": "Which rate Book Report uses to estimate Kindle Unlimited page-read royalties while official marketplace rates are unavailable. previous_month reuses the last known marketplace rates; pessimistic assumes a decline based on recent history; custom uses customPageReadRoyaltyRateUsd." }, "customPageReadRoyaltyRateUsd": { "type": [ "number", "null" ], "description": "Custom royalty amount in US dollars per KENP read. Used only when pageReadRoyaltyRateMode is custom; otherwise null. Report money metrics convert this amount into the requested report currency." }, "kenpcFractionPerEstimatedBorrow": { "type": "number", "minimum": 0, "description": "Decimal fraction of a book's KENPC treated as one estimated Kindle Unlimited borrow. 1 means 100% of KENPC; 0.75 means page reads equal to 75% of KENPC count as one estimated borrow. This is unrelated to series read-through." }, "linkDomain": { "type": "string", "description": "Amazon domain used when Book Report produces linked report metadata." } } }, "connectedSources": { "type": "array", "items": { "type": "object", "required": [ "name", "domain", "connectionMode", "category", "connected", "reconnectWarning" ], "additionalProperties": false, "properties": { "name": { "type": "string" }, "domain": { "type": "string" }, "connectionMode": { "type": "string" }, "category": { "type": "string" }, "connected": { "const": true }, "reconnectWarning": { "type": [ "string", "null" ] } } } }, "capabilities": { "type": "object", "required": [ "readOnly", "reportDefaultsAppliedToMcpReports", "reportDefaultsAppliedToApiReports", "explicitReportCurrencyOverride", "includesPii" ], "additionalProperties": false, "properties": { "readOnly": { "const": true }, "reportDefaultsAppliedToMcpReports": { "const": true }, "reportDefaultsAppliedToApiReports": { "const": true }, "explicitReportCurrencyOverride": { "const": true }, "includesPii": { "const": false } } } } }, "CatalogStringAttribute": { "type": "object", "required": [ "value", "inferred" ], "additionalProperties": false, "properties": { "value": { "type": [ "string", "null" ] }, "inferred": { "type": "boolean", "description": "True when Book Report supplied the value from catalog defaults rather than direct metadata for this Book or Edition." } } }, "CatalogNumberAttribute": { "type": "object", "required": [ "value", "inferred" ], "additionalProperties": false, "properties": { "value": { "type": [ "number", "null" ] }, "inferred": { "type": "boolean", "description": "True when Book Report supplied the value from catalog defaults rather than direct metadata for this Book or Edition." } } }, "CatalogCustomAttributeValue": { "type": "object", "required": [ "customAttributeId", "name", "value", "inferred" ], "additionalProperties": false, "properties": { "customAttributeId": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "inferred": { "type": "boolean" } } }, "CatalogEdition": { "type": "object", "required": [ "editionKey", "sourceTitle", "format", "distributor", "kenpc", "language", "translator", "editor", "illustrator", "url", "image", "nonBook", "classification" ], "additionalProperties": false, "properties": { "editionKey": { "type": "string", "description": "Stable Book Report identifier for this distributor/source edition." }, "sourceTitle": { "type": [ "string", "null" ] }, "format": { "$ref": "#/components/schemas/CatalogStringAttribute" }, "distributor": { "$ref": "#/components/schemas/CatalogStringAttribute" }, "kenpc": { "$ref": "#/components/schemas/CatalogNumberAttribute" }, "language": { "$ref": "#/components/schemas/CatalogStringAttribute" }, "translator": { "$ref": "#/components/schemas/CatalogStringAttribute" }, "editor": { "$ref": "#/components/schemas/CatalogStringAttribute" }, "illustrator": { "$ref": "#/components/schemas/CatalogStringAttribute" }, "url": { "$ref": "#/components/schemas/CatalogStringAttribute" }, "image": { "$ref": "#/components/schemas/CatalogStringAttribute" }, "nonBook": { "type": "boolean" }, "classification": { "type": [ "string", "null" ], "enum": [ "book", "non_book", null ] }, "customAttributes": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogCustomAttributeValue" } } } }, "CatalogBook": { "type": "object", "required": [ "bookKey", "title", "author", "series", "seriesPosition", "publicationDate", "publicationYear", "color", "coauthor", "url", "image", "archived", "nonBook", "memberCount" ], "additionalProperties": false, "properties": { "bookKey": { "type": "string", "description": "Stable identifier for the logical Book grouping one or more Editions." }, "title": { "$ref": "#/components/schemas/CatalogStringAttribute" }, "author": { "$ref": "#/components/schemas/CatalogStringAttribute" }, "series": { "$ref": "#/components/schemas/CatalogStringAttribute" }, "seriesPosition": { "$ref": "#/components/schemas/CatalogNumberAttribute" }, "publicationDate": { "$ref": "#/components/schemas/CatalogStringAttribute" }, "publicationYear": { "$ref": "#/components/schemas/CatalogStringAttribute" }, "color": { "$ref": "#/components/schemas/CatalogStringAttribute" }, "coauthor": { "$ref": "#/components/schemas/CatalogStringAttribute" }, "url": { "$ref": "#/components/schemas/CatalogStringAttribute" }, "image": { "$ref": "#/components/schemas/CatalogStringAttribute" }, "archived": { "type": "boolean" }, "nonBook": { "type": "boolean" }, "memberCount": { "type": "integer", "minimum": 0, "description": "Number of Editions grouped into this Book." }, "customAttributes": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogCustomAttributeValue" } }, "editions": { "type": "array", "description": "Present only when includeEditions=true.", "items": { "$ref": "#/components/schemas/CatalogEdition" } } } }, "CatalogResponse": { "type": "object", "required": [ "meta", "customAttributeDefinitions", "books" ], "additionalProperties": false, "properties": { "meta": { "type": "object", "required": [ "totalBooks", "returnedBooks", "offset", "limit", "truncated", "generatedAt", "includedEditions", "excludedArchivedBooks", "excludedNonBookProducts", "catalogVisibility" ], "additionalProperties": false, "properties": { "totalBooks": { "type": "integer", "minimum": 0 }, "returnedBooks": { "type": "integer", "minimum": 0 }, "offset": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 500 }, "truncated": { "type": "boolean" }, "generatedAt": { "type": "string", "format": "date-time" }, "includedEditions": { "type": "boolean" }, "excludedArchivedBooks": { "type": "integer", "minimum": 0 }, "excludedNonBookProducts": { "type": "integer", "minimum": 0 }, "catalogVisibility": { "type": "object", "required": [ "archivedBooks", "nonBookProducts" ], "additionalProperties": false, "properties": { "archivedBooks": { "type": "object", "required": [ "mode", "includeParameter", "note" ], "additionalProperties": true, "properties": { "mode": { "type": "string", "enum": [ "included", "hidden_by_default" ] }, "includeParameter": { "type": "string" }, "hiddenMatchingBooks": { "type": "integer", "minimum": 0 }, "hiddenMatchingProducts": { "type": "integer", "minimum": 0 }, "note": { "type": "string" } } }, "nonBookProducts": { "type": "object", "required": [ "mode", "includeParameter", "note" ], "additionalProperties": true, "properties": { "mode": { "type": "string", "enum": [ "included", "hidden_by_default" ] }, "includeParameter": { "type": "string" }, "hiddenMatchingBooks": { "type": "integer", "minimum": 0 }, "hiddenMatchingProducts": { "type": "integer", "minimum": 0 }, "note": { "type": "string" } } } } } } }, "customAttributeDefinitions": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "describes" ], "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "describes": { "type": "string", "enum": [ "book", "edition" ] } } } }, "books": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogBook" } } } }, "ReportResponse": { "type": "object", "required": [ "meta", "columns", "rows" ], "additionalProperties": false, "properties": { "meta": { "type": "object", "required": [ "generatedAt", "start", "end", "currency", "rowCount", "pageReadRoyaltyRateMode", "customPageReadRoyaltyRateUsd", "kenpcFractionPerEstimatedBorrow", "linkDomain", "sort", "generationMs" ], "additionalProperties": false, "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "start": { "type": "string", "format": "date" }, "end": { "type": "string", "format": "date" }, "currency": { "type": "string" }, "rowCount": { "type": "integer", "minimum": 0, "description": "Total rows generated before the optional request limit is applied." }, "pageReadRoyaltyRateMode": { "type": "string", "enum": [ "previous_month", "pessimistic", "custom" ], "description": "Page-read royalty rate mode applied to the report while official marketplace rates were unavailable." }, "customPageReadRoyaltyRateUsd": { "type": [ "number", "null" ], "description": "Custom royalty amount in US dollars per KENP read when pageReadRoyaltyRateMode is custom; otherwise null. Report money metrics convert this amount into the requested report currency." }, "kenpcFractionPerEstimatedBorrow": { "type": "number", "minimum": 0, "description": "Decimal fraction of a book's KENPC treated as one estimated Kindle Unlimited borrow. 1 means 100% of KENPC; 0.75 means page reads equal to 75% of KENPC count as one estimated borrow. This is unrelated to series read-through." }, "linkDomain": { "type": "string" }, "sort": { "type": "object", "required": [ "key", "direction", "type" ], "additionalProperties": false, "properties": { "key": { "$ref": "#/components/schemas/ReportMetricKey" }, "direction": { "const": "desc" }, "type": { "const": "metric" } } }, "generationMs": { "type": "number" } } }, "columns": { "type": "array", "description": "Ordered column metadata. Use kind and type rather than guessing from a row value.", "items": { "oneOf": [ { "type": "object", "required": [ "key", "kind", "type" ], "additionalProperties": false, "properties": { "key": { "type": "string", "description": "Requested attribute key, or its *_key companion when includeFilterKey=true." }, "kind": { "const": "attribute" }, "type": { "const": "string" } } }, { "type": "object", "required": [ "key", "kind", "type" ], "additionalProperties": false, "properties": { "key": { "$ref": "#/components/schemas/ReportMetricKey" }, "kind": { "const": "metric" }, "type": { "const": "number" }, "currency": { "type": "string", "description": "Present for money metrics." } } } ] } }, "rows": { "type": "array", "items": { "type": "object", "description": "Keys correspond to columns[].key. Missing report facts are normally represented as numeric zero.", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "null" } ] } } }, "rowWindow": { "type": "object", "description": "Present only when the request includes limit.", "required": [ "totalRows", "returnedRows", "limit", "truncated", "note" ], "additionalProperties": false, "properties": { "totalRows": { "type": "integer", "minimum": 0 }, "returnedRows": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1 }, "truncated": { "type": "boolean" }, "note": { "type": "string" } } } } }, "ErrorIssue": { "type": "object", "required": [ "path", "code", "message" ], "additionalProperties": false, "properties": { "path": { "type": "string", "description": "JSON field or request parameter associated with the issue." }, "code": { "type": "string", "description": "Stable machine-readable issue category, such as required, invalid_type, invalid_value, or unknown_field." }, "message": { "type": "string" } } }, "ErrorResponse": { "type": "object", "required": [ "ok", "code", "message" ], "additionalProperties": false, "properties": { "ok": { "const": false }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "feature_disabled", "method_not_allowed", "rate_limited", "external_access_error", "request_timeout", "internal_error" ] }, "message": { "type": "string" }, "issues": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ErrorIssue" } }, "featureFlag": { "type": "string" } }, "example": { "ok": false, "code": "invalid_request", "message": "Report request validation failed.", "issues": [ { "path": "metrics", "code": "invalid_value", "message": "Unknown report metric \"revenue\"." } ] } } } }, "x-generated-by": "server/handlers/externalAccess/openApiSpec.ts" }