BeyondBSR - BookSearch API

Search Amazon KDP books on the BeyondBSR public API and retrieve BSR (Best Sellers Rank) history for a single book. Use this skill whenever the user wants to...

Security Scan

The skill is internally consistent: it documents calling the BeyondBSR API and only requests a single API key (BOOKSEARCH_API_KEY) that is appropriate for the stated purpose.

Purpose & Capability

Name/description match the declared requirements and endpoints. The only required secret is BOOKSEARCH_API_KEY, which is appropriate for an external API that provides BSR/book search data. Minor note: the skill metadata lacks a source/homepage which means provenance is unknown, but this is a transparency issue rather than an incoherence between purpose and requested capabilities.

Instruction Scope

SKILL.md limits runtime actions to calling two documented BeyondBSR endpoints for search and BSR history and instructs the agent to read only BOOKSEARCH_API_KEY. The doc explicitly forbids unrelated data (price-history, account/user data) and instructs not to echo the API key. No instructions request access to unrelated files, credentials, or external endpoints.

Install Mechanism

Instruction-only skill with no install spec and no code files; nothing is written to disk or downloaded during install. This is the lowest-risk install model and is appropriate for a simple API-integration skill.

Credentials

Only a single environment variable is required (BOOKSEARCH_API_KEY) and the SKILL.md documents the expected format and strict handling. The requested credential is proportionate and directly tied to the described API usage.

Persistence & Privilege

The skill does not request permanent/always-on inclusion (always:false) and does not declare writes to other skills or system-wide config. Autonomous invocation by the agent is allowed by default (disable-model-invocation:false) which is normal for skills; this is noted but not flagged by itself.

Assessment

This skill appears coherent and limited to calling the BeyondBSR API using a single API key. Before installing, consider: 1) Verify the origin/trustworthiness of the skill (source and owner are not public and there is no homepage listed). 2) Only provide a BOOKSEARCH_API_KEY issued by a trusted BeyondBSR account; avoid using long-lived keys with broader scopes than necessary. 3) Treat the key as a secret: confirm the platform will not leak it and rotate it if you suspect exposure. 4) Review BeyondBSR’s privacy/terms to ensure you are comfortable with sending search queries and ASINs to that service. 5) If you are uncomfortable with autonomous invocation, disable model invocation for the skill or avoid setting the API key in shared environments.

BookSearch API

Programmatic search over the BeyondBSR book catalogue plus BSR history retrieval for a single book. Two endpoints, JSON in / JSON out, API-key auth.

When to use this skill

Use it when the user asks to:

• Find books matching numeric filters: BSR range, rating, reviews count, royalty, page count age, publication recency.
• Discover niches by keyword inclusion/exclusion or Amazon category IDs.
• Filter by marketplace (Amazon.com, .co.uk, .de, .fr, .it, .es, .ca).
• Distinguish self-publishers from traditional publishers.
• Estimate sales (daily / weekly / monthly / quarterly) and revenue per copy.
• Compare BSR averages across multiple time windows (7d / 30d / 90d / 180d / 365d).
• Retrieve the BSR timeline of a single book (by domainId + asin) over the last N days, e.g. for charting rank evolution.

Do NOT use for: price-history charts, review/rating timelines, account/user data, or anything not in the response schemas below. Those are out of scope.

Endpoints

POST https://beyondbsr.com/api/v1/books/search
GET  https://beyondbsr.com/api/v1/books/{domainId}/{asin}/bsr-history?days={1..365}
Content-Type: application/json   (search only)
X-API-Key: $BOOKSEARCH_API_KEY

Authentication

• Read the key from the BOOKSEARCH_API_KEY env var. Format: bbsr_live_<43-char-base64url>.
• Never print, echo, log, or include the key in any user-facing output. Never paste it into another tool's input.
• On 401 Unauthorized: do not retry. Report "API key missing or invalid — check BOOKSEARCH_API_KEY env var" and stop.
• Send X-API-Key exactly once. Multi-valued headers are rejected.

