Addon guide
Provider API
Expose catalogues, search, metadata, chapters, and images through a normalized HTTP API that users can install in Ink Reader.
The addon model
A provider addon is a server, not a script bundle. Ink Reader stores the user's API root, discovers the providers offered by that server, and requests normalized data. Site-specific parsing and network behavior remain outside the app.
If a user installs https://example.com/api/v1, the app resolves endpoints beneath that exact root. Do not assume the host root or a fixed deployment layout.
The server may offer one provider or many. Each provider has its own stable ID, capabilities, catalogues, filters, and source paths.
Installation
The easiest flow is a small website with an install button. The button opens Ink Reader using a deep link containing the encoded API root. The app then shows the available providers and lets the user choose which ones to enable.
ink-reader://install-addon?url=https%3A%2F%2Fexample.com%2Fapi%2Fv1During development, add the server manually in Ink Reader or use a development deep link. Production addons should use HTTPS and keep their API root stable.
Core endpoints
The full schemas and query parameters live in the OpenAPI document. This is the smallest useful map of the contract.
/healthService health and version information./providersInstallable providers and their capabilities./providers/{provider}Provider metadata, catalogues, and search filters./providers/{provider}/catalogs/{catalog}One paginated catalogue./providers/{provider}/searchSearch with provider-supported filters./providers/{provider}/novelNormalized book metadata and chapter index./providers/{provider}/dotbookStreamable Dotbook manifest and resources./providers/{provider}/chapterSanitized chapter content./providers/{provider}/imageProxied source artwork with a safe media type.curl --fail --silent \
https://addons.pplx-pro.com/api/v1/providersResponses and caching
Return predictable JSON and appropriate HTTP status codes. List responses should expose pagination rather than forcing clients to load an entire site. Content that can be cached should include enough source identity to avoid collisions across providers.
- 200 for a successful normalized result.
- 400 for malformed or unsupported input.
- 404 when a source path no longer resolves.
- 429 when the provider needs the client or upstream worker to slow down.
- 502/503 for temporary upstream failures, with a retry hint when possible.
Servers should cache catalogue pages, metadata, chapter indexes, chapter content, and images. Use upstream validators where available. Avoid aggressive refreshes: book chapters are usually immutable, while catalogues and book metadata can use shorter lifetimes.
Use the provider ID plus normalized source path or stable source ID. A book should not become a different book merely because the addon host moved.
Implementation checklist
- Give the provider a stable, lowercase ID and public display name.
- Implement provider metadata and at least one catalogue or search capability.
- Normalize book metadata and return a stable, ordered chapter index.
- Sanitize chapter markup into supported content; never pass executable scripts to clients.
- Validate every source path against the provider's expected hosts and path shapes.
- Proxy images only from approved upstream hosts and enforce size and media-type limits.
- Add deterministic fixture-based tests. Routine tests must not depend on a live third-party site.
- Apply caching, pacing, retries with jittered exponential backoff, and clear temporary errors.
- Keep the OpenAPI contract and implementation in sync.
Provider boundaries
The provider implementation owns upstream requests, parsing, anti-abuse pacing, cache policy, and source quirks. Ink Reader owns presentation, user configuration, and local reading state. Keeping that boundary clean makes an addon replaceable without changing the reader.
Next steps
Start against the OpenAPI specification, then compare your responses with the public server. If your source can return normalized chapters and stable resource IDs, consider exposing the same books through the streamable Dotbook profile.