API & MCP for developers

RandomTranslator has two ways in for code and AI assistants:

• a small public catalogue API that needs no sign-in, and
• an MCP connector for Claude, ChatGPT and other assistants, behind the reader's own RandomTranslator sign-in.

Neither one translates, requests or scrapes a novel. They read what the site already holds.

Public API#

Base URL: https://randomtranslator.com/api/v1. JSON over HTTPS, no key, no token.

Stability#

The routes below are the public subset. For them we promise:

• The stable fields listed under each route keep their name, type and meaning. We may add fields; we do not remove or rename a stable field without a changelog entry and at least 30 days' notice here.
• Every other field in a response, and every route not listed here, is the website's own and can change without notice. Read only the stable fields.
• Ask for view=card where a route offers it. It is the lean, stable shape.

Routes#

Search and filter the catalogue

GET /novels/

Stable fields (view=card): total, and per item id, slug, original_title, translated_title, original_author, translated_author, translated_category, status, image_url, synopsis (plain English, at most 280 characters), novel_metadata.word_count, novel_metadata.reader_count, novel_metadata.rating_count, novel_metadata.score_percent.

Genres, fandoms and tags

GET /novels/hub

Every genre, fandom and tag with its number of works. An entry's name is the exact value the search filters take. Cached for an hour.

Stable fields: totals, genres[].name, genres[].count, fandoms[].name, fandoms[].count, tags[].name, tags[].count, tags[].group, tag_groups[].slug, tag_groups[].label.

Popular

GET /novels/popular/{range} with range one of daily, weekly, monthly, all_time.

Stable fields: the card fields above, plus list_move (places climbed since about 24 hours ago; negative fell; null when new or nothing to compare) and list_new.

Is this novel on RandomTranslator?

GET /novels/lookup?title=&author=

The novel held under this exact title (Chinese or English, case-insensitive), or null. With author, a novel by another author does not match. Cache-Control: public, max-age=120.

Stable fields: novel_id, slug, title, card (the card fields above).

Which chapters exist

GET /novels/{id}/chapters/sequences

Stable fields: ranges, every run of consecutive chapter numbers as [first, last].

Recap outline

GET /novels/{id}/recaps?view=structure

The novel's volume and arc outline with no story text. Without view=structure the answer contains recap text, which spoils the story; we do not promise its shape.

Similar novels

GET /ai/similar/{id}?limit= (limit at most 20)

Novels this novel's readers also read. No AI call happens here; the name is historical. Cache-Control: public, max-age=300.

Stable fields: novel_match, items[].id, items[].slug, items[].translated_title, items[].original_title, items[].chapter_count.

Errors#

Errors are JSON, {"detail": "...", "code": "..."}:

Examples#

# Completed novels with the "System" tag, best rated first, lean rows
curl -s 'https://randomtranslator.com/api/v1/novels/?status=completed&include_tags[]=System&sort_by=score&limit=10&view=card'

# What is popular this week, without fan-fiction
curl -s 'https://randomtranslator.com/api/v1/novels/popular/weekly?include_fanfiction=false&view=card'

# Every genre, fandom and tag the filters accept
curl -s 'https://randomtranslator.com/api/v1/novels/hub'

# Do you have this novel?
curl -s --get 'https://randomtranslator.com/api/v1/novels/lookup' --data-urlencode 'title=斗破苍穹'

# Its chapter numbers, then readers-also-read
curl -s 'https://randomtranslator.com/api/v1/novels/12345/chapters/sequences'
curl -s 'https://randomtranslator.com/api/v1/ai/similar/12345?limit=10'

Use RandomTranslator in Claude and ChatGPT#

The connector lets an assistant search the catalogue, read your library and reading position, tell you which novels got new chapters, look up a novel's glossary, and recap a novel up to where you are.

Connector URL: https://randomtranslator.com/mcp

Claude: Settings, Connectors, Add custom connector. Paste the URL, press Add, then Connect. Sign in with Patreon when asked, read what the app may do, and press Allow.

ChatGPT: turn on Developer mode (Settings, Apps and Connectors, Advanced settings), then add a custom connector with the URL above and OAuth sign-in. Sign in with Patreon when asked and press Allow.

You can see and disconnect every connected app on your account page under Connected apps. Signing out everywhere also disconnects them all.

What the connector never does: translate or re-translate a chapter, request or refresh a novel, use Google Translate, read aloud, change anything on your account, or show chapter text.

OAuth for apps#

Third-party apps use the same OAuth 2.1 server as the assistants. RandomTranslator is its own authorization server; it is separate from DaoSearch's and does not accept DaoSearch tokens.

• Discovery: https://randomtranslator.com/.well-known/oauth-authorization-server and https://randomtranslator.com/.well-known/oauth-protected-resource/mcp.
• Register: POST https://randomtranslator.com/oauth/register (RFC 7591) with client_name, redirect_uris (https, or http://127.0.0.1 / http://localhost on any port) and token_endpoint_auth_method: "none" (a public client, the default and the right choice for a mobile or desktop app). A server-side app may ask for client_secret_post or client_secret_basic; its secret is shown once, in the registration answer. Redirect URIs are https, or http on localhost, 127.0.0.1 or [::1]. Limit: 30 registrations an hour per address.
• Authorize: https://randomtranslator.com/oauth/authorize with PKCE S256 (required; plain is refused), state, scope, and resource=https://randomtranslator.com/mcp. The reader signs in with Patreon and sees a consent page. The redirect carries code, state and iss.
• Token: POST https://randomtranslator.com/oauth/token, grants authorization_code and refresh_token. Access tokens last 1 hour. Refresh tokens last 60 days and rotate on every use: keep the new one, because sending a used one again disconnects the app.
• Revoke: POST https://randomtranslator.com/oauth/revoke (RFC 7009).
• Use the token only against https://randomtranslator.com/mcp. It does not work on /api/v1.

Scopes:

Without a scope, an app gets all four. Chapter text is reserved for RandomTranslator's own apps and is not available to third-party apps or connectors.

Limits and fair use#

• Public API: 120 requests a minute and 30 in any 5 seconds per address. Cache what you fetch; the catalogue changes slowly.
• Connector and OAuth apps: 60 calls a minute and 2,000 a day for each connected app (the day resets at 00:00 UTC).
• Do not mirror the catalogue or chapters, resell access, or use the API to get around the paid tier. We disconnect apps and block addresses that do.
• We can switch the connector off at any time to protect the site.

Questions, or a higher limit for a good reason: Contact, or Discord.

Changelog#

• 2026-11: Public catalogue API documented. MCP connector and OAuth for apps.