Marketplace domains

Map natural-language marketplace references (e.g. "Amazon.de", "the UK store", "amazon italia") to domainId using this table:

domainId	locale	country	name
1	com	US	United States
2	co.uk	GB	United Kingdom
3	de	DE	Germany
4	fr	FR	France
6	ca	CA	Canada
8	it	IT	Italy
9	es	ES	Spain

IDs 5 and 7 are intentional gaps in the dataset — do not invent them. The validator technically accepts 1–12, but only the seven IDs above are guaranteed to return data. If the user asks for a marketplace not listed (e.g. Japan, Australia), tell them it is not currently supported.

Request schema

All fields are optional except domainId. Enums accept either the string name (e.g. "Weekly") or the integer value.

Required

Field	Type	Constraint
domainId	int	One of the 7 IDs in the marketplace table above (validator allows 1–12).

BSR filters

Field	Type	Default	Notes
bsrType	enum	Weekly	Historical(-1), Current(0), Weekly(7), Days30(8), Days90(9), Days180(10), Days365(11)
bsrMin	int?	1	≥ 1
bsrMax	int?	100000	≥ 1, bsrMin ≤ bsrMax
bsrYear	short?	null	2000–(current year + 1). Required together with bsrMonth. Use only with bsrType=Historical.
bsrMonth	short?	null	1–12. Required together with bsrYear.

Product filters

Field	Type	Default	Notes
bindingType	enum?	null (all)	All, Paperback, Hardcover
publisherType	enum?	All	All, SelfPublishersOnly, PublishersOnly
interiorType	enum?	BlackWhite	BlackWhite, FullColor
vatType	enum?	Reduced	Reduced, Standard
includePreOrders	bool?	false	—

Quality filters

Field	Type	Constraint
ratingMin	double?	0.0–5.0, ratingMin ≤ ratingMax
ratingMax	double?	0.0–5.0
reviewsMin	int?	≥ 0, reviewsMin ≤ reviewsMax
reviewsMax	int?	≥ 0

Economic filters

Field	Type	Notes
royaltyMin	decimal?	In currency units, not cents. min ≤ max.
royaltyMax	decimal?	—
monthsSincePublicationMin	int?	min ≤ max
monthsSincePublicationMax	int?	—

Discovery

Field	Type	Constraint
includeKeywords	string[]	≤ 25 items, each ≤ 100 chars, non-empty
excludeKeywords	string[]	≤ 25 items, each ≤ 100 chars, non-empty
categoryIds	long[]	≤ 100 items, each > 0 (Amazon BrowseNode IDs)

Pagination

Field	Type	Default	Range
limit	int?	100	1–300
offset	int?	0	0–100000

Workflow

1. Marketplace — Identify domainId from intent using the marketplace table. If ambiguous (e.g. "Amazon"), ask which country.
2. Translate — Map every natural-language filter to its schema field. Don't guess enum values; use the table.
3. Pagination — Default to limit: 50. Raise to 100–300 only if the user explicitly wants many results. Start with offset: 0.
4. Send — POST the JSON body. Inspect the status code first.
5. Paginate if needed — If returnedCount == limit, more results likely exist. Offer to fetch the next page with offset += limit.
6. Present — Surface title, asin, bsr, sales/revenue estimates, and a clickable cover URL (see response notes).

Example request

{
  "domainId": 3,
  "bsrType": "Days90",
  "bsrMin": 1,
  "bsrMax": 50000,
  "bindingType": "Paperback",
  "publisherType": "SelfPublishersOnly",
  "ratingMin": 4.0,
  "reviewsMin": 10,
  "interiorType": "BlackWhite",
  "vatType": "Reduced",
  "royaltyMin": 2.50,
  "royaltyMax": 15.00,
  "monthsSincePublicationMax": 24,
  "includePreOrders": false,
  "includeKeywords": ["journal", "notebook"],
  "excludeKeywords": ["coloring"],
  "categoryIds": [266162, 3248921],
  "limit": 50,
  "offset": 0
}

