# Novelbin — 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 novels by title, genre, or popularity, and explore trending, completed, or recently updated works. Access full novel details, chapter listings, chapter content, author information, related titles, and reader comments. Authenticated users can manage bookmarks with reading-status tracking and subscribe to novels for update notifications.

**Category:** Entertainment | **Website:** [novelbin.me/](https://novelbin.me/) | **Docs:** [parse.bot/marketplace/e0f4ccf0-cefd-4a49-9e91-47eb15a5f94f/novelbin-me-api](https://parse.bot/marketplace/e0f4ccf0-cefd-4a49-9e91-47eb15a5f94f/novelbin-me-api)

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

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/novelbin/`
**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

### Add to bookmark

Add a novel to the authenticated user's bookmark list. Requires prior login call in the same session.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | Novel slug |
| `status` | string | No | Status: reading, plan_to_read, completed, dropped |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/novelbin/add-to-bookmark \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"slug":"<string>","status":"<string>"}'
```

### Get chapter content

Retrieve the full text content of a specific chapter. The novel_slug and chapter_slug together identify a unique chapter page. Chapter slugs come from get_novel_chapters results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `chapter_slug` | string | Yes | Chapter slug identifier from get_novel_chapters results (e.g. 'chapter-1-nightmare-begins') |
| `novel_slug` | string | Yes | Novel slug identifier (e.g. 'shadow-slave') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/novelbin/get-chapter-content \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"chapter_slug":"<string>","novel_slug":"<string>"}'
```

### Get completed novels

Retrieve novels marked as fully completed, paginated. Returns 20 novels per page with title, slug, author, and cover image.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/novelbin/get-completed-novels \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>"}'
```

### Get genres list

Return all available genre categories that can be used with get_novels_by_genre. This is a static list and does not require any input.

**Estimated cost:** Metered

_No parameters required._

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

### Get hot novels

Retrieve currently trending/hot novels, paginated. Returns 20 novels per page with title, slug, author, and cover image.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/novelbin/get-hot-novels \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>"}'
```

### Get latest release novels

Retrieve the most recently updated novels, paginated. Returns 20 novels per page with title, slug, author, and cover image.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/novelbin/get-latest-release-novels \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>"}'
```

### Get most popular novels

Retrieve all-time most popular novels sorted by total viewership, paginated. Returns 20 novels per page with title, slug, author, and cover image.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/novelbin/get-most-popular-novels \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>"}'
```

### Get novel chapters

Retrieve the list of all chapters for a given novel. May return a large list for long novels (thousands of chapters). Each chapter includes a title and slug usable with get_chapter_content.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | Novel slug identifier (e.g. 'shadow-slave') |

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

### Get novel comments

Retrieve reader comments for a specific novel, with pagination and sort control.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `skip` | integer | No | Number of comments to skip for pagination. |
| `slug` | string | Yes | Novel slug identifier (e.g. 'shadow-slave') |
| `sort` | string | No | Sort order: 'latest' or 'oldest' |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/novelbin/get-novel-comments \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"skip":"<integer>","slug":"<string>","sort":"<string>"}'
```

### Get novel details

Retrieve full details for a specific novel by its slug, including title, author, genres, status, rating, cover image URL, and description. The slug is the URL-path identifier from search or listing results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | Novel slug identifier (e.g. 'shadow-slave', 'lord-of-the-mysteries') |

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

### Get novels by genre

Retrieve novels filtered by a specific genre, paginated. Returns 20 novels per page. Use get_genres_list to see all available genres.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `genre` | string | Yes | Genre name. |
| `page` | integer | No | Page number for pagination. |

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

### Get related novels

Retrieve novels related to a given novel (hot novels in the same genre). Returns a list of novel titles and slugs from the novel's detail page sidebar.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | Novel slug identifier (e.g. 'shadow-slave') |

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

### Login

Authenticate a user with email and password.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `email` | string | Yes | User email |
| `password` | string | Yes | User password |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/novelbin/login \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"email":"<string>","password":"<string>"}'
```

### Search novels

Full-text search over NovelBin's catalog by keyword. Returns matching novels with title, author, cover image, and latest chapter info. Results are not paginated — all matches for the keyword appear in a single response.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword (e.g. 'shadow slave', 'cultivation') |

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

### Subscribe to novel

Subscribe to a novel to receive notifications. Requires prior login call in the same session.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `slug` | string | Yes | Novel slug |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/novelbin/subscribe-to-novel \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"slug":"<string>"}'
```

## Next steps

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