Skip to content

Search an EPUB's text

GET
/assets/{id}/epub/search

Finds text in the chapters of an EPUB asset and returns each match with its chapter and a short excerpt.

Matching ignores case and looks for the exact characters, so “run” also matches “running” and “brunch”; there’s no stemming or whole-word matching. Each chapter’s text is searched with tags removed and spaces collapsed, including the title in its head but not scripts or styles. Chapters are searched in reading order, up to 5 matches per chapter and 200 in all, and a chapter that can’t be read is skipped without notice, so results can be incomplete. Results aren’t cached, so each search that goes ahead opens the book again.

You need to be signed in, and any account can search any EPUB asset. A q shorter than 2 bytes once surrounding spaces are trimmed, such as a single ASCII letter, returns an empty list without looking up the asset, so it says nothing about whether the asset exists. A 404 means no asset has that id, it’s in the trash or it has no stored file. A missing or repeated q gets a plain-text 400, and server errors get a plain-text 500, not the JSON shown.

id
required
string format: uuid

The id of the EPUB asset.

q
required
string
>= 1 characters

The text to find. Surrounding spaces are trimmed and case is ignored. Anything shorter than 2 bytes, an empty q included, returns an empty list.

The matches, in reading order. The list can be empty.

Array<object>

One match from an EPUB search.

object
chapter_idx
required

The position of the chapter the match is in, as idx in the chapter list.

integer
chapter_label
required

Currently always “Chapter N”, with N = chapter_idx + 1, not the label the chapter list shows.

string
snippet
required

An excerpt of the chapter’s text around char_offset: up to 60 bytes before it and up to the query’s length plus 60 bytes after it, with ”…” where the text was cut. It normally holds the match, but if lowercasing changed the length of earlier text it can be shifted. The cut is made by bytes, so a character at either end can come out broken.

string
char_offset
required

Where the match starts, as a byte offset (not a character count) into the chapter’s text with tags removed, spaces collapsed and letters lowercased. Lowercasing can change the length of some non-ASCII text, so the offset may not line up with the original text.

integer

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Unexpected server error

object
error
required

Human-readable error summary

string
Example
the request could not be completed