BytesAgain βΊ Skills βΊ BeyondBSR - BookSearch API
π¦ ClawHub
BeyondBSR - BookSearch API
by @ramius88
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...
Versionv1.0.4
β‘ When to Use
| Trigger | Action |
|---|---|
| - 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 | |
| ```bash | |
| 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: | |
| ```json | |
| { | |
| "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`. | |
TERMINAL
clawhub install booksearch-apiπ§ͺ Use this skill with your agent
Most visitors already have an agent. Pick your environment, install or copy the workflow, then run the smoke-test prompt above.
Manusinvite
Task-oriented agent. Great for testing AI skills end-to-end.
Try Manus β
OpenClaw
Local-first agent. Install skills via ClawHub CLI.
Set up OpenClaw β
Claude Code
Anthropic's coding agent. Paste the prompt or SKILL.md into your session.
Claude Code docs β
Cursor
AI-powered IDE. Use the smoke-test prompt in Cursor Agent.
Open Cursor β
Continue.dev
Open-source AI code assistant. Add SKILL.md as a custom tool.
Continue docs β
Windsurf
Agentic IDE by Codeium. Paste the prompt into Cascade.
Try Windsurf β
Cline
VS Code extension for autonomous coding with MCP tools.
Cline on GitHub β
Copilot Workspace
GitHub's AI dev environment. Suitable for code-generation skills.
Copilot Workspace β
π Can't find the right skill?
Search 60,000+ AI agent skills β free, no login needed.