{ "openapi": "3.1.0", "info": { "title": "Book Report API", "version": "1.0.0", "summary": "Use Book Report to discover account context and vocabulary, run numeric reports, read resolved Book and Edition metadata, and make previewable, auditable changes to authorized catalogs.", "description": "Use Book Report to discover account context and vocabulary, run numeric reports, read resolved Book and Edition metadata, and make previewable, auditable changes to authorized catalogs.\n\nBook Report has two complementary data surfaces. Reports return numeric facts such as sales and earnings; catalog discovery returns descriptive Book and Edition metadata plus stable catalog keys. Discover report fields and filter values before constructing an unfamiliar report. Request Editions explicitly when work depends on Edition-level metadata.\n\nA Report Request has four parts: a date range, attributes that group rows, metrics that measure each row, and optional filters that narrow the underlying data. Multiple values for one filter are OR; different filter keys are AND. Relative ranges use the Book Report server calendar in UTC. Explicit start and end dates are inclusive. The total attribute may be used alone or with other attributes and produces the literal root label Total. When account defaults matter, read GET /api/v1/account-context first.\n\nReport Execution returns aggregated numeric facts. Catalog discovery returns descriptive Book and Edition metadata, stable catalog keys, catalog-management state, custom definitions, and direct custom values. Only language, KENPC, translator, editor, and illustrator may be inferred from peer Editions in the same Book. Format and distributor are never inferred. Custom values are direct and never inferred.\n\nBook Report imports activity for Editions—the source-specific products readers buy—and uses the catalog to organize those facts into Books and report attributes. Catalog edits do not change imported sales, earnings, or other source facts. Once committed, they refresh reports and can change how those facts are labelled, grouped, filtered, and attributed in Today, Historical, API, and MCP reports.\n\nCatalog editing terms: the Actor is the authenticated account or connection making the request; the Catalog Owner is the account whose catalog may change; an Editable Catalog is a Catalog Owner’s catalog the Actor is currently allowed to manage.\n\nStaging changes only a draft. Each staging call changes the revision and invalidates any earlier preview. Preview resolves the complete ordered diff without changing the saved Catalog. Commit is the only destructive operation and requires the latest preview token after explicit confirmation. A bad draft may be abandoned safely by creating a fresh session.\n\nFor every Edition action, copy the exact editionKey and distributor.value from the same accountId-targeted Catalog response. Use bookKey and customAttributeId exactly as returned there. Unknown Book or Edition identities are rejected; read the targeted Catalog again instead of guessing. Actions the Actor is not authorized to perform are rejected.\n\nThese operations read data already imported into Book Report. They do not initiate or refresh distributor imports.\n\nBook Report data can support business analysis, but results are not financial, legal, tax, or accounting advice. Book Report enforces catalog authorization when each operation runs.\n\nCatalog editing workflow:\n\n1. List Editable Catalogs with GET /api/v1/editable-catalogs, then select the returned accountId for the intended Catalog Owner.\n2. Read that exact targeted Catalog with GET /api/v1/catalog; include Editions before using Edition identities.\n3. Create a Catalog Edit Session with the same explicit accountId using POST /api/v1/catalog-edit-sessions.\n4. Stage every intended Authorized Action with POST /api/v1/catalog-edit-sessions/:sessionId/actions.\n5. Preview the canonical changes with POST /api/v1/catalog-edit-sessions/:sessionId/preview.\n6. Show the complete preview to the user.\n7. Commit only the latest confirmed preview token with POST /api/v1/catalog-edit-sessions/:sessionId/commit.\n8. If the Catalog changed or the preview became stale, read the Catalog again, rebuild or re-preview the draft, and ask for confirmation again.\n9. If a commit times out or fails ambiguously, inspect the session with GET /api/v1/catalog-edit-sessions/:sessionId before retrying. If it is committed, stop. If it is still a draft, preview again as needed and obtain fresh confirmation before committing.\n10. Page edit history with GET /api/v1/catalog-edit-sessions and an undo draft from POST /api/v1/catalog-edit-sessions/:sessionId/undo to reverse committed changes. Undo is non-destructive until its preview is confirmed and committed.\n\nAuthenticate with a Book Report API key as a Bearer token. Send a Book Report API key as Authorization: Bearer YOUR_API_KEY. Management operations require an API key with management access.\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/* operations support public browser CORS, including Authorization and OPTIONS preflight. A browser may call the API when a user intentionally supplies a key; never embed a reusable key in public source.\n\nAll documented operations live under /api/v1, use JSON results, expose X-Api-Version: 1, and return sanitized ErrorResponse envelopes for HTTP failures.\n\nHTTP failures use the shared sanitized ErrorResponse model for 400, 401, 403, 405, 409, 429, 500, 504 responses." }, "servers": [ { "url": "https://app.getbookreport.com", "description": "Production" } ], "security": [ { "ApiKeyBearerAuth": [] } ], "tags": [ { "name": "Reports", "description": "Numeric report facts and Report Execution." }, { "name": "Discovery", "description": "Account-available report vocabulary and filter values." }, { "name": "Account", "description": "Safe report defaults and connected-source context." }, { "name": "Catalog", "description": "Resolved descriptive Book and Edition metadata." }, { "name": "Catalog editing", "description": "Previewable, auditable Catalog Edit Sessions and Authorized Actions." }, { "name": "Ad destinations", "description": "Current Book or Edition links and effective attributes for imported Ad Destinations." } ], "paths": { "/api/v1/report-fields": { "get": { "operationId": "listReportFields", "tags": [ "Discovery" ], "summary": "Discover account-available report fields", "description": "Use this to discover the authenticated account’s valid ranges, attributes, filters, metrics, custom fields, and feature-dependent fields before constructing an unfamiliar Report Request. It does not return currencies. Every returned attribute and metric may be combined in one Report Execution; an absent field is unavailable to this account.", "responses": { "200": { "description": "The account-available report vocabulary and relative date ranges.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportFieldsResponse" }, "examples": { "availableFields": { "summary": "All built-in fields at contract-generation time", "value": { "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": "edition", "label": "Edition", "type": "Edition", "description": "A specific distributor Edition of a Book, such as its KDP eBook or ACX audiobook. Labels begin with the Book title and add useful distributor or format details. A provider ID is included only when those details do not distinguish the Book's Editions." }, { "key": "product", "label": "Product", "type": "Book", "description": "The catalog book grouping used by Book, except reviewed non-book BookFunnel products remain separate instead of being combined into one Non-Book Products row. Use Book ID for distributor-specific edition or product identifiers." }, { "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": "Edition", "description": "The language associated with the book, when available." }, { "key": "book_id", "label": "Book ID", "type": "Edition", "description": "The raw identifier reported by the distributor for an Edition. Unlike Edition, this shows the ID without the Book title or a distributor and format label." }, { "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": "Edition", "description": "Contributor names listed as translators in distributor metadata. Multiple names may be combined in one value." }, { "key": "illustrator", "label": "Illustrator", "type": "Edition", "description": "Contributor names listed as illustrators in distributor metadata. Multiple names may be combined in one value." }, { "key": "editor", "label": "Editor", "type": "Edition", "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": "Edition", "description": "The format of the book involved in the transaction, such as eBook, paperback, hardcover, or audiobook." }, { "key": "distributor", "label": "Distributor", "type": "Edition", "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": "ad_platform", "label": "Ad Platform", "type": "Advertising", "description": "The advertising platform that reported the activity, such as Amazon or Meta." }, { "key": "campaign", "label": "Campaign", "type": "Advertising", "description": "The campaign reported by the advertising provider." }, { "key": "ad", "label": "Ad", "type": "Advertising", "description": "The ad 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": "edition", "label": "Edition", "type": "Edition", "description": "A specific distributor Edition of a Book, such as its KDP eBook or ACX audiobook. Labels begin with the Book title and add useful distributor or format details. A provider ID is included only when those details do not distinguish the Book's Editions." }, { "key": "product", "label": "Product", "type": "Book", "description": "The catalog book grouping used by Book, except reviewed non-book BookFunnel products remain separate instead of being combined into one Non-Book Products row. Use Book ID for distributor-specific edition or product identifiers." }, { "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": "Edition", "description": "The language associated with the book, when available." }, { "key": "book_id", "label": "Book ID", "type": "Edition", "description": "The raw identifier reported by the distributor for an Edition. Unlike Edition, this shows the ID without the Book title or a distributor and format label." }, { "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": "Edition", "description": "Contributor names listed as translators in distributor metadata. Multiple names may be combined in one value." }, { "key": "illustrator", "label": "Illustrator", "type": "Edition", "description": "Contributor names listed as illustrators in distributor metadata. Multiple names may be combined in one value." }, { "key": "editor", "label": "Editor", "type": "Edition", "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": "Edition", "description": "The format of the book involved in the transaction, such as eBook, paperback, hardcover, or audiobook." }, { "key": "distributor", "label": "Distributor", "type": "Edition", "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": "earnings_per_sale", "label": "Earnings per Sale", "isMoney": true, "type": "Calculated Metrics", "description": "Total earnings divided by paid sales. Free units, borrows, and pre-orders are excluded from the sales count." }, { "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": "amazon_ad_spend", "label": "Amazon Ad Spend", "isMoney": true, "type": "Advertising Metrics", "description": "The amount spent on Amazon advertising." }, { "key": "facebook_ad_spend", "label": "Facebook Ad Spend", "isMoney": true, "type": "Advertising Metrics", "description": "The amount spent on Facebook 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%." } ] } } } } } }, "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 the account’s report-compatible filters. Call with a built-in filter key, built-in filter label, or custom:* key to page and search its values. Pass values[].value—not the display label—to the report operation (POST /api/v1/report).", "parameters": [ { "name": "filter", "in": "query", "required": false, "description": "Built-in filter key or label, or an account custom:* key. Omit to list filters.", "schema": { "type": "string", "minLength": 1, "description": "Built-in filter key or label, or an account custom:* key. Omit to list filters." } }, { "name": "query", "in": "query", "required": false, "description": "Optional case-insensitive search across labels and values for the selected filter.", "schema": { "type": "string", "description": "Optional case-insensitive search across labels and values for the selected filter." } }, { "name": "limit", "in": "query", "required": false, "description": "Values per page. Defaults to 50; maximum 100.", "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100, "description": "Values per page. Defaults to 50; maximum 100." } }, { "name": "cursor", "in": "query", "required": false, "description": "Zero-based cursor returned by a previous call. Defaults to 0.", "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Zero-based cursor returned by a previous call. Defaults to 0." } } ], "responses": { "200": { "description": "Available report filters or one paged set of values, plus the single shared filter-value usage object.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterValuesResponse" }, "examples": { "filters": { "summary": "Available filters with correct registry types", "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": "Transaction", "optionCount": 2 }, { "key": "format", "label": "Format", "type": "Transaction", "optionCount": 2 } ], "totalFilters": 2 } }, "countryValues": { "summary": "Country filter values", "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": "Transaction", "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": "edition", "label": "Edition", "type": "Edition", "description": "A specific distributor Edition of a Book, such as its KDP eBook or ACX audiobook. Labels begin with the Book title and add useful distributor or format details. A provider ID is included only when those details do not distinguish the Book's Editions." }, { "key": "product", "label": "Product", "type": "Book", "description": "The catalog book grouping used by Book, except reviewed non-book BookFunnel products remain separate instead of being combined into one Non-Book Products row. Use Book ID for distributor-specific edition or product identifiers." }, { "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": "Edition", "description": "The language associated with the book, when available." }, { "key": "book_id", "label": "Book ID", "type": "Edition", "description": "The raw identifier reported by the distributor for an Edition. Unlike Edition, this shows the ID without the Book title or a distributor and format label." }, { "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": "Edition", "description": "Contributor names listed as translators in distributor metadata. Multiple names may be combined in one value." }, { "key": "illustrator", "label": "Illustrator", "type": "Edition", "description": "Contributor names listed as illustrators in distributor metadata. Multiple names may be combined in one value." }, { "key": "editor", "label": "Editor", "type": "Edition", "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": "Edition", "description": "The format of the book involved in the transaction, such as eBook, paperback, hardcover, or audiobook." }, { "key": "distributor", "label": "Distributor", "type": "Edition", "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": "Use this when account defaults matter to a Report Request or its explanation. It returns safe report settings, connected-source context, and external-access capabilities. Page-read royalty settings control temporary Kindle Unlimited royalty estimates; the KENPC fraction per estimated borrow controls borrow estimation and is unrelated to series read-through. It never returns email addresses, account IDs, API keys, OAuth IDs, cookies, tokens, or raw third-party account identifiers.", "responses": { "200": { "description": "Safe report defaults, connected-source summaries, and capability flags for the authenticated account.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountContextRest" }, "examples": { "kdpContext": { "summary": "KDP-connected account context", "value": { "reportSettings": { "currency": "USD", "pageReadRoyaltyRateMode": "previous_month", "customPageReadRoyaltyRateUsd": null, "kenpcFractionPerEstimatedBorrow": 0.75, "linkDomain": "www.amazon.com" }, "connectedSources": [ { "name": "Kindle Direct Publishing", "domain": ".amazon.com", "connectionMode": "extension", "category": "retailer", "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 Book and Edition metadata", "description": "Returns the resolved Book and Edition model used by catalog editing. Book-wide metadata lives on Books; source-specific format, distributor, language, KENPC, and contributor metadata lives on Editions. Only language, KENPC, translator, editor, and illustrator may be inferred from peer Editions in the same Book. Format and distributor are never inferred. Custom definitions and direct custom values are included, and custom values are never inferred.\n\nOmit accountId to read the normal combined catalog visible to the Actor. Supplying an accountId returned by GET /api/v1/editable-catalogs selects one Editable Catalog for management. Public Account IDs are canonical uppercase. Team Access never exposes the target argument.\n\nSearch fields combine with AND at the logical-Book level; an Edition filter matches a Book when any Edition matches. When Editions are included, every Edition for each matching Book is returned. Archived Books and reviewed non-book products are hidden by default. Catalog keys identify catalog objects and are not guaranteed report filter keys; use GET /api/v1/report-filter-values for authoritative report values. Catalog discovery returns descriptive metadata; POST /api/v1/report returns numeric facts.", "parameters": [ { "name": "accountId", "in": "query", "required": false, "description": "Optional Catalog Owner Public Account ID. Supplying it selects an Editable Catalog and requires data:manage.", "schema": { "type": "string", "pattern": "^BR-[A-Z0-9]{3}-[A-Z0-9]{3}$", "description": "Optional Catalog Owner Public Account ID. Supplying it selects an Editable Catalog and requires data:manage." } }, { "name": "query", "in": "query", "required": false, "description": "Case-insensitive search across Book and Edition identifiers and metadata.", "schema": { "type": "string", "description": "Case-insensitive search across Book and Edition identifiers and metadata." } }, { "name": "author", "in": "query", "required": false, "description": "Case-insensitive author or contributor search.", "schema": { "type": "string", "description": "Case-insensitive author or contributor search." } }, { "name": "series", "in": "query", "required": false, "description": "Case-insensitive series search.", "schema": { "type": "string", "description": "Case-insensitive series search." } }, { "name": "format", "in": "query", "required": false, "description": "Case-insensitive Edition format search.", "schema": { "type": "string", "description": "Case-insensitive Edition format search." } }, { "name": "distributor", "in": "query", "required": false, "description": "Case-insensitive Edition distributor search.", "schema": { "type": "string", "description": "Case-insensitive Edition distributor search." } }, { "name": "includeEditions", "in": "query", "required": false, "description": "Include Edition-level metadata under every returned Book.", "schema": { "default": false, "type": "boolean", "description": "Include Edition-level metadata under every returned Book." } }, { "name": "includeArchived", "in": "query", "required": false, "description": "Include archived Books hidden by default.", "schema": { "default": false, "type": "boolean", "description": "Include archived Books hidden by default." } }, { "name": "includeNonBookProducts", "in": "query", "required": false, "description": "Include reviewed non-book products hidden by default.", "schema": { "default": false, "type": "boolean", "description": "Include reviewed non-book products hidden by default." } }, { "name": "sortBy", "in": "query", "required": false, "description": "Sort by title, publication date, or series. Defaults to title.", "schema": { "default": "title", "type": "string", "enum": [ "title", "publicationDate", "series" ], "description": "Sort by title, publication date, or series. Defaults to title." } }, { "name": "sortDirection", "in": "query", "required": false, "description": "Sort direction. Defaults to asc.", "schema": { "default": "asc", "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction. Defaults to asc." } }, { "name": "limit", "in": "query", "required": false, "description": "Books per page. Defaults to 100; maximum 500.", "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 500, "description": "Books per page. Defaults to 100; maximum 500." } }, { "name": "offset", "in": "query", "required": false, "description": "Zero-based pagination offset. Defaults to 0.", "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Zero-based pagination offset. Defaults to 0." } } ], "responses": { "200": { "description": "Resolved catalog metadata, stable Book and Edition keys, management state, custom definitions and values, pagination, and visibility details.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogResponseRest" }, "examples": { "books": { "summary": "Catalog without Edition arrays", "value": { "meta": { "totalBooks": 1, "returnedBooks": 1, "offset": 0, "limit": 100, "truncated": false, "generatedAt": "2026-08-12T12:00:00.000Z", "includedEditions": false, "excludedArchivedBooks": 0, "excludedNonBookProducts": 0, "catalogVisibility": { "archivedBooks": { "mode": "hidden_by_default", "includeParameter": "includeArchived", "hiddenMatchingBooks": 0, "note": "Archived Books are hidden unless includeArchived=true." }, "nonBookProducts": { "mode": "hidden_by_default", "includeParameter": "includeNonBookProducts", "hiddenMatchingProducts": 0, "note": "Reviewed non-book products are hidden unless requested." } } }, "customAttributeDefinitions": [], "books": [ { "bookKey": "book-1", "title": { "value": "A Sample Book", "inferred": false }, "author": { "value": "Example Author", "inferred": false }, "series": { "value": null, "inferred": false }, "seriesPosition": { "value": null, "inferred": false }, "publicationDate": { "value": "2026-01-15", "inferred": false }, "publicationYear": { "value": "2026", "inferred": false }, "color": { "value": null, "inferred": false }, "coauthor": { "value": null, "inferred": false }, "url": { "value": "https://example.invalid/book", "inferred": false }, "image": { "value": null, "inferred": false }, "archived": false, "nonBook": false, "memberCount": 1 } ] } }, "booksAndEditions": { "summary": "Catalog with Edition metadata", "value": { "meta": { "totalBooks": 1, "returnedBooks": 1, "offset": 0, "limit": 100, "truncated": false, "generatedAt": "2026-08-12T12:00:00.000Z", "includedEditions": true, "excludedArchivedBooks": 0, "excludedNonBookProducts": 0, "catalogVisibility": { "archivedBooks": { "mode": "hidden_by_default", "includeParameter": "includeArchived", "hiddenMatchingBooks": 0, "note": "Archived Books are hidden unless includeArchived=true." }, "nonBookProducts": { "mode": "hidden_by_default", "includeParameter": "includeNonBookProducts", "hiddenMatchingProducts": 0, "note": "Reviewed non-book products are hidden unless requested." } } }, "customAttributeDefinitions": [], "books": [ { "bookKey": "book-1", "title": { "value": "A Sample Book", "inferred": false }, "author": { "value": "Example Author", "inferred": false }, "series": { "value": null, "inferred": false }, "seriesPosition": { "value": null, "inferred": false }, "publicationDate": { "value": "2026-01-15", "inferred": false }, "publicationYear": { "value": "2026", "inferred": false }, "color": { "value": null, "inferred": false }, "coauthor": { "value": null, "inferred": false }, "url": { "value": "https://example.invalid/book", "inferred": false }, "image": { "value": null, "inferred": false }, "archived": false, "nonBook": false, "memberCount": 1, "editions": [ { "editionKey": "edition-1", "sourceTitle": "A Sample Book", "format": { "value": "eBook", "inferred": false }, "distributor": { "value": "Kindle Direct Publishing", "inferred": false }, "kenpc": { "value": 320, "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://example.invalid/edition", "inferred": false }, "image": { "value": null, "inferred": false }, "nonBook": false, "classification": "book" } ] } ] } } } } } }, "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": "Run a Report Request for numeric facts such as sales, earnings, units, borrows, pages read, refunds, and royalties. 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. Discover unfamiliar fields with GET /api/v1/report-fields and authoritative filter values with GET /api/v1/report-filter-values. Multiple values within one filter are OR; different filter keys are AND.\n\nChoose either one relative range or inclusive explicit start and end dates. Relative ranges use the Book Report server calendar in UTC. The total attribute may be used alone or with other attributes; when combined it produces the literal root label Total. includeFilterKey adds *_key companion columns for requested attributes where stable keys exist.\n\nRows sort descending by the first requested metric. Money metrics use the account currency unless currency overrides it. Page-read royalty and estimated-borrow settings from GET /api/v1/account-context apply automatically. Use catalog discovery for descriptive Book and Edition metadata; Report Execution returns aggregated facts.", "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 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": "Ordered column metadata, string/number/null report rows, canonical generation metadata, and transport-specific row-window metadata.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportResponse" }, "examples": { "earningsByBook": { "summary": "One numeric report row", "value": { "meta": { "generatedAt": "2026-08-12T12:00:00.000Z", "start": "2026-07-14", "end": "2026-08-12", "currency": "USD", "rowCount": 1, "pageReadRoyaltyRateMode": "previous_month", "customPageReadRoyaltyRateUsd": null, "kenpcFractionPerEstimatedBorrow": 0.75, "linkDomain": "www.amazon.com", "sort": { "key": "earnings", "direction": "desc", "type": "metric" }, "generationMs": 12 }, "columns": [ { "key": "book", "kind": "attribute", "type": "string" }, { "key": "earnings", "kind": "metric", "type": "number", "currency": "USD" } ], "rows": [ { "book": "A Sample Book", "earnings": 42.5 } ] } }, "filteredMonthlyTopRows": { "summary": "Stable key companions and a REST row limit", "value": { "meta": { "generatedAt": "2026-08-12T12:00:00.000Z", "start": "2026-01-01", "end": "2026-06-30", "currency": "USD", "rowCount": 18, "pageReadRoyaltyRateMode": "previous_month", "customPageReadRoyaltyRateUsd": null, "kenpcFractionPerEstimatedBorrow": 0.75, "linkDomain": "www.amazon.com", "sort": { "key": "earnings", "direction": "desc", "type": "metric" }, "generationMs": 12 }, "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": "A Sample Book", "book_key": "book-1", "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": "edition", "label": "Edition", "type": "Edition", "description": "A specific distributor Edition of a Book, such as its KDP eBook or ACX audiobook. Labels begin with the Book title and add useful distributor or format details. A provider ID is included only when those details do not distinguish the Book's Editions." }, { "key": "product", "label": "Product", "type": "Book", "description": "The catalog book grouping used by Book, except reviewed non-book BookFunnel products remain separate instead of being combined into one Non-Book Products row. Use Book ID for distributor-specific edition or product identifiers." }, { "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": "Edition", "description": "The language associated with the book, when available." }, { "key": "book_id", "label": "Book ID", "type": "Edition", "description": "The raw identifier reported by the distributor for an Edition. Unlike Edition, this shows the ID without the Book title or a distributor and format label." }, { "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": "Edition", "description": "Contributor names listed as translators in distributor metadata. Multiple names may be combined in one value." }, { "key": "illustrator", "label": "Illustrator", "type": "Edition", "description": "Contributor names listed as illustrators in distributor metadata. Multiple names may be combined in one value." }, { "key": "editor", "label": "Editor", "type": "Edition", "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": "Edition", "description": "The format of the book involved in the transaction, such as eBook, paperback, hardcover, or audiobook." }, { "key": "distributor", "label": "Distributor", "type": "Edition", "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/editable-catalogs": { "get": { "operationId": "listEditableCatalogs", "tags": [ "Catalog editing" ], "summary": "List catalogs the Actor can manage", "description": "Lists the Actor’s own Catalog and each shared Editable Catalog the Actor can currently manage. Use a returned Public Account ID to read that exact Catalog, create its Catalog Edit Session, or inspect its edit history.", "responses": { "200": { "description": "At least one Catalog Owner identity, Public Account ID, and owner-or-granted access classification.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditableCatalogsResponseRest" }, "examples": { "owner": { "summary": "Actor-owned Editable Catalog", "value": { "catalogs": [ { "accountId": "BR-7KM-4QX", "label": "Your catalog", "access": "owner" } ] } } } } } }, "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/ad-destinations": { "get": { "operationId": "listAdDestinations", "tags": [ "Ad destinations" ], "summary": "List advertised destinations, links, and attributes", "description": "Lists exact destinations imported with advertising facts, their current Book or Edition link, every effective report attribute with its source, and whether the destination is excluded from reports. Omit the Catalog Owner target for the Actor’s own data. Use the returned destination string unchanged when updating it.A destination can link to a readable shared Catalog. Use its returned Catalog Owner Public Account ID to identify the linked Book, Edition, or custom attribute. Direct attributes and report exclusion belong to the importing account.", "parameters": [ { "name": "accountId", "in": "query", "required": false, "description": "Optional Catalog Owner Public Account ID. Omission selects the Actor’s Catalog.", "schema": { "type": "string", "pattern": "^BR-[A-Z0-9]{3}-[A-Z0-9]{3}$", "description": "Optional Catalog Owner Public Account ID. Omission selects the Actor’s Catalog." } }, { "name": "limit", "in": "query", "required": false, "description": "Ad Destinations per page. Defaults to 100; maximum 250.", "schema": { "default": 100, "type": "integer", "minimum": 1, "maximum": 250, "description": "Ad Destinations per page. Defaults to 100; maximum 250." } }, { "name": "cursor", "in": "query", "required": false, "description": "Zero-based Ad Destination cursor returned by the previous page. Defaults to 0.", "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Zero-based Ad Destination cursor returned by the previous page. Defaults to 0." } } ], "responses": { "200": { "description": "A bounded page of exact Ad Destinations with current links and effective attributes.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvertisingDestinationPageRest" }, "examples": { "matchedDestination": { "summary": "One automatically matched Ad Destination", "value": { "destinations": [ { "destination": "https://www.amazon.com/dp/B012345678", "catalogOwnerAccountId": "BR-BBB-BBB", "link": { "mode": "automatic", "target": { "type": "edition", "distributor": "Kindle Direct Publishing", "editionKey": "B012345678" } }, "attributes": { "author": { "value": "Example Author", "source": "link" }, "format": { "value": "eBook", "source": "link" }, "marketplace": { "value": "Amazon.com", "source": "inferred" }, "custom": [ { "customAttributeId": "launch-campaign", "name": "Launch Campaign", "describes": "book", "value": "Spring", "source": "link" } ] }, "excludedFromReports": false, "hasRecentSpend": true, "needsAttention": false } ], "totalDestinations": 1, "returnedDestinations": 1, "limit": 100, "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" } } }, "post": { "operationId": "updateAdDestination", "tags": [ "Ad destinations" ], "summary": "Apply sparse changes to one Ad Destination", "description": "Applies sparse authored changes to one exact destination, then rebuilds and returns its current link and effective attributes. Author, Series, and custom-attribute changes require an unlinked destination. Marketplace can be set independently of Book or Edition matching; clearing it restores URL inference. Select automatic to clear the authored Book or Edition link and return to automatic matching. Report exclusion is independent and preserves the underlying link and attributes.For a shared Book or Edition link, target its Catalog Owner and use IDs from that Catalog. An authorized collaborator can link a destination imported into their own account before the Catalog Owner connects Facebook. The link is saved in the target Catalog. For direct attributes or report exclusion, target the importing account.", "requestBody": { "required": true, "description": "Exact destination plus sparse link, direct-attribute, or report-exclusion changes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvertisingDestinationUpdateRequest" }, "examples": { "linkEdition": { "summary": "Link one destination to an Edition", "value": { "accountId": "BR-BBB-BBB", "destination": "https://www.amazon.com/dp/B012345678", "changes": { "link": { "mode": "edition", "distributor": "Kindle Direct Publishing", "editionKey": "B012345678" } } } }, "setDirectAttributes": { "summary": "Keep one destination unlinked and set attributes directly", "value": { "destination": "https://author.example/free-story", "changes": { "link": { "mode": "unlinked" }, "attributes": { "author": "Example Author" } } } }, "clearOverride": { "summary": "Return one destination to automatic matching", "value": { "destination": "https://www.amazon.com/dp/B012345678", "changes": { "link": { "mode": "automatic" } } } } } } } }, "responses": { "200": { "description": "The updated Ad Destination after rebuilding its link and effective attributes.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvertisingDestinationUpdatedRest" }, "examples": { "updatedDestination": { "summary": "One rebuilt Ad Destination", "value": { "destination": "https://www.amazon.com/dp/B012345678", "catalogOwnerAccountId": "BR-BBB-BBB", "link": { "mode": "edition", "distributor": "Kindle Direct Publishing", "editionKey": "B012345678" }, "attributes": { "author": { "value": "Example Author", "source": "link" }, "format": { "value": "eBook", "source": "link" }, "marketplace": { "value": "Amazon.com", "source": "inferred" }, "custom": [ { "customAttributeId": "launch-campaign", "name": "Launch Campaign", "describes": "book", "value": "Spring", "source": "link" } ] }, "excludedFromReports": false, "hasRecentSpend": true, "needsAttention": 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-edit-sessions": { "get": { "operationId": "listCatalogEditSessions", "tags": [ "Catalog editing" ], "summary": "List Catalog Edit history", "description": "Lists lightweight committed Catalog Edit Session summaries for one authorized Catalog Owner, newest first. Omit the target for the Actor’s own Catalog. Pages default to 25 summaries and accept at most 100. Fetch a session by ID for its full ordered changes, or use its ID to begin an undo workflow.", "parameters": [ { "name": "accountId", "in": "query", "required": false, "description": "Optional Catalog Owner Public Account ID. Omission selects the Actor’s Catalog.", "schema": { "type": "string", "pattern": "^BR-[A-Z0-9]{3}-[A-Z0-9]{3}$", "description": "Optional Catalog Owner Public Account ID. Omission selects the Actor’s Catalog." } }, { "name": "limit", "in": "query", "required": false, "description": "Committed-session summaries per page. Defaults to 25; maximum 100.", "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100, "description": "Committed-session summaries per page. Defaults to 25; maximum 100." } }, { "name": "cursor", "in": "query", "required": false, "description": "Zero-based history cursor returned by the previous page. Defaults to 0.", "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Zero-based history cursor returned by the previous page. Defaults to 0." } } ], "responses": { "200": { "description": "Catalog Owner identity and a paginated page of lightweight committed-session summaries.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogEditSessionHistoryPageRest" }, "examples": { "nonemptyHistory": { "summary": "One lightweight committed-session summary", "value": { "catalogOwner": { "accountId": "BR-7KM-4QX", "label": "Your catalog", "access": "owner" }, "sessions": [ { "sessionId": "session-1", "committedAt": "2026-08-12T12:05:00.000Z", "revision": 1, "changeCount": 1, "undoneChangeCount": 0, "effectStatus": "applied", "attribution": { "type": "oauth", "name": "Catalog helper" } } ], "totalSessions": 1, "returnedSessions": 1, "limit": 25, "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" } } }, "post": { "operationId": "createCatalogEditSession", "tags": [ "Catalog editing" ], "summary": "Create an empty Catalog Edit draft", "description": "Creates an empty draft Catalog Edit Session for the explicitly selected Catalog Owner. First list Editable Catalogs and copy the intended Catalog Owner Public Account ID, including when editing the Actor’s own Catalog. Creation does not change saved catalog state.", "requestBody": { "required": true, "description": "Required explicit Catalog Owner Public Account ID from Editable Catalog discovery.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogEditSessionCreateRequest" }, "examples": { "selectedCatalogOwner": { "summary": "Create a draft for an explicitly selected Catalog Owner", "value": { "accountId": "BR-7KM-4QX" } } } } } }, "responses": { "200": { "description": "The newly created empty draft Catalog Edit Session.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogEditSessionCreatedRest" }, "examples": { "emptyDraft": { "summary": "A new empty draft with authorized action types", "value": { "catalogOwner": { "accountId": "BR-7KM-4QX", "label": "Your catalog", "access": "owner" }, "sessionId": "session-1", "status": "draft", "revision": 0, "createdAt": "2026-08-12T12:00:00.000Z", "availableActionTypes": [ "edit_book_info", "edit_edition_info", "add_custom_column", "remove_custom_column", "set_book_archived", "group_books", "move_editions", "separate_editions", "classify_products" ] } } } } } }, "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-edit-sessions/{sessionId}": { "get": { "operationId": "getCatalogEditSession", "tags": [ "Catalog editing" ], "summary": "Get one Catalog Edit Session", "description": "Returns full detail for a draft or committed Catalog Edit Session when the Actor can still manage its Catalog Owner. Use it to inspect current status, revision, ordered canonical changes, preview state, reversal links, and safe committed attribution. This read-only management call changes nothing.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "Catalog Edit Session ID.", "schema": { "type": "string", "minLength": 1, "description": "Catalog Edit Session ID." } } ], "responses": { "200": { "description": "Catalog Owner identity and full appropriate detail for the requested Catalog Edit Session.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogEditSessionDetailRest" }, "examples": { "committedDetail": { "summary": "Full committed session detail", "value": { "catalogOwner": { "accountId": "BR-7KM-4QX", "label": "Your catalog", "access": "owner" }, "sessionId": "session-1", "status": "committed", "revision": 1, "previewToken": null, "createdAt": "2026-08-12T12:00:00.000Z", "committedAt": "2026-08-12T12:05:00.000Z", "reversesSessionId": null, "availableActionTypes": [], "changes": [ { "changeId": "change-1", "ordinal": 1, "type": "edit_book_info", "description": "Set **Original title**'s title to **Revised title**", "reversesChangeId": null, "target": { "kind": "book", "key": "book-1", "label": "Original title" }, "data": { "bookKey": "book-1", "field": "title", "state": { "present": true, "value": "Revised title" } }, "before": { "present": true, "value": "Original title", "displayValue": "Original title", "bookTitle": "Original title" }, "after": { "present": true, "value": "Revised title", "displayValue": "Revised title", "bookTitle": "Original title" } } ], "attribution": { "type": "oauth", "name": "Catalog helper" } } } } } } }, "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-edit-sessions/{sessionId}/actions": { "post": { "operationId": "addCatalogEditAction", "tags": [ "Catalog editing" ], "summary": "Add one Authorized Action to a draft session", "description": "Stages one canonical public catalog action in an existing draft Catalog Edit Session. Read the targeted Catalog first and copy its identities exactly. Repeating a compactable action for the same field or object replaces the earlier draft change. Staging changes only the draft and invalidates any earlier preview.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "Catalog Edit Session ID.", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "description": "Exactly one canonical public Catalog Edit action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogEditActionRequest" }, "examples": { "edit_book_info": { "summary": "Valid edit_book_info action", "value": { "type": "edit_book_info", "edits": [ { "bookKey": "book-1", "changes": { "title": "Revised title" } } ] } }, "edit_edition_info": { "summary": "Valid edit_edition_info action", "value": { "type": "edit_edition_info", "edits": [ { "editionKey": "edition-1", "distributor": "Kindle Direct Publishing", "changes": { "language": "English" } } ] } }, "add_custom_column": { "summary": "Valid add_custom_column action", "value": { "type": "add_custom_column", "customAttributeId": "35f2dc77-1b19-4c48-a213-8ed6f6f8155e", "name": "Narrator", "describes": "edition" } }, "remove_custom_column": { "summary": "Valid remove_custom_column action", "value": { "type": "remove_custom_column", "customAttributeId": "35f2dc77-1b19-4c48-a213-8ed6f6f8155e" } }, "set_book_archived": { "summary": "Valid set_book_archived action", "value": { "type": "set_book_archived", "edits": [ { "bookKey": "book-1", "archived": true } ] } }, "group_books": { "summary": "Valid group_books action", "value": { "type": "group_books", "groups": [ { "bookKeys": [ "book-1", "book-2" ], "bookInfoFromBookKey": "book-1" } ] } }, "move_editions": { "summary": "Valid move_editions action", "value": { "type": "move_editions", "moves": [ { "editionKey": "edition-2", "distributor": "Draft2Digital", "bookKey": "book-1" } ] } }, "separate_editions": { "summary": "Valid separate_editions action", "value": { "type": "separate_editions", "editions": [ { "editionKey": "edition-2", "distributor": "Draft2Digital" } ] } }, "classify_products": { "summary": "Valid classify_products action", "value": { "type": "classify_products", "classifications": [ { "editionKey": "product-1", "distributor": "BookFunnel", "classification": "book", "format": "eBook" } ] } } } } } }, "responses": { "200": { "description": "Catalog Owner identity, draft revision, and concise ordered staged-change summaries.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogEditSessionStagedRest" }, "examples": { "stagedRevision": { "summary": "A draft after one action is staged", "value": { "catalogOwner": { "accountId": "BR-7KM-4QX", "label": "Your catalog", "access": "owner" }, "sessionId": "session-1", "status": "draft", "revision": 1, "changeCount": 1, "stagedChanges": [ { "changeId": "change-1", "ordinal": 1, "type": "edit_book_info", "description": "Set **Original title**'s title to **Revised title**", "reversesChangeId": null, "target": { "kind": "book", "key": "book-1", "label": "Original title" } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "504": { "$ref": "#/components/responses/RequestTimeout" } } } }, "/api/v1/catalog-edit-sessions/{sessionId}/preview": { "post": { "operationId": "previewCatalogEditSession", "tags": [ "Catalog editing" ], "summary": "Resolve and preview canonical Catalog changes", "description": "Resolves every staged action against current Catalog state and returns the Catalog Owner, complete ordered human-readable canonical diff, revision, and preview token. Show the entire preview to the user. Preview again after staging because a new revision invalidates the earlier token. Preview changes nothing.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "Catalog Edit Session ID.", "schema": { "type": "string", "minLength": 1, "description": "Catalog Edit Session ID." } } ], "responses": { "200": { "description": "Catalog Owner identity, complete ordered canonical diff, revision, count, and preview token.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogEditSessionPreviewedRest" }, "examples": { "resolvedPreview": { "summary": "A complete before-and-after preview with confirmation token", "value": { "catalogOwner": { "accountId": "BR-7KM-4QX", "label": "Your catalog", "access": "owner" }, "sessionId": "session-1", "status": "draft", "revision": 1, "previewToken": "preview-1", "changeCount": 1, "changes": [ { "changeId": "change-1", "ordinal": 1, "type": "edit_book_info", "description": "Set **Original title**'s title to **Revised title**", "reversesChangeId": null, "target": { "kind": "book", "key": "book-1", "label": "Original title" }, "data": { "bookKey": "book-1", "field": "title", "state": { "present": true, "value": "Revised title" } }, "before": { "present": true, "value": "Original title", "displayValue": "Original title", "bookTitle": "Original title" }, "after": { "present": true, "value": "Revised title", "displayValue": "Revised title", "bookTitle": "Original title" } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "504": { "$ref": "#/components/responses/RequestTimeout" } } } }, "/api/v1/catalog-edit-sessions/{sessionId}/commit": { "post": { "operationId": "commitCatalogEditSession", "tags": [ "Catalog editing" ], "summary": "Commit the latest confirmed preview", "description": "This is the destructive Catalog Editing operation. After showing the latest preview and receiving confirmation, atomically persist the changes only when previewToken still matches the draft revision and Catalog state. If the Catalog changed or the preview is stale, refresh the targeted Catalog and rebuild or re-preview before asking again. After any ambiguous timeout or server failure, inspect the session with GET /api/v1/catalog-edit-sessions/:sessionId before retrying: if committed, stop; if draft, re-preview as needed and obtain fresh confirmation.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "Catalog Edit Session ID.", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "description": "The latest confirmed preview token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogEditCommitRequest" }, "examples": { "commit": { "summary": "Commit the latest confirmed preview", "value": { "previewToken": "preview-1" } } } } } }, "responses": { "200": { "description": "Catalog Owner identity, atomically committed change summaries, and safe Catalog Edit Attribution.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogEditSessionCommittedRest" }, "examples": { "committedSession": { "summary": "Committed change summaries with safe attribution", "value": { "catalogOwner": { "accountId": "BR-7KM-4QX", "label": "Your catalog", "access": "owner" }, "sessionId": "session-1", "status": "committed", "revision": 1, "committedAt": "2026-08-12T12:05:00.000Z", "changeCount": 1, "committedChanges": [ { "changeId": "change-1", "ordinal": 1, "type": "edit_book_info", "description": "Set **Original title**'s title to **Revised title**", "reversesChangeId": null, "target": { "kind": "book", "key": "book-1", "label": "Original title" } } ], "attribution": { "type": "oauth", "name": "Catalog helper" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "504": { "$ref": "#/components/responses/RequestTimeout" } } } }, "/api/v1/catalog-edit-sessions/{sessionId}/undo": { "post": { "operationId": "createCatalogEditUndoSession", "tags": [ "Catalog editing" ], "summary": "Create a draft that reverses committed changes", "description": "Creates a new draft with explicit scope: use {scope:\"all\"} to reverse every applied change, or {scope:\"selected\",changeIds:[...]} for a distinct nonempty selection. Undo creation is non-destructive. Preview the new draft, show it, and commit its latest confirmed token like any other session.", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "Catalog Edit Session ID.", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "description": "Required explicit all-or-selected undo scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogEditUndoRequest" }, "examples": { "undoAll": { "summary": "Undo every change", "value": { "scope": "all" } }, "undoSelected": { "summary": "Undo selected committed changes", "value": { "scope": "selected", "changeIds": [ "change-1" ] } } } } } }, "responses": { "200": { "description": "Catalog Owner identity and a non-destructive draft of ordered reversal changes with stable links.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogEditUndoSessionCreatedRest" }, "examples": { "undoDraft": { "summary": "A non-destructive undo draft with reversal links", "value": { "catalogOwner": { "accountId": "BR-7KM-4QX", "label": "Your catalog", "access": "owner" }, "sessionId": "session-2", "status": "draft", "revision": 1, "reversesSessionId": "session-1", "changeCount": 1, "stagedChanges": [ { "changeId": "change-2", "ordinal": 1, "type": "edit_book_info", "description": "Undo: Set **Original title**'s title to **Revised title**", "reversesChangeId": "change-1", "target": { "kind": "book", "key": "book-1", "label": "Original title" } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "504": { "$ref": "#/components/responses/RequestTimeout" } } } } }, "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. Management operations require an API key with management access." } }, "headers": { "ApiVersion": { "description": "Public API major version. Always 1 for documented operations.", "schema": { "type": "string", "const": "1" } }, "BearerChallenge": { "description": "Bearer authentication challenge.", "schema": { "type": "string" } }, "AllowedMethods": { "description": "Comma-separated methods accepted by this operation.", "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 operation.", "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 operation.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" }, "Allow": { "$ref": "#/components/headers/AllowedMethods" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Conflict": { "description": "The Catalog Edit Session is no longer in the required draft state, its preview is stale, or the underlying Catalog changed.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "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": { "EmptyInput": { "description": "No operation-specific input.", "type": "object", "properties": {}, "additionalProperties": false, "examples": [ {} ] }, "ReportRange": { "description": "Relative range resolved against the current Book Report server calendar in UTC.", "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" ] }, "ReportAttributeKey": { "description": "Built-in attribute key or account custom:* key returned by report-field discovery.", "type": "string", "minLength": 1, "x-bookreport-built-in-values": [ "total", "book", "edition", "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", "ad_platform", "campaign", "ad", "ad_group", "ad_profile", "attribution", "date", "month", "year" ] }, "ReportFilterKey": { "description": "Built-in filter key or label accepted by runtime, or an account custom:* key returned by report-field discovery.", "type": "string", "minLength": 1, "x-bookreport-built-in-values": [ "book", "edition", "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" ], "x-bookreport-runtime-also-accepts-labels": true }, "ReportMetricKey": { "description": "Numeric report metric. Money metrics carry currency metadata; ratio metrics use decimal ratios where 1 is 100%.", "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", "earnings_per_sale", "refunds", "pre_orders", "ad_spend", "amazon_ad_spend", "facebook_ad_spend", "net_earnings", "impressions", "clicks", "cpc", "cpm", "ctr" ] }, "ReportField": { "description": "Public report attribute or filter definition.", "type": "object", "properties": { "key": { "type": "string", "description": "Public field token used in report requests." }, "label": { "type": "string", "description": "Human-readable field label." }, "type": { "type": "string", "description": "Book Report field type." }, "description": { "type": "string", "description": "Field usage guidance." } }, "required": [ "key", "label", "type" ], "additionalProperties": false }, "ReportMetricField": { "description": "Public report metric definition.", "type": "object", "properties": { "key": { "type": "string", "description": "Public field token used in report requests." }, "label": { "type": "string", "description": "Human-readable field label." }, "type": { "type": "string", "description": "Book Report field type." }, "description": { "type": "string", "description": "Field usage guidance." }, "isMoney": { "type": "boolean", "description": "Whether this metric is denominated in currency." } }, "required": [ "key", "label", "type", "isMoney" ], "additionalProperties": false }, "ReportFieldsResponse": { "description": "Account-available report vocabulary. It does not return currencies.", "type": "object", "properties": { "ranges": { "type": "array", "items": { "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": "Supported relative date ranges." }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Public field token used in report requests." }, "label": { "type": "string", "description": "Human-readable field label." }, "type": { "type": "string", "description": "Book Report field type." }, "description": { "type": "string", "description": "Field usage guidance." } }, "required": [ "key", "label", "type" ], "additionalProperties": false }, "description": "Account-available row-grouping vocabulary, including custom and feature-dependent fields." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Public field token used in report requests." }, "label": { "type": "string", "description": "Human-readable field label." }, "type": { "type": "string", "description": "Book Report field type." }, "description": { "type": "string", "description": "Field usage guidance." } }, "required": [ "key", "label", "type" ], "additionalProperties": false }, "description": "Account-available report filters." }, "metrics": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Public field token used in report requests." }, "label": { "type": "string", "description": "Human-readable field label." }, "type": { "type": "string", "description": "Book Report field type." }, "description": { "type": "string", "description": "Field usage guidance." }, "isMoney": { "type": "boolean", "description": "Whether this metric is denominated in currency." } }, "required": [ "key", "label", "type", "isMoney" ], "additionalProperties": false }, "description": "Account-available numeric report metrics." } }, "required": [ "ranges", "attributes", "filters", "metrics" ], "additionalProperties": false, "examples": [ { "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": "edition", "label": "Edition", "type": "Edition", "description": "A specific distributor Edition of a Book, such as its KDP eBook or ACX audiobook. Labels begin with the Book title and add useful distributor or format details. A provider ID is included only when those details do not distinguish the Book's Editions." }, { "key": "product", "label": "Product", "type": "Book", "description": "The catalog book grouping used by Book, except reviewed non-book BookFunnel products remain separate instead of being combined into one Non-Book Products row. Use Book ID for distributor-specific edition or product identifiers." }, { "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": "Edition", "description": "The language associated with the book, when available." }, { "key": "book_id", "label": "Book ID", "type": "Edition", "description": "The raw identifier reported by the distributor for an Edition. Unlike Edition, this shows the ID without the Book title or a distributor and format label." }, { "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": "Edition", "description": "Contributor names listed as translators in distributor metadata. Multiple names may be combined in one value." }, { "key": "illustrator", "label": "Illustrator", "type": "Edition", "description": "Contributor names listed as illustrators in distributor metadata. Multiple names may be combined in one value." }, { "key": "editor", "label": "Editor", "type": "Edition", "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": "Edition", "description": "The format of the book involved in the transaction, such as eBook, paperback, hardcover, or audiobook." }, { "key": "distributor", "label": "Distributor", "type": "Edition", "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": "ad_platform", "label": "Ad Platform", "type": "Advertising", "description": "The advertising platform that reported the activity, such as Amazon or Meta." }, { "key": "campaign", "label": "Campaign", "type": "Advertising", "description": "The campaign reported by the advertising provider." }, { "key": "ad", "label": "Ad", "type": "Advertising", "description": "The ad 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": "edition", "label": "Edition", "type": "Edition", "description": "A specific distributor Edition of a Book, such as its KDP eBook or ACX audiobook. Labels begin with the Book title and add useful distributor or format details. A provider ID is included only when those details do not distinguish the Book's Editions." }, { "key": "product", "label": "Product", "type": "Book", "description": "The catalog book grouping used by Book, except reviewed non-book BookFunnel products remain separate instead of being combined into one Non-Book Products row. Use Book ID for distributor-specific edition or product identifiers." }, { "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": "Edition", "description": "The language associated with the book, when available." }, { "key": "book_id", "label": "Book ID", "type": "Edition", "description": "The raw identifier reported by the distributor for an Edition. Unlike Edition, this shows the ID without the Book title or a distributor and format label." }, { "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": "Edition", "description": "Contributor names listed as translators in distributor metadata. Multiple names may be combined in one value." }, { "key": "illustrator", "label": "Illustrator", "type": "Edition", "description": "Contributor names listed as illustrators in distributor metadata. Multiple names may be combined in one value." }, { "key": "editor", "label": "Editor", "type": "Edition", "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": "Edition", "description": "The format of the book involved in the transaction, such as eBook, paperback, hardcover, or audiobook." }, { "key": "distributor", "label": "Distributor", "type": "Edition", "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": "earnings_per_sale", "label": "Earnings per Sale", "isMoney": true, "type": "Calculated Metrics", "description": "Total earnings divided by paid sales. Free units, borrows, and pre-orders are excluded from the sales count." }, { "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": "amazon_ad_spend", "label": "Amazon Ad Spend", "isMoney": true, "type": "Advertising Metrics", "description": "The amount spent on Amazon advertising." }, { "key": "facebook_ad_spend", "label": "Facebook Ad Spend", "isMoney": true, "type": "Advertising Metrics", "description": "The amount spent on Facebook 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%." } ] } ] }, "FilterValueUsage": { "description": "Single authoritative explanation of how discovery values map to report filters.", "type": "object", "properties": { "reportFilterField": { "type": "string", "const": "value", "description": "The values property to pass into report filters." }, "displayField": { "type": "string", "const": "label", "description": "The values property intended for display text." }, "note": { "type": "string", "description": "Authoritative value-versus-label guidance." } }, "required": [ "reportFilterField", "displayField", "note" ], "additionalProperties": false, "examples": [ { "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." } ] }, "FilterValuesInput": { "description": "Filter-discovery query or tool arguments.", "type": "object", "properties": { "filter": { "type": "string", "minLength": 1, "description": "Built-in filter key or label, or an account custom:* key. Omit to list filters." }, "query": { "type": "string", "description": "Optional case-insensitive search across labels and values for the selected filter." }, "limit": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100, "description": "Values per page. Defaults to 50; maximum 100." }, "cursor": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Zero-based cursor returned by a previous call. Defaults to 0." } }, "additionalProperties": false, "examples": [ { "filter": "country", "query": "can", "limit": 50, "cursor": 0 } ] }, "FilterValuesResponse": { "description": "Either available filters or one page of values for a selected filter.", "anyOf": [ { "type": "object", "properties": { "filterValueUsage": { "type": "object", "properties": { "reportFilterField": { "type": "string", "const": "value", "description": "The values property to pass into report filters." }, "displayField": { "type": "string", "const": "label", "description": "The values property intended for display text." }, "note": { "type": "string", "description": "Authoritative value-versus-label guidance." } }, "required": [ "reportFilterField", "displayField", "note" ], "additionalProperties": false, "description": "How to use every returned filter value." }, "filters": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "description": "Public report filter token." }, "label": { "type": "string", "minLength": 1, "description": "Human-readable filter label." }, "type": { "type": "string", "minLength": 1, "description": "Book Report filter registry type." }, "optionCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of account-available values for this filter." } }, "required": [ "key", "label", "type", "optionCount" ], "additionalProperties": false }, "description": "Account-available report filters." }, "totalFilters": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of account-available report filters." } }, "required": [ "filterValueUsage", "filters", "totalFilters" ], "additionalProperties": false }, { "type": "object", "properties": { "filterValueUsage": { "type": "object", "properties": { "reportFilterField": { "type": "string", "const": "value", "description": "The values property to pass into report filters." }, "displayField": { "type": "string", "const": "label", "description": "The values property intended for display text." }, "note": { "type": "string", "description": "Authoritative value-versus-label guidance." } }, "required": [ "reportFilterField", "displayField", "note" ], "additionalProperties": false, "description": "How to use every returned filter value." }, "filter": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "description": "Public report filter token." }, "label": { "type": "string", "minLength": 1, "description": "Human-readable filter label." }, "type": { "type": "string", "minLength": 1, "description": "Book Report filter registry type." }, "optionCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of account-available values for this filter." } }, "required": [ "key", "label", "type", "optionCount" ], "additionalProperties": false, "description": "The selected report filter." }, "values": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Human-readable display text." }, "value": { "type": "string", "description": "Value to pass to a report filter." } }, "required": [ "label", "value" ], "additionalProperties": false }, "description": "This page of authoritative filter values." }, "totalValues": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Total values available for the selected filter." }, "matchedValues": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Values matching the optional search query." }, "returnedValues": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Values included in this response page." }, "cursor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Zero-based cursor used for this response page." }, "nextCursor": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Cursor for the next page, or null when complete." } }, "required": [ "filterValueUsage", "filter", "values", "totalValues", "matchedValues", "returnedValues", "cursor", "nextCursor" ], "additionalProperties": false } ], "examples": [ { "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": "Transaction", "optionCount": 2 }, { "key": "format", "label": "Format", "type": "Transaction", "optionCount": 2 } ], "totalFilters": 2 }, { "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": "Transaction", "optionCount": 2 }, "values": [ { "label": "Canada", "value": "CA" }, { "label": "United States", "value": "US" } ], "totalValues": 2, "matchedValues": 2, "returnedValues": 2, "cursor": 0, "nextCursor": null } ] }, "AccountContextRest": { "description": "Safe account report defaults, connected sources, and external-access capabilities.", "type": "object", "properties": { "reportSettings": { "type": "object", "properties": { "currency": { "type": "string", "minLength": 1, "description": "Default currency used for report money metrics." }, "pageReadRoyaltyRateMode": { "type": "string", "enum": [ "previous_month", "pessimistic", "custom" ], "description": "Page-read royalty mode: previous_month reuses the last known marketplace rates; pessimistic estimates a decline from recent history; custom uses the configured nonnegative custom USD rate." }, "customPageReadRoyaltyRateUsd": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ], "description": "Nonnegative custom USD royalty per KENP read when the mode is custom, or null otherwise. Report money metrics convert it to the requested currency." }, "kenpcFractionPerEstimatedBorrow": { "type": "number", "minimum": 0, "description": "Fraction of a Book's KENPC counted as one estimated borrow; 0.75 means pages equal to 75% of KENPC count as one borrow. This is not series read-through." }, "linkDomain": { "type": "string", "minLength": 1, "description": "Amazon domain used for linked report metadata." } }, "required": [ "currency", "pageReadRoyaltyRateMode", "customPageReadRoyaltyRateUsd", "kenpcFractionPerEstimatedBorrow", "linkDomain" ], "additionalProperties": false, "description": "Account report defaults." }, "connectedSources": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Connected source display name." }, "domain": { "type": "string", "minLength": 1, "description": "Canonical source domain." }, "connectionMode": { "type": "string", "minLength": 1, "description": "How Book Report connects to this source." }, "category": { "type": "string", "minLength": 1, "description": "Source category." }, "connected": { "type": "boolean", "const": true, "description": "This source is connected." }, "reconnectWarning": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reconnect guidance when the source needs attention, otherwise null." } }, "required": [ "name", "domain", "connectionMode", "category", "connected", "reconnectWarning" ], "additionalProperties": false, "description": "One connected source visible to the account." }, "description": "Sources visible to the authenticated account." }, "capabilities": { "type": "object", "properties": { "readOnly": { "type": "boolean", "description": "Whether this connection or API key is read-only." }, "catalogEditingSessions": { "type": "boolean", "const": true, "description": "Whether Catalog Edit Sessions are authorized for this connection." }, "reportDefaultsAppliedToMcpReports": { "type": "boolean", "const": true, "description": "Account defaults apply to MCP Report Execution." }, "reportDefaultsAppliedToApiReports": { "type": "boolean", "const": true, "description": "Account defaults apply to REST Report Execution." }, "explicitReportCurrencyOverride": { "type": "boolean", "const": true, "description": "Report Requests may explicitly override currency." }, "includesPii": { "type": "boolean", "const": false, "description": "This safe account-context response excludes PII." } }, "required": [ "readOnly", "reportDefaultsAppliedToMcpReports", "reportDefaultsAppliedToApiReports", "explicitReportCurrencyOverride", "includesPii" ], "additionalProperties": false, "description": "Safe external-access capability flags." } }, "required": [ "reportSettings", "connectedSources", "capabilities" ], "additionalProperties": false, "examples": [ { "reportSettings": { "currency": "USD", "pageReadRoyaltyRateMode": "previous_month", "customPageReadRoyaltyRateUsd": null, "kenpcFractionPerEstimatedBorrow": 0.75, "linkDomain": "www.amazon.com" }, "connectedSources": [ { "name": "Kindle Direct Publishing", "domain": ".amazon.com", "connectionMode": "extension", "category": "retailer", "connected": true, "reconnectWarning": null } ], "capabilities": { "readOnly": true, "reportDefaultsAppliedToMcpReports": true, "reportDefaultsAppliedToApiReports": true, "explicitReportCurrencyOverride": true, "includesPii": false } } ] }, "CatalogStringAttribute": { "description": "Resolved string metadata with an inference marker.", "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved string value, or null when unavailable." }, "inferred": { "type": "boolean", "description": "True when Book Report supplied a supported metadata value from peer Editions in the same Book." } }, "required": [ "value", "inferred" ], "additionalProperties": false }, "CatalogNumberAttribute": { "description": "Resolved whole-number metadata with an inference marker.", "type": "object", "properties": { "value": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Resolved whole-number value, or null when unavailable." }, "inferred": { "type": "boolean", "description": "True when Book Report supplied a supported metadata value from peer Editions in the same Book." } }, "required": [ "value", "inferred" ], "additionalProperties": false }, "CatalogInputRest": { "description": "REST catalog query parameters using camelCase.", "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^BR-[A-Z0-9]{3}-[A-Z0-9]{3}$", "description": "Optional Catalog Owner Public Account ID. Supplying it selects an Editable Catalog and requires data:manage." }, "query": { "type": "string", "description": "Case-insensitive search across Book and Edition identifiers and metadata." }, "author": { "type": "string", "description": "Case-insensitive author or contributor search." }, "series": { "type": "string", "description": "Case-insensitive series search." }, "format": { "type": "string", "description": "Case-insensitive Edition format search." }, "distributor": { "type": "string", "description": "Case-insensitive Edition distributor search." }, "includeEditions": { "default": false, "type": "boolean", "description": "Include Edition-level metadata under every returned Book." }, "includeArchived": { "default": false, "type": "boolean", "description": "Include archived Books hidden by default." }, "includeNonBookProducts": { "default": false, "type": "boolean", "description": "Include reviewed non-book products hidden by default." }, "sortBy": { "default": "title", "type": "string", "enum": [ "title", "publicationDate", "series" ], "description": "Sort by title, publication date, or series. Defaults to title." }, "sortDirection": { "default": "asc", "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction. Defaults to asc." }, "limit": { "default": 100, "type": "integer", "minimum": 1, "maximum": 500, "description": "Books per page. Defaults to 100; maximum 500." }, "offset": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Zero-based pagination offset. Defaults to 0." } }, "additionalProperties": false, "examples": [ { "includeEditions": true } ] }, "CatalogResponseRest": { "description": "Resolved Books, Editions, management state, custom attributes, pagination, and visibility.", "type": "object", "properties": { "meta": { "type": "object", "properties": { "totalBooks": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Total matching Books before pagination." }, "returnedBooks": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Books returned in this page." }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Page offset." }, "limit": { "type": "integer", "minimum": 1, "maximum": 500, "description": "Maximum Books requested for this page." }, "truncated": { "type": "boolean", "description": "Whether more matching Books follow this page." }, "generatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "Catalog generation timestamp." }, "includedEditions": { "type": "boolean", "description": "Whether Edition arrays were requested." }, "excludedArchivedBooks": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Matching archived Books hidden from this result." }, "excludedNonBookProducts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Matching non-book products hidden from this result." }, "catalogVisibility": { "type": "object", "properties": { "archivedBooks": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "included", "hidden_by_default" ], "description": "Whether this category was included in the result." }, "includeParameter": { "type": "string", "description": "Transport input that includes this category." }, "hiddenMatchingBooks": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Matching archived Books omitted from this response." }, "hiddenMatchingProducts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Matching non-book products omitted from this response." }, "note": { "type": "string", "description": "Human-readable visibility guidance." } }, "required": [ "mode", "includeParameter", "note" ], "additionalProperties": false, "description": "Archived-Book visibility for this response." }, "nonBookProducts": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "included", "hidden_by_default" ], "description": "Whether this category was included in the result." }, "includeParameter": { "type": "string", "description": "Transport input that includes this category." }, "hiddenMatchingBooks": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Matching archived Books omitted from this response." }, "hiddenMatchingProducts": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Matching non-book products omitted from this response." }, "note": { "type": "string", "description": "Human-readable visibility guidance." } }, "required": [ "mode", "includeParameter", "note" ], "additionalProperties": false, "description": "Non-book-product visibility for this response." } }, "required": [ "archivedBooks", "nonBookProducts" ], "additionalProperties": false, "description": "Visibility rules applied to this response." } }, "required": [ "totalBooks", "returnedBooks", "offset", "limit", "truncated", "generatedAt", "includedEditions", "excludedArchivedBooks", "excludedNonBookProducts", "catalogVisibility" ], "additionalProperties": false, "description": "Catalog pagination, generation, and visibility metadata." }, "customAttributeDefinitions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable custom-attribute definition ID." }, "name": { "type": "string", "description": "Custom-attribute display name." }, "describes": { "type": "string", "enum": [ "book", "edition" ], "description": "Catalog object kind described by this definition." } }, "required": [ "id", "name", "describes" ], "additionalProperties": false, "description": "One custom-attribute definition." }, "description": "Custom-attribute definitions available in this catalog." }, "books": { "type": "array", "items": { "type": "object", "properties": { "bookKey": { "type": "string", "description": "Stable logical Book catalog key." }, "title": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved string value, or null when unavailable." }, "inferred": { "type": "boolean", "description": "True when Book Report supplied a supported metadata value from peer Editions in the same Book." } }, "required": [ "value", "inferred" ], "additionalProperties": false, "description": "Resolved Book title." }, "author": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved string value, or null when unavailable." }, "inferred": { "type": "boolean", "description": "True when Book Report supplied a supported metadata value from peer Editions in the same Book." } }, "required": [ "value", "inferred" ], "additionalProperties": false, "description": "Resolved Book author." }, "series": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved string value, or null when unavailable." }, "inferred": { "type": "boolean", "description": "True when Book Report supplied a supported metadata value from peer Editions in the same Book." } }, "required": [ "value", "inferred" ], "additionalProperties": false, "description": "Resolved Book series." }, "seriesPosition": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Resolved whole-number value, or null when unavailable." }, "inferred": { "type": "boolean", "description": "True when Book Report supplied a supported metadata value from peer Editions in the same Book." } }, "required": [ "value", "inferred" ], "additionalProperties": false, "description": "Resolved position within the Book series." }, "publicationDate": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved string value, or null when unavailable." }, "inferred": { "type": "boolean", "description": "True when Book Report supplied a supported metadata value from peer Editions in the same Book." } }, "required": [ "value", "inferred" ], "additionalProperties": false, "description": "Resolved Book publication date." }, "publicationYear": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved string value, or null when unavailable." }, "inferred": { "type": "boolean", "description": "True when Book Report supplied a supported metadata value from peer Editions in the same Book." } }, "required": [ "value", "inferred" ], "additionalProperties": false, "description": "Resolved Book publication year." }, "color": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved string value, or null when unavailable." }, "inferred": { "type": "boolean", "description": "True when Book Report supplied a supported metadata value from peer Editions in the same Book." } }, "required": [ "value", "inferred" ], "additionalProperties": false, "description": "Resolved Book color." }, "coauthor": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved string value, or null when unavailable." }, "inferred": { "type": "boolean", "description": "True when Book Report supplied a supported metadata value from peer Editions in the same Book." } }, "required": [ "value", "inferred" ], "additionalProperties": false, "description": "Resolved Book coauthor." }, "url": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved string value, or null when unavailable." }, "inferred": { "type": "boolean", "description": "True when Book Report supplied a supported metadata value from peer Editions in the same Book." } }, "required": [ "value", "inferred" ], "additionalProperties": false, "description": "Resolved Book URL." }, "image": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved string value, or null when unavailable." }, "inferred": { "type": "boolean", "description": "True when Book Report supplied a supported metadata value from peer Editions in the same Book." } }, "required": [ "value", "inferred" ], "additionalProperties": false, "description": "Resolved Book image URL." }, "archived": { "type": "boolean", "description": "Whether this Book is archived in catalog management." }, "nonBook": { "type": "boolean", "description": "Whether this logical Book represents a non-book product." }, "memberCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of Editions grouped into this logical Book." }, "customAttributes": { "type": "array", "items": { "type": "object", "properties": { "customAttributeId": { "type": "string", "description": "Stable custom-attribute definition ID." }, "name": { "type": "string", "description": "Custom-attribute display name." }, "value": { "type": "string", "description": "Direct custom-attribute value." }, "inferred": { "type": "boolean", "const": false, "description": "Custom values are direct and are never inferred." } }, "required": [ "customAttributeId", "name", "value", "inferred" ], "additionalProperties": false, "description": "One direct custom-attribute value." }, "description": "Direct Book custom-attribute values that are present; omitted when no values exist." }, "editions": { "type": "array", "items": { "type": "object", "properties": { "editionKey": { "type": "string", "description": "Stable Edition catalog key." }, "sourceTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Title imported directly for this Edition, or null." }, "format": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Direct string value, or null when unavailable." }, "inferred": { "type": "boolean", "const": false, "description": "This direct Edition value is never inferred." } }, "required": [ "value", "inferred" ], "additionalProperties": false, "description": "Direct Edition format; format is never inferred." }, "distributor": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Direct string value, or null when unavailable." }, "inferred": { "type": "boolean", "const": false, "description": "This direct Edition value is never inferred." } }, "required": [ "value", "inferred" ], "additionalProperties": false, "description": "Direct Edition distributor; distributor is never inferred." }, "kenpc": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Resolved positive whole-number value, or null when unavailable." }, "inferred": { "type": "boolean", "description": "True when Book Report supplied a supported metadata value from peer Editions in the same Book." } }, "required": [ "value", "inferred" ], "additionalProperties": false, "description": "Kindle Edition Normalized Page Count; may be inferred from peer Editions." }, "language": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved string value, or null when unavailable." }, "inferred": { "type": "boolean", "description": "True when Book Report supplied a supported metadata value from peer Editions in the same Book." } }, "required": [ "value", "inferred" ], "additionalProperties": false, "description": "Edition language; may be inferred from peer Editions." }, "translator": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved string value, or null when unavailable." }, "inferred": { "type": "boolean", "description": "True when Book Report supplied a supported metadata value from peer Editions in the same Book." } }, "required": [ "value", "inferred" ], "additionalProperties": false, "description": "Edition translator; may be inferred from peer Editions." }, "editor": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved string value, or null when unavailable." }, "inferred": { "type": "boolean", "description": "True when Book Report supplied a supported metadata value from peer Editions in the same Book." } }, "required": [ "value", "inferred" ], "additionalProperties": false, "description": "Edition editor; may be inferred from peer Editions." }, "illustrator": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved string value, or null when unavailable." }, "inferred": { "type": "boolean", "description": "True when Book Report supplied a supported metadata value from peer Editions in the same Book." } }, "required": [ "value", "inferred" ], "additionalProperties": false, "description": "Edition illustrator; may be inferred from peer Editions." }, "url": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved string value, or null when unavailable." }, "inferred": { "type": "boolean", "description": "True when Book Report supplied a supported metadata value from peer Editions in the same Book." } }, "required": [ "value", "inferred" ], "additionalProperties": false, "description": "Resolved Edition URL." }, "image": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Resolved string value, or null when unavailable." }, "inferred": { "type": "boolean", "description": "True when Book Report supplied a supported metadata value from peer Editions in the same Book." } }, "required": [ "value", "inferred" ], "additionalProperties": false, "description": "Resolved Edition image URL." }, "nonBook": { "type": "boolean", "description": "Whether catalog review classifies this as a non-book." }, "classification": { "anyOf": [ { "type": "string", "enum": [ "book", "non_book" ] }, { "type": "null" } ], "description": "Explicit catalog-review classification, when present." }, "customAttributes": { "type": "array", "items": { "type": "object", "properties": { "customAttributeId": { "type": "string", "description": "Stable custom-attribute definition ID." }, "name": { "type": "string", "description": "Custom-attribute display name." }, "value": { "type": "string", "description": "Direct custom-attribute value." }, "inferred": { "type": "boolean", "const": false, "description": "Custom values are direct and are never inferred." } }, "required": [ "customAttributeId", "name", "value", "inferred" ], "additionalProperties": false, "description": "One direct custom-attribute value." }, "description": "Direct Edition custom-attribute values that are present; omitted when no values exist." } }, "required": [ "editionKey", "sourceTitle", "format", "distributor", "kenpc", "language", "translator", "editor", "illustrator", "url", "image", "nonBook", "classification" ], "additionalProperties": false, "description": "One resolved Edition." }, "description": "Member Editions when explicitly requested." } }, "required": [ "bookKey", "title", "author", "series", "seriesPosition", "publicationDate", "publicationYear", "color", "coauthor", "url", "image", "archived", "nonBook", "memberCount" ], "additionalProperties": false, "description": "One resolved logical Book." }, "description": "This page of resolved logical Books." } }, "required": [ "meta", "customAttributeDefinitions", "books" ], "additionalProperties": false, "examples": [ { "meta": { "totalBooks": 1, "returnedBooks": 1, "offset": 0, "limit": 100, "truncated": false, "generatedAt": "2026-08-12T12:00:00.000Z", "includedEditions": false, "excludedArchivedBooks": 0, "excludedNonBookProducts": 0, "catalogVisibility": { "archivedBooks": { "mode": "hidden_by_default", "includeParameter": "includeArchived", "hiddenMatchingBooks": 0, "note": "Archived Books are hidden unless includeArchived=true." }, "nonBookProducts": { "mode": "hidden_by_default", "includeParameter": "includeNonBookProducts", "hiddenMatchingProducts": 0, "note": "Reviewed non-book products are hidden unless requested." } } }, "customAttributeDefinitions": [], "books": [ { "bookKey": "book-1", "title": { "value": "A Sample Book", "inferred": false }, "author": { "value": "Example Author", "inferred": false }, "series": { "value": null, "inferred": false }, "seriesPosition": { "value": null, "inferred": false }, "publicationDate": { "value": "2026-01-15", "inferred": false }, "publicationYear": { "value": "2026", "inferred": false }, "color": { "value": null, "inferred": false }, "coauthor": { "value": null, "inferred": false }, "url": { "value": "https://example.invalid/book", "inferred": false }, "image": { "value": null, "inferred": false }, "archived": false, "nonBook": false, "memberCount": 1 } ] }, { "meta": { "totalBooks": 1, "returnedBooks": 1, "offset": 0, "limit": 100, "truncated": false, "generatedAt": "2026-08-12T12:00:00.000Z", "includedEditions": true, "excludedArchivedBooks": 0, "excludedNonBookProducts": 0, "catalogVisibility": { "archivedBooks": { "mode": "hidden_by_default", "includeParameter": "includeArchived", "hiddenMatchingBooks": 0, "note": "Archived Books are hidden unless includeArchived=true." }, "nonBookProducts": { "mode": "hidden_by_default", "includeParameter": "includeNonBookProducts", "hiddenMatchingProducts": 0, "note": "Reviewed non-book products are hidden unless requested." } } }, "customAttributeDefinitions": [], "books": [ { "bookKey": "book-1", "title": { "value": "A Sample Book", "inferred": false }, "author": { "value": "Example Author", "inferred": false }, "series": { "value": null, "inferred": false }, "seriesPosition": { "value": null, "inferred": false }, "publicationDate": { "value": "2026-01-15", "inferred": false }, "publicationYear": { "value": "2026", "inferred": false }, "color": { "value": null, "inferred": false }, "coauthor": { "value": null, "inferred": false }, "url": { "value": "https://example.invalid/book", "inferred": false }, "image": { "value": null, "inferred": false }, "archived": false, "nonBook": false, "memberCount": 1, "editions": [ { "editionKey": "edition-1", "sourceTitle": "A Sample Book", "format": { "value": "eBook", "inferred": false }, "distributor": { "value": "Kindle Direct Publishing", "inferred": false }, "kenpc": { "value": 320, "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://example.invalid/edition", "inferred": false }, "image": { "value": null, "inferred": false }, "nonBook": false, "classification": "book" } ] } ] } ] }, "ReportRequest": { "description": "REST report request with array attributes and metrics and exactly one date form.", "type": "object", "properties": { "range": { "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 Book Report UTC server calendar. Mutually exclusive with start/end." }, "start": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Inclusive YYYY-MM-DD start date. Required with end when range is omitted." }, "end": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Inclusive YYYY-MM-DD end date. Required with start when range is omitted." }, "attributes": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Ordered grouping hierarchy from report-field discovery. total may be used alone or creates the literal aggregate root Total alongside other grouping columns.", "x-bookreport-built-in-values": [ "total", "book", "edition", "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", "ad_platform", "campaign", "ad", "ad_group", "ad_profile", "attribution", "date", "month", "year" ] }, "metrics": { "minItems": 1, "type": "array", "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", "earnings_per_sale", "refunds", "pre_orders", "ad_spend", "amazon_ad_spend", "facebook_ad_spend", "net_earnings", "impressions", "clicks", "cpc", "cpm", "ctr" ] }, "description": "Numeric measures from report-field discovery. The first metric controls descending row order.", "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", "earnings_per_sale", "refunds", "pre_orders", "ad_spend", "amazon_ad_spend", "facebook_ad_spend", "net_earnings", "impressions", "clicks", "cpc", "cpm", "ctr" ] }, "filters": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "description": "Map of report filter keys to authoritative values. OR within a key; AND across keys.", "x-bookreport-built-in-keys": [ "book", "edition", "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" ] }, "currency": { "type": "string", "minLength": 1, "description": "Optional nonblank Book Report currency override. Field discovery does not return currencies." }, "includeFilterKey": { "default": false, "type": "boolean", "description": "Boolean. Set to true to add *_key companion columns for all requested attributes that have stable keys. Do not pass attribute or filter names." }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Positive top-row limit applied after sorting; explicit values have no documented maximum." } }, "required": [ "attributes", "metrics" ], "additionalProperties": false, "examples": [ { "range": "last_30_days", "attributes": [ "book" ], "metrics": [ "earnings", "units" ] }, { "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 } ], "oneOf": [ { "required": [ "range" ], "not": { "anyOf": [ { "required": [ "start" ] }, { "required": [ "end" ] } ] } }, { "required": [ "start", "end" ], "not": { "required": [ "range" ] } } ], "x-bookreport-date-selection": { "exactlyOne": [ "range", "start+end" ], "orderedExplicitDates": "start <= end" } }, "ReportResponse": { "description": "Report Execution columns, rows, generation metadata, and row-window metadata.", "type": "object", "properties": { "meta": { "type": "object", "properties": { "generatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "Report generation timestamp." }, "start": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Inclusive report start date." }, "end": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$", "description": "Inclusive report end date." }, "currency": { "type": "string", "minLength": 1, "description": "Currency used for money metrics." }, "rowCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Rows produced before the transport row limit." }, "pageReadRoyaltyRateMode": { "type": "string", "enum": [ "previous_month", "pessimistic", "custom" ], "description": "Page-read royalty mode: previous_month reuses the last known marketplace rates; pessimistic estimates a decline; custom uses the configured nonnegative custom USD rate." }, "customPageReadRoyaltyRateUsd": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ], "description": "Configured nonnegative custom USD royalty per KENP read, or null. Money metrics are converted to the report currency." }, "kenpcFractionPerEstimatedBorrow": { "type": "number", "minimum": 0, "description": "Fraction of a Book’s KENPC counted as one estimated borrow; 0.75 means 75%. This is not series read-through." }, "linkDomain": { "type": "string", "minLength": 1, "description": "Amazon domain used for linked report metadata." }, "sort": { "type": "object", "properties": { "key": { "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", "earnings_per_sale", "refunds", "pre_orders", "ad_spend", "amazon_ad_spend", "facebook_ad_spend", "net_earnings", "impressions", "clicks", "cpc", "cpm", "ctr" ], "description": "First requested metric used to sort rows." }, "direction": { "type": "string", "const": "desc", "description": "Rows sort in descending order." }, "type": { "type": "string", "const": "metric", "description": "Sort key is a report metric." } }, "required": [ "key", "direction", "type" ], "additionalProperties": false, "description": "Sort applied to report rows." }, "generationMs": { "type": "number", "minimum": 0, "description": "Server report-generation duration in milliseconds." } }, "required": [ "generatedAt", "start", "end", "currency", "rowCount", "pageReadRoyaltyRateMode", "customPageReadRoyaltyRateUsd", "kenpcFractionPerEstimatedBorrow", "linkDomain", "generationMs" ], "additionalProperties": false, "description": "Report Execution metadata." }, "columns": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "description": "Requested attribute key or its *_key companion when includeFilterKey/include_filter_key is true." }, "kind": { "type": "string", "const": "attribute", "description": "This is an attribute column." }, "type": { "type": "string", "const": "string", "description": "Attribute cells are strings or null." } }, "required": [ "key", "kind", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "key": { "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", "earnings_per_sale", "refunds", "pre_orders", "ad_spend", "amazon_ad_spend", "facebook_ad_spend", "net_earnings", "impressions", "clicks", "cpc", "cpm", "ctr" ], "description": "Requested metric key." }, "kind": { "type": "string", "const": "metric", "description": "This is a metric column." }, "type": { "type": "string", "const": "number", "description": "Metric cells are numbers." }, "currency": { "type": "string", "minLength": 1, "description": "Present for money metrics." } }, "required": [ "key", "kind", "type" ], "additionalProperties": false } ], "description": "One output-column definition." }, "description": "Ordered output-column definitions." }, "rows": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "null" } ] }, "description": "One report row." }, "description": "Report rows containing only string, number, or null cells." }, "rowWindow": { "type": "object", "properties": { "totalRows": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Rows produced before applying the top-row limit." }, "returnedRows": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Rows included after applying the top-row limit." }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Applied top-row limit." }, "truncated": { "type": "boolean", "description": "Whether the limit omitted report rows." }, "note": { "type": "string", "description": "Human-readable row-window guidance." } }, "required": [ "totalRows", "returnedRows", "limit", "truncated", "note" ], "additionalProperties": false, "description": "Present only when the REST request supplied limit." } }, "required": [ "meta", "columns", "rows" ], "additionalProperties": false, "examples": [ { "meta": { "generatedAt": "2026-08-12T12:00:00.000Z", "start": "2026-07-14", "end": "2026-08-12", "currency": "USD", "rowCount": 1, "pageReadRoyaltyRateMode": "previous_month", "customPageReadRoyaltyRateUsd": null, "kenpcFractionPerEstimatedBorrow": 0.75, "linkDomain": "www.amazon.com", "sort": { "key": "earnings", "direction": "desc", "type": "metric" }, "generationMs": 12 }, "columns": [ { "key": "book", "kind": "attribute", "type": "string" }, { "key": "earnings", "kind": "metric", "type": "number", "currency": "USD" } ], "rows": [ { "book": "A Sample Book", "earnings": 42.5 } ] }, { "meta": { "generatedAt": "2026-08-12T12:00:00.000Z", "start": "2026-01-01", "end": "2026-06-30", "currency": "USD", "rowCount": 18, "pageReadRoyaltyRateMode": "previous_month", "customPageReadRoyaltyRateUsd": null, "kenpcFractionPerEstimatedBorrow": 0.75, "linkDomain": "www.amazon.com", "sort": { "key": "earnings", "direction": "desc", "type": "metric" }, "generationMs": 12 }, "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": "A Sample Book", "book_key": "book-1", "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." } } ] }, "PublicAccountIdInput": { "description": "Canonical uppercase Book Report Public Account ID input.", "type": "string", "pattern": "^BR-[A-Z0-9]{3}-[A-Z0-9]{3}$", "examples": [ "BR-7KM-4QX" ] }, "PublicAccountId": { "description": "Canonical uppercase Book Report Public Account ID returned by Book Report.", "type": "string", "pattern": "^BR-[A-Z0-9]{3}-[A-Z0-9]{3}$", "examples": [ "BR-7KM-4QX" ] }, "EditableCatalogsResponseRest": { "description": "Catalogs the Actor owns or may manage through granted access.", "type": "object", "properties": { "catalogs": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^BR-[A-Z0-9]{3}-[A-Z0-9]{3}$", "description": "Canonical uppercase Public Account ID of the Catalog Owner." }, "label": { "type": "string", "minLength": 1, "description": "Safe non-PII Catalog Owner label." }, "access": { "type": "string", "enum": [ "owner", "granted" ], "description": "owner is the Actor’s catalog; granted is a shared Editable Catalog the Actor may manage." } }, "required": [ "accountId", "label", "access" ], "additionalProperties": false, "description": "One Editable Catalog." }, "description": "Editable Catalogs available to the Actor." } }, "required": [ "catalogs" ], "additionalProperties": false, "examples": [ { "catalogs": [ { "accountId": "BR-7KM-4QX", "label": "Your catalog", "access": "owner" } ] } ] }, "AdvertisingDestinationListRequest": { "description": "REST Ad Destination target and bounded pagination.", "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^BR-[A-Z0-9]{3}-[A-Z0-9]{3}$", "description": "Optional Catalog Owner Public Account ID. Omission selects the Actor’s Catalog." }, "limit": { "default": 100, "type": "integer", "minimum": 1, "maximum": 250, "description": "Ad Destinations per page. Defaults to 100; maximum 250." }, "cursor": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Zero-based Ad Destination cursor returned by the previous page. Defaults to 0." } }, "additionalProperties": false, "examples": [ { "limit": 100, "cursor": 0 } ] }, "AdvertisingDestinationUpdateRequest": { "description": "REST sparse changes for one exact Ad Destination.", "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^BR-[A-Z0-9]{3}-[A-Z0-9]{3}$", "description": "Optional Catalog Owner Public Account ID. Omission selects the Actor’s Catalog." }, "destination": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "Exact Ad Destination returned by destination listing." }, "changes": { "type": "object", "properties": { "link": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "automatic", "description": "Remove the authored Book or Edition link and use automatic matching." } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "unlinked", "description": "Keep this destination explicitly unlinked." } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "book", "description": "Link to one logical Book." }, "bookKey": { "type": "string", "minLength": 1, "description": "Book key copied from Catalog discovery." } }, "required": [ "mode", "bookKey" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "edition", "description": "Link to one Edition." }, "distributor": { "type": "string", "minLength": 1, "description": "Edition distributor value copied from Catalog discovery." }, "editionKey": { "type": "string", "minLength": 1, "description": "Edition identity copied from Catalog discovery." } }, "required": [ "mode", "distributor", "editionKey" ], "additionalProperties": false } ], "description": "Authored link selection for one Ad Destination." }, "attributes": { "type": "object", "properties": { "author": { "description": "Direct author attribute, or null to clear it.", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "series": { "description": "Direct series attribute, or null to clear it.", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "marketplace": { "description": "Direct marketplace attribute, or null to clear it.", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Direct report attributes. Author and Series require an unlinked destination; Marketplace is independent of Book or Edition matching." }, "customAttributes": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "customAttributeId": { "type": "string", "minLength": 1, "description": "Stable custom-attribute definition ID copied from Catalog discovery." }, "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "Direct custom-attribute value, or null to clear it." } }, "required": [ "customAttributeId", "value" ], "additionalProperties": false }, "description": "Sparse direct custom-attribute changes by stable ID." }, "excludedFromReports": { "type": "boolean", "description": "Exclude this destination from Meta advertising reports." } }, "additionalProperties": false, "description": "Sparse link, direct built-in attribute, and direct custom-attribute changes. Null values clear those values. Author, Series, and custom attributes require an unlinked destination; Marketplace remains independent of Book or Edition matching." } }, "required": [ "destination", "changes" ], "additionalProperties": false, "examples": [ { "accountId": "BR-BBB-BBB", "destination": "https://www.amazon.com/dp/B012345678", "changes": { "link": { "mode": "edition", "distributor": "Kindle Direct Publishing", "editionKey": "B012345678" } } }, { "destination": "https://author.example/free-story", "changes": { "link": { "mode": "unlinked" }, "attributes": { "author": "Example Author" } } }, { "destination": "https://www.amazon.com/dp/B012345678", "changes": { "link": { "mode": "automatic" } } } ] }, "AdvertisingDestinationPageRest": { "description": "One bounded page of Ad Destinations.", "type": "object", "properties": { "destinations": { "type": "array", "items": { "type": "object", "properties": { "destination": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "Exact destination string imported from the advertising provider." }, "catalogOwnerAccountId": { "type": "string", "pattern": "^BR-[A-Z0-9]{3}-[A-Z0-9]{3}$", "description": "Public Account ID of the Catalog containing the linked Book or Edition and its custom attributes. When omitted, use the requested account." }, "link": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "automatic", "description": "Use automatic matching." }, "target": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "book", "description": "Logical Book reference." }, "bookKey": { "type": "string", "minLength": 1, "description": "Book key from Catalog discovery." } }, "required": [ "type", "bookKey" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "edition", "description": "Edition reference." }, "distributor": { "type": "string", "minLength": 1, "description": "Edition distributor value from Catalog discovery." }, "editionKey": { "type": "string", "minLength": 1, "description": "Edition key from Catalog discovery." } }, "required": [ "type", "distributor", "editionKey" ], "additionalProperties": false } ], "description": "The linked Book or Edition." }, { "type": "null" } ], "description": "Automatically matched Book or Edition, if any." } }, "required": [ "mode", "target" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "unlinked", "description": "Keep this destination explicitly unlinked." } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "book", "description": "Manually linked to one Book." }, "bookKey": { "type": "string", "minLength": 1, "description": "Book key copied from Catalog discovery." } }, "required": [ "mode", "bookKey" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "edition", "description": "Manually linked to one Edition." }, "distributor": { "type": "string", "minLength": 1, "description": "Edition distributor value copied from Catalog discovery." }, "editionKey": { "type": "string", "minLength": 1, "description": "Edition identity copied from Catalog discovery." } }, "required": [ "mode", "distributor", "editionKey" ], "additionalProperties": false } ], "description": "Current matching mode and Book or Edition. Automatic matching includes its inferred target when one was found." }, "attributes": { "type": "object", "properties": { "title": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective title report attribute and its source." }, "author": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective author report attribute and its source." }, "publicationDate": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective publicationDate report attribute and its source." }, "publicationYear": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective publicationYear report attribute and its source." }, "series": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective series report attribute and its source." }, "seriesPosition": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective seriesPosition report attribute and its source." }, "color": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective color report attribute and its source." }, "coauthor": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective coauthor report attribute and its source." }, "language": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective language report attribute and its source." }, "kenpc": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective kenpc report attribute and its source." }, "translator": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective translator report attribute and its source." }, "editor": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective editor report attribute and its source." }, "illustrator": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective illustrator report attribute and its source." }, "format": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective format report attribute and its source." }, "distributor": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective distributor report attribute and its source." }, "marketplace": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "direct", "inferred" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective marketplace report attribute and its source." }, "custom": { "type": "array", "items": { "type": "object", "properties": { "customAttributeId": { "type": "string", "minLength": 1, "description": "Stable custom-attribute definition ID." }, "name": { "type": "string", "minLength": 1, "description": "Current custom-attribute display name." }, "describes": { "type": "string", "enum": [ "book", "edition" ], "description": "Whether the custom attribute describes Books or Editions." }, "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "Effective value, or null when this destination has no value." }, "source": { "anyOf": [ { "type": "string", "enum": [ "link", "direct" ], "description": "Whether this value comes through the current Book or Edition link or was set directly on the destination." }, { "type": "null" } ], "description": "Where this value comes from, or null when there is no value." } }, "required": [ "customAttributeId", "name", "describes", "value", "source" ], "additionalProperties": false, "description": "One Catalog custom attribute and its destination value." }, "description": "Every Catalog custom-attribute definition, with its stable ID, scope, effective value, and source." } }, "required": [ "custom" ], "additionalProperties": false, "description": "Every effective report attribute, with Catalog custom attributes in their own namespace." }, "excludedFromReports": { "type": "boolean", "description": "Whether this destination is excluded from Meta advertising reports. An Ad with multiple destinations is omitted only when every destination is excluded." }, "hasRecentSpend": { "type": "boolean", "description": "Whether this destination belongs to an Ad with spend in the current or previous two calendar months." }, "needsAttention": { "type": "boolean", "description": "Whether this destination has recent spend, no effective Book or Edition link, and no directly set attributes." } }, "required": [ "destination", "link", "attributes", "excludedFromReports", "hasRecentSpend", "needsAttention" ], "additionalProperties": false, "description": "One exact advertised destination and its current interpretation." }, "description": "Ad Destinations in exact destination order." }, "totalDestinations": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Total Ad Destinations before pagination." }, "returnedDestinations": { "type": "integer", "minimum": 0, "maximum": 250, "description": "Number of Ad Destinations returned in this page." }, "limit": { "type": "integer", "minimum": 1, "maximum": 250, "description": "Maximum Ad Destinations requested for this page." }, "cursor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Zero-based cursor used for this page." }, "nextCursor": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Cursor for the next page, or null at the end." } }, "required": [ "destinations", "totalDestinations", "returnedDestinations", "limit", "cursor", "nextCursor" ], "additionalProperties": false, "examples": [ { "destinations": [ { "destination": "https://www.amazon.com/dp/B012345678", "catalogOwnerAccountId": "BR-BBB-BBB", "link": { "mode": "automatic", "target": { "type": "edition", "distributor": "Kindle Direct Publishing", "editionKey": "B012345678" } }, "attributes": { "author": { "value": "Example Author", "source": "link" }, "format": { "value": "eBook", "source": "link" }, "marketplace": { "value": "Amazon.com", "source": "inferred" }, "custom": [ { "customAttributeId": "launch-campaign", "name": "Launch Campaign", "describes": "book", "value": "Spring", "source": "link" } ] }, "excludedFromReports": false, "hasRecentSpend": true, "needsAttention": false } ], "totalDestinations": 1, "returnedDestinations": 1, "limit": 100, "cursor": 0, "nextCursor": null } ] }, "AdvertisingDestinationUpdatedRest": { "description": "Updated Ad Destination after rebuilding its compiled result.", "type": "object", "properties": { "destination": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "Exact destination string imported from the advertising provider." }, "catalogOwnerAccountId": { "type": "string", "pattern": "^BR-[A-Z0-9]{3}-[A-Z0-9]{3}$", "description": "Public Account ID of the Catalog containing the linked Book or Edition and its custom attributes. When omitted, use the requested account." }, "link": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "automatic", "description": "Use automatic matching." }, "target": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "book", "description": "Logical Book reference." }, "bookKey": { "type": "string", "minLength": 1, "description": "Book key from Catalog discovery." } }, "required": [ "type", "bookKey" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "edition", "description": "Edition reference." }, "distributor": { "type": "string", "minLength": 1, "description": "Edition distributor value from Catalog discovery." }, "editionKey": { "type": "string", "minLength": 1, "description": "Edition key from Catalog discovery." } }, "required": [ "type", "distributor", "editionKey" ], "additionalProperties": false } ], "description": "The linked Book or Edition." }, { "type": "null" } ], "description": "Automatically matched Book or Edition, if any." } }, "required": [ "mode", "target" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "unlinked", "description": "Keep this destination explicitly unlinked." } }, "required": [ "mode" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "book", "description": "Manually linked to one Book." }, "bookKey": { "type": "string", "minLength": 1, "description": "Book key copied from Catalog discovery." } }, "required": [ "mode", "bookKey" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "edition", "description": "Manually linked to one Edition." }, "distributor": { "type": "string", "minLength": 1, "description": "Edition distributor value copied from Catalog discovery." }, "editionKey": { "type": "string", "minLength": 1, "description": "Edition identity copied from Catalog discovery." } }, "required": [ "mode", "distributor", "editionKey" ], "additionalProperties": false } ], "description": "Current matching mode and Book or Edition. Automatic matching includes its inferred target when one was found." }, "attributes": { "type": "object", "properties": { "title": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective title report attribute and its source." }, "author": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective author report attribute and its source." }, "publicationDate": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective publicationDate report attribute and its source." }, "publicationYear": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective publicationYear report attribute and its source." }, "series": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective series report attribute and its source." }, "seriesPosition": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective seriesPosition report attribute and its source." }, "color": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective color report attribute and its source." }, "coauthor": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective coauthor report attribute and its source." }, "language": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective language report attribute and its source." }, "kenpc": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective kenpc report attribute and its source." }, "translator": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective translator report attribute and its source." }, "editor": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective editor report attribute and its source." }, "illustrator": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective illustrator report attribute and its source." }, "format": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective format report attribute and its source." }, "distributor": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "link", "direct" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective distributor report attribute and its source." }, "marketplace": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "number" } ], "description": "Effective report attribute value." }, "source": { "type": "string", "enum": [ "direct", "inferred" ], "description": "Where this effective value comes from." } }, "required": [ "value", "source" ], "additionalProperties": false, "description": "Effective marketplace report attribute and its source." }, "custom": { "type": "array", "items": { "type": "object", "properties": { "customAttributeId": { "type": "string", "minLength": 1, "description": "Stable custom-attribute definition ID." }, "name": { "type": "string", "minLength": 1, "description": "Current custom-attribute display name." }, "describes": { "type": "string", "enum": [ "book", "edition" ], "description": "Whether the custom attribute describes Books or Editions." }, "value": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "Effective value, or null when this destination has no value." }, "source": { "anyOf": [ { "type": "string", "enum": [ "link", "direct" ], "description": "Whether this value comes through the current Book or Edition link or was set directly on the destination." }, { "type": "null" } ], "description": "Where this value comes from, or null when there is no value." } }, "required": [ "customAttributeId", "name", "describes", "value", "source" ], "additionalProperties": false, "description": "One Catalog custom attribute and its destination value." }, "description": "Every Catalog custom-attribute definition, with its stable ID, scope, effective value, and source." } }, "required": [ "custom" ], "additionalProperties": false, "description": "Every effective report attribute, with Catalog custom attributes in their own namespace." }, "excludedFromReports": { "type": "boolean", "description": "Whether this destination is excluded from Meta advertising reports. An Ad with multiple destinations is omitted only when every destination is excluded." }, "hasRecentSpend": { "type": "boolean", "description": "Whether this destination belongs to an Ad with spend in the current or previous two calendar months." }, "needsAttention": { "type": "boolean", "description": "Whether this destination has recent spend, no effective Book or Edition link, and no directly set attributes." } }, "required": [ "destination", "link", "attributes", "excludedFromReports", "hasRecentSpend", "needsAttention" ], "additionalProperties": false, "examples": [ { "destination": "https://www.amazon.com/dp/B012345678", "catalogOwnerAccountId": "BR-BBB-BBB", "link": { "mode": "edition", "distributor": "Kindle Direct Publishing", "editionKey": "B012345678" }, "attributes": { "author": { "value": "Example Author", "source": "link" }, "format": { "value": "eBook", "source": "link" }, "marketplace": { "value": "Amazon.com", "source": "inferred" }, "custom": [ { "customAttributeId": "launch-campaign", "name": "Launch Campaign", "describes": "book", "value": "Spring", "source": "link" } ] }, "excludedFromReports": false, "hasRecentSpend": true, "needsAttention": false } ] }, "CatalogTargetRequest": { "description": "REST Catalog Edit history target and pagination.", "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^BR-[A-Z0-9]{3}-[A-Z0-9]{3}$", "description": "Optional Catalog Owner Public Account ID. Omission selects the Actor’s Catalog." }, "limit": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100, "description": "Committed-session summaries per page. Defaults to 25; maximum 100." }, "cursor": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Zero-based history cursor returned by the previous page. Defaults to 0." } }, "additionalProperties": false, "examples": [ { "limit": 25, "cursor": 0 } ] }, "CatalogEditSessionCreateRequest": { "description": "Required REST Catalog Owner target selected from Editable Catalog discovery.", "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^BR-[A-Z0-9]{3}-[A-Z0-9]{3}$", "description": "Required Catalog Owner Public Account ID selected from Editable Catalog discovery." } }, "required": [ "accountId" ], "additionalProperties": false, "examples": [ { "accountId": "BR-7KM-4QX" } ] }, "SessionIdPathInput": { "description": "REST Catalog Edit Session path identifier.", "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1, "description": "Catalog Edit Session ID." } }, "required": [ "sessionId" ], "additionalProperties": false, "examples": [ { "sessionId": "session-1" } ] }, "CatalogEditSessionCreatedRest": { "description": "New empty Catalog Edit draft and the authorized action types available to continue.", "type": "object", "properties": { "catalogOwner": { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^BR-[A-Z0-9]{3}-[A-Z0-9]{3}$", "description": "Canonical uppercase Public Account ID of the Catalog Owner." }, "label": { "type": "string", "minLength": 1, "description": "Safe non-PII label for the Catalog Owner." }, "access": { "type": "string", "enum": [ "owner", "granted" ], "description": "Whether the Actor owns this catalog or manages it through granted access." } }, "required": [ "accountId", "label", "access" ], "additionalProperties": false, "description": "Explicit identity of the Catalog Owner whose catalog the session manages." }, "sessionId": { "type": "string", "minLength": 1, "description": "Catalog Edit Session ID." }, "status": { "type": "string", "const": "draft", "description": "A newly created session is a non-destructive draft." }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Revision incremented whenever draft actions change." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "Draft creation timestamp." }, "availableActionTypes": { "type": "array", "items": { "type": "string", "enum": [ "edit_book_info", "edit_edition_info", "add_custom_column", "remove_custom_column", "set_book_archived", "group_books", "move_editions", "separate_editions", "classify_products" ], "description": "Authorized public action type." }, "description": "Authorized public action types available for this draft." } }, "required": [ "catalogOwner", "sessionId", "status", "revision", "createdAt", "availableActionTypes" ], "additionalProperties": false, "examples": [ { "catalogOwner": { "accountId": "BR-7KM-4QX", "label": "Your catalog", "access": "owner" }, "sessionId": "session-1", "status": "draft", "revision": 0, "createdAt": "2026-08-12T12:00:00.000Z", "availableActionTypes": [ "edit_book_info", "edit_edition_info", "add_custom_column", "remove_custom_column", "set_book_archived", "group_books", "move_editions", "separate_editions", "classify_products" ] } ] }, "CatalogEditSessionStagedRest": { "description": "Concise draft state after staging, sufficient to continue safely.", "type": "object", "properties": { "catalogOwner": { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^BR-[A-Z0-9]{3}-[A-Z0-9]{3}$", "description": "Canonical uppercase Public Account ID of the Catalog Owner." }, "label": { "type": "string", "minLength": 1, "description": "Safe non-PII label for the Catalog Owner." }, "access": { "type": "string", "enum": [ "owner", "granted" ], "description": "Whether the Actor owns this catalog or manages it through granted access." } }, "required": [ "accountId", "label", "access" ], "additionalProperties": false, "description": "Explicit identity of the Catalog Owner whose catalog the session manages." }, "sessionId": { "type": "string", "minLength": 1, "description": "Catalog Edit Session ID." }, "status": { "type": "string", "const": "draft", "description": "Staging operates only on a draft session." }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Revision incremented whenever draft actions change." }, "changeCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of canonical changes currently staged." }, "stagedChanges": { "type": "array", "items": { "type": "object", "properties": { "changeId": { "type": "string", "minLength": 1, "description": "Stable canonical change ID." }, "ordinal": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "One-based canonical change order within the session." }, "type": { "type": "string", "enum": [ "edit_book_info", "edit_edition_info", "add_custom_column", "remove_custom_column", "set_book_archived", "group_books", "move_editions", "separate_editions", "classify_products" ], "description": "Canonical change type." }, "description": { "type": "string", "minLength": 1, "description": "Human-readable Markdown summary of the canonical change." }, "reversesChangeId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "Original change reversed by this change, or null." }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "book", "edition" ], "description": "Catalog object kind." }, "key": { "type": "string", "minLength": 1, "description": "Stable catalog object key." }, "label": { "type": "string", "minLength": 1, "description": "Human-readable catalog object label." } }, "required": [ "kind", "key", "label" ], "additionalProperties": false, "description": "Small stable target descriptor when the runtime can derive one truthfully." } }, "required": [ "changeId", "ordinal", "type", "description", "reversesChangeId" ], "additionalProperties": false, "description": "Concise stable summary of one canonical session change." }, "description": "Concise ordered summaries of the staged changes." } }, "required": [ "catalogOwner", "sessionId", "status", "revision", "changeCount", "stagedChanges" ], "additionalProperties": false, "examples": [ { "catalogOwner": { "accountId": "BR-7KM-4QX", "label": "Your catalog", "access": "owner" }, "sessionId": "session-1", "status": "draft", "revision": 1, "changeCount": 1, "stagedChanges": [ { "changeId": "change-1", "ordinal": 1, "type": "edit_book_info", "description": "Set **Original title**'s title to **Revised title**", "reversesChangeId": null, "target": { "kind": "book", "key": "book-1", "label": "Original title" } } ] } ] }, "CatalogEditSessionPreviewedRest": { "description": "Catalog Owner, complete ordered canonical diff, revision, and preview token.", "type": "object", "properties": { "catalogOwner": { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^BR-[A-Z0-9]{3}-[A-Z0-9]{3}$", "description": "Canonical uppercase Public Account ID of the Catalog Owner." }, "label": { "type": "string", "minLength": 1, "description": "Safe non-PII label for the Catalog Owner." }, "access": { "type": "string", "enum": [ "owner", "granted" ], "description": "Whether the Actor owns this catalog or manages it through granted access." } }, "required": [ "accountId", "label", "access" ], "additionalProperties": false, "description": "Explicit identity of the Catalog Owner whose catalog the session manages." }, "sessionId": { "type": "string", "minLength": 1, "description": "Catalog Edit Session ID." }, "status": { "type": "string", "const": "draft", "description": "Preview leaves the session in draft state." }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Revision incremented whenever draft actions change." }, "previewToken": { "type": "string", "minLength": 1, "description": "Confirmation token bound to this exact revision and Catalog state." }, "changeCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of canonical changes in this preview." }, "changes": { "type": "array", "items": { "type": "object", "properties": { "changeId": { "type": "string", "minLength": 1, "description": "Stable canonical change ID." }, "ordinal": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "One-based canonical change order within the session." }, "type": { "type": "string", "enum": [ "edit_book_info", "edit_edition_info", "add_custom_column", "remove_custom_column", "set_book_archived", "group_books", "move_editions", "separate_editions", "classify_products" ], "description": "Canonical change type." }, "description": { "type": "string", "minLength": 1, "description": "Human-readable Markdown summary of the canonical change." }, "reversesChangeId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "Original change reversed by this change, or null." }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "book", "edition" ], "description": "Catalog object kind." }, "key": { "type": "string", "minLength": 1, "description": "Stable catalog object key." }, "label": { "type": "string", "minLength": 1, "description": "Human-readable catalog object label." } }, "required": [ "kind", "key", "label" ], "additionalProperties": false, "description": "Small stable target descriptor when the runtime can derive one truthfully." }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Canonical change payload using this transport’s field names." }, "before": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Catalog state before this change, or null before resolution." }, "after": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Catalog state after this change, or null before resolution." } }, "required": [ "changeId", "ordinal", "type", "description", "reversesChangeId", "data", "before", "after" ], "additionalProperties": false, "description": "Full ordered canonical diff entry, including the resolved state transition." }, "description": "Complete ordered canonical diff to show before confirmation." } }, "required": [ "catalogOwner", "sessionId", "status", "revision", "previewToken", "changeCount", "changes" ], "additionalProperties": false, "examples": [ { "catalogOwner": { "accountId": "BR-7KM-4QX", "label": "Your catalog", "access": "owner" }, "sessionId": "session-1", "status": "draft", "revision": 1, "previewToken": "preview-1", "changeCount": 1, "changes": [ { "changeId": "change-1", "ordinal": 1, "type": "edit_book_info", "description": "Set **Original title**'s title to **Revised title**", "reversesChangeId": null, "target": { "kind": "book", "key": "book-1", "label": "Original title" }, "data": { "bookKey": "book-1", "field": "title", "state": { "present": true, "value": "Revised title" } }, "before": { "present": true, "value": "Original title", "displayValue": "Original title", "bookTitle": "Original title" }, "after": { "present": true, "value": "Revised title", "displayValue": "Revised title", "bookTitle": "Original title" } } ] } ] }, "CatalogEditSessionCommittedRest": { "description": "Committed change summaries and safe Catalog Edit Attribution.", "type": "object", "properties": { "catalogOwner": { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^BR-[A-Z0-9]{3}-[A-Z0-9]{3}$", "description": "Canonical uppercase Public Account ID of the Catalog Owner." }, "label": { "type": "string", "minLength": 1, "description": "Safe non-PII label for the Catalog Owner." }, "access": { "type": "string", "enum": [ "owner", "granted" ], "description": "Whether the Actor owns this catalog or manages it through granted access." } }, "required": [ "accountId", "label", "access" ], "additionalProperties": false, "description": "Explicit identity of the Catalog Owner whose catalog the session manages." }, "sessionId": { "type": "string", "minLength": 1, "description": "Catalog Edit Session ID." }, "status": { "type": "string", "const": "committed", "description": "A successful commit returns a committed session." }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Revision incremented whenever draft actions change." }, "committedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "Commit timestamp." }, "changeCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of changes committed atomically." }, "committedChanges": { "type": "array", "items": { "type": "object", "properties": { "changeId": { "type": "string", "minLength": 1, "description": "Stable canonical change ID." }, "ordinal": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "One-based canonical change order within the session." }, "type": { "type": "string", "enum": [ "edit_book_info", "edit_edition_info", "add_custom_column", "remove_custom_column", "set_book_archived", "group_books", "move_editions", "separate_editions", "classify_products" ], "description": "Canonical change type." }, "description": { "type": "string", "minLength": 1, "description": "Human-readable Markdown summary of the canonical change." }, "reversesChangeId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "Original change reversed by this change, or null." }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "book", "edition" ], "description": "Catalog object kind." }, "key": { "type": "string", "minLength": 1, "description": "Stable catalog object key." }, "label": { "type": "string", "minLength": 1, "description": "Human-readable catalog object label." } }, "required": [ "kind", "key", "label" ], "additionalProperties": false, "description": "Small stable target descriptor when the runtime can derive one truthfully." } }, "required": [ "changeId", "ordinal", "type", "description", "reversesChangeId" ], "additionalProperties": false, "description": "Concise stable summary of one canonical session change." }, "description": "Ordered summaries of the committed changes." }, "attribution": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "books_ui", "oauth", "api" ], "description": "Safe source category recorded for this committed edit." }, "name": { "type": "string", "minLength": 1, "description": "Safe source label recorded for this committed edit." } }, "required": [ "type", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "unavailableReason": { "type": "string", "const": "Safe catalog edit attribution is unavailable.", "description": "Explicit reason that safe attribution cannot be shown without exposing or inventing an identity." } }, "required": [ "unavailableReason" ], "additionalProperties": false } ], "description": "Safe Catalog Edit Attribution, or a specific explanation that it is unavailable." } }, "required": [ "catalogOwner", "sessionId", "status", "revision", "committedAt", "changeCount", "committedChanges", "attribution" ], "additionalProperties": false, "examples": [ { "catalogOwner": { "accountId": "BR-7KM-4QX", "label": "Your catalog", "access": "owner" }, "sessionId": "session-1", "status": "committed", "revision": 1, "committedAt": "2026-08-12T12:05:00.000Z", "changeCount": 1, "committedChanges": [ { "changeId": "change-1", "ordinal": 1, "type": "edit_book_info", "description": "Set **Original title**'s title to **Revised title**", "reversesChangeId": null, "target": { "kind": "book", "key": "book-1", "label": "Original title" } } ], "attribution": { "type": "oauth", "name": "Catalog helper" } } ] }, "CatalogEditUndoSessionCreatedRest": { "description": "Non-destructive undo draft with stable reversal links and staged summaries.", "type": "object", "properties": { "catalogOwner": { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^BR-[A-Z0-9]{3}-[A-Z0-9]{3}$", "description": "Canonical uppercase Public Account ID of the Catalog Owner." }, "label": { "type": "string", "minLength": 1, "description": "Safe non-PII label for the Catalog Owner." }, "access": { "type": "string", "enum": [ "owner", "granted" ], "description": "Whether the Actor owns this catalog or manages it through granted access." } }, "required": [ "accountId", "label", "access" ], "additionalProperties": false, "description": "Explicit identity of the Catalog Owner whose catalog the session manages." }, "sessionId": { "type": "string", "minLength": 1, "description": "Catalog Edit Session ID." }, "status": { "type": "string", "const": "draft", "description": "Undo creation returns a non-destructive draft." }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Revision incremented whenever draft actions change." }, "reversesSessionId": { "type": "string", "minLength": 1, "description": "Committed session this undo draft reverses." }, "changeCount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Number of reversal changes staged." }, "stagedChanges": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "changeId": { "type": "string", "minLength": 1, "description": "Stable canonical change ID." }, "ordinal": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "One-based canonical change order within the session." }, "type": { "type": "string", "enum": [ "edit_book_info", "edit_edition_info", "add_custom_column", "remove_custom_column", "set_book_archived", "group_books", "move_editions", "separate_editions", "classify_products" ], "description": "Canonical change type." }, "description": { "type": "string", "minLength": 1, "description": "Human-readable Markdown summary of the canonical change." }, "reversesChangeId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "Original change reversed by this change, or null." }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "book", "edition" ], "description": "Catalog object kind." }, "key": { "type": "string", "minLength": 1, "description": "Stable catalog object key." }, "label": { "type": "string", "minLength": 1, "description": "Human-readable catalog object label." } }, "required": [ "kind", "key", "label" ], "additionalProperties": false, "description": "Small stable target descriptor when the runtime can derive one truthfully." } }, "required": [ "changeId", "ordinal", "type", "description", "reversesChangeId" ], "additionalProperties": false, "description": "Concise stable summary of one canonical session change." }, "description": "Ordered summaries of the staged reversal changes." } }, "required": [ "catalogOwner", "sessionId", "status", "revision", "reversesSessionId", "changeCount", "stagedChanges" ], "additionalProperties": false, "examples": [ { "catalogOwner": { "accountId": "BR-7KM-4QX", "label": "Your catalog", "access": "owner" }, "sessionId": "session-2", "status": "draft", "revision": 1, "reversesSessionId": "session-1", "changeCount": 1, "stagedChanges": [ { "changeId": "change-2", "ordinal": 1, "type": "edit_book_info", "description": "Undo: Set **Original title**'s title to **Revised title**", "reversesChangeId": "change-1", "target": { "kind": "book", "key": "book-1", "label": "Original title" } } ] } ] }, "CatalogEditSessionDetailRest": { "description": "Full appropriate detail for one draft or committed Catalog Edit Session.", "type": "object", "properties": { "catalogOwner": { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^BR-[A-Z0-9]{3}-[A-Z0-9]{3}$", "description": "Canonical uppercase Public Account ID of the Catalog Owner." }, "label": { "type": "string", "minLength": 1, "description": "Safe non-PII label for the Catalog Owner." }, "access": { "type": "string", "enum": [ "owner", "granted" ], "description": "Whether the Actor owns this catalog or manages it through granted access." } }, "required": [ "accountId", "label", "access" ], "additionalProperties": false, "description": "Explicit identity of the Catalog Owner whose catalog the session manages." }, "sessionId": { "type": "string", "minLength": 1, "description": "Catalog Edit Session ID." }, "status": { "type": "string", "enum": [ "draft", "committed" ], "description": "Current Catalog Edit Session lifecycle state." }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Revision incremented whenever draft actions change." }, "previewToken": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "Current preview token, or null when no valid preview exists." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "Draft creation timestamp." }, "committedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "ISO 8601 timestamp." }, { "type": "null" } ], "description": "Commit timestamp, or null while draft." }, "reversesSessionId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "Committed session reversed by this undo session, or null." }, "availableActionTypes": { "type": "array", "items": { "type": "string", "enum": [ "edit_book_info", "edit_edition_info", "add_custom_column", "remove_custom_column", "set_book_archived", "group_books", "move_editions", "separate_editions", "classify_products" ], "description": "Authorized public action type." }, "description": "Authorized action types while draft; empty after commit." }, "changes": { "type": "array", "items": { "type": "object", "properties": { "changeId": { "type": "string", "minLength": 1, "description": "Stable canonical change ID." }, "ordinal": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "One-based canonical change order within the session." }, "type": { "type": "string", "enum": [ "edit_book_info", "edit_edition_info", "add_custom_column", "remove_custom_column", "set_book_archived", "group_books", "move_editions", "separate_editions", "classify_products" ], "description": "Canonical change type." }, "description": { "type": "string", "minLength": 1, "description": "Human-readable Markdown summary of the canonical change." }, "reversesChangeId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "description": "Original change reversed by this change, or null." }, "target": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "book", "edition" ], "description": "Catalog object kind." }, "key": { "type": "string", "minLength": 1, "description": "Stable catalog object key." }, "label": { "type": "string", "minLength": 1, "description": "Human-readable catalog object label." } }, "required": [ "kind", "key", "label" ], "additionalProperties": false, "description": "Small stable target descriptor when the runtime can derive one truthfully." }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "Canonical change payload using this transport’s field names." }, "before": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Catalog state before this change, or null before resolution." }, "after": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ], "description": "Catalog state after this change, or null before resolution." } }, "required": [ "changeId", "ordinal", "type", "description", "reversesChangeId", "data", "before", "after" ], "additionalProperties": false, "description": "Full ordered canonical diff entry, including the resolved state transition." }, "description": "Full ordered canonical changes for this session." }, "attribution": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "books_ui", "oauth", "api" ], "description": "Safe source category recorded for this committed edit." }, "name": { "type": "string", "minLength": 1, "description": "Safe source label recorded for this committed edit." } }, "required": [ "type", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "unavailableReason": { "type": "string", "const": "Safe catalog edit attribution is unavailable.", "description": "Explicit reason that safe attribution cannot be shown without exposing or inventing an identity." } }, "required": [ "unavailableReason" ], "additionalProperties": false } ], "description": "Safe Catalog Edit Attribution, or a specific explanation that it is unavailable." } }, "required": [ "catalogOwner", "sessionId", "status", "revision", "previewToken", "createdAt", "committedAt", "reversesSessionId", "availableActionTypes", "changes" ], "additionalProperties": false, "examples": [ { "catalogOwner": { "accountId": "BR-7KM-4QX", "label": "Your catalog", "access": "owner" }, "sessionId": "session-1", "status": "committed", "revision": 1, "previewToken": null, "createdAt": "2026-08-12T12:00:00.000Z", "committedAt": "2026-08-12T12:05:00.000Z", "reversesSessionId": null, "availableActionTypes": [], "changes": [ { "changeId": "change-1", "ordinal": 1, "type": "edit_book_info", "description": "Set **Original title**'s title to **Revised title**", "reversesChangeId": null, "target": { "kind": "book", "key": "book-1", "label": "Original title" }, "data": { "bookKey": "book-1", "field": "title", "state": { "present": true, "value": "Revised title" } }, "before": { "present": true, "value": "Original title", "displayValue": "Original title", "bookTitle": "Original title" }, "after": { "present": true, "value": "Revised title", "displayValue": "Revised title", "bookTitle": "Original title" } } ], "attribution": { "type": "oauth", "name": "Catalog helper" } } ] }, "CatalogEditSessionHistoryPageRest": { "description": "Paginated lightweight committed-session summaries in newest-first order.", "type": "object", "properties": { "catalogOwner": { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^BR-[A-Z0-9]{3}-[A-Z0-9]{3}$", "description": "Canonical uppercase Public Account ID of the Catalog Owner." }, "label": { "type": "string", "minLength": 1, "description": "Safe non-PII label for the Catalog Owner." }, "access": { "type": "string", "enum": [ "owner", "granted" ], "description": "Whether the Actor owns this catalog or manages it through granted access." } }, "required": [ "accountId", "label", "access" ], "additionalProperties": false, "description": "Explicit identity of the Catalog Owner whose catalog the session manages." }, "sessions": { "type": "array", "items": { "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1, "description": "Committed Catalog Edit Session ID." }, "committedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "description": "Commit timestamp." }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Committed session revision." }, "changeCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of original committed changes." }, "undoneChangeCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of original changes whose latest effect is undone." }, "effectStatus": { "type": "string", "enum": [ "applied", "partially_undone", "undone" ], "description": "Current aggregate effect of this committed session." }, "attribution": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "books_ui", "oauth", "api" ], "description": "Safe source category recorded for this committed edit." }, "name": { "type": "string", "minLength": 1, "description": "Safe source label recorded for this committed edit." } }, "required": [ "type", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "unavailableReason": { "type": "string", "const": "Safe catalog edit attribution is unavailable.", "description": "Explicit reason that safe attribution cannot be shown without exposing or inventing an identity." } }, "required": [ "unavailableReason" ], "additionalProperties": false } ], "description": "Safe Catalog Edit Attribution, or a specific explanation that it is unavailable." } }, "required": [ "sessionId", "committedAt", "revision", "changeCount", "undoneChangeCount", "effectStatus", "attribution" ], "additionalProperties": false, "description": "One committed Catalog Edit Session summary." }, "description": "Lightweight committed-session summaries; use get-session for full changes." }, "totalSessions": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Total committed original sessions before pagination." }, "returnedSessions": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Number of session summaries in this page." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum session summaries requested for this page." }, "cursor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Zero-based cursor used for this page." }, "nextCursor": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Cursor for the next page, or null at the end." } }, "required": [ "catalogOwner", "sessions", "totalSessions", "returnedSessions", "limit", "cursor", "nextCursor" ], "additionalProperties": false, "examples": [ { "catalogOwner": { "accountId": "BR-7KM-4QX", "label": "Your catalog", "access": "owner" }, "sessions": [ { "sessionId": "session-1", "committedAt": "2026-08-12T12:05:00.000Z", "revision": 1, "changeCount": 1, "undoneChangeCount": 0, "effectStatus": "applied", "attribution": { "type": "oauth", "name": "Catalog helper" } } ], "totalSessions": 1, "returnedSessions": 1, "limit": 25, "cursor": 0, "nextCursor": null } ] }, "CatalogEditCommitRequest": { "description": "Strict required REST commit body containing only the latest confirmed preview token.", "type": "object", "properties": { "previewToken": { "type": "string", "minLength": 1, "description": "Token returned by the latest confirmed preview of this exact revision." } }, "required": [ "previewToken" ], "additionalProperties": false, "examples": [ { "previewToken": "preview-1" } ] }, "CatalogEditUndoRequest": { "description": "Strict required REST undo scope: every change or selected distinct change IDs.", "oneOf": [ { "type": "object", "properties": { "scope": { "type": "string", "const": "all", "description": "Reverse every currently applied change in the session." } }, "required": [ "scope" ], "additionalProperties": false }, { "type": "object", "properties": { "scope": { "type": "string", "const": "selected", "description": "Reverse only the listed distinct changeIds." }, "changeIds": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Distinct committed change IDs to reverse.", "uniqueItems": true } }, "required": [ "scope", "changeIds" ], "additionalProperties": false } ], "examples": [ { "scope": "all" }, { "scope": "selected", "changeIds": [ "change-1" ] } ] }, "CatalogEditActionRequest": { "description": "One public canonical Catalog Edit action. reset_to_defaults is intentionally not public.", "oneOf": [ { "$ref": "#/components/schemas/EditBookInfoAction" }, { "$ref": "#/components/schemas/EditEditionInfoAction" }, { "$ref": "#/components/schemas/AddCustomColumnAction" }, { "$ref": "#/components/schemas/RemoveCustomColumnAction" }, { "$ref": "#/components/schemas/SetBookArchivedAction" }, { "$ref": "#/components/schemas/GroupBooksAction" }, { "$ref": "#/components/schemas/MoveEditionsAction" }, { "$ref": "#/components/schemas/SeparateEditionsAction" }, { "$ref": "#/components/schemas/ClassifyProductsAction" } ], "discriminator": { "propertyName": "type", "mapping": { "edit_book_info": "#/components/schemas/EditBookInfoAction", "edit_edition_info": "#/components/schemas/EditEditionInfoAction", "add_custom_column": "#/components/schemas/AddCustomColumnAction", "remove_custom_column": "#/components/schemas/RemoveCustomColumnAction", "set_book_archived": "#/components/schemas/SetBookArchivedAction", "group_books": "#/components/schemas/GroupBooksAction", "move_editions": "#/components/schemas/MoveEditionsAction", "separate_editions": "#/components/schemas/SeparateEditionsAction", "classify_products": "#/components/schemas/ClassifyProductsAction" } }, "examples": [ { "type": "edit_book_info", "edits": [ { "bookKey": "book-1", "changes": { "title": "Revised title" } } ] }, { "type": "edit_edition_info", "edits": [ { "editionKey": "edition-1", "distributor": "Kindle Direct Publishing", "changes": { "language": "English" } } ] }, { "type": "add_custom_column", "customAttributeId": "35f2dc77-1b19-4c48-a213-8ed6f6f8155e", "name": "Narrator", "describes": "edition" }, { "type": "remove_custom_column", "customAttributeId": "35f2dc77-1b19-4c48-a213-8ed6f6f8155e" }, { "type": "set_book_archived", "edits": [ { "bookKey": "book-1", "archived": true } ] }, { "type": "group_books", "groups": [ { "bookKeys": [ "book-1", "book-2" ], "bookInfoFromBookKey": "book-1" } ] }, { "type": "move_editions", "moves": [ { "editionKey": "edition-2", "distributor": "Draft2Digital", "bookKey": "book-1" } ] }, { "type": "separate_editions", "editions": [ { "editionKey": "edition-2", "distributor": "Draft2Digital" } ] }, { "type": "classify_products", "classifications": [ { "editionKey": "product-1", "distributor": "BookFunnel", "classification": "book", "format": "eBook" } ] } ] }, "ErrorIssue": { "description": "One machine-readable request issue.", "type": "object", "properties": { "path": { "type": "string", "description": "Request path associated with this issue." }, "code": { "type": "string", "description": "Machine-readable issue code." }, "message": { "type": "string", "description": "Sanitized human-readable issue message." } }, "required": [ "path", "code", "message" ], "additionalProperties": false }, "ErrorResponse": { "description": "Sanitized REST error envelope.", "type": "object", "properties": { "ok": { "type": "boolean", "const": false, "description": "Always false for an error response." }, "code": { "type": "string", "enum": [ "invalid_request", "unauthorized", "forbidden", "feature_disabled", "method_not_allowed", "rate_limited", "stale_preview", "catalog_changed", "session_not_draft", "external_access_error", "request_timeout", "internal_error" ], "description": "Stable machine-readable error category." }, "message": { "type": "string", "description": "Sanitized human-readable error message." }, "issues": { "description": "Field-level request issues when validation fails.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "Request path associated with this issue." }, "code": { "type": "string", "description": "Machine-readable issue code." }, "message": { "type": "string", "description": "Sanitized human-readable issue message." } }, "required": [ "path", "code", "message" ], "additionalProperties": false } }, "featureFlag": { "description": "Feature flag associated with feature_disabled, when any.", "type": "string" } }, "required": [ "ok", "code", "message" ], "additionalProperties": false, "examples": [ { "ok": false, "code": "invalid_request", "message": "Report request validation failed.", "issues": [ { "path": "metrics", "code": "invalid_value", "message": "Unknown report metric revenue." } ] }, { "ok": false, "code": "stale_preview", "message": "Please preview this session again before committing." }, { "ok": false, "code": "catalog_changed", "message": "The catalog changed. Please start again." }, { "ok": false, "code": "session_not_draft", "message": "Session is not a draft." } ] }, "EditBookInfoAction": { "description": "Edit built-in Book-wide information and Book-scoped custom columns for one or more books without changing their identities. This is the REST discriminated-union form; type is explicit.", "type": "object", "properties": { "type": { "type": "string", "const": "edit_book_info", "description": "Canonical public action discriminator." }, "edits": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "bookKey": { "type": "string", "minLength": 1, "description": "The bookKey returned by the Book Report catalog." }, "changes": { "type": "object", "properties": { "title": { "description": "The complete book title. Pass null to remove the override and use the default.", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "author": { "description": "The primary author or pen name. Pass null to remove the override and use the default.", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "publicationDate": { "description": "The publication date in YYYY-MM-DD form. Pass null to remove the override and use the default.", "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "null" } ] }, "series": { "description": "The series name. Pass null to remove the override and use the default.", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "seriesPosition": { "description": "The positive whole-number position of the book within its series. Pass null to remove the override and use the default.", "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "color": { "description": "The Book Report display color. Pass null to remove the override and use the default.", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "coauthor": { "description": "The co-author name or names. Pass null to remove the override and use the default.", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "customAttributes": { "description": "Book-scoped custom column values to set or clear. Custom column values are direct and are never inferred.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "customAttributeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The customAttributeId returned by the Book Report catalog." }, "value": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": ".*\\S.*" }, { "type": "null" } ], "description": "The text value, or null to clear it." } }, "required": [ "customAttributeId", "value" ], "additionalProperties": false } } }, "additionalProperties": false, "minProperties": 1, "description": "At least one built-in or custom-attribute change for this catalog object." } }, "required": [ "bookKey", "changes" ], "additionalProperties": false }, "description": "One or more books and the built-in information to change." } }, "required": [ "type", "edits" ], "additionalProperties": false, "examples": [ { "type": "edit_book_info", "edits": [ { "bookKey": "book-1", "changes": { "title": "Revised title" } } ] } ], "x-bookreport-runtime-constraints": [ "Objects are strict: unknown properties are rejected.", "Arrays declared nonempty by the canonical action schema require at least one item.", "Identifiers declared as UUIDs must be valid UUID strings.", "Null is accepted only where the canonical action uses null to clear an override or custom value.", "Every edit requires at least one built-in change or one custom-attribute change.", "Custom values are trimmed and must contain a non-whitespace character before they can be set; null clears the value." ] }, "EditEditionInfoAction": { "description": "Edit built-in information and Edition-scoped custom columns for one or more individual editions. Custom column values are direct and never inferred. Unset values for built-in fields may be inferred from other editions in the same Book. This is the REST discriminated-union form; type is explicit.", "type": "object", "properties": { "type": { "type": "string", "const": "edit_edition_info", "description": "Canonical public action discriminator." }, "edits": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "editionKey": { "type": "string", "minLength": 1, "description": "The editionKey returned by the Book Report catalog." }, "distributor": { "type": "string", "minLength": 1, "description": "The distributor value returned for this edition by the Book Report catalog." }, "changes": { "type": "object", "properties": { "language": { "description": "The edition language. When it is unset, Book Report may infer it from another edition in the same Book. Pass null to remove the override and use the default.", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "kenpc": { "description": "The positive whole-number Kindle Edition Normalized Page Count. When it is unset, Book Report may infer it from another compatible edition in the same Book. Pass null to remove the override and use the default.", "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "translator": { "description": "The translator name or names. When it is unset, Book Report may infer it from another edition in the same Book. Pass null to remove the override and use the default.", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "editor": { "description": "The editor name or names. When it is unset, Book Report may infer it from another edition in the same Book. Pass null to remove the override and use the default.", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "illustrator": { "description": "The illustrator name or names. When it is unset, Book Report may infer it from another edition in the same Book. Pass null to remove the override and use the default.", "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "customAttributes": { "description": "Edition-scoped custom column values to set or clear. Custom column values are direct and are never inferred.", "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "customAttributeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The customAttributeId returned by the Book Report catalog." }, "value": { "anyOf": [ { "type": "string", "minLength": 1, "pattern": ".*\\S.*" }, { "type": "null" } ], "description": "The text value, or null to clear it." } }, "required": [ "customAttributeId", "value" ], "additionalProperties": false } } }, "additionalProperties": false, "minProperties": 1, "description": "At least one built-in or custom-attribute change for this catalog object." } }, "required": [ "editionKey", "distributor", "changes" ], "additionalProperties": false }, "description": "One or more editions and the built-in information to change." } }, "required": [ "type", "edits" ], "additionalProperties": false, "examples": [ { "type": "edit_edition_info", "edits": [ { "editionKey": "edition-1", "distributor": "Kindle Direct Publishing", "changes": { "language": "English" } } ] } ], "x-bookreport-runtime-constraints": [ "Objects are strict: unknown properties are rejected.", "Arrays declared nonempty by the canonical action schema require at least one item.", "Identifiers declared as UUIDs must be valid UUID strings.", "Null is accepted only where the canonical action uses null to clear an override or custom value.", "Every edit requires at least one built-in change or one custom-attribute change.", "Custom values are trimmed and must contain a non-whitespace character before they can be set; null clears the value." ] }, "AddCustomColumnAction": { "description": "Add a text column that describes either whole Books or individual Editions. This is the REST discriminated-union form; type is explicit.", "type": "object", "properties": { "type": { "type": "string", "const": "add_custom_column", "description": "Canonical public action discriminator." }, "customAttributeId": { "description": "Optional stable customAttributeId. Omit it to let Book Report create one.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 1, "description": "Trimmed nonblank custom-column name. archived is reserved, case-insensitively.", "pattern": ".*\\S.*", "not": { "pattern": "^\\s*[Aa][Rr][Cc][Hh][Ii][Vv][Ee][Dd]\\s*$" } }, "describes": { "type": "string", "enum": [ "book", "edition" ], "description": "Whether this column stores one value for each Book or one value for each Edition." } }, "required": [ "type", "name", "describes" ], "additionalProperties": false, "examples": [ { "type": "add_custom_column", "customAttributeId": "35f2dc77-1b19-4c48-a213-8ed6f6f8155e", "name": "Narrator", "describes": "edition" } ], "x-bookreport-runtime-constraints": [ "Objects are strict: unknown properties are rejected.", "Arrays declared nonempty by the canonical action schema require at least one item.", "Identifiers declared as UUIDs must be valid UUID strings.", "Null is accepted only where the canonical action uses null to clear an override or custom value.", "The name is trimmed and must contain a non-whitespace character.", "The name archived is reserved, matched case-insensitively after trimming." ] }, "RemoveCustomColumnAction": { "description": "Remove a custom column and all of its saved values. This is the REST discriminated-union form; type is explicit.", "type": "object", "properties": { "type": { "type": "string", "const": "remove_custom_column", "description": "Canonical public action discriminator." }, "customAttributeId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "description": "The customAttributeId returned by the Book Report catalog." } }, "required": [ "type", "customAttributeId" ], "additionalProperties": false, "examples": [ { "type": "remove_custom_column", "customAttributeId": "35f2dc77-1b19-4c48-a213-8ed6f6f8155e" } ], "x-bookreport-runtime-constraints": [ "Objects are strict: unknown properties are rejected.", "Arrays declared nonempty by the canonical action schema require at least one item.", "Identifiers declared as UUIDs must be valid UUID strings.", "Null is accepted only where the canonical action uses null to clear an override or custom value." ] }, "SetBookArchivedAction": { "description": "Set whether one or more books are archived. This is the REST discriminated-union form; type is explicit.", "type": "object", "properties": { "type": { "type": "string", "const": "set_book_archived", "description": "Canonical public action discriminator." }, "edits": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "bookKey": { "type": "string", "minLength": 1, "description": "The bookKey returned by the Book Report catalog." }, "archived": { "type": "boolean", "description": "True to archive the book; false to unarchive it." } }, "required": [ "bookKey", "archived" ], "additionalProperties": false }, "description": "One or more books and whether each should be archived." } }, "required": [ "type", "edits" ], "additionalProperties": false, "examples": [ { "type": "set_book_archived", "edits": [ { "bookKey": "book-1", "archived": true } ] } ], "x-bookreport-runtime-constraints": [ "Objects are strict: unknown properties are rejected.", "Arrays declared nonempty by the canonical action schema require at least one item.", "Identifiers declared as UUIDs must be valid UUID strings.", "Null is accepted only where the canonical action uses null to clear an override or custom value." ] }, "GroupBooksAction": { "description": "Group duplicate Books and choose which Book supplies the grouped Book information. This is the REST discriminated-union form; type is explicit.", "type": "object", "properties": { "type": { "type": "string", "const": "group_books", "description": "Canonical public action discriminator." }, "groups": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "bookKeys": { "minItems": 2, "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "The distinct bookKey values of every Book that should become one grouped Book.", "uniqueItems": true }, "bookInfoFromBookKey": { "type": "string", "minLength": 1, "description": "The bookKey whose information the grouped Book should use. It must be one of bookKeys." } }, "required": [ "bookKeys", "bookInfoFromBookKey" ], "additionalProperties": false, "description": "At least two distinct Book keys that will form one group. bookInfoFromBookKey must be a member of bookKeys.", "x-bookreport-member-field": "bookInfoFromBookKey", "x-bookreport-member-of": "bookKeys" }, "description": "One or more groups of Books to combine." } }, "required": [ "type", "groups" ], "additionalProperties": false, "examples": [ { "type": "group_books", "groups": [ { "bookKeys": [ "book-1", "book-2" ], "bookInfoFromBookKey": "book-1" } ] } ], "x-bookreport-runtime-constraints": [ "Objects are strict: unknown properties are rejected.", "Arrays declared nonempty by the canonical action schema require at least one item.", "Identifiers declared as UUIDs must be valid UUID strings.", "Null is accepted only where the canonical action uses null to clear an override or custom value.", "Every group requires at least two distinct bookKeys.", "bookInfoFromBookKey must be one of the group’s bookKeys." ] }, "MoveEditionsAction": { "description": "Move one or more editions into another Book. This is the REST discriminated-union form; type is explicit.", "type": "object", "properties": { "type": { "type": "string", "const": "move_editions", "description": "Canonical public action discriminator." }, "moves": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "editionKey": { "type": "string", "minLength": 1, "description": "The editionKey of the Edition to move." }, "distributor": { "type": "string", "minLength": 1, "description": "The distributor value returned for this edition by the Book Report catalog." }, "bookKey": { "type": "string", "minLength": 1, "description": "The bookKey of the Book the Edition should move to." } }, "required": [ "editionKey", "distributor", "bookKey" ], "additionalProperties": false }, "description": "One or more editions and the Books they should move to." } }, "required": [ "type", "moves" ], "additionalProperties": false, "examples": [ { "type": "move_editions", "moves": [ { "editionKey": "edition-2", "distributor": "Draft2Digital", "bookKey": "book-1" } ] } ], "x-bookreport-runtime-constraints": [ "Objects are strict: unknown properties are rejected.", "Arrays declared nonempty by the canonical action schema require at least one item.", "Identifiers declared as UUIDs must be valid UUID strings.", "Null is accepted only where the canonical action uses null to clear an override or custom value." ] }, "SeparateEditionsAction": { "description": "Make one or more Editions into separate Books. This is the REST discriminated-union form; type is explicit.", "type": "object", "properties": { "type": { "type": "string", "const": "separate_editions", "description": "Canonical public action discriminator." }, "editions": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "editionKey": { "type": "string", "minLength": 1, "description": "Stable editionKey copied from the targeted Catalog response." }, "distributor": { "type": "string", "minLength": 1, "description": "Edition distributor used to disambiguate the source product." } }, "required": [ "editionKey", "distributor" ], "additionalProperties": false }, "description": "The editionKey values that should each become their own Book." } }, "required": [ "type", "editions" ], "additionalProperties": false, "examples": [ { "type": "separate_editions", "editions": [ { "editionKey": "edition-2", "distributor": "Draft2Digital" } ] } ], "x-bookreport-runtime-constraints": [ "Objects are strict: unknown properties are rejected.", "Arrays declared nonempty by the canonical action schema require at least one item.", "Identifiers declared as UUIDs must be valid UUID strings.", "Null is accepted only where the canonical action uses null to clear an override or custom value." ] }, "ClassifyProductsAction": { "description": "Classify BookFunnel products as books or non-books. Books require a supported format. This is the REST discriminated-union form; type is explicit.", "type": "object", "properties": { "type": { "type": "string", "const": "classify_products", "description": "Canonical public action discriminator." }, "classifications": { "minItems": 1, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "editionKey": { "type": "string", "minLength": 1, "description": "The editionKey returned by the Book Report catalog." }, "distributor": { "type": "string", "minLength": 1, "description": "The distributor value returned for this edition by the Book Report catalog." }, "classification": { "type": "string", "const": "book", "description": "Classify this product as a book." }, "format": { "type": "string", "enum": [ "eBook", "Paperback", "Hardcover", "Audiobook" ], "description": "The book format reported for this product." } }, "required": [ "editionKey", "distributor", "classification", "format" ], "additionalProperties": false }, { "type": "object", "properties": { "editionKey": { "type": "string", "minLength": 1, "description": "The editionKey returned by the Book Report catalog." }, "distributor": { "type": "string", "minLength": 1, "description": "The distributor value returned for this edition by the Book Report catalog." }, "classification": { "type": "string", "const": "non_book", "description": "Classify this product as a non-book." } }, "required": [ "editionKey", "distributor", "classification" ], "additionalProperties": false } ] }, "description": "One or more BookFunnel products to classify." } }, "required": [ "type", "classifications" ], "additionalProperties": false, "examples": [ { "type": "classify_products", "classifications": [ { "editionKey": "product-1", "distributor": "BookFunnel", "classification": "book", "format": "eBook" } ] } ], "x-bookreport-runtime-constraints": [ "Objects are strict: unknown properties are rejected.", "Arrays declared nonempty by the canonical action schema require at least one item.", "Identifiers declared as UUIDs must be valid UUID strings.", "Null is accepted only where the canonical action uses null to clear an override or custom value." ] } } }, "x-generated-by": "server/handlers/externalAccess/openApiSpec.ts" }