libsocial-core API reference

Translation to use for every chapter that has more than one — same meaning as get_chapter(..., branch_id=...), applied title-wide. Chapters with only one translation are unaffected. Mutually exclusive with translation_index.

Alternative to branch_id: pick the translation at this position in each ambiguous chapter's branches list (0 for the first, and so on) — useful when ambiguous chapters don't share one branch_id across the title. Mutually exclusive with branch_id.

Extra delay, in seconds, after fetching each chapter, on top of ApiClient's own per-request pacing — to be gentler on the API during a large bulk download. Defaults to no extra delay.

Called with (completed, total) after each chapter is fetched, if given — a programmatic progress hook for callers that aren't printing to a console (e.g. a web app polling/streaming download progress to a browser), who would otherwise have no way to observe anything before this whole await returns. Independent of verbosity: both can be set at once, each drives its own output.

How many extra times to retry a single chapter fetch that comes back rate-limited, on top of ApiClient's own retries, before giving up on the whole download — see above. Each retry honors the API's Retry-After if it sent one, otherwise waits with its own capped exponential backoff. Set to 0 to disable this extra layer and let a persistent RateLimitError end the download immediately (still wrapped in DownloadTitleInterruptedError with whatever was already fetched).

If both branch_id and translation_index are given.

If the title has one or more chapters with more than one translation that branch_id/translation_index didn't resolve.

If fetching a chapter fails unrecoverably partway through the download — carries every chapter already fetched.

The chapter's volume number.

The chapter number, as returned by the API — may contain a decimal (e.g. "51.6").

Which translation to fetch, as returned by get_translations(). Only required when the chapter has more than one.

Bypass the disk cache and re-fetch from the API even if a cached response is on hand.

If the chapter has more than one translation and branch_id wasn't given.

A list of (volume, number) pairs identifying each chapter.

If any requested chapter doesn't exist.

If any requested chapter has more than one translation.

Bypass the disk cache and re-fetch from the API even if a cached response is on hand.

Bypass the disk cache and re-fetch from the API even if a cached response is on hand — needed to pick up newly published chapters, since otherwise the cached chapter list would keep being reused.

The chapter's volume number.

The chapter number.

If no chapter exists for this volume/number.

The volume number.

If the title has no chapters for this volume.

If any of the volume's chapters has more than one translation.

The volume numbers to fetch.

If the title has no chapters for one of the volumes.

If any of the volumes' chapters has more than one translation.

Bypass the disk cache and re-fetch from the API even if the country list was already cached.

Every Country (id, name) that applies to site.

Bypass the disk cache and re-fetch from the API even if the genre list was already cached.

Every Genre (id, name, adult flag) that applies to site.

Bypass the disk cache and re-fetch from the API even if the status list was already cached.

Every status (Label: id, label) that applies to site.

1-based page number.

How many titles per page. Must be between MIN_PER_PAGE (10) and MAX_PER_PAGE (60) — the API's own limits (see docs/api-notes.md); anything outside that range raises here instead of a confusing 422 from the API.

Free-text search term, matched against name/rus_name/eng_name. None (the default) or an empty string lists without searching.

Genre ids to filter by. A title must have all of them, not just one (AND, not OR — see docs/api-notes.md). Not validated against list_genres() before sending — an unrecognized id just matches nothing rather than erroring.

Tag.ids (from Title.tags) to filter by. Same AND semantics as genres — a title must have all of them, not just any one (confirmed against the live API, see docs/api-notes.md; not the OR some might expect from tags being more numerous/specific than genres). Also not validated before sending, same as genres.

Title.status.ids to filter by (e.g. ongoing, completed). A title matches if its own status is any of these (OR, same as countries — a title only has one status, see docs/api-notes.md). None or an empty list applies no status filter. Ids come from list_statuses().

Country.ids to filter by. A title matches if its own country is any of these (OR, not AND like genres/tags — a title only has one country of origin, so requiring all of them could never match past the first, see docs/api-notes.md). None or an empty list applies no country filter. Ids come from list_countries(). Sent on the wire as the API's types[] parameter, not a country/countries[] one — see docs/api-notes.md for why (Country mirrors the API's own "type" concept, which isn't strictly limited to literal countries).

Only titles with at least this many chapters (inclusive). Counts the same number as Title.chapter_count (uploaded chapters). None (the default) applies no lower bound.

Only titles with at most this many chapters (inclusive). None (the default) applies no upper bound.

Sort order. Despite the name, this is sent as the API's sort_by parameter — an actual sort parameter exists but is silently ignored by the API (see docs/api-notes.md). Known accepted values: "name", "created_at", "views", "chap_count", "last_chapter_at" (the default), "rate_avg", "random" — this list isn't guaranteed exhaustive.

Bypass the disk cache and re-fetch from the API even if this exact combination of parameters was already cached.

A page_model page: the matching titles plus whether a next page exists.

If page is less than 1, per_page is outside MIN_PER_PAGE..MAX_PER_PAGE, min_chapters/max_chapters is negative, or min_chapters is greater than max_chapters.

The title's {id}--{slug} identifier.

The chapter number, as returned by the API (may contain a decimal).

The volume number.

Which translation team's branch to fetch, for chapters with more than one. Defaults to whichever branch the API picks (see docs/api-notes.md — this is not simply the first branch listed).

The data object from the API response.

The title's {id}--{slug} identifier.

The data array from the API response.

The title's {id}--{slug} identifier.

Extra fields[] values to request from the API.

The data object from the API response.

The raw data.types array from the API response, unfiltered by site.

The raw data.genres array from the API response, unfiltered by site.

The raw data.status array from the API response, unfiltered by site.

1-based page number.

Page size. The API only accepts 10..60 (validated by the caller, see Catalog.list_titles); values outside that raise here via a 422.

Free-text search term, matched against name/rus_name/eng_name. None or empty omits the q parameter entirely.

Genre ids to filter by. A title must have all of them (AND, not OR — see docs/api-notes.md), not just any one.

Tag ids to filter by. Same AND semantics as genres — a title must have all of them, not just any one (see docs/api-notes.md).

Title.status.ids to filter by. A title matches if its own status is any of these (OR, like countries — a title only has one status, see docs/api-notes.md). Sent on the wire as repeated status[] parameters.

Country.ids to filter by. A title matches if its own country is any of these (OR, not AND like genres/tags — a title only has one country, confirmed against the live API, see docs/api-notes.md). Sent on the wire as repeated types[] parameters — the API's own name for this concept is "type", not "country" (see docs/api-notes.md).

Minimum chapter count, inclusive. Sent as chap_count_min.

Maximum chapter count, inclusive. Sent as chap_count_max.

Forwarded as the API's sort_by parameter, not sort — the API silently ignores an actual sort parameter (see docs/api-notes.md); this mismatch between the SDK's public keyword and the wire parameter name is deliberate, not a typo.

The full JSON response: {"data": [...], "meta": {...}, "links": {...}}.

Minimum time, in seconds, before the next request (from any client sharing this pacer) may start after this one. Each caller passes its own, so clients with different delays can share a pacer.

Sleep function to wait with — the calling client's, so tests that inject a fake one don't actually wait.