Example cURL

curl -X POST "https://beyondbsr.com/api/v1/books/search" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $BOOKSEARCH_API_KEY" \
  -d '{
    "domainId": 3,
    "bsrType": "Days90",
    "bsrMax": 50000,
    "bindingType": "Paperback",
    "publisherType": "SelfPublishersOnly",
    "ratingMin": 4.0,
    "limit": 50
  }'

Response schema

Envelope — BookSearchApiResponse

Field	Type	Notes
returnedCount	int	Items in this page. NOT a total-match count (no total exposed).
limit	int	Effective limit applied (capped at 300).
offset	int	Effective offset applied.
results	array	BookSearchResultDto[]. Empty if no match.

Result item — BookSearchResultDto (most relevant fields)

Field	Type	Notes
id	long	Internal book ID.
asin	string	10-char Amazon ASIN.
title	string	Full title.
authors	string?	Comma-separated, ordered by display_order.
publicationDate	datetime?	Nullable.
publisher	string?	Manufacturer/publisher name.
coverImageFilename	string?	Build URL: https://m.media-amazon.com/images/I/{filename}.
imageFilenames	string[]	All carousel images (same URL pattern).
rating	double	0.0–5.0.
reviews	int	Total reviews.
bsr	int	The column matching the requested bsrType — i.e. the value filtered/sorted on.
bsrCurrent	int?	Latest snapshot BSR, regardless of bsrType.
avgBsr7d	int?	Always populated.
avgBsr30d	int?	Always populated.
avgBsr90d	int?	Always populated.
avgBsr180d	int?	Always populated.
avgBsr365d	int?	Always populated.
pageCount	int?	—
priceCents	int?	List price (MSRP) in cents.
dailyEstimate	decimal	Estimated copies/day from BSR model.
weeklyEstimate	decimal	Estimated copies/week.
monthlyEstimate	decimal	Estimated copies/month.
quarterlyEstimate	decimal	Copies/quarter (needs ≥ 13 weeks of data).
royalty*Cents	int?	Per-copy royalty in cents. 4 combinations: B/W or Color × Reduced or Standard VAT.
*Revenue*Cents	long?	Derived = estimate × royalty. 16 fields total: {daily,weekly,monthly,quarterly} × {Black,Color} × {Reduced,Standard}.
binding	string?	Localised label (e.g. "Paperback", "Hardcover", "Non-standard").
dimensions	string?	Formatted, prefixed by binding. Example: "Paperback: 152 x 8 x 229 mm".
trim/spineWidthMm	int?	Trim/spine measurements.

Important caveats

• All royalty and revenue fields are in cents — divide by 100 before showing currency.
• bsr ≠ bsrCurrent. bsr is whatever column was chosen by bsrType; bsrCurrent is always the latest snapshot.
• In bsrType=Historical mode, the avgBsrXd averages come from the current snapshot table while bsr itself is the historical month value — there is a documented temporal asymmetry inside the same response. Mention this if the user is doing a strict historical analysis.

BSR History endpoint

Single-ASIN BSR timeline. Returns raw snapshots from the time-series store, ordered ascending by recordedAt.

GET https://beyondbsr.com/api/v1/books/{domainId}/{asin}/bsr-history?days={1..365}
X-API-Key: $BOOKSEARCH_API_KEY
Accept: application/json

When to use

• The user has a specific ASIN and wants its BSR over time (chart, drill-down, sanity-check the search-time avgBsrXd averages).
• The user wants to verify a book's recent rank trajectory (e.g. "is it gaining or losing visibility?").

If the user has filter criteria but no specific ASIN, use POST /search first, then call this endpoint per ASIN of interest.

Path & query parameters

Param	In	Type	Required	Constraint
domainId	path	int	yes	One of the 7 marketplace IDs (see Marketplace domains table; validator allows 1–12).
asin	path	string	yes	Exactly 10 chars, regex ^[A-Z0-9]{10}$ (uppercase letters / digits only).
days	query	int?	no	1–365. Default 365. Window is [now - days, now] UTC.

