Skip to main content
The Novels API lets you browse the novel library, search for titles, inspect metadata, and remove novels. All endpoints are under /api/novel and require authentication.
The list endpoint path is /api/novels (the /novel prefix + s suffix). Single-resource endpoints use /api/novel/{id}.

​
GET /api/novels

Return a paginated list of novels in the library. Query parameters
​
search
string
default:""
Free-text search against novel titles.
​
domain
string
default:""
Filter by source domain (e.g. royalroad.com).
​
offset
integer
default:"0"
Number of records to skip.
​
limit
integer
default:"20"
Maximum records to return. Cannot exceed 100.
Response — Paginated[Novel]
​
total
integer
Total matching records.
​
offset
integer
Current offset.
​
limit
integer
Current limit.
​
items
Novel[]
curl -s "http://localhost:8080/api/novels?search=overgeared&limit=5" \
  -H "Authorization: Bearer $TOKEN"

{
  "total": 1,
  "offset": 0,
  "limit": 5,
  "items": [
    {
      "id": "abc123",
      "domain": "readnovelfull.com",
      "url": "https://readnovelfull.com/overgeared.html",
      "title": "Overgeared",
      "authors": "Park Saenal",
      "synopsis": "Satisfy's top ranker...",
      "tags": ["action", "fantasy"],
      "cover_url": "https://readnovelfull.com/cover.jpg",
      "cover_file": "novels/abc123/cover.jpg",
      "cover_available": true,
      "mtl": false,
      "rtl": false,
      "manga": false,
      "language": "en",
      "volume_count": 22,
      "chapter_count": 1753,
      "created_at": 1700000000000,
      "updated_at": 1700001000000
    }
  ]
}

​
GET /api/novel/sources

Return a list of all source domains that have at least one novel in the library. Useful for populating a domain filter. Response — array of SourceItem objects.
​
url
string
Source base URL.
​
domain
string
Domain name.
​
version
integer
Crawler version number.
​
has_manga
boolean
Whether the source has manga.
​
has_mtl
boolean
Whether the source provides machine-translated content.
​
language
string
Two-letter language code.
​
is_disabled
boolean
Whether the source is currently disabled.
​
disable_reason
string | null
Reason the source is disabled, if applicable.
​
can_search
boolean
Whether the source supports novel search.
​
can_login
boolean
Whether the source supports user login.
​
total_novels
integer
Number of novels from this source in the library.
curl -s http://localhost:8080/api/novel/sources \
  -H "Authorization: Bearer $TOKEN"

​
GET /api/novel/

Return a single novel by its ID. Path parameters
​
novel_id
string
required
The novel’s unique ID.
Response — a Novel object (same fields as in the list response). 
curl -s http://localhost:8080/api/novel/abc123 \
  -H "Authorization: Bearer $TOKEN"

​
GET /api/novel//volumes

Return all volumes for a novel. Path parameters
​
novel_id
string
required
The novel’s unique ID.
Response — array of Volume objects.
​
id
string
Unique volume ID.
​
novel_id
string
Parent novel ID.
​
serial
integer
Volume number (1-indexed).
​
title
string
Volume title.
​
chapter_count
integer
Number of chapters in this volume.
​
created_at
integer
Creation time (UNIX ms).
​
updated_at
integer
Last update time (UNIX ms).
curl -s http://localhost:8080/api/novel/abc123/volumes \
  -H "Authorization: Bearer $TOKEN"

​
GET /api/novel//chapters

Return a paginated list of chapters for a novel. Path parameters
​
novel_id
string
required
The novel’s unique ID.
Query parameters
​
offset
integer
default:"0"
Number of records to skip.
​
limit
integer
default:"20"
Maximum records to return. Cannot exceed 100.
Response — Paginated[Chapter] (see Chapters API for chapter field descriptions). 
curl -s "http://localhost:8080/api/novel/abc123/chapters?limit=50" \
  -H "Authorization: Bearer $TOKEN"

​
GET /api/novel//artifacts

Return the latest artifacts (generated e-book files) for a novel. Path parameters
​
novel_id
string
required
The novel’s unique ID.
Response — array of Artifact objects (see Artifacts API for field descriptions). 
curl -s http://localhost:8080/api/novel/abc123/artifacts \
  -H "Authorization: Bearer $TOKEN"

​
DELETE /api/novel/

Permanently remove a novel and all its associated data from the library.
This action is irreversible and deletes all chapters, volumes, and artifacts for the novel. Requires admin privileges.
Path parameters
​
novel_id
string
required
The novel’s unique ID.
Response — true on success. 
curl -s -X DELETE http://localhost:8080/api/novel/abc123 \
  -H "Authorization: Bearer $TOKEN"

Build docs developers (and LLMs) love

Get started for freeTalk to us