Twkan APItwkan.com ↗
Access twkan.com novel listings, full chapter text, keyword search, and detail records via a structured API. 5 endpoints covering ranked lists, TOC, and content.
What is the Twkan API?
The twkan.com API provides 5 endpoints for reading free Chinese web novels from twkan.com, covering ranked novel listings, keyword search, full novel detail records, complete chapter tables of contents, and per-chapter text retrieval. The get_chapter endpoint returns chapter text as both an ordered paragraph array and a newline-joined string, along with adjacent chapter IDs for sequential reading.
curl -X GET 'https://api.parse.bot/scraper/28add905-136f-4ef9-8e0e-5d555e388124/list_novels?sort=popular&status=completed&category=urban' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace twkan-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: twkan.com novel SDK — browse rankings, drill into a novel, read chapters."""
from parse_apis.twkan_com_api import Twkan, Category, Sort, Status, InputNotFound
client = Twkan()
# Browse popular completed urban novels; limit= caps total items fetched.
for summary in client.novel_summaries.list(
category=Category.URBAN, status=Status.COMPLETED, sort=Sort.POPULAR, limit=5
):
print(summary.title, summary.author, summary.status)
# Search by keyword, take the first hit, then drill into full detail.
hit = client.novel_summaries.search(keyword="獵人", limit=1).first()
if hit is not None:
novel = hit.details()
print(novel.title, novel.author, novel.chapter_count, novel.rating)
print("Tags:", ", ".join(novel.tags))
# List the first few chapters from the table of contents.
for ch_summary in novel.chapters.list(limit=3):
print(f" #{ch_summary.index} {ch_summary.title} ({ch_summary.word_count} chars)")
# Read the full text of the first chapter.
first_ch = novel.chapters.list(limit=1).first()
if first_ch is not None:
chapter = novel.chapters.get(chapter_id=first_ch.chapter_id)
print(chapter.title)
print(chapter.content[:200])
# Point lookup by a known novel_id.
try:
detail = client.novels.get(novel_id="82888")
print(detail.title, detail.word_count_label)
except InputNotFound:
print("Novel not found")
print("exercised: novel_summaries.list / novel_summaries.search / details / novels.get / chapters.list / chapters.get")
Lists novels from the site's ranking pages, filtered by category and completion status and ordered by one of the site's three rankings (new books, weekly popularity, recommendations). Returns one page of up to 30 novel summaries per call; pass page to move through the result space (page 1 when omitted) and use has_more / total_pages for continuation. The per-item category field is not shown on these ranking pages and is always null here; use get_novel for a novel's category. Descriptions are the site's own truncated blurbs; latest_chapter_id can be passed to get_chapter.
| Param | Type | Description |
|---|---|---|
| page | integer | 1-based result page. Each page holds up to 30 novels. |
| sort | string | Ranking to list: new (newest books), popular (weekly visits), recommended (all-time recommendation votes). |
| status | string | Completion filter; all = both ongoing and completed novels, completed = finished novels only. |
| category | string | Genre filter from the site's category menu; all = no genre filter. |
{
"type": "object",
"fields": {
"page": "integer, the page that was returned",
"novels": "array of novel summaries: novel_id (string, use with get_novel/list_chapters), title, author, category (always null on this endpoint), status (site label, e.g. 連載 ongoing / 全本 completed), description, cover_url, latest_chapter_id, latest_chapter_title",
"has_more": "boolean, true when a following page exists",
"total_pages": "integer, number of pages the site reports for this ranking/filter"
},
"sample": {
"data": {
"page": 2,
"novels": [
{
"title": "誤吞了秦皇陵仙丹",
"author": "二兩消愁",
"status": "全本",
"category": null,
"novel_id": "111151",
"cover_url": "https://twkan.com/files/article/image/111/111151/111151s.jpg",
"description": "秦始皇陵失竊，剛大學畢業正在出租屋待業的王浩，誤打誤撞獲得失竊秦皇陵文物。",
"latest_chapter_id": "58214404",
"latest_chapter_title": "第984章 大結局"
}
],
"has_more": true,
"total_pages": 16
},
"status": "success"
}
}About the Twkan API
Novel Discovery and Search
The list_novels endpoint returns up to 30 novel summaries per page drawn from the site's ranking pages. Three sort modes are available: new (newest additions), popular (weekly visit ranking), and recommended (all-time recommendation votes). Results can be narrowed by category (genre label from the site's menu) and status (all or completed). Each summary includes novel_id, title, and author; note that category is always null on this endpoint. The search_novels endpoint accepts a keyword (typically a partial Chinese title) and returns up to 20 matches per page, including category, status, description, and a total_results count from the site.
Novel and Chapter Detail
The get_novel endpoint fetches a single novel's full record by novel_id: title, author, category, status (連載 or 全本), description, cover_url, rating (out of 5 or null), tags array, updated_at, and additional metadata. Passing an unknown or removed novel_id returns a stale_input error rather than empty results.
The list_chapters endpoint returns the complete, unpaginated table of contents for a novel in reading order. Each entry carries index, chapter_id, title, word_count, and publish time. Long novels with several hundred chapters are returned in a single response. The get_chapter endpoint resolves a chapter_id (as emitted by list_chapters, or the latest_chapter_id from novel summaries) into the full chapter: paragraphs array, content string, author, updated_at, and prev_chapter_id / next_chapter_id for cursor-based sequential reading.
Identifiers and Navigation
All identifiers are numeric strings. novel_id flows from list_novels or search_novels into get_novel, list_chapters, and get_chapter. chapter_id flows from list_chapters into get_chapter. The prev_chapter_id and next_chapter_id fields on chapter responses allow walking an entire novel sequentially without re-fetching the table of contents.
The Twkan API is a managed, monitored endpoint for twkan.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when twkan.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official twkan.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a Chinese web novel reader app that navigates chapters using prev_chapter_id and next_chapter_id
- Index a corpus of novel blurbs and tags from get_novel for a recommendation or similarity search system
- Track weekly popularity ranking shifts by polling list_novels with sort=popular across dates
- Monitor newly published chapters for a watchlist of novel_ids using updated_at from get_novel
- Compile word-count statistics per chapter for a given novel using the word_count field from list_chapters
- Search twkan.com by partial title keyword and surface category and status labels for a discovery UI
- Aggregate completed novels by genre by combining status=completed and category filters in list_novels
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.