Example request

GET /api/v1/books/1/1635864348/bsr-history?days=90
X-API-Key: $BOOKSEARCH_API_KEY
Accept: application/json

Example cURL

curl -X GET "https://beyondbsr.com/api/v1/books/1/1635864348/bsr-history?days=90" \
  -H "X-API-Key: $BOOKSEARCH_API_KEY" \
  -H "Accept: application/json"

Response schema — BookBsrHistoryApiResponse

Field	Type	Notes
asin	string	Echoed from request.
domainId	int	Echoed from request.
fromUtc	datetime	Window start (now - days), UTC.
toUtc	datetime	Window end (now), UTC.
pointCount	int	Number of BSR snapshots in points.
points	array	BsrPointDto[] ordered ascending by recordedAt.

BsrPointDto:

Field	Type	Notes
recordedAt	datetime	UTC timestamp of the snapshot.
bestSellersRank	int?	BSR at that timestamp. May be null if Keepa returned no rank.

Example body:

{
  "asin": "1635864348",
  "domainId": 1,
  "fromUtc": "2026-01-27T00:00:00Z",
  "toUtc": "2026-04-27T00:00:00Z",
  "pointCount": 412,
  "points": [
    { "recordedAt": "2026-01-27T03:14:00Z", "bestSellersRank": 1234 },
    { "recordedAt": "2026-01-27T15:02:00Z", "bestSellersRank": 1218 }
  ]
}

Status codes (BSR history specific)

Code	Meaning	Notes
200	OK	pointCount may be 0 if no snapshots exist in the window.
400	Validation failed	ValidationProblemDetails. Common causes: days out of range, asin wrong format, domainId out of [1,12].
404	ASIN not found for that domain	Empty body. The book is not tracked in BeyondBSR for this marketplace. Tell the user — do not retry with the same pair.
401 / 429 / 500	See generic table below.

Caveats

• Granularity is raw: Keepa snapshots arrive 1–4× per day on actively-tracked books. A 365-day window typically yields 365–1460 points. No daily aggregation is applied.
• The endpoint returns only (recordedAt, bestSellersRank). Use POST /search if you also need rating/review/price data.
• ASIN is case-sensitive — must be uppercase. 1635864348 (all digits) is valid.
• Default 365 days is the cap. Longer histories are not exposed; do not retry with days > 365.

Status codes & error handling

Code	Meaning	Body	Agent action
200	OK (may be empty list)	BookSearchApiResponse	Parse results. Empty array = no matches, not an error.
400	Validation failed	ValidationProblemDetails (RFC 7807)	Read the errors map, fix the body, do not retry blindly. Surface the issue.
401	Auth failed	empty + WWW-Authenticate: ApiKey realm="BeyondBSR"	Stop. Report misconfigured BOOKSEARCH_API_KEY. Do not retry.
429	Rate limit exceeded	"Rate limit exceeded. Please try again later." + Retry-After header	Honour Retry-After. Back off. Do not hammer the endpoint.
500	Unhandled server error	ProblemDetails JSON	Retry once after a few seconds. If it persists, escalate to the user.

Example 400 body

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "DomainId": ["DomainId must be between 1 and 12."],
    "Limit": ["Limit must be between 1 and 300."]
  }
}

Sorting & pagination notes

• Default sort: ORDER BY <chosen BSR column> ASC (lower BSR = better seller appears first).
• Historical mode (bsrType=Historical + bsrYear/bsrMonth): sorted by the historical monthly BSR rank ASC.
• Tie-breaker is non-deterministic — books with identical BSR may appear in different orders across page fetches. Warn the user if they need a perfectly stable ordering.
• No orderBy parameter is exposed.

Limits

• Rate limit: 120 requests/minute per API key. Shared across all callers using the same key.
• Body size: 128 KB max.
• Page size: 300 results max per request (limit ≤ 300).
• Offset cap: 100,000 (deep pagination beyond this is not supported — refine filters instead).