API reference

One ranked page mixing all three kinds, ordered by full-text relevance. Every result carries a kind discriminator.

Matching is by whole word or word prefix (the last word of the query is treated as a prefix), over work titles and subtitles and the names of authors, narrators and series. Punctuation is a word boundary on both sides, so "Halo: Primordium", "Halo.Primordium" and "Halo Primordium" are the same query - except that a run of single-letter fragments (an initialism) stays one adjacent phrase, so "Q&A" and "M*A*S*H" keep their selectivity rather than matching every row holding those letters apart. A possessive matches in either spelling: a word of four or more characters ending in a single s also matches the possessive it may be with its apostrophe dropped, so "enders game" finds "Ender's Game", and a possessive written with its apostrophe also matches the word stored without one, so "finnegan's wake" finds "Finnegans Wake".

Two boosts run ahead of the relevance hits. A query that IS a work's title - compared whole, ignoring case, spacing and punctuation, including a possessive's apostrophe - returns that work FIRST; several works sharing the title all lead, in id order. A query that names a series and a number - "jack reacher 2", "jack reacher book 2", "jack reacher #2" - resolves that volume and returns it next. An exact title leads a resolved volume, since the title is an equality and the volume an inference. The page stays exactly limit long, so a boost costs the last hit rather than widening the response, and a query that resolves neither returns the plain relevance page.

lang narrows the page to works in the named languages, inside the query - so ?lang=de&limit=20 returns up to 20 German hits - and the boosts obey it too: a work outside the filter never leads. People always pass (a person has no language), and so does a series whose members tie between languages.

The combined search restricted to works. Results are WorkResult objects, identical to the work entries of /api/v1/search, and the filter is applied inside the query - so ?limit=20 returns up to 20 works rather than the works among 20 mixed hits.

Both search boosts apply here too: a query that is a work's title returns that work first, and "jack reacher 2" returns volume 2, exactly as on the combined search.

The combined search restricted to people (authors and narrators share one record, so a person may be either or both). Results are PersonResult objects. Neither search boost applies - what they resolve is always a work.

The combined search restricted to series. Results are SeriesResult objects, each carrying the series' member count and its derived language. Neither search boost applies - what they resolve is always a work.

lang matches a series by its DERIVED language - the language most of its members are in. A series whose members tie derives none and passes every filter: it is the series that holds volumes in the language asked for.

Identify the work an audiobook FILE is, from the facts its tags and its folder path state, each of which may be wrong. Unlike works/search, which needs every word of one query, this takes the facts separately - several title guesses, several author guesses, a series name or two and a position, a runtime, an identifier, and optionally the text a person typed - gathers candidates along each of them (the identifier, the typed text exactly as works/search reads it, every title guess, every work by the named authors, the members of the named series), and ranks every candidate by how well its own facts agree. Each result is a WorkResult plus a 0-100 score and the reasons behind it.

