royalroad.com APIwww.royalroad.com ↗
Access Royal Road fiction data via API. Search by title, tags, and genre. Retrieve ratings, chapter lists, stats, and content warnings for any fiction.
curl -X GET 'https://api.parse.bot/scraper/195f0514-c4a2-4100-87c0-84b79b177517/search_fictions' \ -H 'X-API-Key: $PARSE_API_KEY'
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.
| Param | Type | Description |
|---|---|---|
| page | string | Page number for pagination. |
| genre | string | Genre filter. Accepts: action, adventure, comedy, contemporary, drama, fantasy, historical, horror, mystery, psychological, romance, satire, sci_fi, short_story, thriller, tragedy. |
| title | string | Title or keyword to search for in fiction titles and descriptions. |
| order_by | string | Sort order for results. Accepts: relevance, popularity, rating, name, pages, readers, date. |
| tags_add | string | 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 | Tag to exclude from results. Uses the same tag identifiers as tags_add. |
{
"type": "object",
"fields": {
"page": "integer",
"count": "integer",
"results": "array of fiction summaries with fiction_id, title, url, cover_url, tags, labels, rating, followers, pages, views, chapters",
"total_pages": "integer"
},
"sample": {
"page": 1,
"count": 20,
"results": [
{
"url": "https://www.royalroad.com/fiction/65629/the-game-at-carousel-a-horror-movie-litrpg",
"tags": [
"LitRPG",
"Urban Fantasy",
"Progression"
],
"pages": 4306,
"title": "The Game at Carousel: A Horror Movie LitRPG",
"views": 7954762,
"labels": [
"Original",
"STUB"
],
"rating": 4.81,
"chapters": 443,
"cover_url": "https://www.royalroadcdn.com/public/covers-large/65629-the-game-at-carousel-a-horror-movie-litrpg.jpg?time=1681708250",
"followers": 10603,
"fiction_id": "65629"
}
],
"total_pages": 1068
}
}About the royalroad.com API
The Royal Road API exposes 3 endpoints for discovering and retrieving web fiction data from royalroad.com. Use search_fictions to query by title keyword, genre, or tag filters, list_fictions to pull ranked category feeds like best-rated or trending, and get_fiction to fetch a full detail record including five-dimension ratings, follower counts, chapter lists, and content warnings.
Search and Browse Fictions
The search_fictions endpoint accepts a title keyword along with optional genre, tags_add, and tags_remove parameters. Tags use snake_case identifiers (e.g. litrpg, summoned_hero, female_lead). Results are paginated at 20 items per page and can be sorted via order_by using values like relevance, popularity, rating, pages, or date. Each result in the results array includes fiction_id, title, url, cover_url, tags, labels, rating, followers, pages, views, and chapters.
Category Listings
The list_fictions endpoint retrieves fictions from Royal Road's ranking and browsing pages. The category parameter accepts values including best-rated, trending, active-popular, complete, and weekly-popular. Response pagination varies by category (20–50 items per page). The response shape mirrors search_fictions, returning the same fiction summary fields plus a category string confirming which feed was queried.
Fiction Detail Records
The get_fiction endpoint takes a numeric fiction_id (available from either listing endpoint) and returns a full detail record. The ratings object breaks down into five scores: overall_score, style_score, story_score, grammar_score, and character_score. Additional fields include author, warnings (content warnings as an array of strings), favorites, followers, cover_url, labels, tags, and a chapters array where each entry contains title, url, and date.
- Build a fiction recommendation engine filtered by genre and tags like
litrpgorsummoned_hero - Track weekly trending fictions using
list_fictionswith theweekly-popularcategory - Monitor follower and favorites growth for specific fiction IDs over time via
get_fiction - Aggregate Royal Road's five-dimension rating scores to rank authors by
grammar_scoreorcharacter_score - Compile chapter release histories for a fiction using the
chaptersarray with publication dates - Filter out fictions with specific content warnings when building a reader-facing discovery tool
- Index Royal Road's
best-ratedandcompletecategories to surface finished, high-quality stories
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 250 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Royal Road have an official developer API?+
What does `get_fiction` return for ratings, and how granular is the breakdown?+
ratings object contains five fields: overall_score, style_score, story_score, grammar_score, and character_score. These correspond directly to the rating dimensions Royal Road displays on each fiction page. Raw vote counts are not included in the current response.Can I retrieve the full text content of individual chapters?+
chapters array in get_fiction returns each chapter's title, url, and date, but not the body text. The API covers search, listing, and fiction-level metadata. You can fork it on Parse and revise to add a chapter-content endpoint.How does tag filtering work in `search_fictions`?+
tags_add parameter includes only fictions that carry the specified tag, while tags_remove excludes fictions with that tag. Both use the same snake_case identifiers. Currently only a single tag value is accepted per parameter per request; multi-tag filtering in one call is not supported. You can fork the API on Parse and revise it to support passing multiple tag values simultaneously.