# Royal Road — 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 discover web fiction on Royal Road by title, tags, genres, and categories, then access comprehensive details like ratings, statistics, chapters, and content warnings for each story. Browse the platform's vast collection of fictions with filtered results and in-depth information to find your next favorite read.

**Category:** Entertainment | **Website:** [www.royalroad.com/home](https://www.royalroad.com/home) | **Docs:** [parse.bot/marketplace/0dd7813f-8ee7-40a5-b343-21da89b81b95/royalroad-com-api](https://parse.bot/marketplace/0dd7813f-8ee7-40a5-b343-21da89b81b95/royalroad-com-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/royal-road/`
**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 fiction

Get detailed information about a specific fiction including description, author, ratings (overall, style, story, grammar, character), statistics, content warnings, tags, and chapter list.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `fiction_id` | string | Yes | Numeric fiction ID from Royal Road (e.g. '8300'). Available from search_fictions or list_fictions results. |

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

### List fictions

List fictions from a specific category/ranking page on Royal Road. Returns paginated results with 20-50 items per page depending on category.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Category to list. Accepts exactly one of: best-rated, trending, active-popular, complete, weekly-popular, latest-updates, new, rising-stars, writathon. |
| `page` | string | No | Page number for pagination. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/royal-road/list-fictions \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","page":"<string>"}'
```

### Search fictions

Search fictions by title keyword, tags, genre, and ordering. Returns paginated results with 20 items per page. Supports filtering by included/excluded tags and genre.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `genre` | string | No | Genre filter. Accepts: action, adventure, comedy, contemporary, drama, fantasy, historical, horror, mystery, psychological, romance, satire, sci_fi, short_story, thriller, tragedy. |
| `order_by` | string | No | Sort order for results. Accepts: relevance, popularity, rating, name, pages, readers, date. |
| `page` | string | No | Page number for pagination. |
| `tags_add` | string | No | Tag to include in results. Use snake_case tag identifiers such as: litrpg, summoned_hero, male_lead, female_lead, sci_fi, strong_lead, adventure, fantasy, reader_interactive, supernatural, magic, progression, action, gamelit, high_fantasy, deck_building, post_apocalyptic, low_fantasy, dungeon_crawler, urban_fantasy, contemporary, grimdark, mystery, survival, crafting, comedy, slice_of_life, local_protagonist, apocalypse, villainous_lead, multiple_lead, drama, romance, space_opera, psychological, first_contact, soft_sci-fi, strategy, harem, non-human_lead, secret_identity, attractive_lead, war_and_military, mythos, kingdom_building, technologically_engineered, artificial_intelligence, modern_knowledge, magitech, anti-hero_lead, super_heroes, horror, satire, system_invasion, school_life, martial_arts, historical, dystopia. |
| `tags_remove` | string | No | Tag to exclude from results. Uses the same tag identifiers as tags_add. |
| `title` | string | No | Title or keyword to search for in fiction titles and descriptions. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/credits/royal-road/search-fictions \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"genre":"<string>","order_by":"<string>","page":"<string>","tags_add":"<string>","tags_remove":"<string>","title":"<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.