How Answers Are Shaped

Conventions across every route

  • JSON, GET only. Every route answers JSON. There is no write route.
  • A list is {"items": [...], "total": N}, sometimes with a little more (skip, chapter_count, status_counts). A record is the object itself. See Paging and caps.
  • An error is {"detail": "...", "code": "..."}: detail is one plain sentence a person can act on, and code is stable. Branch on code; the sentence may be reworded. See Errors.
  • A novel is named by its RandomTranslator id, a number (1234). Its page is https://randomtranslator.com/novel/{id}/{slug}, and a chapter's is https://randomtranslator.com/novel/{id}/{slug}/chapter-{n}, where slug comes with the novel. Link the RandomTranslator page wherever you show the data.
  • Chapters are named by their number in the novel, sequence_number (the n of the chapter URL). A chapter's id is internal; use the number.
  • Titles and names come in two languages: original_title and translated_title, original_author and translated_author, a glossary term's original_name and translated_name. The original is Chinese. The English can be null until it is translated.
  • Missing facts are null. An empty list is [].
  • Some figures are already formatted for display, as the site shows them: word_count ("4.6M", "3.1K") and reader_count ("8.1K"). Counts that are numbers (chapter_count, total, total_occurrences, rating_count) are raw integers.
  • Dates and times are ISO 8601 in UTC (2026-11-01T20:14:03Z).
  • Values from a list are as the reference shows them: reading statuses are upper case (READING, PLAN_TO_READ, PAUSED, COMPLETED, DROPPED), notification types too (CHAPTER_UPDATE); sorts and views are lower case.
  • English only. Every answer is in English. Original Chinese titles and names appear as data (original_title, original_name) where they exist.
  • Personal fields. Some answers about a novel add fields about you (user_reading_status, current_chapter_sequence, user_bookmarked); they are always about the key's own account.
  • Parameters. A parameter a route does not have is ignored. A value out of its range (limit=500) is a 422.

Stable fields#

The fields shown in the trimmed answers in the API reference are stable: they keep their name, type and meaning inside /api/v1 (Versioning). Answers carry more fields than that: they are the website's own, can change, and are described in the OpenAPI document. Build on the stable ones.