Scoring: within the structured facts the score is a weighted average of title (60), author (20), series (10) and runtime (10) agreement over the facts the request states, a fact left out counting neither for nor against - except that titles which identify nothing (absent, or only CD1/12-shaped) keep their weight unless the series and its position agree. Every field is judged by its best guess, so a garbage tag beside a good path costs nothing. The typed text is scored separately, read per work as the facts it states about that work (the work's author words as its author, its series words and a volume number as that volume, the rest as a title) and judged by the same rules, and the better of the two scores counts; an identifier hit scores 100. A named title that clearly disagrees outranks a numbering match, and named authors none of whom wrote a work scale its score down.

Bounds: each text value is cut to 256 bytes, at most 4 values of title and of author and 2 of series are read, an author resolves through a bounded window of people and the author and series probes add at most 2,500 works. At most 8 matches run at once, each within 2 seconds; past that the answer is a 503 with Retry-After. Nothing is cached server-side and responses carry no Cache-Control, as for the searches.

Work cards ordered by when they entered the database, newest first, with at most two works from any one series so a bulk import cannot fill the whole page with one series' volumes. Two reading orders of one franchise (a series and a chronological or recommended variant of it) count as one series for that cap. Works with no recorded date sort last.

lang lists only works in the named languages, and the series cap is taken over those.

The whole work document: the abstract book, every recording of it (narrators, runtime, publisher, identifiers, chapter count), and the community expressive layer where it exists.

characters, recaps, recap_summary, community_description and genres depend on the loaded artifact's internal schema version and are omitted - never faked - when the artifact predates them.

A slug a merge has retired answers 301 at the work that replaced it, so a stored id keeps resolving.

The chapter marks of a single recording, in playback order, with millisecond offsets. An unknown work or recording is an empty list rather than a 404: absent chapters and an absent recording are the same answer to a client rendering a timeline. The one exception is a work slug a merge has RETIRED, which answers 301 at the same recording under the surviving slug.

A person with one page of each credit list - works authored and recordings narrated. Both lists take the same window.

The lists are paged by default because a person's credits are unbounded: a corporate credit of record ("Full Cast", "Audible Studios") narrates thousands of works. authored_total and narrated_total are the UNPAGED counts, so a client can always tell it is seeing a slice.

A series with its member works in position order. Positions are strings, so a novella ("2.5") and an omnibus range ("1-3.5") stay distinct from the numbered volumes.

Unlike a person's credits this returns the WHOLE series by default: series membership is bounded by what a series is, and consumers compose a complete series rail from it. Pass limit for a window; works_total is the unpaged membership either way.

Exact identifier resolution: given an Audible ASIN or an ISBN, return the work card and the id of the recording that identifier names. Supply one of the two; if both are given, asin wins.

An ISBN is matched against recording ISBNs first and falls back to the work's print ISBNs, in which case the work's first recording is reported. Identifiers must be in their bare stored form (no hyphens).

How many works exist and how many carry each part of the community layer. A sidecar count is OMITTED (never reported as zero) when the loaded artifact predates its table, so a missing key means "unknowable here" while 0 means "genuinely none".

One filtered, searchable, paginated page of works for the coverage browser. Each row lists which parts of the community layer it still lacks.

available is false (with an empty page) when the requested filter's dimension cannot be evaluated against the loaded artifact.

One page of the series that have interior gaps: an integer position absent strictly between the lowest and highest present one. A decimal position ("2.5") fills no integer slot; an omnibus range ("1-3.5") fills every integer it spans.

An Atom 1.0 feed of recently released, newly catalogued and preorderable works in the series named by s. The series list lives entirely in the URL; the server stores no subscription or reader state. Feed readers deduplicate entries by id. Unknown series slugs are omitted and named in the subtitle, and retired slugs resolve to their surviving series. Successful responses carry Cache-Control: public, max-age=3600 and an ETag derived from the artifact, the raw parameters and the current day - the day, because the window is a rolling cutoff and a preorder becomes a release on a date.

A JSON Feed 1.1 representation of the same stateless watched-series notification feed as /api/v1/watch/feed.atom. Unknown series slugs are omitted and named in the description, and retired slugs resolve to their surviving series. Successful responses carry Cache-Control: public, max-age=3600 and an ETag derived from the artifact, the raw parameters and the current day - the day, because the window is a rolling cutoff and a preorder becomes a release on a date.

An iCalendar (RFC 5545) rendering of the same stateless watched-series feed as /api/v1/watch/feed.atom, for subscribing in Google, Apple or Outlook Calendar: swap the scheme to webcal:// and the reader polls it, with a refresh hint of 12 hours. One all-day event per dated work, on the day the release date names at the precision the catalogue states - a bare 2026 lands on 1 January and 2026-10 on 1 October, with the event description saying which precision that was. A work stating no usable release date is omitted, since an all-day event has nowhere to say the date is unknown; it is still carried by the Atom and JSON representations. The calendar carries at most 200 events, counted AFTER those undated works are left out, so they never spend a slot a dated release could have had. A work belonging to several of the watched series appears once, under the first of them. Event UIDs are stable and carry the preorder or released suffix of the feed item id, so a preorder becoming a release is a new event rather than a moved one. Successful responses carry Cache-Control: public, max-age=3600 and an ETag derived from the artifact, the representation, the raw parameters and the current day.

OUTSIDE /api/v1. This is the endpoint an Audiobookshelf server calls when https://meta.audiosilo.app/abs is configured as a custom metadata provider - Audiobookshelf appends /search to that base URL and sends its own parameters.

The response speaks Audiobookshelf's BookMetadata shape, not this API's: one match per RECORDING (a recording is what a local audiobook is matched against), capped at 10. A matched work that has no recordings yet still answers, as a single work-level match with no narrator, duration or ASIN. Only title is guaranteed; duration is in MINUTES; genres are human-facing labels from this project's own vocabulary; tags is never populated, since the data model has no tag concept.

An isbn is resolved exactly first (hyphens are tolerated); otherwise the query is a full-text work search, with author used to boost - never to filter, so a mismatched author never empties the results. No match is an empty array, never a 404.

Attribution: description is the community's own-words, spoiler-free paragraph where the work carries one, else the CC0 record's own field. A COMMUNITY description ends with a plain-text line - (Description CC BY-SA 4.0, AudioSilo Meta community) - because Audiobookshelf's shape carries no license field and the text is share-alike; the CC0 fallback carries no such line. GET /api/v1/works/{id} returns the same text and its license as separate fields.

A library in one language can rank its own language first through /abs/{lang}/search instead.

OUTSIDE /api/v1. The same provider as /abs/search, for a library in one language: configure https://meta.audiosilo.app/abs/de as the custom metadata provider and Audiobookshelf calls /abs/de/search. Audiobookshelf builds the URL by appending /search to the configured base and sends only its own parameters, which is why the language rides in the path. A base configured with a trailing slash (/abs/de/) arrives as /abs/de//search and is answered with a 307 redirect to the cleaned path, which Audiobookshelf follows.

The language RANKS, it never filters - a German library may still hold an English original, and no match would be the worse answer. The candidates are the works in the named languages followed by the rest, and the author still comes first: works by the given author in the language, then works by the author in any language, then the rest in the language, then everything else. Everything else - the shape, the ISBN shortcut, the attribution line - is exactly /abs/search's.

Reports readiness, not liveness: a server that has not loaded an artifact yet answers 503, so a container health check or load balancer keeps it out of rotation until it can actually answer.

The OpenAPI description of this API. It is static, so unlike every data route it answers even while the server is still fetching its first artifact.

The document is embedded in the binary and therefore constant for its lifetime: it is served with a strong ETag and a one-hour Cache-Control, and a conditional request revalidates instead of downloading it again.

Top-line counts for the loaded artifact, plus the time it was built. Computed once when the artifact loads, so it is free to call.

PRODUCTION ONLY, and registered at all only when the deployment sets METASERVE_WEBHOOK_SECRET. It exists so a freshly published data release is adopted in seconds instead of at the next hourly poll; the poll remains the fallback for a missed delivery.

The body is only a trigger - the server re-queries GitHub and goes through the same checksum-verified atomic swap as a poll, so a forged payload cannot install anything. The request must carry a valid X-Hub-Signature-256 HMAC over the raw body; anything else is rejected before the body is parsed. The response is always empty: 202 means "accepted, refreshing in the background", including for a delivery that is correctly signed but not a matching release event.

Error bodies on this route are plain text, not the JSON error envelope the API uses.