{ "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\n## Authentication\n\nFor scripts and tools that access your own account, use an API key. Create one in Book Report Settings to get started immediately.\n\nFor apps that other people connect to, use [OAuth](#tag/oauth). App creation requires approval: email [hello@getbookreport.com](mailto:hello@getbookreport.com) with your Book Report Account ID and a brief description of what you are building.\n\nBoth methods use the same REST API, account permissions, API eligibility, and account-wide request limit.\n\n## Connecting and updating accounts\n\nThese operations read data already imported into Book Report. They do not initiate or refresh distributor imports.\n\nTo connect or manage publishing, direct sales, or advertising accounts, open [Connect Accounts](https://app.getbookreport.com/connect).\n\nTo import the latest data from connected accounts, open [Update Data](https://app.getbookreport.com/update).\n\nEach page uses the Book Report account signed in to the browser. For shared data, send the link to the author whose accounts need connecting or updating.\n\n## Requests\n\nSend your API key or OAuth access token in the Authorization: Bearer header. Management operations require an API key with management access or the data:manage OAuth scope.\n\nThe public API allows 3,600 requests per account per clock hour across all of that account’s API keys and OAuth connections. A 429 response includes Retry-After.\n\nAll /api/v1/* operations support public browser CORS, including Authorization and OPTIONS preflight. Browser apps can send OAuth access tokens without cookies, or use an API key intentionally supplied by the account owner. Never embed reusable credentials in public source.\n\nThe REST operations live under /api/v1, use JSON results, expose X-Api-Version: 1, and return sanitized ErrorResponse envelopes for HTTP failures." }, "servers": [ { "url": "https://app.getbookreport.com", "description": "Production" } ], "security": [ { "ApiKeyBearerAuth": [] }, { "PartnerOAuth": [ "reports:read" ] } ], "tags": [ { "name": "Reports", "description": "A 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. For read-through, earnings per reader, and per-book EPR contributions, use POST /api/v1/series. Each result includes series totals and per-book read-through and earnings. Use series to select one or more series, unitTypes to choose free downloads, KU reads, or other units, and includeMidSeriesStarters to include readers who start later.\n\nThese operations read data already imported into Book Report. They do not initiate or refresh distributor imports.\n\nTo connect or manage publishing, direct sales, or advertising accounts, open [Connect Accounts](https://app.getbookreport.com/connect).\n\nTo import the latest data from connected accounts, open [Update Data](https://app.getbookreport.com/update).\n\nEach page uses the Book Report account signed in to the browser. For shared data, send the link to the author whose accounts need connecting or updating.\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." }, { "name": "Series", "description": "Estimated reader progression, earnings per reader, and per-book contributions for any selection of series." }, { "name": "Discovery", "description": "Account-available report vocabulary and filter values." }, { "name": "Account", "description": "Safe report defaults and connected-source context." }, { "name": "Catalog", "description": "Book 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\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." }, { "name": "Catalog editing", "description": "Catalog 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\n## 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." }, { "name": "Ads", "description": "Latest imported Meta ad copy, creative previews, and links. Look up ad details separately from performance reports." }, { "name": "Ad destinations", "description": "Current Book or Edition links and effective attributes for imported Ad Destinations." }, { "name": "OAuth", "description": "Let users connect their Book Report account to your app and give it access to their sales and catalog data.\n\n## Setup\n\nTo request access, email [hello@getbookreport.com](mailto:hello@getbookreport.com) with your Book Report Account ID and a brief description of what you'd like to build. Approval is for app registration; customers do not need separate approval.\n\nOnce approved, open Settings > Data Access > Partner Apps and create an app. Choose the type that matches how your app runs:\n\n- **App with server**: choose this if your app has a backend. Keep the client secret and tokens on your server.\n- **Browser app**: choose this if your app runs entirely in the browser, without a backend. It connects using its client ID and PKCE.\n\nRegister your full callback URL, including its path, port, and any query parameters. The redirect_uri in each request must match it exactly. Use HTTPS, or HTTP on localhost or a loopback address during development.\n\nFor an App with server, save the client secret when it is displayed. You can replace it later with Rotate client secret in Settings. Rotation takes effect immediately and keeps existing connections active.\n\nBoth app types use the authorization code flow with PKCE (S256). The examples below use https://app.getbookreport.com as the API origin.\n\n## Browser app example\n\nSet CLIENT_ID to the ID from Settings and REDIRECT_URI to your registered callback URL. Call connect() when the user chooses to connect Book Report. This example uses the browser's Web Crypto API to generate state and a PKCE challenge for each attempt, then redirects the user to Book Report.\n\n```js\nconst ORIGIN = \"https://app.getbookreport.com\";\nconst CLIENT_ID = 'YOUR_CLIENT_ID';\nconst REDIRECT_URI = 'http://localhost:5173/callback';\nconst TX_KEY = 'bookreport.oauth.transaction';\nconst base64url = bytes => btoa(String.fromCharCode(...bytes))\n .replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '');\nconst random = () => base64url(crypto.getRandomValues(new Uint8Array(32)));\n\nasync function connect(manage = false) {\n const state = random();\n const verifier = random();\n const challenge = base64url(new Uint8Array(await crypto.subtle.digest(\n 'SHA-256', new TextEncoder().encode(verifier))));\n sessionStorage.setItem(TX_KEY, JSON.stringify({ state, verifier, createdAt: Date.now() }));\n const query = new URLSearchParams({\n response_type: 'code', client_id: CLIENT_ID, redirect_uri: REDIRECT_URI,\n scope: manage ? 'reports:read data:manage' : 'reports:read',\n state, code_challenge: challenge, code_challenge_method: 'S256',\n });\n location.assign(ORIGIN + '/oauth/partner/authorize?' + query);\n}\n\n// Run once on the callback page. Do not load third-party scripts on this page.\nasync function finishConnection() {\n const query = new URLSearchParams(location.search);\n const tx = JSON.parse(sessionStorage.getItem(TX_KEY) || 'null');\n sessionStorage.removeItem(TX_KEY);\n // Remove the OAuth response from history before doing any network work.\n const clean = new URL(REDIRECT_URI);\n history.replaceState(null, '', clean.pathname + clean.search);\n if (!tx || !query.get('state') || query.get('state') !== tx.state ||\n Date.now() - tx.createdAt > 10 * 60 * 1000) {\n throw new Error('Connection request expired or did not match. Start again.');\n }\n if (query.get('error') === 'access_denied') return null; // User cancelled.\n if (query.has('error') || !query.get('code')) throw new Error('Connection failed. Start again.');\n const response = await fetch(ORIGIN + '/oauth/partner/token', {\n method: 'POST', credentials: 'omit',\n headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n body: new URLSearchParams({ grant_type: 'authorization_code',\n client_id: CLIENT_ID, code: query.get('code'), redirect_uri: REDIRECT_URI,\n code_verifier: tx.verifier }),\n });\n const result = await response.json();\n if (!response.ok) throw new Error(result.error || 'Token exchange failed');\n return { ...result, expiresAt: Date.now() + result.expires_in * 1000 };\n}\n\n// Keep tokens in memory; reconnect after a page reload. To retain a browser\n// session, choose storage deliberately: persisted tokens are exposed to XSS.\nlet tokens = null;\nlet refreshInFlight = null;\nasync function refresh() {\n if (!tokens) throw new Error('Connect Book Report first');\n if (refreshInFlight) return refreshInFlight;\n let receivedThrottle = false;\n refreshInFlight = (async () => {\n const response = await fetch(ORIGIN + '/oauth/partner/token', {\n method: 'POST', credentials: 'omit',\n headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n body: new URLSearchParams({ grant_type: 'refresh_token',\n client_id: CLIENT_ID, refresh_token: tokens.refresh_token }),\n });\n if (response.status === 429) {\n receivedThrottle = true; // This response guarantees no token was consumed.\n const error = new Error('Book Report is busy. Wait before retrying.');\n error.retryAfter = Number(response.headers.get('Retry-After') || 60);\n throw error; // Caller waits error.retryAfter seconds, then may retry.\n }\n const next = await response.json();\n if (!response.ok) {\n tokens = null;\n throw new Error('Reconnect Book Report (' + next.error + ')');\n }\n tokens = { ...next, expiresAt: Date.now() + next.expires_in * 1000 };\n })();\n try {\n await refreshInFlight;\n } catch (error) {\n // The server may have spent this refresh token even if its response was lost.\n if (!receivedThrottle) tokens = null;\n throw error;\n } finally {\n refreshInFlight = null;\n }\n}\n\n// After the callback: tokens = await finishConnection(). Read the scope before\n// enabling editing controls. A user may grant View instead of View and manage.\nasync function loadAccountContext() {\n if (!tokens) throw new Error('Connect Book Report first');\n if (tokens.expiresAt < Date.now() + 60000) await refresh();\n const response = await fetch(ORIGIN + '/api/v1/account-context', {\n credentials: 'omit', headers: { Authorization: 'Bearer ' + tokens.access_token },\n });\n if (!response.ok) throw new Error('Book Report API returned ' + response.status);\n return response.json();\n}\n\nasync function disconnect() {\n if (!tokens) return;\n const response = await fetch(ORIGIN + '/oauth/partner/revoke', {\n method: 'POST', credentials: 'omit',\n headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n body: new URLSearchParams({ client_id: CLIENT_ID, token: tokens.refresh_token }),\n });\n if (!response.ok) throw new Error('Disconnect failed. Retry or revoke in Book Report Settings.');\n tokens = null;\n}\n```\n\n## App with server example\n\nUse the same state and PKCE flow as the browser example. Keep the pending connection in your app's authenticated server session, linked to the user who started it. Use a secure HttpOnly session cookie and check state when handling the callback, including cancellation. Then clear the pending connection and exchange the code on your server.\n\nFor Node.js, generate state and the PKCE verifier with crypto.randomBytes(32).toString('base64url'). Create the challenge with crypto.createHash('sha256').update(verifier).digest('base64url'). Send both client_secret and code_verifier when exchanging the code:\n\n```js\nconst response = await fetch(ORIGIN + '/oauth/partner/token', {\n method: 'POST',\n headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n body: new URLSearchParams({\n grant_type: 'authorization_code', client_id: process.env.BOOK_REPORT_CLIENT_ID,\n client_secret: process.env.BOOK_REPORT_CLIENT_SECRET, code,\n redirect_uri: REDIRECT_URI, code_verifier: transaction.verifier,\n }),\n});\nconst result = await response.json();\nif (!response.ok) throw new Error(result.error || 'Token exchange failed');\n// Save result.access_token, result.refresh_token, result.scope and expires_in\n// together for the local user bound to transaction. Never log these values.\n```\n\nTo refresh tokens or disconnect an App with server, add client_id and client_secret to the form fields shown in the browser example. You can also send these credentials using HTTP Basic authentication instead of form fields. Store tokens encrypted against the user who started the connection, and keep secrets, tokens, and authorization codes out of logs.\n\n## Permissions\n\nThe scope parameter is a space-separated list:\n\n| Permission | `scope` |\n| --- | --- |\n| View | `reports:read` |\n| View and manage | `reports:read data:manage` |\n\nThe user can choose View when your app requests View and manage. Check scope in the token response before enabling editing controls. Management endpoints and targeted catalog reads require both reports:read and data:manage. To request different permissions, send the user through authorization again.\n\nEach Book Report account has one connection per app. Reconnecting with the same permission keeps existing tokens active. Changing permission invalidates existing tokens and pending authorization codes. If the user cancels, the callback receives error=access_denied and the original state.\n\n## Tokens and disconnection\n\nSend the access token in the Authorization header as `Bearer ` when calling the API.\n\nAccess tokens last one hour. Use the refresh token to get a new access token and refresh token, and save the new pair together. Each refresh token expires after 90 days and can be used once. A successful refresh starts a new 90-day period.\n\nRun one refresh at a time for each connection, including across server workers. Reusing an old refresh token revokes the connection and its newest tokens. If a refresh response is lost, ask the user to reconnect. If you receive a 429 response, keep the refresh token and wait for the Retry-After period before trying again.\n\nAuthorization codes last ten minutes and can be exchanged once.\n\nTo disconnect an account, send either token to /oauth/partner/revoke and delete the tokens stored by your app. Users can also disconnect in Book Report Settings. Disabling your app in Settings disconnects all its users.\n\n## Errors and rate limits\n\nOAuth error responses contain error and, when available, error_description.\n\n| Error | What to do |\n| --- | --- |\n| invalid_request | Check the request fields against the endpoint below. |\n| invalid_client | Check the client ID and, for an App with server, its secret. |\n| invalid_grant | Start a new connection. The code, PKCE verifier, redirect URL, or refresh token was rejected. |\n| invalid_scope | Use one of the scope values in the permissions table above. |\n\nFor API requests, a 401 means the access token is invalid or expired. Refresh it once, then ask the user to reconnect if that fails. A 403 means the request needs additional permissions or the account needs API access; check the error response for the cause.\n\nOAuth endpoints have these limits per IP address in a 15-minute window:\n\n| Endpoint | Requests |\n| --- | --- |\n| Authorization | 100 |\n| Token exchange and refresh | 1,200 |\n| Revocation | 1,200 |\n\nOn a 429 response, wait for the number of seconds in Retry-After before trying again. An App with server shares these limits across users connecting from that server, so spread refreshes through the hour. API requests use the account-wide limit described in Requests.\n" } ], "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": "offer_price_original_currency", "label": "Offer Price (Original Currency)", "type": "Transaction", "description": "The offer price reported by the distributor, in its original currency, without conversion or price bands. The reported price may be an average and may exclude tax. Missing prices or currencies appear as Not set." }, { "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." }, { "key": "offer_price_original_currency", "label": "Offer Price (Original Currency)", "type": "Transaction", "description": "The offer price reported by the distributor, in its original currency, without conversion or price bands. The reported price may be an average and may exclude tax. Missing prices or currencies appear as Not set." } ], "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 total normalized pages read or listened through Kindle Unlimited and Kindle+. Includes reports whose reading/listening split is unavailable." }, { "key": "ebook_pages_read", "label": "eBook Pages Read", "isMoney": false, "type": "Quantity Metrics", "description": "Pages assigned to ebook editions. Includes combined totals from older or unsplit reports where reading and listening are not available separately." }, { "key": "audio_pages_listened", "label": "Audio Pages Listened", "isMoney": false, "type": "Quantity Metrics", "description": "Kindle+ listening activity, measured in normalized pages. Older or unsplit reports may show zero here even when listening occurred." }, { "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" } }, "security": [ { "ApiKeyBearerAuth": [] }, { "PartnerOAuth": [ "reports:read" ] } ] } }, "/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." }, { "key": "offer_price_original_currency", "label": "Offer Price (Original Currency)", "type": "Transaction", "description": "The offer price reported by the distributor, in its original currency, without conversion or price bands. The reported price may be an average and may exclude tax. Missing prices or currencies appear as Not set." } ], "security": [ { "ApiKeyBearerAuth": [] }, { "PartnerOAuth": [ "reports:read" ] } ] } }, "/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.\n\nTo connect or manage publishing, direct sales, or advertising accounts, open [Connect Accounts](https://app.getbookreport.com/connect).\n\nTo import the latest data from connected accounts, open [Update Data](https://app.getbookreport.com/update).\n\nEach page uses the Book Report account signed in to the browser. For shared data, send the link to the author whose accounts need connecting or updating.", "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" } }, "security": [ { "ApiKeyBearerAuth": [] }, { "PartnerOAuth": [ "reports:read" ] } ] } }, "/api/v1/account-updates": { "get": { "operationId": "getAccountUpdates", "tags": [ "Account" ], "summary": "Get the latest update time for each connected account", "description": "Returns when Book Report last successfully updated the data for each connected account.\n\nTo connect or manage publishing, direct sales, or advertising accounts, open [Connect Accounts](https://app.getbookreport.com/connect).\n\nTo import the latest data from connected accounts, open [Update Data](https://app.getbookreport.com/update).\n\nEach page uses the Book Report account signed in to the browser. For shared data, send the link to the author whose accounts need connecting or updating.\n\nYour application decides how old is too old.\n\nA null timestamp means no update time is available for that account. This endpoint reads update times; it does not refresh data.", "responses": { "200": { "description": "Connected accounts and their last update times.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountUpdatesResponse" }, "examples": { "connectedAccounts": { "summary": "Update times for connected accounts", "value": { "accounts": [ { "accountId": "BR-ABC-234", "distributor": "Kindle Direct Publishing", "lastUpdatedAt": "2026-10-22T12:05:00.000Z" }, { "accountId": "BR-ABC-234", "platform": "amazon", "account": { "id": "123456789", "name": "Example Author Ads" }, "lastUpdatedAt": "2026-10-22T11:00:00.000Z" }, { "accountId": "BR-ABC-234", "platform": "meta", "account": { "id": "987654321", "name": "Example Author Ads" }, "lastUpdatedAt": null }, { "accountId": "BR-DEF-567", "distributor": "Kobo Writing Life", "lastUpdatedAt": "2026-10-20T09:00:00.000Z" } ] } } } } } }, "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" } }, "security": [ { "ApiKeyBearerAuth": [] }, { "PartnerOAuth": [ "reports:read" ] } ] } }, "/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" } }, "security": [ { "ApiKeyBearerAuth": [] }, { "PartnerOAuth": [ "reports:read" ] } ] } }, "/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. Daily (`date`) breakdowns support up to 100 days, including both start and end, and must start in 2018 or later. For longer or earlier ranges, request `month` or `year`; an unsupported daily request returns a validation error. 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." }, { "key": "offer_price_original_currency", "label": "Offer Price (Original Currency)", "type": "Transaction", "description": "The offer price reported by the distributor, in its original currency, without conversion or price bands. The reported price may be an average and may exclude tax. Missing prices or currencies appear as Not set." } ], "security": [ { "ApiKeyBearerAuth": [] }, { "PartnerOAuth": [ "reports:read" ] } ] } }, "/api/v1/series": { "post": { "operationId": "getSeriesAnalytics", "tags": [ "Series" ], "summary": "Get series analytics", "description": "Get read-through and earnings per reader (EPR) for your series. Each result includes series totals and per-book calculations. The books array contains one entry per series position, ordered by position. Books and editions assigned to the same position are combined.\n\nStart with a date range, for example { \"range\": \"all_time\" }. To select series, call GET /api/v1/report-filter-values with `filter=series`, then copy the selected `values[].value` strings into `series`. These values are currently series titles, for example `{\"series\": [\"Harbour mysteries\"]}`. Omit `series` to include all series. Date and currency conventions match POST /api/v1/report.\n\nChoose which readers to include with unitTypes: free downloads (free), estimated Kindle Unlimited reads (ku), and other units such as paid sales (other). All three are included by default. scope shows the observed unit counts and which categories your request includes.\n\nThe `readers` count estimates how many people entered the series at your chosen starting book, usually Book 1. Each included sale, free download, or estimated KU read of that book counts as a start. Distributors do not provide individual reader histories, so these are estimates from the activity you can observe. By default, the calculation treats a series as a funnel: readers begin at your starting book, and some continue to each later book.\n\nRead-through estimates how far readers progress through the series and where they drop off. Cumulative read-through (`readThrough`) measures the percentage who reach each book from the starting book. Book-to-book read-through (`bookToBookReadThrough`) measures the percentage who continue from the previous book. If a book has no units in the selected period, that comparison uses the previous book with units.\n\nEarnings per reader (`earningsPerReader`) estimates how much you earn, on average, as one new reader moves through the series. Each book contributes according to the proportion of readers who reach it and its average earnings per unit. If 60% reach a book that earns $3 per unit, that book contributes $1.80 per starting reader. Add those contributions across the series to get EPR. Each book's contribution is returned as `eprContribution`.\n\nMid-series starters are units that don't fit the assumption that readers begin at your starting book and continue in order. If Book 1 has 100 units but Book 2 has 150, those extra 50 units cannot all be attributed to the 100 starts in this report. They may come from people who entered later, or who bought Book 1 before your chosen date range. The available sales data cannot tell those cases apart.\n\nBy default, `includeMidSeriesStarters` is `false`, and those extra units are excluded from the estimate. In this example, Book 2 counts as 100 units and contributes two-thirds of its observed earnings. The reduction also carries forward to later books. This keeps EPR focused on the value of a new reader at your chosen starting book, without crediting that reader with earnings that appear to have come from elsewhere.\n\nSet it to `true` to include all observed activity for your selected unit types. Read-through can then exceed 100%, and EPR may overstate what a new reader at the starting book is worth. If your series has another entry point, use `startFromBook` to estimate the value of a reader who begins there. For example, setting it to 7 starts the calculation at Book 7 and leaves out Books 1 through 6.\n\nFor a comparison within each series, add attributes: [\"marketplace\"]. This returns the combined Overall result followed by separate marketplace results. Set includeDetails to true for the observed numbers and adjustments behind each result.\n\nRead notices for missing page counts, excluded series, or estimates based on few readers.\n\nFollow rowWindow.nextOffset to get the next page. Each row keeps its complete books array; scope summarizes all selected series from the requested starting book.", "requestBody": { "required": true, "description": "A date range, optional series selection, and settings for which readers to include.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeriesAnalyticsRequest" }, "examples": { "allSeries": { "summary": "Read-through and earnings per reader for all series", "value": { "range": "all_time" } }, "readerInclusion": { "summary": "Exclude free downloads and estimated mid-series starters", "value": { "range": "all_time", "series": [ "Harbour mysteries" ], "unitTypes": [ "ku", "other" ], "includeMidSeriesStarters": false, "includeDetails": true, "currency": "USD" } }, "compareMarketplaces": { "summary": "Compare marketplaces for one series", "value": { "range": "all_time", "series": [ "Harbour mysteries" ], "attributes": [ "marketplace" ], "currency": "USD" } }, "explainEarnings": { "summary": "Include the numbers behind one series' results", "value": { "start": "2026-01-01", "end": "2026-06-30", "series": [ "Harbour mysteries" ], "includeDetails": true } } } } } }, "responses": { "200": { "description": "Series totals and ordered per-book calculations, with both read-through rates, earnings per reader, resolved settings, scope, notices, and pagination. REST and MCP return the same JSON structure.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeriesAnalyticsResponse" }, "examples": { "allSeries": { "summary": "300 starts, $800 earnings, and $2.67 EPR with both read-through rates", "value": { "meta": { "start": "2008-01-01", "end": "2026-06-30", "currency": "USD", "startFromBook": 1, "unitTypes": [ "free", "ku", "other" ], "includeMidSeriesStarters": false, "attributes": [], "generatedAt": "2026-06-30T12:00:00Z" }, "columns": [ { "key": "series", "label": "Series", "type": "string", "description": "Series name." }, { "key": "readers", "label": "Readers", "description": "Estimated starts at Book 1.", "type": "number", "unit": "units" }, { "key": "earningsPerReader", "label": "Earnings per reader", "description": "Earnings per estimated starting reader.", "type": "number", "unit": "currency", "currency": "USD" }, { "key": "earnings", "label": "Earnings", "description": "Earnings attributed to readers continuing in order.", "type": "number", "unit": "currency", "currency": "USD" }, { "key": "units", "label": "Units", "description": "Units attributed to readers continuing in order.", "type": "number", "unit": "units" }, { "key": "bookCount", "label": "Books", "description": "Included book positions.", "type": "number" }, { "key": "books", "label": "Books", "type": "array", "description": "Ordered per-book results; bookColumns describes the fields." } ], "bookColumns": [ { "key": "position", "label": "Book", "description": "Position in the series.", "type": "number" }, { "key": "units", "label": "Units", "description": "Units at this position.", "type": "number", "unit": "units" }, { "key": "readThrough", "label": "Cumulative read-through", "description": "Percentage continuing from Book 1.", "type": "number", "unit": "percent" }, { "key": "bookToBookReadThrough", "label": "Book-to-book read-through", "description": "Percentage continuing from the preceding book.", "type": "number", "unit": "percent" }, { "key": "earningsPerUnit", "label": "Earnings per unit", "description": "Observed earnings divided by observed units.", "type": "number", "unit": "currency", "currency": "USD" }, { "key": "eprContribution", "label": "EPR contribution", "description": "This book's contribution to earnings per reader.", "type": "number", "unit": "currency", "currency": "USD" } ], "rows": [ { "series": "Harbour mysteries", "breakdown": null, "readers": 300, "earningsPerReader": 2.6666666666666665, "earnings": 800, "units": 480, "bookCount": 3, "books": [ { "position": 1, "units": 300, "readThrough": 100, "bookToBookReadThrough": 100, "earningsPerUnit": 0.6666666666666666, "eprContribution": 0.6666666666666666 }, { "position": 2, "units": 120, "readThrough": 40, "bookToBookReadThrough": 40, "earningsPerUnit": 3, "eprContribution": 1.2 }, { "position": 3, "units": 60, "readThrough": 20, "bookToBookReadThrough": 50, "earningsPerUnit": 4, "eprContribution": 0.8 } ] } ], "scope": { "startFromBook": 1, "unitTypes": [ { "type": "free", "units": 200, "included": true }, { "type": "ku", "units": 80, "included": true }, { "type": "other", "units": 200, "included": true } ], "midSeriesStarters": { "included": false, "units": 0, "percent": 0 } }, "notices": [], "rowWindow": { "totalRows": 1, "returnedRows": 1, "limit": 100, "offset": 0, "hasMore": false, "nextOffset": null } } }, "readerInclusion": { "summary": "200 free downloads excluded; 30 estimated mid-series units excluded; $7 EPR", "value": { "meta": { "start": "2008-01-01", "end": "2026-06-30", "currency": "USD", "startFromBook": 1, "unitTypes": [ "ku", "other" ], "includeMidSeriesStarters": false, "attributes": [], "generatedAt": "2026-06-30T12:00:00Z" }, "columns": [ { "key": "series", "label": "Series", "type": "string", "description": "Series name." }, { "key": "readers", "label": "Readers", "description": "Estimated starts at Book 1.", "type": "number", "unit": "units" }, { "key": "earningsPerReader", "label": "Earnings per reader", "description": "Earnings per estimated starting reader.", "type": "number", "unit": "currency", "currency": "USD" }, { "key": "earnings", "label": "Earnings", "description": "Earnings attributed to readers continuing in order.", "type": "number", "unit": "currency", "currency": "USD" }, { "key": "units", "label": "Units", "description": "Units attributed to readers continuing in order.", "type": "number", "unit": "units" }, { "key": "bookCount", "label": "Books", "description": "Included book positions.", "type": "number" }, { "key": "books", "label": "Books", "type": "array", "description": "Ordered per-book results; bookColumns describes the fields." } ], "bookColumns": [ { "key": "position", "label": "Book", "description": "Position in the series.", "type": "number" }, { "key": "units", "label": "Units", "description": "Units at this position.", "type": "number", "unit": "units" }, { "key": "readThrough", "label": "Cumulative read-through", "description": "Percentage continuing from Book 1.", "type": "number", "unit": "percent" }, { "key": "bookToBookReadThrough", "label": "Book-to-book read-through", "description": "Percentage continuing from the preceding book.", "type": "number", "unit": "percent" }, { "key": "earningsPerUnit", "label": "Earnings per unit", "description": "Observed earnings divided by observed units.", "type": "number", "unit": "currency", "currency": "USD" }, { "key": "eprContribution", "label": "EPR contribution", "description": "This book's contribution to earnings per reader.", "type": "number", "unit": "currency", "currency": "USD" } ], "rows": [ { "series": "Harbour mysteries", "breakdown": null, "readers": 100, "earningsPerReader": 7, "earnings": 700, "units": 250, "bookCount": 3, "books": [ { "position": 1, "units": 100, "readThrough": 100, "bookToBookReadThrough": 100, "earningsPerUnit": 2, "eprContribution": 2, "details": { "observedUnits": 100, "observedEarnings": 200, "inOrderUnits": 100, "inOrderEarnings": 200 } }, { "position": 2, "units": 100, "readThrough": 100, "bookToBookReadThrough": 100, "earningsPerUnit": 3, "eprContribution": 3, "details": { "observedUnits": 120, "observedEarnings": 360, "inOrderUnits": 100, "inOrderEarnings": 300 } }, { "position": 3, "units": 50, "readThrough": 50, "bookToBookReadThrough": 50, "earningsPerUnit": 4, "eprContribution": 2, "details": { "observedUnits": 60, "observedEarnings": 240, "inOrderUnits": 50, "inOrderEarnings": 200 } } ], "details": { "observedUnits": 280, "observedEarnings": 800, "inOrderUnits": 250, "inOrderEarnings": 700, "inOrderEarningsPercent": 87.5, "adjustments": [ { "start": 2, "end": 3, "prevPosition": 1, "prevRawUnits": 100, "rawUnits": 120, "prevEffectiveUnits": 100, "effectiveUnits": 100 } ] } } ], "scope": { "startFromBook": 1, "unitTypes": [ { "type": "free", "units": 200, "included": false }, { "type": "ku", "units": 80, "included": true }, { "type": "other", "units": 200, "included": true } ], "midSeriesStarters": { "included": false, "units": 30, "percent": 10.714285714285714 } }, "notices": [], "rowWindow": { "totalRows": 1, "returnedRows": 1, "limit": 100, "offset": 0, "hasMore": false, "nextOffset": null } } }, "compareMarketplaces": { "summary": "A combined series result and its marketplace comparisons", "value": { "meta": { "start": "2008-01-01", "end": "2026-06-30", "currency": "USD", "startFromBook": 1, "unitTypes": [ "free", "ku", "other" ], "includeMidSeriesStarters": false, "attributes": [ "marketplace" ], "generatedAt": "2026-06-30T12:00:00Z" }, "columns": [ { "key": "series", "label": "Series", "type": "string", "description": "Series name." }, { "key": "breakdown.label", "label": "Marketplace", "type": "string", "description": "Comparison group; null breakdown means Overall." }, { "key": "readers", "label": "Readers", "description": "Estimated starts at Book 1.", "type": "number", "unit": "units" }, { "key": "earningsPerReader", "label": "Earnings per reader", "description": "Earnings per estimated starting reader.", "type": "number", "unit": "currency", "currency": "USD" }, { "key": "earnings", "label": "Earnings", "description": "Earnings attributed to readers continuing in order.", "type": "number", "unit": "currency", "currency": "USD" }, { "key": "units", "label": "Units", "description": "Units attributed to readers continuing in order.", "type": "number", "unit": "units" }, { "key": "bookCount", "label": "Books", "description": "Included book positions.", "type": "number" }, { "key": "books", "label": "Books", "type": "array", "description": "Ordered per-book results; bookColumns describes the fields." } ], "bookColumns": [ { "key": "position", "label": "Book", "description": "Position in the series.", "type": "number" }, { "key": "units", "label": "Units", "description": "Units at this position.", "type": "number", "unit": "units" }, { "key": "readThrough", "label": "Cumulative read-through", "description": "Percentage continuing from Book 1.", "type": "number", "unit": "percent" }, { "key": "bookToBookReadThrough", "label": "Book-to-book read-through", "description": "Percentage continuing from the preceding book.", "type": "number", "unit": "percent" }, { "key": "earningsPerUnit", "label": "Earnings per unit", "description": "Observed earnings divided by observed units.", "type": "number", "unit": "currency", "currency": "USD" }, { "key": "eprContribution", "label": "EPR contribution", "description": "This book's contribution to earnings per reader.", "type": "number", "unit": "currency", "currency": "USD" } ], "rows": [ { "series": "Harbour mysteries", "breakdown": null, "readers": 300, "earningsPerReader": 2.6666666666666665, "earnings": 800, "units": 480, "bookCount": 3, "books": [ { "position": 1, "units": 300, "readThrough": 100, "bookToBookReadThrough": 100, "earningsPerUnit": 0.6666666666666666, "eprContribution": 0.6666666666666666 }, { "position": 2, "units": 120, "readThrough": 40, "bookToBookReadThrough": 40, "earningsPerUnit": 3, "eprContribution": 1.2 }, { "position": 3, "units": 60, "readThrough": 20, "bookToBookReadThrough": 50, "earningsPerUnit": 4, "eprContribution": 0.8 } ] }, { "series": "Harbour mysteries", "breakdown": { "attribute": "marketplace", "key": "amazon.com", "label": "Amazon.com" }, "readers": 180, "earningsPerReader": 2.888888888888889, "earnings": 520, "units": 300, "bookCount": 3, "books": [ { "position": 1, "units": 180, "readThrough": 100, "bookToBookReadThrough": 100, "earningsPerUnit": 0.6666666666666666, "eprContribution": 0.6666666666666666 }, { "position": 2, "units": 80, "readThrough": 44.44444444444444, "bookToBookReadThrough": 44.44444444444444, "earningsPerUnit": 3, "eprContribution": 1.3333333333333333 }, { "position": 3, "units": 40, "readThrough": 22.22222222222222, "bookToBookReadThrough": 50, "earningsPerUnit": 4, "eprContribution": 0.8888888888888888 } ] }, { "series": "Harbour mysteries", "breakdown": { "attribute": "marketplace", "key": "amazon.co.uk", "label": "Amazon.co.uk" }, "readers": 120, "earningsPerReader": 2.3333333333333335, "earnings": 280, "units": 180, "bookCount": 3, "books": [ { "position": 1, "units": 120, "readThrough": 100, "bookToBookReadThrough": 100, "earningsPerUnit": 0.6666666666666666, "eprContribution": 0.6666666666666666 }, { "position": 2, "units": 40, "readThrough": 33.33333333333333, "bookToBookReadThrough": 33.33333333333333, "earningsPerUnit": 3, "eprContribution": 1 }, { "position": 3, "units": 20, "readThrough": 16.666666666666664, "bookToBookReadThrough": 50, "earningsPerUnit": 4, "eprContribution": 0.6666666666666666 } ] } ], "scope": { "startFromBook": 1, "unitTypes": [ { "type": "free", "units": 200, "included": true }, { "type": "ku", "units": 80, "included": true }, { "type": "other", "units": 200, "included": true } ], "midSeriesStarters": { "included": false, "units": 0, "percent": 0 } }, "notices": [], "rowWindow": { "totalRows": 3, "returnedRows": 3, "limit": 100, "offset": 0, "hasMore": false, "nextOffset": null } } }, "explainEarnings": { "summary": "The same result with supporting units, earnings, and adjustments", "value": { "meta": { "start": "2026-01-01", "end": "2026-06-30", "currency": "USD", "startFromBook": 1, "unitTypes": [ "free", "ku", "other" ], "includeMidSeriesStarters": false, "attributes": [], "generatedAt": "2026-06-30T12:00:00Z" }, "columns": [ { "key": "series", "label": "Series", "type": "string", "description": "Series name." }, { "key": "readers", "label": "Readers", "description": "Estimated starts at Book 1.", "type": "number", "unit": "units" }, { "key": "earningsPerReader", "label": "Earnings per reader", "description": "Earnings per estimated starting reader.", "type": "number", "unit": "currency", "currency": "USD" }, { "key": "earnings", "label": "Earnings", "description": "Earnings attributed to readers continuing in order.", "type": "number", "unit": "currency", "currency": "USD" }, { "key": "units", "label": "Units", "description": "Units attributed to readers continuing in order.", "type": "number", "unit": "units" }, { "key": "bookCount", "label": "Books", "description": "Included book positions.", "type": "number" }, { "key": "books", "label": "Books", "type": "array", "description": "Ordered per-book results; bookColumns describes the fields." } ], "bookColumns": [ { "key": "position", "label": "Book", "description": "Position in the series.", "type": "number" }, { "key": "units", "label": "Units", "description": "Units at this position.", "type": "number", "unit": "units" }, { "key": "readThrough", "label": "Cumulative read-through", "description": "Percentage continuing from Book 1.", "type": "number", "unit": "percent" }, { "key": "bookToBookReadThrough", "label": "Book-to-book read-through", "description": "Percentage continuing from the preceding book.", "type": "number", "unit": "percent" }, { "key": "earningsPerUnit", "label": "Earnings per unit", "description": "Observed earnings divided by observed units.", "type": "number", "unit": "currency", "currency": "USD" }, { "key": "eprContribution", "label": "EPR contribution", "description": "This book's contribution to earnings per reader.", "type": "number", "unit": "currency", "currency": "USD" } ], "rows": [ { "series": "Harbour mysteries", "breakdown": null, "readers": 300, "earningsPerReader": 2.6666666666666665, "earnings": 800, "units": 480, "bookCount": 3, "books": [ { "position": 1, "units": 300, "readThrough": 100, "bookToBookReadThrough": 100, "earningsPerUnit": 0.6666666666666666, "eprContribution": 0.6666666666666666, "details": { "observedUnits": 300, "observedEarnings": 200, "inOrderUnits": 300, "inOrderEarnings": 200 } }, { "position": 2, "units": 120, "readThrough": 40, "bookToBookReadThrough": 40, "earningsPerUnit": 3, "eprContribution": 1.2, "details": { "observedUnits": 120, "observedEarnings": 360, "inOrderUnits": 120, "inOrderEarnings": 360 } }, { "position": 3, "units": 60, "readThrough": 20, "bookToBookReadThrough": 50, "earningsPerUnit": 4, "eprContribution": 0.8, "details": { "observedUnits": 60, "observedEarnings": 240, "inOrderUnits": 60, "inOrderEarnings": 240 } } ], "details": { "observedUnits": 480, "observedEarnings": 800, "inOrderUnits": 480, "inOrderEarnings": 800, "inOrderEarningsPercent": 100, "adjustments": [] } } ], "scope": { "startFromBook": 1, "unitTypes": [ { "type": "free", "units": 200, "included": true }, { "type": "ku", "units": 80, "included": true }, { "type": "other", "units": 200, "included": true } ], "midSeriesStarters": { "included": false, "units": 0, "percent": 0 } }, "notices": [], "rowWindow": { "totalRows": 1, "returnedRows": 1, "limit": 100, "offset": 0, "hasMore": false, "nextOffset": 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" } }, "security": [ { "ApiKeyBearerAuth": [] }, { "PartnerOAuth": [ "reports:read" ] } ] } }, "/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" } }, "security": [ { "ApiKeyBearerAuth": [] }, { "PartnerOAuth": [ "reports:read", "data:manage" ] } ] } }, "/api/v1/ads/{adId}": { "get": { "operationId": "getAdDetails", "tags": [ "Ads" ], "summary": "Get an ad’s copy, image, thumbnail, and links", "description": "Look up one Meta ad using its stable provider ID. In a report grouped by ad, set `includeFilterKey=true` and use the returned `ad_key` value. The ad must be visible in your advertising reports. Unknown or inaccessible ads return 404.\n\nReturns saved provider details without making a live Meta request. Creative data becomes available after a successful normal import. Media URLs may expire; normal imports refresh them. Failed creative reads retain the last successful snapshot and its timestamp.\n\nCopy arrays contain configured variants. Ad-level performance does not identify which variant was shown or performed best. These are the latest imported details, not historical creatives for a report date range. Links distinguish destination URLs from Facebook posts.", "parameters": [ { "name": "adId", "in": "path", "required": true, "description": "Meta ad ID. Use the ad_key value from a report grouped by ad with filter keys included.", "schema": { "type": "string", "maxLength": 100, "pattern": "^\\d+$", "description": "Meta ad ID. Use the ad_key value from a report grouped by ad with filter keys included." } } ], "responses": { "200": { "description": "Latest imported ad details, with nullable creative metadata and its import timestamp.", "headers": { "X-Api-Version": { "$ref": "#/components/headers/ApiVersion" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdDetailsResponse" }, "examples": { "videoAd": { "summary": "A video ad with a thumbnail and several configured headlines", "value": { "id": "120000000000001", "name": "Harbour mysteries video", "platform": "meta", "account": { "id": "123456789", "name": "Example Author" }, "campaign": { "id": "120000000000000", "name": "Harbour mysteries" }, "links": [ { "url": "https://www.example.com/books/harbour", "type": "destination" } ], "creative": { "id": "987654321", "primaryTexts": [ "A quiet harbour. An unexpected mystery.\nStart reading today." ], "headlines": [ "Discover your next mystery", "Meet the Harbour detectives" ], "imageUrl": null, "thumbnailUrl": "https://www.example.com/media/harbour-thumbnail.jpg", "videoId": "987654320", "updatedAt": "2026-10-20T12:00:00.000Z" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "504": { "$ref": "#/components/responses/RequestTimeout" } }, "security": [ { "ApiKeyBearerAuth": [] }, { "PartnerOAuth": [ "reports:read" ] } ] } }, "/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" } }, "security": [ { "ApiKeyBearerAuth": [] }, { "PartnerOAuth": [ "reports:read", "data:manage" ] } ] }, "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" } }, "security": [ { "ApiKeyBearerAuth": [] }, { "PartnerOAuth": [ "reports:read", "data:manage" ] } ] } }, "/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" } }, "security": [ { "ApiKeyBearerAuth": [] }, { "PartnerOAuth": [ "reports:read", "data:manage" ] } ] }, "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" } }, "security": [ { "ApiKeyBearerAuth": [] }, { "PartnerOAuth": [ "reports:read", "data:manage" ] } ] } }, "/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" } }, "security": [ { "ApiKeyBearerAuth": [] }, { "PartnerOAuth": [ "reports:read", "data:manage" ] } ] } }, "/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" } }, "security": [ { "ApiKeyBearerAuth": [] }, { "PartnerOAuth": [ "reports:read", "data:manage" ] } ] } }, "/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" } }, "security": [ { "ApiKeyBearerAuth": [] }, { "PartnerOAuth": [ "reports:read", "data:manage" ] } ] } }, "/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" } }, "security": [ { "ApiKeyBearerAuth": [] }, { "PartnerOAuth": [ "reports:read", "data:manage" ] } ] } }, "/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" } }, "security": [ { "ApiKeyBearerAuth": [] }, { "PartnerOAuth": [ "reports:read", "data:manage" ] } ] } }, "/oauth/partner/authorize": { "get": { "operationId": "authorizePartner", "tags": [ "OAuth" ], "summary": "Ask a Book Report user to connect their account", "security": [], "description": "Redirect the user here to sign in to Book Report and approve the connection. The redirect_uri must exactly match a registered callback URL. The user can choose View when your app requests View and manage; check scope in the token response.", "parameters": [ { "name": "response_type", "in": "query", "required": true, "schema": { "const": "code" } }, { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "redirect_uri", "in": "query", "required": true, "schema": { "type": "string", "format": "uri", "description": "Your registered callback URL, including its path, port, and query parameters. Book Report uses code, state, error, error_description, and error_uri for the OAuth response; leave these names available in the query string." } }, { "name": "scope", "in": "query", "required": true, "schema": { "type": "string", "description": "Space-separated permissions. Use reports:read for View, or reports:read data:manage for View and manage.", "enum": [ "reports:read", "reports:read data:manage" ] } }, { "name": "state", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code_challenge", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code_challenge_method", "in": "query", "required": true, "schema": { "const": "S256" } } ], "responses": { "200": { "description": "Book Report sign-in or consent page (HTML)." }, "302": { "description": "Return to the exact registered redirect URI with code and state, or error=access_denied and state when cancelled. The authorization code expires after ten minutes and may be exchanged once." }, "400": { "description": "Invalid request shown on Book Report. Invalid client or redirect URI is never redirected." }, "403": { "description": "The account cannot authorize this connection. Book Report shows the eligibility or account error and a return link." }, "429": { "description": "Too many requests. Wait for Retry-After seconds before retrying.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/oauth/partner/token": { "post": { "operationId": "exchangePartnerToken", "tags": [ "OAuth" ], "summary": "Exchange a code or rotate a refresh token", "security": [ {}, { "PartnerClientBasic": [] } ], "description": "Send form-encoded fields. A Browser app sends client_id. An App with server authenticates using either HTTP Basic or client_id and client_secret in the form. Both app types send code_verifier when exchanging an authorization code. For browser requests, use fetch with credentials set to omit.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "oneOf": [ { "type": "object", "required": [ "grant_type", "code", "redirect_uri", "code_verifier" ], "properties": { "grant_type": { "const": "authorization_code" }, "code": { "type": "string" }, "redirect_uri": { "type": "string" }, "code_verifier": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string", "writeOnly": true } } }, { "type": "object", "required": [ "grant_type", "refresh_token" ], "properties": { "grant_type": { "const": "refresh_token" }, "refresh_token": { "type": "string" }, "scope": { "type": "string", "description": "Optional space-separated permissions. Omit to keep the current permissions, or send reports:read to request replacement tokens with View access." }, "client_id": { "type": "string" }, "client_secret": { "type": "string", "writeOnly": true } } } ] } } } }, "responses": { "200": { "description": "Save the access token and replacement refresh token together. scope contains the permissions the user granted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "access_token", "token_type", "expires_in", "refresh_token", "scope" ], "properties": { "access_token": { "type": "string" }, "token_type": { "const": "Bearer" }, "expires_in": { "type": "integer", "minimum": 1, "maximum": 3600 }, "refresh_token": { "type": "string" }, "scope": { "type": "string", "description": "Space-separated scopes the user actually granted." } } } } } }, "400": { "description": "OAuth error. See Errors and rate limits in the OAuth section for how to handle it.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } } } } }, "401": { "description": "OAuth error. See Errors and rate limits in the OAuth section for how to handle it.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } } } } }, "429": { "description": "Too many requests. Wait for Retry-After seconds before retrying.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/oauth/partner/revoke": { "post": { "operationId": "revokePartnerConnection", "tags": [ "OAuth" ], "summary": "Disconnect the app from a Book Report account", "security": [ {}, { "PartnerClientBasic": [] } ], "description": "Use the same client authentication as the token endpoint. Revoking either an access or refresh token revokes the entire connection and all of its tokens. Unknown or already revoked tokens return success. Delete the local tokens after disconnecting.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" }, "token_type_hint": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string", "writeOnly": true } } } } } }, "responses": { "200": { "description": "Connection revoked, or token already invalid. Empty body." }, "400": { "description": "OAuth error. See Errors and rate limits in the OAuth section for how to handle it.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } } } } }, "401": { "description": "OAuth error. See Errors and rate limits in the OAuth section for how to handle it.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } } } } }, "429": { "description": "Too many requests. Wait for Retry-After seconds before retrying.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer", "minimum": 1 } } } } } } } }, "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." }, "PartnerOAuth": { "type": "oauth2", "description": "Connect a Book Report account using Authorization Code with PKCE S256. App registration requires approval. Customers with API access can connect.", "flows": { "authorizationCode": { "authorizationUrl": "https://app.getbookreport.com/oauth/partner/authorize", "tokenUrl": "https://app.getbookreport.com/oauth/partner/token", "refreshUrl": "https://app.getbookreport.com/oauth/partner/token", "scopes": { "reports:read": "View the data available through the Book Report API.", "data:manage": "View and manage data through the Book Report API." } } } }, "PartnerClientBasic": { "type": "http", "scheme": "basic", "description": "For an App with server, use the client ID as the username and the client secret as the password." } }, "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 or OAuth access token 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" } } } }, "NotFound": { "description": "The ad is unknown or is not visible in the authenticated account’s advertising reports.", "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": { "AdDetailsRequest": { "description": "Look up one Meta ad by its stable provider ID.", "type": "object", "properties": { "adId": { "type": "string", "maxLength": 100, "pattern": "^\\d+$", "description": "Meta ad ID. Use the ad_key value from a report grouped by ad with filter keys included." } }, "required": [ "adId" ], "additionalProperties": false, "examples": [ { "adId": "120000000000001" } ] }, "AdDetailsResponse": { "description": "The latest imported details for one visible Meta ad.", "type": "object", "properties": { "id": { "type": "string", "description": "Stable Meta ad ID, matching the report ad_key." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Latest imported ad name." }, "platform": { "type": "string", "const": "meta", "description": "Advertising platform. Currently meta." }, "account": { "type": "object", "properties": { "id": { "type": "string", "description": "Meta advertising account ID." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Meta advertising account name." } }, "required": [ "id", "name" ], "additionalProperties": false, "description": "Meta advertising account." }, "campaign": { "type": "object", "properties": { "id": { "type": "string", "description": "Meta campaign ID." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Meta campaign name." } }, "required": [ "id", "name" ], "additionalProperties": false, "description": "Meta campaign containing this ad." }, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Exact imported provider URL." }, "type": { "type": "string", "enum": [ "destination", "post" ], "description": "Whether this URL is an ad destination or a Facebook post." } }, "required": [ "url", "type" ], "additionalProperties": false }, "description": "Imported links. A post link opens the Facebook post; it is not a landing-page URL." }, "creative": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Meta creative ID." }, "primaryTexts": { "type": "array", "items": { "type": "string" }, "description": "Distinct primary-text variants, preserving line breaks." }, "headlines": { "type": "array", "items": { "type": "string" }, "description": "Distinct headline variants." }, "imageUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Provider-hosted ad image, when available." }, "thumbnailUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ], "description": "Provider-hosted image or video thumbnail, when available." }, "videoId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Meta video ID, when available. No video file is returned." }, "updatedAt": { "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))$" }, { "type": "null" } ], "description": "When Book Report last imported this creative successfully. Failed reads retain the previous creative and timestamp." } }, "required": [ "id", "primaryTexts", "headlines", "imageUrl", "thumbnailUrl", "videoId", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ], "description": "Latest successfully imported creative, or null until a successful creative import. Text arrays contain configured variants, without performance attribution or a guaranteed order. Media URLs can expire and are refreshed by normal imports. A thumbnail is an image preview, not a video file." } }, "required": [ "id", "name", "platform", "account", "campaign", "links", "creative" ], "additionalProperties": false, "examples": [ { "id": "120000000000001", "name": "Harbour mysteries video", "platform": "meta", "account": { "id": "123456789", "name": "Example Author" }, "campaign": { "id": "120000000000000", "name": "Harbour mysteries" }, "links": [ { "url": "https://www.example.com/books/harbour", "type": "destination" } ], "creative": { "id": "987654321", "primaryTexts": [ "A quiet harbour. An unexpected mystery.\nStart reading today." ], "headlines": [ "Discover your next mystery", "Meet the Harbour detectives" ], "imageUrl": null, "thumbnailUrl": "https://www.example.com/media/harbour-thumbnail.jpg", "videoId": "987654320", "updatedAt": "2026-10-20T12:00:00.000Z" } } ] }, "AccountUpdatesResponse": { "description": "Update times for connected accounts you can access.", "type": "object", "properties": { "accounts": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^BR-[A-Z0-9]{3}-[A-Z0-9]{3}$", "description": "Book Report account ID." }, "distributor": { "type": "string", "enum": [ "Kindle Direct Publishing", "Draft2Digital", "Google Play", "Kobo Writing Life", "Barnes & Noble Press", "ACX", "IngramSpark", "Apple Books", "Findaway Voices", "Smashwords", "INaudio", "BookFunnel", "PublishDrive", "Spotify for Authors" ], "description": "Publishing distributor." }, "lastUpdatedAt": { "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))$" }, { "type": "null" } ], "description": "When Book Report last successfully updated the data for this account, in UTC. null means no update time is available." } }, "required": [ "accountId", "distributor", "lastUpdatedAt" ], "additionalProperties": false, "description": "Publishing account." }, { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^BR-[A-Z0-9]{3}-[A-Z0-9]{3}$", "description": "Book Report account ID." }, "platform": { "type": "string", "enum": [ "amazon", "meta" ], "description": "Advertising platform." }, "account": { "type": "object", "properties": { "id": { "type": "string", "description": "Provider account ID. For Amazon Ads, this is the profile ID." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Provider account name, or null if unavailable." } }, "required": [ "id", "name" ], "additionalProperties": false, "description": "Advertising account." }, "lastUpdatedAt": { "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))$" }, { "type": "null" } ], "description": "When Book Report last successfully updated the data for this account, in UTC. null means no update time is available." } }, "required": [ "accountId", "platform", "account", "lastUpdatedAt" ], "additionalProperties": false, "description": "Advertising account." } ], "description": "One connected account." }, "description": "Connected publishing and advertising accounts." } }, "required": [ "accounts" ], "additionalProperties": false, "examples": [ { "accounts": [ { "accountId": "BR-ABC-234", "distributor": "Kindle Direct Publishing", "lastUpdatedAt": "2026-10-22T12:05:00.000Z" }, { "accountId": "BR-ABC-234", "platform": "amazon", "account": { "id": "123456789", "name": "Example Author Ads" }, "lastUpdatedAt": "2026-10-22T11:00:00.000Z" }, { "accountId": "BR-ABC-234", "platform": "meta", "account": { "id": "987654321", "name": "Example Author Ads" }, "lastUpdatedAt": null }, { "accountId": "BR-DEF-567", "distributor": "Kobo Writing Life", "lastUpdatedAt": "2026-10-20T09:00:00.000Z" } ] } ] }, "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", "offer_price_original_currency", "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", "offer_price_original_currency" ], "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", "ebook_pages_read", "audio_pages_listened", "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": "offer_price_original_currency", "label": "Offer Price (Original Currency)", "type": "Transaction", "description": "The offer price reported by the distributor, in its original currency, without conversion or price bands. The reported price may be an average and may exclude tax. Missing prices or currencies appear as Not set." }, { "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." }, { "key": "offer_price_original_currency", "label": "Offer Price (Original Currency)", "type": "Transaction", "description": "The offer price reported by the distributor, in its original currency, without conversion or price bands. The reported price may be an average and may exclude tax. Missing prices or currencies appear as Not set." } ], "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 total normalized pages read or listened through Kindle Unlimited and Kindle+. Includes reports whose reading/listening split is unavailable." }, { "key": "ebook_pages_read", "label": "eBook Pages Read", "isMoney": false, "type": "Quantity Metrics", "description": "Pages assigned to ebook editions. Includes combined totals from older or unsplit reports where reading and listening are not available separately." }, { "key": "audio_pages_listened", "label": "Audio Pages Listened", "isMoney": false, "type": "Quantity Metrics", "description": "Kindle+ listening activity, measured in normalized pages. Older or unsplit reports may show zero here even when listening occurred." }, { "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" } ] } ] } ] }, "SeriesAnalyticsRequest": { "description": "Read-through and earnings per reader for a date range and selected series, with control over which readers to include.", "type": "object", "properties": { "series": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "\\S" }, "description": "Series to include. Copy the selected values[].value strings from filter-value discovery with filter=series. These values are currently series titles. Each series is calculated separately. Omit this field for all series; an empty array is not accepted." }, "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." }, "unitTypes": { "default": [ "free", "ku", "other" ], "type": "array", "items": { "type": "string", "enum": [ "free", "ku", "other" ] }, "description": "Unit types to include: free means free downloads, ku means estimated Kindle Unlimited reads, and other means other units such as paid sales. Defaults to all three. Use [] to include none. Kindle Unlimited reads are estimated from pages read and the book's KENPC page count.", "uniqueItems": true }, "includeMidSeriesStarters": { "default": false, "type": "boolean", "description": "Defaults to false: estimate the progress and earnings of readers who begin at your chosen starting book and continue in order. Cap each book-to-book rate at 100%, carry that estimate forward, and scale earnings proportionally. Set true to retain all observed activity for the selected unit types; read-through can then exceed 100%, and EPR can overstate the value of a new reader at the starting book." }, "startFromBook": { "default": 1, "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Book position to count as the starting book, default 1. Readers are estimated starts at this position; earlier positions are omitted. All results, including scope, use this starting book." }, "currency": { "type": "string", "minLength": 1, "description": "Optional nonblank Book Report currency override. Field discovery does not return currencies." }, "attributes": { "maxItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Optional comparison within each series. For example, [\"marketplace\"] adds results for each marketplace alongside the combined Overall result. Supply at most one comparison attribute, such as marketplace, country, format, distributor, transaction_type, language, date, month, year, data_owner, or a custom attribute from field discovery. Daily (date) comparisons support up to 100 days and must start in 2018 or later; use month or year for longer ranges. Omit or use [] for Overall results only." }, "includeDetails": { "default": false, "type": "boolean", "description": "Add the numbers behind each row and book: observed units and earnings, the in-order estimate, and any adjustment ranges. Useful for explaining an adjusted result; omitted by default to keep answers short." }, "limit": { "default": 100, "type": "integer", "exclusiveMinimum": 0, "maximum": 1000, "description": "Maximum rows to return, from 1 to 1000 (default 100). A row contains one series or one comparison group and its complete books array. Use rowWindow.nextOffset to retrieve the next page." }, "offset": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of rows to skip, starting at 0. Keep the other request options unchanged when following rowWindow.nextOffset." } }, "additionalProperties": false, "examples": [ { "range": "all_time" }, { "range": "all_time", "series": [ "Harbour mysteries" ], "unitTypes": [ "ku", "other" ], "includeMidSeriesStarters": false, "includeDetails": true, "currency": "USD" }, { "range": "all_time", "series": [ "Harbour mysteries" ], "attributes": [ "marketplace" ], "currency": "USD" }, { "start": "2026-01-01", "end": "2026-06-30", "series": [ "Harbour mysteries" ], "includeDetails": true } ], "allOf": [ { "if": { "required": [ "range" ] }, "then": { "not": { "anyOf": [ { "required": [ "start" ] }, { "required": [ "end" ] } ] } }, "else": { "required": [ "start", "end" ] } } ], "x-bookreport-date-selection": { "exactlyOne": [ "range", "start+end" ], "orderedExplicitDates": "start <= end" } }, "SeriesAnalyticsResponse": { "description": "Series estimates with per-book results, supporting explanations, and pagination.", "type": "object", "properties": { "meta": { "type": "object", "properties": { "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": "Calendar date in YYYY-MM-DD form." }, "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": "Calendar date in YYYY-MM-DD form." }, "currency": { "type": "string", "minLength": 1, "description": "Currency used for every money value in the result." }, "startFromBook": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Starting book used to calculate the results." }, "unitTypes": { "type": "array", "items": { "type": "string", "enum": [ "free", "ku", "other" ] }, "description": "Unit types included in the calculations." }, "includeMidSeriesStarters": { "type": "boolean", "description": "Whether the results retain activity attributed to estimated mid-series starters." }, "attributes": { "maxItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Requested comparison attribute, or [] for Overall rows only." }, "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": "ISO 8601 timestamp." } }, "required": [ "start", "end", "currency", "startFromBook", "unitTypes", "includeMidSeriesStarters", "attributes", "generatedAt" ], "additionalProperties": false, "description": "Resolved request settings and generation time." }, "columns": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "description": "JSON field described by this column." }, "label": { "type": "string", "minLength": 1, "description": "Readable name for this field." }, "type": { "type": "string", "enum": [ "string", "number", "array" ], "description": "Value type; unavailable numeric values are null." }, "description": { "type": "string", "description": "Meaning of this field under the requested options." }, "unit": { "description": "Unit of a numeric value. Percent values use 0 to 100, not 0 to 1, and observed read-through may exceed 100.", "type": "string", "enum": [ "percent", "currency", "units" ] }, "currency": { "description": "Report currency when unit is currency.", "type": "string", "minLength": 1 } }, "required": [ "key", "label", "type", "description" ], "additionalProperties": false }, "description": "Fields returned in each result row and their meaning." }, "bookColumns": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "description": "JSON field described by this column." }, "label": { "type": "string", "minLength": 1, "description": "Readable name for this field." }, "type": { "type": "string", "enum": [ "string", "number", "array" ], "description": "Value type; unavailable numeric values are null." }, "description": { "type": "string", "description": "Meaning of this field under the requested options." }, "unit": { "description": "Unit of a numeric value. Percent values use 0 to 100, not 0 to 1, and observed read-through may exceed 100.", "type": "string", "enum": [ "percent", "currency", "units" ] }, "currency": { "description": "Report currency when unit is currency.", "type": "string", "minLength": 1 } }, "required": [ "key", "label", "type", "description" ], "additionalProperties": false }, "description": "Fields returned within each row's books array and their meaning." }, "rows": { "type": "array", "items": { "type": "object", "properties": { "series": { "type": "string", "description": "Series value, currently its title. This matches values[].value from series discovery and can be passed in the series request array." }, "breakdown": { "anyOf": [ { "type": "object", "properties": { "attribute": { "type": "string", "minLength": 1, "description": "Requested comparison attribute." }, "key": { "type": "string", "description": "Value represented by this comparison group." }, "label": { "type": "string", "description": "Readable label for this comparison group." } }, "required": [ "attribute", "key", "label" ], "additionalProperties": false }, { "type": "null" } ], "description": "null means the combined Overall result for the selected series. Otherwise identifies the attribute value whose activity is calculated separately." }, "readers": { "type": "number", "description": "Estimated starts: units at the requested starting book. Counts are estimated from sales, free downloads, and Kindle Unlimited activity, not individual reader histories." }, "earningsPerReader": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Earnings per estimated starting reader, in the report currency. Null when there are no starting readers; fractional Kindle Unlimited readers are supported." }, "earnings": { "type": "number", "description": "Series earnings from the starting book onward under the selected mid-series-starters setting, in the report currency." }, "units": { "type": "number", "description": "Series units from the starting book onward under the selected mid-series-starters setting." }, "bookCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Number of included book positions with activity in the report." }, "books": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Book position in the series. Results are ordered by position; books and editions assigned to the same position are combined." }, "units": { "type": "number", "description": "Units at this position after the unit-type selection and mid-series-starters setting are applied." }, "readThrough": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Cumulative read-through: units at this position divided by starting-book readers, multiplied by 100. A value of 60 means 60%; null means no starting readers." }, "bookToBookReadThrough": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Units at this position divided by units at the preceding position that has units in the selected range, multiplied by 100. The starting book is 100% when it has readers; null means no units to compare against." }, "earningsPerUnit": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Observed earnings divided by observed units at this position, in the report currency. Null when the position has no selected units." }, "eprContribution": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "This book's earnings under the selected mid-series-starters setting, divided by starting-book readers. Contributions add up to series EPR. Null when there are no starting readers or this position has no selected units." }, "details": { "description": "Supporting observed and in-order numbers when includeDetails/include_details is true.", "type": "object", "properties": { "observedUnits": { "type": "number", "description": "Units after choosing unit types, before excluding estimated mid-series starters." }, "observedEarnings": { "type": "number", "description": "Earnings from the chosen unit types, before excluding estimated mid-series starters, in the report currency." }, "inOrderUnits": { "type": "number", "description": "Units attributed to readers continuing from the chosen starting book." }, "inOrderEarnings": { "type": "number", "description": "Earnings attributed to those in-order readers, in the report currency." } }, "required": [ "observedUnits", "observedEarnings", "inOrderUnits", "inOrderEarnings" ], "additionalProperties": false } }, "required": [ "position", "units", "readThrough", "bookToBookReadThrough", "earningsPerUnit", "eprContribution" ], "additionalProperties": false }, "description": "One result per series position, ordered by position. Books and editions assigned to the same position are combined. Each result includes both read-through rates and its EPR contribution; pagination never splits this array." }, "details": { "description": "Supporting totals and adjustments when includeDetails/include_details is true.", "type": "object", "properties": { "observedUnits": { "type": "number", "description": "Units after choosing unit types, before excluding estimated mid-series starters." }, "observedEarnings": { "type": "number", "description": "Earnings from the chosen unit types, before excluding estimated mid-series starters, in the report currency." }, "inOrderUnits": { "type": "number", "description": "Units attributed to readers continuing from the chosen starting book." }, "inOrderEarnings": { "type": "number", "description": "Earnings attributed to those in-order readers, in the report currency." }, "inOrderEarningsPercent": { "type": "number", "description": "Percentage of observed earnings retained by the in-order estimate." }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "First book position in this adjusted range." }, "end": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Last consecutive adjusted position." }, "prevPosition": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Preceding position that limits this range; it may have no data." }, "prevRawUnits": { "type": "number", "description": "Observed units at the preceding position." }, "rawUnits": { "type": "number", "description": "Observed units at the first adjusted position." }, "prevEffectiveUnits": { "type": "number", "description": "In-order units at the preceding position." }, "effectiveUnits": { "type": "number", "description": "In-order units at the first adjusted position after capping." } }, "required": [ "start", "end", "prevPosition", "prevRawUnits", "rawUnits", "prevEffectiveUnits", "effectiveUnits" ], "additionalProperties": false }, "description": "Consecutive positions affected by capping book-to-book read-through and carrying the estimate forward." } }, "required": [ "observedUnits", "observedEarnings", "inOrderUnits", "inOrderEarnings", "inOrderEarningsPercent", "adjustments" ], "additionalProperties": false } }, "required": [ "series", "breakdown", "readers", "earningsPerReader", "earnings", "units", "bookCount", "books" ], "additionalProperties": false }, "description": "Each series has a combined Overall result, followed by any requested attribute comparisons. Results with few readers or gaps in book activity are included, with explanations in notices." }, "scope": { "type": "object", "properties": { "startFromBook": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Starting book used for scope counts, matching meta.startFromBook." }, "unitTypes": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "free", "ku", "other" ], "description": "Free downloads, estimated KU reads, or other units." }, "units": { "type": "number", "description": "Observed units of this type before unit-type selection or calculation exclusions. The KU value is the known subtotal; missing KENPC values can leave it incomplete, as explained in notices." }, "included": { "type": "boolean", "description": "Whether this unit type is included in the calculations." } }, "required": [ "type", "units", "included" ], "additionalProperties": false }, "description": "Observed counts for all three unit types and their selection state. These counts stay fixed when the inclusion settings change." }, "midSeriesStarters": { "type": "object", "properties": { "included": { "type": "boolean", "description": "Whether estimated mid-series starters are included in the calculations." }, "units": { "type": "number", "description": "Selected units beyond the estimate of readers continuing from the requested starting book." }, "percent": { "type": "number", "description": "Those units as a percentage of observed selected units, on a 0-to-100 scale." } }, "required": [ "included", "units", "percent" ], "additionalProperties": false, "description": "Estimated mid-series starters from the selected unit types in series that can be calculated, measured from the requested starting book." } }, "required": [ "startFromBook", "unitTypes", "midSeriesStarters" ], "additionalProperties": false, "description": "Observed units by type before calculation exclusions, plus estimated mid-series starters from the series that can be calculated. Both use the requested starting book and cover the selected series before pagination." }, "notices": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "description": "Machine-readable reason." }, "message": { "type": "string", "description": "Readable explanation and, where possible, what to do next." }, "series": { "description": "Affected series, when the notice is series-specific.", "type": "string" }, "breakdownKey": { "description": "Affected comparison group, when the notice is group-specific.", "type": "string" }, "positions": { "description": "Affected book positions, when known.", "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } } }, "required": [ "code", "message" ], "additionalProperties": false }, "description": "Explanations for low reader counts or missing positions in the returned rows, plus excluded series across the filtered result. Missing KENPC notices explain incomplete KU counts and whether the selected calculations exclude the affected series; an empty result does not necessarily mean no activity. Adjustment ranges are available through details when requested." }, "rowWindow": { "type": "object", "properties": { "totalRows": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Rows in the complete filtered result, before pagination." }, "returnedRows": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Rows returned on this page." }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 1000, "description": "Applied maximum rows per page." }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Rows skipped for this page." }, "hasMore": { "type": "boolean", "description": "Whether another page is available." }, "nextOffset": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Use this offset with the same request for the next page; null on the final page." } }, "required": [ "totalRows", "returnedRows", "limit", "offset", "hasMore", "nextOffset" ], "additionalProperties": false, "description": "Pagination applies to complete rows. Request nextOffset with the same options to continue. scope covers the full filtered result; notices describe the current page and any series excluded from the full result." } }, "required": [ "meta", "columns", "bookColumns", "rows", "scope", "notices", "rowWindow" ], "additionalProperties": false, "examples": [ { "meta": { "start": "2008-01-01", "end": "2026-06-30", "currency": "USD", "startFromBook": 1, "unitTypes": [ "free", "ku", "other" ], "includeMidSeriesStarters": false, "attributes": [], "generatedAt": "2026-06-30T12:00:00Z" }, "columns": [ { "key": "series", "label": "Series", "type": "string", "description": "Series name." }, { "key": "readers", "label": "Readers", "description": "Estimated starts at Book 1.", "type": "number", "unit": "units" }, { "key": "earningsPerReader", "label": "Earnings per reader", "description": "Earnings per estimated starting reader.", "type": "number", "unit": "currency", "currency": "USD" }, { "key": "earnings", "label": "Earnings", "description": "Earnings attributed to readers continuing in order.", "type": "number", "unit": "currency", "currency": "USD" }, { "key": "units", "label": "Units", "description": "Units attributed to readers continuing in order.", "type": "number", "unit": "units" }, { "key": "bookCount", "label": "Books", "description": "Included book positions.", "type": "number" }, { "key": "books", "label": "Books", "type": "array", "description": "Ordered per-book results; bookColumns describes the fields." } ], "bookColumns": [ { "key": "position", "label": "Book", "description": "Position in the series.", "type": "number" }, { "key": "units", "label": "Units", "description": "Units at this position.", "type": "number", "unit": "units" }, { "key": "readThrough", "label": "Cumulative read-through", "description": "Percentage continuing from Book 1.", "type": "number", "unit": "percent" }, { "key": "bookToBookReadThrough", "label": "Book-to-book read-through", "description": "Percentage continuing from the preceding book.", "type": "number", "unit": "percent" }, { "key": "earningsPerUnit", "label": "Earnings per unit", "description": "Observed earnings divided by observed units.", "type": "number", "unit": "currency", "currency": "USD" }, { "key": "eprContribution", "label": "EPR contribution", "description": "This book's contribution to earnings per reader.", "type": "number", "unit": "currency", "currency": "USD" } ], "rows": [ { "series": "Harbour mysteries", "breakdown": null, "readers": 300, "earningsPerReader": 2.6666666666666665, "earnings": 800, "units": 480, "bookCount": 3, "books": [ { "position": 1, "units": 300, "readThrough": 100, "bookToBookReadThrough": 100, "earningsPerUnit": 0.6666666666666666, "eprContribution": 0.6666666666666666 }, { "position": 2, "units": 120, "readThrough": 40, "bookToBookReadThrough": 40, "earningsPerUnit": 3, "eprContribution": 1.2 }, { "position": 3, "units": 60, "readThrough": 20, "bookToBookReadThrough": 50, "earningsPerUnit": 4, "eprContribution": 0.8 } ] } ], "scope": { "startFromBook": 1, "unitTypes": [ { "type": "free", "units": 200, "included": true }, { "type": "ku", "units": 80, "included": true }, { "type": "other", "units": 200, "included": true } ], "midSeriesStarters": { "included": false, "units": 0, "percent": 0 } }, "notices": [], "rowWindow": { "totalRows": 1, "returnedRows": 1, "limit": 100, "offset": 0, "hasMore": false, "nextOffset": null } }, { "meta": { "start": "2008-01-01", "end": "2026-06-30", "currency": "USD", "startFromBook": 1, "unitTypes": [ "ku", "other" ], "includeMidSeriesStarters": false, "attributes": [], "generatedAt": "2026-06-30T12:00:00Z" }, "columns": [ { "key": "series", "label": "Series", "type": "string", "description": "Series name." }, { "key": "readers", "label": "Readers", "description": "Estimated starts at Book 1.", "type": "number", "unit": "units" }, { "key": "earningsPerReader", "label": "Earnings per reader", "description": "Earnings per estimated starting reader.", "type": "number", "unit": "currency", "currency": "USD" }, { "key": "earnings", "label": "Earnings", "description": "Earnings attributed to readers continuing in order.", "type": "number", "unit": "currency", "currency": "USD" }, { "key": "units", "label": "Units", "description": "Units attributed to readers continuing in order.", "type": "number", "unit": "units" }, { "key": "bookCount", "label": "Books", "description": "Included book positions.", "type": "number" }, { "key": "books", "label": "Books", "type": "array", "description": "Ordered per-book results; bookColumns describes the fields." } ], "bookColumns": [ { "key": "position", "label": "Book", "description": "Position in the series.", "type": "number" }, { "key": "units", "label": "Units", "description": "Units at this position.", "type": "number", "unit": "units" }, { "key": "readThrough", "label": "Cumulative read-through", "description": "Percentage continuing from Book 1.", "type": "number", "unit": "percent" }, { "key": "bookToBookReadThrough", "label": "Book-to-book read-through", "description": "Percentage continuing from the preceding book.", "type": "number", "unit": "percent" }, { "key": "earningsPerUnit", "label": "Earnings per unit", "description": "Observed earnings divided by observed units.", "type": "number", "unit": "currency", "currency": "USD" }, { "key": "eprContribution", "label": "EPR contribution", "description": "This book's contribution to earnings per reader.", "type": "number", "unit": "currency", "currency": "USD" } ], "rows": [ { "series": "Harbour mysteries", "breakdown": null, "readers": 100, "earningsPerReader": 7, "earnings": 700, "units": 250, "bookCount": 3, "books": [ { "position": 1, "units": 100, "readThrough": 100, "bookToBookReadThrough": 100, "earningsPerUnit": 2, "eprContribution": 2, "details": { "observedUnits": 100, "observedEarnings": 200, "inOrderUnits": 100, "inOrderEarnings": 200 } }, { "position": 2, "units": 100, "readThrough": 100, "bookToBookReadThrough": 100, "earningsPerUnit": 3, "eprContribution": 3, "details": { "observedUnits": 120, "observedEarnings": 360, "inOrderUnits": 100, "inOrderEarnings": 300 } }, { "position": 3, "units": 50, "readThrough": 50, "bookToBookReadThrough": 50, "earningsPerUnit": 4, "eprContribution": 2, "details": { "observedUnits": 60, "observedEarnings": 240, "inOrderUnits": 50, "inOrderEarnings": 200 } } ], "details": { "observedUnits": 280, "observedEarnings": 800, "inOrderUnits": 250, "inOrderEarnings": 700, "inOrderEarningsPercent": 87.5, "adjustments": [ { "start": 2, "end": 3, "prevPosition": 1, "prevRawUnits": 100, "rawUnits": 120, "prevEffectiveUnits": 100, "effectiveUnits": 100 } ] } } ], "scope": { "startFromBook": 1, "unitTypes": [ { "type": "free", "units": 200, "included": false }, { "type": "ku", "units": 80, "included": true }, { "type": "other", "units": 200, "included": true } ], "midSeriesStarters": { "included": false, "units": 30, "percent": 10.714285714285714 } }, "notices": [], "rowWindow": { "totalRows": 1, "returnedRows": 1, "limit": 100, "offset": 0, "hasMore": false, "nextOffset": null } }, { "meta": { "start": "2008-01-01", "end": "2026-06-30", "currency": "USD", "startFromBook": 1, "unitTypes": [ "free", "ku", "other" ], "includeMidSeriesStarters": false, "attributes": [ "marketplace" ], "generatedAt": "2026-06-30T12:00:00Z" }, "columns": [ { "key": "series", "label": "Series", "type": "string", "description": "Series name." }, { "key": "breakdown.label", "label": "Marketplace", "type": "string", "description": "Comparison group; null breakdown means Overall." }, { "key": "readers", "label": "Readers", "description": "Estimated starts at Book 1.", "type": "number", "unit": "units" }, { "key": "earningsPerReader", "label": "Earnings per reader", "description": "Earnings per estimated starting reader.", "type": "number", "unit": "currency", "currency": "USD" }, { "key": "earnings", "label": "Earnings", "description": "Earnings attributed to readers continuing in order.", "type": "number", "unit": "currency", "currency": "USD" }, { "key": "units", "label": "Units", "description": "Units attributed to readers continuing in order.", "type": "number", "unit": "units" }, { "key": "bookCount", "label": "Books", "description": "Included book positions.", "type": "number" }, { "key": "books", "label": "Books", "type": "array", "description": "Ordered per-book results; bookColumns describes the fields." } ], "bookColumns": [ { "key": "position", "label": "Book", "description": "Position in the series.", "type": "number" }, { "key": "units", "label": "Units", "description": "Units at this position.", "type": "number", "unit": "units" }, { "key": "readThrough", "label": "Cumulative read-through", "description": "Percentage continuing from Book 1.", "type": "number", "unit": "percent" }, { "key": "bookToBookReadThrough", "label": "Book-to-book read-through", "description": "Percentage continuing from the preceding book.", "type": "number", "unit": "percent" }, { "key": "earningsPerUnit", "label": "Earnings per unit", "description": "Observed earnings divided by observed units.", "type": "number", "unit": "currency", "currency": "USD" }, { "key": "eprContribution", "label": "EPR contribution", "description": "This book's contribution to earnings per reader.", "type": "number", "unit": "currency", "currency": "USD" } ], "rows": [ { "series": "Harbour mysteries", "breakdown": null, "readers": 300, "earningsPerReader": 2.6666666666666665, "earnings": 800, "units": 480, "bookCount": 3, "books": [ { "position": 1, "units": 300, "readThrough": 100, "bookToBookReadThrough": 100, "earningsPerUnit": 0.6666666666666666, "eprContribution": 0.6666666666666666 }, { "position": 2, "units": 120, "readThrough": 40, "bookToBookReadThrough": 40, "earningsPerUnit": 3, "eprContribution": 1.2 }, { "position": 3, "units": 60, "readThrough": 20, "bookToBookReadThrough": 50, "earningsPerUnit": 4, "eprContribution": 0.8 } ] }, { "series": "Harbour mysteries", "breakdown": { "attribute": "marketplace", "key": "amazon.com", "label": "Amazon.com" }, "readers": 180, "earningsPerReader": 2.888888888888889, "earnings": 520, "units": 300, "bookCount": 3, "books": [ { "position": 1, "units": 180, "readThrough": 100, "bookToBookReadThrough": 100, "earningsPerUnit": 0.6666666666666666, "eprContribution": 0.6666666666666666 }, { "position": 2, "units": 80, "readThrough": 44.44444444444444, "bookToBookReadThrough": 44.44444444444444, "earningsPerUnit": 3, "eprContribution": 1.3333333333333333 }, { "position": 3, "units": 40, "readThrough": 22.22222222222222, "bookToBookReadThrough": 50, "earningsPerUnit": 4, "eprContribution": 0.8888888888888888 } ] }, { "series": "Harbour mysteries", "breakdown": { "attribute": "marketplace", "key": "amazon.co.uk", "label": "Amazon.co.uk" }, "readers": 120, "earningsPerReader": 2.3333333333333335, "earnings": 280, "units": 180, "bookCount": 3, "books": [ { "position": 1, "units": 120, "readThrough": 100, "bookToBookReadThrough": 100, "earningsPerUnit": 0.6666666666666666, "eprContribution": 0.6666666666666666 }, { "position": 2, "units": 40, "readThrough": 33.33333333333333, "bookToBookReadThrough": 33.33333333333333, "earningsPerUnit": 3, "eprContribution": 1 }, { "position": 3, "units": 20, "readThrough": 16.666666666666664, "bookToBookReadThrough": 50, "earningsPerUnit": 4, "eprContribution": 0.6666666666666666 } ] } ], "scope": { "startFromBook": 1, "unitTypes": [ { "type": "free", "units": 200, "included": true }, { "type": "ku", "units": 80, "included": true }, { "type": "other", "units": 200, "included": true } ], "midSeriesStarters": { "included": false, "units": 0, "percent": 0 } }, "notices": [], "rowWindow": { "totalRows": 3, "returnedRows": 3, "limit": 100, "offset": 0, "hasMore": false, "nextOffset": null } }, { "meta": { "start": "2026-01-01", "end": "2026-06-30", "currency": "USD", "startFromBook": 1, "unitTypes": [ "free", "ku", "other" ], "includeMidSeriesStarters": false, "attributes": [], "generatedAt": "2026-06-30T12:00:00Z" }, "columns": [ { "key": "series", "label": "Series", "type": "string", "description": "Series name." }, { "key": "readers", "label": "Readers", "description": "Estimated starts at Book 1.", "type": "number", "unit": "units" }, { "key": "earningsPerReader", "label": "Earnings per reader", "description": "Earnings per estimated starting reader.", "type": "number", "unit": "currency", "currency": "USD" }, { "key": "earnings", "label": "Earnings", "description": "Earnings attributed to readers continuing in order.", "type": "number", "unit": "currency", "currency": "USD" }, { "key": "units", "label": "Units", "description": "Units attributed to readers continuing in order.", "type": "number", "unit": "units" }, { "key": "bookCount", "label": "Books", "description": "Included book positions.", "type": "number" }, { "key": "books", "label": "Books", "type": "array", "description": "Ordered per-book results; bookColumns describes the fields." } ], "bookColumns": [ { "key": "position", "label": "Book", "description": "Position in the series.", "type": "number" }, { "key": "units", "label": "Units", "description": "Units at this position.", "type": "number", "unit": "units" }, { "key": "readThrough", "label": "Cumulative read-through", "description": "Percentage continuing from Book 1.", "type": "number", "unit": "percent" }, { "key": "bookToBookReadThrough", "label": "Book-to-book read-through", "description": "Percentage continuing from the preceding book.", "type": "number", "unit": "percent" }, { "key": "earningsPerUnit", "label": "Earnings per unit", "description": "Observed earnings divided by observed units.", "type": "number", "unit": "currency", "currency": "USD" }, { "key": "eprContribution", "label": "EPR contribution", "description": "This book's contribution to earnings per reader.", "type": "number", "unit": "currency", "currency": "USD" } ], "rows": [ { "series": "Harbour mysteries", "breakdown": null, "readers": 300, "earningsPerReader": 2.6666666666666665, "earnings": 800, "units": 480, "bookCount": 3, "books": [ { "position": 1, "units": 300, "readThrough": 100, "bookToBookReadThrough": 100, "earningsPerUnit": 0.6666666666666666, "eprContribution": 0.6666666666666666, "details": { "observedUnits": 300, "observedEarnings": 200, "inOrderUnits": 300, "inOrderEarnings": 200 } }, { "position": 2, "units": 120, "readThrough": 40, "bookToBookReadThrough": 40, "earningsPerUnit": 3, "eprContribution": 1.2, "details": { "observedUnits": 120, "observedEarnings": 360, "inOrderUnits": 120, "inOrderEarnings": 360 } }, { "position": 3, "units": 60, "readThrough": 20, "bookToBookReadThrough": 50, "earningsPerUnit": 4, "eprContribution": 0.8, "details": { "observedUnits": 60, "observedEarnings": 240, "inOrderUnits": 60, "inOrderEarnings": 240 } } ], "details": { "observedUnits": 480, "observedEarnings": 800, "inOrderUnits": 480, "inOrderEarnings": 800, "inOrderEarningsPercent": 100, "adjustments": [] } } ], "scope": { "startFromBook": 1, "unitTypes": [ { "type": "free", "units": 200, "included": true }, { "type": "ku", "units": 80, "included": true }, { "type": "other", "units": 200, "included": true } ], "midSeriesStarters": { "included": false, "units": 0, "percent": 0 } }, "notices": [], "rowWindow": { "totalRows": 1, "returnedRows": 1, "limit": 100, "offset": 0, "hasMore": false, "nextOffset": null } } ] }, "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. Daily (date) breakdowns support up to 100 inclusive days and must start in 2018 or later; use month or year for longer or earlier ranges.", "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", "offer_price_original_currency", "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", "ebook_pages_read", "audio_pages_listened", "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", "ebook_pages_read", "audio_pages_listened", "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", "offer_price_original_currency" ] }, "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", "ebook_pages_read", "audio_pages_listened", "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", "ebook_pages_read", "audio_pages_listened", "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" }