# Pangobooks

> Pangobooks is a marketplace for physical used books (no ebooks or audiobooks).
> Use the public research API below instead of scraping HTML — especially for pricing and search.

Website: https://pangobooks.com
Human docs / try-it: https://pangobooks.com/public-api
OpenAPI: https://pangobooks.com/openapi.json
Sitemap: https://pangobooks.com/sitemaps/sitemap_index.xml

## Preferred research flow

1. Search titles (or books)
2. Fetch pricing by ISBN and/or a specific listing by book id
3. Link humans to the canonical HTML URLs returned in `urls`

## Public research API

No API key required. CORS open (`Access-Control-Allow-Origin: *`).
Response shape: `{ "success": true, "data": { ... } }`

### Rate limits

| Tier | Limit | Auth |
|------|-------|------|
| Free | 10 requests / minute (per IP) | None |
| Registered | 30 requests / minute (per account) | `Authorization: Bearer <auth_token>` from a free Pangobooks account |

Over limit → HTTP `429` + `Retry-After`, with JSON like:

```json
{
  "error": "Too many requests",
  "message": "Free public API limit is 10 requests per minute. Create a free Pangobooks account and send Authorization: Bearer <auth_token> for 30 requests per minute. Docs: https://pangobooks.com/public-api",
  "tier": "free",
  "limit_per_minute": 10,
  "retry_after": 60,
  "upgrade": {
    "limit_per_minute": 30,
    "how": "Send Authorization: Bearer <auth_token> from a registered Pangobooks account",
    "docs": "https://pangobooks.com/public-api"
  }
}
```

### Search (find a title or listing)
- `GET https://pangobooks.com/api/public/search?q={query}&type=titles&limit=5`
- `type`: `titles` (default, preferred) or `books`
- `limit`: 1–10 (default 5). No deep pagination — page 1 only.

### Market pricing (ISBN comps / sold prices)
- `GET https://pangobooks.com/api/public/pricing?isbn={isbn}`
- Prefer this over crawling `/pricing` HTML.

### Listing detail (buy a specific copy)
- `GET https://pangobooks.com/api/public/books/{bookId}`
- HTML equivalent: https://pangobooks.com/books/{bookId}

## Examples

```
GET https://pangobooks.com/api/public/search?q=project+hail+mary&type=titles&limit=5
GET https://pangobooks.com/api/public/pricing?isbn=9780593135204
GET https://pangobooks.com/api/public/books/{bookId}

# Registered tier (30/min)
GET https://pangobooks.com/api/public/pricing?isbn=9780593135204
Authorization: Bearer <auth_token>
```

## HTML surfaces (optional)

- Title pages: https://pangobooks.com/titles/{slug}
- Pricing hub: https://pangobooks.com/pricing
- Canonical pricing: https://pangobooks.com/pricing/author/{authorId}/{titleSlug}/{isbn}
- Listings: https://pangobooks.com/books/{bookId}

## Please do not

- Hammer HTML `/search` or paginate search results for research
- Scrape `/pricing` HTML when the ISBN pricing API is available
- Bypass rate limits or ignore `Retry-After`
- Request unbounded result sets (use `limit` ≤ 10)

## Contact

https://pangobooks.com/help

## Connected assistants (MCP)

Accounts that have been enabled can connect Claude, ChatGPT, Grok, or any remote-MCP client with Sign in with PangoBooks. Other accounts are refused. This file tells an agent how to use the server. MCP clients discover the server from the URL below, not from this file.

- Connect docs: https://pangobooks.com/connect
- MCP server: https://pangobooks.com/api/mcp
- Protected resource metadata: https://pangobooks.com/.well-known/oauth-protected-resource/api/mcp
- Same document at the issuer root: https://pangobooks.com/.well-known/oauth-protected-resource
- OAuth authorization server: https://pangobooks.com/.well-known/oauth-authorization-server
- Disconnect: https://pangobooks.com/oauth/connections

A client that calls `GET` or `POST https://pangobooks.com/api/mcp` without a token receives `401` and `WWW-Authenticate: Bearer resource_metadata="https://pangobooks.com/.well-known/oauth-protected-resource/api/mcp"`. That document lists `scopes_supported` and the authorization server. The authorization-server document lists `/oauth/authorize`, `/api/oauth/token`, `/api/oauth/register`, and `/api/oauth/revoke`.

Permissions the account holder can grant:

| Scope | Starts checked | Tools |
|-------|----------------|-------|
| `search` | yes | `search_books`, `get_listing`, `get_pricing` |
| `cart:read` | yes | `get_cart` |
| `cart:write` | yes | `add_to_cart`, `remove_from_cart` |
| `orders:place` | yes | `prepare_purchase` |
| `seller:inventory` | no | `get_seller_summary`, `get_seller_activity`, `list_seller_listings`, `get_seller_listing`, `list_seller_orders`, `get_seller_order`, `list_seller_offers`, `get_seller_offer` |

`prepare_purchase` does not charge a card and does not reserve inventory. Call it only after the buyer explicitly agrees to the quoted listing subtotal, with `user_confirmed` set to true. Give the buyer `checkout_url` exactly as returned: `https://pangobooks.com/checkout?ids=<listing id>&cid=<buyer id>`. Checkout 404s if `ids` is missing. Shipping and tax are finalized on pangobooks.com.

`seller:inventory` stays unchecked until the seller opts in. Those tools read that seller's own rows in `books`, `sold_books`, `orders`, and `offers`, plus the windowed store activity (visits, shelf adds, cart adds, purchases). `get_seller_listing`, `get_seller_order`, and `get_seller_offer` return the intersection: a listing with its offers and orders, an order with its books and offers, an offer with its books and the order it became. They cannot edit listings, accept an offer, or charge anyone. Order rows include the buyer display name and ship-to city and state. Street addresses, emails, payment details, and buyer ids are omitted. Views and current cart totals cover the first 5000 live listings; larger shops are marked `engagement_complete: false`. Visits are unavailable above 1000 active listings.