# Shamela — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and browse one of the largest collections of Arabic and Islamic books, exploring thousands of titles by category, author, or full-text content. Access detailed book information, read specific pages, and discover newly added works to build your digital Islamic library.

**Category:** Education | **Website:** [shamela.ws/](https://shamela.ws/) | **Docs:** [parse.bot/marketplace/3114b3fc-5155-4980-be68-bd342ddb82e6/shamela-ws-api](https://parse.bot/marketplace/3114b3fc-5155-4980-be68-bd342ddb82e6/shamela-ws-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/shamela/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get author books

Retrieve all books by a specific author. Returns the author's name and a list of their books with IDs, titles, and URLs. Author IDs can be found in book detail pages.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `author_id` | string | Yes | Author ID (e.g. "215" for al-Bukhari). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/shamela/get-author-books \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"author_id":"<string>"}'
```

### Get book details

Retrieve full metadata and table of contents for a specific book. Returns the book title, author, publication metadata (publisher, edition, page count), and a structured table of contents with section titles and page links.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `book_id` | string | Yes | Book ID from category listings or search results (e.g. "6387", "735"). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/shamela/get-book-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"book_id":"<string>"}'
```

### Get book page

Read the text content of a specific page in a book. Returns the full Arabic text of the page along with the book title and author. Page numbers correspond to the book's internal numbering visible in the table of contents.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `book_id` | string | Yes | Book ID (e.g. "6387", "735"). |
| `page_number` | string | Yes | Page number within the book (e.g. "1", "5"). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/shamela/get-book-page \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"book_id":"<string>","page_number":"<string>"}'
```

### Get books by category

List books in a specific category with pagination. Returns a page of books with metadata and a has_next flag for pagination. Each book includes id, title, author, and URL. Use category IDs from get_categories.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | Yes | Category ID from get_categories (e.g. "1" for al-Aqeedah, "6" for Kutub al-Sunnah). |
| `page` | integer | No | Page number for pagination. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/shamela/get-books-by-category \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<string>","page":"<integer>"}'
```

### Get categories

Retrieve all book categories from the Shamela library. Returns the full category tree with IDs, Arabic names, book counts, and direct URLs. Categories are stable identifiers used to browse books via get_books_by_category.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/shamela/get-categories \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get recently added

List recently added books from the library homepage. Returns the latest additions with IDs, titles, authors (when available), and URLs.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/shamela/get-recently-added \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### List all books

List books across multiple categories up to a specified limit. Iterates through categories sequentially, collecting books from each. Useful for bulk discovery of the library's collection.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum number of books to return. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/shamela/list-all-books \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>"}'
```

### Search books by content

Full-text search across all book content in the library. Returns matching excerpts with book titles, authors, URLs, and text snippets containing the search term. Supports pagination.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |
| `query` | string | Yes | Search keyword in Arabic (e.g. "الحديث", "حكم"). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/shamela/search-books-by-content \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>"}'
```

### Search books by name

Search for books by title using the library's autocomplete API. Returns matching books with IDs, titles, and URLs. Accepts Arabic search terms. Results are not paginated.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword in Arabic (e.g. "البخاري", "فقه"). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/shamela/search-books-by-name \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.