# Shamela — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://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. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-shamela-ws-api-3114b3fc/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## 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.paywithlocus.com/api/wrapped/parse-shamela-ws-api-3114b3fc/get_author_books \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-shamela-ws-api-3114b3fc/get_book_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-shamela-ws-api-3114b3fc/get_book_page \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-shamela-ws-api-3114b3fc/get_books_by_category \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-shamela-ws-api-3114b3fc/get_categories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-shamela-ws-api-3114b3fc/get_recently_added \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-shamela-ws-api-3114b3fc/list_all_books \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-shamela-ws-api-3114b3fc/search_books_by_content \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-shamela-ws-api-3114b3fc/search_books_by_name \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```